tooluniverse-clinical-data-integration

What this skill does

# Clinical Data Integration for Drug Safety

End-to-end drug safety review pipeline that integrates FDA label information, FAERS spontaneous reports, disproportionality signal detection, pharmacogenomic biomarkers, clinical trial data, and published literature. Designed for regulatory assessments, pharmacovigilance, and clinical decision support.

**Guiding principles**:
1. **Label is ground truth** -- FDA-approved labeling is the authoritative starting point for known safety information
2. **Signals need context** -- a FAERS signal without label or literature corroboration is hypothesis-generating, not confirmatory
3. **Disproportionality is not causation** -- PRR/ROR measure reporting patterns, not causal relationships
4. **Pharmacogenomics narrows risk** -- PGx biomarkers can identify which patients face elevated risk
5. **Progressive reporting** -- create the report file early; update section by section
6. **English-first queries** -- use English drug names in all tool calls; respond in the user's language

Clinical data integration starts with data harmonization. Different hospitals code the same diagnosis differently (ICD-10 vs SNOMED). Before merging datasets, verify the coding system. Missing data is informative — a missing lab value may mean the test wasn't ordered (patient was stable) not that the result was normal.

## LOOK UP, DON'T GUESS
When uncertain about any scientific fact, SEARCH databases first rather than reasoning from memory. A database-verified answer is always more reliable than a guess.

**Differentiation**: This skill emphasizes *regulatory-grade data integration* across the full drug lifecycle. For focused FAERS signal detection with quantitative scoring, see `tooluniverse-adverse-event-detection`. For general pharmacovigilance workflows, see `tooluniverse-pharmacovigilance`.

---

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

## When to Use

Typical triggers:
- "Give me a full safety review for [drug]"
- "What does the FDA label say about [drug] and [event]?"
- "Are there FAERS signals for [drug]?"
- "What pharmacogenomic biomarkers exist for [drug]?"
- "Find clinical trials studying [drug] safety"
- "Post-market surveillance summary for [drug]"
- "Compare safety profiles of [drug A] and [drug B]"

---

## Core Data Sources

| Source | Type | Best For |
|--------|------|----------|
| **FDA Labels (DailyMed)** | Regulatory | Approved safety information, boxed warnings, drug interactions |
| **FAERS** | Spontaneous reports | Post-market adverse event signals, demographic patterns |
| **CPIC** | Guidelines | Pharmacogenomic dosing recommendations |
| **FDA PGx Biomarkers** | Regulatory | Approved pharmacogenomic labeling |
| **ClinicalTrials.gov** | Trial registry | Ongoing/completed safety trials |
| **PubMed** | Literature | Published safety studies, case reports |

---

## Workflow Overview

```
Phase 0: Drug Identity & Context
  Resolve drug name, get class, mechanism, indications
    |
Phase 1: FDA Label Extraction
  Boxed warnings, contraindications, adverse reactions, interactions
    |
Phase 2: FAERS Signal Detection
  Top adverse events, disproportionality (PRR/ROR), demographics
    |
Phase 3: Pharmacogenomics
  CPIC guidelines, FDA PGx biomarkers, genotype-specific risks
    |
Phase 4: Clinical Trials
  Safety-focused trials, risk evaluation programs
    |
Phase 5: Literature Evidence
  PubMed safety studies, case reports, meta-analyses
    |
Phase 6: Integrated Safety Report
  Synthesize all sources into a cohesive safety profile
```

---

## Phase Details

### Phase 0: Drug Identity & Context

**Objective**: Unambiguously identify the drug and establish baseline context.

**Tools**:
- `DailyMed_search_spls` -- search Structured Product Labels
  - Input: `query` (drug name)
  - Output: SPL list with set IDs, titles, labeler names
- `OpenFDA_get_approval_history` -- get approval dates and supplements
  - Input: `drug_name` (generic or brand name)
  - Output: approval dates, application numbers, supplement history

