feat: add support for class based score ranges

- Add a property `class_` to score calibration functional classifications. One of `range` or `class_` must be defined
- Add validation logic to class based score ranges
- Refactor lib code to support both range types
- Refactor tests to support both range types

TODO: Support for creating variant associations in class based score ranges.

Author: bencap

alembic/versions/0520dfa9f2db_rename_functional_ranges_to_functional_.py

@@ -0,0 +1,45 @@
+"""rename functional ranges to functional classifications, add class_ to model, rename classification to functional_classification
+
+Revision ID: 0520dfa9f2db
+Revises: c770fa9e6e58
+Create Date: 2025-11-18 18:51:33.107952
+
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "0520dfa9f2db"
+down_revision = "c770fa9e6e58"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "score_calibration_functional_classifications",
+        "classification",
+        new_column_name="functional_classification",
+        type_=sa.Enum(
+            "normal", "abnormal", "not_specified", name="functionalclassification", native_enum=False, length=32
+        ),
+        nullable=False,
+    )
+    op.add_column("score_calibration_functional_classifications", sa.Column("class_", sa.String(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column(
+        "score_calibration_functional_classifications",
+        "functional_classification",
+        new_column_name="classification",
+        type_=sa.VARCHAR(length=32),
+        nullable=False,
+    )
+    op.drop_column("score_calibration_functional_classifications", "class_")
+    # ### end Alembic commands ###

src/mavedb/lib/annotation/classification.py

@@ -5,9 +5,9 @@
 from ga4gh.va_spec.acmg_2015 import VariantPathogenicityEvidenceLine
 from ga4gh.va_spec.base.enums import StrengthOfEvidenceProvided
 
-from mavedb.models.enums.functional_classification import FunctionalClassification
+from mavedb.models.enums.functional_classification import FunctionalClassification as FunctionalClassificationOptions
 from mavedb.models.mapped_variant import MappedVariant
-from mavedb.view_models.score_calibration import FunctionalRange
+from mavedb.view_models.score_calibration import FunctionalClassification
 
 logger = logging.getLogger(__name__)
 
@@ -44,7 +44,7 @@ def functional_classification_of_variant(
             " Unable to classify functional impact."
         )
 
-    if not primary_calibration.functional_ranges:
+    if not primary_calibration.functional_classifications:
         raise ValueError(
             f"Variant {mapped_variant.variant.urn} does not have ranges defined in its primary score calibration."
             " Unable to classify functional impact."
@@ -58,14 +58,14 @@ def functional_classification_of_variant(
             " Unable to classify functional impact."
         )
 
-    for functional_range in primary_calibration.functional_ranges:
+    for functional_range in primary_calibration.functional_classifications:
         # 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)
+        functional_range_view = FunctionalClassification.model_validate(functional_range)
 
         if functional_range_view.is_contained_by_range(functional_score):
-            if functional_range_view.classification is FunctionalClassification.normal:
+            if functional_range_view.functional_classification is FunctionalClassificationOptions.normal:
                 return ExperimentalVariantFunctionalImpactClassification.NORMAL
-            elif functional_range_view.classification is FunctionalClassification.abnormal:
+            elif functional_range_view.functional_classification is FunctionalClassificationOptions.abnormal:
                 return ExperimentalVariantFunctionalImpactClassification.ABNORMAL
             else:
                 return ExperimentalVariantFunctionalImpactClassification.INDETERMINATE
@@ -97,7 +97,7 @@ def pathogenicity_classification_of_variant(
             " Unable to classify clinical impact."
         )
 
-    if not primary_calibration.functional_ranges:
+    if not primary_calibration.functional_classifications:
         raise ValueError(
             f"Variant {mapped_variant.variant.urn} does not have ranges defined in its primary score calibration."
             " Unable to classify clinical impact."
@@ -111,9 +111,9 @@ def pathogenicity_classification_of_variant(
             " Unable to classify clinical impact."
         )
 
-    for pathogenicity_range in primary_calibration.functional_ranges:
+    for pathogenicity_range in primary_calibration.functional_classifications:
         # 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)
+        pathogenicity_range_view = FunctionalClassification.model_validate(pathogenicity_range)
 
         if pathogenicity_range_view.is_contained_by_range(functional_score):
             if pathogenicity_range_view.acmg_classification is None:
@@ -124,7 +124,7 @@ def pathogenicity_classification_of_variant(
             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
+            ):  # pragma: no cover - enforced by model validators in FunctionalClassification view model
                 return (VariantPathogenicityEvidenceLine.Criterion.PS3, None)
 
             # TODO#540: Handle moderate+
@@ -140,7 +140,7 @@ def pathogenicity_classification_of_variant(
             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
+            ):  # pragma: no cover - enforced by model validators in FunctionalClassification 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."

src/mavedb/lib/annotation/util.py

@@ -1,16 +1,18 @@
 from typing import Literal
+
 from ga4gh.core.models import Extension
 from ga4gh.vrs.models import (
-    MolecularVariation,
     Allele,
     CisPhasedBlock,
-    SequenceLocation,
-    SequenceReference,
     Expression,
     LiteralSequenceExpression,
+    MolecularVariation,
+    SequenceLocation,
+    SequenceReference,
 )
-from mavedb.models.mapped_variant import MappedVariant
+
 from mavedb.lib.annotation.exceptions import MappingDataDoesntExistException
+from mavedb.models.mapped_variant import MappedVariant
 from mavedb.view_models.score_calibration import SavedScoreCalibration
 
 
@@ -190,13 +192,16 @@ def _variant_score_calibrations_have_required_calibrations_and_ranges_for_annota
     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)
+            saved_calibration.functional_classifications is not None
+            and len(saved_calibration.functional_classifications) > 0
+            and any(fr.acmg_classification is not None for fr in saved_calibration.functional_classifications)
         )
 
     if annotation_type == "functional":
-        return saved_calibration.functional_ranges is not None and len(saved_calibration.functional_ranges) > 0
+        return (
+            saved_calibration.functional_classifications is not None
+            and len(saved_calibration.functional_classifications) > 0
+        )
 
     return True
 

src/mavedb/lib/score_calibrations.py

@@ -21,7 +21,9 @@
 
 def create_functional_classification(
     db: Session,
-    functional_range_create: Union[score_calibration.FunctionalRangeCreate, score_calibration.FunctionalRangeModify],
+    functional_range_create: Union[
+        score_calibration.FunctionalClassificationCreate, score_calibration.FunctionalClassificationModify
+    ],
     containing_calibration: ScoreCalibration,
 ) -> ScoreCalibrationFunctionalClassification:
     """
