---
name: hepatotox-hcc-monitor
description: Real-time hepatotoxicity signal detection for any drug in hepatocellular carcinoma (HCC) patients using FDA FAERS data via openFDA API. Calculates PRR, ROR, BCPNN signal scores and generates clinical risk assessments with actionable recommendations.
allowed-tools: Bash(python *)
---

# HepatoTox: HCC Drug Hepatotoxicity Signal Detector

This Skill performs real-time pharmacovigilance signal detection for drug-induced hepatotoxicity in hepatocellular carcinoma (HCC) patients using the FDA FAERS database via the openFDA API.

## What It Does

1. Queries the openFDA API for adverse event reports
2. Builds HCC-specific 2x2 contingency tables
3. Calculates three signal detection algorithms: PRR, ROR, BCPNN IC
4. Performs multi-algorithm consensus risk assessment
5. Generates clinical recommendations based on risk level

## Requirements

- Python 3.7+ (no external packages needed - uses only standard library)
- Internet access to `api.fda.gov`

## Step 1: Save the Analysis Script

Create `hepatotox_analyzer.py` with the analysis code (see attached script).

## Step 2: Analyze a Single Drug

```bash
python hepatotox_analyzer.py --drug Sorafenib
```

This outputs:
- 2x2 contingency table (HCC patients only)
- PRR, ROR, BCPNN IC with 95% confidence intervals
- Risk level (HIGH / MODERATE / LOW / NO SIGNAL)
- Top hepatotoxic adverse events
- Clinical recommendations

## Step 3: Analyze Multiple Drugs

```bash
# All default HCC drugs (14 drugs)
python hepatotox_analyzer.py --all

# Custom drug list
python hepatotox_analyzer.py --drugs "Sorafenib,Lenvatinib,Nivolumab"
```

## Step 4: Review the Summary Report

The tool outputs a summary table comparing all analyzed drugs:

```
Drug                   Cases      PRR      ROR   BCPNN   Sig Risk
----------------------------------------------------------------------
Sorafenib               162     1.12     1.14    1.86     1 LOW RISK
...
```

## Supported Drugs (Default List)

| Category | Drugs |
|----------|-------|
| Multi-kinase inhibitors | Sorafenib, Lenvatinib, Regorafenib, Cabozantinib, Donafenib |
| PD-1 inhibitors | Nivolumab, Pembrolizumab, Sintilimab, Camrelizumab, Tislelizumab |
| PD-L1 inhibitor | Atezolizumab |
| CTLA-4 inhibitor | Ipilimumab |
| Anti-angiogenic | Bevacizumab, Ramucirumab |

**Any drug name can be analyzed** - the list above is just the default set.

## Algorithm Details

### Signal Detection Methods

- **PRR (Proportional Reporting Ratio)**: $PRR = \frac{a/(a+b)}{c/(c+d)}$, significant when PRR > 2 and lower CI > 1
- **ROR (Reporting Odds Ratio)**: $ROR = \frac{a/c}{b/d}$, significant when ROR > 2 and lower CI > 1
- **BCPNN IC (Information Component)**: $IC = \log_2\frac{P_{11}}{P_{1\cdot} \cdot P_{\cdot 1}}$, significant when IC > 0 and lower CI > 0

### Risk Assessment

- **HIGH**: >= 3 algorithms significant + case count >= 5
- **MODERATE**: >= 2 algorithms significant + case count >= 3
- **LOW**: >= 1 algorithm significant + case count >= 1
- **NO SIGNAL**: no significant algorithms

### Data Source

- FDA FAERS via openFDA API (`https://api.fda.gov/drug/event.json`)
- HCC patients identified via indication keywords (hepatocellular carcinoma, liver cancer, HCC, hepatoma)
- 30+ hepatotoxicity MedDRA Preferred Terms searched


## Attached Analysis Script

