CORAL

Mahmood Lab’s spatial-proteomics pipeline — raw multiplexed slide to cell types, spatial neighbourhoods and outcome models — whose real contribution is making the foundation-model encoder a swappable component, so six of them can be compared on identical preprocessing.

Purpose

Verdict: not adoptable here — this department has no multiplexed imaging to run it on — but three of its design decisions are worth stealing, and its benchmark table is worth reading carefully.

CORAL consumes CODEX and PhenoCycler data; nothing in sources/projects/ or wiki/datasets/ records a multiplex platform, and Cross-Stain Registration mentions multiplex only to say it is a different technique. Without that data the toolkit has nothing to act on. What is transferable is described below and under Methods.

What it does

Five resumable stages, each a CLI command: ingest (standardise a multiplexed slide and normalise its marker names) → tissue (separate tissue from background, via a DeepLabV3 DAPI segmenter or Otsu) → cell (Cellpose) → patch (a regular grid, or one tile centred on each cell) → extract (encode every tile with a chosen encoder). Downstream: phenotype cells from their marker profiles, cluster patches into spatial neighbourhoods without labels, or aggregate to slide level for outcome models.

The choice that makes it interesting is that the encoder is a swappable component. KRONOS2, KRONOS1, Eva, CA-MAE, UNI and a raw mean-marker baseline all sit behind one --extractor flag, running on identical preprocessing. That makes CORAL a benchmarking harness as much as a pipeline — and publishing the harness alongside the numbers is a better standard than most model papers here manage. ### What is worth watching

The engineering is careful and several decisions are ones this group has faced or will face. Details under Methods. The short version: an editable marker map as a single source of truth with a loud guardrail, OME-Zarr with QuPath-editable GeoJSON masks, and resumable per-stage state. Those are reusable as ideas — a design is not a dependency, and none of them requires running CORAL at all.

Data used

None of the group’s. The tutorials run on a public classical Hodgkin lymphoma CODEX slide.

Supported inputs: CODEX / PhenoCycler, as OME-TIFF, plain multi-page TIFF, or one-TIFF-per-channel folders (Keyence / Fusion exports). Announced as “coming soon”: Xenium, Visium, Visium HD, MIBI, IMC, CyCIF, and AnnData / Scanpy / Squidpy export.

The README publishes a benchmark table comparing eight patch encoders on five tasks. Two things about it are worth recording before anyone quotes it.

It is a self-benchmark. CORAL is Mahmood Lab’s toolkit, KRONOS2 is Mahmood Lab’s model, the processing is standardised by the toolkit, and KRONOS2 wins every one of the five columns. That is not an accusation — standardised comparison is exactly what the toolkit is for, and publishing the harness is better than publishing numbers alone. It does mean the table is not independent evidence.

Read down the columns and the story is more specific than “KRONOS2 wins”. On the three cell phenotyping tasks, the naive mean-marker baseline — literally averaging marker intensities — scores 0.702 / 0.737 / 0.790 against KRONOS2’s 0.720 / 0.742 / 0.796. Under two balanced-accuracy points, on every one. On the survival task the gap is large (C-index 0.694 versus 0.535). So the foundation model’s advantage on this evidence is at the slide and patient level, not at the cell level, where a simple intensity summary is nearly as good.

That survival result carries its own caveat: n = 80. A C-index and a 3-year AUC on eighty patients have confidence intervals wide enough to accommodate most of the table — see Concordance Index.

Methods

Read at source level, not from the README. The pipeline is ingest → tissue → cell → patch → extract, then phenotyping or neighbourhood clustering. Four findings.

The marker map is the interesting design decision. A multiplex slide’s channels arrive with whatever names the operator typed, and a panel-agnostic model needs canonical marker identities. CORAL writes an editable marker_map.csv, treats it as the single source of truth, and runs enforce_marker_map at the start of every stage, so an edit takes effect with no separate apply step. The guardrail is deliberately strict: a blank or invalid mapping is a hard error naming the offending rows, and if a map change invalidates a stage that already ran, the user is warned rather than having the output silently discarded. A canonical registry of 287 markers ships as registry_v1.csv with compartment and family annotations. Unrecognised names are tokenised for review rather than dropped.

