Detect and analyze adverse drug event signals using FDA FAERS data, drug labels, disproportionality analysis (PRR, ROR, IC), and biomedical evidence. Generates quantitative safety signal scores (0-100) with evidence grading. Use for post-market surveillance, pharmacovigilance, drug safety assessment, adverse event investigation, and regulatory decision support.
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:
Apply when user asks:
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.
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
# 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}]}}}}
## 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*
# 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}, ...]
# 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"
)
# 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}, ...]}}
## 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*
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.
# 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"
# }
# }
Proportional Reporting Ratio (PRR):
Reporting Odds Ratio (ROR):
Information Component (IC):
| 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 |
# 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.
## 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*
# 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")
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:
# Check if boxed warning exists
if isinstance(boxed, dict) and 'error' in boxed:
boxed_warning_text = "None (no boxed warning for this drug)"