# Reproduce the frozen US coffee sensitivity study

Study: https://www.locusintel.io/blog/us-coffee-expansion-shortlist-robustness
Source cutoff: Overture 2026-09-23.1; ACS 2020–2024 five-year; 2024 Gazetteer.
This is an eight-county model-sensitivity experiment, not a current-venue census or a profitable-site recommendation.

1. Extract `calculation-package.zip` into a new directory, preserving its paths.
2. Put the separately downloaded `frozen-inputs.zip` inside `data/us-retail-expansion-study/2026-10-14/` in that directory.
3. With Python 3.12 and NumPy, pandas and Pillow installed, run from that directory:

```
python scripts/us-retail-expansion-study/restore_frozen_inputs.py
python scripts/us-retail-expansion-study/validate.py
python scripts/us-retail-expansion-study/test_analysis.py
```

`analyze.py` and `audit_business_categories.py` can re-run the saved-data calculations. No network, API credentials or paid provider is needed. The restoration helper verifies all 44 original input hashes and refuses to overwrite differing files. Current results include the exact issuer-confirmed closure exclusion and locked-category repair. The two named pre-correction directories are historical, not the current baseline.

The saved protocol distinguishes pre-result decisions from post-result diagnostics. Source notices and licences remain attached. The evidence manifest records public download hashes; frozen-inputs-manifest.json records each original input's hash.