# NEPHRITIS-LN

**Lupus Nephritis Flare Risk Predictor with Composite Renal Activity Score and Monte Carlo Uncertainty Estimation**

## Authors
Erick Adrián Zamora Tehozol, DNAI, RheumaAI

## Purpose
Predicts 6-month renal flare risk in proliferative lupus nephritis (ISN/RPS Class III/IV/V) using a 10-domain weighted composite score incorporating serological, urinary, and clinical markers with Monte Carlo uncertainty quantification.

## Domains (10)
| Domain | Weight | Key Inputs |
|--------|--------|------------|
| Proteinuria (UPCR) | 0.22 | UPCR mg/mg |
| Anti-dsDNA | 0.15 | Titer IU/mL + trend |
| Complement C3 | 0.12 | Level vs LLN |
| Complement C4 | 0.08 | Level vs LLN |
| eGFR trend | 0.14 | Δ mL/min/1.73m² |
| Hematuria | 0.08 | RBC/hpf + casts |
| IS adherence | 0.07 | Regimen + adherence |
| Prior flares | 0.06 | Count in 3 years |
| Serologic activity | 0.04 | SLEDAI serological |
| Biopsy chronicity | 0.04 | NIH CI (0-12) |

## Risk Levels
- **0-20 Low**: Maintain therapy, q3-6m monitoring
- **21-45 Moderate**: Consider intensification, monthly labs
- **46-70 High**: Nephrology co-management, discuss re-biopsy
- **71-100 Very High**: Urgent referral, repeat biopsy, escalate

## Usage
```bash
python3 nephritis_ln.py          # Run demo (3 scenarios)
echo '{"upcr":1.5,...}' | python3 nephritis_ln.py --json  # JSON API
```

## References
- Petri M et al. SLEDAI-2K. J Rheumatol 2002
- Moroni G et al. Predictors of renal flare. Nephrol Dial Transplant 2009
- Mackay M et al. Anti-dsDNA flare prediction. Arthritis Rheumatol 2020
- Dall'Era M et al. Proteinuria and outcomes. Ann Rheum Dis 2015
- Rovin BH et al. KDIGO 2024 guidelines for LN
- Furie R et al. Voclosporin AURORA trial. Kidney Int 2023
- ACR/EULAR 2024 Treat-to-Target for SLE



## Executable Code

