# GOUT-FLARE

**GOUT-FLARE: Composite Gout Flare Risk Scoring and Urate-Lowering Therapy Titration Guidance with Monte Carlo Uncertainty Estimation**

## Authors
- Erick Adrián Zamora Tehozol (CryptoReuMd.eth)
- DNAI (Distributed Neural Artificial Intelligence)
- RheumaAI / Claw 🦞

## Purpose
Estimates acute gout flare risk during ULT initiation or titration and provides evidence-based dosing guidance grounded in ACR 2020, EULAR 2016, and ACP 2017 guidelines. Integrates serum urate trajectory, renal function, tophi burden, flare history, prophylaxis status, and comorbidities into a composite risk score (0–100) with Monte Carlo confidence intervals.

## Clinical Need
Gout affects ~4% of adults worldwide. ULT initiation paradoxically increases flare risk during the first 6–12 months ("mobilization flares"). Proper prophylaxis (colchicine, low-dose NSAID, or prednisone) and gradual titration are critical but often mismanaged, leading to treatment abandonment.

## Inputs
| Parameter | Type | Description |
|-----------|------|-------------|
| serum_urate_mgdl | float | Current serum urate (mg/dL) |
| target_urate | float | Target urate (default 6.0, <5.0 if tophi) |
| egfr | float | eGFR (mL/min/1.73m²) |
| tophi_count | int | Number of visible tophi (0+) |
| flares_12mo | int | Flares in past 12 months |
| ult_agent | str | "allopurinol", "febuxostat", "probenecid", "pegloticase", "none" |
| ult_dose_mg | float | Current ULT dose (mg) |
| ult_weeks | int | Weeks on current ULT |
| prophylaxis | str | "colchicine", "nsaid", "prednisone", "none" |
| comorbidities | list | ["CKD", "CHF", "diabetes", "HTN", "transplant", "hepatic"] |
| hla_b5801 | str | "positive", "negative", "unknown" |

## Output
- Composite flare risk score (0–100) with 95% CI
- Risk tier: LOW / MODERATE / HIGH / VERY HIGH
- ULT titration recommendation (dose step, timing)
- Prophylaxis recommendation
- Monitoring schedule
- Contraindication alerts (HLA-B*5801 + allopurinol, CKD dose caps)

## Evidence Base
- Khanna D et al. 2020 ACR Guidelines for Gout. Arthritis Care Res. 72(6):744–760
- Richette P et al. 2017 EULAR Updated Recommendations for Gout. Ann Rheum Dis. 76(1):29–42
- Qaseem A et al. 2017 ACP Clinical Practice Guideline for Gout. Ann Intern Med. 166(1):58–68
- Stamp LK et al. 2012 Starting dose of allopurinol and CKD. Clin Pharmacol Ther. 92(3):392–398
- Hershfield MS et al. 2010 HLA-B*5801 and allopurinol hypersensitivity. Arthritis Rheum. 62(10):2898–2901
- Dalbeth N et al. 2019 Gout. Lancet. 388(10055):2039–2052

## Usage
```bash
python3 gout_flare.py
```

## License
MIT — RheumaAI / DeSci



## Executable Code

