tooluniverse-adverse-event-detection

# Adverse Drug Event Signal Detection & Analysis

Automated pipeline for detecting, quantifying, and contextualizing adverse drug event signals using FAERS disproportionality analysis, FDA label mining, mechanism-based prediction, and literature evidence. Produces a quantitative Safety Signal Score (0-100) for regulatory and clinical decision-making.

**KEY PRINCIPLES**:
1. **Signal quantification first** - Every adverse event must have PRR/ROR/IC with confidence intervals
2. **Serious events priority** - Deaths, hospitalizations, life-threatening events always analyzed first
3. **Multi-source triangulation** - FAERS + FDA labels + OpenTargets + DrugBank + literature
4. **Context-aware assessment** - Distinguish drug-specific vs class-wide vs confounding signals
5. **Report-first approach** - Create report file FIRST, update progressively
6. **Evidence grading mandatory** - T1 (regulatory/boxed warning) through T4 (computational)
7. **English-first queries** - Always use English drug names in tool calls, respond in user's language

---

## When to Use

Apply when user asks:
- "What are the safety signals for [drug]?"
- "Detect adverse events for [drug]"
- "Is [drug] associated with [adverse event]?"
- "What are the FAERS signals for [drug]?"
- "Compare safety of [drug A] vs [drug B] for [adverse event]"
- "What are the serious adverse events for [drug]?"
- "Are there emerging safety signals for [drug]?"
- "Post-market surveillance report for [drug]"
- "Pharmacovigilance signal detection for [drug]"
- "What is the disproportionality analysis for [drug] and [event]?"

**Differentiation from tooluniverse-pharmacovigilance**: This skill focuses specifically on **signal detection and quantification** using disproportionality analysis (PRR, ROR, IC) with statistical rigor, produces a quantitative **Safety Signal Score (0-100)**, and performs **comparative safety analysis** across drug classes. The pharmacovigilance skill provides broader safety profiling without the same depth of signal detection metrics.

---

## Workflow Overview

```
Phase 0: Input Parsing & Drug Disambiguation
  Parse drug name, resolve to ChEMBL ID, DrugBank ID
  Identify drug class, mechanism, and approved indications
    |
Phase 1: FAERS Adverse Event Profiling
  Top adverse events by frequency
  Seriousness and outcome distributions
  Demographics (age, sex, country)
    |
Phase 2: Disproportionality Analysis (Signal Detection)
  Calculate PRR, ROR, IC with 95% CI for each AE
  Apply signal detection criteria
  Classify signal strength (Strong/Moderate/Weak/None)
    |
Phase 3: FDA Label Safety Information
  Boxed warnings, contraindications
  Warnings and precautions, adverse reactions
  Drug interactions, special populations
    |
Phase 4: Mechanism-Based Adverse Event Context
  Target-based AE prediction (OpenTargets safety)
  Off-target effects, ADMET predictions
  Drug class effects comparison
    |
Phase 5: Comparative Safety Analysis
  Compare to drugs in same class
  Identify unique vs class-wide signals
  Head-to-head disproportionality comparison
    |
Phase 6: Drug-Drug Interactions & Risk Factors
  Known DDIs causing AEs
  Pharmacogenomic risk factors (PharmGKB)
  FDA PGx biomarkers
    |
Phase 7: Literature Evidence
  PubMed safety studies, case reports
  OpenAlex citation analysis
  Preprint emerging signals (EuropePMC)
    |
Phase 8: Risk Assessment & Safety Signal Score
  Calculate Safety Signal Score (0-100)
  Evidence grading (T1-T4) for each signal
  Clinical significance assessment
    |
Phase 9: Report Synthesis & Recommendations
  Monitoring recommendations
  Risk mitigation strategies
  Completeness checklist
```

---

## Phase 0: Input Parsing & Drug Disambiguation

### 0.1 Resolve Drug Identity

```python
# Step 1: Get ChEMBL ID from drug name
chembl_result = tu.tools.OpenTargets_get_drug_chembId_by_generic_name(drugName="atorvastatin")
# Response: {data: {search: {hits: [{id: "CHEMBL1487", name: "ATORVASTATIN", description: "..."}]}}}
chembl_id = chembl_result['data']['search']['hits'][0]['id']  # "CHEMBL1487"

# Step 2: Get drug mechanism of action
moa = tu.tools.OpenTargets_get_drug_mechanisms_of_action_by_chemblId(chemblId=chembl_id)
# Response: {data: {drug: {mechanismsOfAction: {rows: [{mechanismOfAction: "HMG-CoA reductase inhibitor", actionType: "INHIBITOR", targetName: "...", targets: [{id: "ENSG00000113161", approvedSymbol: "HMGCR"}]}]}}}}

# Step 3: Get blackbox warning status
blackbox = tu.tools.OpenTargets_get_drug_blackbox_status_by_chembl_ID(chemblId=chembl_id)
# Response: {data: {drug: {name: "ATORVASTATIN", hasBeenWithdrawn: false, blackBoxWarning: false}}}

# Step 4: Get DrugBank info (safety, toxicity)
drugbank = tu.tools.drugbank_get_safety_by_drug_name_or_drugbank_id(
    query="atorvastatin", case_sensitive=False, exact_match=False, limit=3
)
# Response: {results: [{drug_name: "Atorvastatin", drugbank_id: "DB01076", toxicity: "...", food_interactions: "..."}]}

# Step 5: Get DrugBank targets
targets = tu.tools.drugbank_get_targets_by_drug_name_or_drugbank_id(
    query="atorvastatin", case_sensitive=False, exact_match=False, limit=3
)
# Response: {results: [{drug_name: "...", targets: [{name: "HMG-CoA reductase", ...}]}]}

# Step 6: Get approved indications
indications = tu.tools.OpenTargets_get_drug_indications_by_chemblId(chemblId=chembl_id)
# Response: {data: {drug: {indications: {rows: [{disease: {name: "hypercholesterolemia"}, maxPhaseForIndication: 4}]}}}}
```

### 0.2 Output for Report