```python
#!/usr/bin/env python3
"""
NEPHRITIS-LN: Lupus Nephritis Flare Risk Predictor with
Composite Renal Activity Score and Monte Carlo Uncertainty Estimation

Authors: Erick Adrián Zamora Tehozol, DNAI, RheumaAI
Date: 2026-04-01

Predicts 6-month flare risk in proliferative lupus nephritis (Class III/IV/V)
using a weighted composite of serological, urinary, and clinical markers.

References:
- Petri M et al. Derivation and validation of the SLEDAI-2K. J Rheumatol 2002;29:288-91
- Touma Z et al. SLEDAI-2K 10 days vs 30 days: flare detection. Lupus 2011;20:67-72
- Moroni G et al. Predictors of renal flare in LN. Nephrol Dial Transplant 2009;24:1824-31
- Mackay M et al. Anti-dsDNA flare prediction. Arthritis Rheumatol 2020;72:1313-1320
- Dall'Era M et al. Proteinuria and renal outcomes in LN. Ann Rheum Dis 2015;74:56-61
- Rovin BH et al. KDIGO 2024 guidelines for lupus nephritis management
- Furie R et al. Voclosporin phase 3 (AURORA). Kidney Int 2023;104:436-46
- ACR/EULAR 2024 Treat-to-Target recommendations for SLE

Grading:
  0-20: Low risk — maintain current therapy, standard monitoring
  21-45: Moderate risk — consider intensification, monthly labs
  46-70: High risk — recommend biopsy discussion, escalate therapy
  71-100: Very High risk — urgent nephrology referral, repeat biopsy
"""

import json
import math
import random
import sys
from typing import Dict, List, Optional, Tuple


# ── Domain Weights (evidence-informed) ──────────────────────────
DOMAINS = {
    "proteinuria": {
        "weight": 0.22,
        "description": "Urine protein-creatinine ratio (UPCR mg/mg) or 24h proteinuria",
        "refs": ["Dall'Era 2015 Ann Rheum Dis", "KDIGO 2024"]
    },
    "anti_dsDNA": {
        "weight": 0.15,
        "description": "Anti-dsDNA antibody titer change",
        "refs": ["Mackay 2020 Arthritis Rheumatol"]
    },
    "complement_C3": {
        "weight": 0.12,
        "description": "Serum C3 level relative to lower limit of normal",
        "refs": ["Petri 2002 J Rheumatol"]
    },
    "complement_C4": {
        "weight": 0.08,
        "description": "Serum C4 level relative to lower limit of normal",
        "refs": ["Petri 2002 J Rheumatol"]
    },
    "eGFR_trend": {
        "weight": 0.14,
        "description": "eGFR decline over past 3-6 months (mL/min/1.73m²)",
        "refs": ["Moroni 2009 Nephrol Dial Transplant"]
    },
    "hematuria": {
        "weight": 0.08,
        "description": "Active urinary sediment (RBC/hpf or RBC casts)",
        "refs": ["KDIGO 2024", "Rovin 2024"]
    },
    "immunosuppression_adherence": {
        "weight": 0.07,
        "description": "Current IS regimen adequacy and adherence",
        "refs": ["ACR/EULAR 2024 T2T"]
    },
    "prior_flare_history": {
        "weight": 0.06,
        "description": "Number of prior renal flares in past 3 years",
        "refs": ["Moroni 2009"]
    },
    "serologic_activity": {
        "weight": 0.04,
        "description": "Extra-renal SLEDAI serological activity score",
        "refs": ["Touma 2011 Lupus"]
    },
    "biopsy_chronicity": {
        "weight": 0.04,
        "description": "Chronicity index from most recent renal biopsy (NIH scale 0-12)",
        "refs": ["Austin 1984 Kidney Int", "Bajema 2018 ISN/RPS"]
    }
}

assert abs(sum(d["weight"] for d in DOMAINS.values()) - 1.0) < 1e-9, "Weights must sum to 1.0"


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

def score_proteinuria(upcr: float) -> float:
    """Score UPCR (mg/mg). Complete remission <0.5, partial <1.0, active >1.0."""
    if upcr < 0.3:
        return 0
    elif upcr < 0.5:
        return 15
    elif upcr < 1.0:
        return 35
    elif upcr < 2.0:
        return 60
    elif upcr < 3.5:
        return 80
    else:
        return 100


def score_anti_dsDNA(titer: float, rising: bool = False) -> float:
    """Score anti-dsDNA. Titer in IU/mL. Rising trend adds risk."""
    base = 0
    if titer < 30:
        base = 0
    elif titer < 100:
        base = 25
    elif titer < 200:
        base = 50
    elif titer < 400:
        base = 75
    else:
        base = 100
    if rising and base > 0:
        base = min(100, base + 20)
    return base


def score_complement(level: float, lln: float) -> float:
    """Score complement (C3 or C4). level and lln in same units (mg/dL)."""
    if lln <= 0:
        return 0
    ratio = level / lln
    if ratio >= 1.0:
        return 0
    elif ratio >= 0.8:
        return 25
    elif ratio >= 0.6:
        return 50
    elif ratio >= 0.4:
        return 75
    else:
        return 100


def score_eGFR_trend(delta: float) -> float:
    """Score eGFR change over 3-6 months. delta = current - previous (negative = decline)."""
    if delta >= 0:
        return 0
    elif delta >= -5:
        return 20
    elif delta >= -10:
        return 45
    elif delta >= -20:
        return 70
    elif delta >= -30:
        return 85
    else:
        return 100


def score_hematuria(rbc_hpf: int, casts: bool = False) -> float:
    """Score active urinary sediment. RBC/hpf and presence of RBC casts."""
    base = 0
    if rbc_hpf < 5:
        base = 0
    elif rbc_hpf < 10:
        base = 20
    elif rbc_hpf < 25:
        base = 45
    elif rbc_hpf < 50:
        base = 70
    else:
        base = 90
    if casts:
        base = min(100, base + 25)
    return base


def score_adherence(regimen: str, adherent: bool) -> float:
    """Score IS adequacy. regimen: none|minimal|standard|intensive."""
    regimen_scores = {
        "none": 80,
        "minimal": 50,
        "standard": 15,
        "intensive": 5
    }
    base = regimen_scores.get(regimen, 40)
    if not adherent:
        base = min(100, base + 30)
    return base


def score_prior_flares(count: int) -> float:
    """Score prior renal flare history (past 3 years)."""
    if count == 0:
        return 0
    elif count == 1:
        return 30
    elif count == 2:
        return 60
    else:
        return 90


def score_serologic_activity(sledai_sero: int) -> float:
    """Score extra-renal serological SLEDAI (0-12 range typical)."""
    if sledai_sero <= 2:
        return 0
    elif sledai_sero <= 4:
        return 25
    elif sledai_sero <= 8:
        return 55
    else:
        return 85


def score_biopsy_chronicity(ci: int) -> float:
    """Score biopsy chronicity index (NIH 0-12)."""
    if ci <= 1:
        return 5
    elif ci <= 3:
        return 25
    elif ci <= 6:
        return 55
    elif ci <= 9:
        return 80
    else:
        return 100


# ── Monte Carlo Uncertainty ─────────────────────────────────────

def monte_carlo_composite(
    domain_scores: Dict[str, float],
    n_simulations: int = 5000,
    noise_sd: float = 5.0,
    seed: Optional[int] = None
) -> Tuple[float, float, float, float]:
    """
    Run MC simulation adding Gaussian noise to each domain score.
    Returns: (mean, sd, ci_low_95, ci_high_95)
    """
    rng = random.Random(seed)
    results = []
    for _ in range(n_simulations):
        total = 0.0
        for name, score in domain_scores.items():
            w = DOMAINS[name]["weight"]
            noisy = max(0, min(100, score + rng.gauss(0, noise_sd)))
            total += w * noisy
        results.append(total)
    results.sort()
    mean = sum(results) / len(results)
    variance = sum((x - mean) ** 2 for x in results) / len(results)
    sd = math.sqrt(variance)
    ci_low = results[int(0.025 * len(results))]
    ci_high = results[int(0.975 * len(results))]
    return round(mean, 1), round(sd, 1), round(ci_low, 1), round(ci_high, 1)


# ── Risk Classification ────────────────────────────────────────

def classify_risk(score: float) -> Tuple[str, str]:
    """Returns (risk_level, recommendation)."""
    if score <= 20:
        return ("Low", "Maintain current therapy. Standard monitoring q3-6 months. "
                "Target: complete remission (UPCR <0.5, stable eGFR).")
    elif score <= 45:
        return ("Moderate", "Consider intensifying IS (add voclosporin or belimumab per KDIGO 2024). "
                "Monthly labs for 3 months. Discuss repeat biopsy if persistent proteinuria.")
    elif score <= 70:
        return ("High", "Recommend nephrology co-management. Discuss repeat renal biopsy. "
                "Escalate to combination therapy (MMF + voclosporin or rituximab). "
                "Biweekly monitoring.")
    else:
        return ("Very High", "URGENT: Nephrology referral within 1 week. Repeat biopsy strongly indicated. "
                "Consider IV cyclophosphamide or rituximab. Rule out TMA/RPGN. "
                "Weekly monitoring until stabilized.")


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

def assess_patient(patient: dict, seed: int = 42) -> dict:
    """
    Run full NEPHRITIS-LN assessment.
    
    patient dict keys:
        upcr: float (mg/mg)
        anti_dsDNA: float (IU/mL)
        anti_dsDNA_rising: bool
        c3: float (mg/dL)
        c3_lln: float (mg/dL, default 90)
        c4: float (mg/dL)
        c4_lln: float (mg/dL, default 10)
        eGFR_delta: float (mL/min/1.73m², negative=decline)
        rbc_hpf: int
        rbc_casts: bool
        is_regimen: str (none|minimal|standard|intensive)
        is_adherent: bool
        prior_flares: int (past 3y)
        sledai_sero: int
        biopsy_ci: int (NIH 0-12)
    """
    domain_scores = {
        "proteinuria": score_proteinuria(patient.get("upcr", 0)),
        "anti_dsDNA": score_anti_dsDNA(
            patient.get("anti_dsDNA", 0),
            patient.get("anti_dsDNA_rising", False)
        ),
        "complement_C3": score_complement(
            patient.get("c3", 90),
            patient.get("c3_lln", 90)
        ),
        "complement_C4": score_complement(
            patient.get("c4", 10),
            patient.get("c4_lln", 10)
        ),
        "eGFR_trend": score_eGFR_trend(patient.get("eGFR_delta", 0)),
        "hematuria": score_hematuria(
            patient.get("rbc_hpf", 0),
            patient.get("rbc_casts", False)
        ),
        "immunosuppression_adherence": score_adherence(
            patient.get("is_regimen", "standard"),
            patient.get("is_adherent", True)
        ),
        "prior_flare_history": score_prior_flares(patient.get("prior_flares", 0)),
        "serologic_activity": score_serologic_activity(patient.get("sledai_sero", 0)),
        "biopsy_chronicity": score_biopsy_chronicity(patient.get("biopsy_ci", 0))
    }

    # Deterministic composite
    composite = sum(
        DOMAINS[name]["weight"] * score
        for name, score in domain_scores.items()
    )
    composite = round(composite, 1)

    # Monte Carlo
    mc_mean, mc_sd, mc_ci_low, mc_ci_high = monte_carlo_composite(
        domain_scores, seed=seed
    )

    risk_level, recommendation = classify_risk(mc_mean)

    return {
        "composite_score": composite,
        "mc_mean": mc_mean,
        "mc_sd": mc_sd,
        "mc_95ci": [mc_ci_low, mc_ci_high],
        "risk_level": risk_level,
        "recommendation": recommendation,
        "domain_scores": {k: round(v, 1) for k, v in domain_scores.items()},
        "domain_weights": {k: DOMAINS[k]["weight"] for k in domain_scores}
    }


# ── Demo / CLI ──────────────────────────────────────────────────

def demo():
    scenarios = [
        {
            "label": "Scenario 1: Stable LN in remission (Low risk)",
            "patient": {
                "upcr": 0.3,
                "anti_dsDNA": 20,
                "anti_dsDNA_rising": False,
                "c3": 95,
                "c3_lln": 90,
                "c4": 18,
                "c4_lln": 10,
                "eGFR_delta": 2,
                "rbc_hpf": 2,
                "rbc_casts": False,
                "is_regimen": "standard",
                "is_adherent": True,
                "prior_flares": 0,
                "sledai_sero": 0,
                "biopsy_ci": 1
            }
        },
        {
            "label": "Scenario 2: Rising serologies, moderate proteinuria (Moderate risk)",
            "patient": {
                "upcr": 0.8,
                "anti_dsDNA": 150,
                "anti_dsDNA_rising": True,
                "c3": 70,
                "c3_lln": 90,
                "c4": 8,
                "c4_lln": 10,
                "eGFR_delta": -7,
                "rbc_hpf": 12,
                "rbc_casts": False,
                "is_regimen": "standard",
                "is_adherent": True,
                "prior_flares": 1,
                "sledai_sero": 6,
                "biopsy_ci": 3
            }
        },
        {
            "label": "Scenario 3: Active nephritic flare, non-adherent (Very High risk)",
            "patient": {
                "upcr": 4.0,
                "anti_dsDNA": 500,
                "anti_dsDNA_rising": True,
                "c3": 35,
                "c3_lln": 90,
                "c4": 3,
                "c4_lln": 10,
                "eGFR_delta": -25,
                "rbc_hpf": 60,
                "rbc_casts": True,
                "is_regimen": "minimal",
                "is_adherent": False,
                "prior_flares": 3,
                "sledai_sero": 10,
                "biopsy_ci": 8
            }
        }
    ]

    print("=" * 70)
    print("NEPHRITIS-LN Demo — Lupus Nephritis Flare Risk Predictor")
    print("=" * 70)

    all_pass = True
    expected_risks = ["Low", "Moderate", "Very High"]

    for i, scenario in enumerate(scenarios):
        result = assess_patient(scenario["patient"])
        status = "✅" if result["risk_level"] == expected_risks[i] else "❌"
        if result["risk_level"] != expected_risks[i]:
            all_pass = False

        print(f"\n{status} {scenario['label']}")
        print(f"   Composite: {result['composite_score']}")
        print(f"   MC Mean:   {result['mc_mean']} ± {result['mc_sd']} "
              f"(95% CI [{result['mc_95ci'][0]}, {result['mc_95ci'][1]}])")
        print(f"   Risk:      {result['risk_level']}")
        print(f"   Action:    {result['recommendation'][:80]}...")
        print(f"   Domains:")
        for k, v in result["domain_scores"].items():
            print(f"     {k}: {v}")

    print("\n" + "=" * 70)
    if all_pass:
        print("ALL 3 SCENARIOS PASSED ✅")
    else:
        print("SOME SCENARIOS FAILED ❌")
    print("=" * 70)

    return all_pass


if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--json":
        # JSON mode for API integration
        data = json.loads(sys.stdin.read())
        result = assess_patient(data)
        print(json.dumps(result, indent=2))
    else:
        success = demo()
        sys.exit(0 if success else 1)

```


