fix: operation error when scores were null

Adds some new utilities and associated tests that check base assumptions of functions which construct annotated variant objects

Author: bencap

src/mavedb/lib/annotation/annotate.py

@@ -13,14 +13,17 @@
 from ga4gh.va_spec.acmg_2015 import VariantPathogenicityEvidenceLine
 from ga4gh.va_spec.base.core import ExperimentalVariantFunctionalImpactStudyResult, Statement
 
-from mavedb.lib.annotation.constants import FUNCTIONAL_RANGES, CLINICAL_RANGES
 from mavedb.lib.annotation.evidence_line import acmg_evidence_line, functional_evidence_line
 from mavedb.lib.annotation.proposition import (
     mapped_variant_to_experimental_variant_clinical_impact_proposition,
     mapped_variant_to_experimental_variant_functional_impact_proposition,
 )
 from mavedb.lib.annotation.statement import mapped_variant_to_functional_statement
 from mavedb.lib.annotation.study_result import mapped_variant_to_experimental_variant_impact_study_result
+from mavedb.lib.annotation.util import (
+    can_annotate_variant_for_pathogenicity_evidence,
+    can_annotate_variant_for_functional_statement,
+)
 from mavedb.models.mapped_variant import MappedVariant
 
 
@@ -29,14 +32,7 @@ def variant_study_result(mapped_variant: MappedVariant) -> ExperimentalVariantFu
 
 
 def variant_functional_impact_statement(mapped_variant: MappedVariant) -> Optional[Statement]:
-    if mapped_variant.variant.score_set.score_ranges is None:
-        return None
-
-    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
-        for range_key in FUNCTIONAL_RANGES
-    ):
+    if not can_annotate_variant_for_functional_statement(mapped_variant):
         return None
 
     # TODO#494: Add support for multiple functional evidence lines. If a score set has multiple ranges
@@ -51,14 +47,7 @@ def variant_functional_impact_statement(mapped_variant: MappedVariant) -> Option
 def variant_pathogenicity_evidence(
     mapped_variant: MappedVariant,
 ) -> Optional[VariantPathogenicityEvidenceLine]:
-    if mapped_variant.variant.score_set.score_ranges is None:
-        return None
-
-    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
-        for range_key in CLINICAL_RANGES
-    ):
+    if not can_annotate_variant_for_pathogenicity_evidence(mapped_variant):
         return None
 
     study_result = mapped_variant_to_experimental_variant_impact_study_result(mapped_variant)

src/mavedb/lib/annotation/classification.py

@@ -40,7 +40,13 @@ def functional_classification_of_variant(
         )
 
     # This property of this column is guaranteed to be defined.
-    functional_score: float = mapped_variant.variant.data["score_data"]["score"]  # type: ignore
+    functional_score: Optional[float] = mapped_variant.variant.data["score_data"]["score"]  # type: ignore
+    if functional_score is None:
+        raise ValueError(
+            f"Variant {mapped_variant.variant.urn} does not have a functional score."
+            " 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:
@@ -72,7 +78,12 @@ def pillar_project_clinical_classification_of_variant(
         )
 
     # This property of this column is guaranteed to be defined.
-    functional_score: float = mapped_variant.variant.data["score_data"]["score"]  # type: ignore
+    functional_score: Optional[float] = mapped_variant.variant.data["score_data"]["score"]  # type: ignore
+    if functional_score is None:
+        raise ValueError(
+            f"Variant {mapped_variant.variant.urn} does not have a functional score."
+            " 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)

src/mavedb/lib/annotation/util.py

@@ -8,6 +8,7 @@
     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
 
@@ -137,3 +138,114 @@ def variation_from_mapped_variant(mapped_variant: MappedVariant) -> MolecularVar
         )
 
     return vrs_object_from_mapped_variant(mapped_variant.post_mapped)
+
+
+def _can_annotate_variant_base_assumptions(mapped_variant: MappedVariant) -> bool:
+    """
+    Check if a mapped variant meets the basic requirements for annotation.
+
+    This function validates that a mapped variant has the necessary data
+    to proceed with annotation by checking for a valid score value.
+
+    Args:
+        mapped_variant (MappedVariant): The mapped variant to check for
+            annotation eligibility.
+
+    Returns:
+        bool: True if the variant can be annotated (has score ranges and
+            a non-None score), False otherwise.
+    """
+    # This property is guaranteed to exist for all variants.
+    if mapped_variant.variant.data["score_data"]["score"] is None:  # type: ignore
+        return False
+
+    return True
+
+
+def _variant_score_ranges_have_required_keys_for_annotation(
+    mapped_variant: MappedVariant, key_options: list[str]
+) -> bool:
+    """
+    Check if a mapped variant's score set contains any of the required score range keys for annotation and is present.
+
+    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.
+
+    Returns:
+        bool: False if none of the required keys are found or if all found keys have None values.
+              Returns True (implicitly) if at least one required key exists with a non-None value.
+    """
+    if mapped_variant.variant.score_set.score_ranges 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
+        for range_key in key_options
+    ):
+        return False
+
+    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.
+
+    Args:
+        mapped_variant (MappedVariant): The mapped variant object to evaluate
+            for pathogenicity evidence annotation eligibility.
+
+    Returns:
+        bool: True if the variant can be annotated for pathogenicity evidence,
+            False otherwise.
+
+    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_for_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_for_annotation(mapped_variant, CLINICAL_RANGES):
+        return False
+
+    return True
+
+
+def can_annotate_variant_for_functional_statement(mapped_variant: MappedVariant) -> bool:
+    """
+    Determine if a mapped variant can be annotated for functional statements.
+
+    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.
+
+    Args:
+        mapped_variant (MappedVariant): The variant object to check for annotation
+            eligibility, containing mapping information and score data.
+
+    Returns:
+        bool: True if the variant can be annotated for functional statements,
+            False otherwise.
+
+    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
+    """
+    if not _can_annotate_variant_base_assumptions(mapped_variant):
+        return False
+    if not _variant_score_ranges_have_required_keys_for_annotation(mapped_variant, FUNCTIONAL_RANGES):
+        return False
+
+    return True

