> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/annotation/data-sources/clinvar.md). # ClinVar ### Overview {% hint style="warning" %} **Deprecated** ClinVar has changed to a [new XML format](https://github.com/ncbi/clinvar/blob/master/ClassificationOnClinVar.md) Use [CliVarPreview](https://github.com/illumina-swi/annotations-docs/tree/prod-landing-page/docs/data-sources/clinvar-preview/README.md) for latest ClinVar entries. {% endhint %} ClinVar is a freely accessible, public archive of reports of the relationships among human variations and phenotypes, with supporting evidence. ClinVar thus facilitates access to and communication about the relationships asserted between human variation and observed health status, and the history of that interpretation. {% hint style="info" %} **Publication** Melissa J Landrum, Jennifer M Lee, Mark Benson, Garth R Brown, Chen Chao, Shanmuga Chitipiralla, Baoshan Gu, Jennifer Hart, Douglas Hoffman, Wonhee Jang, Karen Karapetyan, Kenneth Katz, Chunlei Liu, Zenith Maddipatla, Adriana Malheiro, Kurt McDaniel, Michael Ovetsky, George Riley, George Zhou, J Bradley Holmes, Brandi L Kattman, Donna R Maglott, ClinVar: improving access to variant interpretations and supporting evidence, *Nucleic Acids Research*, **46**, Issue D1, 4 January 2018, Pages D1062–D1067, {% endhint %} ### RCV File #### Example Here's a full RCV entry: {% file src="/files/0al5x1nTUDPiNL4lK4iX" %} #### Parsing In the following section, we discuss which field of the XML was used to extract information that is presented in the JSON output. **ID** ```xml ``` The Acc and Version fields are merged to form the ID (RCV000000001.2) **LastUpdatedDate** ```xml ``` **Significance** ```xml no assertion criteria provided Pathogenic ``` **ReviewStatus** ```xml no assertion criteria provided Pathogenic ``` **Phenotypes** ```xml Joubert syndrome 9 ``` We only use the field with Type="Preferred". Multiple phenotypes may be reported **Location, Variant Type and Variant Id** ```xml ``` * The variant position is extracted from the fields for their respective assemblies. * Updated records contain positionVCF, referenceAlleleVCF and alternateAlleleVCF fields and when present, we use them to create the variant. * For older records, since "start' and "stop" fields are not always available, we use the "display\_start" and "display\_end" fields. * If a required allele is not available, we extract it from the reference sequence. * Only variants having a dbSNP id are extracted. * Note that a ClinVar accession may have multiple variants associated with it (possible in different locations) * VariantId is extracted from the MeasureSet attributes. * VariantType is extracted from the Measure attributes. {% hint style="warning" %} **unsupported variant types** We currently don't support the following variant types: * Microsatellite * protein only * fusion * Complex * Variation * Translocation {% endhint %} **MedGen, OMIM, Orphanet IDs** ```xml ``` **AlleleOrigins** ```xml germline ``` We only extract all Allele Origins from Submissions (SCV) entries. **PubMedIds** ```xml 12114475 LMM Criteria 24033266 9113933 23757202 ``` We only extract all Pubmed Ids from Submissions (SCV) entries. **Parsing Significance** Extracting significance(s) may involve parsing multiple fields. Take the following snippets into consideration. ```xml no assertion criteria provided Pathogenic criteria provided, multiple submitters, no conflicts Pathogenic/Likely pathogenic no assertion criteria provided Conflicting interpretations of pathogenicity Pathogenic(1);Uncertain significance(1) ``` Given the evidence, we converted the significance field into an array of strings which may be parsed out of the `Descriptions` or `Explanation` fields. {% hint style="warning" %} **Varying Delimiters** The delimiters in each field may vary. Currently, the delimiters for `Description` are `,` and `/`. The delimiters for `Explanation` are `;` and `/`. {% endhint %} ### VCV File #### Example ```xml current Homo sapiens 1p36.31 601142 1p36.31 607215 GRCh37/hg19 1p36.31(chr1:6051187-6158763) copy number gain 1p36.31 no interpretation for the single variant no interpretation for the single variant no interpretation for the single variant ``` #### Parsing In the following section, we discuss which field of the XML was used to extract information that is presented in the JSON output. **id** ```xml ``` The Acc and Version fields are merged to form the ID (RCV000000001.2) **significance** ```xml no interpretation for the single variant ``` May have multiple significances listed. **reviewStatus** ```xml no interpretation for the single variant ``` ### Known Issues {% hint style="warning" %} **Known Issues** * The XML file contains \~1k more entries (out of 162K) than the VCF file * The XML file does not have a field indicating that a record is associated with the reference base - something that was present in VCF * The XML file contains entries (e.g. RCV000016645 version=1) which have IUPAC ambiguous bases ("R", "Y", "H", etc.) as their alternate allele {% endhint %} ### Download URLs ### JSON Output **small variants:** ```json "clinvar":[ { "id":"VCV000036581.3", "reviewStatus":"reviewed by expert panel", "significance":[ "benign" ], "refAllele":"G", "altAllele":"A", "lastUpdatedDate":"2020-03-01", "isAlleleSpecific":true }, { "id":"RCV000030258.4", "variationId":"VCV000036581.3", "reviewStatus":"reviewed by expert panel", "alleleOrigins":[ "germline" ], "refAllele":"G", "altAllele":"A", "phenotypes":[ "Lynch syndrome" ], "medGenIds":[ "C1333990" ], "omimIds":[ "120435" ], "significance":[ "benign" ], "lastUpdatedDate":"2017-05-01", "isAlleleSpecific":true } ] ``` **large variants:** ```json "clinvar":[ { "chromosome":"1", "begin":629025, "end":8537745, "variantType":"copy_number_loss", "id":"RCV000051993.4", "variationId":"VCV000058242.1", "reviewStatus":"criteria provided, single submitter", "alleleOrigins":[ "not provided" ], "phenotypes":[ "See cases" ], "significance":[ "pathogenic" ], "lastUpdatedDate":"2022-04-21", "pubMedIds":[ "21844811" ] }, { "id":"VCV000058242.1", "reviewStatus":"criteria provided, single submitter", "significance":[ "pathogenic" ], "lastUpdatedDate":"2022-04-21" }, ...... ] ``` | Field | Type | Notes | | ---------------- | :----------: | ----------------------------------------------------------------------------------- | | id | string | ClinVar ID | | variationId | string | ClinVar VCV ID | | variantType | string | variant type | | reviewStatus | string | see possible values below | | alleleOrigins | string array | see possible values below | | refAllele | string | | | altAllele | string | | | phenotypes | string array | | | medGenIds | string array | MedGen IDs | | omimIds | string array | OMIM IDs | | orphanetIds | string array | Orphanet IDs | | significance | string array | see possible values below | | lastUpdatedDate | string | yyyy-MM-dd | | pubMedIds | string array | PubMed IDs | | isAlleleSpecific | bool | true when the current variant alternate allele matches the ClinVar alternate allele | **reviewStatus:** * no assertion provided * no assertion criteria provided * criteria provided, single submitter * practice guideline * classified by multiple submitters * criteria provided, conflicting interpretations * criteria provided, multiple submitters, no conflicts * no interpretation for the single variant **alleleOrigins:** * unknown * other * germline * somatic * inherited * paternal * maternal * de-novo * biparental * uniparental * not-tested * tested-inconclusive **significance:** * uncertain significance * not provided * benign * likely benign * likely pathogenic * pathogenic * drug response * histocompatibility * association * risk factor * protective * affects * conflicting data from submitters * other * no interpretation for the single variant * conflicting interpretations of pathogenicity ### Building the supplementary files There are 2 ways of building your own OMIM supplementary files using `SAUtils`. The first way is to use `SAUtils` command's subcommands `clinvar`. The ClinVar `.nsa` and `.nsi` for Illumina Connected Annotations can be built using the `SAUtils` command's `clinvar` subcommand. The second way is to use `SAUtils` command's subcommands `AutoDownloadGenerate`. To use `AutoDownloadGenerate`, read more in `SAUtils` section. #### Using `clinvar` subcommands and source data files Two input `.xml` files and a `.version` file are required in order to build the `.nsa` and `.nsi` file. You should have the following files: ```scss ClinVarFullRelease_00-latest.xml.gz ClinVarVariationRelease_00-latest.xml.gz ClinVarFullRelease_00-latest.xml.gz.version ``` The version file is a json file with the following format. ```scss { "name": "ClinVar", "version": "20231230", "description": "A freely accessible, public archive of reports of the relationships among human variations and phenotypes, with supporting evidence", "releaseDate": "2024-01-10" } ``` You have to adjust the version and release date according to the actual date of the ClinVar. The help menu for the utility is as follows: ```scss dotnet SAUtils.dll clinvar --------------------------------------------------------------------------- SAUtils (c) 2022 Illumina, Inc. Stromberg, Roy, Platzer, Siddiqui, Ouyang, et al 3.18.1 --------------------------------------------------------------------------- USAGE: dotnet SAUtils.dll clinvar [options] Creates a supplementary database with ClinVar annotations OPTIONS: --ref, -r compressed reference sequence file --rcv, -i ClinVar Full release XML file --vcv, -c ClinVar Variation release XML file --out, -o output directory --help, -h displays the help menu --version, -v displays the version dotnet SAUtils.dll clinvar ``` Here is a sample execution: ```scss dotnet SAUtils.dll clinvar \\ --ref ~/development/References/7/Homo_sapiens.GRCh38.Nirvana.dat --rcv ClinVarFullRelease_00-latest.xml.gz \\ --vcv ClinVarVariationRelease_00-latest.xml.gz --out ~/development/SupplementaryDatabase/63/GRCh38 --------------------------------------------------------------------------- SAUtils (c) 2022 Illumina, Inc. Stromberg, Roy, Platzer, Siddiqui, Ouyang, et al 3.18.1 --------------------------------------------------------------------------- Found 1535677 VCV records Unknown vcv id:225946 found in RCV000211201.2 Unknown vcv id:225946 found in RCV000211253.2 Unknown vcv id:225946 found in RCV000211375.2 Unknown vcv id:976117 found in RCV001253316.1 Unknown vcv id:1321016 found in RCV001776995.2 3 unknown VCVs found in RCVs. 225946,976117,1321016 0 unknown VCVs found in RCVs. Chromosome 1 completed in 00:00:15.1 Chromosome 2 completed in 00:00:20.0 Chromosome 3 completed in 00:00:09.7 Chromosome 4 completed in 00:00:05.9 Chromosome 5 completed in 00:00:09.8 Chromosome 6 completed in 00:00:08.3 Chromosome 7 completed in 00:00:08.7 Chromosome 8 completed in 00:00:06.2 Chromosome 9 completed in 00:00:08.6 Chromosome 10 completed in 00:00:07.0 Chromosome 11 completed in 00:00:11.7 Chromosome 12 completed in 00:00:08.0 Chromosome 13 completed in 00:00:06.3 Chromosome 14 completed in 00:00:06.0 Chromosome 15 completed in 00:00:06.6 Chromosome 16 completed in 00:00:10.8 Chromosome 17 completed in 00:00:13.8 Chromosome 18 completed in 00:00:02.9 Chromosome 19 completed in 00:00:08.7 Chromosome 20 completed in 00:00:03.6 Chromosome 21 completed in 00:00:02.4 Chromosome 22 completed in 00:00:03.6 Chromosome MT completed in 00:00:00.2 Chromosome X completed in 00:00:07.5 Chromosome Y completed in 00:00:00.0 Maximum bp shifted for any variant:2 Writing 37097 intervals to database... Time: 00:13:26.9 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.connected.illumina.com/annotation/data-sources/clinvar.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.