```markdown
## 1. Drug Identification

| Property | Value |
|----------|-------|
| **Generic Name** | Atorvastatin |
| **ChEMBL ID** | CHEMBL1487 |
| **DrugBank ID** | DB01076 |
| **Drug Class** | HMG-CoA reductase inhibitor (Statin) |
| **Mechanism** | HMG-CoA reductase inhibitor (target: HMGCR) |
| **Primary Target** | HMGCR (ENSG00000113161) |
| **Black Box Warning** | No |
| **Withdrawn** | No |

*Source: OpenTargets, DrugBank*
```

---

## Phase 1: FAERS Adverse Event Profiling

### 1.1 Query FAERS for Adverse Events

```python
# Get top adverse event reactions (returns list of {term, count})
reactions = tu.tools.FAERS_count_reactions_by_drug_event(medicinalproduct="ATORVASTATIN")
# Response: [{term: "FATIGUE", count: 19171}, {term: "DIARRHOEA", count: 17127}, ...]

# Get seriousness classification
seriousness = tu.tools.FAERS_count_seriousness_by_drug_event(medicinalproduct="ATORVASTATIN")
# Response: [{term: "Serious", count: 242757}, {term: "Non-serious", count: 83504}]

# Get outcome distribution
outcomes = tu.tools.FAERS_count_outcomes_by_drug_event(medicinalproduct="ATORVASTATIN")
# Response: [{term: "Unknown", count: 162310}, {term: "Fatal", count: 22128}, ...]

# Get age distribution
age_dist = tu.tools.FAERS_count_patient_age_distribution(medicinalproduct="ATORVASTATIN")
# Response: [{term: "Elderly", count: 38510}, {term: "Adult", count: 24302}, ...]

# Get death-related events
deaths = tu.tools.FAERS_count_death_related_by_drug(medicinalproduct="ATORVASTATIN")
# Response: [{term: "alive", count: 113157}, {term: "death", count: 26909}]

# Get reporter country distribution
countries = tu.tools.FAERS_count_reportercountry_by_drug_event(medicinalproduct="ATORVASTATIN")
# Response: [{term: "US", count: 170963}, {term: "GB", count: 40079}, ...]
```

### 1.2 Get Serious Events Breakdown

```python
# Filter serious events - all types
serious_all = tu.tools.FAERS_filter_serious_events(
    operation="filter_serious_events",
    drug_name="ATORVASTATIN",
    seriousness_type="all"
)
# Response: {status: "success", drug_name: "ATORVASTATIN", seriousness_type: "all",
#   total_serious_events: N, top_serious_reactions: [{reaction: "...", count: N}, ...]}

# Death-related serious events
serious_death = tu.tools.FAERS_filter_serious_events(
    operation="filter_serious_events",
    drug_name="ATORVASTATIN",
    seriousness_type="death"
)
# Response: {status: "success", total_serious_events: 18720,
#   top_serious_reactions: [{reaction: "DEATH", count: 7541}, {reaction: "MYOCARDIAL INFARCTION", count: 1286}, ...]}

# Hospitalization-related
serious_hosp = tu.tools.FAERS_filter_serious_events(
    operation="filter_serious_events",
    drug_name="ATORVASTATIN",
    seriousness_type="hospitalization"
)

# Life-threatening
serious_lt = tu.tools.FAERS_filter_serious_events(
    operation="filter_serious_events",
    drug_name="ATORVASTATIN",
    seriousness_type="life_threatening"
)
```

### 1.3 MedDRA Hierarchy Rollup

```python
# Get MedDRA preferred term rollup (top 50)
meddra = tu.tools.FAERS_rollup_meddra_hierarchy(
    operation="rollup_meddra_hierarchy",
    drug_name="ATORVASTATIN"
)
# Response: {status: "success", drug_name: "ATORVASTATIN",
#   meddra_hierarchy: {PT_level: [{preferred_term: "FATIGUE", count: 13957}, ...]}}
```

### 1.4 Output for Report

```markdown
## 2. FAERS Adverse Event Profile

### 2.1 Overview
- **Total reports**: 326,261 (Serious: 242,757 | Non-serious: 83,504)
- **Fatal outcomes**: 22,128
- **Primary reporter countries**: US (170,963), GB (40,079), CA (16,492)

### 2.2 Top 10 Adverse Events by Frequency

| Rank | Adverse Event | Reports | % of Total |
|------|---------------|---------|------------|
| 1 | Fatigue | 19,171 | 5.9% |
| 2 | Diarrhoea | 17,127 | 5.2% |
| 3 | Dyspnoea | 15,992 | 4.9% |
| ... | ... | ... | ... |

### 2.3 Outcome Distribution

| Outcome | Count | Percentage |
|---------|-------|------------|
| Unknown | 162,310 | 39.6% |
| Recovered/resolved | 94,737 | 23.1% |
| Not recovered | 77,721 | 18.9% |
| Recovering | 49,367 | 12.0% |
| Fatal | 22,128 | 5.4% |
| Recovered with sequelae | 4,930 | 1.2% |

### 2.4 Age Distribution

| Age Group | Reports | Percentage |
|-----------|---------|------------|
| Elderly | 38,510 | 61.3% |
| Adult | 24,302 | 38.7% |
| Other | 152 | <1% |

*Source: FAERS via FAERS_count_reactions_by_drug_event, FAERS_count_seriousness_by_drug_event*
```

---

## Phase 2: Disproportionality Analysis (Signal Detection)

### 2.1 Calculate Signal Metrics

**CRITICAL**: This is the core of the skill. For each top adverse event (at least top 15-20), calculate PRR, ROR, and IC with 95% confidence intervals.

```python
# For each significant adverse event, calculate disproportionality
top_events = ["Rhabdomyolysis", "Myalgia", "Hepatotoxicity", "Diabetes mellitus",
              "Acute kidney injury", "Myopathy", "Pancreatitis"]

for event in top_events:
    result = tu.tools.FAERS_calculate_disproportionality(
        operation="calculate_disproportionality",
        drug_name="ATORVASTATIN",
        adverse_event=event
    )
    # Response structure:
    # {
    #   status: "success",
    #   drug_name: "ATORVASTATIN",
    #   adverse_event: "Rhabdomyolysis",
    #   contingency_table: {
    #     a_drug_and_event: 2226,
    #     b_drug_no_event: 241655,
    #     c_no_drug_event: 37658,
    #     d_no_drug_no_event: 19725450
    #   },
    #   metrics: {
    #     ROR: {value: 4.825, ci_95_lower: 4.622, ci_95_upper: 5.037},
    #     PRR: {value: 4.79, ci_95_lower: 4.59, ci_95_upper: 4.998},
    #     IC: {value: 2.194, ci_95_lower: 2.136, ci_95_upper: 2.252}
    #   },
    #   signal_detection: {
    #     signal_detected: true,
    #     signal_strength: "Strong signal",
    #     criteria: "ROR lower CI > 1.0 and case count >= 3"
    #   }
    # }
```

