# NEFRO-LUP: Lupus Nephritis Flare Risk Stratification Score

## Overview

NEFRO-LUP computes a composite 0–100 risk score for lupus nephritis flare using 8 clinical domains (proteinuria, eGFR, anti-dsDNA, C3, C4, urine sediment, eGFR trend, proteinuria trend) with Monte Carlo uncertainty estimation.

## Authors

- Erick Adrián Zamora Tehozol
- DNAI (Distributed Neural Artificial Intelligence)
- RheumaAI

## Clinical Rationale

Lupus nephritis (LN) affects 40–60% of SLE patients and remains a leading cause of morbidity. Early detection of impending flares enables timely therapeutic escalation, preventing irreversible nephron loss. This tool integrates KDIGO 2024 lupus nephritis guidelines with validated serological and urinary biomarkers to produce a unified flare-risk score.

## Domains (8)

| Domain | Weight | Description |
|--------|--------|-------------|
| Proteinuria (UPCR) | 20% | Urine protein-to-creatinine ratio |
| eGFR | 15% | CKD-EPI estimated GFR |
| Anti-dsDNA | 15% | Anti-dsDNA antibody titer |
| Complement C3 | 12% | Serum C3 level |
| Complement C4 | 8% | Serum C4 level |
| Urine Sediment | 10% | Active sediment score (0–3) |
| eGFR Trend | 10% | 3-month eGFR change |
| Proteinuria Trend | 10% | 3-month UPCR change |

## Risk Tiers

| Score | Tier | Action |
|-------|------|--------|
| 0–14 | LOW | Routine monitoring q3–6mo |
| 15–34 | MODERATE | Monthly monitoring, consider dose adjustment |
| 35–59 | HIGH | Urgent nephrology referral, consider repeat biopsy |
| 60–100 | VERY HIGH | Immediate evaluation, rescue induction therapy |

## Usage

```bash
python3 nefro_lup.py
```

## References

1. KDIGO 2024 Clinical Practice Guideline for the Management of Lupus Nephritis
2. Petri M et al. SLEDAI derivation and validation. Arthritis Rheum. 1992;35(6):630-40
3. Dall'Era M et al. Predictors of renal flare. Lupus Sci Med. 2017;4(1):e000205
4. Moroni G et al. Anti-dsDNA and renal flares. J Am Soc Nephrol. 2009;20(7):1584-90
5. Touma Z et al. UPCR as predictor of renal outcomes. Lupus. 2014;23(1):46-53
6. Birmingham DJ et al. Complement activation and flare prediction. Arthritis Rheum. 2012;64(4):1248-58
7. Rovin BH et al. AURORA trial: voclosporin for lupus nephritis. Lancet. 2021;397(10289):2070-80



## Executable Code

