Refactor score ranges into score calibrations.

- Refactored score range jsonb in score sets into a separate data model with db tables and publication associations
- Removed tests related to score ranges and replaced them with tests for score calibrations.
- Updated test cases to validate the creation of score sets with investigator-provided calibrations.
- Ensured that score set creation fails when non-investigator provided calibrations are included.
- Adjusted error assertions to reflect changes in validation logic for score calibrations.

Author: bencap

src/mavedb/lib/annotation/classification.py

@@ -6,9 +6,7 @@
 from ga4gh.va_spec.base.enums import StrengthOfEvidenceProvided
 
 from mavedb.models.mapped_variant import MappedVariant
-from mavedb.lib.annotation.constants import ZEIBERG_CALIBRATION_CALIBRATION_STRENGTH_OF_EVIDENCE_MAP
-from mavedb.lib.validation.utilities import inf_or_float
-from mavedb.view_models.score_range import ScoreSetRanges
+from mavedb.view_models.score_calibration import FunctionalRange
 
 logger = logging.getLogger(__name__)
 
@@ -24,18 +22,30 @@ class ExperimentalVariantFunctionalImpactClassification(StrEnum):
 def functional_classification_of_variant(
     mapped_variant: MappedVariant,
 ) -> ExperimentalVariantFunctionalImpactClassification:
-    if mapped_variant.variant.score_set.score_ranges is None:
+    """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.
+    """
+    if not mapped_variant.variant.score_set.score_calibrations:
         raise ValueError(
-            f"Variant {mapped_variant.variant.urn} does not have a score set with score ranges."
+            f"Variant {mapped_variant.variant.urn} does not have a score set with score calibrations."
             " Unable to classify functional impact."
         )
 
-    # This view model object is much simpler to work with.
-    score_ranges = ScoreSetRanges(**mapped_variant.variant.score_set.score_ranges).investigator_provided
+    # TODO#494: Support for multiple calibrations (all non-research use only).
+    score_calibrations = mapped_variant.variant.score_set.score_calibrations or []
+    primary_calibration = next((c for c in score_calibrations if c.primary), None)
+
+    if not primary_calibration:
+        raise ValueError(
+            f"Variant {mapped_variant.variant.urn} does not have a primary score calibration."
+            " Unable to classify functional impact."
+        )
 
-    if not score_ranges or not score_ranges.ranges:
+    if not primary_calibration.functional_ranges:
         raise ValueError(
-            f"Variant {mapped_variant.variant.urn} does not have investigator-provided score ranges."
+            f"Variant {mapped_variant.variant.urn} does not have ranges defined in its primary score calibration."
             " Unable to classify functional impact."
         )
 
@@ -47,33 +57,48 @@ def functional_classification_of_variant(
             " Unable to classify functional impact."
         )
 
-    for range in score_ranges.ranges:
-        lower_bound, upper_bound = inf_or_float(range.range[0], lower=True), inf_or_float(range.range[1], lower=False)
-        if functional_score > lower_bound and functional_score <= upper_bound:
-            if range.classification == "normal":
+    for functional_range in primary_calibration.functional_ranges:
+        # It's easier to reason with the view model objects for functional ranges than the JSONB fields in the raw database object.
+        functional_range_view = FunctionalRange.model_validate(functional_range)
+
+        if functional_range_view.is_contained_by_range(functional_score):
+            if functional_range_view.classification == "normal":
                 return ExperimentalVariantFunctionalImpactClassification.NORMAL
-            elif range.classification == "abnormal":
+            elif functional_range_view.classification == "abnormal":
                 return ExperimentalVariantFunctionalImpactClassification.ABNORMAL
             else:
                 return ExperimentalVariantFunctionalImpactClassification.INDETERMINATE
 
     return ExperimentalVariantFunctionalImpactClassification.INDETERMINATE
 
 
