0.3.0

This release expands the published robustness panel from 21 to 26 encoders and rebuilds the
documentation site around the per-sample CRoMa distribution. Five new tile-encoder families
(Mascaret, Phaet and the three-member RudolfV 2 teacher/student family) were extracted across
PathoROB and republished with auditable provenance, a fifth whole-slide encoder joined the slide
panel, and the croma console script that 0.1.0 and 0.2.0 installed is gone — the library is used
through its Python API.

Removed

• BREAKING: the croma console script. It was a thin argparse wrapper over the same API
  functions, and nothing internal depended on it. src/croma/cli.py, its documentation page and its
  [project.scripts] entry point are removed. Every subcommand has a direct replacement:
  croma ri / croma mari / croma croma are RI.compute / MaRI.compute / CRoMa.compute,
  croma expand-embeddings is croma.expand_features_to_manifest, and
  croma build-embedding-manifest is croma.alignment.build_embedding_source_manifest. The one
  thing the CLI did for you is loading the .npy — call numpy.load yourself. (#144)

Added

• Mascaret and Phaet as tile encoders, served through one shared Waiv backend at immutable
  checkpoint revisions with the released 224 px preprocessing and checkpoint-native output
  normalization. (#135)
• The RudolfV 2 family — teacher plus two distilled students — at immutable revisions, with a
  shared native-square backend that pools CLS with the mean of the patch tokens after excluding all
  eight register tokens. (#136)
• PRISM2, a fifth whole-slide encoder. It tops both slide benchmarks, making the two
  PRISM-family encoders the only biology-dominant slide models, and shows essentially no downstream
  degradation. With five encoders the shared median-k no longer collapses, so the slide panel's
  k* exception is now justified by composition sensitivity rather than by n = 4. (#144)
• --image-path-map for extraction: an access-only mapping that preserves canonical manifest
  identity and resolves a mirror only when embeddings actually need computing. (#138)
• A :results-value: role in the docs. Run-derived numbers in prose are now computed from
  committed results/ at build time, and an unknown function, model or column fails the
  warnings-as-errors build. It immediately caught three drifted hand-typed numbers. (#142)

Changed

• The public panel is now 25 pathology encoders plus the DINOv2-B control, recomputed end to end
  on Camelyon, TCGA-4×4 and Tolkach-ESCA under the sparse shared-median-k protocol. For the
  original 21 models every comparable numeric field moved exactly zero. TCGA-2×2 stays local and
  supplementary. (#139, #141)
• Downstream nIPD validation covers the five new encoders, under the unchanged 20-repeat
  protocol and frozen splits. All 36 expanded-panel tile correlations stay positive and significant;
  no sign or significance-threshold changes. (#140)
• Each cohort cell in the aggregate table now reads CRoMa/LTM₁₀ rather than the margin alone,
  so the table shows the two axes its own caption ranks on. Every published value is unchanged — the
  CSV only gains columns. (#125)
• The documentation site is consolidated around the distribution explorer, redesigned as
  master–detail: an always-visible overview of all 26 encoders above a detail view with a range
  brush and a compare-with overlay. The three cohort pages fold into one results page with stable
  anchors, and the static ridgeline figures are retired — the explorer is the overview now. (#142)
• Model tables, exposure markers and family styling are driven from machine-readable provenance,
  including parent/fine-tune and teacher/student relationships and a conservative Charité/CHA
  exposure caveat. (#137)
• Embedding publication is crash-safe and identity-checked. Matrices and provenance sidecars are
  one artifact contract; resume validates checkpoint revision, extraction contract, precision,
  manifest, batch size, dtype and shape; and provenance is folded into the embedding fingerprint so
  a metric cache cannot reuse a stale matrix. An interrupted extraction can no longer be mistaken
  for a complete one. (#134)

Fixed

• RI and MaRI tail statistics reached the aggregate CSV as NaN. The benchmark computed finite
  per-sample median_value, q_alpha and ltm_alpha but dropped them when serializing summaries
  and reading cached payloads. (#139)
• The explorer's range brush never worked — pointerdown triggered a full re-render, destroying
  the SVG that held the pointer capture, so every drag collapsed to a single-bin click. (#142)
• Package-only releases no longer fail CI. A test required the committed results provenance to
  name the currently installed version, which compares historical producer metadata against the
  current runtime. The artifact-list and checksum guarantees are unchanged. (#123)

0.2.0

This release makes croma’s robustness reporting more complete and reproducible, adding canonical F(0), nIPD, public benchmark results, and tracked paper-reproduction tooling. It also tightens several core interfaces, so existing users should review the breaking migrations below.

Added

• CRoMaResult.f0 now provides the canonical confounder-dominant fraction F(0), using the closed <= 0 boundary over defined evaluation units. It is also exposed as f0 in CLI JSON and croma_f0 in benchmark and m-sweep outputs. (#119)
• The documentation now publishes auditable results for twenty pathology foundation models and one natural-image control across three PathoROB cohorts, including provenance, per-cohort distributions, an interactive tail explorer, and dark-mode-correct figures. The aggregate table is ordered by the mean of its visible CRoMa and tail ranks while retaining both axes and the Pareto frontier. (#112, #121)
• Paper-reproduction generators and their tests are now tracked under scripts/repro/ and aligned with the current group_id, all, and closed-boundary F(0) contracts. Upstream APD metadata correctly retains its source slide_id join key while generated croma manifests use group_id. (#120)

Breaking changes

• croma.napd has been removed without an alias and replaced by croma.nipd. nIPD normalizes degradation by above-chance baseline performance and integrates over finite, strictly increasing Cramér’s-V coordinates spanning 0 to 1; it is a different estimand rather than a drop-in rename. PathoROB APD is unchanged. (#113)
• Canonical manifests must now provide a non-empty group_id instead of slide_id. There is no compatibility alias: rename existing manifest columns and re-run scoring, because the group participates in alignment, fingerprints, and score-cache keys. Existing embedding matrices remain reusable. (#117)
• The dataset_wide evaluation design is now named all, with no alias, and all is the new default for every public Python and CLI metric entry point. Calls that relied on the former paired_2x2 default must now request evaluation_design="paired_2x2" explicitly; cached artifacts using the old design name are recomputed. (#118)

0.1.0

First public release of croma, a lean library of robustness metrics for pathology foundation models.

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

Metric	Name	What it does
RI	Robustness Index	Counts favourable vs. unfavourable neighbours
MaRI	Margin-aware Robustness Index	Weights that same evidence by feature distance
CRoMa	Cross-confounder Robustness Margin	A signed margin, with tail-aware reporting

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. Also ships croma.downstream — the confounder-biased probe protocol and its two reductions, APD and nAPD.

pip install croma

The core package depends only on numpy, pandas, scikit-learn and tqdm, and never loads a model or reads an image — you bring the embeddings.

📖 Documentation · full detail in CHANGELOG.md

The paper describing MaRI and CRoMa is in preparation; until it is out, please cite this repository together with the PathoROB study.