```python
#!/usr/bin/env python3
"""
HepatoTox Signal Detector
Real-time hepatotoxicity signal detection for any drug using FDA FAERS data via openFDA API.

Zero external dependencies - uses only Python standard library.
"""

import json
import math
import sys
import time
import urllib.request
import urllib.parse
import urllib.error

# ============================================================================
# Configuration
# ============================================================================

OPENFDA_BASE = "https://api.fda.gov/drug/event.json"
REQUEST_INTERVAL = 0.35  # seconds between API calls to avoid rate limiting

HEPATOTOXIC_KEYWORDS = [
    "hepatotoxicity",
    "liver function test abnormal",
    "liver function test increased",
    "hyperbilirubinaemia",
    "hyperbilirubinemia",
    "transaminases increased",
    "transaminase increased",
    "hepatic enzyme increased",
    "liver enzymes increased",
    "hepatic failure",
    "liver failure",
    "acute hepatic failure",
    "chronic hepatic failure",
    "hepatitis",
    "hepatitis acute",
    "hepatitis toxic",
    "hepatitis cholestatic",
    "cholestasis",
    "cholestatic liver injury",
    "jaundice",
    "jaundice cholestatic",
    "alanine aminotransferase increased",
    "alt increased",
    "aspartate aminotransferase increased",
    "ast increased",
    "blood bilirubin increased",
    "gamma-glutamyltransferase increased",
    "gg increased",
    "alkaline phosphatase increased",
    "liver injury",
    "hepatic function abnormal",
    "liver damage",
    "hepatocellular damage",
    "bile duct stenosis",
    "biliary dilatation",
]

# Deduplicate (some terms appear twice in original config)
HEPATOTOXIC_KEYWORDS = list(dict.fromkeys(HEPATOTOXIC_KEYWORDS))

HCC_INDICATIONS = [
    "hepatocellular carcinoma",
    "liver cancer",
    "hcc",
    "hepatoma",
]

# Default HCC drug list for batch analysis
DEFAULT_HCC_DRUGS = [
    "Sorafenib", "Lenvatinib", "Regorafenib", "Cabozantinib",
    "Donafenib", "Nivolumab", "Pembrolizumab", "Ipilimumab",
    "Atezolizumab", "Bevacizumab", "Ramucirumab",
    "Sintilimab", "Camrelizumab", "Tislelizumab",
]

RISK_LABELS = {
    "high": "HIGH RISK",
    "medium": "MODERATE RISK",
    "low": "LOW RISK",
    "no_signal": "NO SIGNAL",
}

RISK_RECOMMENDATIONS = {
    "high": [
        "Consider discontinuation or dose interruption of the drug",
        "Perform comprehensive liver function panel immediately (ALT, AST, ALP, GGT, total bilirubin, albumin, PT)",
        "Exclude other causes of liver injury (viral hepatitis, alcohol, other hepatotoxic drugs)",
        "Consult hepatology specialist",
        "Assess hepatotoxicity grade per CTCAE v5.0",
        "If signs of liver failure (jaundice, coagulopathy, encephalopathy), discontinue immediately and hospitalize",
    ],
    "medium": [
        "Monitor liver function closely (1-2 times per week)",
        "Check liver panel: ALT, AST, ALP, GGT, total bilirubin",
        "Consider temporary dose reduction or interruption until liver function recovers",
        "Exclude other causes of liver injury",
        "Educate patient on hepatotoxicity symptoms: fatigue, nausea, jaundice, dark urine",
    ],
    "low": [
        "Routine liver function monitoring (every 2-4 weeks)",
        "Educate patient on hepatotoxicity symptoms",
        "Continue current treatment, but watch for new liver abnormalities",
    ],
    "no_signal": [
        "No hepatotoxicity signal detected in FAERS data",
        "Routine liver function monitoring recommended",
        "Continue current treatment protocol",
    ],
}


# ============================================================================
# openFDA API Client
# ============================================================================

_last_request_time = 0


def _rate_limit():
    global _last_request_time
    elapsed = time.time() - _last_request_time
    if elapsed < REQUEST_INTERVAL:
        time.sleep(REQUEST_INTERVAL - elapsed)
    _last_request_time = time.time()


def query_total(search_query):
    """Return total matching report count from openFDA."""
    params = urllib.parse.urlencode({"search": search_query, "limit": 1})
    url = f"{OPENFDA_BASE}?{params}"
    _rate_limit()
    try:
        req = urllib.request.Request(url, headers={"User-Agent": "HepatoTox-Skill/1.0"})
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read())
            return data["meta"]["results"]["total"]
    except urllib.error.HTTPError as e:
        if e.code == 404:
            return 0
        raise
    except Exception as e:
        print(f"  [WARN] API query failed: {e}", file=sys.stderr)
        return 0


def query_top_reactions(search_query, limit=20):
    """Return top reaction terms with counts."""
    params = urllib.parse.urlencode({
        "search": search_query,
        "count": "patient.reaction.reactionmeddrapt.exact",
        "limit": limit,
    })
    url = f"{OPENFDA_BASE}?{params}"
    _rate_limit()
    try:
        req = urllib.request.Request(url, headers={"User-Agent": "HepatoTox-Skill/1.0"})
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read())
            return [(r["term"], r["count"]) for r in data.get("results", [])]
    except urllib.error.HTTPError as e:
        if e.code == 404:
            return []
        raise
    except Exception as e:
        print(f"  [WARN] Reaction query failed: {e}", file=sys.stderr)
        return []


# ============================================================================
# Query Builders
# ============================================================================

def _build_hepatotoxicity_or():
    """Build OR clause for all hepatotoxicity keywords."""
    terms = [f'"{kw}"' for kw in HEPATOTOXIC_KEYWORDS]
    return "patient.reaction.reactionmeddrapt:(" + " OR ".join(terms) + ")"


def _build_hcc_or():
    """Build OR clause for HCC indication keywords."""
    terms = [f'"{kw}"' for kw in HCC_INDICATIONS]
    return "patient.drug.drugindication:(" + " OR ".join(terms) + ")"


def _drug_query(drug_name):
    return f'patient.drug.medicinalproduct:"{drug_name}"'


# ============================================================================
# Contingency Table Builder
# ============================================================================

def build_contingency_table(drug_name):
    """
    Build 2x2 contingency table for signal detection.

    Returns dict with a, b, c, d and derived counts.
    All counts are HCC-specific.
    """
    drug_q = _drug_query(drug_name)
    hcc_q = _build_hcc_or()
    hep_q = _build_hepatotoxicity_or()

    # a+b: drug + HCC indication
    ab = query_total(f"{drug_q} AND {hcc_q}")

    # a: drug + HCC + hepatotoxicity
    a = query_total(f"{drug_q} AND {hcc_q} AND {hep_q}")

    # a+c: HCC + hepatotoxicity (all drugs)
    ac = query_total(f"{hcc_q} AND {hep_q}")

    # total HCC
    total_hcc = query_total(f"{hcc_q}")

    b = ab - a
    c = ac - a
    d = total_hcc - a - b - c

    return {
        "drug": drug_name,
        "a": max(a, 0),
        "b": max(b, 0),
        "c": max(c, 0),
        "d": max(d, 0),
        "total_drug_hcc": ab,
        "total_hcc_hepatotoxicity": ac,
        "total_hcc": total_hcc,
    }


# ============================================================================
# Signal Detection Algorithms (from signal_scores.py, numpy-free)
# ============================================================================

def calc_prr(a, b, c, d):
    """Proportional Reporting Ratio with 95% Wald CI."""
    if a <= 0 or b <= 0 or c <= 0 or d <= 0:
        return {"value": 0, "lower_ci": 0, "upper_ci": 0, "significant": False}
    prr = (a / (a + b)) / (c / (c + d))
    var_log = 1 / a - 1 / (a + b) + 1 / c - 1 / (c + d)
    if var_log > 0:
        se = math.sqrt(var_log)
        lower = math.exp(math.log(prr) - 1.96 * se)
        upper = math.exp(math.log(prr) + 1.96 * se)
    else:
        lower, upper = 0, 0
    return {
        "value": round(prr, 4),
        "lower_ci": round(lower, 4),
        "upper_ci": round(upper, 4),
        "significant": prr > 2.0 and lower > 1.0,
    }


def calc_ror(a, b, c, d):
    """Reporting Odds Ratio with 95% CI."""
    if a <= 0 or b <= 0 or c <= 0 or d <= 0:
        return {"value": 0, "lower_ci": 0, "upper_ci": 0, "significant": False}
    ror = (a / c) / (b / d)
    se = math.sqrt(1 / a + 1 / b + 1 / c + 1 / d)
    lower = math.exp(math.log(ror) - 1.96 * se)
    upper = math.exp(math.log(ror) + 1.96 * se)
    return {
        "value": round(ror, 4),
        "lower_ci": round(lower, 4),
        "upper_ci": round(upper, 4),
        "significant": ror > 2.0 and lower > 1.0,
    }


def calc_bcpnn_ic(a, b, c, d):
    """BCPNN Information Component (normal approximation)."""
    if a <= 0 or b <= 0 or c <= 0 or d <= 0:
        return {"value": 0, "lower_ci": 0, "upper_ci": 0, "significant": False}
    N = a + b + c + d
    E = (a + b) * (a + c) / N
    if E <= 0:
        return {"value": 0, "lower_ci": 0, "upper_ci": 0, "significant": False}
    p1 = a / (a + c)
    p2 = b / (b + d)
    p11 = a / N
    if p1 <= 0 or p2 <= 0 or p11 <= 0:
        return {"value": 0, "lower_ci": 0, "upper_ci": 0, "significant": False}
    ic = (1 / math.log(2)) * math.log(p11 / (p1 * p2))
    se = math.sqrt((1 - p11) / (a + 0.5))
    lower = ic - 1.96 * se
    upper = ic + 1.96 * se
    return {
        "value": round(ic, 4),
        "lower_ci": round(lower, 4),
        "upper_ci": round(upper, 4),
        "significant": ic > 0 and lower > 0,
    }


def assess_risk(prr, ror, bcpnn, case_count):
    """Multi-algorithm consensus risk assessment."""
    sig_count = sum([prr["significant"], ror["significant"], bcpnn["significant"]])
    case_score = (1 if case_count >= 3 else 0) + \
                 (1 if case_count >= 5 else 0) + \
                 (1 if case_count >= 10 else 0)
    if sig_count >= 3 and case_score >= 2:
        return "high"
    if sig_count >= 2 and case_score >= 1:
        return "medium"
    if sig_count >= 1 and case_count >= 1:
        return "low"
    return "no_signal"


# ============================================================================
# Main Analysis
# ============================================================================

def analyze_drug(drug_name):
    """
    Complete hepatotoxicity analysis for a single drug.
    Returns dict with all results.
    """
    print(f"\n{'='*70}")
    print(f"  Analyzing: {drug_name}")
    print(f"{'='*70}")

    # Build contingency table
    ct = build_contingency_table(drug_name)
    a, b, c, d = ct["a"], ct["b"], ct["c"], ct["d"]

    if ct["total_drug_hcc"] == 0:
        print(f"  No FAERS reports found for '{drug_name}' with HCC indication.")
        return None

    # Signal detection
    prr = calc_prr(a, b, c, d)
    ror = calc_ror(a, b, c, d)
    bcpnn = calc_bcpnn_ic(a, b, c, d)
    risk = assess_risk(prr, ror, bcpnn, a)

    # Top reactions (drug + HCC)
    drug_q = _drug_query(drug_name)
    hcc_q = _build_hcc_or()
    all_reactions = query_top_reactions(f"{drug_q} AND {hcc_q}", limit=50)
    hep_set = set(kw.lower() for kw in HEPATOTOXIC_KEYWORDS)
    hep_reactions = [(t, cnt) for t, cnt in all_reactions if t.lower() in hep_set]

    result = {
        "drug": drug_name,
        "contingency_table": ct,
        "signals": {
            "PRR": prr,
            "ROR": ror,
            "BCPNN_IC": bcpnn,
        },
        "risk_level": risk,
        "case_count": a,
        "significant_algorithms": sum([
            prr["significant"], ror["significant"], bcpnn["significant"]
        ]),
        "top_hepatotoxic_events": hep_reactions[:10],
        "recommendations": RISK_RECOMMENDATIONS.get(risk, []),
    }

    _print_report(result)
    return result


def analyze_all_drugs(drugs=None):
    """Analyze all drugs and return summary."""
    if drugs is None:
        drugs = DEFAULT_HCC_DRUGS
    results = []
    for drug in drugs:
        r = analyze_drug(drug)
        if r:
            results.append(r)

    print(f"\n{'='*70}")
    print("  SUMMARY: HCC Drug Hepatotoxicity Risk Assessment")
    print(f"{'='*70}")
    print(f"{'Drug':<20} {'Cases':>6} {'PRR':>8} {'ROR':>8} {'BCPNN':>8} {'Sig':>4} {'Risk':<15}")
    print("-" * 70)
    for r in sorted(results, key=lambda x: x["case_count"], reverse=True):
        sig = sum([
            r["signals"]["PRR"]["significant"],
            r["signals"]["ROR"]["significant"],
            r["signals"]["BCPNN_IC"]["significant"],
        ])
        print(
            f"{r['drug']:<20} "
            f"{r['case_count']:>6} "
            f"{r['signals']['PRR']['value']:>8.2f} "
            f"{r['signals']['ROR']['value']:>8.2f} "
            f"{r['signals']['BCPNN_IC']['value']:>8.2f} "
            f"{sig:>4} "
            f"{RISK_LABELS[r['risk_level']]:<15}"
        )
    return results


def _print_report(result):
    ct = result["contingency_table"]
    sig = result["signals"]
    print(f"\n  Contingency Table (HCC patients):")
    print(f"  {'':>20} | {'Hepatotoxic':>12} | {'Other':>12} | {'Total':>12}")
    print(f"  {'-'*20}-+-{'-'*12}-+-{'-'*12}-+-{'-'*12}")
    print(f"  {result['drug']:>20} | {ct['a']:>12} | {ct['b']:>12} | {ct['a']+ct['b']:>12}")
    print(f"  {'Other drugs':>20} | {ct['c']:>12} | {ct['d']:>12} | {ct['c']+ct['d']:>12}")
    print(f"  {'-'*20}-+-{'-'*12}-+-{'-'*12}-+-{'-'*12}")
    print(f"  {'Total':>20} | {ct['a']+ct['c']:>12} | {ct['b']+ct['d']:>12} | {ct['total_hcc']:>12}")

    print(f"\n  Signal Scores:")
    for name, s in sig.items():
        mark = " *" if s["significant"] else "  "
        print(f"  {mark} {name:>8} = {s['value']:>8.4f}  (95%CI: {s['lower_ci']:.4f} - {s['upper_ci']:.4f})")

    print(f"\n  Risk Level: {RISK_LABELS[result['risk_level']]}")
    print(f"  Significant algorithms: {result['significant_algorithms']}/3")
    print(f"  Case count: {result['case_count']}")

    if result["top_hepatotoxic_events"]:
        print(f"\n  Top Hepatotoxic Events:")
        for event, count in result["top_hepatotoxic_events"]:
            print(f"    - {event}: {count}")

    print(f"\n  Clinical Recommendations:")
    for rec in result["recommendations"][:3]:
        print(f"    > {rec}")


# ============================================================================
# CLI
# ============================================================================

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage:")
        print(f"  python {sys.argv[0]} --drug <drug_name>   Analyze a single drug")
        print(f"  python {sys.argv[0]} --all                Analyze all default HCC drugs")
        print(f"  python {sys.argv[0]} --drugs A,B,C        Analyze specific drugs")
        sys.exit(0)

    cmd = sys.argv[1].lower()

    if cmd == "--drug" and len(sys.argv) >= 3:
        drug = sys.argv[2]
        result = analyze_drug(drug)
    elif cmd == "--all":
        results = analyze_all_drugs()
    elif cmd == "--drugs" and len(sys.argv) >= 3:
        drugs = [d.strip() for d in sys.argv[2].split(",")]
        results = analyze_all_drugs(drugs)
    else:
        print(f"Unknown command: {cmd}")
        sys.exit(1)

```