### 2.2 Signal Detection Criteria

**Proportional Reporting Ratio (PRR)**:
- PRR = (a/(a+b)) / (c/(c+d))
- Signal: PRR >= 2.0 AND lower 95% CI > 1.0 AND case count >= 3

**Reporting Odds Ratio (ROR)**:
- ROR = (a*d) / (b*c)
- Signal: Lower 95% CI > 1.0

**Information Component (IC)**:
- IC = log2(observed/expected)
- Signal: Lower 95% CI > 0

### 2.3 Signal Strength Classification

| Strength | PRR | ROR Lower CI | IC Lower CI | Clinical Action |
|----------|-----|-------------|-------------|-----------------|
| **Strong** | >= 5.0 | >= 3.0 | >= 2.0 | Immediate investigation required |
| **Moderate** | 3.0-4.9 | 2.0-2.9 | 1.0-1.9 | Active monitoring recommended |
| **Weak** | 2.0-2.9 | 1.0-1.9 | 0-0.9 | Routine monitoring, watch for trends |
| **No signal** | < 2.0 | < 1.0 | < 0 | Standard pharmacovigilance |

### 2.4 Demographic Stratification of Key Signals

```python
# For strong/moderate signals, stratify by demographics
result = tu.tools.FAERS_stratify_by_demographics(
    operation="stratify_by_demographics",
    drug_name="ATORVASTATIN",
    adverse_event="Rhabdomyolysis",
    stratify_by="sex"  # Options: sex, age, country
)
# Response: {status: "success", total_reports: 1996,
#   stratification: [{group: 1, count: 1190, percentage: 59.62},  # 1=Male
#                    {group: 2, count: 781, percentage: 39.13}]}    # 2=Female
```

**Note on sex codes**: group 0 = Unknown, group 1 = Male, group 2 = Female.

### 2.5 Output for Report

```markdown
## 3. Disproportionality Analysis (Signal Detection)

### 3.1 Signal Detection Summary

| Adverse Event | Cases (a) | PRR | PRR 95% CI | ROR | ROR 95% CI | IC | Signal |
|---------------|-----------|-----|------------|-----|------------|-----|--------|
| Rhabdomyolysis | 2,226 | 4.79 | 4.59-5.00 | 4.83 | 4.62-5.04 | 2.19 | **STRONG** |
| Myopathy | 1,234 | 6.12 | 5.72-6.55 | 6.18 | 5.77-6.62 | 2.54 | **STRONG** |
| Myalgia | 9,189 | 2.31 | 2.26-2.37 | 2.33 | 2.28-2.39 | 1.18 | Moderate |
| Hepatotoxicity | 456 | 3.45 | 3.10-3.84 | 3.48 | 3.13-3.87 | 1.72 | Moderate |
| Diabetes mellitus | 3,021 | 1.89 | 1.82-1.96 | 1.90 | 1.83-1.97 | 0.91 | Weak |
| Pancreatitis | 678 | 2.15 | 1.97-2.34 | 2.16 | 1.98-2.35 | 1.08 | Weak |

### 3.2 Demographics of Key Signals

**Rhabdomyolysis** (n=1,996):
- Male: 59.6%, Female: 39.1%, Unknown: 1.3%
- Predominantly elderly (>65 years)

*Source: FAERS via FAERS_calculate_disproportionality, FAERS_stratify_by_demographics*
```

---

## Phase 3: FDA Label Safety Information

### 3.1 Extract Label Sections

```python
# Boxed warnings
boxed = tu.tools.FDA_get_boxed_warning_info_by_drug_name(drug_name="atorvastatin")
# Response: {meta: {total: N}, results: [{boxed_warning: ["...text..."]}]}
# NOTE: Returns {error: {code: "NOT_FOUND"}} if no boxed warning exists

# Contraindications
contras = tu.tools.FDA_get_contraindications_by_drug_name(drug_name="atorvastatin")
# Response: {meta: {total: N}, results: [{openfda.generic_name: [...], contraindications: ["...text..."]}]}

# Warnings and precautions
warnings = tu.tools.FDA_get_warnings_by_drug_name(drug_name="atorvastatin")
# Response: {meta: {total: N}, results: [{warnings: ["...text..."], boxed_warning: [...]}]}

# Adverse reactions from label
adverse_rxns = tu.tools.FDA_get_adverse_reactions_by_drug_name(drug_name="atorvastatin")
# Response: {meta: {total: N}, results: [{adverse_reactions: ["...text..."]}]}

# Drug interactions from label
interactions = tu.tools.FDA_get_drug_interactions_by_drug_name(drug_name="atorvastatin")
# Response: {meta: {total: N}, results: [{drug_interactions: ["...text..."]}]}

# Pregnancy/breastfeeding
pregnancy = tu.tools.FDA_get_pregnancy_or_breastfeeding_info_by_drug_name(drug_name="atorvastatin")

# Geriatric use
geriatric = tu.tools.FDA_get_geriatric_use_info_by_drug_name(drug_name="atorvastatin")

# Pediatric use
pediatric = tu.tools.FDA_get_pediatric_use_info_by_drug_name(drug_name="atorvastatin")

# Pharmacogenomics from label
pgx_label = tu.tools.FDA_get_pharmacogenomics_info_by_drug_name(drug_name="atorvastatin")
```

### 3.2 Handling No Results

**IMPORTANT**: FDA label tools return `{error: {code: "NOT_FOUND"}}` when a section does not exist. This is NORMAL for many drugs - for example, most drugs do NOT have boxed warnings. Always check for this pattern:

```python
# Check if boxed warning exists
if isinstance(boxed, dict) and 'error' in boxed:
    boxed_warning_text = "None (no boxed warning for this drug)"
else:
    boxed_warning_text = boxed['results'][0].get('boxed_warning', ['None'])[0]
```

