Skip to content

ClinVar

The clinvar source adds ClinVar's aggregate germline classification of each variant, with its review status, conditions, genes and molecular consequences. It is a lookup in a released dataset and runs no model.

Kind Annotation source; type = "clinvar"
Install pip install altar-clinvar (PyPI)
Genome builds hg38 (published), hg19
Variant classes SNVs and indels with a ClinVar record, on chr1–22, X, Y and M
Data Published: release 20260928 on hg38, read in place. gcs (default): gs://kundajelab-altar/clinvar/clinvar-20260928-hg38; hf: hf://datasets/altar-genomics/clinvar-20260928-hg38. Copy it with altar pull clinvar --to PATH_OR_URI, or --bigquery PROJECT.DATASET.TABLE. Build your own with altar-clinvar-build
Validation Matches upstream on spot checks (Validation)
Licence No NCBI restrictions; attribute ClinVar
Upstream Data, Paper, Documentation

When to use it

  • Use ClinVar to ask whether submitters have classified a variant as pathogenic or benign, how well reviewed that classification is, and for which conditions.
  • Filter or prioritize on clinvar_pathogenic and clinvar_review_stars rather than on the classification text (Filtering).
  • A variant ClinVar has no record for gets no columns. The absence of a submission is not evidence that a variant is benign.
  • Choose gnomAD to ask how common a variant is. ClinVar holds clinical assertions and no frequencies. Rare-disease filtering often reads both.
  • Choose a prediction, such as AlphaMissense or SpliceAI, for a variant no submitter has classified. ClinVar reports what submitters asserted and predicts nothing.

Add it to a run

[sources.clinvar]
type = "clinvar"
  1. Install the binding: pip install altar-clinvar.
  2. Add the section above to the run spec. It reads the published copy in place, with no download and no credentials.

altar sources clinvar lists the columns, the options and the published copy. The run spec reference describes the [sources.<name>] section, and Annotate variants with evidence walks through a run. Tutorial 0: look up what is known about five variants looks five variants up in ClinVar in a notebook.

Outputs

Column Type Meaning
clinvar_variation_id int The ClinVar Variation ID, from ID. Never null.
clinvar_allele_id int The ClinVar Allele ID, from ALLELEID.
clinvar_classification str The aggregate germline classification, from CLNSIG, such as Pathogenic/Likely_pathogenic. Null when the record has no germline classification.
clinvar_pathogenic bool Whether any term of the classification is Pathogenic or Likely_pathogenic. Never null.
clinvar_low_penetrance bool Whether any term is Pathogenic,_low_penetrance or Likely_pathogenic,_low_penetrance. Never null.
clinvar_review_status str The germline review status, from CLNREVSTAT, such as criteria_provided,_single_submitter.
clinvar_review_stars int ClinVar's gold stars, 0 to 4, for that review status. Null when the status is missing or unknown.
clinvar_conditions list of str ClinVar's preferred condition names, from CLNDN, such as not_provided.
clinvar_conflicting_classifications list of str For a conflicting classification, each submitted classification and its count, from CLNSIGCONF, such as Likely_benign_(2).
clinvar_molecular_consequences list of str Molecular consequence names, from MC, such as missense_variant, without their SO IDs.
clinvar_variant_type str The variant type, from CLNVC, such as single_nucleotide_variant or Deletion.
clinvar_origin int The allele-origin bitmask, from ORIGIN: 1 germline, 2 somatic, 32 de novo, and so on; 0 is unknown.
clinvar_origins list of str The origins the bitmask combines, such as ["germline", "de_novo"] for 33.
clinvar_genes list of struct (symbol, gene_id) The genes ClinVar reports, from GENEINFO, in ClinVar's order: each gene's symbol and its NCBI Gene ID, gene_id.
clinvar_oncogenicity str The aggregate oncogenicity classification, from ONC.
clinvar_oncogenicity_review_status str The review status of clinvar_oncogenicity, from ONCREVSTAT.
clinvar_somatic_impact str The aggregate somatic clinical impact, from SCI.
clinvar_somatic_impact_review_status str The review status of clinvar_somatic_impact, from SCIREVSTAT.

Every column starts with clinvar_.

Text keeps ClinVar's VCF spelling, with underscores for spaces. Percent-escapes are decoded: %3B in a condition name becomes ;. A repeated column is a list and is never null; a field the record lacks is an empty list. The gene and condition columns are display and filter values, not a gene or disease model.

