diff --git a/.gitignore b/.gitignore index e560314f..a3fbfa24 100644 --- a/.gitignore +++ b/.gitignore @@ -132,6 +132,7 @@ venv.bak/ # MkDocs build output docs/site/ public/docs/mavedb/ +public/docs/gks-vignettes/ # IDEs and editors .vscode/ diff --git a/docs-gks-vignettes/.gitignore b/docs-gks-vignettes/.gitignore new file mode 100644 index 00000000..b6b3500c --- /dev/null +++ b/docs-gks-vignettes/.gitignore @@ -0,0 +1,2 @@ +.venv/ +site/ diff --git a/docs-gks-vignettes/docs/index.md b/docs-gks-vignettes/docs/index.md new file mode 100644 index 00000000..ebd206b6 --- /dev/null +++ b/docs-gks-vignettes/docs/index.md @@ -0,0 +1,14 @@ +# MaveDB × GA4GH GKS Vignettes + +These pages contain real-world walk-throughs of how **MaveDB** uses the GA4GH **Genomic Knowledge Standards** to solve fundamental problems in sharing multiplexed assay of variant effect (MAVE) and other functional assay data. + +These are drafted for contribution to the [GA4GH GKS Starter Kit](https://github.com/ga4gh/gks-starter-kit); this site is an internal preview. Each vignette describes a real implementation, including the scope of the problem, the underlying data, the tools, and the GKS standards, written to be accessible to a teammate or to leadership. + +## The vignettes + +- [**Giving every MAVE variant a precise, computable identity with VRS**](vignettes/mavedb-mave-variants-vrs/vignette.md) — mapping every variant into VRS 2.0 as MaveDB's canonical variant representation. *(VRS · production)* +- [**Annotating a variant once across every score set that measured it**](vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md) — the VRS digest as a harmonization key. *(VRS · pilot)* +- [**Carrying a measured variant across molecular levels with Cat-VRS**](vignettes/mavedb-protein-variant-cat-vrs/vignette.md) — a variant as a category for its biologically equivalent representations. *(Cat-VRS · proposal)* +- [**Sharing MAVE functional evidence as computable statements with VA-Spec**](vignettes/mavedb-functional-evidence-va-spec/vignette.md) — study results, functional-impact statements, and pathogenicity statements. *(VA-Spec · production)* + +These threads are intended to tell a connected story, following the same variants from VRS identity, through harmonization and categorization, and into VA-Spec evidence. diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json new file mode 100644 index 00000000..dea89428 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json @@ -0,0 +1,1333 @@ +{ + "type": "Statement", + "description": "Variant pathogenicity statement for urn:mavedb:00000096-a-1#2446.", + "specifiedBy": { + "type": "Method", + "name": "ACMG standards and guidelines for the interpretation of sequence variants", + "reportedIn": "https://www.acmg.net/docs/standards_guidelines_for_the_interpretation_of_sequence_variants.pdf" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.755971" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "proposition": { + "type": "VariantPathogenicityProposition", + "description": "Variant pathogenicity proposition for urn:mavedb:00000096-a-1#2446.", + "subjectVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "geneContextQualifier": { + "primaryCoding": { + "system": "https://www.genenames.org/", + "code": "GCK" + } + }, + "predicate": "isCausalFor", + "objectCondition": { + "conceptType": "Disease", + "primaryCoding": { + "system": "https://www.ncbi.nlm.nih.gov/medgen/", + "code": "C0012634", + "iris": [ + "http://identifiers.org/medgen/C0012634" + ] + } + } + }, + "direction": "supports", + "classification": { + "primaryCoding": { + "system": "ACMG Guidelines, 2015", + "code": "pathogenic" + } + }, + "hasEvidenceLines": [ + { + "type": "EvidenceLine", + "description": "Pathogenicity evidence line for urn:mavedb:00000096-a-1#2446.", + "extensions": [ + { + "name": "Containing classification name", + "value": "Decreased activity", + "description": "The name of the classification which contains this variant." + } + ], + "specifiedBy": { + "type": "Method", + "name": "Calibration method", + "methodType": "PS3", + "reportedIn": "Not Provided" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.755235" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "reportedIn": [ + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Document", + "name": "MaveDB Score Calibration", + "extensions": [ + { + "name": "Baseline score", + "value": 1.0, + "description": "No description for this baseline score provided." + }, + { + "name": "Research use only", + "value": false, + "description": "Indicates whether this score calibration is intended for research use only." + }, + { + "name": "Primary calibration", + "value": true, + "description": "Indicates whether this score calibration is the primary calibration for its associated score set." + }, + { + "name": "Investigator provided", + "value": false, + "description": "Indicates whether this score calibration was provided by the investigator rather than generated by MaveDB." + }, + { + "name": "Hyperactive", + "value": [ + 1.18, + null + ], + "description": "No description for this functional classification provided." + }, + { + "name": "(0.66,1.18)", + "value": [ + 0.66, + 1.18 + ], + "description": "No description for this functional classification provided." + }, + { + "name": "Decreased activity", + "value": [ + null, + 0.66 + ], + "description": "No description for this functional classification provided." + } + ], + "documentType": "score calibration", + "title": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "urls": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1/calibrations?calibration=urn%3Amavedb%3Acalibration-b18c5122-57a0-4d54-90a7-9297411219c2" + ] + } + ], + "targetProposition": { + "type": "VariantPathogenicityProposition", + "description": "Variant pathogenicity proposition for urn:mavedb:00000096-a-1#2446.", + "subjectVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "geneContextQualifier": { + "primaryCoding": { + "system": "https://www.genenames.org/", + "code": "GCK" + } + }, + "predicate": "isCausalFor", + "objectCondition": { + "conceptType": "Disease", + "primaryCoding": { + "system": "https://www.ncbi.nlm.nih.gov/medgen/", + "code": "C0012634", + "iris": [ + "http://identifiers.org/medgen/C0012634" + ] + } + } + }, + "hasEvidenceItems": [ + { + "type": "Statement", + "description": "Variant functional impact statement for urn:mavedb:00000096-a-1#2446.", + "specifiedBy": { + "type": "Method", + "name": "Variant interpretation guideline", + "reportedIn": "https://pubmed.ncbi.nlm.nih.gov/29785012/" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.754872" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "proposition": { + "type": "ExperimentalVariantFunctionalImpactProposition", + "description": "Variant functional impact proposition for urn:mavedb:00000096-a-1#2446.", + "subjectVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "predicate": "impactsFunctionOf", + "objectSequenceFeature": { + "primaryCoding": { + "system": "https://www.genenames.org/", + "code": "GCK" + } + }, + "experimentalContextQualifier": { + "id": "urn:mavedb:00000096-a", + "type": "Document", + "name": "MaveDB Experiment", + "description": "Activity of GCK variants measured by functional complementation of an hxk1\u0394hxk2\u0394glk1\u0394 yeast strain.", + "documentType": "experiment", + "title": "GCK activity measured by complementation", + "urls": [ + "https://mavedb.org/experiments/urn:mavedb:00000096-a" + ] + } + }, + "direction": "supports", + "classification": { + "primaryCoding": { + "system": "ga4gh-gks-term:experimental-var-func-impact-classification", + "code": "abnormal" + } + }, + "hasEvidenceLines": [ + { + "type": "EvidenceLine", + "description": "Functional evidence line for urn:mavedb:00000096-a-1#2446", + "extensions": [ + { + "name": "Containing functional classification", + "value": "Decreased activity", + "description": "The functional classification which contains this variant." + } + ], + "specifiedBy": { + "type": "Method", + "name": "Calibration method", + "reportedIn": "http://www.ncbi.nlm.nih.gov/pubmed/37101203" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.754491" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "reportedIn": [ + { + "id": "urn:mavedb:calibration-b18c5122-57a0-4d54-90a7-9297411219c2", + "type": "Document", + "name": "MaveDB Score Calibration", + "extensions": [ + { + "name": "Baseline score", + "value": 1.0, + "description": "No description for this baseline score provided." + }, + { + "name": "Research use only", + "value": false, + "description": "Indicates whether this score calibration is intended for research use only." + }, + { + "name": "Primary calibration", + "value": true, + "description": "Indicates whether this score calibration is the primary calibration for its associated score set." + }, + { + "name": "Investigator provided", + "value": false, + "description": "Indicates whether this score calibration was provided by the investigator rather than generated by MaveDB." + }, + { + "name": "Hyperactive", + "value": [ + 1.18, + null + ], + "description": "No description for this functional classification provided." + }, + { + "name": "(0.66,1.18)", + "value": [ + 0.66, + 1.18 + ], + "description": "No description for this functional classification provided." + }, + { + "name": "Decreased activity", + "value": [ + null, + 0.66 + ], + "description": "No description for this functional classification provided." + } + ], + "documentType": "score calibration", + "title": "IGVF Coding Variant Focus Group -- Controls: All Variants", + "urls": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1/calibrations?calibration=urn%3Amavedb%3Acalibration-b18c5122-57a0-4d54-90a7-9297411219c2" + ] + } + ], + "hasEvidenceItems": [ + { + "type": "ExperimentalVariantFunctionalImpactStudyResult", + "description": "Variant effect study result for urn:mavedb:00000096-a-1#2446.", + "specifiedBy": { + "type": "Method", + "name": "Experimental protocol", + "reportedIn": "http://www.ncbi.nlm.nih.gov/pubmed/37101203" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.486748" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Creator", + "description": "When this resource was first submitted, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0001-5034-1952", + "description": "MaveDB ORCid authenticated user 0000-0001-5034-1952", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000105", + "date": "2022-03-18 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Modifier", + "description": "When this resource was last modified, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0001-5034-1952", + "description": "MaveDB ORCid authenticated user 0000-0001-5034-1952", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000103", + "date": "2022-06-14 00:00:00" + } + ], + "reportedIn": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1?variant=urn%3Amavedb%3A00000096-a-1%232446", + "https://mavedb.org/variant/PA2579976630" + ], + "sourceDataSet": { + "id": "urn:mavedb:00000096-a-1", + "type": "DataSet", + "name": "GCK activity measured by complementation", + "description": "Activity of GCK variants measured by functional complementation of an hxk1\u0394hxk2\u0394glk1\u0394 yeast strain.", + "reportedIn": "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1", + "releaseDate": "2022-06-14", + "license": { + "name": "CC0 (Public domain)", + "primaryCoding": { + "system": "https://spdx.org/licenses/", + "systemVersion": "1.0", + "code": "CC0-1.0", + "iris": [ + "https://creativecommons.org/publicdomain/zero/1.0/" + ] + } + } + }, + "focusVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "functionalImpactScore": 0.21223874 + } + ], + "directionOfEvidenceProvided": "supports", + "evidenceOutcome": { + "primaryCoding": { + "system": "ga4gh-gks-term:experimental-var-func-impact-classification", + "code": "abnormal" + } + } + } + ] + } + ], + "directionOfEvidenceProvided": "supports", + "strengthOfEvidenceProvided": { + "primaryCoding": { + "system": "ACMG Guidelines, 2015", + "code": "moderate" + } + }, + "evidenceOutcome": { + "name": "ACMG 2015 PS3 Criterion Met", + "primaryCoding": { + "system": "ACMG Guidelines, 2015", + "code": "PS3_moderate" + } + } + }, + { + "type": "EvidenceLine", + "description": "Pathogenicity evidence line for urn:mavedb:00000096-a-1#2446.", + "extensions": [ + { + "name": "Containing classification name", + "value": "Decreased activity", + "description": "The name of the classification which contains this variant." + } + ], + "specifiedBy": { + "type": "Method", + "name": "Calibration method", + "methodType": "PS3", + "reportedIn": "Not Provided" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.755802" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-c1472fe6-94f4-4785-b313-4777e9839f92", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: Missense Variants Only", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "reportedIn": [ + { + "id": "urn:mavedb:calibration-c1472fe6-94f4-4785-b313-4777e9839f92", + "type": "Document", + "name": "MaveDB Score Calibration", + "extensions": [ + { + "name": "Baseline score", + "value": 1.0, + "description": "No description for this baseline score provided." + }, + { + "name": "Research use only", + "value": false, + "description": "Indicates whether this score calibration is intended for research use only." + }, + { + "name": "Primary calibration", + "value": false, + "description": "Indicates whether this score calibration is the primary calibration for its associated score set." + }, + { + "name": "Investigator provided", + "value": false, + "description": "Indicates whether this score calibration was provided by the investigator rather than generated by MaveDB." + }, + { + "name": "Decreased activity", + "value": [ + null, + 0.66 + ], + "description": "No description for this functional classification provided." + }, + { + "name": "Hyperactive", + "value": [ + 1.18, + null + ], + "description": "No description for this functional classification provided." + }, + { + "name": "(0.66,1.18)", + "value": [ + 0.66, + 1.18 + ], + "description": "No description for this functional classification provided." + } + ], + "documentType": "score calibration", + "title": "IGVF Coding Variant Focus Group -- Controls: Missense Variants Only", + "urls": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1/calibrations?calibration=urn%3Amavedb%3Acalibration-c1472fe6-94f4-4785-b313-4777e9839f92" + ] + } + ], + "targetProposition": { + "type": "VariantPathogenicityProposition", + "description": "Variant pathogenicity proposition for urn:mavedb:00000096-a-1#2446.", + "subjectVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "geneContextQualifier": { + "primaryCoding": { + "system": "https://www.genenames.org/", + "code": "GCK" + } + }, + "predicate": "isCausalFor", + "objectCondition": { + "conceptType": "Disease", + "primaryCoding": { + "system": "https://www.ncbi.nlm.nih.gov/medgen/", + "code": "C0012634", + "iris": [ + "http://identifiers.org/medgen/C0012634" + ] + } + } + }, + "hasEvidenceItems": [ + { + "type": "Statement", + "description": "Variant functional impact statement for urn:mavedb:00000096-a-1#2446.", + "specifiedBy": { + "type": "Method", + "name": "Variant interpretation guideline", + "reportedIn": "https://pubmed.ncbi.nlm.nih.gov/29785012/" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.755708" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-c1472fe6-94f4-4785-b313-4777e9839f92", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: Missense Variants Only", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "proposition": { + "type": "ExperimentalVariantFunctionalImpactProposition", + "description": "Variant functional impact proposition for urn:mavedb:00000096-a-1#2446.", + "subjectVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "predicate": "impactsFunctionOf", + "objectSequenceFeature": { + "primaryCoding": { + "system": "https://www.genenames.org/", + "code": "GCK" + } + }, + "experimentalContextQualifier": { + "id": "urn:mavedb:00000096-a", + "type": "Document", + "name": "MaveDB Experiment", + "description": "Activity of GCK variants measured by functional complementation of an hxk1\u0394hxk2\u0394glk1\u0394 yeast strain.", + "documentType": "experiment", + "title": "GCK activity measured by complementation", + "urls": [ + "https://mavedb.org/experiments/urn:mavedb:00000096-a" + ] + } + }, + "direction": "supports", + "classification": { + "primaryCoding": { + "system": "ga4gh-gks-term:experimental-var-func-impact-classification", + "code": "abnormal" + } + }, + "hasEvidenceLines": [ + { + "type": "EvidenceLine", + "description": "Functional evidence line for urn:mavedb:00000096-a-1#2446", + "extensions": [ + { + "name": "Containing functional classification", + "value": "Decreased activity", + "description": "The functional classification which contains this variant." + } + ], + "specifiedBy": { + "type": "Method", + "name": "Calibration method", + "reportedIn": "http://www.ncbi.nlm.nih.gov/pubmed/37101203" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.755510" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "id": "urn:mavedb:calibration-c1472fe6-94f4-4785-b313-4777e9839f92", + "type": "Contribution", + "name": "IGVF Coding Variant Focus Group -- Controls: Missense Variants Only", + "description": "Contribution from a score calibration.", + "contributor": { + "type": "Agent", + "name": "AnonymousUser", + "description": "MaveDB ORCid authenticated user AnonymousUser", + "agentType": "Person" + }, + "activityType": "variant specific calibration", + "date": "2025-11-14 00:00:00" + } + ], + "reportedIn": [ + { + "id": "urn:mavedb:calibration-c1472fe6-94f4-4785-b313-4777e9839f92", + "type": "Document", + "name": "MaveDB Score Calibration", + "extensions": [ + { + "name": "Baseline score", + "value": 1.0, + "description": "No description for this baseline score provided." + }, + { + "name": "Research use only", + "value": false, + "description": "Indicates whether this score calibration is intended for research use only." + }, + { + "name": "Primary calibration", + "value": false, + "description": "Indicates whether this score calibration is the primary calibration for its associated score set." + }, + { + "name": "Investigator provided", + "value": false, + "description": "Indicates whether this score calibration was provided by the investigator rather than generated by MaveDB." + }, + { + "name": "Decreased activity", + "value": [ + null, + 0.66 + ], + "description": "No description for this functional classification provided." + }, + { + "name": "Hyperactive", + "value": [ + 1.18, + null + ], + "description": "No description for this functional classification provided." + }, + { + "name": "(0.66,1.18)", + "value": [ + 0.66, + 1.18 + ], + "description": "No description for this functional classification provided." + } + ], + "documentType": "score calibration", + "title": "IGVF Coding Variant Focus Group -- Controls: Missense Variants Only", + "urls": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1/calibrations?calibration=urn%3Amavedb%3Acalibration-c1472fe6-94f4-4785-b313-4777e9839f92" + ] + } + ], + "hasEvidenceItems": [ + { + "type": "ExperimentalVariantFunctionalImpactStudyResult", + "description": "Variant effect study result for urn:mavedb:00000096-a-1#2446.", + "specifiedBy": { + "type": "Method", + "name": "Experimental protocol", + "reportedIn": "http://www.ncbi.nlm.nih.gov/pubmed/37101203" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:44:14.486748" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-05-28 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Creator", + "description": "When this resource was first submitted, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0001-5034-1952", + "description": "MaveDB ORCid authenticated user 0000-0001-5034-1952", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000105", + "date": "2022-03-18 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Modifier", + "description": "When this resource was last modified, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0001-5034-1952", + "description": "MaveDB ORCid authenticated user 0000-0001-5034-1952", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000103", + "date": "2022-06-14 00:00:00" + } + ], + "reportedIn": [ + "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1?variant=urn%3Amavedb%3A00000096-a-1%232446", + "https://mavedb.org/variant/PA2579976630" + ], + "sourceDataSet": { + "id": "urn:mavedb:00000096-a-1", + "type": "DataSet", + "name": "GCK activity measured by complementation", + "description": "Activity of GCK variants measured by functional complementation of an hxk1\u0394hxk2\u0394glk1\u0394 yeast strain.", + "reportedIn": "https://mavedb.org/score-sets/urn:mavedb:00000096-a-1", + "releaseDate": "2022-06-14", + "license": { + "name": "CC0 (Public domain)", + "primaryCoding": { + "system": "https://spdx.org/licenses/", + "systemVersion": "1.0", + "code": "CC0-1.0", + "iris": [ + "https://creativecommons.org/publicdomain/zero/1.0/" + ] + } + } + }, + "focusVariant": { + "id": "ga4gh:VA.uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "F" + } + ], + "digest": "uKdR7fpiG9_r42oyAC33xQyd24VUNW3I", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_000153.1:p.Phe269Gln" + } + ], + "location": { + "id": "ga4gh:SL.mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "type": "SequenceLocation", + "digest": "mr0SP5seWdgAplFqdmHBAbdhfmPcalZq", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ._mgLuM2tl_ap4JfYxyyr96JzV_FxAqsk" + }, + "start": 268, + "end": 269 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + } + }, + "functionalImpactScore": 0.21223874 + } + ], + "directionOfEvidenceProvided": "supports", + "evidenceOutcome": { + "primaryCoding": { + "system": "ga4gh-gks-term:experimental-var-func-impact-classification", + "code": "abnormal" + } + } + } + ] + } + ], + "directionOfEvidenceProvided": "supports", + "strengthOfEvidenceProvided": { + "primaryCoding": { + "system": "ACMG Guidelines, 2015", + "code": "moderate" + } + }, + "evidenceOutcome": { + "name": "ACMG 2015 PS3 Criterion Met", + "primaryCoding": { + "system": "ACMG Guidelines, 2015", + "code": "PS3_moderate" + } + } + } + ] +} \ No newline at end of file diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/ube2i-leu6gly.study-result.va.json b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/ube2i-leu6gly.study-result.va.json new file mode 100644 index 00000000..d50d784b --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/ube2i-leu6gly.study-result.va.json @@ -0,0 +1,143 @@ +{ + "type": "ExperimentalVariantFunctionalImpactStudyResult", + "description": "Variant effect study result for urn:mavedb:00000001-a-1#2323.", + "specifiedBy": { + "type": "Method", + "name": "Experimental protocol", + "reportedIn": "http://www.ncbi.nlm.nih.gov/pubmed/29269382" + }, + "contributions": [ + { + "type": "Contribution", + "name": "MaveDB API", + "description": "Contribution from the MaveDB API", + "contributor": { + "type": "Agent", + "name": "MaveDB API", + "description": "MaveDB API agent, version 2026.2.5", + "extensions": [ + { + "name": "mavedbApiVersion", + "value": "2026.2.5" + } + ], + "agentType": "Software" + }, + "activityType": "software application programming interface", + "date": "2026-06-24 18:13:21.636210" + }, + { + "type": "Contribution", + "name": "MaveDB VRS Mapper", + "description": "Contribution from the MaveDB VRS mapping software", + "contributor": { + "type": "Agent", + "name": "MaveDB VRS Mapping Agent", + "description": "MaveDB VRS mapping agent, version 2026.2.0", + "extensions": [ + { + "name": "mavedbVrsVersion", + "value": "2026.2.0" + } + ], + "agentType": "Software" + }, + "activityType": "human genome sequence mapping process", + "date": "2026-06-10 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Creator", + "description": "When this resource was first submitted, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0003-1628-9390", + "description": "MaveDB ORCid authenticated user 0000-0003-1628-9390", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000105", + "date": "2018-06-26 00:00:00" + }, + { + "type": "Contribution", + "name": "MaveDB Dataset Modifier", + "description": "When this resource was last modified, and by whom.", + "extensions": [ + { + "name": "resourceType", + "value": "Variant" + } + ], + "contributor": { + "type": "Agent", + "name": "0000-0003-1628-9390", + "description": "MaveDB ORCid authenticated user 0000-0003-1628-9390", + "agentType": "Person" + }, + "activityType": "http://purl.obolibrary.org/obo/CRO_0000103", + "date": "2019-02-14 00:00:00" + } + ], + "reportedIn": [ + "https://mavedb.org/score-sets/urn:mavedb:00000001-a-1?variant=urn%3Amavedb%3A00000001-a-1%232323", + "https://mavedb.org/variant/PA2579755325" + ], + "sourceDataSet": { + "id": "urn:mavedb:00000001-a-1", + "type": "DataSet", + "name": "UBE2I imputed & refined", + "description": "A joint Deep Mutational Scan of the human SUMO E2 conjugase UBE2I using functional complementation in yeast, combining DMS-BarSeq and DMS-TileSeq data, followed by machine-learning-based imputation and refinement.", + "reportedIn": "https://mavedb.org/score-sets/urn:mavedb:00000001-a-1", + "releaseDate": "2018-06-26", + "license": { + "name": "CC0 (Public domain)", + "primaryCoding": { + "system": "https://spdx.org/licenses/", + "systemVersion": "1.0", + "code": "CC0-1.0", + "iris": [ + "https://creativecommons.org/publicdomain/zero/1.0/" + ] + } + } + }, + "focusVariant": { + "id": "ga4gh:VA.P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "type": "Allele", + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "value": "L" + } + ], + "digest": "P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "expressions": [ + { + "syntax": "hgvs.p", + "value": "NP_003336.1:p.Leu6Gly" + } + ], + "location": { + "id": "ga4gh:SL.o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "type": "SequenceLocation", + "digest": "o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "sequenceReference": { + "type": "SequenceReference", + "refgetAccession": "SQ.hy5ErT-cGJovsPYIgzchb3BvYQ2MkKB3" + }, + "start": 5, + "end": 6 + }, + "state": { + "type": "LiteralSequenceExpression", + "sequence": "G" + } + }, + "functionalImpactScore": 0.616282520019444 +} \ No newline at end of file diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/vignette.md b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/vignette.md new file mode 100644 index 00000000..1f57bfec --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/vignette.md @@ -0,0 +1,84 @@ +--- +title: "Sharing computable functional evidence with VA-Spec" +slug: mavedb-functional-evidence-va-spec +summary: "MaveDB publishes its functional measurements as a layered stack of VA-Spec statements — raw study results, per-assay functional-impact calls, and variant-level pathogenicity statements — turning experimental scores into provenance-rich evidence clinical interpretation pipelines can consume directly." +products: + - name: VA-Spec + version: "0.4" +pattern: clinical-evidence-sharing +implementer: MaveDB +status: production +contributors: + - bencap + - MaveDB team +last_updated: 2026-08-06 +--- + +# Sharing computable functional evidence with VA-Spec + +Multiplexed assays measure how genetic variants behave using experimental models, and those measurements are some of the strongest evidence available for deciding whether a variant is pathogenic or benign. +Historically, this evidence has lived in spreadsheets or other tabular format that required clinical curators to read and understand often-complex research papers before they could inform a variant's classification. +MaveDB now produces a structured statement for reach variant that represents the score, experimental design, and provenance of the data and metadata using a structured format that clinical information systems can process unambiguously. +Furthermore, because this VA-Spec format is part of a constellation of related standards that are interoperable with the models for functional data implemented by MaveDB, this is also a potent enabler for integration across diverse evidence types beyond functional assays. + +- **Who:** MaveDB +- **GKS products used:** VA-Spec 0.4 with VRS 2.0 variant representations +- **Tools:** [ga4gh-va-spec](https://github.com/ga4gh/va-spec-python) (`ga4gh-va-spec` ~0.4.2), MaveDB annotation pipeline +- **Status:** production + +## Motivation + +A multiplexed assay of variant effect produces a numeric functional score for each variant that summarizes how the variant performed in the experiment. +On its own, a score is hard to reuse and interpret because a downstream consumer needs to know precisely which variant it refers to, what the number means, how it was generated, and whether its provenance is trustworthy enough to act on (e.g. what information was peer reviewed). + +MaveDB represents this using the GA4GH **Variant Annotation Specification (VA-Spec)**, implemented as a stack of three statement types at increasing levels. + +The foundational object is the `ExperimentalVariantFunctionalImpactStudyResult` that contains the numeric score from the assay. +Its `focusVariant` is the variant's [VRS allele](../mavedb-mave-variants-vrs/vignette.md), which anchors the evidence to a precise, content-addressed identity. +The `functionalImpactScore` carries the measured value. +A `contributions` chain records the record's provenance by naming the MaveDB API and VRS-mapping software (with versions), the original submitter (by ORCID iD), and the relevant dates. +The `sourceDataSet` describes the MaveDB score set, its publication, and its license and the `reportedIn` entry links back to the live MaveDB record. +MaveDB produces an `ExperimentalVariantFunctionalImpactStudyResult` for every mappable variant in every published score set. + +Before a functional score can be used as evidence for variant classification, it needs to be calibrated using reference variants of known effect. +There are several methods for calibrating datasets but the most widely-used assign a variant to a functional classification (e.g. `abnormal` or `normal`) based on its score and assigning evidence based on these groups. +MaveDB stores these assignments using `Statement` objects in VA-Spec, with an associated `ExperimentalVariantFunctionalImpactProposition` specifying whether the variant affects target function or not (i.e. is `abnormal` or `normal`). +The associated information about these functional classifications, such as score ranges and their provenance, are also included here. +The `ExperimentalVariantFunctionalImpactStudyResult` is included as an `EvidenceLine`, because this is the evidence used to support or refute the proposition. + +Once the functional scores are calibrated, they are assigned *evidence strength* that may be applied in a variant classification framework (e.g. PS3_Strong or BS3_Supporting for ACMG v3). +These evidence strengths are represented using another `Statement` object with an associated `VariantPathogenicityProposition`. +Similar to above, the functional classification `Statement` are included as `EvidenceLine` members as needed (note that some calibration methods assign evidence to variants directly based on their scores and do not require functional classes). +MaveDB generates one variant pathogenicity `Statement` for each variant in a given score set containing all possible calibration informations. +Downstream users can choose which calibration to apply based on the metadata provided and their own expert judgement. + +## Example data + +We provide two examples. +The first is an `ExperimentalVariantFunctionalImpactStudyResult` for UBE2I [p.Leu6Gly](https://mavedb.org/variants/PA2579755325) (`urn:mavedb:00000001-a-1#2323`, from the [Weile et al., 2017 score set](https://mavedb.org/score-sets/urn:mavedb:00000001-a-1)). Its `focusVariant.id` is the VRS digest produced by the variant-mapping pattern: + +???+ example "ExperimentalVariantFunctionalImpactStudyResult — UBE2I p.Leu6Gly" + ```json + --8<-- "docs/vignettes/mavedb-functional-evidence-va-spec/payloads/ube2i-leu6gly.study-result.va.json" + ``` + +The second is a variant-level pathogenicity `Statement` for a [GCK variant](https://mavedb.org/variants/PA2579976630) (`urn:mavedb:00000096-a-1#2446`, from [this score set](https://mavedb.org/score-sets/urn:mavedb:00000096-a-1)). +There are two separate calibrations, one performed using all possible variants and another performed using only missense variants. +These were performed without any specific disease condition or phenotype in mind, so the proposition's condition is MedGen `C0012634`, the generic "Disease" concept; most calibrations in MaveDB are done in this way but calibrations for specific conditions are supported through this property. +For both calibrations, the variant provides moderate pathogenic evidence (supporting the pathogenicity proposition) and is assigned the ACMG v3 evidence code `PS3_Moderate`: + +??? example "Pathogenicity Statement — GCK variant (1,332 lines)" + ```json + --8<-- "docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json" + ``` + +## Tools + +- [**ga4gh-va-spec**](https://github.com/ga4gh/va-spec-python) (`ga4gh-va-spec` ~0.4.2) — the VA-Spec `StudyResult`, `Statement`, `EvidenceLine`, `Contribution`, and `DataSet` models. +- [**MaveDB API**](https://api.mavedb.org/docs) — generates and serves these VA-Spec annotations as well as the associated data. + +## Reusing this pattern + +- [VA-Spec specification](https://va-ga4gh.readthedocs.io/) — definitions for the shared models. +- Foundational vignette: [Giving every MAVE variant a precise, computable identity with VRS](../mavedb-mave-variants-vrs/vignette.md) — the `focusVariant` used by these statements. +- MaveDB API source: [VariantEffect/mavedb-api](https://github.com/VariantEffect/mavedb-api) — where these VA-Spec statements are assembled and served. diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/payloads/ube2i-leu6gly.vrs.json b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/payloads/ube2i-leu6gly.vrs.json new file mode 100644 index 00000000..c7f4c041 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/payloads/ube2i-leu6gly.vrs.json @@ -0,0 +1,34 @@ +{ + "id": "ga4gh:VA.P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "type": "Allele", + "state": { + "type": "LiteralSequenceExpression", + "sequence": "G" + }, + "digest": "P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "location": { + "id": "ga4gh:SL.o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "end": 6, + "type": "SequenceLocation", + "start": 5, + "digest": "o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "sequenceReference": { + "type": "SequenceReference", + "label": "NP_003336.1", + "refgetAccession": "SQ.hy5ErT-cGJovsPYIgzchb3BvYQ2MkKB3" + } + }, + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "type": "Extension", + "value": "L" + } + ], + "expressions": [ + { + "value": "NP_003336.1:p.Leu6Gly", + "syntax": "hgvs.p" + } + ] +} \ No newline at end of file diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md new file mode 100644 index 00000000..ed1e79a8 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md @@ -0,0 +1,77 @@ +--- +title: "Giving every MAVE variant a precise, computable identity with VRS" +slug: mavedb-mave-variants-vrs +summary: "MaveDB represents every variant from every multiplexed assay using GA4GH VRS, providing canonical, content-addressed identifiers that enable discovery and downstream integration." +products: + - name: VRS + version: "2.0" +pattern: variant-annotation +implementer: MaveDB +status: production +contributors: + - bencap + - afrubin + - MaveDB team +last_updated: 2026-08-03 +--- + +# Giving every MAVE variant a precise, computable identity with VRS + +MaveDB collects the results of multiplexed assays of variant effect, experiments that measure the functional impact of thousands of genetic variants at once, as well as data from lower-throughput functional studies. +Every contributing lab describes its variants differently. +Variants are reported against an experiment-specific target sequence, may be scored at the protein level or the DNA level, and appear using whatever notation suited the experiment. +These differences create challenges when looking at records that may describe the same change, or for connecting a variant to anything outside the original study. +MaveDB now represents every variant it stores using a single shared standard that provides a precise, computable identity that any other system can recognize. + +- **Who:** MaveDB +- **GKS products used:** VRS 2.0 +- **Tools:** [`dcd-mapping`](https://github.com/VariantEffect/dcd_mapping2), [`vrs-python`](https://github.com/ga4gh/vrs-python) (v2.0.0-a6), [`cool-seq-tool`](https://github.com/GenomicMedLab/cool-seq-tool) (v0.4.0.dev3), [`cdot`](https://github.com/SACGF/cdot), [`seqrepo`](https://github.com/biocommons/biocommons.seqrepo) +- **Status:** production + +## Motivation + +A multiplexed assay reports variants in the context of its specific experimental design. +A cDNA-based deep mutational scan of a protein typically measures amino-acid changes against an engineered target; a saturation genome editing screen names nucleotide changes against a genomic window. +Therefore, we need a data standard that can flexibly represent multiple types of variants across sequence contexts and organisms. +When uploaded by users or presented for human interpretation, MaveDB uses a slightly modified subset of the HGVS nomenclature (called MAVE-HGVS), but those records can be ambiguous, making them challenging to compare or search precisely. + +MaveDB resolves this by representing every variant using the GA4GH **Variant Representation Specification (VRS) 2.0**. +VRS includes built-in variant normalization as part of object generation that solves many of the challenges in MAVE-HGVS. +For example, multi-nucleotide substitution variants and their equivalent deletion-insertion represtentation evaluate to the same underlying VRS digest, indicating their identity. +VRS is also easily able to represent both nucleotide and amino acid level variants. + +Because VRS uses composable JSON documents, we can also easily combine multiple variants together into a single object. +For datasets based on human sequences, the `dcd-mapping` pipeline takes each variant's HGVS description, aligns the assay's target to a standard reference sequence using `cool-seq-tool` and `cdot`, and produces a normalized VRS allele with respect to the reference. +This **post-mapped** allele can be easily stored alongside the **pre-mapped** allele as part of the same expanded JSON document. +By presenting both alleles together, we preserve the provenance of the original assays's target sequence, while also sharing the reference-based object that is more useful for downstream data integration and variant matching tasks. + +VRS representations are a fundamental component of MaveDB's modern backend. +It allows us to store variants precisely, effienciently search over the entire dataset, and connect downstream annotations. + +## Example data + +Here is a real post-mapped VRS 2.0 Allele for the UBE2I variant [p.Leu6Gly](https://mavedb.org/variants/PA2579755325) from the deep mutational scan described in score set [`urn:mavedb:00000001-a-1`](https://mavedb.org/score-sets/urn:mavedb:00000001-a-1) (Weile et al., 2017). Because this is mapped to the reference, the `id` and `digest` are computed from the location and state, meaning the same change would produce the same digest from any source (e.g., another functional assay): + +???+ example "VRS 2.0 Allele — UBE2I:p.Leu6Gly" + ```json + --8<-- "docs/vignettes/mavedb-mave-variants-vrs/payloads/ube2i-leu6gly.vrs.json" + ``` + +The `location` points into a standard protein reference (`NP_003336.1`, addressed by its content-based `refgetAccession`), the `state` records the substituted residue (`G`), and the `expressions` block carries the human-readable HGVS (`NP_003336.1:p.Leu6Gly`) alongside the machine identifier. + +## Tools + +- [**`dcd-mapping`**](https://github.com/VariantEffect/dcd_mapping2) — MaveDB's pipeline that aligns each assay's target to a reference and emits VRS alleles for every variant in a score set. +- [**`vrs-python`**](https://github.com/ga4gh/vrs-python) (v2.0.0-a6) — VRS 2.0 Allele/Haplotype models, normalization, and digest computation (`ga4gh_identify`). +- [**`cool-seq-tool`**](https://github.com/GenomicMedLab/cool-seq-tool) v0.4.0.dev3 and [**`cdot`**](https://github.com/SACGF/cdot) — transcript selection and alignment between assay targets and standard references. +- [**`seqrepo`**](https://github.com/biocommons/biocommons.seqrepo) — sequence storage and refget accession resolution. +- [**MaveDB API**](https://api.mavedb.org/docs) — stores the resulting VRS alleles and serves them as MaveDB's canonical variant representation. + +## Reusing this pattern + +- [VRS 2.0 specification and quick start](https://vrs.ga4gh.org/) +- [vrs-python documentation](https://github.com/ga4gh/vrs-python) +- MaveDB API source: [VariantEffect/mavedb-api](https://github.com/VariantEffect/mavedb-api) — the service that maps and serves these VRS variants. +- Related vignette: [Linking the same variant across multiple assays](../mavedb-vrs-cross-score-set-harmonization/vignette.md) — using the VRS identifiers to link variants across assays. +- Related vignette: [Carrying a measured variant across molecular levels with Cat-VRS](../mavedb-protein-variant-cat-vrs/vignette.md) — implementing Cat-VRS over these alleles. +- Related vignette: [Sharing MAVE functional evidence as computable statements with VA-Spec](../mavedb-functional-evidence-va-spec/vignette.md) — attaching variant classification evidence to these VRS variants. diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json new file mode 100644 index 00000000..cf1cb3d9 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json @@ -0,0 +1,76 @@ +{ + "id": "mavedb.cat-vrs:ube2i-leu6gly", + "type": "CategoricalVariant", + "name": "UBE2I p.Leu6Gly", + "description": "A UBE2I variant measured by a multiplexed assay at the protein level. The categorical variant spans every equivalent change across levels; the defining constraint carries the measured allele so the original level and its score keep their provenance, while members expose the coding and genomic changes that satisfy it.", + "extensions": [ + { + "name": "mavedbMeasuredMolecularLevel", + "value": "protein" + } + ], + "constraints": [ + { + "type": "DefiningAlleleConstraint", + "relations": [ + "translates_from" + ], + "allele": { + "id": "ga4gh:VA.P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "type": "Allele", + "state": { + "type": "LiteralSequenceExpression", + "sequence": "G" + }, + "digest": "P39KFBT8kdyfg79JH7IBX-4JKXGrzCxb", + "location": { + "id": "ga4gh:SL.o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "end": 6, + "type": "SequenceLocation", + "start": 5, + "digest": "o4bho24Xqm_HS5mD8-HDjtmtLCZ5XLez", + "sequenceReference": { + "type": "SequenceReference", + "label": "NP_003336.1", + "refgetAccession": "SQ.hy5ErT-cGJovsPYIgzchb3BvYQ2MkKB3" + } + }, + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "type": "Extension", + "value": "L" + } + ], + "expressions": [ + { + "value": "NP_003336.1:p.Leu6Gly", + "syntax": "hgvs.p" + } + ] + } + } + ], + "members": [ + { + "type": "Allele", + "description": "Coding-level member (illustrative). Reverse translation enumerates the coding changes encoding this protein consequence; the pipeline computes each members location and digest.", + "expressions": [ + { + "syntax": "hgvs.c", + "value": "NM_003345.4:c.16_17delinsGG" + } + ] + }, + { + "type": "Allele", + "description": "Genomic-level member (illustrative), the same change projected to the reference genome.", + "expressions": [ + { + "syntax": "hgvs.g", + "value": "NC_000016.10:g.1314000_1314001delinsGG" + } + ] + } + ] +} \ No newline at end of file diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md new file mode 100644 index 00000000..ef8e924f --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md @@ -0,0 +1,69 @@ +--- +title: "Carrying a measured variant across molecular levels with Cat-VRS" +slug: mavedb-protein-variant-cat-vrs +summary: "A multiplexed assay typically measures a variant at one molecular level (e.g. amino acid), but consumers need it at others (e.g. genomic). MaveDB plans to use Cat-VRS to present each measured variant as a category containing equivalent changes, while preserving the level of the assay." +products: + - name: Cat-VRS + version: "1.0" +pattern: variant-categorization +implementer: MaveDB +status: proposal +contributors: + - bencap + - MaveDB team +last_updated: 2026-08-03 +--- + +# Carrying a measured variant across molecular levels with Cat-VRS + +A multiplexed assay typically generates variant functional scores at a single molecular level — often the protein, sometimes the DNA. +Being able to convert between levels is essential for a variety of use cases: a clinical genomics pipeline works from DNA coordinates, while a protein modeller wants the amino acid change. +The degenerate nature of the genetic code means that one protein change can be produced by several different DNA changes, so moving between levels is not a simple one-to-one relabel. +MaveDB plans to present each measured variant as an explicit Cat-VRS category that spans its equivalent forms across levels, while preserving the level was actually measured. +Therefore a downstream data consumer can apply variant data at the level they need without losing the provenance of the original measurement. + +- **Who:** MaveDB +- **GKS products used:** Cat-VRS 1.0 (proposed), building on VRS 2.0 variants +- **Tools:** [cat-vrs](https://github.com/ga4gh/cat-vrs) (`CategoricalVariant`), [vrs-python](https://github.com/ga4gh/vrs-python) +- **Status:** proposal — MaveDB already computes the cross-level equivalent variants; presenting them as Cat-VRS categorical variants is planned + +## Motivation + +Consider a deep mutational scan that reports a score for the protein change UBE2I `p.Leu6Gly`. +The score was measured at the protein level, which is typical for a cDNA-based assay, but due to the redundancy in the genetic code, this amino acid change can result from multiple unique nucleotide changes. +The assay measured and reported only the amino acid variant and did not distinguish between nucleotide variants. +Assigning the score for the amino acid substitution to the underlying DNA alleles would imply that the DNA variants were measured directly, but storing it as only a protein allele disconnects the variant measurement from the DNA coordinates required by downstream tools. +The same tension runs the other way for DNA-level assays, whose measured nucleotide change implies a protein consequence a protein-focused consumer would want surfaced, where ambiguity may be introduced because of alternative protein isoforms. + +MaveDB already computes these cross-level equivalents. +For a protein measurement it works out the coding and genomic changes that produce the amino acid change (i.e. reverse translation — the more challenging direction, because it is one-to-many); for a DNA measurement it derives the protein consequence and the synonymous equivalents. +Each equivalent variant is stored as a deduplicated VRS allele, tagged with its level and linked back to the assay measurement, with the measured allele marked as the authoritative one. + +The plan is to expose that web of equivalent variants using the GA4GH **Categorical Variation Specification (Cat-VRS)**. +Each scored variant is presented as a `CategoricalVariant` whose **defining constraint** is the *measured* [VRS allele](../mavedb-mave-variants-vrs/vignette.md) — the level at which the variants were scored, so the measurement's provenance is explicit — and whose **members** are the equivalent VRS alleles. +This structure specifies precisely what was measured while making every equivalent change explicit and machine-resolvable, letting a consumer attach or read the score at whatever level is needed. + +## Example data + +A **proposed** Cat-VRS `CategoricalVariant` for the measured variant UBE2I [p.Leu6Gly](https://mavedb.org/variants/PA2579755325). +The defining constraint holds the measured MaveDB post-mapped protein allele (`ga4gh:VA.P39KFBT8…`) and an extension states that protein was the measured level. +The `members` are illustrative, showing the shape of the coding and genomic equivalents MaveDB computes, whose concrete coordinates and digests are filled in by the MaveDB processing pipeline: + +???+ example "Proposed CategoricalVariant — UBE2I p.Leu6Gly" + ```json + --8<-- "docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json" + ``` + +## Tools + +- [**cat-vrs**](https://github.com/ga4gh/cat-vrs) — the `CategoricalVariant` model, with a `DefiningAlleleConstraint` for the measured variant and `members` for its equivalents; the proposed representation. +- [**vrs-python**](https://github.com/ga4gh/vrs-python) — represents the measured allele and every member as VRS alleles. +- **MaveDB's cross-level translation** — an internal step that derives a measured variant's equivalents at the other molecular levels. +- [**MaveDB API**](https://api.mavedb.org/docs) — stores the level-tagged alleles and is where the categorical variants are assembled and served. + +## Reusing this pattern + +- [Cat-VRS specification and examples](https://github.com/ga4gh/cat-vrs) — `CategoricalVariant`, defining constraints, and the `proteinSequenceConsequence` recipe. +- Foundational vignette: [Giving every MAVE variant a precise, computable identity with VRS](../mavedb-mave-variants-vrs/vignette.md) — the alleles a categorical variant is built from. +- MaveDB API source: [VariantEffect/mavedb-api](https://github.com/VariantEffect/mavedb-api) — where the level-tagged alleles are stored and the categorical variants will be assembled. +- Related vignette: [Sharing MAVE functional evidence with VA-Spec](../mavedb-functional-evidence-va-spec/vignette.md) — the score that attaches to this categorical variant. diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/payloads/tp53-glu11gln.postmapped.vrs.json b/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/payloads/tp53-glu11gln.postmapped.vrs.json new file mode 100644 index 00000000..a4aeb9ad --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/payloads/tp53-glu11gln.postmapped.vrs.json @@ -0,0 +1,34 @@ +{ + "id": "ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ", + "type": "Allele", + "state": { + "type": "LiteralSequenceExpression", + "sequence": "Q" + }, + "digest": "SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ", + "location": { + "id": "ga4gh:SL.XVL3-XNEArW9-cTBzHRMwdWXgLvJKcJh", + "end": 11, + "type": "SequenceLocation", + "start": 10, + "digest": "XVL3-XNEArW9-cTBzHRMwdWXgLvJKcJh", + "sequenceReference": { + "type": "SequenceReference", + "label": "NP_000537.3", + "refgetAccession": "SQ.KAxM06sYzBF6zFftFaYq9E_18wsnn7al" + } + }, + "extensions": [ + { + "name": "vrs_ref_allele_seq", + "type": "Extension", + "value": "E" + } + ], + "expressions": [ + { + "value": "NP_000537.3:p.Glu11Gln", + "syntax": "hgvs.p" + } + ] +} \ No newline at end of file diff --git a/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md b/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md new file mode 100644 index 00000000..af4ca9ce --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md @@ -0,0 +1,80 @@ +--- +title: "Linking the same variant across multiple assays" +slug: mavedb-vrs-cross-score-set-harmonization +summary: "Assigning a VRS digest to every MAVE variant allows the same change measured in independent experiments to be linked together, annotated once, and connected to the wider variant ecosystem." +products: + - name: VRS + version: "2.0" +pattern: cross-source-variant-harmonization +implementer: MaveDB +status: pilot +contributors: + - bencap + - afrubin + - MaveDB team +last_updated: 2026-08-03 +--- + +# Linking the same variant across multiple assays + +Some of the most interesting variants in MaveDB are the ones that were measured more than once. +Different labs may test the same genetic change with different assays, but due to technical differences in assay design it can be challenging to identify these cases. +MaveDB now recognizes when independent experiments describe the same change and ties their results together automatically, so the variant can be identified and annotated as a single entity instead of as multiple disconnected records. +The same mechanism gives MaveDB a foundation for connecting its variants to the broader genomics ecosystem. + +- **Who:** MaveDB +- **GKS products used:** VRS 2.0 +- **Tools:** [`vrs-python`](https://github.com/ga4gh/vrs-python) (v2.0.0-a6), MaveDB allele store (`vrs_digest` unique constraint) +- **Status:** pilot — VRS-digest deduplication is built into MaveDB's allele model and populated as score sets are mapped onto it; cutover and outward digest-based linking are in progress + +## Motivation + +TP53 is one of the most well-studied genes in MaveDB. +More than a dozen score sets, from at least six independent experiments, have measured its variants using diverse methods including deep mutational scanning, yeast functional complementation, and base-editing tiling screens. +Each research study used its own **target sequence** for TP53, and because a [content-addressed VRS identity](../mavedb-mave-variants-vrs/vignette.md) is derived from the exact sequence and position, the same protein change looks different in each submission. + +Consider the substitution **TP53:p.Glu11Gln**. +Three independent score sets each submitted it against a *different* target sequence, each with its own distinct refget accession (`SQ.JtEW…`, `SQ.KAxM…`, `SQ.jqmY…`). +When MaveDB's mapping pipeline normalizes each one to a standard reference, all three resolve to a single post-mapped VRS allele based on a [MANE Select](https://www.ncbi.nlm.nih.gov/refseq/MANE/) transcript: `ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ` (`NP_000537.3:p.Glu11Gln`). + +That shared digest (`ga4gh:VA.SnOz...`) is the harmonization key. +MaveDB's allele model enforces a **uniqueness constraint on the VRS digest**, so a change measured in five score sets occupies one allele record, not five. +Annotation work (e.g., mapping, classification, evidence assignment) happens against that single record and is shared by every score set that observed the variant. +This deduplication is built into the allele model MaveDB is adopting. + +The same digest is also MaveDB's intended path *outward*. +Today MaveDB reaches external resources (e.g., gnomAD, ClinVar, VEP) through the **ClinGen Allele ID** registered for each variant ([`PA215796`](https://mavedb.org/variants/PA215796) for this change). +This works, but it depends on registering every allele with an external registry. +However, because a VRS digest is computed deterministically from sequence and position, any resource that adopts VRS arrives at the identical identifier for the same change with no registry or pre-registration step. +Moving forward, we intend to move cross-resource matching onto the VRS digest and keep the registered ClinGen IDs as an independent cross-check. + +## Example data + +The same change, **TP53:p.Glu11Gln** was submitted as part of three independent score sets each using a different target sequence. +Using VRS, we can normalize these all to the same digest. + +| Score set | Submitted against (target `refgetAccession`) | Normalizes to | +|---|---|---| +| [`urn:mavedb:00000068-0-1`](https://mavedb.org/score-sets/urn:mavedb:00000068-0-1) | `SQ.JtEWOMSBOOCAxy6RBZNVl9NAKRb4t2iw` | `ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ` | +| [`urn:mavedb:00001234-a-1`](https://mavedb.org/score-sets/urn:mavedb:00001234-a-1) | `SQ.KAxM06sYzBF6zFftFaYq9E_18wsnn7al` | `ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ` | +| [`urn:mavedb:00001235-a-1`](https://mavedb.org/score-sets/urn:mavedb:00001235-a-1) | `SQ.jqmYcMMyIzEg4ZL0tSxF0nakvvGUJ-r6` | `ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ` | + +This single post-mapped VRS allele is annotated by MaveDB once: + +???+ example "Post-mapped VRS Allele — TP53:p.Glu11Gln" + ```json + --8<-- "docs/vignettes/mavedb-vrs-cross-score-set-harmonization/payloads/tp53-glu11gln.postmapped.vrs.json" + ``` + +## Tools + +- [**`vrs-python`**](https://github.com/ga4gh/vrs-python) (v2.0.0-a6) — computes the deterministic, content-addressed digest that serves as the harmonization key +- **MaveDB allele store** — applies a uniqueness constraint on the VRS digest that guarantees one record per distinct variant, across all score sets +- [**MaveDB API**](https://api.mavedb.org/docs) — resolves each variant to its shared allele record and serves the annotations attached to it + +## Reusing this pattern + +- [VRS 2.0 specification](https://vrs.ga4gh.org/) — how content-addressed identifiers enable registry-free matching +- Foundational vignette: [Giving every MAVE variant a precise, computable identity with VRS](../mavedb-mave-variants-vrs/vignette.md) — where these digests come from +- MaveDB API source: [VariantEffect/mavedb-api](https://github.com/VariantEffect/mavedb-api) — the allele model and digest-uniqueness constraint behind this harmonization +- Related implementer: [BRCA Exchange](https://brcaexchange.org/) uses VRS digests for the same cross-source harmonization goal diff --git a/docs-gks-vignettes/mkdocs.yml b/docs-gks-vignettes/mkdocs.yml new file mode 100644 index 00000000..e142c40b --- /dev/null +++ b/docs-gks-vignettes/mkdocs.yml @@ -0,0 +1,54 @@ +site_name: MaveDB × GA4GH GKS Vignettes +site_description: Real-world walk-throughs of how MaveDB uses the GA4GH Genomic Knowledge Standards (VRS, Cat-VRS, VA-Spec) + +# Standalone internal preview of the GKS Starter Kit vignettes MaveDB plans to +# contribute upstream. Mirrors the starter-kit's snippet config (base_path ["."], +# check_paths) so `docs/vignettes//` exports cleanly into ga4gh/gks-starter-kit. + +theme: + name: material + features: + - navigation.sections + - navigation.expand + - content.code.copy + palette: + - scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: deep purple + accent: deep purple + toggle: + icon: material/brightness-4 + name: Switch to light mode + +use_directory_urls: false + +plugins: + - search + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.superfences + - tables + - toc: + permalink: true + - pymdownx.snippets: + base_path: ["."] + check_paths: true + +nav: + - Home: index.md + - Vignettes: + - "Precise VRS identity (VRS)": vignettes/mavedb-mave-variants-vrs/vignette.md + - "Annotate once across score sets (VRS)": vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md + - "Variant as a category (Cat-VRS)": vignettes/mavedb-protein-variant-cat-vrs/vignette.md + - "Functional evidence (VA-Spec)": vignettes/mavedb-functional-evidence-va-spec/vignette.md + +strict: true diff --git a/docs-gks-vignettes/requirements.txt b/docs-gks-vignettes/requirements.txt new file mode 100644 index 00000000..74a24aef --- /dev/null +++ b/docs-gks-vignettes/requirements.txt @@ -0,0 +1 @@ +mkdocs-material==9.7.3 diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 8a915e01..1159c4ca 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -20,4 +20,15 @@ echo "Copying docs to $DEST..." rm -rf "$DEST" cp -r "$REPO_ROOT/docs/site" "$DEST" -echo "Done. Documentation will be served at /docs/mavedb/." +# --- GA4GH GKS vignettes (standalone preview site, served at /docs/gks-vignettes/) --- +# Built from its own dir so its `base_path: ["."]` snippet config resolves the +# starter-kit-style includes; same toolchain (mkdocs-material) as the main docs. +GKS_DIR="$REPO_ROOT/docs-gks-vignettes" +GKS_DEST="$REPO_ROOT/public/docs/gks-vignettes" +echo "Building GKS vignettes documentation..." +( cd "$GKS_DIR" && mkdocs build ) +echo "Copying GKS vignettes to $GKS_DEST..." +rm -rf "$GKS_DEST" +cp -r "$GKS_DIR/site" "$GKS_DEST" + +echo "Done. Documentation will be served at /docs/mavedb/ and /docs/gks-vignettes/."