Issue 434: Add VCV IDs to evidence strings

README.md

@@ -170,3 +170,9 @@ for record in ClinVarDataset('/path/to/clinvar.xml.gz'):
     # e.g. RCV001842692: 3_38633214_G_C => Cardiac arrhythmia
     print(s)
 ```
+
+## Citation
+
+If you find CMAT useful, you can cite the following:
+
+> Shen et al., CMAT: ClinVar Mapping and Annotation Toolkit. _Bioinformatics Advances_, 2024. [doi:10.1093/bioadv/vbae018](https://doi.org/10.1093/bioadv/vbae018)

cmat/clinvar_xml_io/clinvar_measure.py

@@ -26,9 +26,10 @@ class ClinVarRecordMeasure:
     MS_REPEAT_EXPANSION = 'repeat_expansion'
     MS_NO_COMPLETE_COORDS = 'no_complete_coords'
 
-    def __init__(self, measure_xml, clinvar_record):
+    def __init__(self, measure_xml, clinvar_record, vcv_id):
         self.measure_xml = measure_xml
         self.clinvar_record = clinvar_record
+        self.vcv_id = vcv_id
 
     @property
     def all_names(self):

cmat/clinvar_xml_io/clinvar_record.py

@@ -42,7 +42,7 @@ def __init__(self, record_xml, xsd_version, trait_class=ClinVarTrait, measure_cl
         if not variant_measure:
             self.measure = None
         else:
-            self.measure = measure_class(variant_measure, self)
+            self.measure = measure_class(variant_measure, self, self.vcv_id)
 
     def __str__(self):
         return f'ClinVarRecord object with accession {self.accession}'
@@ -60,6 +60,11 @@ def write(self, output):
     def accession(self):
         return find_mandatory_unique_element(self.record_xml, './ClinVarAccession').attrib['Acc']
 
+    @property
+    def vcv_id(self):
+        """ClinVar's accession for a MeasureSet, present only in RCV records."""
+        return find_mandatory_unique_element(self.record_xml, './MeasureSet').attrib.get('Acc', None)
+
     @property
     def last_updated_date(self):
         """This tracks the latest update date, counting even minor technical updates.

cmat/output_generation/clinvar_to_evidence_strings.py

@@ -238,6 +238,7 @@ def generate_evidence_string(clinvar_record, allele_origins, disease_name, disea
         'variantFunctionalConsequenceId': consequence_attributes.so_term.accession,
         'variantId': clinvar_record.measure.vcf_full_coords,  # CHROM_POS_REF_ALT notation.
         'variantRsId': clinvar_record.measure.rs_id,
+        'variantIdFromSource': clinvar_record.vcv_id,
 
         # PHENOTYPE ATTRIBUTES.
         # The alphabetical list of *all* valid disease names from all traits from that ClinVar record, reported as a

data-exploration/clinvar-variant-types/README.md

@@ -9,8 +9,8 @@ The data was last updated on **2022-10-24.** Graphs can be enlarged by clicking
 ## Updating the data
 
 ```bash
-wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarFullRelease_00-latest.xml.gz
-python3 clinvar-variant-types.py --clinvar-xml ClinVarFullRelease_00-latest.xml.gz
+wget -O clinvar.xml.gz https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/RCV_release/ClinVarRCVRelease_00-latest.xml.gz
+python3 clinvar-variant-types.py --clinvar-xml clinvar.xml.gz
 ```
 
 The source code for diagrams and tables will be printed to STDOUT. The diagrams can then be built using the website http://sankeymatic.com/build/. Parameters for rendering them will be indicated in the output as well. The tables should be copy-pasted into the [corresponding Markdown file](supplementary-tables.md).

data-exploration/clinvar-variant-types/clinvar-variant-types.py

@@ -4,7 +4,7 @@
 from collections import Counter
 import logging
 
-from eva_cttv_pipeline.clinvar_xml_io import clinvar_xml_io
+from cmat import clinvar_xml_io
 
 logging.basicConfig()
 logger = logging.getLogger(__name__)

tests/output_generation/resources/expected_genetics_evidence_string.json

@@ -25,5 +25,6 @@
   "variantFunctionalConsequenceId": "SO_0001583",
   "variantHgvsId": "NC_000014.9:g.67729209A>G",
   "variantId": "14_67729209_A_G",
+  "variantIdFromSource": "VCV000002046",
   "variantRsId": "rs28940313"
 }

tests/output_generation/resources/expected_multiple_names_evidence_string.json

@@ -22,5 +22,6 @@
   "variantFunctionalConsequenceId": "SO_0001583",
   "variantHgvsId": "NC_000007.14:g.94423102G>A",
   "variantId": "7_94423102_G_A",
+  "variantIdFromSource": "VCV000374196",
   "variantRsId": "rs1057518967"
 }

tests/output_generation/resources/expected_somatic_evidence_string.json

@@ -25,5 +25,6 @@
   "variantFunctionalConsequenceId": "SO_0001583",
   "variantHgvsId": "NC_000014.9:g.67729209A>G",
   "variantId": "14_67729209_A_G",
+  "variantIdFromSource": "VCV000002046",
   "variantRsId": "rs28940313"
 }