-def zeiberg_calibration_clinical_classification_of_variant(
+def pathogenicity_classification_of_variant(
     mapped_variant: MappedVariant,
 ) -> tuple[VariantPathogenicityEvidenceLine.Criterion, Optional[StrengthOfEvidenceProvided]]:
-    if mapped_variant.variant.score_set.score_ranges is None:
+    """Classify a variant's pathogenicity and evidence strength using clinical calibration.
+
+    Uses the first clinical score calibration and its functional ranges.
+    Raises ValueError if required calibration, score, or evidence strength is missing.
+    """
+    if not mapped_variant.variant.score_set.score_calibrations:
         raise ValueError(
-            f"Variant {mapped_variant.variant.urn} does not have a score set with score thresholds."
+            f"Variant {mapped_variant.variant.urn} does not have a score set with score calibrations."
             " Unable to classify clinical impact."
         )
 
-    score_ranges = ScoreSetRanges(**mapped_variant.variant.score_set.score_ranges).zeiberg_calibration
+    # TODO#494: Support multiple clinical calibrations.
+    score_calibrations = mapped_variant.variant.score_set.score_calibrations or []
+    primary_calibration = next((c for c in score_calibrations if c.primary), None)
+
+    if not primary_calibration:
+        raise ValueError(
+            f"Variant {mapped_variant.variant.urn} does not have a primary score calibration."
+            " Unable to classify clinical impact."
+        )
 
-    if not score_ranges or not score_ranges.ranges:
+    if not primary_calibration.functional_ranges:
         raise ValueError(
-            f"Variant {mapped_variant.variant.urn} does not have pillar project score ranges."
+            f"Variant {mapped_variant.variant.urn} does not have ranges defined in its primary score calibration."
             " Unable to classify clinical impact."
         )
 
@@ -85,9 +110,44 @@ def zeiberg_calibration_clinical_classification_of_variant(
             " Unable to classify clinical impact."
         )
 
-    for range in score_ranges.ranges:
-        lower_bound, upper_bound = inf_or_float(range.range[0], lower=True), inf_or_float(range.range[1], lower=False)
-        if functional_score > lower_bound and functional_score <= upper_bound:
-            return ZEIBERG_CALIBRATION_CALIBRATION_STRENGTH_OF_EVIDENCE_MAP[range.evidence_strength]
-
-    return ZEIBERG_CALIBRATION_CALIBRATION_STRENGTH_OF_EVIDENCE_MAP[0]
+    for pathogenicity_range in primary_calibration.functional_ranges:
+        # It's easier to reason with the view model objects for functional ranges than the JSONB fields in the raw database object.
+        pathogenicity_range_view = FunctionalRange.model_validate(pathogenicity_range)
+
+        if pathogenicity_range_view.is_contained_by_range(functional_score):
+            if pathogenicity_range_view.acmg_classification is None:
+                return (VariantPathogenicityEvidenceLine.Criterion.PS3, None)
+
+            # More of a type guard, as the ACMGClassification model we construct above enforces that
+            # criterion and evidence strength are mutually defined.
+            if (
+                pathogenicity_range_view.acmg_classification.evidence_strength is None
+                or pathogenicity_range_view.acmg_classification.criterion is None
+            ):  # pragma: no cover - enforced by model validators in FunctionalRange view model
+                return (VariantPathogenicityEvidenceLine.Criterion.PS3, None)
+
+            # TODO#540: Handle moderate+
+            if (
+                pathogenicity_range_view.acmg_classification.evidence_strength.name
+                not in StrengthOfEvidenceProvided._member_names_
+            ):
+                raise ValueError(
+                    f"Variant {mapped_variant.variant.urn} is contained in a clinical calibration range with an invalid evidence strength."
+                    " Unable to classify clinical impact."
+                )
+
+            if (
+                pathogenicity_range_view.acmg_classification.criterion.name
+                not in VariantPathogenicityEvidenceLine.Criterion._member_names_
+            ):  # pragma: no cover - enforced by model validators in FunctionalRange view model
+                raise ValueError(
+                    f"Variant {mapped_variant.variant.urn} is contained in a clinical calibration range with an invalid criterion."
+                    " Unable to classify clinical impact."
+                )
+
+            return (
+                VariantPathogenicityEvidenceLine.Criterion[pathogenicity_range_view.acmg_classification.criterion.name],
+                StrengthOfEvidenceProvided[pathogenicity_range_view.acmg_classification.evidence_strength.name],
+            )
+
+    return (VariantPathogenicityEvidenceLine.Criterion.PS3, None)

src/mavedb/lib/annotation/constants.py

@@ -1,34 +1,2 @@
-from ga4gh.va_spec.acmg_2015 import VariantPathogenicityEvidenceLine
-from ga4gh.va_spec.base.enums import StrengthOfEvidenceProvided
-
 GENERIC_DISEASE_MEDGEN_CODE = "C0012634"
 MEDGEN_SYSTEM = "https://www.ncbi.nlm.nih.gov/medgen/"
-
-ZEIBERG_CALIBRATION_CALIBRATION_STRENGTH_OF_EVIDENCE_MAP = {
-    # No evidence
-    0: (VariantPathogenicityEvidenceLine.Criterion.PS3, None),
-    # Supporting evidence
-    -1: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.SUPPORTING),
-    1: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.SUPPORTING),
-    # Moderate evidence
-    -2: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.MODERATE),
-    2: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.MODERATE),
-    -3: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.MODERATE),
-    3: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.MODERATE),
-    # Strong evidence
-    -4: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.STRONG),
-    4: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.STRONG),
-    -5: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.STRONG),
-    5: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.STRONG),
-    -6: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.STRONG),
-    6: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.STRONG),
-    -7: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.STRONG),
-    7: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.STRONG),
-    # Very Strong evidence
-    -8: (VariantPathogenicityEvidenceLine.Criterion.BS3, StrengthOfEvidenceProvided.VERY_STRONG),
-    8: (VariantPathogenicityEvidenceLine.Criterion.PS3, StrengthOfEvidenceProvided.VERY_STRONG),
-}
-
-# TODO#493
-FUNCTIONAL_RANGES = ["investigator_provided"]
-CLINICAL_RANGES = ["zeiberg_calibration"]

