# Replication Package — Phase B Outcome Correlation

**Working paper**: `mh_gap_youth_outcomes_v1_article.md`
**Methodology supplement**: `mh_gap_youth_outcomes_v1_methodology_supplement.md`
**Source dataset**: `analysis_outputs.mh_gap_youth_outcomes_v1` (35 states × 11 fields)
**License**: CC-BY-4.0

---

## What this package contains

| File | Purpose |
|---|---|
| `mh_gap_youth_outcomes_v1_article.md` | Working paper (~3,100w, 8 sections + supplementary) |
| `mh_gap_youth_outcomes_v1_methodology_supplement.md` | Pipeline + joining + correlation methodology |
| `mh_gap_youth_outcomes_v1_codebook.md` | 11-field data dictionary for the CSV |
| `mh_gap_youth_outcomes_v1_dartboard_narratives.md` | 10 per-state outcome profile narratives |
| `mh_gap_youth_outcomes_v1_press_release.md` + `mh_gap_youth_outcomes_v1_press_qa.md` | Press materials |
| `mh_gap_youth_outcomes_v1_executive_brief.md` | 2-page brief |
| `mh_gap_youth_outcomes_v1_sensitivity_analysis.md` | σ + sub-sample + AADR-year + taxonomy + denominator sweeps |
| `mh_gap_youth_outcomes_v1_narration_script.md` | TTS-ready data-story narration |
| `mh_gap_youth_outcomes_v1_bibliography.md` | 28 references organized by topic |
| `mh_gap_youth_outcomes_v1_state.csv` | Full joined dataset |
| `manifest.json` | sha256, field list, license, provenance |
| `README.md` | This file |

## How to reproduce the dataset from scratch

### 1. Phase A prerequisite: produce the Youth V1 gap dataset

Replicate the Youth Mental Health Access Gap V1 analysis first (see `mh_gap_youth_v1_replication_README.md`). This produces `analysis_outputs.mh_gap_youth_v1_state_v1` — 35 states × 12 gap measures.

### 2. Pull outcome source data

```python
# CDC YRBSS 2023 Mental Health Indicators
# data.cdc.gov/resource/nu3s-3dwd.json
# Filter to year=2023, demographics_type=Total, 5 mental-health questions
# Approximately 200 state-question rows for Total demographic.

# NCHS Leading Causes of Death (suicide cause)
# data.cdc.gov/resource/bi63-dtpu.json?cause_name=Suicide
# Most recent year: 2017. ~988 state-year rows total.

# NCHS VSRR Provisional Drug Overdose
# data.cdc.gov/resource/xkb8-kh2a.json?indicator=Number of Drug Overdose Deaths&year=2023
# 12-month-ending counts by state.

# ACS state total population
# api.census.gov/data/2023/acs/acs1?get=NAME,B01001_001E&for=state:*&key=<KEY>
# Needed for drug OD rate per 100K computation.
```

### 3. Stage as MongoDB collections

- `connector_data.yrbss_mental_health_v1` — raw YRBSS rows
- `connector_data.nchs_suicide_state_v1` — bi63-dtpu rows filtered to Suicide cause
- `connector_data.vsrr_drug_od_state_v1` — VSRR + ACS-population-derived per-state rate
- (state total population can be in the VSRR collection or separate)

### 4. Run the join

```python
import asyncio
from motor.motor_asyncio import AsyncIOMotorClient
async def main():
    db = AsyncIOMotorClient(...)["daedarch"]
    youth = {r["state_abbr"]: r async for r in db["analysis_outputs.mh_gap_youth_v1_state_v1"].find({})}
    # ... etc — see methodology supplement §7 for full code
```

Output: `analysis_outputs.mh_gap_youth_outcomes_v1` — 35 rows × 11 fields.

### 5. Run the correlation

For each gap_metric in {need, covariate, access, log_gap_ratio, residual_z} and each outcome_metric in {yrbss_considered, yrbss_made_plan, yrbss_attempted, all_age_suicide_aadr_2017, drug_od_rate_per_100k_2023}: compute Pearson r over the joined rows where both are non-null. See methodology supplement §2 for the formula.

### 6. Verify outputs

Your correlation matrix should match Table 1 of the working paper:

| Gap metric | YRBSS considered | YRBSS made plan | YRBSS attempted | All-age AADR | Drug OD rate |
|---|---:|---:|---:|---:|---:|
| need_value | +0.817 | +0.800 | +0.762 | +0.338 | +0.192 |
| covariate_value | +0.428 | +0.587 | +0.428 | +0.462 | -0.214 |
| access_value | -0.030 | +0.000 | +0.109 | +0.143 | +0.211 |
| log_gap_ratio | -0.028 | -0.015 | +0.027 | -0.164 | -0.095 |
| residual_z | -0.140 | -0.162 | -0.077 | -0.296 | -0.045 |

If any cell diverges by more than ±0.02, check (a) YRBSS release version, (b) NCHS bi63-dtpu year selection (2017 is correct), (c) ACS 2023 vs 2022 denominator.

## Sensitivity tests

See `mh_gap_youth_outcomes_v1_sensitivity_analysis.md` for full tables:

- σ sub-sample variations (excluding leverage points)
- AADR year sensitivity (1999-2017 stability check)
- Narrow vs broad NPPES taxonomy set
- Drug OD denominator alternatives (ACS vs NCHS bridged-race)
- Outlier exclusion (re-run without framework-flagged states)
- Population threshold variation (25K vs 50K vs 100K)

The headline findings are robust across all combinations.

## Limitations

8 listed in detail in the working paper §6:

1. Cross-sectional design
2. AADR is 2017 (6-year temporal gap)
3. All-age mortality (youth-specific requires CDC WONDER POST API)
4. YRBSS state coverage (35 of 50 + territories)
5. NPPES counts structural not capacity
6. No multivariate confounding adjustment
7. No FBI crime data (API key pending)
8. No HCUP ER visit data (licensed access required)

## How to extend

The framework is designed for re-binding. To apply Phase B-style outcome correlation to another need-vs-access study:

```python
# After producing your study's per-geography gap measures collection
inputs = {
  "study_id": "your_study_outcomes_v1",
  "gap_dataset": "analysis_outputs.<study_id>_<geography>_v1",
  "outcome_datasets": [
    {"collection":"...","measure_field":"...","label":"..."},
    {"collection":"...","measure_field":"...","label":"..."}
  ],
  "join_key": "state_abbr"  # or county_fips for tract-level studies
}
# Output: analysis_outputs.<study_id>_outcomes_v1 (joined rows)
#       + correlation matrix (one cell per gap × outcome pair)
```

The Phase B pipeline is not yet a registered DB-native tool (it's currently inline in the methodology supplement). v1.1 will register `atlas.outcome_correlation_v1` as a reusable tool taking any need-vs-access study + a set of outcome metric bindings.

## Contact

- Methodology questions: [email protected]
- Data questions: [email protected]
- Press inquiries: [email protected]

## Acknowledgments

CDC YRBSS team for biennial state-level youth surveillance. NCHS for state-level mortality data via the Leading Causes of Death and VSRR programs. The Census Bureau ACS team. The 35 states whose participation makes this analysis possible.

We acknowledge again that the most consequential limitation is what this analysis cannot say: at state-level cross-section, no claim of causal supply-vs-outcome effect can be made. The framework's value is the *workforce-build-out priority signal*; treating it as a *suicide-prevention triage signal* would mismatch the intervention to the problem.