A reusable, evidence-based playbook of statistical and spatial-analysis lessons for multiplex spatial-proteomics / imaging studies (mIHC, IMC, CODEX, MIBI, t-CyCIF, Vectra/Opal, Xenium-protein) — analysing cell abundance, spatial relationships, niches, and outcome associations on any tissue or disease.
Distilled from a completed multiplex imaging project. All biology is anonymized into transferable methodological rules, each anchored to a published method or benchmark with a DOI.
The core idea, in one paragraph. Most apparent "spatial findings" are abundance, local density, or pseudoreplication in disguise. The playbook's discipline: (1) data hygiene + fix the unit of replication (patient, not cell) first; (2) answer abundance and architecture as separate questions; (3) choose an abundance-normalized metric for the question at hand (NMS, not SpatialScore); (4) prove specificity with a negative control; (5) apply FDR and separate effect size from significance (never compare z across radii); (6) triangulate across metric families (COZI cross-check + an orthogonal method); (7) stratify by site/tissue; (8) for outcome, show it survives abundance adjustment and state the internal-only validity ceiling. The negatives you rule out carry as much weight as the positive you keep.
The playbook is plain Markdown with a portable Agent Skill frontmatter block, so every route below loads the same content. Pick one.
Copy the inner spatial-proteomics-analysis/ folder into your skills directory:
git clone https://github.com/<owner>/spatial-proteomics-analysis
cp -r spatial-proteomics-analysis/spatial-proteomics-analysis ~/.claude/skills/| Runtime | Skills directory |
|---|---|
| Claude Code | ~/.claude/skills/ (or .claude/skills/ in a project) |
| Codex / Copilot CLI / Gemini CLI | ~/.agents/skills/ |
| Project-local, any runtime | .agents/skills/ |
The agent then loads it automatically when a task matches the description in the frontmatter.
AGENTS.md in this repo is a ready-made, agent-neutral entry point — it tells an agent
when to read the playbook and which reference to open for which question.
-
Working inside this repo: nothing to do. Codex, Cursor, Copilot, Gemini, Jules, and Claude Code all pick up
AGENTS.mdautomatically; Claude Code also accepts it asCLAUDE.md. -
Working in another repo: vendor the playbook and point at it from your own instruction file:
git clone --depth 1 https://github.com/<owner>/spatial-proteomics-analysis \ docs/spatial-proteomics-analysis
Then add one line to your
AGENTS.md/CLAUDE.md:For any multiplex spatial-proteomics analysis, follow `docs/spatial-proteomics-analysis/spatial-proteomics-analysis/SKILL.md` before writing analysis code.
Paste or attach spatial-proteomics-analysis/SKILL.md as a
system prompt / project instruction / custom-GPT knowledge file. It stands alone — it tells the
analyst or agent what to do, in what order, and what to avoid.
For a longer session, add references/06_quick_reference.md
(one page) — or attach the whole folder if the tool supports it. Total corpus is well under
40k tokens, so it fits comfortably in a modern context window.
The files are self-contained Markdown with stable headings and relative links. Index the
spatial-proteomics-analysis/ folder directly — no preprocessing needed.
| File | What it is |
|---|---|
SKILL.md |
Start here. The operating procedure — order of operations, metric decision guide, controls, significance discipline, red flags. |
references/00_references.md |
The evidence base — every method/benchmark with DOI + what it grounds (method refs web-verified 2026-06). |
references/01_statistical_lessons.md |
Statistics — pseudoreplication, abundance/density confounding, negative controls, FDR, power, Simpson's paradox, data quality, survival, closing leads. |
references/02_spatial_metrics_guide.md |
Spatial metrics — decision table + per-metric PRINCIPLE / WHEN / PITFALLS (NMS, COZI, CKI, entropy gradient, prevalence/distinctiveness, SpatialScore, Ripley/KAMP, boundary definition, triangulation). |
references/03_data_qc_and_coordinates.md |
Before any metric — label/region provenance, QC exclusion, tissue-edge and FOV-clipping artifacts, coordinate units, scale and origin verification. |
references/04_controls_and_triangulation.md |
Proving a claim — the standard control kit (negative, permutation, density-matched, spillover, cutoff sweep) and the triangulation tiers. |
references/05_compute_and_reproducibility.md |
Running it — environment hygiene, large-data compute, seeds and caps, background-job liveness, "verify before done", persisting knowledge, scout-then-scale. |
references/06_quick_reference.md |
The pre-report card — metric chooser, control kit, pre-claim checklist, red flags in the result and in your reasoning, data-hygiene pre-flight. |
- No identifying information. No tissue, disease, cohort, sample, patient, institution, file path,
or credential from the source project appears anywhere in this repository. Worked examples are
stripped to the methodological content. (Section B of
00_references.mdcites published third-party papers by name, which necessarily includes their own disease context — those are someone else's public findings, not the source cohort's.) - Numbers are illustrations, not results. Where a figure appears (an effect that halves, a q that crosses 0.05, a control that tracks its target) it exists to show the shape of a pitfall. Do not cite, benchmark against, or reuse any number here as a finding.
- Environment-agnostic. The playbook prescribes methodology, not tooling: no assumed language, package manager, operating system, or directory layout.
- Method references (SPIAT, COZI/NEP, KAMP, squidpy, Cellular Neighbourhoods, SpatialScore,
Moran's I) are web-verified with DOIs in
references/00_references.md. Domain/biology benchmarks (Section B) are carried from the source project's literature record — re-verify exact DOIs before formal citation. Note: "COFI" is not a real method — the intended reference is COZI.
MIT — see LICENSE.