From 613a5d6ba620cdd65c6d7dbea902bc94a6facbc7 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Mon, 29 Jun 2026 11:39:23 -0700 Subject: [PATCH] docs(gks-vignettes): add GA4GH GKS Starter Kit vignettes doc tree - Four vignettes covering VRS identity, cross-score-set harmonization, Cat-VRS categorization, and VA-Spec functional evidence sharing - Standalone MkDocs site under ui/docs-gks-vignettes/ for internal preview before upstream contribution to ga4gh/gks-starter-kit - use_directory_urls: false to match main docs and fix static serving - JSON payload blocks wrapped in collapsible details admonitions; large VA-Spec pathogenicity statement collapsed by default, smaller payloads expanded --- .gitignore | 1 + docs-gks-vignettes/.gitignore | 2 + docs-gks-vignettes/docs/index.md | 14 + .../gck-pathogenicity-statement.va.json | 1333 +++++++++++++++++ .../ube2i-leu6gly.study-result.va.json | 143 ++ .../vignette.md | 74 + .../payloads/ube2i-leu6gly.vrs.json | 34 + .../mavedb-mave-variants-vrs/vignette.md | 68 + .../ube2i-leu6gly.proposed.cat-vrs.json | 76 + .../vignette.md | 63 + .../tp53-glu11gln.postmapped.vrs.json | 34 + .../vignette.md | 72 + docs-gks-vignettes/mkdocs.yml | 54 + docs-gks-vignettes/requirements.txt | 1 + scripts/build-docs.sh | 13 +- 15 files changed, 1981 insertions(+), 1 deletion(-) create mode 100644 docs-gks-vignettes/.gitignore create mode 100644 docs-gks-vignettes/docs/index.md create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/payloads/ube2i-leu6gly.study-result.va.json create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/vignette.md create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/payloads/ube2i-leu6gly.vrs.json create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/payloads/tp53-glu11gln.postmapped.vrs.json create mode 100644 docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md create mode 100644 docs-gks-vignettes/mkdocs.yml create mode 100644 docs-gks-vignettes/requirements.txt 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..6db08142 --- /dev/null +++ b/docs-gks-vignettes/docs/index.md @@ -0,0 +1,14 @@ +# MaveDB × GA4GH GKS Vignettes + +Real-world walk-throughs of how **MaveDB** uses the GA4GH **Genomic Knowledge Standards** to solve core problems in sharing multiplexed assay of variant effect (MAVE) 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 is a real implementation — the problem, the data, the tools, and what GKS unlocks — written to be forwardable 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 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 every molecular level with Cat-VRS**](vignettes/mavedb-protein-variant-cat-vrs/vignette.md) — a measured variant as a category over its equivalents. *(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 thread one connected story: the same variants flow from VRS identity, through harmonization and categorization, 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..bb9d8dda --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-functional-evidence-va-spec/vignette.md @@ -0,0 +1,74 @@ +--- +title: "Sharing MAVE functional evidence as computable statements 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-06-29 +--- + +# Sharing MAVE functional evidence as computable statements with VA-Spec + +**Why this matters** + +Multiplexed assays measure how genetic variants behave in the lab, and those measurements are some of the strongest evidence available for deciding whether a variant is pathogenic. But that evidence has historically lived as spreadsheets of numbers that a human had to find, interpret, and transcribe before it could inform a clinical assessment. MaveDB now publishes each measurement as a structured statement that records the score, what was measured, how, by whom, and where it came from — in a shared format that variant-interpretation systems can read automatically. Experimental evidence becomes something software can pick up and use, with its full provenance attached. + +**At a glance** + +- **Who:** MaveDB +- **GKS products used:** VA-Spec 0.4, building on VRS 2.0 variants +- **Tools:** [ga4gh-va-spec](https://github.com/ga4gh/va-spec-python) (`ga4gh-va-spec` ~0.4.2), MaveDB annotation pipeline +- **Status:** production + +--- + +## The story + +A multiplexed assay of variant effect produces a functional score for each variant — a number summarizing how the variant behaved in the experiment. On its own, a score is hard to reuse: a downstream consumer needs to know which variant it refers to (precisely), what the number means, how it was generated, and whether its provenance is trustworthy enough to act on. + +MaveDB expresses this using the GA4GH **Variant Annotation Specification (VA-Spec)**, as a stack of three statement types at rising altitudes. + +At the base is the `ExperimentalVariantFunctionalImpactStudyResult` — the raw measurement. Its `focusVariant` is the variant's [VRS allele](../mavedb-mave-variants-vrs/vignette.md), anchoring the evidence to a precise, content-addressed identity rather than a free-text label, and `functionalImpactScore` carries the measured value. Around that it records structured **provenance**: a `contributions` chain naming the MaveDB API and VRS-mapping software (with versions), the original submitter (by ORCID), and the relevant dates; a `sourceDataSet` describing the score set, its publication, and its license; and `reportedIn` links back to the live MaveDB records. MaveDB emits one for every mappable variant in every published score set. + +*Calibration* is what turns a raw score into evidence: using reference variants of known effect, it sets the score thresholds — and the ACMG evidence strength (*supporting*, *moderate*, *strong*) — at which the assay's scores support a normal or abnormal functional call. Where a score set has been calibrated, MaveDB raises its raw results into a per-assay **functional-impact `Statement`** — the assay's normal/abnormal call. It aggregates the assay's calibrations into a single functional classification (for example `abnormal` or `normal`) rooted in the study result beneath it: the assay saying what its numbers *mean*, not just what they were. + +At the top sits a variant-level **pathogenicity `Statement`**, the only layer that aggregates *across assays*. It carries one evidence line per assay that measured the variant — each wrapping that assay's functional-impact statement, scored against an ACMG criterion such as PS3 — and integrates them into an ACMG-style classification. Crucially, it integrates MaveDB's **functional evidence only**: it is the functional *contribution* to a classification, not a standalone clinical verdict, which also requires population, segregation, and computational evidence that a downstream knowledgebase supplies. The layers nest — a pathogenicity statement contains its functional statements, which contain their study results — so a single object can carry the conclusion together with the full evidentiary chain beneath it. Because the evidence is structured and VRS-anchored at every level, a variant-interpretation pipeline can ingest any of these layers directly. + +## The data + +Two real exports, at opposite ends of the stack. + +The base unit — 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 exactly 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 apex — the full, real 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)). It is classified `pathogenic` and aggregates **two assays'** evidence lines, each an *ACMG 2015 PS3 Criterion Met* at `moderate` strength, each wrapping an `abnormal` functional-impact statement rooted in its own study result — the entire evidentiary stack in one object. Note the proposition's condition: MedGen `C0012634`, the generic *"Disease"* concept. MaveDB currently calibrates its functional scores against this single generic disease condition rather than any gene-specific disorder, so the classification expresses functional impact toward disease in general, not a specific clinical diagnosis: + +??? example "Pathogenicity Statement — GCK variant (1,332 lines)" + ```json + --8<-- "docs/vignettes/mavedb-functional-evidence-va-spec/payloads/gck-pathogenicity-statement.va.json" + ``` + +## The tools used + +- [**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 populates across all three altitudes. +- [**MaveDB API**](https://api.mavedb.org/docs) — generates and serves these VA-Spec annotations (the `MaveDB API` agent stamped into each statement's `contributions`) alongside the underlying score-set data. + +## How to reuse this pattern + +- [VA-Spec specification](https://va-ga4gh.readthedocs.io/) — the statement and study-result model. +- Foundational vignette: [Giving every MAVE variant a precise, computable identity with VRS](../mavedb-mave-variants-vrs/vignette.md) — the `focusVariant` these statements point at. +- MaveDB API source: [VariantEffect/mavedb-api](https://github.com/VariantEffect/mavedb-api) — where these VA-Spec statements are assembled and served. +- Related vignette: [Annotating a variant once, across every score set](../mavedb-vrs-cross-score-set-harmonization/vignette.md) — why one variant's evidence can draw on many experiments. + +--- 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..33c68d06 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md @@ -0,0 +1,68 @@ +--- +title: "Giving every MAVE variant a precise, computable identity with VRS" +slug: mavedb-mave-variants-vrs +summary: "MaveDB maps every variant from every multiplexed assay into VRS 2.0, turning lab-specific notation into one canonical, content-addressed identifier." +products: + - name: VRS + version: "2.0" +pattern: variant-annotation +implementer: MaveDB +status: production +contributors: + - bencap + - MaveDB team +last_updated: 2026-06-29 +--- + +# Giving every MAVE variant a precise, computable identity with VRS + +**Why this matters** + +MaveDB collects the results of multiplexed assays of variant effect — experiments that measure the functional impact of thousands of genetic variants at once. Every contributing lab describes its variants differently: against its own engineered target sequence, at the protein level or the DNA level, in whatever notation suited the experiment. That made it hard to know when two records described the same change, or to connect a measured variant to anything outside the original study. MaveDB now maps every variant it stores into a single shared standard, so each one carries a precise, computable identity that any other system can recognize without having to understand how the original experiment was written down. + +**At a glance** + +- **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) (`ga4gh.vrs` 2.0.0-a6), [cool-seq-tool](https://github.com/GenomicMedLab/cool-seq-tool) 0.4.0.dev3, [cdot](https://github.com/SACGF/cdot), [seqrepo](https://github.com/biocommons/biocommons.seqrepo) +- **Status:** production + +--- + +## The story + +A multiplexed assay reports variants in the terms of its own experiment. A deep mutational scan of a protein names amino-acid changes against an engineered target; a saturation genome editing screen names nucleotide changes against a genomic window. The same biological change can therefore arrive in MaveDB in several notations, on several reference sequences, depending on who ran the assay. Stored as raw strings, those records can't be compared, searched precisely, or linked to the wider variant ecosystem. + +MaveDB resolves this by mapping every variant into the GA4GH **Variant Representation Specification (VRS) 2.0**. 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. VRS then computes a **content-addressed digest** — a hash derived deterministically from the variant's location and state — and uses it as the allele's identifier (`ga4gh:VA.…`). Two records that describe the same change normalize to the same digest, no matter how the original experiments phrased them. + +MaveDB keeps both a **pre-mapped** allele (on the assay's own target sequence, preserving exactly what was measured) and a **post-mapped** allele (on a standard human reference), so nothing about the original experiment is lost while everything gains a shared identity. This VRS representation is the substrate for the rest of MaveDB's modern backend: it is how variants are stored precisely, how they are searched, and what every downstream annotation hangs off of. + +## The data + +A real post-mapped VRS 2.0 Allele for the UBE2I variant [p.Leu6Gly](https://mavedb.org/variants/PA2579755325), from the deep mutational scan in score set [`urn:mavedb:00000001-a-1`](https://mavedb.org/score-sets/urn:mavedb:00000001-a-1) (Weile et al., 2017). The `id`/`digest` are computed from the location and state — the same change would produce the same digest from any source: + +???+ 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. + +## The tools used + +- [**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) (`ga4gh.vrs` 2.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) 0.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. + +## How to reuse 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: [Annotating a variant once, across every score set](../mavedb-vrs-cross-score-set-harmonization/vignette.md) — what the shared VRS digest unlocks. +- Related vignette: [Representing a scored protein variant as a category of changes](../mavedb-protein-variant-cat-vrs/vignette.md) — Cat-VRS over these alleles. +- Related vignette: [Sharing MAVE functional evidence with VA-Spec](../mavedb-functional-evidence-va-spec/vignette.md) — the evidence built on 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..1f20510b --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md @@ -0,0 +1,63 @@ +--- +title: "Carrying a measured variant across every molecular level with Cat-VRS" +slug: mavedb-protein-variant-cat-vrs +summary: "A multiplexed assay measures a variant at one molecular level, but consumers need it at others. MaveDB plans to use Cat-VRS to present each measured variant as a category spanning all equivalent changes — without losing which level was measured." +products: + - name: Cat-VRS + version: "1.0" +pattern: variant-categorization +implementer: MaveDB +status: proposal +contributors: + - bencap + - MaveDB team +last_updated: 2026-06-29 +--- + +# Carrying a measured variant across every molecular level with Cat-VRS + +**Why this matters** + +A multiplexed assay measures a variant at a single molecular level — often the protein, sometimes the DNA. But the same change exists at every level, and whoever uses the result may need a different one: a clinical pipeline works from DNA coordinates, while a protein modeller wants the amino-acid change. The catch is that one protein change can be produced by several different DNA changes, so moving between levels is not a simple relabel. MaveDB plans to present each measured variant as an explicit category that spans all of its equivalent forms across levels — while always recording which level was actually measured, so a consumer can reason at the level they need without losing the provenance of the original measurement. + +**At a glance** + +- **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 + +--- + +## The story + +Take a deep mutational scan that reports a score for the protein change UBE2I p.Leu6Gly. The score was measured at the protein level, but the genetic code is degenerate: that one amino-acid change can be encoded by more than one codon and reached from the reference by more than one DNA change. The assay did not distinguish between them — it measured the protein outcome. Storing the result as a single DNA allele would assert more than the experiment showed; storing it only as a protein allele leaves it disconnected from the DNA coordinates downstream tools and clinical workflows depend on. 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. + +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 (reverse translation — the genuinely hard direction, because it is one-to-many); for a DNA measurement it derives the protein consequence and the synonymous equivalents. Each equivalent 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 equivalents 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 the assay actually scored, so the measurement's provenance is explicit — and whose **members** are the equivalent VRS alleles at the other levels. The categorical variant says precisely what was measured while making every equivalent change explicit and machine-resolvable, letting a consumer attach or read the score at whatever level they work in. This is the unit of molecular representation MaveDB plans to expose, rather than a bare allele, while the underlying storage stays as the deduplicated, level-tagged alleles it is assembled from. + +## The data + +A **proposed** Cat-VRS `CategoricalVariant` for the measured variant UBE2I [p.Leu6Gly](https://mavedb.org/variants/PA2579755325). The defining constraint holds the *real* MaveDB post-mapped protein allele (`ga4gh:VA.P39KFBT8…`) and an extension records that protein was the measured level; the `members` are illustrative — they show the shape of the coding and genomic equivalents MaveDB computes, whose concrete coordinates and digests the pipeline fills in: + +???+ example "Proposed CategoricalVariant — UBE2I p.Leu6Gly" + ```json + --8<-- "docs/vignettes/mavedb-protein-variant-cat-vrs/payloads/ube2i-leu6gly.proposed.cat-vrs.json" + ``` + +## The tools used + +- [**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. + +## How to reuse 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..730a2c59 --- /dev/null +++ b/docs-gks-vignettes/docs/vignettes/mavedb-vrs-cross-score-set-harmonization/vignette.md @@ -0,0 +1,72 @@ +--- +title: "Annotating a variant once, across every score set that measured it" +slug: mavedb-vrs-cross-score-set-harmonization +summary: "Because every MAVE variant carries a VRS digest, the same change measured in independent experiments collapses to one record — annotated once, with a built-in path to link out to the wider variant ecosystem." +products: + - name: VRS + version: "2.0" +pattern: cross-source-variant-harmonization +implementer: MaveDB +status: pilot +contributors: + - bencap + - MaveDB team +last_updated: 2026-06-29 +--- + +# Annotating a variant once, across every score set that measured it + +**Why this matters** + +The most valuable variants in MaveDB are the ones that were measured more than once. Different labs, using different experiments, often test the same genetic change — and historically each measurement sat in its own silo, described in its own terms, with no automatic way to tell that they were about the same thing. MaveDB now recognizes when independent experiments describe the same change and ties their results together automatically, so the variant is curated, annotated, and looked up as a single entity instead of a scatter of disconnected records. The same mechanism gives MaveDB a foundation for connecting its variants to the broader genomics ecosystem. + +**At a glance** + +- **Who:** MaveDB +- **GKS products used:** VRS 2.0 +- **Tools:** [vrs-python](https://github.com/ga4gh/vrs-python) (`ga4gh.vrs` 2.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; the serving cutover and outward digest-based linking are in progress + +--- + +## The story + +TP53 is one of the most-studied genes in MaveDB: more than a dozen score sets, from at least six independent experiments, have measured its variants using assays as different as deep mutational scanning, yeast functional complementation, and base-editing tiling screens. Each of those groups deposited 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 starts life looking different in each submission. + +Consider the substitution **TP53 p.Glu11Gln**. Three independent score sets each submitted it against a *different* target sequence — three distinct refget accessions (`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: `ga4gh:VA.SnOzGzPkL6_TKrM0h38YeaTJ1AEgp2MJ` (`NP_000537.3:p.Glu11Gln`). + +That shared digest 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 — mapping, classification, evidence — 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 migrating its serving onto. + +The same digest is also MaveDB's intended path *outward*. Today MaveDB reaches external resources — gnomAD, ClinVar, VEP — through the **ClinGen Allele ID** registered for each variant (e.g. [`PA215796`](https://mavedb.org/variants/PA215796) for this change); that works, but it depends on registering every allele with an external registry. 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 cross-resource matching onto the VRS digest — keeping the registered ClinGen IDs as an independent cross-check — is the forward-looking half of this pattern. + +## The data + +The same change, **TP53 p.Glu11Gln**, submitted by three independent score sets against three different target sequences — and the single post-mapped VRS allele all three normalize to: + +| 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` | + +The single post-mapped VRS allele that all three collapse to — the record MaveDB annotates 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" + ``` + +## The tools used + +- [**vrs-python**](https://github.com/ga4gh/vrs-python) (`ga4gh.vrs` 2.0.0-a6) — computes the deterministic, content-addressed digest that serves as the harmonization key. +- **MaveDB allele store** — a uniqueness constraint on the VRS digest 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. + +## How to reuse 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/."