Release 2026.2.7.1

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mavedb"
-version = "2026.2.7"
+version = "2026.2.7.1"
 description = "API for MaveDB, the database of Multiplexed Assays of Variant Effect."
 license = "AGPL-3.0-only"
 readme = "README.md"

src/mavedb/__init__.py

@@ -6,7 +6,7 @@
 logger = module_logging.getLogger(__name__)
 
 __project__ = "mavedb-api"
-__version__ = "2026.2.7"
+__version__ = "2026.2.7.1"
 
 logger.info(f"MaveDB {__version__}")
 

src/mavedb/lib/acmg.py

@@ -8,6 +8,48 @@
 from mavedb.models.enums.strength_of_evidence import StrengthOfEvidenceProvided
 
 
+def acmg_evidence_outcome_code(criterion: str, evidence_strength: Optional[str]) -> str:
+    """Build the ACMG 2015 evidence outcome code for a criterion and the strength it was met at.
+
+    Three rules, which are the ACMG convention rather than anything MaveDB invented:
+
+    - no strength means the criterion was evaluated and *not* met, written ``"PS3_not_met"``
+    - STRONG is the criterion's baseline, so it is written bare: ``"PS3"``
+    - any other strength is suffixed: ``"PS3_moderate"``
+
+    Takes the criterion code and strength *name* as strings rather than enums so that the VA-Spec
+    annotation builders and the flat exports can share one implementation despite drawing their
+    enumerations from different places. That also means this survives any future decision about which
+    enumeration is canonical.
+
+    Parameters
+    ----------
+    criterion : str
+        The criterion code, e.g. ``"PS3"`` or ``"BS3"``.
+    evidence_strength : Optional[str]
+        The strength name, e.g. ``"MODERATE"``. None when the criterion was not met.
+
+    Returns
+    -------
+    str
+        The evidence outcome code.
+
+    Examples
+    --------
+    >>> acmg_evidence_outcome_code("PS3", "STRONG")
+    'PS3'
+    >>> acmg_evidence_outcome_code("PS3", "MODERATE")
+    'PS3_moderate'
+    >>> acmg_evidence_outcome_code("BS3", None)
+    'BS3_not_met'
+    """
+    if evidence_strength is None:
+        return f"{criterion}_not_met"
+    if evidence_strength.upper() == StrengthOfEvidenceProvided.STRONG.name:
+        return criterion
+    return f"{criterion}_{evidence_strength.lower()}"
+
+
 def points_evidence_strength_equivalent(
     points: int,
 ) -> tuple[Optional[ACMGCriterion], Optional[StrengthOfEvidenceProvided]]:

src/mavedb/lib/annotation/annotate.py

