# Beyond Inflation: Measuring the Real Cost of Living in Zimbabwe's Multi-Currency Economy, May 2024 – September 2026

Research code, data extracts, tables and figures for the paper. Every number
in the manuscript is read from `results.json`, which `scripts/analysis.py`
writes; the manuscript build fails if any number cannot be computed.

## Reproduce

From the repository root:

```sh
# 1. Build a research database with the platform's collectors (any empty SQLite path)
DATABASE_PATH=/path/to/research.db npx tsx scripts/ingest.ts

# 2. Export the analysis extracts to research/beyond-inflation/data/
DATABASE_PATH=/path/to/research.db npx tsx research/beyond-inflation/scripts/export.mts

# 3. Food energy table (downloads USDA SR Legacy, about 6 MB, once)
python3 research/beyond-inflation/scripts/energy.py

# 4. Analysis: tables/, figures/, results.json (fixed seed)
python3 research/beyond-inflation/scripts/analysis.py

# 5. Manuscript (needs pandoc via `pip install pypandoc_binary`; PDF via headless Chromium)
python3 research/beyond-inflation/scripts/build_manuscript.py            # manuscript, title page first
python3 research/beyond-inflation/scripts/build_manuscript.py --blind    # optional anonymised copy for blind review
```

The extracts in `data/` are those used for the paper (database built on
28 September 2026). Steps 3–5 reproduce the paper from them without step 1.

## Files

| Path | What it is |
|---|---|
| `scripts/export.mts` | Exports observations, pooled shelf, basket lines and reference tables from a platform database. Reuses the platform's own classification and basket pricing. |
| `scripts/common.py` | Loading, cleaning (audit corrections), plotting helpers. |
| `scripts/analysis.py` | Every analysis in the paper, section by section. |
| `scripts/energy.py` | Maps basket items to USDA SR Legacy energy values → `data/energy_kcal.csv`. |
| `scripts/build_manuscript.py`, `scripts/pdf.mjs` | Fill the template from `results.json` and `tables/`; write .md, .docx, .html and .pdf. |
| `scripts/pdftext.mts` | Text extraction used to read ZIMSTAT and RBZ PDFs. |
| `sources/references-verified.md` | Every reference, with how it was verified. |
| `sources/wb_gem_DPANUSSPB_ZWE.json` | World Bank GEM monthly official rate (pre-ZiG units), rescaled in `analysis.official_rate_monthly`. |
| `sources/wdi_PA.NUS.FCRF_ZWE.json` | World Bank annual official rate, used to check the rescaled series. |
| `sources/rbz_official_zwg_rates.csv` | Four RBZ daily rate sheets read directly, used as checks. |
| `sources/zimpricecheck_archived_rates.csv` | Maximum business, informal and cash rates from 18 archived copies of the price-monitoring site's rates page (May 2024 – February 2026); joined to the live reading of 28 September 2026 in `analysis.market_rates_history`. |
| `manuscript/template.md`, `manuscript/print.css` | Manuscript text with its numbers as expressions; print style. |

`manuscript/title_page.md` (author contact details) and `manuscript/build/`
are not in version control.

The study window is May 2024 to September 2026 (`START` in `analysis.py`);
the extracts also hold older data, which the analysis leaves out.

## Data corrections applied (see the paper, Table 2)

- The price-monitoring site's informal range was published upside down in
  the live reading of 28 September 2026 (the "lowest" rate above the
  "highest"); every day's pair is recoded as a lower and upper end.
- Outside the window (2019–2022): 238 archived prices from US-dollar
  columns had been stored as ZWL because the historical-tables collector
  read the currency from the cell, not the column header, and 25 rows of a
  bank exchange-rate table were stored as prices. `common.clean_observations`
  corrects both; the collector (`lib/ingest/collectors/zpc-tables.ts`)
  should be fixed the same way.

## Limits worth knowing before reuse

- Informal, cash and maximum business rates exist for 19 dates between
  14 May 2024 and 28 September 2026 (18 archived copies of the monitoring
  site's page plus the live reading); supermarket till rates for one day,
  28 September 2026. The archived rates are in the platform database but
  not in `data/exchange_rates.csv`, because the Internet Archive could not
  be reached when the extracts were built; they are kept in `sources/`.
- The official monthly rate before 2026 is the World Bank GEM series
  rescaled by one constant (checked against the 2025 annual rate and four
  RBZ sheets). The RBZ website blocks automated reading; do not script it.
- The current shelf comes from three national chains' online catalogues
  (one price list per chain, no branch prices), but 91% of its products
  come from one chain. Tuckshops and informal traders are not covered.
- Rent is excluded: the platform holds too few listings for an estimate.