### 3.3 Output for Report

```markdown
## 4. FDA Label Safety Information

### 4.1 Boxed Warning
None

### 4.2 Contraindications
- Acute liver failure or decompensated cirrhosis
- Hypersensitivity to atorvastatin (includes anaphylaxis, angioedema, SJS, TEN)

### 4.3 Warnings and Precautions
| Warning | Clinical Relevance |
|---------|-------------------|
| Myopathy/Rhabdomyolysis | Risk with CYP3A4 inhibitors, high doses |
| Immune-Mediated Necrotizing Myopathy | Rare autoimmune myopathy |
| Hepatic Dysfunction | Monitor LFTs |
| Increased HbA1c/Glucose | Diabetes risk |

### 4.4 Drug Interactions (from label)
| Interacting Drug | Mechanism | Clinical Action |
|-----------------|-----------|-----------------|
| Cyclosporine | Increased exposure | Avoid combination |
| CYP3A4 inhibitors | Increased atorvastatin levels | Use lowest dose |
| Gemfibrozil | Increased myopathy risk | Avoid |

### 4.5 Special Populations
- **Pregnancy**: Contraindicated
- **Geriatric**: No dose adjustment needed
- **Pediatric**: Approved for heterozygous FH ages 10+

*Source: FDA drug labels via FDA_get_contraindications_by_drug_name, FDA_get_warnings_by_drug_name*
```

---

## Phase 4: Mechanism-Based Adverse Event Context

### 4.1 Target Safety Profile

```python
# Get target safety data from OpenTargets
# First get target ensembl ID from MOA result
target_id = "ENSG00000113161"  # HMGCR from Phase 0

safety = tu.tools.OpenTargets_get_target_safety_profile_by_ensemblID(ensemblId=target_id)
# Response: {data: {target: {id: "...", approvedSymbol: "HMGCR",
#   safetyLiabilities: [{event: "Decrease, Fertility", eventId: "...",
#     effects: [{direction: "Inhibition/Decrease/Downregulation"}],
#     studies: [{type: "cell-based"}], datasource: "AOP-Wiki"}]}}}

# Get OpenTargets adverse events (uses FAERS data)
ot_aes = tu.tools.OpenTargets_get_drug_adverse_events_by_chemblId(chemblId="CHEMBL1487")
# Response: {data: {drug: {adverseEvents: {count: 13, criticalValue: 513.67,
#   rows: [{name: "myalgia", meddraCode: "10028411", count: 4126, logLR: 6067.33}, ...]}}}}
```

### 4.2 ADMET Predictions (if SMILES available)

```python
# Get SMILES from DrugBank/PharmGKB
smiles = "CC(C)C1=C(C(=C(N1CC[C@H](C[C@H](CC(=O)O)O)O)C2=CC=C(C=C2)F)C3=CC=CC=C3)C(=O)NC4=CC=CC=C4"

# Toxicity predictions
toxicity = tu.tools.ADMETAI_predict_toxicity(smiles=[smiles])
# Response: predictions for hepatotoxicity, cardiotoxicity, etc.

# CYP interaction predictions
cyp = tu.tools.ADMETAI_predict_CYP_interactions(smiles=[smiles])
# Response: CYP inhibition/substrate predictions
```

### 4.3 Drug Warnings from OpenTargets

```python
# Drug warnings (withdrawals, safety warnings)
warnings = tu.tools.OpenTargets_get_drug_warnings_by_chemblId(chemblId="CHEMBL1487")
# Response: {data: {drug: {id: "CHEMBL1487", name: "ATORVASTATIN"}}}
# Note: Empty if no warnings exist
```

### 4.4 Output for Report

```markdown
## 5. Mechanism-Based Adverse Event Context

### 5.1 Target Safety Profile (HMGCR)
| Safety Liability | Direction | Evidence | Source |
|-----------------|-----------|----------|--------|
| Decreased fertility | Inhibition | Cell-based | AOP-Wiki |

### 5.2 OpenTargets Significant Adverse Events
| Adverse Event | FAERS Count | log(LR) | MedDRA Code |
|---------------|-------------|---------|-------------|
| Myalgia | 4,126 | 6,067 | 10028411 |
| Rhabdomyolysis | 2,546 | 4,788 | 10039020 |
| CPK increased | 1,709 | 2,909 | 10005470 |

### 5.3 ADMET Predictions
| Property | Prediction | Confidence |
|----------|-----------|------------|
| Hepatotoxicity | Moderate risk | 0.65 |
| Cardiotoxicity (hERG) | Low risk | 0.23 |
| CYP3A4 substrate | Yes | 0.92 |

*Source: OpenTargets, ADMETAI*
```

---

## Phase 5: Comparative Safety Analysis

### 5.1 Compare to Drug Class

```python
# Head-to-head comparison with class member
comparison = tu.tools.FAERS_compare_drugs(
    operation="compare_drugs",
    drug1="ATORVASTATIN",
    drug2="SIMVASTATIN",
    adverse_event="Rhabdomyolysis"
)
# Response: {status: "success", adverse_event: "Rhabdomyolysis",
#   drug1: {name: "ATORVASTATIN", metrics: {PRR: {value: 4.79, ...}, ROR: {...}, IC: {...}},
#           signal_detection: {signal_detected: true, signal_strength: "Strong signal"}},
#   drug2: {name: "SIMVASTATIN", metrics: {PRR: {value: 12.78, ...}, ...}},
#   comparison: "SIMVASTATIN shows stronger signal than ATORVASTATIN"}

# Compare multiple events across class members
class_drugs = ["ATORVASTATIN", "SIMVASTATIN", "ROSUVASTATIN", "PRAVASTATIN"]
key_events = ["Rhabdomyolysis", "Myalgia", "Hepatotoxicity", "Diabetes mellitus"]
# Run FAERS_compare_drugs for each pair and event combination

# Aggregate adverse events across drug class
class_aes = tu.tools.FAERS_count_additive_adverse_reactions(
    medicinalproducts=class_drugs
)
# Response: [{term: "FATIGUE", count: N}, ...]

# Aggregate seriousness across class
class_serious = tu.tools.FAERS_count_additive_seriousness_classification(
    medicinalproducts=class_drugs
)
# Response: [{term: "Serious", count: N}, {term: "Non-serious", count: N}]
```