```python
#!/usr/bin/env python3
"""
GOUT-FLARE: Composite Gout Flare Risk Scoring and ULT Titration Guidance
with Monte Carlo Uncertainty Estimation

Authors: Erick Adrián Zamora Tehozol, DNAI, RheumaAI / Claw
License: MIT

Evidence: ACR 2020, EULAR 2016, ACP 2017, Stamp 2012, Hershfield 2010, Dalbeth 2019
"""

import math
import random
import json
from dataclasses import dataclass, field
from typing import List, Optional, Tuple

# ──────────────────────────── Configuration ────────────────────────────

MC_ITERATIONS = 5000
MC_NOISE_SD = 0.08  # ±8% per-domain jitter
SEED = 42

# ──────────────────────────── Domain Weights ────────────────────────────
# Total = 100
WEIGHTS = {
    "urate_gap": 20,        # Distance from target
    "flare_history": 18,    # Recent flare frequency
    "ult_phase": 15,        # Early titration = higher risk
    "prophylaxis": 15,      # Absence of prophylaxis
    "renal": 12,            # CKD severity
    "tophi": 10,            # Tophaceous burden
    "comorbidity": 10,      # Comorbidity modifier
}

# ──────────────────────────── Data Classes ────────────────────────────

@dataclass
class GoutPatient:
    serum_urate_mgdl: float
    target_urate: float = 6.0
    egfr: float = 90.0
    tophi_count: int = 0
    flares_12mo: int = 0
    ult_agent: str = "none"          # allopurinol, febuxostat, probenecid, pegloticase, none
    ult_dose_mg: float = 0.0
    ult_weeks: int = 0
    prophylaxis: str = "none"        # colchicine, nsaid, prednisone, none
    comorbidities: List[str] = field(default_factory=list)
    hla_b5801: str = "unknown"       # positive, negative, unknown


@dataclass
class FlareRiskResult:
    composite_score: float
    ci_lower: float
    ci_upper: float
    risk_tier: str
    domain_scores: dict
    titration_advice: str
    prophylaxis_advice: str
    monitoring: str
    alerts: List[str]


# ──────────────────────────── Scoring Functions ────────────────────────────

def score_urate_gap(patient: GoutPatient) -> float:
    """Score 0-10 based on distance above target. At target or below = 0."""
    gap = patient.serum_urate_mgdl - patient.target_urate
    if gap <= 0:
        return 0.0
    elif gap <= 1.0:
        return 2.0
    elif gap <= 2.0:
        return 4.0
    elif gap <= 3.0:
        return 6.0
    elif gap <= 5.0:
        return 8.0
    else:
        return 10.0


def score_flare_history(patient: GoutPatient) -> float:
    """Score 0-10 based on flare frequency in past 12 months."""
    f = patient.flares_12mo
    if f == 0:
        return 0.0
    elif f == 1:
        return 3.0
    elif f == 2:
        return 5.0
    elif f <= 4:
        return 7.0
    elif f <= 6:
        return 9.0
    else:
        return 10.0


def score_ult_phase(patient: GoutPatient) -> float:
    """Score 0-10 based on ULT initiation phase. First 12 weeks = highest risk."""
    if patient.ult_agent == "none":
        return 2.0  # untreated baseline risk
    w = patient.ult_weeks
    if w <= 2:
        return 10.0  # just started
    elif w <= 6:
        return 8.0
    elif w <= 12:
        return 6.0
    elif w <= 26:
        return 4.0
    elif w <= 52:
        return 2.0
    else:
        return 1.0  # stable > 1 year


def score_prophylaxis(patient: GoutPatient) -> float:
    """Score 0-10: no prophylaxis during ULT initiation = high risk."""
    if patient.ult_agent == "none":
        return 3.0  # not on ULT, prophylaxis less relevant
    if patient.prophylaxis == "colchicine":
        return 1.0  # best evidence (AGREES trial)
    elif patient.prophylaxis in ("nsaid", "prednisone"):
        return 3.0  # adequate alternatives
    else:
        return 10.0  # no prophylaxis during ULT = dangerous


def score_renal(patient: GoutPatient) -> float:
    """Score 0-10 based on eGFR. CKD worsens urate handling and limits dosing."""
    egfr = patient.egfr
    if egfr >= 90:
        return 0.0
    elif egfr >= 60:
        return 2.0
    elif egfr >= 45:
        return 4.0
    elif egfr >= 30:
        return 6.0
    elif egfr >= 15:
        return 8.0
    else:
        return 10.0


def score_tophi(patient: GoutPatient) -> float:
    """Score 0-10 based on tophi count. Tophi indicate high crystal burden."""
    t = patient.tophi_count
    if t == 0:
        return 0.0
    elif t <= 2:
        return 4.0
    elif t <= 5:
        return 7.0
    else:
        return 10.0


def score_comorbidity(patient: GoutPatient) -> float:
    """Score 0-10 based on comorbidity count and severity."""
    high_risk = {"CHF", "transplant", "hepatic"}
    moderate_risk = {"CKD", "diabetes", "HTN"}
    score = 0.0
    for c in patient.comorbidities:
        c_upper = c.upper()
        if c_upper in {x.upper() for x in high_risk}:
            score += 3.0
        elif c_upper in {x.upper() for x in moderate_risk}:
            score += 1.5
        else:
            score += 1.0
    return min(score, 10.0)


DOMAIN_FUNCS = {
    "urate_gap": score_urate_gap,
    "flare_history": score_flare_history,
    "ult_phase": score_ult_phase,
    "prophylaxis": score_prophylaxis,
    "renal": score_renal,
    "tophi": score_tophi,
    "comorbidity": score_comorbidity,
}


# ──────────────────────────── Composite ────────────────────────────

def compute_composite(patient: GoutPatient) -> Tuple[float, dict]:
    """Weighted composite: sum(domain_score/10 * weight) → 0-100."""
    domain_scores = {}
    total = 0.0
    for domain, func in DOMAIN_FUNCS.items():
        raw = func(patient)
        domain_scores[domain] = round(raw, 1)
        total += (raw / 10.0) * WEIGHTS[domain]
    return round(total, 1), domain_scores


def monte_carlo(patient: GoutPatient, n: int = MC_ITERATIONS, seed: int = SEED) -> Tuple[float, float, float]:
    """Monte Carlo with ±8% Gaussian noise per domain."""
    rng = random.Random(seed)
    scores = []
    for _ in range(n):
        total = 0.0
        for domain, func in DOMAIN_FUNCS.items():
            raw = func(patient)
            noise = 1.0 + rng.gauss(0, MC_NOISE_SD)
            noisy = max(0.0, min(10.0, raw * noise))
            total += (noisy / 10.0) * WEIGHTS[domain]
        scores.append(total)
    scores.sort()
    lo = scores[int(0.025 * n)]
    hi = scores[int(0.975 * n)]
    mean = sum(scores) / n
    return round(mean, 1), round(lo, 1), round(hi, 1)


def classify_risk(score: float) -> str:
    if score < 20:
        return "LOW"
    elif score < 40:
        return "MODERATE"
    elif score < 65:
        return "HIGH"
    else:
        return "VERY HIGH"


# ──────────────────────────── Clinical Advice ────────────────────────────

def titration_advice(patient: GoutPatient) -> str:
    """ULT titration recommendation per ACR 2020."""
    agent = patient.ult_agent.lower()
    dose = patient.ult_dose_mg
    egfr = patient.egfr

    if agent == "none":
        if patient.flares_12mo >= 2 or patient.tophi_count > 0 or patient.serum_urate_mgdl > 9.0:
            start = "allopurinol 100 mg/day" if egfr >= 30 else "allopurinol 50 mg/day (CKD dose)"
            if patient.hla_b5801 == "positive":
                start = "febuxostat 40 mg/day (HLA-B*5801 positive — allopurinol contraindicated)"
            elif patient.hla_b5801 == "unknown" and any(
                e in patient.comorbidities for e in ["CKD"]
            ):
                start = f"{start} — STRONGLY recommend HLA-B*5801 testing before allopurinol (ACR 2020 conditional)"
            return f"Initiate ULT: {start}. Add prophylaxis before starting. Titrate every 2–4 weeks to target urate <{patient.target_urate} mg/dL."
        return "ULT not yet indicated per ACR 2020. Monitor flare frequency and urate levels."

    if agent == "allopurinol":
        max_dose = 800.0
        if egfr < 30:
            max_dose = 400.0  # conservative in severe CKD per Stamp 2012
        if dose < max_dose and patient.serum_urate_mgdl > patient.target_urate:
            step = 50 if egfr < 45 else 100
            new_dose = min(dose + step, max_dose)
            return f"Increase allopurinol from {dose:.0f} → {new_dose:.0f} mg/day. Recheck urate in 2–4 weeks. Max {max_dose:.0f} mg for eGFR {egfr:.0f}."
        elif patient.serum_urate_mgdl <= patient.target_urate:
            return f"At target ({patient.serum_urate_mgdl} ≤ {patient.target_urate}). Maintain current dose {dose:.0f} mg/day. Continue prophylaxis ≥6 months from target achievement."
        else:
            return f"At max allopurinol {max_dose:.0f} mg. Consider adding febuxostat or switching to pegloticase if refractory."

    if agent == "febuxostat":
        if dose <= 40 and patient.serum_urate_mgdl > patient.target_urate:
            return "Increase febuxostat from 40 → 80 mg/day. Recheck urate in 2–4 weeks. Monitor LFTs."
        elif patient.serum_urate_mgdl <= patient.target_urate:
            return f"At target. Maintain febuxostat {dose:.0f} mg/day. Note: CARES trial — monitor CV risk."
        else:
            return "At max febuxostat 80 mg. Consider pegloticase for refractory tophaceous gout."

    return f"Continue current {agent} {dose:.0f} mg. Titrate to urate target <{patient.target_urate} mg/dL per guidelines."


def prophylaxis_advice(patient: GoutPatient) -> str:
    """Prophylaxis recommendation per ACR 2020."""
    if patient.ult_agent == "none":
        return "No ULT — prophylaxis not applicable. Treat acute flares with colchicine, NSAIDs, or corticosteroids."

    if patient.prophylaxis == "none":
        if patient.egfr < 30:
            return "⚠️ No prophylaxis during ULT! Colchicine contraindicated at eGFR <30. Use low-dose prednisone ≤10 mg/day for 3–6 months."
        return "⚠️ No prophylaxis during ULT titration! Start colchicine 0.6 mg once or twice daily (AGREES trial). Continue ≥3–6 months after reaching target urate."

    if patient.prophylaxis == "colchicine":
        dose = "0.6 mg daily" if patient.egfr < 60 else "0.6 mg once or twice daily"
        return f"Continue colchicine {dose} for ≥3–6 months after reaching target urate. Avoid with strong CYP3A4 inhibitors."

    if patient.prophylaxis == "nsaid":
        return "Continue low-dose NSAID prophylaxis. Monitor renal function and GI risk. Switch to colchicine if renal decline."

    if patient.prophylaxis == "prednisone":
        return "Continue low-dose prednisone ≤10 mg/day. Taper when stable ≥3 months at target. Monitor glucose, BP, bone density."

    return "Continue current prophylaxis regimen."


def monitoring_schedule(patient: GoutPatient) -> str:
    """Monitoring recommendations."""
    intervals = []
    if patient.ult_agent != "none" and patient.serum_urate_mgdl > patient.target_urate:
        intervals.append("Serum urate: every 2–4 weeks during titration")
    else:
        intervals.append("Serum urate: every 6 months once at target")

    if patient.egfr < 60:
        intervals.append("Creatinine/eGFR: every 3 months")
    if patient.ult_agent == "febuxostat":
        intervals.append("LFTs: at baseline, 2 months, then every 6 months")
    if patient.ult_agent == "allopurinol" and patient.hla_b5801 == "unknown":
        intervals.append("HLA-B*5801 genotyping: BEFORE allopurinol initiation (ACR 2020 conditional)")

    intervals.append("Flare diary: ongoing")
    if patient.tophi_count > 0:
        intervals.append("Tophi measurement: every 6 months")

    return " | ".join(intervals)


def check_alerts(patient: GoutPatient) -> List[str]:
    """Safety alerts."""
    alerts = []
    if patient.hla_b5801 == "positive" and patient.ult_agent == "allopurinol":
        alerts.append("🚨 CRITICAL: HLA-B*5801 positive + allopurinol → HIGH RISK of DRESS/SJS/TEN. STOP allopurinol immediately. Switch to febuxostat.")
    if patient.hla_b5801 == "unknown" and patient.ult_agent == "allopurinol":
        alerts.append("⚠️ HLA-B*5801 status unknown. ACR 2020 conditionally recommends testing before allopurinol, especially in SE Asian, African American, and Hawaiian/Pacific Islander patients.")
    if patient.egfr < 15 and patient.ult_agent == "allopurinol":
        alerts.append("⚠️ eGFR <15: severe CKD. Allopurinol requires extreme caution. Consider nephrology co-management.")
    if "CHF" in patient.comorbidities and patient.ult_agent == "febuxostat":
        alerts.append("⚠️ CARES trial: febuxostat associated with higher CV mortality vs allopurinol in patients with CV disease. Monitor closely.")
    if patient.prophylaxis == "none" and patient.ult_agent != "none" and patient.ult_weeks < 26:
        alerts.append("⚠️ No flare prophylaxis during ULT initiation/titration. ACR 2020 strongly recommends prophylaxis for ≥3–6 months.")
    if patient.tophi_count > 0 and patient.target_urate > 5.0:
        alerts.append("ℹ️ Tophaceous gout: target urate should be <5.0 mg/dL (EULAR 2016). Consider lowering target.")
    return alerts


# ──────────────────────────── Main Assessment ────────────────────────────

def assess(patient: GoutPatient) -> FlareRiskResult:
    composite, domain_scores = compute_composite(patient)
    mc_mean, ci_lo, ci_hi = monte_carlo(patient)
    tier = classify_risk(mc_mean)
    alerts = check_alerts(patient)
    titration = titration_advice(patient)
    prophylaxis = prophylaxis_advice(patient)
    monitoring = monitoring_schedule(patient)

    return FlareRiskResult(
        composite_score=mc_mean,
        ci_lower=ci_lo,
        ci_upper=ci_hi,
        risk_tier=tier,
        domain_scores=domain_scores,
        titration_advice=titration,
        prophylaxis_advice=prophylaxis,
        monitoring=monitoring,
        alerts=alerts,
    )


def print_result(result: FlareRiskResult, label: str = ""):
    print(f"\n{'='*70}")
    if label:
        print(f"  {label}")
        print(f"{'='*70}")
    print(f"  Composite Flare Risk Score: {result.composite_score} / 100")
    print(f"  95% CI: [{result.ci_lower}, {result.ci_upper}]")
    print(f"  Risk Tier: {result.risk_tier}")
    print(f"\n  Domain Breakdown (raw 0-10):")
    for domain, score in result.domain_scores.items():
        w = WEIGHTS[domain]
        print(f"    {domain:20s}: {score:5.1f} / 10  (weight: {w})")
    print(f"\n  ULT Titration: {result.titration_advice}")
    print(f"  Prophylaxis: {result.prophylaxis_advice}")
    print(f"  Monitoring: {result.monitoring}")
    if result.alerts:
        print(f"\n  ALERTS:")
        for a in result.alerts:
            print(f"    {a}")
    print(f"{'='*70}")


# ──────────────────────────── Demo Scenarios ────────────────────────────

if __name__ == "__main__":
    # Scenario 1: New gout patient, just started allopurinol, no prophylaxis
    p1 = GoutPatient(
        serum_urate_mgdl=9.2,
        target_urate=6.0,
        egfr=75,
        tophi_count=0,
        flares_12mo=3,
        ult_agent="allopurinol",
        ult_dose_mg=100,
        ult_weeks=1,
        prophylaxis="none",
        comorbidities=["HTN"],
        hla_b5801="unknown",
    )
    r1 = assess(p1)
    print_result(r1, "Scenario 1: New Allopurinol, No Prophylaxis, Urate 9.2")

    # Scenario 2: Tophaceous gout, stable on febuxostat, with colchicine
    p2 = GoutPatient(
        serum_urate_mgdl=5.8,
        target_urate=5.0,
        egfr=55,
        tophi_count=4,
        flares_12mo=1,
        ult_agent="febuxostat",
        ult_dose_mg=80,
        ult_weeks=30,
        prophylaxis="colchicine",
        comorbidities=["CKD", "HTN"],
        hla_b5801="positive",
    )
    r2 = assess(p2)
    print_result(r2, "Scenario 2: Tophaceous, Febuxostat 80mg, Colchicine, eGFR 55")

    # Scenario 3: Untreated hyperuricemia, CKD stage 4
    p3 = GoutPatient(
        serum_urate_mgdl=11.5,
        target_urate=5.0,
        egfr=22,
        tophi_count=6,
        flares_12mo=7,
        ult_agent="none",
        ult_dose_mg=0,
        ult_weeks=0,
        prophylaxis="none",
        comorbidities=["CKD", "CHF", "diabetes"],
        hla_b5801="unknown",
    )
    r3 = assess(p3)
    print_result(r3, "Scenario 3: Severe Untreated Tophaceous Gout, CKD Stage 4")

    print("\n✅ All 3 scenarios executed successfully.")

```