src/mavedb/routers/mapped_variant.py

@@ -139,12 +139,12 @@ async def show_mapped_variant_functional_impact_statement(
 
     if not functional_impact:
         logger.info(
-            msg="Could not construct a functional impact statement for this mapped variant; No score range evidence exists for this score set.",
+            msg="Could not construct a functional impact statement for this mapped variant. Variant does not have sufficient evidence to evaluate its functional impact.",
             extra=logging_context(),
         )
         raise HTTPException(
             status_code=404,
-            detail=f"Could not construct a functional impact statement for mapped variant {urn}: No score range evidence found",
+            detail=f"Could not construct a functional impact statement for mapped variant {urn}. Variant does not have sufficient evidence to evaluate its functional impact.",
         )
 
     return functional_impact
@@ -180,12 +180,12 @@ async def show_mapped_variant_acmg_evidence_line(
 
     if not pathogenicity_evidence:
         logger.info(
-            msg="Could not construct a pathogenicity evidence line for this mapped variant; No calibrations exist for this score set.",
+            msg="Could not construct a pathogenicity evidence line for this mapped variant; Variant does not have sufficient evidence to evaluate its pathogenicity.",
             extra=logging_context(),
         )
         raise HTTPException(
             status_code=404,
-            detail=f"Could not construct a pathogenicity evidence line for mapped variant {urn}; No calibrations exist for this score set",
+            detail=f"Could not construct a pathogenicity evidence line for mapped variant {urn}; Variant does not have sufficient evidence to evaluate its pathogenicity.",
         )
 
     return pathogenicity_evidence

tests/lib/annotation/test_annotate.py

@@ -19,6 +19,13 @@ def test_variant_functional_impact_statement_no_score_ranges(mock_mapped_variant
     assert result is None
 
 
+def test_variant_functional_impact_statement_no_score(mock_mapped_variant):
+    mock_mapped_variant.variant.data = {"score_data": {"score": None}}
+    result = variant_functional_impact_statement(mock_mapped_variant)
+
+    assert result is None
+
+
 def test_variant_functional_impact_statement_with_score_ranges(mock_mapped_variant):
     result = variant_functional_impact_statement(mock_mapped_variant)
 
@@ -40,6 +47,13 @@ def test_variant_pathogenicity_evidence_no_score_ranges_no_thresholds(mock_mappe
     assert result is None
 
 
+def test_variant_pathogenicity_evidence_no_score(mock_mapped_variant):
+    mock_mapped_variant.variant.data = {"score_data": {"score": None}}
+    result = variant_pathogenicity_evidence(mock_mapped_variant)
+
+    assert result is None
+
+
 def test_variant_pathogenicity_evidence_no_score_ranges_with_thresholds(mock_mapped_variant):
     mock_mapped_variant.variant.score_set.score_ranges.pop("investigator_provided")
     result = variant_pathogenicity_evidence(mock_mapped_variant)

tests/lib/annotation/test_util.py

@@ -1,9 +1,16 @@
 import pytest
 
 from mavedb.lib.annotation.exceptions import MappingDataDoesntExistException
-from mavedb.lib.annotation.util import variation_from_mapped_variant
+from mavedb.lib.annotation.util import (
+    variation_from_mapped_variant,
+    _can_annotate_variant_base_assumptions,
+    _variant_score_ranges_have_required_keys_for_annotation,
+    can_annotate_variant_for_functional_statement,
+    can_annotate_variant_for_pathogenicity_evidence,
+)
 
 from tests.helpers.constants import TEST_VALID_POST_MAPPED_VRS_ALLELE, TEST_SEQUENCE_LOCATION_ACCESSION
+from unittest.mock import patch
 
 
 @pytest.mark.parametrize(
@@ -24,3 +31,99 @@ def test_variation_from_mapped_variant_no_post_mapped(mock_mapped_variant):
 
     with pytest.raises(MappingDataDoesntExistException):
         variation_from_mapped_variant(mock_mapped_variant)
+
+
+## Test base annotation assumptions
+
+
+def test_base_assumption_check_returns_false_when_score_is_none(mock_mapped_variant):
+    mock_mapped_variant.variant.data = {"score_data": {"score": None}}
+
+    assert _can_annotate_variant_base_assumptions(mock_mapped_variant) is False
+
+
+def test_base_assumption_check_returns_true_when_all_conditions_met(mock_mapped_variant):
+    assert _can_annotate_variant_base_assumptions(mock_mapped_variant) is True
+
+
+## Test variant score ranges have required keys for annotation
+
+
+def test_score_range_check_returns_false_when_keys_are_none(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = None
+    key_options = ["required_key1", "required_key2"]
+
+    assert _variant_score_ranges_have_required_keys_for_annotation(mock_mapped_variant, key_options) is False
+
+
+def test_score_range_check_returns_false_when_no_keys_present(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = {"other_key": "value"}
+    key_options = ["required_key1", "required_key2"]
+
+    assert _variant_score_ranges_have_required_keys_for_annotation(mock_mapped_variant, key_options) is False
+
+
+def test_score_range_check_returns_false_when_key_present_but_value_is_none(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = {"required_key1": None}
+    key_options = ["required_key1", "required_key2"]
+
+    assert _variant_score_ranges_have_required_keys_for_annotation(mock_mapped_variant, key_options) is False
+
+
+def test_score_range_check_returns_none_when_at_least_one_key_has_value(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = {"required_key1": "value"}
+    key_options = ["required_key1", "required_key2"]
+
+    assert _variant_score_ranges_have_required_keys_for_annotation(mock_mapped_variant, key_options) is True
+
+
+## Test clinical range check
+
+
+def test_clinical_range_check_returns_false_when_base_assumptions_fail(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = None
+    result = can_annotate_variant_for_pathogenicity_evidence(mock_mapped_variant)
+
+    assert result is False
+
+
+@pytest.mark.parametrize("clinical_ranges", [["clinical_range"], ["other_clinical_range"]])
+def test_clinical_range_check_returns_false_when_clinical_ranges_check_fails(mock_mapped_variant, clinical_ranges):
+    mock_mapped_variant.variant.score_set.score_ranges = {"unrelated_key": "value"}
+
+    with patch("mavedb.lib.annotation.util.CLINICAL_RANGES", clinical_ranges):
+        result = can_annotate_variant_for_pathogenicity_evidence(mock_mapped_variant)
+
+    assert result is False
+
+
+# The default mock_mapped_variant object should be valid
+def test_clinical_range_check_returns_true_when_all_conditions_met(mock_mapped_variant):
+    assert can_annotate_variant_for_pathogenicity_evidence(mock_mapped_variant) is True
+
+
+## Test functional range check
+
+
+def test_functional_range_check_returns_false_when_base_assumptions_fail(mock_mapped_variant):
+    mock_mapped_variant.variant.score_set.score_ranges = None
+    result = can_annotate_variant_for_functional_statement(mock_mapped_variant)
+
+    assert result is False
+
+
+@pytest.mark.parametrize("functional_ranges", [["functional_range"], ["other_functional_range"]])
+def test_functional_range_check_returns_false_when_functional_ranges_check_fails(
+    mock_mapped_variant, functional_ranges
+):
+    mock_mapped_variant.variant.score_set.score_ranges = {"unrelated_key": "value"}
+
+    with patch("mavedb.lib.annotation.util.FUNCTIONAL_RANGES", functional_ranges):
+        result = can_annotate_variant_for_functional_statement(mock_mapped_variant)
+
+    assert result is False
+
+
+# The default mock_mapped_variant object should be valid
+def test_functional_range_check_returns_true_when_all_conditions_met(mock_mapped_variant):
+    assert can_annotate_variant_for_functional_statement(mock_mapped_variant) is True

tests/routers/test_mapped_variants.py

@@ -419,7 +419,7 @@ def test_cannot_show_mapped_variant_functional_impact_statement_when_no_score_ra
 
     assert response.status_code == 404
     assert (
-        f"Could not construct a functional impact statement for mapped variant {score_set['urn']}#1: No score range evidence found"
+        f"Could not construct a functional impact statement for mapped variant {score_set['urn']}#1. Variant does not have sufficient evidence to evaluate its functional impact"
         in response_data["detail"]
     )
 
@@ -583,7 +583,7 @@ def test_cannot_show_mapped_variant_clinical_evidence_line_when_no_score_calibra
 
     assert response.status_code == 404
     assert (
-        f"Could not construct a pathogenicity evidence line for mapped variant {score_set['urn']}#1; No calibrations exist"
+        f"Could not construct a pathogenicity evidence line for mapped variant {score_set['urn']}#1; Variant does not have sufficient evidence to evaluate its pathogenicity"
         in response_data["detail"]
     )