Faers Analytics Tools#

Configuration File: faers_analytics_tools.json Tool Type: Local Tools Count: 6

This page contains all tools defined in the faers_analytics_tools.json configuration file.

Available Tools#

FAERS_calculate_disproportionality (Type: FAERSAnalyticsTool)#

Calculate statistical disproportionality measures (ROR, PRR, IC) with 95% CI for drug-event pairs…

FAERS_calculate_disproportionality tool specification

Tool Information:

  • Name: FAERS_calculate_disproportionality

  • Type: FAERSAnalyticsTool

  • Description: Calculate statistical disproportionality measures (ROR, PRR, IC) with 95% CI for drug-event pairs. Returns signal strength classification. Example: drug=’ibuprofen’, event=’hepatotoxicity’ → ROR=2.3 [1.8-2.9]. Use for pharmacovigilance signal detection. WHICH REPORTS THE STATISTIC IS COMPUTED OVER: the drug arm of the 2x2 table searches the reported product name AND openFDA’s SPL annotation, which tags a report with EVERY brand and generic name registered for the active ingredient of a product the report named. A query therefore collects the whole active-ingredient population, not one product. That is correct for a generic name (TOFACITINIB’s 186,783 reports include the 173,708 that named XELJANZ, which are genuinely tofacitinib exposure) and wrong for a brand name whose ingredient has unrelated products (CYANOKIT, a cyanide antidote, has 4,119 reports of which only 238 named it; the rest are vitamin B12 supplementation). The share does NOT distinguish the two – both examples are ~93% – so the response measures it per call rather than guessing. Read cohort_scope before acting on the headline metrics: it carries reports_naming_queried_drug, reports_matched_by_name_resolution_only, percent_matched_by_name_resolution_only and a note. When those differ it also carries reported_name_only_analysis, the same 2x2 and ROR restricted to reports that named the drug – consult it, because the two can reach OPPOSITE verdicts: for CYANOKIT + DEATH the headline ROR is 0.287 [0.217-0.379], entirely below 1 and reported as ‘disproportionately LESS often’, while restricted to the 238 reports naming CYANOKIT it is 1.24 [0.694-2.216], i.e. inconclusive. cohort_scope is null when the split could not be established, including when the two measurements straddled an openFDA refresh and disagreed; null means unknown, never zero.

Parameters:

  • operation (unknown) (optional) Operation type (fixed)

  • drug_name (string) (optional) Generic drug name (e.g., ‘IBUPROFEN’, ‘ATORVASTATIN’)

  • adverse_event (string) (optional) MedDRA Preferred Term (e.g., ‘Hepatotoxicity’, ‘Myopathy’). Must be a WHOLE MedDRA Preferred Term: it is matched against the complete term, not as a substring, so a term that is not a Preferred Term (e.g. “bleeding”) is rejected, naming real Preferred Terms to retry with, rather than silently matched against every Preferred Term containing the word. Capitalization does not matter; spelling does – FAERS uses British forms (“Haemorrhage”, not “Hemorrhage”).

  • reaction (string) (optional) Alias for adverse_event. MedDRA Preferred Term for the adverse drug reaction, matched as a whole term (see adverse_event).

  • drug (string) (optional) Alias for drug_name. Generic drug name.

Example Usage:

query = {
    "name": "FAERS_calculate_disproportionality",
    "arguments": {
    }
}
result = tu.run(query)

FAERS_compare_drugs (Type: FAERSAnalyticsTool)#

Compare safety signals for two drugs with the same adverse event. Returns ROR/PRR/IC for both dru…

FAERS_compare_drugs tool specification

Tool Information:

  • Name: FAERS_compare_drugs

  • Type: FAERSAnalyticsTool

  • Description: Compare safety signals for two drugs with the same adverse event. Returns ROR/PRR/IC for both drugs with comparative analysis. Example: compare fulvestrant vs tamoxifen for hepatotoxicity. Use for safety benchmarking. The adverse event is matched against whole MedDRA Preferred Terms, so each arm’s counts contain the requested Preferred Term and nothing else. This matters for a COMPARISON specifically: a substring match sweeps in every compound term containing it, by a factor that differs per drug, so the ratio of the two arms – and with it the verdict – moves. Comparing heparin and bivalirudin on “Thrombocytopenia” is the worked case: a substring match adds HEPARIN-INDUCED THROMBOCYTOPENIA, which is bivalirudin’s INDICATION rather than its adverse effect, inflating heparin 2.45x and bivalirudin 4.11x and turning a real 1.6x difference into “similar-strength”. Each drug’s arm also returns the 2x2 contingency_table its metrics were computed from – a_drug_and_event, b_drug_no_event, c_no_drug_event, d_no_drug_no_event, the same keys FAERS_calculate_disproportionality uses – so the case counts behind the verdict are visible without extra calls. This matters because a ratio of two ratios is uninterpretable on its own: “similar-strength signals” means something very different when both arms rest on thousands of co-reported cases than when one rests on a handful. When either arm’s a_drug_and_event falls below 25, comparison_caveat names that arm and its count and warns that comparison is not an equal-confidence statement; it is null when both arms clear the threshold. 25 is where an arm’s own 95% ROR interval becomes narrower than the 1.5x ratio this comparison uses to separate “similar-strength” from “stronger”.

Parameters:

  • operation (unknown) (optional) Operation type (fixed)

  • drug1 (string) (optional) First drug name (generic)

  • drug2 (string) (optional) Second drug name (generic)

  • adverse_event (string) (optional) MedDRA Preferred Term to compare. Must be a WHOLE MedDRA Preferred Term: it is matched against the complete term, not as a substring, so a term that is not a Preferred Term (e.g. “bleeding”) is rejected, naming real Preferred Terms to retry with, rather than silently matched against every Preferred Term containing the word. Capitalization does not matter; spelling does – FAERS uses British forms (“Haemorrhage”, not “Hemorrhage”).

  • reaction (string) (optional) Alias for adverse_event. MedDRA Preferred Term for the adverse drug reaction, matched as a whole term (see adverse_event).

  • drugs (array) (optional) Alias for drug1/drug2. EXACTLY two drug names, e.g. [“tofacitinib”, “baricitinib”]. A list of three or more is rejected rather than truncated: the analysis is pairwise (one 2x2 contingency table per drug), so extra names cannot be compared in a single call – issue one call per pair.

Example Usage:

query = {
    "name": "FAERS_compare_drugs",
    "arguments": {
    }
}
result = tu.run(query)

FAERS_filter_serious_events (Type: FAERSAnalyticsTool)#

Filter for serious adverse events (death, hospitalization, disability, life-threatening). Returns…

FAERS_filter_serious_events tool specification

Tool Information:

  • Name: FAERS_filter_serious_events

  • Type: FAERSAnalyticsTool

  • Description: Filter for serious adverse events (death, hospitalization, disability, life-threatening). Returns top reactions meeting seriousness criteria. Example: fulvestrant serious events → Death: 150 cases, Hospitalization: 500 cases. Use for risk-benefit assessment.

Parameters:

  • operation (unknown) (optional) Operation type (fixed)

  • drug_name (string) (optional) Generic drug name

  • seriousness_type (string) (optional) Type of serious event to filter

  • drug (string) (optional) Alias for drug_name. Generic drug name.

  • event_type (string) (optional) Alias for seriousness_type. Type of serious event (e.g., hospitalization, death, life_threatening).

  • adverse_event (string) (optional) Specific adverse event to filter within serious events (e.g., ‘Myocardial infarction’, ‘Death’). Must be a WHOLE MedDRA Preferred Term: it is matched against the complete term, not as a substring, so a term that is not a Preferred Term (e.g. “bleeding”) matches nothing, rather than silently matching every Preferred Term containing the word. Capitalization does not matter; spelling does – FAERS uses British forms (“Haemorrhage”, not “Hemorrhage”).

Example Usage:

