# TACRO-CYP5

TACRO-CYP5 is a transparent clinical decision-support skill for tacrolimus exposure-risk stratification in autoimmune disease, with emphasis on lupus nephritis and other calcineurin-inhibitor use cases where CYP3A5 genotype and therapeutic drug monitoring matter.

## What it does
- Estimates tacrolimus misexposure risk on a 0-100 scale
- Separates the dominant direction into `UNDEREXPOSURE`, `TOXICITY`, or `MIXED`
- Integrates CYP3A5 phenotype, starting dose per kg, kidney function, hepatic context, CYP3A inhibitors/inducers, age, nephrotoxic co-therapy, and monitoring readiness
- Returns a 95% uncertainty interval and domain-level contributions

## Intended use
Pre-treatment pharmacogenomic review, tacrolimus start planning, and early therapeutic drug monitoring triage in autoimmune patients.

## Not for
- Replacing CPIC or institution-specific tacrolimus dosing protocols
- Interpreting tacrolimus troughs without clinician review
- Managing acute kidney injury, neurotoxicity, or drug-induced liver injury emergencies
- Overriding specialist judgment in complex transplant or ICU settings

## Run
```bash
python3 tacro_cyp5.py
```

## Inputs
See the `TacroPatient` dataclass in `tacro_cyp5.py`.

## Outputs
- Composite misexposure score
- Risk category: LOW / MODERATE / HIGH / VERY HIGH
- Dominant direction: UNDEREXPOSURE / TOXICITY / MIXED
- 95% uncertainty interval
- Recommendation
- Monitoring comment
- Domain-level contribution table

## Core references
- Birdwell KA, Decker B, Barbarino JM, et al. Clin Pharmacol Ther. 2015. DOI: 10.1002/cpt.113
- Niioka T, Komatsuda A, Kato S, et al. Clin Exp Nephrol. 2015. DOI: 10.3109/00498254.2015.1045571
- Wei L, Wang T, Hu Y, et al. 2025. DOI: 10.12182/20250560509
- Froelicher D, Troncoso-Pastoriza JR, Raisaro JL, et al. Nat Commun. 2021. DOI: 10.1038/s41467-021-25972-y


## Executable Code

