Compound scoring: Cap rankscore values to (min, ) range

* compound scoring: When correcting rankscore, cap to min bound
* Update READMEs on compound scoring

Author: torbjorgen

docs/commands/score-compounds.md

@@ -0,0 +1,20 @@
+# Score Compounds
+
+This module performs ranking of compound variants.
+
+During the ranking of these compounds the rank score might be modified in place.
+See `genmod/score_variants/compound_scorer.py:L248`.
+
+## Rankscore Capping
+Since the rank scores are modified in place in this module, there's a risk
+that the modified rank score might fall outside the valid range of normalization
+bounds `(MIN, MAX)` that was established in the `score_variants` module.
+
+This applies to variants belonging to the lower range of rank scores.
+
+When this happens, the modified rank score is capped to  `(MIN, )` if it's of `RankScore` type
+or `(0, 1)` if it's of `RankScoreNormalized` type.
+
+In previous Genmod versions there were no such capping rule in effect.
+Earlier ranked variants from `compounds` module might show lower rank
+scores compared to this implementation.

docs/commands/score-variants.md

@@ -13,4 +13,7 @@ and `CategorySumMin` is the sum of minimal score values for all categories,
 i. e `CategorySumMin = SUM(CategoryMin_n) for 0...n categories`.
 The same applies to `CategorySumMax = SUM(CategoryMax_n) for 0...n categories`.
 
-Refer to `score_variants.py::score()` method for implementation details.
+Refer to `score_variants.py::score()` method for implementation details.
+
+Additionally, also read in the `score-compounds.md` on compound scoring step that affects
+final rank score values.

genmod/score_variants/cap_rank_score_to_min_bound.py

@@ -0,0 +1,27 @@
+from genmod.score_variants.score_variant import MIN_SCORE_NORMALIZED
+from genmod.score_variants.rank_score_variant_definitions import RANK_SCORE_TYPE_NAMES
+
+
+def cap_rank_score_to_min_bound(rank_score_type: str,
+                                rank_score,
+                                min_rank_score_value: float) -> float:
+    """
+    Caps rank_score to fall withing MIN bound of normalized rank score, if it's outside valid range.
+    Args:
+        rank_score_type: Type of rank score
+        rank_score: The value to bounds check
+        min_rank_score_value: Minimum allowed bound according to rank score normalization
+    Returns:
+        Bounds capped rank score, either to min_rank_score_value (if RankScore)
+        or MIN_SCORE_NORMALIZED if RankScoreNormalized type.
+    """
+
+    if rank_score_type not in set(RANK_SCORE_TYPE_NAMES):
+        raise ValueError(f'Unknown rank score type {rank_score_type}')
+
+    if rank_score_type == 'RankScoreNormalized':
+        min_rank_score_value = MIN_SCORE_NORMALIZED
+
+    if rank_score < min_rank_score_value:
+        return min_rank_score_value
+    return rank_score

genmod/score_variants/compound_scorer.py

@@ -23,6 +23,7 @@
 
 from genmod.score_variants.score_variant import as_normalized_max_min, MIN_SCORE_NORMALIZED, MAX_SCORE_NORMALIZED
 from genmod.score_variants.rank_score_variant_definitions import RANK_SCORE_TYPE_NAMES
+from genmod.score_variants.cap_rank_score_to_min_bound import cap_rank_score_to_min_bound
 
 logger = logging.getLogger(__name__)
 
@@ -249,6 +250,12 @@ def run(self):
                                                                               min_rank_score_value=variant_rankscore_normalization_bounds[variant_id][0],
                                                                               max_rank_score_value=variant_rankscore_normalization_bounds[variant_id][1]
                                                                               )
+                            # In case the current_rank_score falls outside normalization bounds after modification,
+                            # cap it to within the MIN normalization bound.
+                            current_rank_score = cap_rank_score_to_min_bound(rank_score_type=rank_score_type,
+                                                                             rank_score=current_rank_score,
+                                                                             min_rank_score_value=variant_rankscore_normalization_bounds[variant_id][0]
+                                                                             )
 
                         for compound_id in compound_list:
                             logger.debug("Checking compound {0}".format(compound_id))

tests/score_variants/test_rankscore_capping.py

@@ -0,0 +1,31 @@
+from genmod.score_variants.cap_rank_score_to_min_bound import cap_rank_score_to_min_bound, MIN_SCORE_NORMALIZED
+
+
+MIN_SCORE: float = -5.0
+
+
+def test_rankscore_normalized_capping():
+    """
+    Test the MIN normalization bounds capping of rankscore normalized.
+    """
+    # GIVEN a normalized rank score
+    # WHEN running cap method
+    # THEN expect rank score to be larger than min bound
+    for rank_score_normalized in range(-10, 10):
+        assert cap_rank_score_to_min_bound(rank_score_type='RankScoreNormalized',
+                                           rank_score=float(rank_score_normalized),
+                                           min_rank_score_value=MIN_SCORE_NORMALIZED) >= MIN_SCORE_NORMALIZED
+
+
+def test_rankscore_capping():
+    """
+    Test the MIN normalization bounds capping of rankscore.
+    """
+
+    # GIVEN a rank score
+    # WHEN running cap method
+    # THEN expect rank score to be larger than min bound
+    for rank_score in range(-10, 10):
+        assert cap_rank_score_to_min_bound(rank_score_type='RankScore',
+                                           rank_score=rank_score,
+                                           min_rank_score_value=MIN_SCORE) >= MIN_SCORE