# HANDROM

**Hand range-of-motion and functional impairment stratification in rheumatic disease**

## What it does

HANDROM is a transparent clinical skill that estimates hand impairment severity from range-of-motion loss, grip and pinch weakness, inflammatory burden, pain/stiffness, and functional difficulty.

## Inputs

- Diagnosis context
- Age
- Wrist, MCP, PIP, and thumb ROM
- Grip strength
- Pinch strength
- Pain VAS
- Swollen and tender joint counts
- Morning stiffness duration
- Dressing, jar-opening, and writing difficulty
- Optional CRP
- Contracture or digital ischemia/red-flag context
- Optional QuickDASH

## Outputs

- Hand impairment score on a 0-100 scale
- Category: MINIMAL / MILD / MODERATE / SEVERE / CRITICAL
- 95% uncertainty interval
- Referral recommendation
- Red-flag notes
- Domain-level contribution table

## Why it matters

Hand dysfunction is a real clinical endpoint in rheumatoid arthritis, systemic sclerosis, psoriatic arthritis, and hand osteoarthritis. A transparent score helps clinicians separate inflammatory activity, structural limitation, and functional disability when deciding on therapy, occupational therapy, splinting, or further evaluation.

## Run

```bash
python3 handrom.py
```

## Demo scenarios

1. Mild osteoarthritis stiffness
2. Active RA hand synovitis
3. Systemic sclerosis with contracture and digital ischemia

## Limitations

- Heuristic support tool, not a validated replacement for formal hand-function instruments
- Does not replace occupational therapy assessment
- Does not diagnose ischemia, infection, tendon rupture, or acute neurologic injury
- ROM estimates are only as good as the measured inputs

## References

1. Sandqvist G, Nilsson J-Å, Wuttge DM, Hesselstrand R. Development of a modified hand mobility in scleroderma (HAMIS) test and its potential as an outcome measure in systemic sclerosis. *J Rheumatol.* 2014;41(11):2186-2192. DOI: 10.3899/jrheum.140286
2. Sandqvist G, Wuttge DM, Hesselstrand R. The Modified Hand Mobility in Scleroderma Test and Skin Involvement - A Followup Study. *J Rheumatol.* 2016;43(7):1356-1362. DOI: 10.3899/jrheum.151142
3. Shiratori AP, Iop R da R, Borges Júnior NG, Domenech SC, Gevaerd M da S. Evaluation protocols of hand grip strength in individuals with rheumatoid arthritis: a systematic review. *Rev Bras Reumatol.* 2014;54(2):140-147. DOI: 10.1016/j.rbre.2014.03.009
4. Alomari MA, Keewan EF, Shammaa RA, et al. Vascular function and handgrip strength in rheumatoid arthritis patients. *ScientificWorldJournal.* 2012;2012:580863. DOI: 10.1100/2012/580863
5. QuickDASH systematic review. *J Phys Ther Sci.* 2014. DOI: 10.1016/j.jphys.2014.06.003
6. The thickness of the A1 pulleys reflects the disability of hand mobility in scleroderma. *Eur J Radiol.* 2010. DOI: 10.1016/j.ejrad.2010.05.013


## Executable Code

