fda-database

# FDA Database Access ## Overview Access comprehensive FDA regulatory data through openFDA, the FDA's initiative to provide open APIs for public datasets. Query information about drugs, medical devices, foods, animal/veterinary products, and substances using Python with standardized interfaces. **Key capabilities:** - Query adverse events for drugs, devices, foods, and veterinary products - Access product labeling, approvals, and regulatory submissions - Monitor recalls and enforcement actions - Look up National Drug Codes (NDC) and substance identifiers (UNII) - Analyze device classifications and clearances (510k, PMA) - Track drug shortages and supply issues - Research chemical structures and substance relationships ## When to Use This Skill This skill should be used when working with: - **Drug research**: Safety profiles, adverse events, labeling, approvals, shortages - **Medical device surveillance**: Adverse events, recalls, 510(k) clearances, PMA approvals - **Food safety**: Recalls, allergen tracking, adverse events, dietary supplements - **Veterinary medicine**: Animal drug adverse events by species and breed - **Chemical/substance data**: UNII lookup, CAS number mapping, molecular structures - **Regulatory analysis**: Approval pathways, enforcement actions, compliance tracking - **Pharmacovigilance**: Post-market surveillance, safety signal detection - **Scientific research**: Drug interactions, comparative safety, epidemiological studies ## Quick Start ### 1. Basic Setup ```python from scripts.fda_query import FDAQuery # Initialize (API key optional but recommended) fda = FDAQuery(api_key="YOUR_API_KEY") # Query drug adverse events events = fda.query_drug_events("aspirin", limit=100) # Get drug labeling label = fda.query_drug_label("Lipitor", brand=True) # Search device recalls recalls = fda.query("device", "enforcement", search="classification:Class+I", limit=50) ``` ### 2. API Key Setup While the API works without a key, registering provides higher rate limits: - **Without key**: 240 requests/min, 1,000/day - **With key**: 240 requests/min, 120,000/day Register at: https://open.fda.gov/apis/authentication/ Set as environment variable: ```bash export FDA_API_KEY="your_key_here" ``` ### 3. Running Examples ```bash # Run comprehensive examples python scripts/fda_examples.py # This demonstrates: # - Drug safety profiles # - Device surveillance # - Food recall monitoring # - Substance lookup # - Comparative drug analysis # - Veterinary drug analysis ``` ## FDA Database Categories ### Drugs Access 6 drug-related endpoints covering the full drug lifecycle from approval to post-market surveillance. **Endpoints:** 1. **Adverse Events** - Reports of side effects, errors, and therapeutic failures 2. **Product Labeling** - Prescribing information, warnings, indications 3. **NDC Directory** - National Drug Code product information 4. **Enforcement Reports** - Drug recalls and safety actions 5. **Drugs@FDA** - Historical approval data since 1939 6. **Drug Shortages** - Current and resolved supply issues **Common use cases:** ```python # Safety signal detection fda.count_by_field("drug", "event", search="patient.drug.medicinalproduct:metformin", field="patient.reaction.reactionmeddrapt") # Get prescribing information label = fda.query_drug_label("Keytruda", brand=True) # Check for recalls recalls = fda.query_drug_recalls(drug_name="metformin") # Monitor shortages shortages = fda.query("drug", "drugshortages", search="status:Currently+in+Shortage") ``` **Reference:** See `references/drugs.md` for detailed documentation ### Devices Access 9 device-related endpoints covering medical device safety, approvals, and registrations. **Endpoints:** 1. **Adverse Events** - Device malfunctions, injuries, deaths 2. **510(k) Clearances** - Premarket notifications 3. **Classification** - Device categories and risk classes 4. **Enforcement Reports** - Device recalls 5. **Recalls** - Detailed recall information 6. **PMA** - Premarket approval data for Class III devices 7. **Registrations & Listings** - Manufacturing facility data 8. **UDI** - Unique Device Identification database 9. **COVID-19 Serology** - Antibody test performance data **Common use cases:** ```python # Monitor device safety events = fda.query_device_events("pacemaker", limit=100) # Look up device classification classification = fda.query_device_classification("DQY") # Find 510(k) clearances clearances = fda.query_device_510k(applicant="Medtronic") # Search by UDI device_info = fda.query("device", "udi", search="identifiers.id:00884838003019") ``` **Reference:** See `references/devices.md` for detailed documentation ### Foods Access 2 food-related endpoints for safety monitoring and recalls. **Endpoints:** 1. **Adverse Events** - Food, dietary supplement, and cosmetic events 2. **Enforcement Reports** - Food product recalls **Common use cases:** ```python # Monitor allergen recalls recalls = fda.query_food_recalls(reason="undeclared peanut") # Track dietary supplement events events = fda.query_food_events( industry="Dietary Supplements") # Find contamination recalls listeria = fda.query_food_recalls( reason="listeria", classification="I") ``` **Reference:** See `references/foods.md` for detailed documentation ### Animal & Veterinary Access veterinary drug adverse event data with species-specific information. **Endpoint:** 1. **Adverse Events** - Animal drug side effects by species, breed, and product **Common use cases:** ```python # Species-specific events dog_events = fda.query_animal_events( species="Dog", drug_name="flea collar") # Breed predisposition analysis breed_query = fda.query("animalandveterinary", "event", search="reaction.veddra_term_name:*seizure*+AND+" "animal.breed.breed_component:*Labrador*") ``` **Reference:** See `references/animal_veterinary.md` for detailed documentation ### Substances & Other Access molecular-level substance data with UNII codes, chemical structures, and relationships. **Endpoints:** 1. **Substance Data** - UNII, CAS, chemical structures, relationships 2. **NSDE** - Historical substance data (legacy) **Common use cases:** ```python # UNII to CAS mapping substance = fda.query_substance_by_unii("R16CO5Y76E") # Search by name results = fda.query_substance_by_name("acetaminophen") # Get chemical structure structure = fda.query("other", "substance", search="names.name:ibuprofen+AND+substanceClass:chemical") ``` **Reference:** See `references/other.md` for detailed documentation ## Common Query Patterns ### Pattern 1: Safety Profile Analysis Create comprehensive safety profiles combining multiple data sources: ```python def drug_safety_profile(fda, drug_name): """Generate complete safety profile.""" # 1. Total adverse events events = fda.query_drug_events(drug_name, limit=1) total = events["meta"]["results"]["total"] # 2. Most common reactions reactions = fda.count_by_field( "drug", "event", search=f"patient.drug.medicinalproduct:*{drug_name}*", field="patient.reaction.reactionmeddrapt", exact=True ) # 3. Serious events serious = fda.query("drug", "event", search=f"patient.drug.medicinalproduct:*{drug_name}*+AND+serious:1", limit=1) # 4. Recent recalls recalls = fda.query_drug_recalls(drug_name=drug_name) return { "total_events": total, "top_reactions": reactions["results"][:10], "serious_events": serious["meta"]["results"]["total"], "recalls": recalls["results"] } ``` ### Pattern 2: Temporal Trend Analysis Analyze trends over time using date ranges: ```python from datetime import datetime, timedelta def get_monthly_trends(fda, drug_name, months=12): """Get monthly adverse event trends.""" trends = [] for i in range(months): end = datetime.now() - timedelta(days=30*i) start = end - timedelta(days=30) date_range = f"[{start.strftime('%Y%m%d')}+TO+{end.strftime('%Y%m%d')}]" search = f"patient.drug.medicinalproduct:*{drug_name}*+AND+receivedate:{date_range}" result = fda.query("drug", "event", search=search, limit=1) count = result["meta"]["results"]["total"] if "meta" in result else 0 trends.append({ "month": start.strftime("%Y-%m"), "events": count }) return trends ``` ### Pattern 3: Comparative Analysis Compare multiple products side-by-side: ```python def compare_drugs(fda, drug_list): """Compare safety profiles of multiple drugs.""" comparison = {} for drug in drug_list: # Total events events = fda.query_drug_events(drug, limit=1) total = events["meta"]["results"]["total"] if "meta" in events else 0 # Serious events serious = fda.query("drug", "event", search=f"patient.drug.medicinalproduct:*{drug}*+AND+serious:1", limit=1) serious_count = serious["meta"]["results"]["total"] if "meta" in serious else 0 comparison[drug] = { "total_events": total, "serious_events": serious_count, "serious_rate": (serious_count/total*100) if total > 0 else 0 } return comparison ``` ### Pattern 4: Cross-Database Lookup Link data across multiple endpoints: ```python def comprehensive_device_lookup(fda, device_name): """Look up device across all relevant databases.""" return { "adverse_events": fda.query_device_events(device_name, limit=10), "510k_clearances": fda.query_device_510k(device_name=device_name), "recalls": fda.query("device", "enforcement", search=f"product_description:*{device_name}*"), "udi_info": fda.query("device", "udi", search=f"brand_name:*{device_name}*") } ``` ## Working with Results ### Response Structure All API responses follow this structure: ```python { "meta": { "disclaimer": "...", "results": { "skip": 0, "limit": 100, "total": 15234 } }, "results": [ # Array of result objects ] } ``` ### Error Handling Always handle potential errors: ```python result = fda.query_drug_events("aspirin", limit=10) if "error" in result: print(f"Error: {result['error']}") elif "results" not in result or len(result["results"]) == 0: print("No results found") else: # Process results for event in result["results"]: # Handle event data pass ``` ### Pagination For large result sets, use pagination: ```python # Automatic pagination all_results = fda.query_all( "drug", "event", search="patient.drug.medicinalproduct:aspirin", max_results=5000 ) # Manual pagination for skip in range(0, 1000, 100): batch = fda.query("drug", "event", search="...", limit=100, skip=skip) # Process batch ``` ## Best Practices ### 1. Use Specific Searches **DO:** ```python # Specific field search search="patient.drug.medicinalproduct:aspirin" ``` **DON'T:** ```python # Overly broad wildcard search="*aspirin*" ``` ### 2. Implement Rate Limiting The `FDAQuery` class handles rate limiting automatically, but be aware of limits: - 240 requests per minute - 120,000 requests per day (with API key) ### 3. Cache Frequently Accessed Data The `FDAQuery` class includes built-in caching (enabled by default): ```python # Caching is automatic fda = FDAQuery(api_key=api_key, use_cache=True, cache_ttl=3600) ``` ### 4. Use Exact Matching for Counting When counting/aggregating, use `.exact` suffix: