From da75c62892552ea3e77454e4590ede6728210198 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Mon, 15 Jun 2026 16:49:21 -0700 Subject: [PATCH 1/3] docs(data-standards): clarify VA-Spec object type identification Both statement layers serialize with type "Statement"; document distinguishing them via proposition.type and correct the pathogenicity example to use the GA4GH schema values. Add a warning that the pathogenicity classification reflects MaveDB functional evidence only, not a complete clinical determination. --- docs/content/reference/data-standards.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/content/reference/data-standards.md b/docs/content/reference/data-standards.md index 869b7968..9879f9d5 100644 --- a/docs/content/reference/data-standards.md +++ b/docs/content/reference/data-standards.md @@ -76,6 +76,9 @@ graph LR Availability is determined per-variant. Functional Impact Study Results are available for any variant that has been successfully mapped (i.e., has post-mapped genomic coordinates). Functional Impact Statements and Variant Pathogenicity Statements additionally require [score calibrations](score-calibrations.md) on the score set and a non-null score value for the variant. +!!! note "Identifying object types" + The `type` field carries the GA4GH schema value, not MaveDB's class name. Both statement layers serialize with `"type": "Statement"` — distinguish them by `proposition.type`: `ExperimentalVariantFunctionalImpactProposition` for a Functional Impact Statement versus `VariantPathogenicityProposition` for a Variant Pathogenicity Statement. The pathogenicity statement's clinical evidence lines likewise serialize with `"type": "EvidenceLine"` (the object is a `VariantPathogenicityEvidenceLine`, but that string never appears in `type`). Study Results carry `"type": "ExperimentalVariantFunctionalImpactStudyResult"`. + ### Functional Impact Study Result A Functional Impact Study Result captures the raw output of a MAVE experiment for a single variant. It is the foundational VA-Spec object and does not require score calibrations. @@ -167,6 +170,9 @@ Each Functional Impact Statement contains: A Variant Pathogenicity Statement translates functional evidence into clinical terms by mapping functional classifications to [ACMG/AMP criteria](https://pubmed.ncbi.nlm.nih.gov/25741868/). This is the primary object MaveDB exports for integration into clinical variant interpretation workflows. +!!! warning "Functional evidence only — not a clinical determination" + The classification on a Variant Pathogenicity Statement reflects **MaveDB functional evidence only** — the strongest of the variant's eligible calibrations — and does not incorporate the non-functional ACMG criteria (population frequency, segregation, computational predictions) that a complete clinical determination requires. Treat it as the functional contribution (a calibrated PS3/BS3 line of evidence) to be integrated with other evidence downstream, not as a standalone clinical classification. + Each statement assigns an ACMG criterion and evidence strength: | ACMG criterion | Direction | Meaning | @@ -188,7 +194,7 @@ Each Variant Pathogenicity Statement contains: ```json { - "type": "VariantPathogenicityStatement", + "type": "Statement", "description": "Variant pathogenicity statement for urn:mavedb:00000050-a-1#12345.", "direction": "Supports", "proposition": { @@ -205,7 +211,7 @@ Each Variant Pathogenicity Statement contains: }, "hasEvidenceLines": [ { - "type": "VariantPathogenicityEvidenceLine", + "type": "EvidenceLine", "directionOfEvidenceProvided": "Supports", "strengthOfEvidenceProvided": { "primaryCoding": { From 26ecccfe007b49dee6af9554c085a1e9e6dd35f7 Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Tue, 16 Jun 2026 09:45:12 -0700 Subject: [PATCH 2/3] docs(data-standards): add per-variant VA-Spec layer table Add a heuristic table mapping a variant's state (mapped, scored, calibrated) to the highest VA-Spec layer it qualifies for, consolidating the per-variant availability rules previously only described in prose. Also document that a score falling outside every calibration range is annotated at the layer above as Indeterminate/Uncertain Significance with a Neutral direction, rather than demoted to a lower layer. --- docs/content/reference/data-standards.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/content/reference/data-standards.md b/docs/content/reference/data-standards.md index 9879f9d5..90a03c95 100644 --- a/docs/content/reference/data-standards.md +++ b/docs/content/reference/data-standards.md @@ -76,6 +76,18 @@ graph LR Availability is determined per-variant. Functional Impact Study Results are available for any variant that has been successfully mapped (i.e., has post-mapped genomic coordinates). Functional Impact Statements and Variant Pathogenicity Statements additionally require [score calibrations](score-calibrations.md) on the score set and a non-null score value for the variant. +The table below summarizes the **highest** layer a variant qualifies for. Higher layers nest the layers beneath them (a Study Result sits inside a Functional Impact Statement, which sits inside a Variant Pathogenicity Statement), so a variant that qualifies for a higher layer is also represented at every lower one. + +| Variant state | Highest VA-Spec layer | +|---|---| +| Not successfully mapped (no post-mapped genomic coordinates) | *None* — excluded from VRS and VA-Spec output | +| Mapped, but no score value | Functional Impact Study Result | +| Mapped and scored, but the score set has no eligible calibration | Functional Impact Study Result | +| Mapped and scored, with an eligible functional calibration | Functional Impact Statement | +| Mapped and scored, with an eligible calibration carrying [ACMG/AMP evidence strengths](score-calibrations.md) | Variant Pathogenicity Statement | + +"Eligible" excludes [research-use-only](score-calibrations.md) calibrations. A variant whose score falls outside every calibration range is still annotated at the layer above — its classification is `Indeterminate` (functional) or `Uncertain Significance` (pathogenicity) with a `Neutral` direction, rather than being demoted to a lower layer. + !!! note "Identifying object types" The `type` field carries the GA4GH schema value, not MaveDB's class name. Both statement layers serialize with `"type": "Statement"` — distinguish them by `proposition.type`: `ExperimentalVariantFunctionalImpactProposition` for a Functional Impact Statement versus `VariantPathogenicityProposition` for a Variant Pathogenicity Statement. The pathogenicity statement's clinical evidence lines likewise serialize with `"type": "EvidenceLine"` (the object is a `VariantPathogenicityEvidenceLine`, but that string never appears in `type`). Study Results carry `"type": "ExperimentalVariantFunctionalImpactStudyResult"`. From 747a9226245d511a7a69164e2793bc585d9a210a Mon Sep 17 00:00:00 2001 From: Benjamin Capodanno Date: Tue, 16 Jun 2026 11:33:29 -0700 Subject: [PATCH 3/3] docs(data-standards): use lowercase VA-Spec code values Align classification, direction, strength, and evidenceOutcome code values in the examples, prose, and tables with the lowercase form MaveDB actually emits (e.g. `pathogenic`, `abnormal`, `supports`), and note the convention so consumers do not match on the wrong casing. ACMG criterion codes such as `PS3` and `BS3_supporting` keep their conventional casing. --- docs/content/reference/data-standards.md | 48 ++++++++++++------------ 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/content/reference/data-standards.md b/docs/content/reference/data-standards.md index 90a03c95..58a447bd 100644 --- a/docs/content/reference/data-standards.md +++ b/docs/content/reference/data-standards.md @@ -86,11 +86,13 @@ The table below summarizes the **highest** layer a variant qualifies for. Higher | Mapped and scored, with an eligible functional calibration | Functional Impact Statement | | Mapped and scored, with an eligible calibration carrying [ACMG/AMP evidence strengths](score-calibrations.md) | Variant Pathogenicity Statement | -"Eligible" excludes [research-use-only](score-calibrations.md) calibrations. A variant whose score falls outside every calibration range is still annotated at the layer above — its classification is `Indeterminate` (functional) or `Uncertain Significance` (pathogenicity) with a `Neutral` direction, rather than being demoted to a lower layer. +"Eligible" excludes [research-use-only](score-calibrations.md) calibrations. A variant whose score falls outside every calibration range is still annotated at the layer above — its classification is `indeterminate` (functional) or `uncertain significance` (pathogenicity) with a `neutral` direction, rather than being demoted to a lower layer. !!! note "Identifying object types" The `type` field carries the GA4GH schema value, not MaveDB's class name. Both statement layers serialize with `"type": "Statement"` — distinguish them by `proposition.type`: `ExperimentalVariantFunctionalImpactProposition` for a Functional Impact Statement versus `VariantPathogenicityProposition` for a Variant Pathogenicity Statement. The pathogenicity statement's clinical evidence lines likewise serialize with `"type": "EvidenceLine"` (the object is a `VariantPathogenicityEvidenceLine`, but that string never appears in `type`). Study Results carry `"type": "ExperimentalVariantFunctionalImpactStudyResult"`. + Unlike the `type` field, `classification`, `direction`, and `evidenceOutcome` *code* values are lowercase — e.g. `pathogenic` / `benign` / `uncertain significance`, `normal` / `abnormal` / `indeterminate`, and `supports` / `disputes` / `neutral`. (ACMG criterion codes such as `PS3` / `BS3_supporting` keep their conventional casing.) + ### Functional Impact Study Result A Functional Impact Study Result captures the raw output of a MAVE experiment for a single variant. It is the foundational VA-Spec object and does not require score calibrations. @@ -129,14 +131,14 @@ Each Study Result contains: ### Functional Impact Statement -A Functional Impact Statement classifies a variant's functional impact as **Normal**, **Abnormal**, or **Indeterminate** based on where its score falls within the ranges defined by a [score calibration](score-calibrations.md). +A Functional Impact Statement classifies a variant's functional impact as `normal`, `abnormal`, or `indeterminate` based on where its score falls within the ranges defined by a [score calibration](score-calibrations.md). When multiple calibrations are available for a score set, MaveDB generates an evidence line for each eligible calibration — that is, each calibration that is not marked as [research-use-only](score-calibrations.md) — and selects the **strongest** calibration to determine the statement-level classification. All evidence lines are included in the exported object for transparency. Each Functional Impact Statement contains: -- A **classification** (`Normal`, `Abnormal`, or `Indeterminate`). -- A **direction of evidence** — `Supports` (abnormal function), `Disputes` (normal function), or `Neutral` (indeterminate) — aggregated across all evidence lines. +- A **classification** (`normal`, `abnormal`, or `indeterminate`). +- A **direction of evidence** — `supports` (abnormal function), `disputes` (normal function), or `neutral` (indeterminate) — aggregated across all evidence lines. - **Evidence lines**, one per eligible calibration, each referencing the underlying Functional Impact Study Result and the calibration that produced the classification. ??? example "Example Functional Impact Statement" @@ -145,7 +147,7 @@ Each Functional Impact Statement contains: { "type": "Statement", "description": "Variant functional impact statement for urn:mavedb:00000050-a-1#12345.", - "direction": "Supports", + "direction": "supports", "proposition": { "type": "ExperimentalVariantFunctionalImpactProposition", "predicate": "impactsFunctionOf", @@ -154,17 +156,17 @@ Each Functional Impact Statement contains: }, "classification": { "primaryCoding": { - "code": "Abnormal", + "code": "abnormal", "system": "ga4gh-gks-term:experimental-var-func-impact-classification" } }, "hasEvidenceLines": [ { "type": "EvidenceLine", - "directionOfEvidenceProvided": "Supports", + "directionOfEvidenceProvided": "supports", "evidenceOutcome": { "primaryCoding": { - "code": "Abnormal", + "code": "abnormal", "system": "ga4gh-gks-term:experimental-var-func-impact-classification" } }, @@ -192,13 +194,13 @@ Each statement assigns an ACMG criterion and evidence strength: | PS3 | Supports pathogenicity | Well-established functional study shows a damaging effect | | BS3 | Supports benignity | Well-established functional study shows no damaging effect | -The evidence strength (e.g., `Supporting`, `Moderate`, `Strong`, `Very Strong`) indicates the level of confidence in the classification, determined by the score calibration. +The evidence strength (e.g., `supporting`, `moderate`, `strong`, `very strong`) indicates the level of confidence in the classification, determined by the score calibration. -When multiple calibrations are eligible, MaveDB generates a clinical evidence line for each and selects the **strongest** to determine the statement-level classification. All evidence lines are included in the output. If calibrations provide conflicting evidence at equal strength (e.g., one supports pathogenicity while another supports benignity), the classification defaults to `Uncertain Significance`. +When multiple calibrations are eligible, MaveDB generates a clinical evidence line for each and selects the **strongest** to determine the statement-level classification. All evidence lines are included in the output. If calibrations provide conflicting evidence at equal strength (e.g., one supports pathogenicity while another supports benignity), the classification defaults to `uncertain significance`. Each Variant Pathogenicity Statement contains: -- A **classification** (`Pathogenic`, `Benign`, or `Uncertain Significance`). +- A **classification** (`pathogenic`, `benign`, or `uncertain significance`). - A **direction of evidence** aggregated across all clinical evidence lines. - **Clinical evidence lines**, each containing the ACMG criterion, evidence strength, and a nested Functional Impact Statement. @@ -208,7 +210,7 @@ Each Variant Pathogenicity Statement contains: { "type": "Statement", "description": "Variant pathogenicity statement for urn:mavedb:00000050-a-1#12345.", - "direction": "Supports", + "direction": "supports", "proposition": { "type": "VariantPathogenicityProposition", "predicate": "isCausalFor", @@ -217,22 +219,22 @@ Each Variant Pathogenicity Statement contains: }, "classification": { "primaryCoding": { - "code": "Pathogenic", + "code": "pathogenic", "system": "ACMG Guidelines, 2015" } }, "hasEvidenceLines": [ { "type": "EvidenceLine", - "directionOfEvidenceProvided": "Supports", + "directionOfEvidenceProvided": "supports", "strengthOfEvidenceProvided": { "primaryCoding": { - "code": "Strong" + "code": "strong" } }, "evidenceOutcome": { "primaryCoding": { - "code": "ps3_strong", + "code": "PS3", "system": "ACMG Guidelines, 2015" }, "name": "ACMG 2015 PS3 Criterion Met" @@ -256,13 +258,13 @@ This means a single Variant Pathogenicity Statement may contain multiple evidenc ### Evidence strength mapping -MaveDB's internal evidence strength scale includes a `Moderate+` level that sits between `Moderate` and `Strong`. Because the GA4GH VA-Spec standard does not include this level, MaveDB maps `Moderate+` to `Moderate` when generating Variant Pathogenicity Statements. This ensures compliance with the standard while preserving a conservative interpretation of evidence strength. +MaveDB's internal evidence strength scale includes a `Moderate+` level that sits between `Moderate` and `Strong`. Because the GA4GH VA-Spec standard does not include this level, MaveDB maps `Moderate+` to `moderate` when generating Variant Pathogenicity Statements. This ensures compliance with the standard while preserving a conservative interpretation of evidence strength. The full internal evidence strength scale, from weakest to strongest: : `Supporting` · `Moderate` · `Moderate+` · `Strong` · `Very Strong` -In VA-Spec output, `Moderate+` appears as `Moderate`. +In VA-Spec output, `Moderate+` appears as `moderate`. ### Direction of evidence @@ -270,14 +272,14 @@ VA-Spec uses a `direction` field to indicate whether evidence supports or disput | Functional classification | Direction | Rationale | |---|---|---| -| Normal | Disputes | Normal function argues against pathogenicity | -| Abnormal | Supports | Abnormal function argues for pathogenicity | -| Indeterminate | Neutral | Insufficient evidence to determine direction | +| `normal` | `disputes` | Normal function argues against pathogenicity | +| `abnormal` | `supports` | Abnormal function argues for pathogenicity | +| `indeterminate` | `neutral` | Insufficient evidence to determine direction | !!! tip - The default proposition being evaluated is that the variant **affects function** (for Functional Impact Statements) or **is pathogenic** (for Variant Pathogenicity Statements). This is why `Normal` function *disputes* the proposition while `Abnormal` function *supports* it. + The default proposition being evaluated is that the variant **affects function** (for Functional Impact Statements) or **is pathogenic** (for Variant Pathogenicity Statements). This is why `normal` function *disputes* the proposition while `abnormal` function *supports* it. -When a statement includes multiple evidence lines, MaveDB aggregates their directions. If all evidence lines point in the same direction, the statement inherits that direction. If evidence lines conflict, the statement direction is set to `Neutral`. +When a statement includes multiple evidence lines, MaveDB aggregates their directions. If all evidence lines point in the same direction, the statement inherits that direction. If evidence lines conflict, the statement direction is set to `neutral`. ### Variants without VRS representations