## Demo Output

```
======================================================================
NEPHRITIS-LN Demo — Lupus Nephritis Flare Risk Predictor
======================================================================

✅ Scenario 1: Stable LN in remission (Low risk)
   Composite: 4.5
   MC Mean:   5.9 ± 1.4 (95% CI [3.3, 8.7])
   Risk:      Low
   Action:    Maintain current therapy. Standard monitoring q3-6 months. Target: complete remi...
   Domains:
     proteinuria: 15
     anti_dsDNA: 0
     complement_C3: 0
     complement_C4: 0
     eGFR_trend: 0
     hematuria: 0
     immunosuppression_adherence: 15
     prior_flare_history: 0
     serologic_activity: 0
     biopsy_chronicity: 5

✅ Scenario 2: Rising serologies, moderate proteinuria (Moderate risk)
   Composite: 42.1
   MC Mean:   42.1 ± 1.8 (95% CI [38.6, 45.6])
   Risk:      Moderate
   Action:    Consider intensifying IS (add voclosporin or belimumab per KDIGO 2024). Monthly ...
   Domains:
     proteinuria: 35
     anti_dsDNA: 70
     complement_C3: 50
     complement_C4: 25
     eGFR_trend: 45
     hematuria: 45
     immunosuppression_adherence: 15
     prior_flare_history: 30
     serologic_activity: 55
     biopsy_chronicity: 25

✅ Scenario 3: Active nephritic flare, non-adherent (Very High risk)
   Composite: 94.5
   MC Mean:   93.2 ± 1.3 (95% CI [90.5, 95.6])
   Risk:      Very High
   Action:    URGENT: Nephrology referral within 1 week. Repeat biopsy strongly indicated. Con...
   Domains:
     proteinuria: 100
     anti_dsDNA: 100
     complement_C3: 100
     complement_C4: 100
     eGFR_trend: 85
     hematuria: 100
     immunosuppression_adherence: 80
     prior_flare_history: 90
     serologic_activity: 85
     biopsy_chronicity: 80

======================================================================
ALL 3 SCENARIOS PASSED ✅
======================================================================

```