### 5.2 Output for Report

```markdown
## 6. Comparative Safety Analysis (Statin Class)

### 6.1 Head-to-Head: Rhabdomyolysis

| Drug | PRR | PRR 95% CI | ROR | Cases | Signal |
|------|-----|------------|-----|-------|--------|
| Simvastatin | 12.78 | 12.43-13.14 | 13.05 | 5,234 | **STRONG** |
| Atorvastatin | 4.79 | 4.59-5.00 | 4.83 | 2,226 | **STRONG** |
| Rosuvastatin | 3.45 | 3.21-3.71 | 3.47 | 1,102 | Moderate |
| Pravastatin | 5.67 | 5.28-6.09 | 5.72 | 1,876 | **STRONG** |

### 6.2 Class-Wide vs Drug-Specific Signals

| Signal Type | Events |
|-------------|--------|
| **Class-wide** (all statins) | Myalgia, Rhabdomyolysis, CPK elevation, Hepatotoxicity |
| **Drug-specific** (atorvastatin) | [None identified - all signals are class-wide] |

*Source: FAERS via FAERS_compare_drugs*
```

---

## Phase 6: Drug-Drug Interactions & Risk Factors

### 6.1 Drug-Drug Interactions

```python
# FDA label DDIs
ddi_label = tu.tools.FDA_get_drug_interactions_by_drug_name(drug_name="atorvastatin")
# Response: {results: [{drug_interactions: ["...text..."]}]}

# DrugBank interactions
ddi_db = tu.tools.drugbank_get_drug_interactions_by_drug_name_or_id(
    query="atorvastatin", case_sensitive=False, exact_match=False, limit=3
)

# DailyMed DDIs
ddi_dailymed = tu.tools.DailyMed_parse_drug_interactions(drug_name="atorvastatin")
```

### 6.2 Pharmacogenomic Risk Factors

```python
# PharmGKB drug search
pgx_search = tu.tools.PharmGKB_search_drugs(query="atorvastatin")
# Response: {status: "success", data: [{id: "PA448500", name: "atorvastatin", smiles: "..."}]}

# Get detailed PGx info
pgx_details = tu.tools.PharmGKB_get_drug_details(drug_id="PA448500")

# PharmGKB dosing guidelines
dosing = tu.tools.PharmGKB_get_dosing_guidelines(gene="SLCO1B1")
# SLCO1B1 is key pharmacogene for statins

# FDA PGx biomarkers
fda_pgx = tu.tools.fda_pharmacogenomic_biomarkers(drug_name="atorvastatin", limit=10)
# Response: {count: N, results: [{drug_name: "...", biomarker: "...", ...}]}
# Note: May return empty results for some drugs
```

### 6.3 Output for Report

```markdown
## 7. Drug-Drug Interactions & Pharmacogenomic Risk

### 7.1 Key Drug-Drug Interactions
| Interacting Drug | Mechanism | Risk | Management |
|-----------------|-----------|------|------------|
| Cyclosporine | CYP3A4 inhibition | Rhabdomyolysis | Avoid combination |
| Clarithromycin | CYP3A4 inhibition | Myopathy | Limit to 20mg/day |
| Gemfibrozil | Glucuronidation inhibition | Myopathy | Avoid combination |
| Niacin (>1g/day) | Additive myotoxicity | Myopathy | Monitor closely |

### 7.2 Pharmacogenomic Risk Factors
| Gene | Variant | Phenotype | Recommendation | Evidence |
|------|---------|-----------|----------------|----------|
| SLCO1B1 | rs4149056 (*5) | Reduced transport | Consider lower dose | Level 1A |
| CYP3A4 | *22 (rs35599367) | Poor metabolizer | Increased exposure | Level 3 |

*Source: FDA label, PharmGKB, fda_pharmacogenomic_biomarkers*
```

---

## Phase 7: Literature Evidence

### 7.1 Search Published Literature

```python
# PubMed safety studies
pubmed = tu.tools.PubMed_search_articles(
    query='atorvastatin adverse events safety rhabdomyolysis',
    limit=20
)
# Response: [{pmid: "...", title: "...", authors: [...], journal: "...",
#   pub_date: "...", pub_year: "...", doi: "..."}]

# Citation analysis via OpenAlex
openalex = tu.tools.openalex_search_works(
    query="atorvastatin safety adverse events",
    limit=15
)

# Preprints via EuropePMC
preprints = tu.tools.EuropePMC_search_articles(
    query="atorvastatin safety signal",
    source="PPR",
    pageSize=10
)
```

### 7.2 Output for Report

```markdown
## 8. Literature Evidence

### 8.1 Key Safety Publications
| PMID | Title | Year | Journal |
|------|-------|------|---------|
| 41657777 | Differential musculoskeletal outcome reporting... | 2026 | Front Pharmacol |
| ... | ... | ... | ... |

### 8.2 Evidence Summary
| Evidence Type | Count | Key Findings |
|---------------|-------|--------------|
| Meta-analyses | 5 | Statin myopathy 5-10%, rhabdomyolysis rare |
| RCTs | 12 | CV benefit outweighs muscle risk |
| Case reports | 23 | Severe rhabdomyolysis with CYP3A4 inhibitors |

*Source: PubMed, OpenAlex*
```

---

## Phase 8: Risk Assessment & Safety Signal Score

### 8.1 Safety Signal Score Calculation (0-100)

The Safety Signal Score quantifies overall drug safety concern on a 0-100 scale (higher = more concern).

**Component 1: FAERS Signal Strength (0-35 points)**
```
If any signal has PRR >= 5 AND ROR lower CI >= 3: 35 points
If any signal has PRR 3-5 AND ROR lower CI 2-3: 20 points
If any signal has PRR 2-3 AND ROR lower CI 1-2: 10 points
If no signals detected: 0 points
```

**Component 2: Serious Adverse Events (0-30 points)**
```
Deaths reported with high count (>100): 30 points
Deaths reported with low count (1-100): 25 points
Life-threatening events: 20 points
Hospitalizations only: 15 points
Non-serious only: 0 points
```

**Component 3: FDA Label Warnings (0-25 points)**
```
Boxed warning present: 25 points
Drug withdrawn or restricted: 25 points
Contraindications present: 15 points
Warnings and precautions: 10 points
Adverse reactions only: 5 points
No label warnings: 0 points
```

