# CDC WONDER Mortality Database - Data Directory

**Source ID:** DS-00005

This directory contains data files fetched from the CDC WONDER Mortality Database API.

## File Structure

### Raw JSON Files
- `drugOverdose_latest.json` - Drug overdose deaths (ICD-10: X40-X44, X60-X64, X85, Y10-Y14)
- `opioid_latest.json` - Opioid-specific deaths (ICD-10: T40.0-T40.4, T40.6)
- `suicide_latest.json` - Suicide deaths (ICD-10: X60-X84, Y87.0, U03)
- `allCause_latest.json` - All-cause mortality
- `all_queries_latest.json` - Combined dataset from all queries

### Transformed Pipe-Delimited Files
- `drugOverdose_latest.txt` - Drug overdose deaths in Substrate format
- `opioid_latest.txt` - Opioid deaths in Substrate format
- `suicide_latest.txt` - Suicide deaths in Substrate format
- `allCause_latest.txt` - All-cause mortality in Substrate format

## Data Format

### Raw JSON
Array of mortality records with fields:
- `state` - US state name
- `year` - Year of death
- `deaths` - Number of deaths
- `population` - Population (if available)
- `crudeRate` - Crude death rate per 100,000
- `ageAdjustedRate` - Age-adjusted death rate per 100,000 (if available)

### Pipe-Delimited Format
Substrate standard format:
```
RECORD ID | QUERY TYPE | STATE | YEAR | DEATHS | POPULATION | CRUDE RATE | AGE ADJUSTED RATE
DS-00005-drugOverdose-California-2020 | Drug Overdose Deaths | California | 2020 | 5000 | 39538223 | 12.6 | N/A
```

## Update Process

Run the update script to fetch latest data:

```bash
bun run update.ts
```

## Data Coverage

- **Geographic:** All US states + DC + territories
- **Temporal:** 1999-present (ICD-10 era); most recent data typically 1-2 years lag
- **Frequency:** Annual updates (final data); quarterly (provisional data)
- **Completeness:** Census (100% of deaths, not sample)

## Important Notes

### Cell Suppression
CDC WONDER suppresses cells with counts <10 to protect privacy. Suppressed cells appear as "Suppressed" in results.

### Data Quality
- Drug overdose deaths: May be undercounted by 10-20% due to incomplete toxicology testing
- Suicide deaths: Estimated 20-35% undercount due to classification challenges
- Provisional data: Subject to revision when finalized (can change by 5-10%)

### Rate Calculations
- Crude Rate: Deaths per 100,000 population
- Age-Adjusted Rate: Standardized to 2000 US standard population (enables comparability across populations with different age structures)

## Citation

When using this data, cite:

Centers for Disease Control and Prevention, National Center for Health Statistics. (2024). *Wide-ranging ONline Data for Epidemiologic Research (WONDER)*. http://wonder.cdc.gov

## Last Updated

Generated by update.ts script. See update.log for last update timestamp and details.