clinvar_genes is a list of records, one per gene. symbol is the gene symbol, such as BRCA1, and gene_id is its NCBI Gene ID, an integer.

A variant ClinVar has no record for gets no ClinVar columns. The absence of a submission is not evidence that a variant is benign.

An augmented VCF written from a run's export carries these columns as ALTAR1_CLINVAR_* INFO fields; see Write an augmented VCF.

Classification terms

CLNSIG joins one variant's germline classifications with / and adds other terms after |. HFE C282Y (Variation ID 9) is Pathogenic/Pathogenic,_low_penetrance|risk_factor. The source splits a value on both separators and compares each term. A comma stays inside its term.

  • clinvar_pathogenic is true when any term is Pathogenic or Likely_pathogenic.
  • clinvar_low_penetrance is true when any term is a low-penetrance pathogenic term. A classification that is only low penetrance, such as Pathogenic,_low_penetrance alone, is not clinvar_pathogenic. HFE C282Y sets both.
  • Risk alleles (Likely_risk_allele, Uncertain_risk_allele, risk_factor), Conflicting_classifications_of_pathogenicity and every other term set neither flag.

Records without a germline classification

clinvar_classification and clinvar_review_status are null, and clinvar_pathogenic is false, for a record with no germline classification. That covers variants classified only for somatic clinical impact or oncogenicity, variants classified only inside a haplotype or genotype, and records with no classification. They are 5 to 9% of the records in samples of the 20260928 release. Such a record still has its Variation ID, genes, consequences and any somatic or oncogenicity classification.

Review stars

clinvar_review_stars follows ClinVar's review status table:

Stars Review status
4 practice_guideline
3 reviewed_by_expert_panel
2 criteria_provided,_multiple_submitters,_no_conflicts
1 criteria_provided,_single_submitter, criteria_provided,_conflicting_classifications
0 no_assertion_criteria_provided, no_classification_provided, no_classification_for_the_single_variant, no_classifications_from_unflagged_records

A status not in the table gets null stars.

Configuration

Option Set in Type Default Meaning
dataset [sources.clinvar.options] path not set your own copy, as a path or URI, such as one altar pull made (default: the published copy)
table [sources.clinvar.options] text not set your own BigQuery table, project.dataset.table, such as one altar pull --bigquery loaded
release [sources.clinvar.options] text not set the release a table holds, given only with table (default: the published release)
genome_build [sources.clinvar.options] text not set the genome build of the data, checked against it when given
prioritize_pathogenic [sources.clinvar.options] true or false false true lets a pathogenic or likely pathogenic germline classification with at least one review star set prioritized
storage_options [sources.clinvar.options] table not set fsspec settings for reading the files, such as credentials
connection [sources.clinvar] not set connection = "<name>": the [connections.<name>] section to read the data through
location [sources.clinvar.options] one of "gcs", "hf" "gcs" where to read the published copy from

Every option is optional. With none, the source reads the published copy from gcs.

  • location = "hf" reads the Hugging Face mirror, which needs pip install "altar[hf]" (Where it comes from).
  • dataset names your own Parquet copy, as a path or a URI. It may hold another release or hg19.
  • table names your own BigQuery table, project.dataset.table, read through a gcp connection. It is Preview: tested on the BigQuery emulator and DuckDB; not run against live BigQuery.
  • release is given with table only: the release date the table holds, such as 20261005. The default is the published release.
  • genome_build, when given, must be hg38 or hg19. With table, it names the table's build.
  • prioritize_pathogenic = true lets reviewed pathogenic classifications set prioritized. The default is false (Prioritization).
  • storage_options is not allowed with connection.
  • connection = "<name>", set in [sources.clinvar] itself, names the [connections.<name>] section to read through.

An unknown option stops the run with an error that lists the valid ones.

Inputs

  • Genome builds: hg38 for the published copy. Build your own copy for hg19 from ClinVar's vcf_GRCh37 files (Build another release). ClinVar builds both from the same records, so the columns mean the same thing on either assembly.
  • Variant classes: the SNVs and indels ClinVar has a record for, on chr1–22, X, Y and M. An hg19 copy has no chrM rows.
  • Allele matching: ClinVar's keys are trimmed and left-aligned. Ingestion with a reference FASTA gives a cohort the same keys. A lookup takes variant IDs as given, so an indel that was only trimmed finds no row: chr17:43045710:GG:GT misses ClinVar's pathogenic BRCA1 record chr17:43045711:G:T. See Variant identity and normalization.