**Component 4: Literature Evidence (0-10 points)**
```
Meta-analyses confirming safety signals: 10 points
Multiple RCTs with safety concerns: 7 points
Case reports/case series: 4 points
No published safety concerns: 0 points
```

**Total Score Interpretation:**
| Score Range | Interpretation | Action |
|-------------|---------------|--------|
| **75-100** | High concern | Serious safety signals; requires immediate regulatory attention |
| **50-74** | Moderate concern | Significant monitoring needed; consider risk mitigation |
| **25-49** | Low-moderate concern | Routine enhanced monitoring; standard risk management |
| **0-24** | Low concern | Standard safety profile; routine pharmacovigilance |

### 8.2 Evidence Grading

| Tier | Criteria | Example |
|------|----------|---------|
| **T1** | Boxed warning, confirmed by RCTs, PRR > 10 | Metformin: Lactic acidosis |
| **T2** | Label warning + FAERS signal (PRR 3-10) + published studies | Atorvastatin: Rhabdomyolysis |
| **T3** | FAERS signal (PRR 2-3) + case reports | Atorvastatin: Pancreatitis |
| **T4** | Computational prediction only (ADMET) or weak signal | ADMETAI hepatotoxicity prediction |

### 8.3 Output for Report

```markdown
## 9. Risk Assessment

### 9.1 Safety Signal Score: 62/100 (MODERATE CONCERN)

| Component | Score | Max | Rationale |
|-----------|-------|-----|-----------|
| FAERS Signal Strength | 35 | 35 | Strong signals (PRR >= 5 for rhabdomyolysis) |
| Serious Adverse Events | 15 | 30 | Hospitalizations; deaths uncommon for drug itself |
| FDA Label Warnings | 10 | 25 | Warnings/precautions but no boxed warning |
| Literature Evidence | 7 | 10 | Multiple RCTs confirm muscle-related risks |
| **TOTAL** | **62** | **100** | **MODERATE CONCERN** |

### 9.2 Evidence-Graded Signals

| Signal | Grade | PRR | Serious | Label | Literature | Overall |
|--------|-------|-----|---------|-------|------------|---------|
| Rhabdomyolysis | T2 | 4.79 | Yes | Warning | Confirmed | Moderate |
| Myopathy | T2 | 6.12 | Yes | Warning | Confirmed | Moderate |
| Hepatotoxicity | T3 | 3.45 | Rare | Warning | Case reports | Low-Moderate |
| Diabetes risk | T3 | 1.89 | No | Warning | RCT data | Low |
```

---

## Phase 9: Report Synthesis & Recommendations

### 9.1 Report Template

**File**: `[DRUG]_adverse_event_report.md`

```markdown
# Adverse Drug Event Signal Detection Report: [DRUG]

**Generated**: [Date] | **Drug**: [Generic Name] | **ChEMBL ID**: [ID]
**Safety Signal Score**: [XX/100] ([INTERPRETATION])

---

## Executive Summary

[2-3 paragraph summary of key findings]

**Key Safety Signals**:
1. [Strongest signal with PRR/ROR]
2. [Second signal]
3. [Third signal]

**Regulatory Status**: [Boxed warning Y/N] | [Withdrawn Y/N] | [Restrictions]

---

## 1. Drug Identification
[Phase 0 output]

## 2. FAERS Adverse Event Profile
[Phase 1 output]

## 3. Disproportionality Analysis
[Phase 2 output]

## 4. FDA Label Safety Information
[Phase 3 output]

## 5. Mechanism-Based Context
[Phase 4 output]

## 6. Comparative Safety Analysis
[Phase 5 output]

## 7. Drug-Drug Interactions & PGx Risk
[Phase 6 output]

## 8. Literature Evidence
[Phase 7 output]

## 9. Risk Assessment
[Phase 8 output]

## 10. Clinical Recommendations

### 10.1 Monitoring Recommendations
| Parameter | Frequency | Rationale |
|-----------|-----------|-----------|
| [Lab test] | [Frequency] | [Why] |

### 10.2 Risk Mitigation Strategies
| Risk | Mitigation | Evidence |
|------|-----------|----------|
| [Risk] | [Strategy] | [Source] |

### 10.3 Patient Counseling Points
- [Point 1]
- [Point 2]

### 10.4 Populations at Higher Risk
| Population | Risk Factor | Recommendation |
|-----------|-------------|----------------|
| [Group] | [Factor] | [Action] |

---

## 11. Completeness Checklist
[See below]

## 12. Data Sources
[All tools and databases used with timestamps]
```

---

## Completeness Checklist

### Phase 0: Drug Disambiguation
- [ ] Generic name resolved
- [ ] ChEMBL ID obtained
- [ ] DrugBank ID obtained
- [ ] Drug class identified
- [ ] Mechanism of action stated
- [ ] Primary target identified
- [ ] Blackbox/withdrawal status checked

### Phase 1: FAERS Profiling
- [ ] Top adverse events queried (>=15 events)
- [ ] Seriousness distribution obtained
- [ ] Outcome distribution obtained
- [ ] Age distribution obtained
- [ ] Death-related events counted
- [ ] Reporter country distribution obtained

### Phase 2: Disproportionality Analysis
- [ ] PRR calculated for >= 10 adverse events
- [ ] ROR with 95% CI for each event
- [ ] IC with 95% CI for each event
- [ ] Signal strength classified for each
- [ ] Demographics stratified for strong signals

### Phase 3: FDA Label
- [ ] Boxed warnings checked (or confirmed none)
- [ ] Contraindications extracted
- [ ] Warnings and precautions extracted
- [ ] Adverse reactions from label
- [ ] Drug interactions from label
- [ ] Special populations (pregnancy, geriatric, pediatric)

### Phase 4: Mechanism Context
- [ ] Target safety profile (OpenTargets)
- [ ] OpenTargets adverse events queried
- [ ] ADMET predictions (if SMILES available)

### Phase 5: Comparative Analysis
- [ ] At least 1 class comparison performed
- [ ] Class-wide vs drug-specific signals identified
- [ ] Aggregate class AEs computed (if applicable)

