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_pathogenicandclinvar_review_starsrather 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¶
- Install the binding:
pip install altar-clinvar. - 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_pathogenicis true when any term isPathogenicorLikely_pathogenic.clinvar_low_penetranceis true when any term is a low-penetrance pathogenic term. A classification that is only low penetrance, such asPathogenic,_low_penetrancealone, is notclinvar_pathogenic. HFE C282Y sets both.- Risk alleles (
Likely_risk_allele,Uncertain_risk_allele,risk_factor),Conflicting_classifications_of_pathogenicityand 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 needspip install "altar[hf]"(Where it comes from).datasetnames your own Parquet copy, as a path or a URI. It may hold another release or hg19.tablenames your own BigQuery table,project.dataset.table, read through agcpconnection. It is Preview: tested on the BigQuery emulator and DuckDB; not run against live BigQuery.releaseis given withtableonly: the release date the table holds, such as20261005. The default is the published release.genome_build, when given, must behg38orhg19. Withtable, it names the table's build.prioritize_pathogenic = truelets reviewed pathogenic classifications setprioritized. The default isfalse(Prioritization).storage_optionsis not allowed withconnection.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_GRCh37files (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:GTmisses ClinVar's pathogenic BRCA1 recordchr17: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##fileDateequal to--release, a##referenceequal to the build's assembly, and the INFO fields it reads, includingONCandSCI; - checks inputs named like ClinVar's files against
--release; - writes
1aschr1andMTaschrM, and skipsMTon hg19, because ClinVar's GRCh37MTrecords are on the rCRS while UCSC hg19'schrMis another sequence; - trims each allele, and skips and counts records with no ALT, a symbolic ALT or an
Nbase, and records on contigs other than chr1–22, X, Y and M; - counts review statuses and
ORIGINbits 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.--overwritedeletes 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
gcsor from your own copy. - On BigQuery, read a loaded table in the store's own SQL with
altar_clinvar.bigquery_sourcerather 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:
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-clinvaris 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.