croma

croma measures how much a pathology foundation model's representation is driven by biology rather than by non-biological technical variation -- staining, scanning, tissue preparation -- across centers.

RI was introduced in the PathoROB study. croma provides a clean re-implementation of it, adds MaRI as its margin-aware extension, and introduces CRoMa, which overcomes limitations of both. MaRI and CRoMa are described in A distributional robustness margin for pathology foundation models.

For downstream shortcut-susceptibility experiments, croma also provides the confounder-biased probe protocol, PathoROB's APD reduction, and normalized integrated performance degradation (nIPD). nIPD expresses degradation relative to the above-chance baseline performance available to lose and integrates it over Cramér's V. See the downstream API.

📖 Documentation

Install

pip install croma

The core package depends only on numpy, pandas, scikit-learn and tqdm. It never loads a model or reads an image -- you bring the embeddings. Add the paper-reproduction utilities with pip install "croma[repro]".

Quickstart

You need a manifest CSV with one row per sample, and an embeddings array of shape (N, D) whose row i is the embedding of manifest row i. Don't normalize them -- croma L2-normalizes internally and compares neighbours by cosine distance.

import numpy as np
import pandas as pd
from croma import CRoMa, MaRI, RI

manifest = pd.read_csv("manifest.csv")
features = np.load("embeddings.npy")

common = dict(confounder_column="center")  # evaluation_design defaults to "all"

ri = RI.compute(features, manifest, k_candidates=[5, 11, 21], **common)
mari = MaRI.compute(features, manifest, k_candidates=[5, 11, 21], **common)
croma = CRoMa.compute(features, manifest, **common)

print(f"RI    {ri.value:.3f}  (k={ri.k}, support {ri.support:.1%})")
print(f"MaRI  {mari.value:.3f}  (tau={mari.tau:.4f}, support {mari.support:.1%})")
print(f"CRoMa {croma.value:+.3f}  (lower-tail mean {croma.ltm_alpha:+.3f})")

Results

Twenty-six encoders — twenty-five pathology foundation models and one natural-image control (†) — scored on three tile cohorts from PathoROB.

Top 8 of 26 ranked pathology encoders, over 3 tile cohorts; the DINOv2-B control is shown unranked in the full table. The CRoMa and tail ranks are the means of that encoder's within-cohort ranks — by median CRoMa, and by tail severity LTM₁₀ — and the mean rank averages those two. It orders the table; it does not replace them, because a strong median can hide a brittle tail and only the two columns show that — which is why each cohort shows both, median CRoMa/LTM₁₀. Bold marks the Pareto frontier: the encoders no other pathology encoder beats on both axes at once. ‡ PathoROB RI on these cohorts was used during the encoder's development, e.g. in checkpoint selection, as disclosed by its authors. Ranks are shown unadjusted.

📊 Full panel, per-cohort detail and the distributions

Reading the numbers

RI and MaRI live in [0, 1]; above 0.5, biological evidence outweighs confounder evidence. CRoMa lives in (-1, 1) and is neutral at 0, positive when biology dominates.

Three habits will keep you out of trouble:

1. Always read support next to RI and MaRI. It is the fraction of evaluation units with informative neighbours inside k: manifest samples under all, or subset occurrences under paired_2x2. A high RI over a thin support is not a strong result.
2. Never pin tau. It defaults to None, which resolves it per model on the scale of that model's own neighbour distances. One fixed tau shared across models sharpens the margin for some and flattens it for others -- exactly the distortion MaRI exists to remove. See Choosing tau.
3. Read the tail, not just the mean. croma.ltm_alpha is the mean of the worst 10% of samples. Pooled scores hide brittle subgroups.

Also in the docs

• Evaluation designs -- all, the default, scores every manifest row together and gives one number over the whole cohort at sample level; paired_2x2 controls what is compared and reports occurrence-level outputs. Includes the manifest contract and minimal valid examples for each.
• Benchmarking -- the multi-model pipeline that produced the paper's numbers, split into embed / compute / render steps under scripts/.

Citing

If you use MaRI or CRoMa, please cite the paper — and the PathoROB study that introduced the Robustness Index these build on.

@article{grisi2026distributional,
  title   = {A distributional robustness margin for pathology foundation models},
  author  = {Grisi, Cl{\'e}ment and van der Laak, Jeroen and Litjens, Geert},
  journal = {arXiv preprint arXiv:2607.25497},
  year    = {2026},
  doi     = {10.48550/arXiv.2607.25497},
  url     = {https://arxiv.org/abs/2607.25497}
}

To cite the software itself rather than the method, use CITATION.cff directly; GitHub's Cite this repository button resolves to the paper above.

License

Apache 2.0