query = {
    "name": "FAERS_filter_serious_events",
    "arguments": {
    }
}
result = tu.run(query)

FAERS_rollup_meddra_hierarchy (Type: FAERSAnalyticsTool)#

Aggregate adverse events by MedDRA hierarchy (Preferred Term level). Returns the most-reported pr…

FAERS_rollup_meddra_hierarchy tool specification

Tool Information:

  • Name: FAERS_rollup_meddra_hierarchy

  • Type: FAERSAnalyticsTool

  • Description: Aggregate adverse events by MedDRA hierarchy (Preferred Term level). Returns the most-reported preferred terms with counts, ranked by descending report count, up to openFDA’s per-request maximum (999 anonymous, 1000 with FDA_API_KEY set). openFDA does not report how many distinct terms exist, so ‘unique_PTs_returned’ is the number of rows returned, NOT a total: check ‘truncated’ and read ‘truncation_note’ before treating the list as the drug’s full reaction profile. A PT absent from the list is not evidence it was never reported. Note: Full HLT/SOC hierarchy requires MedDRA license. Use for adverse event profile overview.

Parameters:

  • operation (unknown) (optional) Operation type (fixed)

  • drug_name (string) (optional) Generic drug name

  • drug (string) (optional) Alias for drug_name. Generic drug name.

Example Usage:

query = {
    "name": "FAERS_rollup_meddra_hierarchy",
    "arguments": {
    }
}
result = tu.run(query)

FAERS_stratify_by_demographics (Type: FAERSAnalyticsTool)#

Stratify adverse event reports by demographics (sex, age group, country). Returns counts and perc…

FAERS_stratify_by_demographics tool specification

Tool Information:

  • Name: FAERS_stratify_by_demographics

  • Type: FAERSAnalyticsTool

  • Description: Stratify adverse event reports by demographics (sex, age group, country). Returns counts and percentages by demographic group. Example: ibuprofen + GI bleeding stratified by sex → Female: 60%, Male: 40%. Use for subpopulation risk assessment. IMPORTANT – the stratification covers only a SUBSET of the matching reports: FAERS records demographics inconsistently, and openFDA computes a count facet solely over records that populate the counted field, so reports missing the demographic are absent from the groups entirely rather than bucketed as unknown. The response therefore reports two figures side by side: total_reports_matching_query (every report matching the drug/event query, from openFDA’s own meta.results.total) and stratified_report_count (the subset where the demographic is recorded, which the groups sum to) – for ondansetron stratified by age these are ~136,000 and ~25,000 respectively. A coverage_note names both figures and the coverage fraction. Each group percentage is a share of stratified_report_count, which is the correct denominator for a stratification. The legacy total_reports key repeats stratified_report_count for backward compatibility and is NOT the drug’s report count – read total_reports_matching_query for that. If the extra total request fails, total_reports_matching_query is null and coverage_note says so; everything else is still returned.

Parameters:

  • operation (unknown) (optional) Operation type (fixed)

  • drug_name (string) (optional) Generic drug name

  • adverse_event (string) (optional) MedDRA Preferred Term. Must be a WHOLE MedDRA Preferred Term: it is matched against the complete term, not as a substring, so a term that is not a Preferred Term (e.g. “bleeding”) matches nothing, rather than silently matching every Preferred Term containing the word. Capitalization does not matter; spelling does – FAERS uses British forms (“Haemorrhage”, not “Hemorrhage”).

  • stratify_by (string) (optional) Demographic dimension to stratify by. Use “sex”, “age”, or “country” (“age_group” is also accepted as alias for “age”).

  • reaction (string) (optional) Alias for adverse_event. MedDRA Preferred Term for the adverse drug reaction, matched as a whole term (see adverse_event).

  • demographic (string) (optional) Alias for stratify_by. Demographic dimension to stratify by (sex, age, or country).

  • drug (string) (optional) Alias for drug_name. Generic drug name.

Example Usage:

query = {
    "name": "FAERS_stratify_by_demographics",
    "arguments": {
    }
}
result = tu.run(query)