### Phase 6: DDIs & PGx
- [ ] DDIs from FDA label extracted
- [ ] PharmGKB queried
- [ ] Dosing guidelines checked
- [ ] FDA PGx biomarkers checked

### Phase 7: Literature
- [ ] PubMed searched (>=10 articles)
- [ ] OpenAlex citation analysis (if time permits)
- [ ] Key safety publications cited

### Phase 8: Risk Assessment
- [ ] Safety Signal Score calculated (0-100)
- [ ] Each signal evidence-graded (T1-T4)
- [ ] Score interpretation provided

### Phase 9: Report
- [ ] Report file created and saved
- [ ] Executive summary written
- [ ] Monitoring recommendations provided
- [ ] Risk mitigation strategies listed
- [ ] Patient counseling points included
- [ ] All sources cited

---

## Tool Parameter Reference (Verified)

### FAERS Tools (OpenFDA-based)

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `FAERS_count_reactions_by_drug_event` | `medicinalproduct` (REQUIRED), `patientsex`, `patientagegroup`, `occurcountry` | Returns [{term, count}] |
| `FAERS_count_seriousness_by_drug_event` | `medicinalproduct` (REQUIRED), `patientsex`, `patientagegroup`, `occurcountry` | Returns [{term: "Serious"/"Non-serious", count}] |
| `FAERS_count_outcomes_by_drug_event` | `medicinalproduct` (REQUIRED), `patientsex`, `patientagegroup`, `occurcountry` | Returns [{term: "Fatal"/"Recovered"/..., count}] |
| `FAERS_count_patient_age_distribution` | `medicinalproduct` (REQUIRED) | Returns [{term: "Elderly"/"Adult"/..., count}] |
| `FAERS_count_death_related_by_drug` | `medicinalproduct` (REQUIRED) | Returns [{term: "alive"/"death", count}] |
| `FAERS_count_reportercountry_by_drug_event` | `medicinalproduct` (REQUIRED), `patientsex`, `patientagegroup`, `serious` | Returns [{term: "US"/"GB"/..., count}] |
| `FAERS_search_adverse_event_reports` | `medicinalproduct`, `limit` (max 100), `skip` | Returns individual case reports with patient/drug/reaction data |
| `FAERS_search_reports_by_drug_and_reaction` | `medicinalproduct` (REQUIRED), `reactionmeddrapt` (REQUIRED), `limit`, `skip`, `patientsex`, `serious` | Returns individual reports filtered by specific reaction |
| `FAERS_search_serious_reports_by_drug` | `medicinalproduct` (REQUIRED), `seriousnessdeath`, `seriousnesshospitalization`, `seriousnesslifethreatening`, `seriousnessdisabling`, `limit` | Returns serious event reports |

### FAERS Analytics Tools (operation-based)

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `FAERS_calculate_disproportionality` | `operation`="calculate_disproportionality", `drug_name` (REQUIRED), `adverse_event` (REQUIRED) | Returns PRR, ROR, IC with 95% CI and signal detection |
| `FAERS_analyze_temporal_trends` | `operation`="analyze_temporal_trends", `drug_name` (REQUIRED), `adverse_event` (optional) | Returns yearly counts and trend direction |
| `FAERS_compare_drugs` | `operation`="compare_drugs", `drug1` (REQUIRED), `drug2` (REQUIRED), `adverse_event` (REQUIRED) | Returns PRR/ROR/IC for both drugs side-by-side |
| `FAERS_filter_serious_events` | `operation`="filter_serious_events", `drug_name` (REQUIRED), `seriousness_type` (death/hospitalization/disability/life_threatening/all) | Returns top serious reactions with counts |
| `FAERS_stratify_by_demographics` | `operation`="stratify_by_demographics", `drug_name` (REQUIRED), `adverse_event` (REQUIRED), `stratify_by` (sex/age/country) | Returns stratified counts and percentages. Sex codes: 0=Unknown, 1=Male, 2=Female |
| `FAERS_rollup_meddra_hierarchy` | `operation`="rollup_meddra_hierarchy", `drug_name` (REQUIRED) | Returns top 50 preferred terms with counts |

### FAERS Aggregate Tools (multi-drug)

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `FAERS_count_additive_adverse_reactions` | `medicinalproducts` (REQUIRED, array), `patientsex`, `patientagegroup`, `occurcountry`, `serious`, `seriousnessdeath` | Aggregates AE counts across multiple drugs |
| `FAERS_count_additive_seriousness_classification` | `medicinalproducts` (REQUIRED, array), `patientsex`, `patientagegroup`, `occurcountry` | Aggregates seriousness across multiple drugs |
| `FAERS_count_additive_reaction_outcomes` | `medicinalproducts` (REQUIRED, array) | Aggregates outcomes across multiple drugs |

### FDA Label Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `FDA_get_boxed_warning_info_by_drug_name` | `drug_name` | Returns `{error: {code: "NOT_FOUND"}}` if no boxed warning |
| `FDA_get_contraindications_by_drug_name` | `drug_name` | Returns `{meta: {total: N}, results: [{contraindications: [...]}]}` |
| `FDA_get_adverse_reactions_by_drug_name` | `drug_name` | Returns `{meta: {total: N}, results: [{adverse_reactions: [...]}]}` |
| `FDA_get_warnings_by_drug_name` | `drug_name` | Returns `{meta: {total: N}, results: [{warnings: [...]}]}` |
| `FDA_get_drug_interactions_by_drug_name` | `drug_name` | Returns `{meta: {total: N}, results: [{drug_interactions: [...]}]}` |
| `FDA_get_pharmacogenomics_info_by_drug_name` | `drug_name` | Returns PGx info from label |
| `FDA_get_pregnancy_or_breastfeeding_info_by_drug_name` | `drug_name` | Returns pregnancy info |
| `FDA_get_geriatric_use_info_by_drug_name` | `drug_name` | Returns geriatric use info |
| `FDA_get_pediatric_use_info_by_drug_name` | `drug_name` | Returns pediatric info |