```python
#!/usr/bin/env python3
"""
NEFRO-LUP: Lupus Nephritis Flare Risk Stratification Score
with Monte Carlo Uncertainty Estimation

Authors: Erick Adrián Zamora Tehozol, DNAI, RheumaAI
Date: 2026-03-29

Computes a composite 0–100 risk score for lupus nephritis flare
based on 8 clinical domains, with Monte Carlo sensitivity analysis.

References:
  - Kidney Disease: Improving Global Outcomes (KDIGO) 2024 Lupus Nephritis Guidelines
  - Petri M et al. Derivation and validation of the SLEDAI. Arthritis Rheum. 1992;35(6):630-40
  - Dall'Era M et al. Predictors of renal flare in lupus nephritis. Lupus Sci Med. 2017;4(1):e000205
  - Moroni G et al. Anti-dsDNA antibodies and renal flares. J Am Soc Nephrol. 2009;20(7):1584-90
  - Touma Z et al. UPCR as predictor of renal outcomes in SLE. Lupus. 2014;23(1):46-53
  - Birmingham DJ et al. Complement activation and flare prediction. Arthritis Rheum. 2012;64(4):1248-58
  - Hanly JG et al. Repeat kidney biopsy in lupus nephritis. Kidney Int. 2019;95(5):1187-98
"""

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


# ── Domain Definitions ──────────────────────────────────────────────────────

DOMAINS = {
    "proteinuria": {
        "weight": 0.20,
        "description": "Urine protein-to-creatinine ratio (UPCR, mg/mg)",
        "unit": "mg/mg",
        "scoring": [
            (0.0, 0.5, 0, "Normal (<0.5)"),
            (0.5, 1.0, 25, "Mild (0.5–1.0)"),
            (1.0, 2.0, 50, "Moderate (1.0–2.0)"),
            (2.0, 3.5, 75, "Severe (2.0–3.5)"),
            (3.5, float("inf"), 100, "Nephrotic (>3.5)"),
        ],
    },
    "egfr": {
        "weight": 0.15,
        "description": "Estimated GFR (CKD-EPI, mL/min/1.73m²)",
        "unit": "mL/min/1.73m²",
        "scoring": [
            (90, float("inf"), 0, "Normal (≥90)"),
            (60, 90, 20, "Mild decrease (60–89)"),
            (45, 60, 45, "Moderate (45–59)"),
            (30, 45, 70, "Moderate-Severe (30–44)"),
            (0, 30, 100, "Severe (<30)"),
        ],
        "inverted": True,  # lower value = higher risk
    },
    "anti_dsdna": {
        "weight": 0.15,
        "description": "Anti-dsDNA antibody titer (IU/mL)",
        "unit": "IU/mL",
        "scoring": [
            (0, 30, 0, "Negative (<30)"),
            (30, 75, 25, "Low positive (30–74)"),
            (75, 200, 55, "Moderate (75–199)"),
            (200, 500, 80, "High (200–499)"),
            (500, float("inf"), 100, "Very high (≥500)"),
        ],
    },
    "complement_c3": {
        "weight": 0.12,
        "description": "Serum C3 (mg/dL)",
        "unit": "mg/dL",
        "scoring": [
            (90, float("inf"), 0, "Normal (≥90)"),
            (70, 90, 30, "Mild decrease (70–89)"),
            (50, 70, 60, "Moderate decrease (50–69)"),
            (0, 50, 100, "Severe decrease (<50)"),
        ],
        "inverted": True,
    },
    "complement_c4": {
        "weight": 0.08,
        "description": "Serum C4 (mg/dL)",
        "unit": "mg/dL",
        "scoring": [
            (16, float("inf"), 0, "Normal (≥16)"),
            (10, 16, 35, "Low (10–15)"),
            (0, 10, 100, "Very low (<10)"),
        ],
        "inverted": True,
    },
    "urine_sediment": {
        "weight": 0.10,
        "description": "Active urinary sediment score (0=inactive, 1=hematuria only, 2=hematuria+casts, 3=RBC casts+WBC casts)",
        "unit": "ordinal 0–3",
        "scoring": [
            (0, 0.5, 0, "Inactive"),
            (0.5, 1.5, 30, "Hematuria only"),
            (1.5, 2.5, 65, "Hematuria + cellular casts"),
            (2.5, float("inf"), 100, "Active sediment with RBC casts"),
        ],
    },
    "egfr_trend": {
        "weight": 0.10,
        "description": "eGFR change over 3 months (mL/min/1.73m²; negative = decline)",
        "unit": "mL/min/1.73m²",
        "scoring": [
            (5, float("inf"), 0, "Improving (>+5)"),
            (0, 5, 10, "Stable (0 to +5)"),
            (-10, 0, 40, "Mild decline (0 to -10)"),
            (-25, -10, 70, "Moderate decline (-10 to -25)"),
            (float("-inf"), -25, 100, "Rapid decline (>-25)"),
        ],
        "inverted": True,
    },
    "proteinuria_trend": {
        "weight": 0.10,
        "description": "UPCR change over 3 months (mg/mg; positive = worsening)",
        "unit": "mg/mg delta",
        "scoring": [
            (float("-inf"), -0.5, 0, "Improving (decreasing >0.5)"),
            (-0.5, 0, 10, "Stable-improving"),
            (0, 0.5, 30, "Mild increase"),
            (0.5, 1.0, 60, "Moderate increase"),
            (1.0, float("inf"), 100, "Rapid increase (>1.0)"),
        ],
    },
}


def score_domain(domain_key: str, value: float) -> Tuple[int, str]:
    """Score a single domain. Returns (score, label)."""
    domain = DOMAINS[domain_key]
    is_inverted = domain.get("inverted", False)

    for low, high, score, label in domain["scoring"]:
        if is_inverted:
            # For inverted domains, ranges are listed high→low
            if low <= value < high:
                return score, label
        else:
            if low <= value < high:
                return score, label

    # Fallback
    return domain["scoring"][-1][2], domain["scoring"][-1][3]


def compute_composite(domain_scores: Dict[str, int]) -> float:
    """Weighted composite score 0–100."""
    total = 0.0
    for key, score in domain_scores.items():
        total += DOMAINS[key]["weight"] * score
    return round(total, 1)


def classify_risk(score: float) -> Tuple[str, str]:
    """Classify composite score into risk tier + recommendation."""
    if score < 15:
        return "LOW", "Routine monitoring q3–6mo. Continue current immunosuppression."
    elif score < 35:
        return "MODERATE", "Intensify monitoring to monthly. Consider immunosuppressive dose adjustment. Repeat labs in 4–6 weeks."
    elif score < 60:
        return "HIGH", "Urgent nephrology referral. Consider repeat renal biopsy. Intensify immunosuppression per KDIGO 2024."
    else:
        return "VERY HIGH", "Immediate nephrology evaluation. Strong indication for repeat biopsy. Consider rescue induction therapy (IV cyclophosphamide or voclosporin + MMF per KDIGO 2024)."


def monte_carlo(inputs: Dict[str, float], n_sim: int = 5000, seed: int = 42) -> Dict:
    """Run Monte Carlo sensitivity analysis with ±10% measurement uncertainty."""
    rng = random.Random(seed)
    scores = []

    for _ in range(n_sim):
        perturbed = {}
        for key, val in inputs.items():
            noise = rng.gauss(0, 0.10)  # 10% CV
            perturbed_val = val * (1 + noise)
            domain_score, _ = score_domain(key, perturbed_val)
            perturbed[key] = domain_score
        scores.append(compute_composite(perturbed))

    scores.sort()
    mean_score = sum(scores) / len(scores)
    ci_low = scores[int(0.025 * n_sim)]
    ci_high = scores[int(0.975 * n_sim)]

    return {
        "mean": round(mean_score, 1),
        "ci95_low": round(ci_low, 1),
        "ci95_high": round(ci_high, 1),
        "n_simulations": n_sim,
    }


def run_assessment(inputs: Dict[str, float], n_sim: int = 5000, seed: int = 42) -> Dict:
    """Full assessment: domain scores + composite + classification + MC."""
    domain_results = {}
    domain_scores = {}

    for key in inputs:
        if key not in DOMAINS:
            continue
        score, label = score_domain(key, inputs[key])
        domain_scores[key] = score
        domain_results[key] = {
            "value": inputs[key],
            "unit": DOMAINS[key]["unit"],
            "score": score,
            "label": label,
            "weight": DOMAINS[key]["weight"],
        }

    composite = compute_composite(domain_scores)
    risk_tier, recommendation = classify_risk(composite)
    mc = monte_carlo(inputs, n_sim, seed)

    return {
        "composite_score": composite,
        "risk_tier": risk_tier,
        "recommendation": recommendation,
        "domain_scores": domain_results,
        "monte_carlo": mc,
    }


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

def demo():
    scenarios = [
        {
            "name": "Scenario 1: Stable lupus nephritis in remission",
            "inputs": {
                "proteinuria": 0.3,
                "egfr": 95,
                "anti_dsdna": 20,
                "complement_c3": 110,
                "complement_c4": 22,
                "urine_sediment": 0,
                "egfr_trend": 2,
                "proteinuria_trend": -0.1,
            },
        },
        {
            "name": "Scenario 2: Class IV LN with rising proteinuria",
            "inputs": {
                "proteinuria": 2.8,
                "egfr": 52,
                "anti_dsdna": 320,
                "complement_c3": 55,
                "complement_c4": 8,
                "urine_sediment": 2,
                "egfr_trend": -15,
                "proteinuria_trend": 1.2,
            },
        },
        {
            "name": "Scenario 3: Nephrotic-range flare with rapid GFR decline",
            "inputs": {
                "proteinuria": 5.5,
                "egfr": 28,
                "anti_dsdna": 650,
                "complement_c3": 38,
                "complement_c4": 5,
                "urine_sediment": 3,
                "egfr_trend": -30,
                "proteinuria_trend": 2.5,
            },
        },
    ]

    for scenario in scenarios:
        print(f"\n{'='*70}")
        print(f"  {scenario['name']}")
        print(f"{'='*70}")

        result = run_assessment(scenario["inputs"])

        print(f"\n  Composite Score: {result['composite_score']}/100")
        print(f"  Risk Tier: {result['risk_tier']}")
        print(f"  Monte Carlo 95% CI: [{result['monte_carlo']['ci95_low']}, {result['monte_carlo']['ci95_high']}]")
        print(f"  Recommendation: {result['recommendation']}")

        print(f"\n  Domain Breakdown:")
        for key, d in result["domain_scores"].items():
            print(f"    {key:20s}  value={d['value']:>8}  score={d['score']:>3}  [{d['label']}]")

    print(f"\n{'='*70}")
    print("  All scenarios completed successfully.")
    print(f"{'='*70}")


if __name__ == "__main__":
    demo()

```