Where it comes from

The Kundaje lab builds ClinVar release 20260928 from ClinVar's GRCh38 VCF and its _papu file with altar-clinvar-build. It publishes the output in a public-read bucket, with a byte-for-byte mirror on Hugging Face (dataset card). The card above lists both locations. It holds 4,555,530 alleles in 26 files, 106 MB. altar-clinvar depends on altar[gcs], so the default location needs no other install.

ClinVar publishes a new VCF every week, so the published copy is soon not the newest. Each version of altar-clinvar pins one published release, and only on hg38. For a newer release, or for hg19, build it yourself and name it with dataset.

location = "hf" reads the mirror, which needs pip install "altar[hf]". Hugging Face limits anonymous requests, so a large cohort read from hf can stall; see Hugging Face rate limits.

To keep your own copy:

altar pull clinvar --to gs://my-bucket/clinvar-20260928-hg38
altar pull clinvar --bigquery my-project.reference.clinvar_20260928_hg38 --project my-project

The first copies the Parquet files and checks that every file records the release. The second loads them into a BigQuery table clustered on variant_id, with the repeated columns as arrays, and labels the table with its release. altar pull --bigquery is Preview: tested against a fake BigQuery client only; not run against live BigQuery. Name the copy with dataset or table. Choose where data is read from covers the published copy, your own copy, BigQuery tables, altar pull and connections for every source.

Release and identity

A ClinVar release is named by the YYYYMMDD date in ClinVar's file names: clinvar_20260928.vcf.gz is 20260928, for weekly and monthly files alike. The genome build is hg38 for ClinVar's vcf_GRCh38 files or hg19 for its vcf_GRCh37 files.

Releases before 20240127 are rejected. Until then CLNSIG mixed germline and somatic submissions, and the oncogenicity and somatic clinical impact classifications had no fields of their own.

The source's identity is the contract org.kundajelab.altar.annotation.clinvar (version 1.0.0), the release date and the genome build. Each release is a different identity, so cached rows of different releases never mix. Where the data is read from is not part of it, and neither is prioritize_pathogenic. The published copy, a pulled copy and a BigQuery table of one release declare the same identity.

Build another release

altar-clinvar-build streams ClinVar's VCF into Parquet, one row per allele, keyed by the canonical chr:pos:ref:alt:

altar-clinvar-build --release 20261005 --genome-build hg38 \
  --input clinvar_20261005.vcf.gz clinvar_20261005_papu.vcf.gz \
  --output ./clinvar-20261005-hg38

The _papu file adds the variants ClinVar places on the chrY pseudoautosomal regions. --input and --output also take URIs. This builds from NCBI into your bucket, with no download step:

altar-clinvar-build --release 20261005 --genome-build hg38 \
  --input https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar_20261005.vcf.gz \
  --output gs://my-bucket/clinvar-20261005-hg38/

A URI needs its provider's Altar extra, such as altar[http] for https://. For hg19, give --genome-build hg19 and the vcf_GRCh37 file. --input - reads one VCF from standard input, and --stdin-name names it.

The builder:

  • writes <output>/chr=<chromosome>/<input name>.parquet, with the release date, genome build and builder version in each file's metadata;
  • checks each header: ##source=ClinVar, a ##fileDate equal to --release, a ##reference equal to the build's assembly, and the INFO fields it reads, including ONC and SCI;
  • checks inputs named like ClinVar's files against --release;
  • writes 1 as chr1 and MT as chrM, and skips MT on hg19, because ClinVar's GRCh37 MT records are on the rCRS while UCSC hg19's chrM is another sequence;
  • trims each allele, and skips and counts records with no ALT, a symbolic ALT or an N base, and records on contigs other than chr1–22, X, Y and M;
  • counts review statuses and ORIGIN bits it does not know, and keeps those rows;
  • rejects input that is not sorted by position, a variant key that occurs twice across all inputs, and a build that writes no rows;
  • rejects a bgzipped input that does not end with bgzip's end-of-file block;
  • writes only into an empty or absent --output. --overwrite deletes a previous build there first.

A URI output is resumable: running the same command again after a crash skips the inputs already written. --input-attempts, --input-storage-option and --output-storage-option work as for gnomAD's builder. The builder prints how many records it skipped for each reason.

Compute and scale

  • A lookup runs no model and needs no GPU.
  • The published copy is 4,555,530 alleles in 26 files, 106 MB. A lookup reads only the partitions and row groups its variants fall in.
  • Hugging Face limits anonymous requests, so read a large cohort from gcs or from your own copy.
  • On BigQuery, read a loaded table in the store's own SQL with altar_clinvar.bigquery_source rather than staging Python lookups (Python and extension).