### OpenTargets Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `OpenTargets_get_drug_chembId_by_generic_name` | `drugName` | Returns `{data: {search: {hits: [{id, name, description}]}}}` |
| `OpenTargets_get_drug_adverse_events_by_chemblId` | `chemblId` | Returns `{data: {drug: {adverseEvents: {count, rows: [{name, meddraCode, count, logLR}]}}}}` |
| `OpenTargets_get_drug_blackbox_status_by_chembl_ID` | `chemblId` | Returns `{data: {drug: {hasBeenWithdrawn, blackBoxWarning}}}` |
| `OpenTargets_get_drug_warnings_by_chemblId` | `chemblId` | Returns drug warnings (may be empty) |
| `OpenTargets_get_drug_mechanisms_of_action_by_chemblId` | `chemblId` | Returns `{data: {drug: {mechanismsOfAction: {rows: [{mechanismOfAction, actionType, targetName, targets}]}}}}` |
| `OpenTargets_get_drug_indications_by_chemblId` | `chemblId` | Returns approved and investigational indications |
| `OpenTargets_get_target_safety_profile_by_ensemblID` | `ensemblId` | Returns `{data: {target: {safetyLiabilities: [{event, effects, studies, datasource}]}}}` |

### DrugBank Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `drugbank_get_safety_by_drug_name_or_drugbank_id` | `query`, `case_sensitive` (bool), `exact_match` (bool), `limit` | Returns toxicity, food interactions |
| `drugbank_get_targets_by_drug_name_or_drugbank_id` | `query`, `case_sensitive`, `exact_match`, `limit` | Returns drug targets |
| `drugbank_get_drug_interactions_by_drug_name_or_id` | `query`, `case_sensitive`, `exact_match`, `limit` | Returns DDIs |
| `drugbank_get_pharmacology_by_drug_name_or_drugbank_id` | `query`, `case_sensitive`, `exact_match`, `limit` | Returns pharmacology |

### PharmGKB Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `PharmGKB_search_drugs` | `query` | Returns `{data: [{id, name, smiles}]}` |
| `PharmGKB_get_drug_details` | `drug_id` (e.g., "PA448500") | Returns detailed drug info |
| `PharmGKB_get_dosing_guidelines` | `guideline_id`, `gene` (both optional) | Returns dosing guidelines |
| `PharmGKB_get_clinical_annotations` | `annotation_id`, `gene_id` (both optional) | Returns clinical annotations |
| `fda_pharmacogenomic_biomarkers` | `drug_name`, `biomarker`, `limit` | Returns `{count, results: [...]}` |

### ADMETAI Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `ADMETAI_predict_toxicity` | `smiles` (REQUIRED, array of strings) | Predicts hepatotoxicity, cardiotoxicity, etc. |
| `ADMETAI_predict_CYP_interactions` | `smiles` (REQUIRED, array) | Predicts CYP inhibition/substrate |

### Literature Tools

| Tool | Key Parameters | Notes |
|------|---------------|-------|
| `PubMed_search_articles` | `query`, `limit` | Returns list of article dicts |
| `openalex_search_works` | `query`, `limit` | Returns works with citation counts |
| `EuropePMC_search_articles` | `query`, `source` ("PPR" for preprints), `pageSize` | Returns articles including preprints |
| `search_clinical_trials` | `query_term` (REQUIRED), `condition`, `intervention`, `pageSize` | Returns clinical trials |

---

## Fallback Chains

| Primary Tool | Fallback 1 | Fallback 2 |
|--------------|------------|------------|
| `FAERS_calculate_disproportionality` | Manual calculation from `FAERS_count_*` data | Literature PRR values |
| `FAERS_count_reactions_by_drug_event` | `FAERS_rollup_meddra_hierarchy` | OpenTargets adverse events |
| `FDA_get_boxed_warning_info_by_drug_name` | `OpenTargets_get_drug_blackbox_status_by_chembl_ID` | DrugBank safety |
| `FDA_get_contraindications_by_drug_name` | `FDA_get_warnings_by_drug_name` | DrugBank safety |
| `OpenTargets_get_drug_chembId_by_generic_name` | `ChEMBL_search_drugs` | Manual search |
| `PharmGKB_search_drugs` | `fda_pharmacogenomic_biomarkers` | FDA label PGx section |
| `PubMed_search_articles` | `openalex_search_works` | `EuropePMC_search_articles` |

---

## Common Patterns

### Pattern 1: Full Safety Signal Profile for a Single Drug
Use all phases (0-9) for comprehensive report. Best for regulatory submissions, safety reviews.

### Pattern 2: Specific Adverse Event Investigation
Focus on Phases 0, 2, 3, 7. User asks "Does [drug] cause [event]?" - calculate disproportionality for that specific event, check label, search literature.

### Pattern 3: Drug Class Comparison
Focus on Phases 0, 2, 5. Compare 3-5 drugs in same class for a specific adverse event using `FAERS_compare_drugs`.

### Pattern 4: Emerging Signal Detection
Focus on Phases 1, 2, 7. Screen top 20+ FAERS events for signals, identify any not in FDA label (Phase 3), search recent literature for confirmation.

### Pattern 5: Pharmacogenomic Risk Assessment
Focus on Phases 0, 6. Identify genetic risk factors for adverse events using PharmGKB and FDA PGx biomarkers.

### Pattern 6: Pre-Approval Safety Assessment
Focus on Phases 4, 7. Use ADMET predictions and target safety profiles when FAERS data is limited (new drugs).

---

## Edge Cases

### Drug with No FAERS Reports
- Skip Phases 1-2
- Rely on FDA label (Phase 3), mechanism predictions (Phase 4), and literature (Phase 7)
- Safety Signal Score will be lower due to lack of signal detection data

### Generic vs Brand Name
- Always try both names in FAERS queries (FAERS uses brand names sometimes)
- Use `OpenTargets_get_drug_chembId_by_generic_name` to resolve to standard identifier
- Use `FDA_get_brand_name_generic_name` for name cross-reference

### Drug Combinations
- Use `FAERS_search_reports_by_drug_combination` for polypharmacy analysis
- Distinguish combination AEs from individual drug AEs
- Use `FAERS_count_additive_adverse_reactions` for aggregate class analysis

### Confounding by Indication
- Compare AE profile to the disease being treated
- Example: "Death" reports for chemotherapy drugs may reflect disease progression
- Always note this limitation in the report

### Drugs with Boxed Warnings
- Score component automatically 25/25 for label warnings
- Prioritize boxed warning events in disproportionality analysis
- Cross-reference boxed warning with FAERS signal strength