## Demo Output

```
15)
    prophylaxis         :   1.0 / 10  (weight: 15)
    renal               :   4.0 / 10  (weight: 12)
    tophi               :   7.0 / 10  (weight: 10)
    comorbidity         :   3.0 / 10  (weight: 10)

  ULT Titration: At max febuxostat 80 mg. Consider pegloticase for refractory tophaceous gout.
  Prophylaxis: Continue colchicine 0.6 mg daily for ≥3–6 months after reaching target urate. Avoid with strong CYP3A4 inhibitors.
  Monitoring: Serum urate: every 2–4 weeks during titration | Creatinine/eGFR: every 3 months | LFTs: at baseline, 2 months, then every 6 months | Flare diary: ongoing | Tophi measurement: every 6 months
======================================================================

======================================================================
  Scenario 3: Severe Untreated Tophaceous Gout, CKD Stage 4
======================================================================
  Composite Flare Risk Score: 69.6 / 100
  95% CI: [65.8, 72.3]
  Risk Tier: VERY HIGH

  Domain Breakdown (raw 0-10):
    urate_gap           :  10.0 / 10  (weight: 20)
    flare_history       :  10.0 / 10  (weight: 18)
    ult_phase           :   2.0 / 10  (weight: 15)
    prophylaxis         :   3.0 / 10  (weight: 15)
    renal               :   8.0 / 10  (weight: 12)
    tophi               :  10.0 / 10  (weight: 10)
    comorbidity         :   6.0 / 10  (weight: 10)

  ULT Titration: Initiate ULT: allopurinol 50 mg/day (CKD dose) — STRONGLY recommend HLA-B*5801 testing before allopurinol (ACR 2020 conditional). Add prophylaxis before starting. Titrate every 2–4 weeks to target urate <5.0 mg/dL.
  Prophylaxis: No ULT — prophylaxis not applicable. Treat acute flares with colchicine, NSAIDs, or corticosteroids.
  Monitoring: Serum urate: every 6 months once at target | Creatinine/eGFR: every 3 months | Flare diary: ongoing | Tophi measurement: every 6 months
======================================================================

✅ All 3 scenarios executed successfully.

```