@@ -32,7 +34,7 @@ def create_functional_classification(
 
     Args:
         db (Session): Database session for performing database operations.
-        functional_range_create (score_calibration.FunctionalRangeCreate):
+        functional_range_create (score_calibration.FunctionalClassificationCreate):
             Input data containing the functional range parameters including label,
             description, range bounds, inclusivity flags, and optional ACMG
             classification information.
@@ -64,7 +66,7 @@ def create_functional_classification(
         inclusive_lower_bound=functional_range_create.inclusive_lower_bound,
         inclusive_upper_bound=functional_range_create.inclusive_upper_bound,
         acmg_classification=acmg_classification,
-        classification=functional_range_create.classification,
+        functional_classification=functional_range_create.functional_classification,
         oddspaths_ratio=functional_range_create.oddspaths_ratio,  # type: ignore[arg-type]
         positive_likelihood_ratio=functional_range_create.positive_likelihood_ratio,  # type: ignore[arg-type]
         acmg_classification_id=acmg_classification.id if acmg_classification else None,
@@ -155,25 +157,25 @@ async def _create_score_calibration(
         **calibration_create.model_dump(
             by_alias=False,
             exclude={
-                "functional_ranges",
+                "functional_classifications",
                 "threshold_sources",
                 "classification_sources",
                 "method_sources",
                 "score_set_urn",
             },
         ),
         publication_identifier_associations=calibration_pub_assocs,
-        functional_ranges=[],
+        functional_classifications=[],
         created_by=user,
         modified_by=user,
     )  # type: ignore[call-arg]
 
-    for functional_range_create in calibration_create.functional_ranges or []:
+    for functional_range_create in calibration_create.functional_classifications or []:
         persisted_functional_range = create_functional_classification(
             db, functional_range_create, containing_calibration=calibration
         )
         db.add(persisted_functional_range)
-        calibration.functional_ranges.append(persisted_functional_range)
+        calibration.functional_classifications.append(persisted_functional_range)
 
     return calibration
 
@@ -406,15 +408,15 @@ async def modify_score_calibration(
     # Remove associations and calibrations that are no longer present
     for assoc in existing_assocs_map.values():
         db.delete(assoc)
-    for functional_classification in calibration.functional_ranges:
+    for functional_classification in calibration.functional_classifications:
         db.delete(functional_classification)
-    calibration.functional_ranges.clear()
+    calibration.functional_classifications.clear()
     db.flush()
     db.refresh(calibration)
 
     for attr, value in calibration_update.model_dump().items():
         if attr not in {
-            "functional_ranges",
+            "functional_classifications",
             "threshold_sources",
             "classification_sources",
             "method_sources",
@@ -430,12 +432,12 @@ async def modify_score_calibration(
     calibration.publication_identifier_associations = updated_assocs
     calibration.modified_by = user
 
-    for functional_range_update in calibration_update.functional_ranges or []:
+    for functional_range_update in calibration_update.functional_classifications or []:
         persisted_functional_range = create_functional_classification(
             db, functional_range_update, containing_calibration=calibration
         )
         db.add(persisted_functional_range)
-        calibration.functional_ranges.append(persisted_functional_range)
+        calibration.functional_classifications.append(persisted_functional_range)
 
     db.add(calibration)
     return calibration

src/mavedb/models/score_calibration.py

@@ -41,7 +41,7 @@ class ScoreCalibration(Base):
     baseline_score = Column(Float, nullable=True)
     baseline_score_description = Column(String, nullable=True)
 
-    functional_ranges: Mapped[list["ScoreCalibrationFunctionalClassification"]] = relationship(
+    functional_classifications: Mapped[list["ScoreCalibrationFunctionalClassification"]] = relationship(
         "ScoreCalibrationFunctionalClassification",
         back_populates="calibration",
         cascade="all, delete-orphan",

src/mavedb/models/score_calibration_functional_classification.py

@@ -11,7 +11,7 @@
 from mavedb.db.base import Base
 from mavedb.lib.validation.utilities import inf_or_float
 from mavedb.models.acmg_classification import ACMGClassification
-from mavedb.models.enums.functional_classification import FunctionalClassification
+from mavedb.models.enums.functional_classification import FunctionalClassification as FunctionalClassificationOptions
 from mavedb.models.score_calibration_functional_classification_variant_association import (
     score_calibration_functional_classification_variants_association_table,
 )
@@ -32,13 +32,15 @@ class ScoreCalibrationFunctionalClassification(Base):
     label = Column(String, nullable=False)
     description = Column(String, nullable=True)
 
-    classification = Column(
-        Enum(FunctionalClassification, native_enum=False, validate_strings=True, length=32),
+    functional_classification = Column(
+        Enum(FunctionalClassificationOptions, native_enum=False, validate_strings=True, length=32),
         nullable=False,
-        default=FunctionalClassification.not_specified,
+        default=FunctionalClassificationOptions.not_specified,
     )
 
     range = Column(JSONB(none_as_null=True), nullable=True)  # (lower_bound, upper_bound)
+    class_ = Column(String, nullable=True)
+
     inclusive_lower_bound = Column(Boolean, nullable=True, default=True)
     inclusive_upper_bound = Column(Boolean, nullable=True, default=False)
 

src/mavedb/scripts/load_calibration_csv.py

@@ -106,7 +106,7 @@
 from mavedb.scripts.environment import with_database_session
 from mavedb.view_models.acmg_classification import ACMGClassificationCreate
 from mavedb.view_models.publication_identifier import PublicationIdentifierCreate
-from mavedb.view_models.score_calibration import FunctionalRangeCreate, ScoreCalibrationCreate
+from mavedb.view_models.score_calibration import FunctionalClassificationCreate, ScoreCalibrationCreate
 
 BRNICH_PMID = "31892348"
 RANGE_PATTERN = re.compile(r"^\s*([\[(])\s*([^,]+)\s*,\s*([^\])]+)\s*([])])\s*$", re.IGNORECASE)
@@ -274,7 +274,7 @@ def build_ranges(row: Dict[str, str], infer_strengths: bool = True) -> Tuple[Lis
 
         label = row.get(f"class_{i}_name", "").strip()
         ranges.append(
-            FunctionalRangeCreate(
+            FunctionalClassificationCreate(
                 label=label,
                 classification=classification,
                 range=(lower, upper),
@@ -366,7 +366,7 @@ def main(db: Session, csv_path: str, delimiter: str, overwrite: bool, purge_publ
                     method_sources=method_publications,
                     classification_sources=calculation_publications,
                     research_use_only=False,
-                    functional_ranges=ranges,
+                    functional_classifications=ranges,
                     notes=calibration_notes,
                 )
             except Exception as e:  # broad to keep import running

src/mavedb/scripts/load_pp_style_calibration.py

@@ -183,7 +183,7 @@ def main(db: Session, archive_path: str, dataset_map: str, overwrite: bool) -> N
                     click.echo(f"      Overwriting existing '{calibration_name}' in Score Set {score_set.urn}")
 
             benign_has_lower_functional_scores = calibration_data.get("scoreset_flipped", False)
-            functional_ranges: List[score_calibration.FunctionalRangeCreate] = []
+            functional_classifications: List[score_calibration.FunctionalClassificationCreate] = []
             for points, range_data in calibration_data.get("point_ranges", {}).items():
                 if not range_data:
                     continue
@@ -212,7 +212,7 @@ def main(db: Session, archive_path: str, dataset_map: str, overwrite: bool) -> N
                     inclusive_lower = False
                     inclusive_upper = True if upper_bound is not None else False
 
-                functional_range = score_calibration.FunctionalRangeCreate(
+                functional_range = score_calibration.FunctionalClassificationCreate(
                     label=f"{ps_or_bs} {strength_label} ({points})",
                     classification="abnormal" if points > 0 else "normal",
                     range=range_data,
@@ -222,11 +222,11 @@ def main(db: Session, archive_path: str, dataset_map: str, overwrite: bool) -> N
                     inclusive_lower_bound=inclusive_lower,
                     inclusive_upper_bound=inclusive_upper,
                 )
-                functional_ranges.append(functional_range)
+                functional_classifications.append(functional_range)
 
             score_calibration_create = score_calibration.ScoreCalibrationCreate(
                 title=calibration_name,
-                functional_ranges=functional_ranges,
+                functional_classifications=functional_classifications,
                 research_use_only=True,
                 score_set_urn=score_set.urn,
                 calibration_metadata={"prior_probability_pathogenicity": calibration_data.get("prior", None)},