Skip to content

How to Read These Docs

These docs serve three kinds of reader. Some want to understand the data, often starting from what they already know of ClinVar's website. Some want to know how ClinVar's XML becomes this format. Some are building a pipeline or an application on top of it. Find yours below, follow its path as far as you need, and use the tab map to jump around.

The sections at a glance

The site has six tabs, one per reader goal:

Tab What it gives you Read it when
Home What ClinVar-GKM is and its key concepts, plus this guide, Data Use and Citation (the ClinVar disclaimer, how to cite, the license) and Stay Informed (the announcement list) You are new to the project, or about to use, publish or share the data
Get the Data The files: monthly and weekly full bundles, weekly deltas, Parquet, and how releases work You need the data, or need to keep a copy current
Understand the Data What each part of the bundle means: variations, SCV, VCV and RCV statements, ID references and annotated examples. Also the Data Model, every class and field generated from the schemas, and Mapping & Vocabularies, which maps ClinVar's statement types, classifications and review status You want to understand the data, or need exact field definitions
Use the Data Query the Data (the 22 Parquet tables, a browser query console, joins, recipes and working at scale), Working in Python (the GA4GH libraries on bundles and Parquet) and two end-to-end User Stories You want to work with the data in SQL or Python, or see it used for a real task
How It's Built Each step from ClinVar's XML to the published bundle You want to know how a value was produced
Reference Versioning, Changelog, Release Validation, Known Issues, FAQ, Glossary and more You need what changed, what is guaranteed, or a definition

The tabs build on each other:

  • Get the Data delivers the files.
  • Understand the Data explains what is in them and defines every field exactly.
  • Use the Data offers the same content as tables you can query.
  • How It's Built explains how each value was derived from ClinVar.
  • Reference records what changes between releases and what each release guarantees.

Path 1: I know ClinVar's website and want to understand the data

Everything on a ClinVar variation page has a place in the bundle. This table maps the pieces of the page you know to where they live, and to the page that explains each one.

On ClinVar's website In ClinVar-GKM Explained in
A variation (VCV000012582) and its details: HGVS names, location, genes A variation record (clinvar:12582), a Cat-VRS categorical variant, defined by GA4GH VRS allele and location records Variations
The Germline classification and its review status A vcv statement in the germline group, with its aggregate classification VCV Statements
The Somatic clinical impact and oncogenicity classifications vcv statements in the somatic clinical impact and oncogenicity groups VCV Statements, Statement Types
Each row of Submitted classifications (an SCV) An scv statement, which points to its submitter, its proposition and its evidence SCV Statements
A classification for one condition (an RCV) An rcv statement RCV Statements
The condition (a MedGen-linked trait) A condition, or a conditionSet when there are several Output Format
Review status stars The statement's review status, which also sets its rank when submissions are aggregated Review Status
"Pathogenic", "Drug response", and the other classification terms A classification on a typed proposition (for example VariantPathogenicityProposition) Classifications, Propositions

Suggested order: 1. The Key Concepts on Home. 2. Output Format, for how the bundle's sections fit together. 3. The statement pages, starting with SCV Statements. 4. The annotated Examples, to see one real variation end to end.

Keep the Glossary and the FAQ at hand. To explore without writing code, the query console runs SQL in your browser.

Path 2: I want to know how ClinVar's XML becomes this format

The Pipeline Overview walks the whole release. ClinVar's XML is first loaded into relational BigQuery tables by the upstream clinvar-ingest pipeline and prepared by clinvar-ingest-bq-tools. ClinVar-GKM's stored procedures take over from there.

Suggested order: 1. Variation Identity and VRS Processing: how each variant gets its GA4GH VRS identity. 2. Cat-VRS: how a ClinVar variation becomes a categorical variant. 3. Conditions & Traits: how submitted conditions are matched to ClinVar's traits. 4. SCV Statements, then VCV Statements with their aggregation rules, then RCV Statements. 5. Export & Distribute: bundle assembly, weekly deltas, Parquet and publication.

When a value in the data surprises you, the matching pipeline step says where it came from. Mapping & Vocabularies records the mapping rules. Release Validation lists the checks every release passes before publication. Design decisions are recorded as ADRs, for example ADR 0007 on pipeline principles.

Path 3: I am building a pipeline or an application on this data

Suggested order: 1. How Releases Work: monthly and weekly full bundles, weekly deltas, and how to keep a copy current. Then Weekly Deltas for applying a delta to a full bundle. 2. Versioning & Releases: what is guaranteed. 1.1.0 is the general-availability release; published files are immutable, and a breaking change opens a new major line. 3. Pick an interface: - JSON bundles: the Output Format, ID References for resolving #/section/id pointers, and the Data Model for exact fields and schemas. - Parquet: Query the Data, from the 22 tables and joins to working at scale and other tools. 4. The GA4GH libraries: vrs-python, cat-vrs-python and va-spec-python, collected in the GKM Starter Kit, read these records directly. Working in Python loads bundle and Parquet records into their models, with the library versions that read 1.1.0, and validates a bundle with the GKM Toolkit against the ClinVar-GKM schemas. See also GA4GH Standards. 5. Worked problems: the User Stories, and Sub-Bundle Extraction for cutting a self-contained subset.

Before you depend on a release, check the Changelog for migration notes and Known Issues. The Release Validation page lists the checks behind each release.

Getting help and news