## Demo Output

```
y. Consider rescue induction therapy (IV cyclophosphamide or voclosporin + MMF per KDIGO 2024).

  Domain Breakdown:
    proteinuria           value=     2.8  score= 75  [Severe (2.0–3.5)]
    egfr                  value=      52  score= 45  [Moderate (45–59)]
    anti_dsdna            value=     320  score= 80  [High (200–499)]
    complement_c3         value=      55  score= 60  [Moderate decrease (50–69)]
    complement_c4         value=       8  score=100  [Very low (<10)]
    urine_sediment        value=       2  score= 65  [Hematuria + cellular casts]
    egfr_trend            value=     -15  score= 70  [Moderate decline (-10 to -25)]
    proteinuria_trend     value=     1.2  score=100  [Rapid increase (>1.0)]

======================================================================
  Scenario 3: Nephrotic-range flare with rapid GFR decline
======================================================================

  Composite Score: 100.0/100
  Risk Tier: VERY HIGH
  Monte Carlo 95% CI: [92.5, 100.0]
  Recommendation: Immediate nephrology evaluation. Strong indication for repeat biopsy. Consider rescue induction therapy (IV cyclophosphamide or voclosporin + MMF per KDIGO 2024).

  Domain Breakdown:
    proteinuria           value=     5.5  score=100  [Nephrotic (>3.5)]
    egfr                  value=      28  score=100  [Severe (<30)]
    anti_dsdna            value=     650  score=100  [Very high (≥500)]
    complement_c3         value=      38  score=100  [Severe decrease (<50)]
    complement_c4         value=       5  score=100  [Very low (<10)]
    urine_sediment        value=       3  score=100  [Active sediment with RBC casts]
    egfr_trend            value=     -30  score=100  [Rapid decline (>-25)]
    proteinuria_trend     value=     2.5  score=100  [Rapid increase (>1.0)]

======================================================================
  All scenarios completed successfully.
======================================================================

```