```python
#!/usr/bin/env python3
"""
TACRO-CYP5: Tacrolimus exposure-risk stratification in autoimmune disease.

Purpose:
Estimate whether the bedside problem is more likely tacrolimus underexposure,
toxicity, or a mixed exposure-instability pattern before or during therapy.

Author: Dr. Erick Zamora-Tehozol, DNAI, RheumaAI
ORCID: 0000-0002-7888-3961
License: MIT
"""

from __future__ import annotations

from dataclasses import dataclass, asdict
from typing import Dict, Any, List
import math
import random


@dataclass
class TacroPatient:
    cyp3a5: str = "unknown"  # expresser, intermediate, poor, unknown
    weight_kg: float = 68.0
    starting_dose_mg_per_day: float = 4.0
    target_trough_ng_ml: float = 6.0
    egfr_ml_min: float = 90.0
    alt_u_l: float = 22.0
    age: int = 45
    days_since_start: int = 0
    cyp3a_inhibitor: bool = False
    cyp3a_inducer: bool = False
    nephrotoxic_co_therapy: bool = False
    hepatic_dysfunction: bool = False
    trough_monitoring_ready: bool = True


def clamp(value: float, lo: float = 0.0, hi: float = 100.0) -> float:
    return max(lo, min(hi, value))


def phenotype_scores(status: str) -> tuple[float, float, str]:
    s = status.lower().strip()
    mapping = {
        "expresser": (44.0, 3.0, "CYP3A5 expresser: lower tacrolimus exposure is common"),
        "intermediate": (24.0, 10.0, "CYP3A5 intermediate: partial underexposure risk"),
        "poor": (6.0, 40.0, "CYP3A5 poor metabolizer: higher exposure / toxicity concern"),
        "unknown": (18.0, 18.0, "CYP3A5 status unknown before tacrolimus planning"),
    }
    return mapping.get(s, mapping["unknown"])


def dose_mg_per_kg(starting_dose_mg_per_day: float, weight_kg: float) -> float:
    return starting_dose_mg_per_day / max(weight_kg, 30.0)


def score_underexposure(p: TacroPatient) -> tuple[float, List[dict]]:
    score = 0.0
    domains: List[dict] = []

    geno, tox, detail = phenotype_scores(p.cyp3a5)
    domains.append({"name": "genotype", "under": geno, "tox": tox, "detail": detail})
    score += geno

    mg_per_kg = dose_mg_per_kg(p.starting_dose_mg_per_day, p.weight_kg)
    if mg_per_kg < 0.04:
        val = 24.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is quite conservative"
    elif mg_per_kg < 0.06:
        val = 14.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day may under-shoot early targets"
    elif mg_per_kg < 0.08:
        val = 5.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is in a typical starting range"
    else:
        val = 0.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is relatively robust"
    domains.append({"name": "starting_dose", "under": val, "tox": 0.0, "detail": detail})
    score += val

    if p.cyp3a_inducer:
        domains.append({"name": "inducer", "under": 20.0, "tox": 0.0, "detail": "CYP3A inducer detected"})
        score += 20.0
    else:
        domains.append({"name": "inducer", "under": 0.0, "tox": 0.0, "detail": "No CYP3A inducer"})

    if p.target_trough_ng_ml >= 8:
        domains.append({"name": "target", "under": 8.0, "tox": 0.0, "detail": f"Target trough {p.target_trough_ng_ml:.1f} ng/mL is relatively ambitious"})
        score += 8.0
    elif p.target_trough_ng_ml >= 6:
        domains.append({"name": "target", "under": 4.0, "tox": 0.0, "detail": f"Target trough {p.target_trough_ng_ml:.1f} ng/mL is standard for many autoimmune contexts"})
        score += 4.0
    else:
        domains.append({"name": "target", "under": 0.0, "tox": 0.0, "detail": f"Target trough {p.target_trough_ng_ml:.1f} ng/mL is comparatively low"})

    if p.days_since_start < 7:
        val = 12.0
        detail = "Very early therapy: exposure is still being stabilized"
    elif p.days_since_start < 21:
        val = 6.0
        detail = "Early therapy: dose-response remains unstable"
    else:
        val = 0.0
        detail = "Beyond the earliest high-variance window"
    domains.append({"name": "time", "under": val, "tox": 0.0, "detail": detail})
    score += val

    if not p.trough_monitoring_ready:
        domains.append({"name": "monitoring", "under": 11.0, "tox": 0.0, "detail": "No clear early trough monitoring plan"})
        score += 11.0
    else:
        domains.append({"name": "monitoring", "under": 0.0, "tox": 0.0, "detail": "Trough monitoring plan documented"})

    return clamp(score), domains


def score_toxicity(p: TacroPatient) -> tuple[float, List[dict]]:
    score = 0.0
    domains: List[dict] = []

    _, tox, detail = phenotype_scores(p.cyp3a5)
    domains.append({"name": "genotype", "under": 0.0, "tox": tox, "detail": detail})
    score += tox

    mg_per_kg = dose_mg_per_kg(p.starting_dose_mg_per_day, p.weight_kg)
    if mg_per_kg > 0.10:
        val = 30.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is aggressive"
    elif mg_per_kg > 0.08:
        val = 18.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is above a cautious start"
    elif mg_per_kg > 0.06:
        val = 7.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is moderate"
    else:
        val = 0.0
        detail = f"Starting dose {mg_per_kg:.3f} mg/kg/day is conservative"
    domains.append({"name": "starting_dose", "under": 0.0, "tox": val, "detail": detail})
    score += val

    if p.cyp3a_inhibitor:
        domains.append({"name": "inhibitor", "under": 0.0, "tox": 24.0, "detail": "CYP3A inhibitor detected"})
        score += 24.0
    else:
        domains.append({"name": "inhibitor", "under": 0.0, "tox": 0.0, "detail": "No CYP3A inhibitor"})

    if p.egfr_ml_min < 30:
        val = 30.0
        detail = f"eGFR {p.egfr_ml_min:.0f} mL/min/1.73m² is very low"
    elif p.egfr_ml_min < 45:
        val = 20.0
        detail = f"eGFR {p.egfr_ml_min:.0f} mL/min/1.73m² is reduced"
    elif p.egfr_ml_min < 60:
        val = 10.0
        detail = f"eGFR {p.egfr_ml_min:.0f} mL/min/1.73m² is mildly reduced"
    else:
        val = 0.0
        detail = f"eGFR {p.egfr_ml_min:.0f} mL/min/1.73m² is not a major renal toxicity amplifier"
    domains.append({"name": "renal", "under": 0.0, "tox": val, "detail": detail})
    score += val

    if p.hepatic_dysfunction or p.alt_u_l > 80:
        val = 14.0
        detail = "Hepatic dysfunction or marked ALT elevation present"
    elif p.alt_u_l > 45:
        val = 7.0
        detail = f"ALT {p.alt_u_l:.0f} U/L is mildly elevated"
    else:
        val = 0.0
        detail = f"ALT {p.alt_u_l:.0f} U/L is not a dominant toxicity signal"
    domains.append({"name": "hepatic", "under": 0.0, "tox": val, "detail": detail})
    score += val

    if p.nephrotoxic_co_therapy:
        domains.append({"name": "nephrotoxin", "under": 0.0, "tox": 12.0, "detail": "Concomitant nephrotoxic co-therapy present"})
        score += 12.0
    else:
        domains.append({"name": "nephrotoxin", "under": 0.0, "tox": 0.0, "detail": "No major nephrotoxic co-therapy"})

    if p.age >= 65:
        domains.append({"name": "age", "under": 0.0, "tox": 4.0, "detail": f"Age {p.age} years adds modest toxicity concern"})
        score += 4.0
    else:
        domains.append({"name": "age", "under": 0.0, "tox": 0.0, "detail": f"Age {p.age} years does not materially change toxicity risk"})

    if not p.trough_monitoring_ready:
        domains.append({"name": "monitoring", "under": 0.0, "tox": 10.0, "detail": "No clear trough monitoring plan"})
        score += 10.0
    else:
        domains.append({"name": "monitoring", "under": 0.0, "tox": 0.0, "detail": "Trough monitoring plan documented"})

    return clamp(score), domains


def risk_direction(under: float, tox: float) -> str:
    if abs(under - tox) <= 8:
        return "MIXED"
    return "UNDEREXPOSURE" if under > tox else "TOXICITY"


def risk_category(score: float) -> str:
    if score < 15:
        return "LOW"
    if score < 35:
        return "MODERATE"
    if score < 60:
        return "HIGH"
    return "VERY HIGH"


def summarize_domains(under_domains: List[dict], tox_domains: List[dict]) -> List[dict]:
    merged: Dict[str, dict] = {}
    for d in under_domains + tox_domains:
        slot = merged.setdefault(d["name"], {"name": d["name"], "under": 0.0, "tox": 0.0, "detail": d["detail"]})
        slot["under"] += float(d.get("under", 0.0))
        slot["tox"] += float(d.get("tox", 0.0))
    return list(merged.values())


def compute_tacro_cyp5(patient: TacroPatient, n_simulations: int = 5000, seed: int = 42) -> Dict[str, Any]:
    under, under_domains = score_underexposure(patient)
    tox, tox_domains = score_toxicity(patient)
    composite = clamp(max(under, tox) + 0.2 * min(under, tox))
    direction = risk_direction(under, tox)

    rng = random.Random(seed)
    simulations: List[float] = []
    direction_counts = {"UNDEREXPOSURE": 0, "TOXICITY": 0, "MIXED": 0}

    for _ in range(n_simulations):
        noisy = TacroPatient(
            cyp3a5=patient.cyp3a5 if rng.random() > 0.03 else "unknown",
            weight_kg=max(30.0, patient.weight_kg + rng.gauss(0, 1.8)),
            starting_dose_mg_per_day=max(0.5, patient.starting_dose_mg_per_day + rng.gauss(0, 0.2)),
            target_trough_ng_ml=max(3.0, patient.target_trough_ng_ml + rng.gauss(0, 0.4)),
            egfr_ml_min=max(5.0, patient.egfr_ml_min + rng.gauss(0, 4.0)),
            alt_u_l=max(5.0, patient.alt_u_l + rng.gauss(0, 6.0)),
            age=patient.age,
            days_since_start=max(0, int(round(patient.days_since_start + rng.gauss(0, 1.0)))),
            cyp3a_inhibitor=patient.cyp3a_inhibitor if rng.random() > 0.01 else not patient.cyp3a_inhibitor,
            cyp3a_inducer=patient.cyp3a_inducer if rng.random() > 0.01 else not patient.cyp3a_inducer,
            nephrotoxic_co_therapy=patient.nephrotoxic_co_therapy if rng.random() > 0.01 else not patient.nephrotoxic_co_therapy,
            hepatic_dysfunction=patient.hepatic_dysfunction if rng.random() > 0.02 else not patient.hepatic_dysfunction,
            trough_monitoring_ready=patient.trough_monitoring_ready if rng.random() > 0.05 else not patient.trough_monitoring_ready,
        )
        u, _ = score_underexposure(noisy)
        t, _ = score_toxicity(noisy)
        sim = clamp(max(u, t) + 0.2 * min(u, t))
        simulations.append(sim)
        direction_counts[risk_direction(u, t)] += 1

    simulations.sort()
    low_idx = int(0.025 * (n_simulations - 1))
    high_idx = int(0.975 * (n_simulations - 1))
    ci_low = round(simulations[low_idx], 1)
    ci_high = round(simulations[high_idx], 1)

    return {
        "input_summary": asdict(patient),
        "underexposure_score": round(under, 1),
        "toxicity_score": round(tox, 1),
        "composite_score": round(composite, 1),
        "risk_category": risk_category(composite),
        "dominant_direction": direction,
        "ci_lower": ci_low,
        "ci_upper": ci_high,
        "direction_counts": direction_counts,
        "domains": summarize_domains(under_domains, tox_domains),
        "recommendation": recommend(patient, composite, direction, under, tox),
        "monitoring_comment": monitoring_comment(patient, direction),
        "limitations": [
            "Heuristic model, not a validated population pharmacokinetic engine.",
            "CPIC dosing guidance and clinician trough monitoring remain the standard reference points.",
            "Does not replace urgent evaluation for AKI, neurotoxicity, infection, or liver injury.",
            "Drug labels and local protocols may differ for lupus nephritis, vasculitis, and transplant contexts.",
        ],
    }


def recommend(patient: TacroPatient, composite: float, direction: str, under: float, tox: float) -> str:
    if composite < 15:
        return "Tacrolimus can usually start with routine genotype-aware planning and early trough follow-up."
    if direction == "UNDEREXPOSURE":
        return "This profile favors underexposure. Confirm CYP3A5 status, review inducers, and plan early trough-guided titration."
    if direction == "TOXICITY":
        return "This profile favors toxicity. Review inhibitors, renal/hepatic context, and consider a more conservative start or alternative strategy."
    return "This is a mixed-risk profile. Do not rely on dose alone; integrate genotype, renal function, and early trough data."


def monitoring_comment(patient: TacroPatient, direction: str) -> str:
    parts = []
    if not patient.trough_monitoring_ready:
        parts.append("Monitoring plan is not yet documented.")
    else:
        parts.append("Trough monitoring is documented.")
    if direction == "UNDEREXPOSURE":
        parts.append("Earlier first trough may help avoid prolonged subtherapeutic exposure.")
    elif direction == "TOXICITY":
        parts.append("Early renal function and tacrolimus level checks are important.")
    else:
        parts.append("Mixed exposure instability justifies close lab and medication review.")
    return " ".join(parts)


def fmt_result(label: str, result: Dict[str, Any]) -> str:
    lines = [
        f"{label}",
        f"  Composite: {result['composite_score']:.1f} ({result['risk_category']}, {result['dominant_direction']})",
        f"  95% CI: {result['ci_lower']:.1f} to {result['ci_upper']:.1f}",
        f"  Underexposure: {result['underexposure_score']:.1f}",
        f"  Toxicity: {result['toxicity_score']:.1f}",
        f"  Recommendation: {result['recommendation']}",
        f"  Monitoring: {result['monitoring_comment']}",
    ]
    return "\n".join(lines)


def demo() -> None:
    scenarios = [
        (
            "Scenario 1 - CYP3A5 expresser with lupus nephritis induction and weak starting exposure",
            TacroPatient(
                cyp3a5="expresser",
                weight_kg=72,
                starting_dose_mg_per_day=3.0,
                target_trough_ng_ml=8.0,
                egfr_ml_min=88,
                alt_u_l=24,
                age=34,
                days_since_start=3,
                cyp3a_inducer=False,
                cyp3a_inhibitor=False,
                nephrotoxic_co_therapy=False,
                hepatic_dysfunction=False,
                trough_monitoring_ready=False,
            ),
        ),
        (
            "Scenario 2 - Poor metabolizer with reduced kidney function and inhibitor exposure",
            TacroPatient(
                cyp3a5="poor",
                weight_kg=60,
                starting_dose_mg_per_day=6.0,
                target_trough_ng_ml=6.0,
                egfr_ml_min=38,
                alt_u_l=58,
                age=67,
                days_since_start=10,
                cyp3a_inhibitor=True,
                cyp3a_inducer=False,
                nephrotoxic_co_therapy=True,
                hepatic_dysfunction=False,
                trough_monitoring_ready=True,
            ),
        ),
        (
            "Scenario 3 - Unknown genotype with moderate dose and monitoring in place",
            TacroPatient(
                cyp3a5="unknown",
                weight_kg=68,
                starting_dose_mg_per_day=4.0,
                target_trough_ng_ml=6.0,
                egfr_ml_min=74,
                alt_u_l=28,
                age=46,
                days_since_start=14,
                cyp3a_inhibitor=False,
                cyp3a_inducer=False,
                nephrotoxic_co_therapy=False,
                hepatic_dysfunction=False,
                trough_monitoring_ready=True,
            ),
        ),
    ]

    for label, patient in scenarios:
        result = compute_tacro_cyp5(patient)
        print(fmt_result(label, result))
        print("  Top domains:")
        for domain in result["domains"]:
            if domain["under"] or domain["tox"]:
                print(f"    - {domain['name']}: under={domain['under']:.1f}, tox={domain['tox']:.1f} | {domain['detail']}")
        print()


if __name__ == "__main__":
    demo()

```

