From 613a5d6ba620cdd65c6d7dbea902bc94a6facbc7 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Mon, 29 Jun 2026 11:39:23 -0700 Subject: [PATCH 01/12] 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/." From 06d4500a3d0e06ae6a6ba932a0f1218f561aedb4 Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Tue, 14 Jul 2026 18:35:14 +1000 Subject: [PATCH 02/12] edits for main docs page --- docs-gks-vignettes/docs/index.md | 12 ++++++------ .../mavedb-protein-variant-cat-vrs/vignette.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs-gks-vignettes/docs/index.md b/docs-gks-vignettes/docs/index.md index 6db08142..98a7e8e8 100644 --- a/docs-gks-vignettes/docs/index.md +++ b/docs-gks-vignettes/docs/index.md @@ -1,14 +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 pages contain eal-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 is a real implementation — the problem, the data, the tools, and what GKS unlocks — written to be forwardable to a teammate or to leadership. +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 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)* +- [**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 thread one connected story: the same variants flow from VRS identity, through harmonization and categorization, into VA-Spec evidence. +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-protein-variant-cat-vrs/vignette.md b/docs-gks-vignettes/docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md index 1f20510b..03d7fc58 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: "Carrying a measured variant across every molecular level with Cat-VRS" +title: "Carrying a measured variant across molecular levels 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: From ec5a91baff1607569bf3f383ee0e410c5d0a9ac1 Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Tue, 14 Jul 2026 18:35:34 +1000 Subject: [PATCH 03/12] edits for harmonization --- .../vignette.md | 72 ++++++++++--------- 1 file changed, 40 insertions(+), 32 deletions(-) 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 index 730a2c59..5f9d87be 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: "Annotating a variant once, across every score set that measured it" +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: @@ -10,38 +10,48 @@ implementer: MaveDB status: pilot contributors: - bencap + - afrubin - MaveDB team -last_updated: 2026-06-29 +last_updated: 2026-07-14 --- -# Annotating a variant once, across every score set that measured it +# 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** +Some of the most interesting variants in MaveDB are the ones that were measured more than once. +Different labs, using different experiments, often test the same genetic change, but due to technical differences in assay design it was 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) (`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 - ---- +- **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 -## The story +## Motivation -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. +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 — 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`). +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 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. +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 — 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 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. -## The data +## Example 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: +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 | |---|---|---| @@ -49,24 +59,22 @@ The same change, **TP53 p.Glu11Gln**, submitted by three independent score sets | [`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: +This single post-mapped VRS allele is annotated by MaveDB once: -???+ example "Post-mapped VRS Allele — TP53 p.Glu11Gln" +???+ 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. +## Tools -## How to reuse this pattern +- [**`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 -- [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. +## 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 From 717149a2503d3abe45970176c4b59856f8b43e98 Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Thu, 16 Jul 2026 16:58:35 +1000 Subject: [PATCH 04/12] update title --- .../mavedb-vrs-cross-score-set-harmonization/vignette.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 index 5f9d87be..a493d14e 100644 --- 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 @@ -1,7 +1,7 @@ --- -title: "Annotating a variant once across every score set that measured it" +title: "Linking the same variant across multiple assays" 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." +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" @@ -12,10 +12,10 @@ contributors: - bencap - afrubin - MaveDB team -last_updated: 2026-07-14 +last_updated: 2026-07-15 --- -# Annotating a variant once across every score set that measured it +# 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, using different experiments, often test the same genetic change, but due to technical differences in assay design it was challenging to identify these cases. From 5193f45e7b8642654e12d01a4ebc0d772a0fde5d Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Thu, 16 Jul 2026 16:58:52 +1000 Subject: [PATCH 05/12] refactor base VRS vignette to include non-mapped use case --- .../mavedb-mave-variants-vrs/vignette.md | 60 +++++++++++-------- 1 file changed, 35 insertions(+), 25 deletions(-) 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 index 33c68d06..3442b2be 100644 --- a/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md @@ -1,7 +1,7 @@ --- 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." +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" @@ -10,59 +10,69 @@ implementer: MaveDB status: production contributors: - bencap + - afrubin - MaveDB team -last_updated: 2026-06-29 +last_updated: 2026-07-15 --- # 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** +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) (`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) +- **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 -## The story +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. -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 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. -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. +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 storing both alleles alongside, we preserve the provenance of the original assays's target sequence, while also providing the reference-based object that is more useful for downstream data integration and matching tasks. -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. +VRS representations are fundamental for the implementation of MaveDB's modern backend. This is how variants are stored precisely, how they are searched, and what every downstream annotation relies on. -## The data +## Example 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: +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" +???+ 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 +## 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) (`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. +- [**`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. -## How to reuse this pattern +## 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: [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. +- 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. --- From fed0e233d2e096766624b214b2793b9c292500b0 Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Mon, 3 Aug 2026 16:19:45 +1200 Subject: [PATCH 06/12] light edits --- .../docs/vignettes/mavedb-mave-variants-vrs/vignette.md | 7 ++++--- .../mavedb-vrs-cross-score-set-harmonization/vignette.md | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) 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 index 3442b2be..91944f1d 100644 --- a/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md @@ -12,7 +12,7 @@ contributors: - bencap - afrubin - MaveDB team -last_updated: 2026-07-15 +last_updated: 2026-08-03 --- # Giving every MAVE variant a precise, computable identity with VRS @@ -43,9 +43,10 @@ VRS is also easily able to represent both nucleotide and amino acid level varian 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 storing both alleles alongside, we preserve the provenance of the original assays's target sequence, while also providing the reference-based object that is more useful for downstream data integration and matching tasks. +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 fundamental for the implementation of MaveDB's modern backend. This is how variants are stored precisely, how they are searched, and what every downstream annotation relies on. +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 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 index a493d14e..af4ca9ce 100644 --- 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 @@ -12,13 +12,13 @@ contributors: - bencap - afrubin - MaveDB team -last_updated: 2026-07-15 +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, using different experiments, often test the same genetic change, but due to technical differences in assay design it was challenging to identify these cases. +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. From dde8d6fe4e494b21108fea4e9018eedd4f93947c Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Mon, 3 Aug 2026 17:29:34 +1200 Subject: [PATCH 07/12] edits for Cat-VRS --- .../vignette.md | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) 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 index 03d7fc58..8c9425ed 100644 --- 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 @@ -1,7 +1,7 @@ --- title: "Carrying a measured variant across molecular levels 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." +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" @@ -11,53 +11,59 @@ status: proposal contributors: - bencap - MaveDB team -last_updated: 2026-06-29 +last_updated: 2026-08-03 --- -# Carrying a measured variant across every molecular level with Cat-VRS +# Carrying a measured variant across molecular levels 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** +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 ---- - -## The story +## Motivation -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. +Consider 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 (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. +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 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 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. -## The data +## Example 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: +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" ``` -## The tools used +## 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. -## How to reuse this pattern +## 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. - ---- From db003ca40025e1a7c6639d2b875346311c23d5b1 Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Thu, 6 Aug 2026 16:13:34 +1000 Subject: [PATCH 08/12] tidy trailing formatting --- .../docs/vignettes/mavedb-mave-variants-vrs/vignette.md | 2 -- 1 file changed, 2 deletions(-) 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 index 91944f1d..ed1e79a8 100644 --- a/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md +++ b/docs-gks-vignettes/docs/vignettes/mavedb-mave-variants-vrs/vignette.md @@ -75,5 +75,3 @@ The `location` points into a standard protein reference (`NP_003336.1`, addresse - 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. - ---- From ebff3a4087cfa1b4810125dbc1ab84f4f972037c Mon Sep 17 00:00:00 2001 From: Alan Rubin Date: Thu, 6 Aug 2026 16:13:46 +1000 Subject: [PATCH 09/12] major edits for VA-Spec --- .../vignette.md | 72 +++++++++++-------- 1 file changed, 41 insertions(+), 31 deletions(-) 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 index bb9d8dda..3bdba15a 100644 --- 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 @@ -1,5 +1,5 @@ --- -title: "Sharing MAVE functional evidence as computable statements with VA-Spec" +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: @@ -11,64 +11,74 @@ status: production contributors: - bencap - MaveDB team -last_updated: 2026-06-29 +last_updated: 2026-08-06 --- -# Sharing MAVE functional evidence as computable statements with VA-Spec +# Sharing computable functional evidence 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** +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, building on VRS 2.0 variants +- **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 ---- - -## The story +## Motivation -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. +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 expresses this using the GA4GH **Variant Annotation Specification (VA-Spec)**, as a stack of three statement types at rising altitudes. +MaveDB represents this using the GA4GH **Variant Annotation Specification (VA-Spec)**, implemented as a stack of three statement types at increasing levels. -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. +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. -*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. +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. -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. +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 representing 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. -## The data +## Example 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: +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 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: +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" ``` -## The tools used +## 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 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. +- [**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. -## How to reuse this pattern +## Reusing 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. +- [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. -- 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. - ---- From 36e7e24721f2893b78d082e4b9d4e585d0422f47 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Thu, 6 Aug 2026 12:30:32 -0700 Subject: [PATCH 10/12] =?UTF-8?q?fix=20typo=20in=20introduction=20of=20Mav?= =?UTF-8?q?eDB=20=C3=97=20GA4GH=20GKS=20Vignettes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs-gks-vignettes/docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-gks-vignettes/docs/index.md b/docs-gks-vignettes/docs/index.md index 98a7e8e8..ebd206b6 100644 --- a/docs-gks-vignettes/docs/index.md +++ b/docs-gks-vignettes/docs/index.md @@ -1,6 +1,6 @@ # MaveDB × GA4GH GKS Vignettes -These pages contain eal-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 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. From 7e12e2636f4d00c21f3a928c6015500caeff40a5 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Thu, 6 Aug 2026 12:30:56 -0700 Subject: [PATCH 11/12] fix grammar in motivation section of Cat-VRS vignette --- .../docs/vignettes/mavedb-protein-variant-cat-vrs/vignette.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 8c9425ed..ef8e924f 100644 --- 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 @@ -29,7 +29,7 @@ Therefore a downstream data consumer can apply variant data at the level they ne ## Motivation -Consider deep mutational scan that reports a score for the protein change UBE2I p.Leu6Gly. +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. From 893e3e034e16dbe7fecaf1caa641410ebecc5fb5 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Thu, 6 Aug 2026 13:04:29 -0700 Subject: [PATCH 12/12] fix typo in VA-Spec vignette --- .../vignettes/mavedb-functional-evidence-va-spec/vignette.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 3bdba15a..1f57bfec 100644 --- 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 @@ -47,7 +47,7 @@ The associated information about these functional classifications, such as score 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 representing using another `Statement` object with an associated `VariantPathogenicityProposition`. +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.