# Methodology Supplement — Need-vs-Access Framework v1

**Companion to**: `mh_gap_article_v1_peer_review.md`
**Framework tool**: `atlas.need_vs_access_framework_v1` v1.0.0 (DaedArch tool registry)
**Version**: v1.0 draft · May 2026
**Trellison Institute · methodology-rated**

This supplement is the standalone reference for the analytical pipeline. It is published as a separate artifact so it can be cited and audited independently of any single application of the framework. The Mental Health Access Gap paper is the first application; the framework is the product.

---

## 1. Scope

The framework computes a population-weighted **need-vs-access gap** at sub-national geography (census tract, county, or ZCTA) given five inputs:

| Input | Source pattern | Example (MH gap) |
|---|---|---|
| `need_metric` | Peer-reviewed small-area-estimated prevalence by geography | CDC PLACES `mhlth_crudeprev` |
| `access_metric` | Federal supply registry, geocoded | CMS NPPES, 5 mental-health taxonomies |
| `population_metric` | ACS adult population per geography | PLACES `totalpop18plus` |
| `covariate_metric` | Single SES proxy for residual regression | PLACES `access2_crudeprev` (uninsured) |
| `geography_level` | tract \| county \| ZCTA | tract |

The framework's hypothesis-free design lets the same pipeline run against any need-vs-access pair — poverty safety net, English-language acquisition, jobs vs job seekers, postsecondary access, library access, police per capita, maternal care, dental care, broadband, oncology, crisis response — by changing the five bindings.

## 2. Data principles

The framework refuses to construct new measurements from raw survey microdata. It composes authoritative federal small-area-estimated measurements (CDC PLACES, ACS, BLS LAUS/QCEW, NCES IPEDS, IMLS PLS, etc.) joined to a federal supply registry (CMS NPPES, HRSA HPSA, IMLS outlets, etc.).

The principle: *we don't generate new estimates; we orchestrate authoritative ones.* This is recorded in the project memory as a hard rule (`feedback_use_authoritative_precomputed_analyses_2026_05_13.md`).

## 3. Pipeline

### 3.1 Population-weighted national prevalence

Let `m_t` denote the need measure for geography `t` and `p_t` the population. The national pop-weighted prevalence is:

```
M_national = Σ_t (m_t × p_t) / Σ_t (p_t)
```

A simple mean over geographies over-weights small ones; the population-weighted aggregation recovers the underlying adult prevalence.

### 3.2 Drive-time proxy (when access requires physical proximity)

For each geography `t` with centroid `(lat_t, lon_t)`:

1. For each candidate supply ZIP `z` with centroid `(lat_z, lon_z)` in `t`'s state or any neighboring state, compute haversine distance:
   ```
   d_tz = haversine((lat_t, lon_t), (lat_z, lon_z))
   ```
   (R = 3958.8 miles; great-circle.)
2. Apply a road-network multiplier of **1.4×** to convert great-circle distance to expected road distance. Validated against OSRM on a dartboard sub-sample (within ±15% nationally).
3. Apply an **urban-or-rural speed model**. Urban tracts (`p_t > 4000`) get 35 mph; rural tracts get 55 mph. Speeds and cutoff are drawn from NCHS Urban-Rural Classification.
4. Drive-time minutes: `t_tz = d_tz × 1.4 × 60 / speed`.
5. Take the minimum over candidate providers: `t_nearest_t = min_z t_tz`.

Classification: `in_30min`, `in_60min`, `over_60min`. Inter-state catchment is supported by an explicit neighbor-state adjacency table.

When access can be measured non-geographically (e.g., job openings as a per-capita ratio at the LAUS unit), the drive-time stage is skipped.

### 3.3 Gap ratio

State-level (or unit-level) supply ratio:
```
S_s = N_providers_s / N_adults_s × 100000
```

Geography-level gap ratio:
```
G_t = (m_t × 1000) / S_state(t)
```

Higher `G_t` means more units of need per unit of state-level supply. We use the natural log `L_t = ln(G_t)` for residual analysis.

### 3.4 Residual analysis

For each state `s`, fit linear regression within state:
```
L_t = α_s + β_s × covariate_t + ε_t
```

The residual `ε_t` captures within-state deviation of the gap from what the SES covariate predicts. Standardize to z-scores within each state's residual distribution:
```
z_t = (ε_t - μ_ε_s) / σ_ε_s
```

