Glossary¶
Key terms, acronyms, and concepts used throughout the ClinVar-GKS documentation.
Standards and Organizations¶
GA4GH (Global Alliance for Genomics and Health) : International consortium developing standards for genomic data representation and exchange.
GKS (Genomic Knowledge Standards) : Collective term for GA4GH standards — VRS, Cat-VRS, and VA-Spec — for representing genomic variants and variant assertions.
VRS (Variation Representation Specification) : GA4GH standard for normalized, computable variant identifiers. Defines how variants are represented with sequence references, locations, and states.
Cat-VRS (Categorical Variation Representation Specification) : GA4GH standard for categorical variant representations that group variants at a higher level — CanonicalAlleles, CategoricalCnvChange, CategoricalCnvCount.
VA-Spec (Variant Annotation Specification) : GA4GH standard for variant annotation statements. Defines the Statement, Proposition, and EvidenceLine structures used by SCV and VCV outputs.
ACMG (American College of Medical Genetics and Genomics) : Organization that publishes pathogenicity classification guidelines (2015, v4) used by ClinVar submitters.
AMP/ASCO/CAP : Association for Molecular Pathology / American Society of Clinical Oncology / College of American Pathologists. Published somatic clinical impact tiering guidelines (Tier I-IV).
ClinVar Concepts¶
ClinVar : NCBI database of variant submissions and aggregate classifications from clinical, research, and community sources.
SCV (Submitted Clinical Variant) : Individual submission from a laboratory, research group, or other organization reporting their interpretation of a variant. Each SCV contains one classification for one variant and condition combination.
VCV (Variant-level Clinical Variant) : Aggregate classification combining all SCV submissions for the same variant across all conditions. Represents the variant-level summary.
RCV (Review-level Clinical Variant) : Aggregate classification combining all SCV submissions for the same variant AND the same condition. Used internally by ClinVar for aggregation.
Trait (ClinVar terminology) : A disease, phenotype, or finding associated with a variant submission. In GKS output, this is termed "Condition."
TraitSet : A group of traits with a membership operator. In GKS output, this is termed "ConditionSet."
Review Status : Star levels (0-4) indicating submission confidence. Determines how submissions are ranked during aggregation. See Review Status.
Submission Levels¶
Submission Level : Classification of SCV authority and review rigor. Determines aggregation logic and review status derivation.
PG (Practice Guideline) : Submission level rank 4 (4 stars). Published practice guidelines from authoritative bodies.
EP (Expert Panel) : Submission level rank 3 (3 stars). Classifications reviewed and approved by expert panels.
CP (Criteria Provided) : Submission level rank 1 (1 star). Submitter provided documented criteria for their classification.
NOCP (No Assertion Criteria Provided) : Submission level rank 0 (0 stars). Classification submitted without documented criteria.
NOCL (No Classification Provided) : Submission level rank -1 (0 stars). Submission present but no classification was given.
FLAG (Flagged Submission) : Submission level rank -3 (0 stars). Submission flagged by ClinVar for quality concerns.
Data Model¶
Statement (VA-Spec) : A complete assertion containing classification, proposition, evidence, contributions, and metadata. Both SCV and VCV records are Statements.
Proposition (VA-Spec) : The core claim being asserted. Contains a subject (variant), predicate (relationship), object (condition/therapy), and optional qualifiers.
EvidenceLine (VA-Spec)
: Links a proposition to evidence items with direction and strength assessments. Evidence lines are stored in the evidenceLine bundle section and referenced from all statement levels via hasEvidenceLines arrays of #/evidenceLine/ JSON pointer strings.
CategoricalVariant (Cat-VRS) : Higher-level grouping that associates a ClinVar variation with its resolved VRS representation. Types: CanonicalAllele, CategoricalCnvChange, CategoricalCnvCount.
MappableConcept
: A single concept with conceptType, name, and optional extension array. Used for single-label classifications and single-condition objectCondition values.
ConceptSet
: A structured group of concepts with concepts array, conceptSetType, and membershipOperator. Used for multi-condition objectCondition values (OR operator for VCV with multiple distinct conditions; AND operator for RCV conditionSets).
Constraint (Cat-VRS) : Defining relationship between a categorical variant and its VRS representation. Types: DefiningAlleleConstraint, DefiningLocationConstraint, CopyChangeConstraint, CopyCountConstraint.
Extension : Name/value pair carrying metadata not part of core GA4GH specifications but essential for interpreting the data. Present on statements, classifications, propositions, conditions, and categorical variants.
Proposition Types¶
VariantPathogenicityProposition
: Proposition type for germline pathogenicity assertions. Predicate: isCausalFor. Statement type G.01.
VariantOncogenicityProposition
: Proposition type for oncogenicity assertions. Predicate: isOncogenicFor. Statement type O.10.
VariantClinicalSignificanceProposition
: Proposition type for somatic clinical significance (AMP/ASCO/CAP tiering). Predicate: isClinicallySignificantFor. Statement type S.11.
VariantTherapeuticResponseProposition
: Proposition type for therapeutic response assertions. Predicate: predictsSensitivityTo. Statement type S.12.
VariantDiagnosticProposition : Proposition type for diagnostic assertions. Statement type S.13.
VariantPrognosticProposition : Proposition type for prognostic assertions. Statement type S.14.
ClinVar*Proposition : Custom proposition types for non-standard ClinVar statement types (G.02-G.09): Drug Response, Risk Factor, Protective, Affects, Association, Confers Sensitivity, Other, Not Provided.
Classification Terms¶
Confidence
: Statement-level attribute indicating the submission level. A Concept struct with conceptType: "Confidence" and name set to the submission level label (e.g., "criteria provided", "expert panel"). Present on both SCV and aggregate (VCV/RCV) statements.
Direction
: Whether evidence supports or disputes a proposition. Values: supports, disputes, neutral. On aggregate statements, derived from the classification label (multi-SCV) or passed through from the contributing SCV (single-SCV).
Strength
: Evidence strength level. Values: definitive, likely, strong, potential. Omitted (null) when not applicable. On aggregate statements, derived from the classification label (multi-SCV) or passed through from the contributing SCV (single-SCV).
Tier I / Tier II / Tier III / Tier IV : Somatic clinical impact classification levels. Tier I (Strong) and Tier II (Potential) require paired sub-statements. Tier III (Unknown) and Tier IV (Benign/Likely benign) do not.
Concordant : All contributing SCVs for a variant share the same classification. Produces a single aggregate label.
Conflicting
: Contributing SCVs have different classifications. Produces a "Conflicting classifications of..." label with a conflictingExplanation extension.
Qualifier Types¶
Gene Context Qualifier : Proposition qualifier restricting an assertion to a specific gene. Contains NCBI Gene identifier and HGNC mappings.
Mode of Inheritance Qualifier : Proposition qualifier specifying inheritance pattern (e.g., autosomal dominant, X-linked). Maps to HPO terms.
Penetrance Qualifier
: Proposition qualifier indicating penetrance level for pathogenic or risk allele classifications. Values: low, risk.
VCV Aggregation¶
Aggregation : Process of combining multiple SCV submissions into higher-order VCV statements following submission-level-specific logic.
Winner-Takes-All : Aggregation strategy at the Aggregate Contribution Layer where the highest-ranked submission level's classification becomes the aggregate result. Lower-ranked levels become non-contributing.
Contributing Submission : Submission whose review status is highest-ranked within an aggregation group. Directly reflected in the aggregate classification.
Non-Contributing Submission : Submission ranked lower than the contributing submission. Preserved in the evidence structure but not reflected in the aggregate label.
Grouping Layer : First conceptual aggregation layer. Consists of Classification Grouping and Priority Grouping steps. Produces initial aggregation of SCVs into groups by submission level.
Classification Grouping (Grouping Layer) : First step of the Grouping Layer. Groups SCVs by variation + statement group + proposition type + submission level [+ tier]. Applies submission-level-specific classification and conflict detection logic.
Priority Grouping (Grouping Layer) : Second step of the Grouping Layer (somatic sci only). Aggregates tier-level groups within each submission level.
Aggregate Contribution Layer : Second and final aggregation layer. Applies winner-takes-all ranking across submission levels. Terminal layer for both germline and somatic statements.
Aggregate Review Status : Final review status of a VCV statement derived from submission level and aggregation outcome. See Aggregate Review Status.
Classification Attributes (VCV/RCV)¶
classification
: VCV/RCV statement-level classification attribute. Contains a single aggregate label with optional conflictingExplanation extension. The classification lives only on the statement, not on the proposition.
objectCondition
: VCV/RCV proposition attribute. Contains the unique condition(s) associated with the aggregate statement. For VCV, this is a single MappableConcept or an OR ConceptSet of distinct conditions from contributing SCVs. For RCV, this is the condition sourced from gks_scv_condition_sets — either a Condition MappableConcept or a ConditionSet ConceptSet. Extensions excluded.
Identifier Formats¶
clinvar:{variation_id}
: ClinVar variation identifier. References a CategoricalVariant record in the variation bundle section. Example: clinvar:12582.
clinvar.submission:SCV{id}.{version}
: SCV submission identifier with version. References an SCV Statement record in the scv bundle section. Example: clinvar.submission:SCV001571657.2.
clinvar.submitter:{submitter_id}
: Submitter organization identifier. References a submitter record in the submitter bundle section. Example: clinvar.submitter:508027.
clinvar.trait:{trait_id}
: Condition/trait identifier. References a condition record in the condition bundle section. Example: clinvar.trait:9580.
clinvar.traitset:{trait_set_id}
: Condition set identifier. References a condition set in the conditionSet bundle section. Example: clinvar.traitset:1234.
ga4gh:{type}.{digest}
: VRS identity digest. References alleles or locations in the corresponding bundle sections. Example: ga4gh:VA.xXBYkzzu1AH0oyMKlbBtP2.
Output Format¶
Bundle
: A JSON file containing all data for a ClinVar release, organized as named sections at the root level. Each section is a keyed collection of objects of the same class, where the key is the object's unique identifier. Objects reference each other using #/ JSON pointer strings. Typed Parquet files (one per bundle section) are also produced during assembly for analytical workloads.
Bundle Section
: A named top-level key in the bundle file (e.g., variation, scv, proposition) containing a keyed collection of objects.
JSON Pointer Reference
: A #/{section}/{key} string used to reference an object in another bundle section. Example: #/allele/ga4gh:VA.abc123 resolves to the allele with that key in the allele section.
Technical Terms¶
Null Stripping
: Technique where null-valued fields and empty arrays are omitted from JSON output via JSON_STRIP_NULLS(remove_empty => TRUE).
By-Reference Format : JSON structure where related objects are referenced by ID rather than embedded inline. Reduces duplication when many statements reference the same variant.
Inline Format : JSON structure where related objects are fully embedded within the parent. Self-contained — each record has all data needed for interpretation.
JSON Pointer
: Standard format (RFC 6901) for referencing nested JSON values. Used in somatic target propositions (e.g., 4/proposition/subjectVariant).
BigQuery : Google Cloud Platform data warehouse used for all ClinVar-GKS SQL procedures and table storage.
Stored Procedure
: BigQuery SQL routine executing a specific pipeline step (e.g., gks_catvar_proc, gks_vcv_proc).
External Databases¶
MedGen : Medical Genetics database providing standardized condition identifiers. Primary coding system for conditions.
OMIM (Online Mendelian Inheritance in Man) : Comprehensive database of genetic disorders. Used for condition cross-references.
MONDO (Monarch Disease Ontology) : Unified disease ontology providing standardized condition identifiers.
HPO (Human Phenotype Ontology) : Standardized phenotype terms used for conditions and mode of inheritance.
Orphanet : Database of rare diseases. Used for condition cross-references.
HGNC (HUGO Gene Nomenclature Committee) : Official gene nomenclature database. Gene symbols and identifiers appear in gene context qualifiers.
dbSNP : NCBI SNP database. External cross-reference source for variants.
identifiers.org : Standardized URL namespace for biomedical identifiers used in mapping IRIs.