That whole mechanism is the answer to a problem this wiki has not written down: an H&E encoder takes three fixed channels, and a spatial-proteomics encoder takes N arbitrary named channels, so the channel vocabulary becomes part of the model interface. See Spatial Proteomics.

Masks are handed to QuPath, not locked in. Tissue segmentation writes tissue.geojson described as “hand-editable in QuPath”, alongside a rasterised mask and a review overlay. The whole store is OME-Zarr, chosen explicitly for parallel chunked I/O, robustness against partial writes, and portability to “any OME-NGFF–aware tool (including QuPath and napari)”. This is the same GeoJSON-as-interchange pattern QuPath Annotation Workflow already documents, arrived at independently.

The vendoring is documented better than most published code. src/coral/tissue/_carta/NOTICE lists every file copied verbatim, every file copied with edits, what each edit removed, and what was deliberately not vendored. It is the clearest provenance record I have read in a research repository, and it is the model to copy if the group ever vendors someone else’s model.

Resumability is real, not aspirational. Per-slide state.json records each stage’s status, timestamps and output paths; re-running skips completed work and .lock files protect in-flight tasks.

Current state / open questions

• Licensing, in one line and deliberately not pursued (AGENTS.md §8): CC BY-NC-ND, which sits oddly beside a README inviting pull requests and a launch post calling it open-source. For whenever licensing is dealt with properly.
• Does the group have, or want, any multiplexed imaging at all? Nothing in this wiki records a CODEX, PhenoCycler, MIBI or IMC platform, and that is the precondition for everything here.
• KRONOS2 is released ahead of its documentation: the technical report is “coming soon” and the README’s citation points at the KRONOS1 preprint (arXiv:2506.03373, June 2025). So the model being recommended has no paper, and the paper being cited describes a different model. [unverified] — worth re-checking once the report appears.
• Would the marker-map guardrail pattern transfer to the group’s own IHC work, where channel naming is also inconsistent? The problem shape is similar even though the modality is not.

How it connects

Spatial Proteomics — the modality this exists to serve, and where the marker-vocabulary argument is written up properly; this repository is its worked example.

Foundation Models in Pathology — the same idea one modality across: a frozen pretrained encoder turning tiles into features. What changes is the input, and that change is larger than it looks.

QuPath Annotation Workflow — CORAL exports tissue boundaries as GeoJSON for hand correction in QuPath, which is the same interchange decision this group already made independently.

Concordance Index — the README’s survival column is a C-index on 80 patients, which is the exact setting where that page warns the statistic is unstable.

PinkKidney — the group’s own encoder comparison, and the closest local analogue to CORAL’s benchmark table: same question, H&E instead of multiplex, and the same difficulty separating encoder quality from everything else in the pipeline.

MultiSurv — the other external repository here that is paper-companion code rather than a maintained tool; CORAL is much better engineered but sits in the same category, and the same question applies to both — take the ideas, not the dependency.

Derived from: repository cloned 2026-07-27 at dd0f861 (full clone, two commits); README.md read in full; LICENSE, pyproject.toml, src/coral/markers/guardrail.py, markers/data/registry_v1.csv, markers/kronos1_markers.py, tissue/_carta/LICENSE and tissue/_carta/NOTICE read directly. Hugging Face metadata for MahmoodLab/KRONOS2 and MahmoodLab/KRONOS read via the Hub API on 2026-07-27 (both gated; model cards not readable). arXiv:2506.03373 abstract read. Repository metadata read from github.com 2026-07-27. Launch announcement text supplied by Serdar in chat, because LinkedIn blocks automated fetching.