feat(fusion): add clinical-test signal normalisers (MMSE/MoCA/UPDRS/gait/age)

src/fusion/clinical.py

@@ -0,0 +1,38 @@
+"""Map raw clinical-test scores to a unitless signal in [-1, 1].
+
++1 means the test strongly supports the disease being present.
+-1 means it strongly supports the disease being absent.
+"""
+from __future__ import annotations
+
+
+def _linear_map(value: float, low: float, high: float, *, invert: bool) -> float:
+    """Map `value` from [low, high] to [-1, 1]. If invert, flip sign."""
+    if high == low:
+        return 0.0
+    clipped = max(low, min(high, value))
+    norm = (clipped - low) / (high - low)
+    signal = 2.0 * norm - 1.0
+    return -signal if invert else signal
+
+
+def mmse_to_signal(score: float) -> float:
+    """MMSE: 30 = healthy (-1), 18 = severe (+1), 24 = mild cutoff (0)."""
+    return _linear_map(score, low=18.0, high=30.0, invert=True)
+
+
+def moca_to_signal(score: float) -> float:
+    """MoCA: same scale as MMSE."""
+    return _linear_map(score, low=18.0, high=30.0, invert=True)
+
+
+def updrs_to_signal(score: float) -> float:
+    return _linear_map(score, low=0.0, high=199.0, invert=False)
+
+
+def gait_to_signal(speed_m_s: float) -> float:
+    return _linear_map(speed_m_s, low=0.0, high=1.4, invert=True)
+
+
+def age_to_signal(years: float) -> float:
+    return _linear_map(years, low=30.0, high=90.0, invert=False)

tests/fusion/test_clinical.py

@@ -0,0 +1,54 @@
+"""Tests for src.fusion.clinical — per-test signal normalisers.
+
+Convention: signal in [-1, 1] where +1 = strong evidence the disease IS
+present and -1 = strong evidence it is NOT present.
+"""
+from __future__ import annotations
+
+import pytest
+
+from src.fusion import clinical
+
+
+class TestMMSE:
+    def test_perfect_score_signals_no_alzheimers(self) -> None:
+        assert clinical.mmse_to_signal(30.0) == pytest.approx(-1.0)
+
+    def test_severely_impaired_signals_alzheimers(self) -> None:
+        assert clinical.mmse_to_signal(0.0) == pytest.approx(1.0)
+
+    def test_borderline_24_is_near_neutral_slightly_positive(self) -> None:
+        sig = clinical.mmse_to_signal(24.0)
+        assert -0.1 < sig < 0.5
+
+
+class TestMoCA:
+    def test_perfect_signals_negative(self) -> None:
+        assert clinical.moca_to_signal(30.0) == pytest.approx(-1.0)
+
+    def test_zero_signals_positive(self) -> None:
+        assert clinical.moca_to_signal(0.0) == pytest.approx(1.0)
+
+
+class TestUPDRS:
+    def test_zero_signals_no_parkinsons(self) -> None:
+        assert clinical.updrs_to_signal(0.0) == pytest.approx(-1.0)
+
+    def test_max_signals_parkinsons(self) -> None:
+        assert clinical.updrs_to_signal(199.0) == pytest.approx(1.0, abs=1e-3)
+
+
+class TestGait:
+    def test_fast_walker_signals_negative(self) -> None:
+        assert clinical.gait_to_signal(1.4) < -0.4
+
+    def test_slow_walker_signals_positive(self) -> None:
+        assert clinical.gait_to_signal(0.3) > 0.4
+
+
+class TestAge:
+    def test_young_signals_negative(self) -> None:
+        assert clinical.age_to_signal(30.0) < -0.4
+
+    def test_elderly_signals_positive(self) -> None:
+        assert clinical.age_to_signal(85.0) > 0.4