# Replication Package — Mental Health Access Gap V1
**Working paper**: `mh_gap_article_v1_peer_review.md`
**Methodology supplement**: `mh_gap_v1_methodology_supplement.md`
**Framework tool**: `atlas.need_vs_access_framework_v1` v1.0.0
**Dataset**: `mh_gap_tract_v1.csv` (78,815 rows × 27 fields, sha256 in manifest.json)
**License**: CC-BY-4.0
**Recommended citation**: Trellison Institute, *The Mental Health Access Gap in the United States Divides into Two Distinct Problems*, working paper v1.0 (May 2026). DOI: [pending]
---
## What this package contains
| File | Purpose |
|---|---|
| `mh_gap_article_v1_peer_review.md` | The working paper (~6,500 words, 10 sections) |
| `mh_gap_v1_methodology_supplement.md` | Standalone methodology reference |
| `mh_gap_v1_codebook.md` | Per-field data dictionary for the CSV |
| `mh_gap_v1_dartboard_narratives.md` | 12 case-study tract profiles |
| `mh_gap_v1_press_release.md` + `mh_gap_v1_press_qa.md` | Press materials |
| `mh_gap_v1_executive_brief_v1.md` | 2-page brief |
| `mh_gap_v1_narration_v1_3.md` | TTS-ready data-story narration |
| `mh_gap_tract_v1.csv` | Full per-tract dataset |
| `manifest.json` | sha256, field list, license, source provenance |
| `atlas.need_vs_access_framework_v1.code_content` | Pipeline code (DB-native tool export) |
| `README.md` | This file |
## How to reproduce the dataset from scratch
The analytical pipeline depends only on authoritative federal data sources. To reproduce `mh_gap_tract_v1.csv` from raw inputs:
### 1. Pull source data
```python
# CDC PLACES tract-level wide-format (MHLTH + ACCESS2)
# https://data.cdc.gov/dataset/PLACES-Local-Data-for-Better-Health-Census-Tract-D/yjkw-uj5s
# Approximately 84,400 rows nationwide.
# CDC PLACES tract-level long-format with geolocation (MHLTH)
# https://data.cdc.gov/dataset/PLACES-Local-Data-for-Better-Health-Census-Tract-D/cwsq-ngmh
# Used for tract-centroid coordinates.
# CMS NPPES National Provider Identifier registry
# https://npiregistry.cms.hhs.gov/api
# Query 5 mental-health taxonomies (psychiatry, psychology, clinical social work, MFT, psychiatric NP).
# Approximately 102,000 providers nationwide.
# Census Gazetteer 2024 ZCTA centroids
# https://www2.census.gov/geo/docs/maps-data/data/gazetteer/2024_Gazetteer/
# Required for ZIP-centroid distance calculations.
```
### 2. Stage inputs in the same database
The framework expects the source tables to be in MongoDB collections (`connector_data.cdc_places_tract`, `connector_data.cdc_places_tract_geo`, `connector_data.cms_nppes`, `connector_data.census_gazetteer_zcta`). Adapter scripts for each connector are in the DaedArch tool registry under `harturk.*` and `connector.*`.
### 3. Run the framework
```python
# DB-native — call via the DaedArch platform's tool executor
POST /api/v4/execute
{
"tool_id": "atlas.need_vs_access_framework_v1",
"inputs": {
"study_id": "mh_gap_v1",
"need": {
"collection": "connector_data.cdc_places_tract",
"measure_field": "mhlth_crudeprev",
"geography_id_field": "tract_fips"
},
"access": {
"collection": "connector_data.cms_nppes",
"rollup_to": "state",
"geography_id_field": "practice_state"
},
"population": {
"collection": "connector_data.cdc_places_tract",
"geography_id_field": "tract_fips",
"pop_field": "totalpop18plus"
},
"covariate": {
"collection": "connector_data.cdc_places_tract",
"measure_field": "access2_crudeprev",
"geography_id_field": "tract_fips"
},
"geography_level": "tract",
"population_threshold": 1000,
"outlier_threshold_sigma": 1.5,
"dartboard_n_per_class": 4
}
}
```
### 4. Run the drive-time supplement
The framework's residual analysis runs without drive-time; the headline two-problem finding requires a separate drive-time computation that joins the tract centroid to the nearest provider ZIP centroid (haversine × 1.4 road multiplier, urban/rural speed model). See methodology supplement §3.2.
### 5. Compare outputs
Your `analysis_outputs.mh_gap_v1_tract_v1` collection should match `mh_gap_tract_v1.csv` byte-for-byte (modulo CSV float formatting). The aggregate stats should reproduce:
- Population-weighted prevalence: **16.80%**
- Within 30-min drive: **91.3%**
- Over 60-min drive: **2.6%**
- Residual class breakdown: **89% expected / 6.4% negative / 4.6% positive**
If any of these diverge by more than ±0.5 percentage points, check (a) PLACES release version, (b) NPPES snapshot date, (c) any sub-state catchment configuration.
## Sensitivity tests we ran
The methodology supplement (§5) reports sensitivity at:
- `outlier_threshold_sigma` ∈ {1.0, 1.5, 2.0}
- urban speed ∈ {30, 35, 40} mph
- rural speed ∈ {45, 55, 65} mph
- road multiplier ∈ {1.2, 1.4, 1.5}
- urban-rural cutoff ∈ {2,500; 4,000; 5,000} population
The headline two-problem finding (geographic 6.3M / capacity 238M) is robust across all combinations. The college-town positive-outlier pattern is detectable at σ ≥ 1.5 across all speed combinations.
## Limitations
The methodology supplement §4 lists 7 limitations in detail. Briefly:
1. PLACES inherits BRFSS self-report uncertainty
2. NPPES doesn't reflect provider capacity, hours, network status
3. ZIP-centroid is an approximation of precise provider geocoding
4. Drive-time proxy approximates road network; private vehicle assumed
5. Single-covariate residual regression; multivariate extension warranted
6. Self-report not validated against psychiatric diagnoses
7. Residual class is a signal, not causation
## How to extend to other access domains
The framework is hypothesis-free with respect to the access domain. To run on poverty safety-net, library access, postsecondary, etc., bind:
```python
# Library access example (IMLS PLS + ACS)
inputs = {
"study_id": "library_access_v1",
"need": {"collection": "...", "measure_field": "..."}, # e.g., ACS literacy proxy
"access": {"collection": "connector_data.imls_pls", "rollup_to": "county"},
"population": {...},
"covariate": {...},
"geography_level": "county"
}
```
The framework writes outputs to `analysis_outputs.library_access_v1_county_v1` and `analysis_outputs.library_access_dartboard_v1` — same schema, same outputs, same dartboard sampling.
## Contact
- Methodology questions: [email protected]
- Data questions: [email protected]
- Press inquiries: [email protected]
- Framework tool registry: DaedArch platform · `atlas.need_vs_access_framework_v1` v1.0.0
## Acknowledgments
CDC PLACES team for the tract-level small-area estimates. CMS for the NPPES public registry. Census Bureau for the Gazetteer file and the underlying ACS demographic estimates. The 78,815 census tracts and the 244.5 million American adults their numbers represent.