PANDA — reproducibility recipe

panda/               model + losses + panda/markers.yaml
scripts/pan_skin/    skin pipeline: download -> corpus -> train -> CV -> zero-shot
scripts/pancreas/    pancreas pipeline (same shape)
scripts/hematopoiesis/  HSC pipeline (same shape)
scripts/common/      system-agnostic train / CV / zero-shot drivers
scripts/analysis/    downstream discovery + interpretability
scripts/figures/     paper + supplement figure builders
data/corpus/{sys}/   downloaded + harmonized data
data/raw/            per-dataset raw counts (not in git)
checkpoints/{sys}/{variant}/panda_final.pt
discovery/{sys}/{variant}/*.json,*.csv    all quantitative artefacts
figures/             fig1_..fig6, PANDA_supplement.pdf, biology/*.pdf

1. Requirements

• Python: 3.9+ (project is tested on 3.10).
• CUDA: PyTorch 2.6.0 wheels — CUDA 12.1/12.4 runtime works.
• GPU: any single CUDA GPU works — the trainer is single-device (batch 256, a compact MLP; a consumer GPU trains a checkpoint in well under an hour).
• Disk: ~400 GB (raw GEO tars + harmonized corpora + checkpoints).
• RAM: ~64 GB (the pancreas HVG builder peaks near ~40 GB).

torch==2.6.0             scanpy==1.11.5           anndata>=0.11.4
harmonypy==0.2.0         numpy>=1.24,<3.0         scipy>=1.10
scikit-learn>=1.2        pandas>=1.5              matplotlib>=3.7
seaborn>=0.12            umap-learn>=0.5          pyyaml>=6.0
tqdm>=4.65               leidenalg>=0.10          pynndescent>=0.5
scikit-misc>=0.5

Repository root resolution (PANDA_ROOT)

1.1 LD_LIBRARY_PATH prefix (required for every PyTorch invocation)

2. Data acquisition

Pan-skin (6 studies, 45,387 cells)

Pan-hematopoietic (3 studies used in the paper, 192,833 cells)

Pan-pancreatic (6 studies, 120,611 cells)

3. Corpus build (per system)

Pan-skin

Pan-hematopoietic

Pan-pancreatic

4. Training

5. Held-out 5-fold cross-validation (Table 1)

• scripts/common/run_cv.py — canonical, 5 epochs per fold, matches paper numbers (mean acc / F1 / AUROC + per-class report).
• scripts/common/cv_holdout.py — same architecture but supports GroupKFold by dataset and a fuller 6-8 epoch curriculum; slower.

Multi-seed rigor

Correction (2026-08): older cv_5fold_seed{1,2}.json files in the repo history were produced on different corpus builds (different cell counts and label vocabularies) by cv_holdout.py with a different curriculum; the "33/35 fold-comparisons" claim previously derived from them was invalid and has been withdrawn. The seeds committed now are regenerated with the commands above on the canonical corpora (verified same n/K per configuration). Honest result: Marker beats PCA on 34/45 fold-comparisons — pancreas 15/15 (+0.04 acc every seed), skin 11/15 (gap ≤0.003), hematopoiesis 8/15 (parity).

6. Held-out labeled zero-shot targets (Section 5)

7. Discovery analyses

7.1 Section 5 (held-out labeled) marker deep-dives

7.2 Section 6 — Dingwall En1-cKO (skin)

7.3 Section 7 — Dahlin Kit-mutant (hematopoiesis)

7.4 Section 7.4 — Veres held-out (pancreas)

7.5 Section 8 — cross-system prototype geometry + interpretability

8. Figures + supplement

Main-text figures (figures/fig{1,2,3,4}_*.pdf)

Supplement (figures/PANDA_supplement.pdf)

Biology deep-dive supplement pages

9. PDF build

10. End-to-end make target

11. Trouble-shooting

• libcusparseLt.so.0: cannot open shared object file — you forgot to export LD_LIBRARY_PATH before Python started. The pip-installed nvidia-cusparselt-cu12 provides the library; PyTorch does not add its path to the loader search. See section 1.1.
• GLIBCXX_3.4.30 not found — your system libstdc++ is too old; prepend a newer libstdc++.so.6's directory to LD_LIBRARY_PATH.
• Dingwall GSM -> genotype mapping (frequent bug source): the correct map is WT = {GSM6833478, GSM6833479, GSM6833480, GSM6833481}, cKO = {GSM6833482, GSM6833483}. GSM6833480/481 are rttaControl (Cre-negative WT), not cKO. Getting this wrong flips every En1-cKO enrichment sign.
• Pancreas HVG builder OOM — scripts/pancreas/03_shared_hvgs_and_pca.py peaks near 40 GB RAM on the 6-study union. Run on a node with >= 64 GB.
• data/raw not in git — it is git-ignored (14+ GB of GEO tars). Rerun section 2 to repopulate.
• stratified split failure on rare classes — small-support classes (< 2 members per fold) are merged into the parent canonical_label. If a fold still errors, check that corpus.h5ad's canonical_label column has the expected vocabulary; the paper vocab is the union enumerated in PAPER.tex Sec 3.
• n_conditions mismatch — PANDAEncoder reads it from len(datasets) in the checkpoint; regenerate the checkpoint if you have added/removed a dataset.
• ContrastiveSampler in 1-condition data — auto-disabled when there is only one condition; no config change needed.
• DataParallel batch-size — default bs=256 is calibrated for 4x A100 40 GB. Drop to bs=64 for a single GPU or you will OOM inside the sub-center prototype attention.
• Embeddings not persisted — after training writes the checkpoint, the 128-d projection is re-computed on demand in every downstream analysis; if you want it cached, re-save the AnnData explicitly via adata.write_h5ad().
• Sulic is NOT held out of the standard corpus — all 4,683 Sulic cells (including the 4,183-cell held_out_labeled slice) are inside data/corpus/pan_skin/harmonized/corpus.h5ad. Scoring the standard checkpoints on the Sulic slice is a train-set evaluation. Use scripts/pan_skin/92_retrain_with_sulic_anchor.py (500-cell anchor corpus, artefacts 97_sulic_anchor_*) for the honest number, as the paper now does.
• Corpus rebuild from raw GEO data is currently not possible from this repo — the per-dataset loader modules (panda/data/*_loaders.py) that 06_build_per_dataset_h5ads.py / 02_build_per_dataset.py import were never committed (only stale v2 copies exist under archive/). Everything from training onward is reproducible from the harmonized corpora on the Hugging Face mirror; re-deriving the corpora from GEO requires reconstructing the loaders.

12. Artefact index (from PAPER.tex Section 11)

• Model checkpoints: checkpoints/{system}/{variant}/panda_final.pt
• Marker gene lists: panda/markers.yaml
• Corpus builders: scripts/{pan_skin,hematopoiesis,pancreas}/
• Unified trainer: scripts/common/train_panda.py
• Unified 5-fold CV: scripts/common/run_cv.py (or cv_holdout.py)
• Zero-shot driver: scripts/common/run_all_zero_shot.py
• External label supplements: data/external_labels/{dingwall_supp,haensel,joost2016,mca,mia,byrnes,yu,baccin,melanocyte_anchor}/
• CV outputs: discovery/{system}/{variant}/cv_5fold{,_seed1,_seed2}.json
• Zero-shot summaries:
  • discovery/pancreas/{pca,marker}/baron_summary.json
  • discovery/pancreas/{pca,marker}/veres_summary.json
  • discovery/hematopoiesis/{pca,marker}/nestorowa_summary.json
  • discovery/pan_skin/{pca,marker}/sulic_summary.json
  • discovery/pan_skin/{pca,marker}/belote_summary.json
• Adult-beta panel: discovery/pancreas/marker/95_adult_beta_validation.json
• Pathway modules: discovery/{system}/marker/57_pathway_class_by_module_{padj,delta}.tsv
• Dingwall EDEN validation: Line A discovery/pan_skin/marker/98_eden_summary.json; Line B data/processed/dingwall_replica/dingwall_replica.h5ad, replica_cluster_20_qc.json, replica_marker_matches.csv; Line C discovery/pan_skin/marker/104_dingwall_derm_summary.json + prediction CSVs.
• Primary EDEN (Derm2): discovery/pan_skin/marker/100_primary_eden_discovery.csv, 100_primary_eden_summary.json, 101_derm_identity_summary.json, 101_derm_subcluster_scores.csv.
• Dingwall other: discovery/pan_skin/marker/57_pathway_analysis.csv, 90_dingwall_marker_deep_dive.csv.
• Dahlin Kit-mutant: discovery/hematopoiesis/marker/92_dahlin_marker_deep_dive.csv, dahlin_summary.json.
• Veres deep-dive: discovery/pancreas/marker/91_veres_marker_deep_dive.csv.

Data mirror

• data/corpus/{pan_skin,hematopoiesis,pancreas}/harmonized/ — training corpora
• data/external_labels/ — paper-supplement label files
• checkpoints/{pan_skin,hematopoiesis,pancreas}/marker/ — trained weights

• data/raw/ — GEO downloads (regenerable from scripts/*/03_download*.sh)
• data/corpus/tier{1,2,3}/ — pretraining tier data
• data/processed/ — intermediate build artefacts