src/mavedb/lib/annotation/evidence_line.py

@@ -12,7 +12,7 @@
     VariantPathogenicityProposition,
 )
 
-from mavedb.lib.annotation.classification import zeiberg_calibration_clinical_classification_of_variant
+from mavedb.lib.annotation.classification import pathogenicity_classification_of_variant
 from mavedb.lib.annotation.contribution import (
     mavedb_api_contribution,
     mavedb_vrs_contribution,
@@ -33,7 +33,7 @@ def acmg_evidence_line(
     proposition: VariantPathogenicityProposition,
     evidence: list[Union[StudyResult, EvidenceLineType, StatementType, iriReference]],
 ) -> Optional[VariantPathogenicityEvidenceLine]:
-    evidence_outcome, evidence_strength = zeiberg_calibration_clinical_classification_of_variant(mapped_variant)
+    evidence_outcome, evidence_strength = pathogenicity_classification_of_variant(mapped_variant)
 
     if not evidence_strength:
         evidence_outcome_code = f"{evidence_outcome.value}_not_met"

src/mavedb/lib/annotation/util.py

@@ -1,3 +1,4 @@
+from typing import Literal
 from ga4gh.core.models import Extension
 from ga4gh.vrs.models import (
     MolecularVariation,
@@ -8,9 +9,9 @@
     Expression,
     LiteralSequenceExpression,
 )
-from mavedb.lib.annotation.constants import CLINICAL_RANGES, FUNCTIONAL_RANGES
 from mavedb.models.mapped_variant import MappedVariant
 from mavedb.lib.annotation.exceptions import MappingDataDoesntExistException
+from mavedb.view_models.score_calibration import SavedScoreCalibration
 
 
 def allele_from_mapped_variant_dictionary_result(allelic_mapping_results: dict) -> Allele:
@@ -162,43 +163,51 @@ def _can_annotate_variant_base_assumptions(mapped_variant: MappedVariant) -> boo
     return True
 
 
-def _variant_score_ranges_have_required_keys_and_ranges_for_annotation(
-    mapped_variant: MappedVariant, key_options: list[str]
+def _variant_score_calibrations_have_required_calibrations_and_ranges_for_annotation(
+    mapped_variant: MappedVariant, annotation_type: Literal["pathogenicity", "functional"]
 ) -> bool:
     """
-    Check if a mapped variant's score set contains any of the required score range keys for annotation and is present.
+    Check if a mapped variant's score set contains any of the required calibrations for annotation.
 
     Args:
         mapped_variant (MappedVariant): The mapped variant object containing the variant with score set data.
-        key_options (list[str]): List of possible score range keys to check for in the score set.
+        annotation_type (Literal["pathogenicity", "functional"]): The type of annotation to check for.
+            Must be either "pathogenicity" or "functional".
 
     Returns:
-        bool: False if none of the required keys are found or if all found keys have None values or if all found keys
-              do not have range data.
-              Returns True (implicitly) if at least one required key exists with a non-None value.
+        bool: False if none of the required kinds are found or if all found calibrations have None or empty functional
+         range values/do not have range data.
+              Returns True (implicitly) if at least one required kind exists and has a non-empty functional range.
     """
-    if mapped_variant.variant.score_set.score_ranges is None:
+    if mapped_variant.variant.score_set.score_calibrations is None:
         return False
 
-    if not any(
-        range_key in mapped_variant.variant.score_set.score_ranges
-        and mapped_variant.variant.score_set.score_ranges[range_key] is not None
-        and mapped_variant.variant.score_set.score_ranges[range_key]["ranges"]
-        for range_key in key_options
-    ):
+    # TODO#494: Support for multiple calibrations (all non-research use only).
+    primary_calibration = next((c for c in mapped_variant.variant.score_set.score_calibrations if c.primary), None)
+    if not primary_calibration:
         return False
 
+    saved_calibration = SavedScoreCalibration.model_validate(primary_calibration)
+    if annotation_type == "pathogenicity":
+        return (
+            saved_calibration.functional_ranges is not None
+            and len(saved_calibration.functional_ranges) > 0
+            and any(fr.acmg_classification is not None for fr in saved_calibration.functional_ranges)
+        )
+
+    if annotation_type == "functional":
+        return saved_calibration.functional_ranges is not None and len(saved_calibration.functional_ranges) > 0
+
     return True
 
 
 def can_annotate_variant_for_pathogenicity_evidence(mapped_variant: MappedVariant) -> bool:
     """
     Determine if a mapped variant can be annotated for pathogenicity evidence.
 
-    This function checks whether a given mapped variant meets all the necessary
-    requirements to receive pathogenicity evidence annotations. It validates
-    both basic annotation assumptions and the presence of required clinical
-    score range keys.
+    This function checks if a variant meets all the necessary conditions to receive
+    pathogenicity evidence annotations by validating base assumptions and ensuring the variant's
+    score calibrations contain the required kinds for pathogenicity evidence annotation.
 
     Args:
         mapped_variant (MappedVariant): The mapped variant object to evaluate
@@ -211,14 +220,16 @@ def can_annotate_variant_for_pathogenicity_evidence(mapped_variant: MappedVarian
     Notes:
         The function performs two main validation checks:
         1. Basic annotation assumptions via _can_annotate_variant_base_assumptions
-        2. Required clinical range keys via _variant_score_ranges_have_required_keys_and_ranges_for_annotation
+        2. Verifies score calibrations have an appropriate calibration for pathogenicity evidence annotation.
 
         Both checks must pass for the variant to be considered eligible for
         pathogenicity evidence annotation.
     """
     if not _can_annotate_variant_base_assumptions(mapped_variant):
         return False
-    if not _variant_score_ranges_have_required_keys_and_ranges_for_annotation(mapped_variant, CLINICAL_RANGES):
+    if not _variant_score_calibrations_have_required_calibrations_and_ranges_for_annotation(
+        mapped_variant, "pathogenicity"
+    ):
         return False
 
     return True
@@ -230,7 +241,7 @@ def can_annotate_variant_for_functional_statement(mapped_variant: MappedVariant)
 
     This function checks if a variant meets all the necessary conditions to receive
     functional annotations by validating base assumptions and ensuring the variant's
-    score ranges contain the required keys for functional annotation.
+    score calibrations contain the required kinds for functional annotation.
 
     Args:
         mapped_variant (MappedVariant): The variant object to check for annotation
@@ -243,11 +254,13 @@ def can_annotate_variant_for_functional_statement(mapped_variant: MappedVariant)
     Notes:
         The function performs two main checks:
         1. Validates base assumptions using _can_annotate_variant_base_assumptions
-        2. Verifies score ranges have required keys using FUNCTIONAL_RANGES
+        2. Verifies score calibrations have an appropriate calibration for functional annotation.
     """
     if not _can_annotate_variant_base_assumptions(mapped_variant):
         return False
-    if not _variant_score_ranges_have_required_keys_and_ranges_for_annotation(mapped_variant, FUNCTIONAL_RANGES):
+    if not _variant_score_calibrations_have_required_calibrations_and_ranges_for_annotation(
+        mapped_variant, "functional"
+    ):
         return False
 
     return True