Reproducible water-pollution transfer study

This repository contains the analytical record and revised paper for an India-to-Mexico water-pollution transfer study. The authoritative workflow is the reproducible pipeline below; exploratory_pipeline.ipynb is an exploratory, human-readable companion notebook.

Quick start

Requirements: Python 3.13, uv, and the two raw data files described in data/raw/README.md.

make setup
make reproduce
make verify
make test

make reproduce runs the analytical pipeline and then regenerates every figure used by the manuscript. It writes deterministic evidence to reports/evidence/ and figures to paper/media/figures/revision/.

To build the paper, install a TeX distribution with latexmk, then run:

make paper

Repository map

Path	Role
reproduce.py	Public entry point: analysis, then figure rendering.
revision_pipeline.py	Authoritative analysis: scoring, evaluation, transfer, sensitivity analyses, and evidence manifests.
render_evidence_figures.py	Rendering only; converts evidence CSVs into manuscript PNGs.
verify_evidence.py	Checks required evidence, figures, seed, and input hashes after a run.
test_revision_pipeline.py	Unit tests for scoring rules, leakage controls, splits, censoring, and transfer helpers.
exploratory_pipeline.ipynb	Exploratory narrative notebook. Its documented pure loader/schema cells are temporarily shared by the analysis script.
data/raw/	User-provided, untracked India CSV and Mexico workbook.
reports/evidence/	Generated analysis artifacts and provenance manifests.
paper/	Complete LaTeX source and generated revision figures.

Reproduction contract

Use the lockfile without modification:

uv sync --locked
uv run python reproduce.py
uv run python verify_evidence.py
uv run python -m unittest -v test_revision_pipeline.py

The evidence manifest records package versions, seed, grouped split policy, preprocessing policy, and SHA-256 hashes of both raw inputs. The Mexico alignment cache is reused only when its recorded raw-workbook hash matches the current workbook, preventing stale cached results.

Data and outputs

Raw data are intentionally not versioned. Obtain them from the cited sources and place them at the exact paths in data/raw/README.md. Generated evidence is versioned as an audit record; rerunning the pipeline may update it if raw inputs or the locked environment differ.

reports/evidence/aligned_target.pkl is a derived speed cache, not a research artifact. Delete it with make clean-cache to force Mexico re-alignment.

Notebook status

Do not use exploratory_pipeline.ipynb as the citation or final-results entry point. It preserves exploratory work and shared input normalization. Cite and rerun the workflow through reproduce.py; inspect revision_pipeline.py for the final analytical protocol.