# Reproducibility

Every web artifact in this repo is regenerated from public data by `pipeline/`. The
sample shipped here is a strict subset of that output.

## 1. Environment

```bash
python -m venv .venv && source .venv/bin/activate
pip install -r pipeline/requirements-lock.txt
pip install -e pipeline/packages/asd-braintwin
```

Python 3.12. The package (`asd_braintwin`) holds the engine (reference-space fit,
marker extraction, normative trajectories) and the builders the scripts call.

## 2. Obtain the source data (under their terms)

You must download these yourself; they are not redistributed here.

- **ABIDE I — PCP / C-PAC / CC200** (ROI timeseries). CC BY-NC-SA, non-commercial
  research. See [DATA.md](../DATA.md).
- **ADHD-200** (resting-state, optional — only for the extended clinic cohort).

Place them where the builders expect (paths are configurable at the top of each
script; defaults mirror the research tree's `data/raw/`).

For the core ABIDE I engine, the repository includes a resumable downloader and
converter. It retrieves the official PCP `C-PAC / filt_noglobal / CC200` ROI
time-series and creates the aligned NPZ files expected by the package:

```bash
python pipeline/scripts/prepare_abide_data.py
# → data/processed/abide_cc200_tuple.npz
# → data/processed/abide_cc200_dfc.npz
```

The script validates the 1102-subject source cohort and the 937-subject strict-QC
subset. ADHD-200 remains optional and is only needed by
`build_extended_library.py`.

## 3. Build the web artifacts

```bash
# Core in-depth bundle: reference fit, 16 curated subjects, meshes, normative model
python pipeline/scripts/build_braintwin.py
#   → braintwin_data.js  + per-subject library (937 strict-QC)  + subject_index

# Decision-support pack (conformal quantiles, continuum, behavior anchors)
python pipeline/scripts/build_dss.py
#   → dss_data.js

# Extended cohort: relaxed-QC (165) + ADHD-200 (155) projected through the strict
# reference; amplitude markers neutralized for ADHD-200; per-subject conditioned added
python pipeline/scripts/build_extended_library.py
#   → extends subject_index + per-subject library to 1257  (and the clinic bundle)
```

## 4. Validation expectations (honesty check)

A faithful rebuild should reproduce, within tolerance:

| Metric | Expected |
|---|---|
| In-depth fMRI **LOSO AUC** | ≈ **0.626** |
| 5-fold CV AUC | ≈ 0.633 |
| Normative (conditioned) LOSO AUC | ≈ 0.637 |
| sMRI-only LOSO AUC | ≈ 0.52 (adds negligibly when fused) |
| Per-site AUC spread | 0.31 – 0.73 across 20 sites |

> If a pooled cross-site AUC comes out **above ~0.78**, treat it as a **site-leakage
> bug**, not a result. The honest number is leave-one-site-out, ≈ 0.626.

The internal model reported as **AUROC 0.91** is a separate, unreleased model; its data
and weights are not in this repo and cannot be reproduced from it.

## 5. Re-sample this public repo

To rebuild the trimmed public tree (40-subject in-depth sample + path rewiring) from a
full research checkout:

```bash
bash tools/assemble.sh
```

Edit the sampling counts in `tools/assemble.sh` (`evenly(strict, 14)` etc.) to change
how many subjects ship.