@@ -8,14 +8,14 @@
     See: https://va-spec.ga4gh.org/en/latest/va-standard-profiles/community-profiles/acmg-2015-profiles.html#variant-pathogenicity-statement-acmg-2015
 """
 
-from typing import Optional, Union
+from typing import Optional, Sequence, TypeVar, Union
 
 from ga4gh.va_spec.acmg_2015 import VariantPathogenicityStatement
 from ga4gh.va_spec.base.core import ExperimentalVariantFunctionalImpactStudyResult, Statement
 
 from mavedb.lib.annotation.classification import functional_classification_of_variant
-from mavedb.lib.annotation.exceptions import MappingDataDoesntExistException
 from mavedb.lib.annotation.evidence_line import acmg_evidence_line, functional_evidence_line
+from mavedb.lib.annotation.exceptions import MappingDataDoesntExistException
 from mavedb.lib.annotation.proposition import (
     mapped_variant_to_experimental_variant_clinical_impact_proposition,
     mapped_variant_to_experimental_variant_functional_impact_proposition,
@@ -26,39 +26,62 @@
 )
 from mavedb.lib.annotation.study_result import mapped_variant_to_experimental_variant_impact_study_result
 from mavedb.lib.annotation.util import (
+    calibration_scope_extension,
+    calibrations_available_for_annotation,
     can_annotate_variant_for_functional_statement,
     can_annotate_variant_for_pathogenicity_evidence,
-    score_calibration_may_be_used_for_annotation,
     select_strongest_functional_calibration,
     select_strongest_pathogenicity_calibration,
 )
+from mavedb.lib.permissions.principal import Principal
 from mavedb.models.mapped_variant import MappedVariant
+from mavedb.models.score_calibration import ScoreCalibration
+
+Annotation = TypeVar(
+    "Annotation", ExperimentalVariantFunctionalImpactStudyResult, Statement, VariantPathogenicityStatement
+)
+
+
+def _disclosing_calibration_scope(annotation: Annotation, calibrations: Sequence[ScoreCalibration]) -> Annotation:
+    """Record on the annotation which principal it was built for.
+
+    Applied at the top-level entry points only. Nested study results and statements built as components of
+    an evidence line inherit the scope of the object that contains them.
+    """
+    # model_copy rather than assigning to `.extensions`: mypy resolves the field's element type to a
+    # `ga4gh.va_spec.base.core.Extension` that does not exist at runtime (the ga4gh namespace packages
+    # confuse its import resolution), so a direct assignment is a false positive.
+    return annotation.model_copy(
+        update={"extensions": [*(annotation.extensions or []), calibration_scope_extension(calibrations)]}
+    )
 
 
 def variant_study_result(mapped_variant: MappedVariant) -> ExperimentalVariantFunctionalImpactStudyResult:
-    return mapped_variant_to_experimental_variant_impact_study_result(mapped_variant)
+    # A study result reports the measured score and carries no calibration-derived evidence, so its scope
+    # is public regardless of viewer. Disclosed anyway, so that a missing scope never has to be read as
+    # "public" or "generated before disclosure existed".
+    return _disclosing_calibration_scope(mapped_variant_to_experimental_variant_impact_study_result(mapped_variant), [])
 
 
 def variant_functional_impact_statement(
-    mapped_variant: MappedVariant, allow_research_use_only_calibrations: bool = False
+    mapped_variant: MappedVariant,
+    allow_research_use_only_calibrations: bool = False,
+    principal: Optional[Principal] = None,
 ) -> Optional[Statement]:
     if not can_annotate_variant_for_functional_statement(
-        mapped_variant, allow_research_use_only_calibrations=allow_research_use_only_calibrations
+        mapped_variant, allow_research_use_only_calibrations=allow_research_use_only_calibrations, principal=principal
     ):
         return None
 
     study_result = mapped_variant_to_experimental_variant_impact_study_result(mapped_variant)
     functional_proposition = mapped_variant_to_experimental_variant_functional_impact_proposition(mapped_variant)
 
-    # Collect eligible calibrations
-    eligible_calibrations = []
-    for score_calibration in mapped_variant.variant.score_set.score_calibrations:
-        if score_calibration_may_be_used_for_annotation(
-            score_calibration,
-            annotation_type="functional",
-            allow_research_use_only_calibrations=allow_research_use_only_calibrations,
-        ):
-            eligible_calibrations.append(score_calibration)
+    eligible_calibrations = calibrations_available_for_annotation(
+        mapped_variant,
+        "functional",
+        allow_research_use_only_calibrations=allow_research_use_only_calibrations,
+        principal=principal,
+    )
 
     # Select the calibration with the strongest evidence
     strongest_calibration, strongest_range = select_strongest_functional_calibration(
@@ -77,32 +100,34 @@ def variant_functional_impact_statement(
     for score_calibration in eligible_calibrations:
         functional_evidence.append(functional_evidence_line(mapped_variant, score_calibration, [study_result]))
 
-    return mapped_variant_to_functional_statement(
-        mapped_variant, functional_proposition, functional_evidence, strongest_calibration, classification
+    return _disclosing_calibration_scope(
+        mapped_variant_to_functional_statement(
+            mapped_variant, functional_proposition, functional_evidence, strongest_calibration, classification
+        ),
+        eligible_calibrations,
     )
 
 
 def variant_pathogenicity_statement(
-    mapped_variant: MappedVariant, allow_research_use_only_calibrations: bool = False
+    mapped_variant: MappedVariant,
+    allow_research_use_only_calibrations: bool = False,
+    principal: Optional[Principal] = None,
 ) -> Optional[VariantPathogenicityStatement]:
     if not can_annotate_variant_for_pathogenicity_evidence(
-        mapped_variant, allow_research_use_only_calibrations=allow_research_use_only_calibrations
+        mapped_variant, allow_research_use_only_calibrations=allow_research_use_only_calibrations, principal=principal
     ):
         return None
 
     study_result = mapped_variant_to_experimental_variant_impact_study_result(mapped_variant)
     functional_proposition = mapped_variant_to_experimental_variant_functional_impact_proposition(mapped_variant)
     clinical_proposition = mapped_variant_to_experimental_variant_clinical_impact_proposition(mapped_variant)
 
-    # Collect eligible calibrations
-    eligible_calibrations = []
-    for score_calibration in mapped_variant.variant.score_set.score_calibrations:
-        if score_calibration_may_be_used_for_annotation(
-            score_calibration,
-            annotation_type="pathogenicity",
-            allow_research_use_only_calibrations=allow_research_use_only_calibrations,
-        ):
-            eligible_calibrations.append(score_calibration)
+    eligible_calibrations = calibrations_available_for_annotation(
+        mapped_variant,
+        "pathogenicity",
+        allow_research_use_only_calibrations=allow_research_use_only_calibrations,
+        principal=principal,
+    )
 
     # Select the calibration with the strongest evidence
     strongest_calibration, strongest_range = select_strongest_pathogenicity_calibration(
@@ -130,25 +155,33 @@ def variant_pathogenicity_statement(
             acmg_evidence_line(mapped_variant, score_calibration, clinical_proposition, [functional_statement])
         )
 
-    return mapped_variant_to_pathogenicity_statement(
-        mapped_variant, clinical_proposition, clinical_evidence, strongest_calibration, strongest_range
+    return _disclosing_calibration_scope(
+        mapped_variant_to_pathogenicity_statement(
+            mapped_variant, clinical_proposition, clinical_evidence, strongest_calibration, strongest_range
+        ),
+        eligible_calibrations,
     )
 
 
 def variant_highest_level_annotation(
     mapped_variant: MappedVariant,
+    principal: Optional[Principal] = None,
 ) -> Optional[Union[ExperimentalVariantFunctionalImpactStudyResult, Statement, VariantPathogenicityStatement]]:
     """
     Build the single highest-materialized VA-Spec layer for a mapped variant.
 
     Layer ladder (highest to lowest): pathogenicity statement -> functional impact statement -> study result.
     Returns None when the variant has no post-mapped allele and therefore cannot be annotated.
