Replication Guide

The Accounting Conservation Framework (ACF) ships with a fully scripted replication pipeline that regenerates all analytic artefacts created in Tasks 02–07. This guide explains how to set up the environment, execute the one-command workflow, and verify reproducibility.

Quick Start

git clone https://github.com/nirvanchitnis-cmyk/accounting-conservation-framework.git
cd accounting-conservation-framework
bash REPRODUCE.sh

Runtime: ~120 minutes on a 16 GB RAM laptop (CPU-only)
Outputs: All results written to results/
Report: Deterministic check in results/REPRODUCIBILITY_REPORT.txt

Prerequisites

Operating System: Linux, macOS, or Windows (via WSL2)
Python: 3.9 – 3.12
Hardware: ≥16 GB RAM recommended (8 GB minimum), 10 GB free disk space
Network: Required for initial dependency installation (pip)
Data: Processed SEC filings (results/disaggregates/filings_real.csv). If absent, run python scripts/download_sec_data.py --output results/disaggregates/.

Step-by-Step Pipeline

Environment bootstrap (REPRODUCE.sh, Step 0)
- Creates or reuses ./venv
- Installs pinned dependencies from requirements-freeze.txt
- Fixes deterministic seeds (PYTHONHASHSEED=0, ACF_RANDOM_SEED=1337)
Constraint algebra (Step 2)
- scripts/compute_rank_snf.py generates results/constraint_analysis/*
Feasibility gap solver (Step 3)
- scripts/compute_feasibility_gaps.py writes δ* scores to results/feasibility_analysis/gap_scores.csv
Hierarchical calibration (Step 4)
- scripts/calibrate_residuals.py produces FDR-adjusted q-values and calibration plots
Temporal analysis (Step 5)
- scripts/temporal_analysis.py builds Bai–Perron and CUSUM diagnostics
Nullspace & adversarial audit (Step 6)
- scripts/analyze_gameability.py records nullspace dimensionality and adversarial probes
Precision/recall metrics (Step 7)
- scripts/compute_precision_recall.py consumes manual labels (if available)
- For documentation-only runs, the script skips gracefully when labels are missing
Reproducibility verification (Step 8)
- scripts/validate_reproducibility.py compares current artefacts against results/canonical/ within a configurable tolerance (default 1e-6)
Regression test sweep (Step 9)
- Executes the task-specific pytest modules to guard against regressions

Reproducibility Verification

Canonical artefacts live in results/canonical/.
On the first run the validation script seeds the canonical directory with the newly generated outputs (ensuring future comparisons have a baseline).
To intentionally refresh the baseline after a vetted change:

python scripts/validate_reproducibility.py --update-canonical

Review the report:

cat results/REPRODUCIBILITY_REPORT.txt

You should see:

============================================================
REPRODUCIBILITY VERIFICATION REPORT
============================================================
...
✅ ALL CHECKS PASSED - REPRODUCIBLE
============================================================

Troubleshooting

Symptom	Resolution
`ModuleNotFoundError: No module named 'cvxpy'`	Ensure the virtual environment is active and reinstall: `python -m pip install -r requirements-freeze.txt`
Missing `filings_real.csv`	Download processed filings: `python scripts/download_sec_data.py --output results/disaggregates/`
LP solver warnings (`ECOS` unavailable)	SCS is the fallback backend; performance may degrade but results remain stable. Install ECOS for faster solves: `python -m pip install ecos==2.0.14`
Minor numeric mismatches in report	Adjust tolerance: `python scripts/validate_reproducibility.py --tolerance 1e-4`
Regression tests fail	Re-run `REPRODUCE.sh` to ensure fresh artefacts, then inspect failing pytest modules for details

Archival Packaging Checklist

Run bash REPRODUCE.sh
Confirm results/REPRODUCIBILITY_REPORT.txt reports success
Zip the following for deposition (Zenodo/OSF):
- REPRODUCE.sh
- MODEL_CARD.md
- requirements-freeze.txt
- docs/reproducibility/REPLICATION_GUIDE.md
- results/ (including canonical/ and regenerated artefacts)
Record the commit SHA and Python version in accompanying documentation

Support

Operational questions: nirvanchitnis@gmail.com
Security disclosures: security@nchitnis-audit.com
Licensing: Code (Proprietary), Documentation (CC BY 4.0), Data (Research Use Only)