# Replication guide — UQO WP 35

## Environment
- macOS or Linux, Python 3.12 (managed with `uv`), TeX Live with `latexmk` and the `aer` bibliography style, `make`.
- Pinned dependencies in `pyproject.toml` (numpy 2.3.4, pandas 2.3.3, scipy 1.16.2, statsmodels 0.14.5, lifelines 0.30.0,
  scikit-learn 1.7.2, networkx 3.5, matplotlib 3.10.7, pyreadr 0.5.3, openpyxl 3.1.5, pyarrow 21.0.0, pytest 8.4.2, …).

```bash
uv venv -p 3.12 .venv && uv pip install -p .venv/bin/python -e .
```

## One-command reproduction
```bash
make all      # fetch → data → measure → econ → sim → figures → paper
make test     # 11 tests
```
Individual targets, in dependency order:

| target | command | outputs | time (M5 Max laptop) |
|---|---|---|---|
| fetch | `python -m wp35.acquisition.fetch` | `data/raw/*`, `data/metadata/source_registry.json` | ~1 min (65 MB) |
| data | `python -m wp35.harmonization.build_panels` | `data/processed/*.parquet`, `results/diagnostics/*`, coverage figures | ~1 min |
| measure | `python -m wp35.measurement.build_indices` | `data/processed/*_indices.parquet`, `results/empirical/measurement_*`, `power_h2a_*` | ~10 s |
| econ | `python -m wp35.econometrics.run_all` (= h1, h2_seshat, h2_modern) | `results/empirical/h1_*`, `h2_*`, `h4_*`, `h5_*` | ~15 min (modern panel dominates) |
| sim | `python -m wp35.simulations.run_experiments && python -m wp35.simulations.analyze` | `results/simulated/*` and `fig_sim_*` | ~1 min on 12 cores |
| figures | `python -m wp35.visualization.make_all` | `paper/tables/*.tex`, `paper/figures/*.pdf` | ~10 s |
| paper | `python -m wp35.validation.build_bib && cd paper && latexmk -pdf main.tex` | `paper/references.bib`, `paper/main.pdf` | ~1 min |

## Determinism
- Estimation seed 20261101 (cross-validation folds, power simulations); simulation seeds 0–7; IRT is deterministic (EM).
- `python -m wp35.validation.verify_bib` re-queries Crossref and may differ if Crossref metadata changes; the verified list used for the paper is `research/prior_art.csv` + `research/bib_overrides.csv`.

## Provenance of every number
Each table fragment in `paper/tables/` is written by `src/wp35/visualization/make_all.py` from a file in `results/`;
each figure likewise. The execution log `results/logs/execution_log.md` records every command and every correction
made during the study; `results/logs/final_research_audit.md` lists completed, failed and blocked tasks.

## Pre-registration
`research/preregistration.md` was frozen before any predictor–outcome association was computed; SHA-256
`ecda8804e17f931789be8e274ba1ff989000de356700a85b638b043928182e3a` (recorded in `research/decisions.md`, D-003).
Verify with `shasum -a 256 research/preregistration.md`.