Prioritization

Off by default. ClinVar is curated evidence, not a model prediction, and is often used as a filter or a display column. To let reviewed pathogenic classifications set prioritized:

[sources.clinvar]
type = "clinvar"
options = { prioritize_pathogenic = true }

The rule is PATHOGENIC_PREDICATE: And(Eq(Col("clinvar_pathogenic"), Lit(True)), Ge(Col("clinvar_review_stars"), Lit(1))). It selects a pathogenic or likely pathogenic germline classification with at least one review star. Zero stars means no submitter gave assertion criteria. The rule does not select a classification that is only low penetrance. In code, combine clinvar_low_penetrance with it to include those:

from altar.predicates import And, Col, Eq, Ge, Lit, Or
from altar_clinvar import PATHOGENIC_PREDICATE

reviewed_low_penetrance = And(Eq(Col("clinvar_low_penetrance"), Lit(True)), Ge(Col("clinvar_review_stars"), Lit(1)))
pathogenic_or_low_penetrance = Or(PATHOGENIC_PREDICATE, reviewed_low_penetrance)

What prioritized means explains how rules combine.

Filtering

Filter on the flags rather than on clinvar_classification text. The flags also catch combined values such as Likely_pathogenic,_low_penetrance/Likely_risk_allele. Ge(Col("clinvar_review_stars"), Lit(2)) asks for a higher review bar. A variant with no ClinVar record has no ClinVar values, so a rule on these columns does not match it unless it tests IsNull.

Validation

Validation label: Matches upstream on spot checks. When the published copy was built, the alleles written plus the records skipped were checked against ClinVar's 4,557,594 upstream records. APOE rs429358 and rs7412, CFTR F508del, BRCA1 185delAG and m.3243A>G were looked up in the published copy and in ClinVar, and agreed.

Not validated:

  • a release or genome build you build yourself, such as a newer weekly release or hg19;
  • reading a BigQuery table (table) or loading one (altar pull --bigquery) on live BigQuery, both Preview.

Limits

  • An indel that was only trimmed, not left-aligned, finds no row (Inputs).
  • An hg19 build has no mitochondrial rows.
  • Records on patches, alternate loci and unplaced contigs are skipped.
  • The published copy is one weekly release on hg38. A newer release or hg19 needs a build of your own.
  • ClinVar's information is not intended for direct diagnostic use or medical decision-making without review by a genetics professional. The source reports ClinVar's classifications and makes none of its own.

Cite and licence

Cite ClinVar's paper (PMID 29165669), and name the release you used, such as "ClinVar 20260928":

@article{landrum2018clinvar,
  author = {Landrum, Melissa J. and Lee, Jennifer M. and Benson, Mark and Brown, Garth R. and Chao, Chen and
    Chitipiralla, Shanmuga and Gu, Baoshan and Hart, Jennifer and Hoffman, Douglas and Jang, Wonhee and
    Karapetyan, Karen and Katz, Kenneth and Liu, Chunlei and Maddipatla, Zenith and Malheiro, Adriana and
    McDaniel, Kurt and Ovetsky, Michael and Riley, George and Zhou, George and Holmes, J. Bradley and
    Kattman, Brandi L. and Maglott, Donna R.},
  title = {{ClinVar}: improving access to variant interpretations and supporting evidence},
  journal = {Nucleic Acids Research},
  volume = {46},
  number = {D1},
  pages = {D1062--D1067},
  year = {2018},
  doi = {10.1093/nar/gkx1153}
}
  • Data: NCBI places no restrictions on the use or distribution of ClinVar data, though some submitters may claim rights in the data they submitted. See NCBI's policies. ClinVar asks for attribution as a data source in publications and websites (data use policy).
  • Binding: altar-clinvar is MIT-licensed. It ships no ClinVar data and is not affiliated with or endorsed by NCBI or ClinVar.

Python and extension

ClinVarSource.from_options() builds the same source as a run spec, with the same options as keywords. Look up evidence shows a lookup in several sources at once. ClinVarSource.published_dataset() returns the published locations and identity.

On BigQuery, read a loaded table in the store's own SQL with altar_clinvar.bigquery_source, which takes the same prioritize_pathogenic flag. Run at warehouse scale on BigQuery covers it, and what each read path checks.