# REPRODUCIBILITY.md — Regenerating This Project Conversationally, No Code Required This document is a set of **prompt templates**, one per pipeline stage, that let a judge, reviewer, or another lab reproduce this project by talking to Claude (or an equivalent code-executing LLM agent) directly — copy a prompt, run it, check the output against what's in `t-cell-project-compiled/data/results/` and `docs/manuscript.md`, then move to the next stage. No pre-written script is required; the agent writes and runs the code live in response to each prompt, the same way this project was actually built. Each stage below states: **what to paste**, **what tools/access the agent needs**, **what to expect back**, and **how to sanity-check it** against this repository's own saved outputs. > Use these prompts *in order* — later stages depend on files produced by earlier ones (either freshly regenerated, or pulled from `data/` in this repo if you want to skip straight to a later stage). --- ## Stage 0 — Environment check **Prompt:** > "I'm reproducing a computational biology pipeline. Confirm you can reach: (1) NCBI GEO for public transcriptomics data, (2) anonymous S3 access to `s3://genome-scale-tcell-perturb-seq/marson2025_data/`, (3) the Open Targets Platform GraphQL API, (4) the STRING API. Then confirm you have pandas, numpy, scipy, and statsmodels available." **Expect:** a short confirmation of reachability for each, or an explicit note of what's blocked (in a sandboxed agent, some of these may require an explicit network-allowlist approval — that's normal, just approve it). --- ## Stage 1 — Curate disease-state and treatment-reversal signatures **Prompt (repeat once per disease — this is the exact instruction that drove Stage 1 originally):** > "Find a public GEO dataset comparing active [DISEASE] patients to healthy controls in blood or CD4+ T cells (a 'disease-state' signature), and a second GEO dataset with matched pre/post-treatment samples from patients who responded to an effective [DISEASE] therapy (a 'treatment-reversal' signature). Prefer CD4+ T-cell or PBMC tissue over other tissue, and a genuinely paired pre/post design over a cross-sectional responder-vs-non-responder comparison. Download the series matrix, confirm sample groups from the actual metadata (don't take the GEO title at face value), and run a differential expression test (Welch's t-test for the disease-state comparison, paired t-test for the reversal comparison) to produce a gene-level table of log2FC, p-value, and BH-adjusted FDR." Run this for: **RA, Psoriasis, MS** (original 3) and **T1D, IBD, Lupus/SLE, Celiac disease** (cross-validation extension). **What actually happened when this ran:** several first-choice datasets failed the "genuinely paired" check on inspection (GSE58795, GSE12051, GSE20690 for RA all turned out to be cross-sectional once the raw metadata was read) and had to be discarded — expect the agent to try 2-4 candidate accessions per disease before landing on a usable one. The RA and T1D reversal signatures both ended up as documented compromises (synovial tissue instead of blood for RA; responder-vs-non-responder instead of a true paired design for T1D) — this is normal, not a bug, and should be reported as a caveat rather than hidden. **Sanity-check against this repo:** `t-cell-project-compiled/data/signatures/*.csv` and `t-cell-project-compiled/data/signatures/crossvalidation/*.csv` — 14 files total, one per disease-state/reversal combination for 7 diseases. `t-cell-project-compiled/data/signatures/crossvalidation/crossval_disease_data_quality.csv` records the strong/moderate/weak quality call per new disease. --- ## Stage 2 — Extract the genome-scale Perturb-seq knockdown screen **Prompt:** > "Download `GWCD4i.DE_stats.h5ad` from `s3://genome-scale-tcell-perturb-seq/marson2025_data/` (anonymous access, ~16.8 GB) — this is a genome-scale CRISPRi knockdown screen in primary human CD4+ T cells. It has layers for log_fc, p_value, adj_p_value, baseMean, lfcSE, and zscore, one row per (knockdown gene, culture condition) combination. Restrict to the `Stim48hr` culture condition only, and extract a compact matrix of log2FC / p-value / adj-p-value for every knockdown gene x every measured gene. Save this as a checkpoint (not the full raw file) so it doesn't need to be re-downloaded." **Expect:** a compact `.npz` file (~900 MB) with the knockdown x measured-gene matrices — this is `t-cell-project-compiled/data/perturbseq_checkpoints/perturbseq_Stim48hr_de_matrices.npz` in this repo (excluded from git due to size; see `README.md` for how to get it back). A standard `boto3.download_file()` call may hang or time out on a file this large — a chunked range-request downloader was needed originally; if the agent's first download attempt stalls, ask it to retry with byte-range chunking. **Sanity-check:** matrix shape should be **11,281 knockdown genes × 10,282 measured genes** for the Stim48hr condition. --- ## Stage 3 — CMap-style reversal scoring **Prompt:** > "For each disease, take the top 150 most up-regulated and top 150 most down-regulated genes from its treatment-reversal signature (restricted to genes also measured in the Perturb-seq data). For every one of the 11,281 knockdowns, compute a weighted running-sum enrichment score (GSEA/Subramanian-style) of how strongly that knockdown's own differential expression pattern is enriched for genes moving in the *reverse* direction of disease — i.e., does knocking down this gene push the transcriptome toward the treated/healthy state? Build an empirical null by permuting gene labels across a random subsample of ~2,000 knockdowns, 100 times, pooled across permutations, and use it to compute two-sided empirical p-values. Apply Benjamini-Hochberg FDR correction genome-wide (per disease, across all 11,281 tests)." **Expect:** one reversal-score table per disease with columns `gene, reversal_score, p_value, fdr`. Original run: **RA 1,713/11,281 genes FDR<0.1; Psoriasis 7/11,281; MS 1,181/11,281** — the sparse psoriasis result is a real finding (small reversal cohort), not an error, and shapes how "consensus" gets interpreted downstream. **Sanity-check:** `t-cell-project-compiled/data/results/stage3_reversal_scores_{RA,Psoriasis,MS}.csv`. --- ## Stage 4 — Cross-disease consensus ranking **Prompt:** > "Merge the three per-disease reversal-score tables. For each gene, count how many diseases it reaches FDR<0.1 in. Report the counts: how many genes are significant in at least 1 disease, at least 2, and all 3." **Expect:** **2,663 genes at FDR<0.1 in ≥1 disease; 238 in ≥2 diseases; 0 in all 3** (explain the zero — it follows directly from the sparse psoriasis signal in Stage 3, not from an error). **Sanity-check:** `t-cell-project-compiled/data/results/stage4_cross_disease_consensus.csv`. --- ## Stage 5 — Six-filter plausibility cascade **Prompt:** > "Starting from the 238-gene cross-disease consensus pool (≥2 diseases), apply six sequential filters and report the surviving count after each: (1) expression plausibility — the gene's own baseline expression in CD4+ T cells (from the Perturb-seq baseMean) must be above the 10th percentile across all measured genes; (2) effect-size robustness — flag (don't exclude) genes whose |log2FC| in their best disease is below 0.3; (3) consensus strength — require significance in ≥2 diseases (already applied, restate the count); (4) network support — query the STRING API for direct interactions (score≥400) between each candidate and a curated list of ~160 known autoimmune GWAS genes; (5) novelty — flag candidates that ARE themselves on that GWAS gene list as 'non-novel'; (6) threshold sensitivity — rerun Stage 3's scoring with reversal gene-set sizes of 100, 150, and 200 genes and confirm the direction of effect doesn't flip." **Expect:** Filter 1 → 2,009 pass; Filter 2 → 105 flagged robust (not excluded); Filter 3 → 177 candidates; Filter 4 → 34/177 have direct STRING support; Filter 5 → 171/177 novel, 6 non-novel; Filter 6 → 177/177 (100%) sign-stable. **Sanity-check:** `t-cell-project-compiled/data/results/stage5_full_filtered_candidates.csv`, `stage5_filter4_network_support.csv`, `stage5_filter6_threshold_sensitivity.csv`. --- ## Stage 6 — Druggability / targetability annotation **Prompt:** > "For the top 40 candidates (ranked by reversal score, consensus, and Stage 5 filter results), query the Open Targets Platform GraphQL API for known drugs, protein class, and small-molecule/antibody tractability data. Classify each as DIRECTLY TARGETABLE (has an approved drug or high-tractability pocket), INDIRECTLY TARGETABLE (druggable protein family, no approved drug yet), or CHALLENGING (no tractability evidence)." **Expect:** **7 directly targetable, 8 indirectly targetable, 25 challenging** out of the top 40. **Sanity-check:** `t-cell-project-compiled/data/results/stage6_druggability_summary.csv`, `t-cell-project-compiled/data/results/MASTER_ranked_candidate_table.csv` (the full 40-row, 18-column master table). --- ## Stage 7 — Cross-disease validation (the 4-disease extension) **Prompt:** > "Take the same top-40 candidate gene list. Re-score each of them (same weighted-enrichment method, same pooled permutation null, but now applying FDR correction across only these 40 genes per disease rather than genome-wide) against the 4 new disease reversal signatures curated in Stage 1 (T1D, IBD, Lupus, Celiac). Then build a full gene × disease hit matrix (40 genes × 7 diseases total) with reversal score, FDR, and significance per cell. Classify each gene by breadth: UNIVERSAL REGULATOR if significant (FDR<0.1) in 4+ of the 7 diseases; MULTI-DISEASE REGULATOR if significant in 2-3; DISEASE-SPECIFIC if significant in only 1. Separately, cluster the 40 genes by STRING protein-interaction score (≥400) and flag any gene as PATHWAY-LEVEL SIGNAL if it clusters with 2 or more OTHER genes from the top 40 that are each individually significant in a DIFFERENT disease (this is a stricter bar than simply having ≥1 connected neighbor — verify the count carefully, this criterion was gotten wrong on a first pass in the original run and had to be corrected)." **Expect:** T1D 4/40 significant, IBD 13/40, Lupus 0/40, Celiac 6/40 at the 40-gene scale. Breadth classification: **2 UNIVERSAL REGULATORS (TET2, KAT6B), 38 MULTI-DISEASE REGULATORS, 0 DISEASE-SPECIFIC**. Pathway-level flag (under the corrected ≥2-other-genes rule): only a 6-member TCR-proximal cluster (ITK, VAV1, CD52, CD33, ARHGAP30, TBC1D10C) qualifies. **Sanity-check:** `t-cell-project-compiled/data/results/crossvalidation/crossvalidation_hit_matrix.csv`, `gene_classification_breadth.csv`. --- ## Stage 8 — Single-molecule multi-disease targeting assessment **Prompt:** > "For each UNIVERSAL REGULATOR from Stage 7, assess feasibility as a single-molecule multi-disease drug target: (1) mechanism — is there a plausible shared biological reason it would matter across its significant diseases, and is the direction of effect consistent across them (same sign of reversal score) or inconsistent (which would undercut a single-mechanism story)? (2) existing precedent — search for any published mouse-model or clinical evidence connecting this gene (or a close paralog) to any of its significant diseases independently of this screen; (3) safety — cross-check the gene's known human safety liabilities (search the literature directly; do not rely solely on the CD4+-T-cell expression-based proxy used earlier in the pipeline, since that proxy has a specific known blind spot for genes essential in other cell lineages)." **Expect (from the original run):** TET2 formally qualifies as universal but is **NOT RECOMMENDED** — direction of effect is actually inconsistent across its 4 significant diseases, and independently, TET2 loss-of-function carries a well-documented clonal hematopoiesis (CHIP) risk invisible to the CD4+-T-cell expression safety proxy. KAT6B is the standout: no T-cell literature of its own, but its paralog KAT6A has independently published causal evidence protecting against EAE (MS model) and colitis (IBD model) in mice, and a dual KAT6A/B inhibitor (PF-07248144) already has Phase 1 human safety data from an oncology program and is in Phase 3 trials (KATSIS-1, NCT07062965) for a different indication. **Sanity-check:** `t-cell-project-compiled/data/results/crossvalidation/single_molecule_targeting_assessment.csv`. **Verify any specific trial ID, paper title, or safety claim independently via a live search before repeating it** — do not take a prior run's claim as settled without re-checking, the same way the original run's claims were independently re-verified by an auditor pass before being finalized. --- ## Stage 9 — Compile the unified report **Prompt:** > "Merge the discovery-phase report and the cross-validation-phase report into one document: an executive summary, a methods section covering both phases in full formula/parameter detail, a results section per phase, a standalone 'most surprising finding' section, and one merged validation/caveats section covering both phases (make sure it explicitly notes the CD4+-T-cell-expression safety-proxy blind spot found in Stage 8). Draw a schematic pipeline architecture diagram showing all stages from disease curation through the final single-molecule targeting assessment. Render the whole thing to Markdown, HTML (with figures embedded), and PDF." **Sanity-check:** `docs/manuscript.md` / `.html` / `.pdf`, `t-cell-project-compiled/figures/pipeline_architecture_diagram.png`. --- ## What "reproduced" means here — and what to expect to differ Every quoted number above is the **exact result from the original run**, preserved so you have a ground truth to check against. Because Stage 1 involves an agent independently searching GEO and making judgment calls about dataset quality, and because the permutation null in Stage 3 has a random seed, expect **exact GEO accession choices and precise p-values to vary slightly run to run** — the qualitative conclusions (which genes are top candidates, the T1D/IBD/Lupus/Celiac data-quality pattern, the TET2/KAT6B universal-regulator result, the KAT6B repurposing story) should reproduce consistently. If a re-run lands on a materially different top candidate, that is itself worth investigating rather than dismissing — treat any discrepancy from the numbers quoted above as a signal to check both runs' underlying data, not as an automatic sign the new run is wrong.