## Demo Output

```
Scenario 1 - CYP3A5 expresser with lupus nephritis induction and weak starting exposure
  Composite: 91.6 (VERY HIGH, UNDEREXPOSURE)
  95% CI: 74.6 to 100.0
  Underexposure: 89.0
  Toxicity: 13.0
  Recommendation: This profile favors underexposure. Confirm CYP3A5 status, review inducers, and plan early trough-guided titration.
  Monitoring: Monitoring plan is not yet documented. Earlier first trough may help avoid prolonged subtherapeutic exposure.
  Top domains:
    - genotype: under=44.0, tox=6.0 | CYP3A5 expresser: lower tacrolimus exposure is common
    - starting_dose: under=14.0, tox=0.0 | Starting dose 0.042 mg/kg/day may under-shoot early targets
    - target: under=8.0, tox=0.0 | Target trough 8.0 ng/mL is relatively ambitious
    - time: under=12.0, tox=0.0 | Very early therapy: exposure is still being stabilized
    - monitoring: under=11.0, tox=10.0 | No clear early trough monitoring plan

Scenario 2 - Poor metabolizer with reduced kidney function and inhibitor exposure
  Composite: 100.0 (VERY HIGH, TOXICITY)
  95% CI: 100.0 to 100.0
  Underexposure: 16.0
  Toxicity: 100.0
  Recommendation: This profile favors toxicity. Review inhibitors, renal/hepatic context, and consider a more conservative start or alternative strategy.
  Monitoring: Trough monitoring is documented. Early renal function and tacrolimus level checks are important.
  Top domains:
    - genotype: under=6.0, tox=80.0 | CYP3A5 poor metabolizer: higher exposure / toxicity concern
    - starting_dose: under=0.0, tox=18.0 | Starting dose 0.100 mg/kg/day is relatively robust
    - target: under=4.0, tox=0.0 | Target trough 6.0 ng/mL is standard for many autoimmune contexts
    - time: under=6.0, tox=0.0 | Early therapy: dose-response remains unstable
    - inhibitor: under=0.0, tox=24.0 | CYP3A inhibitor detected
    - renal: under=0.0, tox=20.0 | eGFR 38 mL/min/1.73m² is reduced
    - hepatic: under=0.0, tox=7.0 | ALT 58 U/L is mildly elevated
    - nephrotoxin: under=0.0, tox=12.0 | Concomitant nephrotoxic co-therapy present
    - age: under=0.0, tox=4.0 | Age 67 years adds modest toxicity concern

Scenario 3 - Unknown genotype with moderate dose and monitoring in place
  Composite: 45.6 (HIGH, UNDEREXPOSURE)
  95% CI: 34.0 to 55.6
  Underexposure: 42.0
  Toxicity: 18.0
  Recommendation: This profile favors underexposure. Confirm CYP3A5 status, review inducers, and plan early trough-guided titration.
  Monitoring: Trough monitoring is documented. Earlier first trough may help avoid prolonged subtherapeutic exposure.
  Top domains:
    - genotype: under=18.0, tox=36.0 | CYP3A5 status unknown before tacrolimus planning
    - starting_dose: under=14.0, tox=0.0 | Starting dose 0.059 mg/kg/day may under-shoot early targets
    - target: under=4.0, tox=0.0 | Target trough 6.0 ng/mL is standard for many autoimmune contexts
    - time: under=6.0, tox=0.0 | Early therapy: dose-response remains unstable
```