**Workflow**:
1. Search DailyMed to confirm the drug name and identify the correct SPL
2. Get approval history to establish how long the drug has been marketed
3. Note the therapeutic class, mechanism of action, and approved indications
4. Record brand names vs generic name for consistent FAERS queries

**Tip**: FAERS uses `medicinalproduct` which can be brand or generic. Try both forms in Phase 2.

### Phase 1: FDA Label Extraction

**Objective**: Extract all safety-relevant sections from the FDA-approved label.

**Tools**:
- `FDA_get_boxed_warning_info_by_drug_name` -- boxed (black box) warnings
  - Input: `drug_name`
  - Output: warning text, or `{error: {code: "NOT_FOUND"}}` if none exists (normal)
- `FDA_get_warnings_and_cautions_by_drug_name` -- warnings and precautions section
  - Input: `drug_name`
  - Output: full warnings text
- `DailyMed_parse_adverse_reactions` -- adverse reactions from label
  - Input: `setid` (NOT `set_id`; from Phase 0 DailyMed search)
  - Output: parsed adverse reaction tables and text
- `DailyMed_parse_drug_interactions` -- drug interaction section
  - Input: `setid` (NOT `set_id`)
  - Output: parsed interaction data

**Workflow**:
1. Check for boxed warnings first -- these represent the most serious safety concerns
2. Extract warnings and precautions
3. Parse adverse reactions (both clinical trial rates and post-marketing reports)
4. Extract drug interactions
5. A `NOT_FOUND` response for boxed warnings is normal and means no boxed warning exists

**Label section priority**: Boxed Warning > Contraindications > Warnings/Precautions > Adverse Reactions > Drug Interactions

### Phase 2: FAERS Signal Detection

**Objective**: Identify post-market safety signals from spontaneous reports.

**Tools**:
- `FAERS_count_reactions_by_drug_event` -- top adverse events by frequency
  - Input: `medicinalproduct` (drug name, NOT `drug_name`)
  - Output: `[{term, count}]`
- `FAERS_calculate_disproportionality` -- PRR, ROR, IC for drug-event pair
  - Input: `drug_name`, `adverse_event`
  - Output: `{metrics: {PRR: {value, ci_95_lower, ci_95_upper}, ROR: {...}, IC: {...}}, signal_detection: {signal_detected, signal_strength}}`
- `FAERS_filter_serious_events` -- filter by seriousness type
  - Input: `drug_name`, `seriousness_type` (all/death/hospitalization/disability/life_threatening)
  - Output: serious event breakdown
- `FAERS_stratify_by_demographics` -- age/sex/country stratification
  - Input: `drug_name`, `adverse_event` (optional), `stratify_by` (sex/age/country)
  - Output: demographic breakdown (sex codes: 0=Unknown, 1=Male, 2=Female)

**Workflow**:
1. Get top 20 adverse events by report count
2. For the top 10-15, calculate disproportionality (PRR, ROR, IC with 95% CI)
3. Signal criteria: PRR >= 2.0, lower CI > 1.0, N >= 3 reports
4. For detected signals, filter by seriousness (deaths, hospitalizations)
5. Stratify strong signals by demographics to identify at-risk populations

**Important notes**:
- `FAERS_count_reactions_by_drug_event` uses `medicinalproduct` param, not `drug_name`
- `FAERS_calculate_disproportionality` uses `drug_name` param
- MedDRA term levels differ between count and disproportionality tools; case counts may not match exactly

**FAERS signal interpretation** — what the numbers mean:

| Metric | Value | Interpretation |
|--------|-------|---------------|
| **PRR** (Proportional Reporting Ratio) | < 1.0 | Event reported LESS than expected (possible protective effect or underreporting) |
| | 1.0-2.0 | No signal or weak signal |
| | 2.0-5.0 | **Moderate signal** — warrants investigation |
| | > 5.0 | **Strong signal** — likely real association (but still not proof of causatio