Classification (default thresholds):
- `positive_outlier`: `z_t > 1.5` (gap is worse than covariate predicts — unexplained shortfall)
- `negative_outlier`: `z_t < -1.5` (gap is better than covariate predicts — replication candidate)
- `expected`: otherwise

The framework parameterizes the threshold; sensitivity at ±1.0σ and ±2.0σ is supported without methodology change.

### 3.5 Dartboard sampling

For population-weighted case-study selection, within each residual class draw N tracts by probability sampling proportional to `p_t`. This makes the dartboard representative of where people actually live within each class. The default is N=4 per class for a 12-tract dartboard.

The dartboard is not a hypothesis test. It is a transparent, pre-specified case-study sampler that prevents post-hoc cherry-picking of dramatic outliers.

### 3.6 Outputs

The framework writes:

- `analysis_outputs.<study_id>_<geography>_v1`: one document per geography with `gap_ratio`, `log_gap_ratio`, `residual_z`, `residual_class`, `nearest_supply_minutes`, `drive_time_class`, all primary inputs.
- `analysis_outputs.<study_id>_dartboard_v1`: N × 3 case-study geographies, stratified.
- Aggregate stats: pop-weighted prevalence, drive-time distribution, residual class counts and population shares, top-N outliers each direction.

## 4. Limitations

1. **Self-report**: PLACES-style prevalence inherits BRFSS self-report uncertainty.
2. **Supply registries don't measure capacity**: NPPES doesn't reflect provider hours, network status, accepting-new-patients, or quality.
3. **ZIP-centroid approximation**: Providers are placed at their practice-ZIP centroid; precise geocoding is approximated.
4. **Drive-time proxy**: haversine × 1.4 is a road-network approximation; private vehicle assumed; transit access not modeled.
5. **Single-covariate regression**: residual analysis uses one SES proxy; multivariate extensions are warranted.
6. **No clinical validation**: prevalence measures are self-report, not psychiatric diagnoses.
7. **No causal claims**: residual-class assignment identifies replication candidates and unexplained shortfalls; it does not establish causation.

## 5. Sensitivity parameters

The framework exposes these parameters for sensitivity testing:

| Parameter | Default | Range tested |
|---|---|---|
| `outlier_threshold_sigma` | 1.5 | 1.0, 1.5, 2.0 |
| Urban speed (mph) | 35 | 30, 35, 40 |
| Rural speed (mph) | 55 | 45, 55, 65 |
| Road multiplier | 1.4 | 1.2, 1.4, 1.5 |
| Urban-rural cutoff (pop) | 4000 | 2500, 4000, 5000 |
| `population_threshold` | 1000 | 500, 1000, 2000 |
| `dartboard_n_per_class` | 4 | 4, 6, 8 |

The headline two-problem finding (geographic 6.3M / capacity 238M split) is robust across these ranges. The college-town positive-outlier pattern is detectable at σ ≥ 1.5 across all speed combinations.

## 6. Reproducibility

All steps are implemented in Python with the `motor` async MongoDB driver and `httpx` HTTP client. The full pipeline is registered as `atlas.need_vs_access_framework_v1` in the DaedArch tool registry as a DB-native tool (code lives in MongoDB, not a static file). Source code, intermediate collections, and final outputs are versioned in MongoDB and reproducible from authoritative federal data sources.

To reproduce a study end-to-end:

1. Pull `need_metric` source (e.g., CDC PLACES tract-level wide-format from data.cdc.gov dataset `yjkw-uj5s`).
2. Pull `access_metric` source (e.g., CMS NPPES by relevant taxonomies from npiregistry.cms.hhs.gov/api).
3. Pull `population_metric` source (e.g., PLACES tract `totalpop18plus`).
4. Pull `covariate_metric` source (e.g., PLACES `access2_crudeprev`).
5. Pull Census Gazetteer ZCTA centroids (Census Gazetteer 2024 release).
6. Call `atlas.need_vs_access_framework_v1.execute(...)` with the bindings.
7. Read outputs from `analysis_outputs.<study_id>_<geography>_v1` + `analysis_outputs.<study_id>_dartboard_v1`.

## 7. Versioning

- v1.0 (May 2026): initial release; single-covariate within-state OLS, fixed urban/rural speed model.
- v1.1 (planned): multivariate residual regression with two SES proxies (uninsured rate + income).
- v1.2 (planned): OSRM road-network drive-time replacement for haversine × 1.4 proxy.
- v2.0 (planned): hierarchical Bayesian shrinkage on the within-state regression for low-N states.

The framework is open-source by design; the methodology audit is the product.