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.

📖 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="paired_2x2")

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}, undefined {ri.undefined_frac:.1%})")
print(f"MaRI  {mari.value:.3f}  (tau={mari.tau:.4f})")
print(f"CRoMa {croma.value:+.3f}  (lower-tail mean {croma.ltm_alpha:+.3f})")

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 undefined_frac next to RI and MaRI. Samples with no informative neighbour in their top k are excluded from the score, so 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 -- paired_2x2 controls what is compared and reports occurrence-level outputs; dataset_wide gives one number over the whole cohort at sample level. Includes the manifest contract and minimal valid examples for each.
• CLI -- the same three metrics from the shell, over a .npy that already exists.
• Benchmarking -- the multi-model pipeline that produced the paper's numbers, split into embed / compute / render steps under scripts/.

Citing

The paper describing MaRI and CRoMa is in preparation. Until it is out, please cite this repository — use the Cite this repository button, or CITATION.cff directly — along with the PathoROB study that introduced the Robustness Index.

License

Apache 2.0