+
+    The viewer decides which layer is reachable as well as what the layer contains: a variant whose only
+    calibration is invisible to this principal degrades to a study result rather than yielding a statement
+    with nothing in it.
     """
     try:
-        if can_annotate_variant_for_pathogenicity_evidence(mapped_variant):
-            return variant_pathogenicity_statement(mapped_variant)
-        if can_annotate_variant_for_functional_statement(mapped_variant):
-            return variant_functional_impact_statement(mapped_variant)
+        if can_annotate_variant_for_pathogenicity_evidence(mapped_variant, principal=principal):
+            return variant_pathogenicity_statement(mapped_variant, principal=principal)
+        if can_annotate_variant_for_functional_statement(mapped_variant, principal=principal):
+            return variant_functional_impact_statement(mapped_variant, principal=principal)
         return variant_study_result(mapped_variant)
     except MappingDataDoesntExistException:
         return None

src/mavedb/lib/annotation/classification.py

@@ -21,13 +21,35 @@ class ExperimentalVariantFunctionalImpactClassification(StrEnum):
     INDETERMINATE = "indeterminate"
 
 
+def _classification_contains_variant(
+    functional_classification: ScoreCalibrationFunctionalClassification,
+    mapped_variant: MappedVariant,
+    containing_classification_ids: Optional[set[int]],
+) -> bool:
+    """Whether this classification's score range contains the variant.
+
+    Prefers a pre-resolved id set, which is an O(1) check. Falls back to the ORM relationship, which is
+    correct but loads every variant of the range.
+    """
+    if containing_classification_ids is not None:
+        return functional_classification.id in containing_classification_ids
+    return mapped_variant.variant in functional_classification.variants
+
+
 def functional_classification_of_variant(
-    mapped_variant: MappedVariant, score_calibration: ScoreCalibration
+    mapped_variant: MappedVariant,
+    score_calibration: ScoreCalibration,
+    containing_classification_ids: Optional[set[int]] = None,
 ) -> tuple[Optional[ScoreCalibrationFunctionalClassification], ExperimentalVariantFunctionalImpactClassification]:
     """Classify a variant's functional impact as normal, abnormal, or indeterminate.
 
     Uses the primary score calibration and its functional ranges.
     Raises ValueError if required calibration or score is missing.