```python
#!/usr/bin/env python3
"""
HANDROM: Hand Range-of-Motion and Functional Impairment Stratification in Rheumatic Disease

Authors: Dr. Erick Zamora-Tehozol, DNAI, RheumaAI
License: MIT

Purpose:
Estimate hand impairment severity from range-of-motion loss, grip/pinch weakness,
inflammatory burden, pain/stiffness, and functional difficulty. Intended for
transparent clinical framing and occupational-therapy referral support.

References:
  - Sandqvist G, et al. J Rheumatol. 2014;41(11):2186-2192. DOI: 10.3899/jrheum.140286
  - Sandqvist G, Wuttge DM, Hesselstrand R. J Rheumatol. 2016;43(7):1356-1362. DOI: 10.3899/jrheum.151142
  - Roque LCS, et al. J Phys Ther Sci / related rehab trial. DOI: 10.1177/02692155211038728
  - Shiratori AP, et al. Rev Bras Reumatol. 2014;54(2):140-147. DOI: 10.1016/j.rbre.2014.03.009
  - Alomari MA, et al. ScientificWorldJournal. 2012. DOI: 10.1100/2012/580863
  - Ferruccio? (QuickDASH review) J Phys. 2014. DOI: 10.1016/j.jphys.2014.06.003
"""

from __future__ import annotations

from dataclasses import dataclass, field
import math
import random
from typing import Dict, List


NORMAL_ROM = {
    "wrist_extension_deg": 70.0,
    "wrist_flexion_deg": 80.0,
    "mcp_flexion_deg": 90.0,
    "pip_flexion_deg": 100.0,
    "thumb_abduction_deg": 60.0,
}


@dataclass
class HandROMInput:
    diagnosis: str
    age: int
    wrist_extension_deg: float
    wrist_flexion_deg: float
    mcp_flexion_deg: float
    pip_flexion_deg: float
    thumb_abduction_deg: float
    grip_strength_kg: float
    pinch_strength_kg: float
    pain_vas: float
    swollen_joints: int
    tender_joints: int
    morning_stiffness_min: float
    dressing_difficulty_0_10: float
    jar_opening_difficulty_0_10: float
    writing_difficulty_0_10: float
    crp_mg_l: float = 0.0
    contracture_present: bool = False
    digital_ulcer_or_ischemia: bool = False
    quickdash_0_100: float | None = None


@dataclass
class DomainScore:
    name: str
    raw: float
    weighted: float
    weight: float
    detail: str


@dataclass
class HandROMResult:
    score: float
    category: str
    confidence_interval: tuple[float, float]
    recommendation: str
    notes: List[str]
    domains: List[DomainScore] = field(default_factory=list)


WEIGHTS = {
    "rom": 0.30,
    "strength": 0.20,
    "inflammation": 0.20,
    "pain_stiffness": 0.15,
    "function": 0.15,
}


def _clamp(value: float, low: float = 0.0, high: float = 100.0) -> float:
    return max(low, min(high, value))


def _score_rom(case: HandROMInput) -> tuple[float, str]:
    deficits = []
    for field, normal in NORMAL_ROM.items():
        observed = getattr(case, field)
        deficit = _clamp((normal - observed) / normal * 100.0, 0.0, 100.0)
        deficits.append(deficit)
    raw = sum(deficits) / len(deficits)
    return raw, "Average deficit across wrist/finger/thumb ROM"


def _score_strength(case: HandROMInput) -> tuple[float, str]:
    grip = case.grip_strength_kg
    pinch = case.pinch_strength_kg

    if grip >= 30 and pinch >= 8:
        raw = 0
    elif grip >= 20 and pinch >= 6:
        raw = 25
    elif grip >= 12 and pinch >= 4:
        raw = 55
    else:
        raw = 85

    if case.diagnosis.lower().startswith("ssc") or "scleroder" in case.diagnosis.lower():
        raw += 5
    return _clamp(raw), f"Grip {grip:.1f} kg, pinch {pinch:.1f} kg"


def _score_inflammation(case: HandROMInput) -> tuple[float, str]:
    swollen = _clamp(case.swollen_joints / 10.0 * 100.0)
    tender = _clamp(case.tender_joints / 10.0 * 100.0)
    stiffness = _clamp(case.morning_stiffness_min / 120.0 * 100.0)
    crp = 0.0 if case.crp_mg_l <= 5 else _clamp((case.crp_mg_l - 5) / 20.0 * 100.0)
    raw = 0.35 * swollen + 0.25 * tender + 0.25 * stiffness + 0.15 * crp
    if "ra" in case.diagnosis.lower() or "psa" in case.diagnosis.lower():
        raw += 5 if case.swollen_joints > 0 else 0
    return _clamp(raw), f"Swollen {case.swollen_joints}, tender {case.tender_joints}, stiffness {case.morning_stiffness_min:.0f} min"


def _score_pain_stiffness(case: HandROMInput) -> tuple[float, str]:
    pain = _clamp(case.pain_vas / 10.0 * 100.0)
    stiffness = _clamp(case.morning_stiffness_min / 120.0 * 100.0)
    raw = 0.65 * pain + 0.35 * stiffness
    return _clamp(raw), f"Pain VAS {case.pain_vas:.1f}/10; morning stiffness {case.morning_stiffness_min:.0f} min"


def _score_function(case: HandROMInput) -> tuple[float, str]:
    if case.quickdash_0_100 is not None:
        quickdash = _clamp(case.quickdash_0_100)
        raw = quickdash
        detail = f"QuickDASH {quickdash:.1f}/100"
    else:
        avg_task = (
            case.dressing_difficulty_0_10
            + case.jar_opening_difficulty_0_10
            + case.writing_difficulty_0_10
        ) / 3.0
        raw = _clamp(avg_task * 10.0)
        detail = (
            f"Dressing {case.dressing_difficulty_0_10:.1f}/10, "
            f"jar opening {case.jar_opening_difficulty_0_10:.1f}/10, "
            f"writing {case.writing_difficulty_0_10:.1f}/10"
        )

    if case.contracture_present:
        raw += 10
    if case.digital_ulcer_or_ischemia:
        raw += 15
    return _clamp(raw), detail


def _diagnosis_modifier(case: HandROMInput) -> float:
    d = case.diagnosis.lower()
    mod = 0.0
    if "ssc" in d or "scleroder" in d:
        mod += 6.0
    if "ra" in d:
        mod += 4.0 if case.swollen_joints > 0 else 0.0
    if "psa" in d or "psori" in d:
        mod += 3.0
    if "oa" in d:
        mod += 2.0
    if case.digital_ulcer_or_ischemia:
        mod += 8.0
    return mod


def compute_handrom(case: HandROMInput, n_simulations: int = 5000, seed: int = 42) -> HandROMResult:
    scorers = [
        ("rom", _score_rom),
        ("strength", _score_strength),
        ("inflammation", _score_inflammation),
        ("pain_stiffness", _score_pain_stiffness),
        ("function", _score_function),
    ]

    domains: List[DomainScore] = []
    total = 0.0
    for name, scorer in scorers:
        raw, detail = scorer(case)
        weighted = raw * WEIGHTS[name]
        total += weighted
        domains.append(DomainScore(name=name, raw=round(raw, 1), weighted=round(weighted, 1), weight=WEIGHTS[name], detail=detail))

    total += _diagnosis_modifier(case)
    score = round(_clamp(total), 1)

    rng = random.Random(seed)
    sims = []
    for _ in range(n_simulations):
        noisy = HandROMInput(
            diagnosis=case.diagnosis,
            age=case.age,
            wrist_extension_deg=max(0.0, case.wrist_extension_deg + rng.gauss(0, 3.0)),
            wrist_flexion_deg=max(0.0, case.wrist_flexion_deg + rng.gauss(0, 3.0)),
            mcp_flexion_deg=max(0.0, case.mcp_flexion_deg + rng.gauss(0, 4.0)),
            pip_flexion_deg=max(0.0, case.pip_flexion_deg + rng.gauss(0, 4.0)),
            thumb_abduction_deg=max(0.0, case.thumb_abduction_deg + rng.gauss(0, 3.0)),
            grip_strength_kg=max(0.0, case.grip_strength_kg + rng.gauss(0, 2.0)),
            pinch_strength_kg=max(0.0, case.pinch_strength_kg + rng.gauss(0, 0.8)),
            pain_vas=_clamp(case.pain_vas + rng.gauss(0, 0.7), 0, 10),
            swollen_joints=max(0, int(round(case.swollen_joints + rng.gauss(0, 0.6)))),
            tender_joints=max(0, int(round(case.tender_joints + rng.gauss(0, 1.0)))),
            morning_stiffness_min=max(0.0, case.morning_stiffness_min + rng.gauss(0, 12.0)),
            dressing_difficulty_0_10=_clamp(case.dressing_difficulty_0_10 + rng.gauss(0, 0.8), 0, 10),
            jar_opening_difficulty_0_10=_clamp(case.jar_opening_difficulty_0_10 + rng.gauss(0, 0.8), 0, 10),
            writing_difficulty_0_10=_clamp(case.writing_difficulty_0_10 + rng.gauss(0, 0.8), 0, 10),
            crp_mg_l=max(0.0, case.crp_mg_l + rng.gauss(0, 1.5)),
            contracture_present=case.contracture_present,
            digital_ulcer_or_ischemia=case.digital_ulcer_or_ischemia,
            quickdash_0_100=case.quickdash_0_100,
        )
        total_noisy = 0.0
        for name, scorer in scorers:
            raw, _ = scorer(noisy)
            total_noisy += raw * WEIGHTS[name]
        total_noisy += _diagnosis_modifier(noisy)
        sims.append(_clamp(total_noisy))

    sims.sort()
    ci_lower = round(sims[int(0.025 * n_simulations)], 1)
    ci_upper = round(sims[int(0.975 * n_simulations)], 1)

    if score < 15:
        category = "MINIMAL"
        recommendation = "Home exercise, ergonomic advice, and routine follow-up."
    elif score < 30:
        category = "MILD"
        recommendation = "Consider hand therapy and symptom-guided reassessment."
    elif score < 50:
        category = "MODERATE"
        recommendation = "Refer to occupational/hand therapy and reassess inflammatory control."
    elif score < 70:
        category = "SEVERE"
        recommendation = "Urgent hand therapy plus rheumatology review for active inflammatory or fibrotic limitation."
    else:
        category = "CRITICAL"
        recommendation = "Urgent evaluation for severe contracture, ischemia, infection, or rapidly progressive disability."

    notes = []
    if case.contracture_present:
        notes.append("Fixed contracture materially increases functional burden.")
    if case.digital_ulcer_or_ischemia:
        notes.append("Digital ischemia/ulcer is a red flag and should not be managed as simple stiffness.")
    if case.quickdash_0_100 is not None and case.quickdash_0_100 >= 50:
        notes.append("QuickDASH suggests substantial upper-extremity disability.")
    if case.swollen_joints > 0 and ("ra" in case.diagnosis.lower() or "psa" in case.diagnosis.lower()):
        notes.append("Active synovitis may be modifiable with disease control.")
    if "ssc" in case.diagnosis.lower() or "scleroder" in case.diagnosis.lower():
        notes.append("Systemic sclerosis patterns often mix fibrosis, vasculopathy, and tendon involvement.")

    return HandROMResult(
        score=score,
        category=category,
        confidence_interval=(ci_lower, ci_upper),
        recommendation=recommendation,
        notes=notes,
        domains=domains,
    )


def print_result(label: str, result: HandROMResult) -> None:
    print("\n" + "=" * 70)
    print(label)
    print("=" * 70)
    print(f"Score: {result.score}/100 [{result.category}]")
    print(f"95% CI: [{result.confidence_interval[0]}, {result.confidence_interval[1]}]")
    print(f"Recommendation: {result.recommendation}")
    print("\nDomains:")
    for d in result.domains:
        print(f"- {d.name}: raw {d.raw:.1f} × w {d.weight:.2f} = {d.weighted:.1f} ({d.detail})")
    if result.notes:
        print("\nNotes:")
        for note in result.notes:
            print(f"* {note}")


def demo() -> None:
    cases = [
        (
            "Scenario 1 — Mild osteoarthritis stiffness",
            HandROMInput(
                diagnosis="OA",
                age=67,
                wrist_extension_deg=62,
                wrist_flexion_deg=75,
                mcp_flexion_deg=88,
                pip_flexion_deg=95,
                thumb_abduction_deg=55,
                grip_strength_kg=22,
                pinch_strength_kg=6.2,
                pain_vas=3.0,
                swollen_joints=0,
                tender_joints=1,
                morning_stiffness_min=15,
                dressing_difficulty_0_10=2.0,
                jar_opening_difficulty_0_10=3.0,
                writing_difficulty_0_10=2.0,
                crp_mg_l=2.0,
            ),
        ),
        (
            "Scenario 2 — Active RA hand synovitis",
            HandROMInput(
                diagnosis="RA",
                age=54,
                wrist_extension_deg=42,
                wrist_flexion_deg=52,
                mcp_flexion_deg=58,
                pip_flexion_deg=70,
                thumb_abduction_deg=35,
                grip_strength_kg=12.5,
                pinch_strength_kg=3.8,
                pain_vas=7.5,
                swollen_joints=6,
                tender_joints=9,
                morning_stiffness_min=95,
                dressing_difficulty_0_10=7.0,
                jar_opening_difficulty_0_10=8.0,
                writing_difficulty_0_10=6.5,
                crp_mg_l=14.0,
                quickdash_0_100=58.0,
            ),
        ),
        (
            "Scenario 3 — Systemic sclerosis with contracture and ischemia",
            HandROMInput(
                diagnosis="Systemic sclerosis",
                age=60,
                wrist_extension_deg=28,
                wrist_flexion_deg=35,
                mcp_flexion_deg=40,
                pip_flexion_deg=44,
                thumb_abduction_deg=20,
                grip_strength_kg=7.5,
                pinch_strength_kg=1.9,
                pain_vas=6.8,
                swollen_joints=1,
                tender_joints=5,
                morning_stiffness_min=180,
                dressing_difficulty_0_10=8.5,
                jar_opening_difficulty_0_10=9.0,
                writing_difficulty_0_10=8.0,
                crp_mg_l=6.5,
                contracture_present=True,
                digital_ulcer_or_ischemia=True,
                quickdash_0_100=72.0,
            ),
        ),
    ]

    for label, case in cases:
        print_result(label, compute_handrom(case))


if __name__ == "__main__":
    demo()

```

## Demo Output

```
======================================================================
Scenario 1 — Mild osteoarthritis stiffness
======================================================================
Score: 17.2/100 [MILD]
95% CI: [15.0, 26.1]
Recommendation: Consider hand therapy and symptom-guided reassessment.

Domains:
- rom: raw 6.6 × w 0.30 = 2.0 (Average deficit across wrist/finger/thumb ROM)
- strength: raw 25.0 × w 0.20 = 5.0 (Grip 22.0 kg, pinch 6.2 kg)
- inflammation: raw 5.6 × w 0.20 = 1.1 (Swollen 0, tender 1, stiffness 15 min)
- pain_stiffness: raw 23.9 × w 0.15 = 3.6 (Pain VAS 3.0/10; morning stiffness 15 min)
- function: raw 23.3 × w 0.15 = 3.5 (Dressing 2.0/10, jar opening 3.0/10, writing 2.0/10)

======================================================================
Scenario 2 — Active RA hand synovitis
======================================================================
Score: 67.1/100 [SEVERE]
95% CI: [59.1, 69.8]
Recommendation: Urgent hand therapy plus rheumatology review for active inflammatory or fibrotic limitation.

Domains:
- rom: raw 36.4 × w 0.30 = 10.9 (Average deficit across wrist/finger/thumb ROM)
- strength: raw 85.0 × w 0.20 = 17.0 (Grip 12.5 kg, pinch 3.8 kg)
- inflammation: raw 75.0 × w 0.20 = 15.0 (Swollen 6, tender 9, stiffness 95 min)
- pain_stiffness: raw 76.5 × w 0.15 = 11.5 (Pain VAS 7.5/10; morning stiffness 95 min)
- function: raw 58.0 × w 0.15 = 8.7 (QuickDASH 58.0/100)

Notes:
* QuickDASH suggests substantial upper-extremity disability.
* Active synovitis may be modifiable with disease control.

======================================================================
Scenario 3 — Systemic sclerosis with contracture and ischemia
======================================================================
Score: 77.5/100 [CRITICAL]
95% CI: [75.2, 79.8]
Recommendation: Urgent evaluation for severe contracture, ischemia, infection, or rapidly progressive disability.

Domains:
- rom: raw 58.9 × w 0.30 = 17.7 (Average deficit across wrist/finger/thumb ROM)
- strength: raw 85.0 × w 0.20 = 17.0 (Grip 7.5 kg, pinch 1.9 kg)
- inflammation: raw 42.1 × w 0.20 = 8.4 (Swollen 1, tender 5, stiffness 180 min)
- pain_stiffness: raw 79.2 × w 0.15 = 11.9 (Pain VAS 6.8/10; morning stiffness 180 min)
- function: raw 97.0 × w 0.15 = 14.5 (QuickDASH 72.0/100)

Notes:
* Fixed contracture materially increases functional burden.
* Digital ischemia/ulcer is a red flag and should not be managed as simple stiffness.
* QuickDASH suggests substantial upper-extremity disability.
```