+
+    *containing_classification_ids*, when given, is the set of functional-classification ids already known
+    to contain this variant. Pass it to avoid the ORM membership check below, which loads every variant of
+    every range. A caller classifying many variants should resolve membership once from the association
+    table; see ``mavedb.lib.csv.variant``.
     """
     if not mapped_variant.variant.score_set.score_calibrations:
         raise ValueError(
@@ -41,11 +63,8 @@ def functional_classification_of_variant(
             " Unable to classify functional impact."
         )
 
-    # TODO#XXX: Performance: avoid ORM relationship membership checks (`variant in functional_range.variants`) in this
-    #           DB-agnostic function. Resolve class-based matches in an upstream DB-aware layer using the association table,
-    #           pass matched functional classification IDs into this function, and use O(1) ID membership checks here.
     for functional_range in score_calibration.functional_classifications:
-        if mapped_variant.variant in functional_range.variants:
+        if _classification_contains_variant(functional_range, mapped_variant, containing_classification_ids):
             if functional_range.functional_classification is FunctionalClassificationOptions.normal:
                 return functional_range, ExperimentalVariantFunctionalImpactClassification.NORMAL
             elif functional_range.functional_classification is FunctionalClassificationOptions.abnormal:
@@ -58,6 +77,7 @@ def functional_classification_of_variant(
 def pathogenicity_classification_of_variant(
     mapped_variant: MappedVariant,
     score_calibration: ScoreCalibration,
+    containing_classification_ids: Optional[set[int]] = None,
 ) -> tuple[
     Optional[ScoreCalibrationFunctionalClassification],
     VariantPathogenicityEvidenceLine.Criterion,
@@ -87,11 +107,8 @@ def pathogenicity_classification_of_variant(
             " Unable to classify clinical impact."
         )
 
-    # TODO#XXX: Performance: avoid ORM relationship membership checks (`variant in pathogenicity_range.variants`) in this
-    #           DB-agnostic function. Resolve class-based matches in an upstream DB-aware layer using the association table,
-    #           pass matched functional classification IDs into this function, and use O(1) ID membership checks here.
     for pathogenicity_range in score_calibration.functional_classifications:
-        if mapped_variant.variant in pathogenicity_range.variants:
+        if _classification_contains_variant(pathogenicity_range, mapped_variant, containing_classification_ids):
             if pathogenicity_range.acmg_classification is None:
                 return (pathogenicity_range, VariantPathogenicityEvidenceLine.Criterion.PS3, None)