Multi-slide pooled fit_stain_reference

[timtreis]

fit_stain_reference now accepts image_key: str | list[str] — a list pools several images' tissue pixels into one fit (one reference for a cohort in one SpatialData).

ref = sq.experimental.im.fit_stain_reference(sdata, ["s1", "s2"], method="macenko")

tissue_mask_key takes an order-matched list (or None for the {key}_tissue convention). Single-image fit unchanged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.23%. Comparing base (b71dae1) to head (483b124).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1209      +/-   ##
==========================================
+ Coverage   77.11%   77.23%   +0.11%     
==========================================
  Files          63       63              
  Lines        9418     9466      +48     
  Branches     1585     1597      +12     
==========================================
+ Hits         7263     7311      +48     
  Misses       1554     1554              
  Partials      601      601              

Files with missing lines	Coverage Δ
...c/squidpy/experimental/im/_stain/_decomposition.py	92.18% <100.00%> (+0.31%)	⬆️
src/squidpy/experimental/im/_stain/_normalize.py	94.96% <100.00%> (+1.21%)	⬆️
src/squidpy/experimental/im/_stain/_reinhard.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[selmanozleyen]

can these tests be merged into a parameterized one?

[timtreis]

Folded into two parametrized tests: test_pooled_fit (runs + pool-of-one == single, exact except vahadane where NMF is not bit-reproducible even seeded) and test_validation (all raise cases as one table). test_order_matched_non_convention_masks stays separate since it asserts values, not an exception.

[selmanozleyen]

Can't we use _unique_order_preserving here somehow?

[timtreis]

Done — duplicate check now goes through _unique_order_preserving.

[selmanozleyen]

There are lines duplicated here:

You should normalize to [str] if it's str. Then you'd do this procedure for free on both

   das, masks = [], []
    for k, mk in zip(image_keys, mask_keys, strict=True):
        da = _resolve_image(sdata, k, scale, prefer="coarsest")
        validate_rgb_range(da)
        das.append(da)
        masks.append(_resolve_tissue_bool_mask(sdata, k, da, mk))
    dtypes = {str(da.dtype) for da in das}
    if len(dtypes) != 1:
        raise ValueError(f"pooled images must share a dtype; got {sorted(dtypes)}.")

    if method == "reinhard":
        return fit_reinhard_pooled(das, masks, params, image_keys)
    bg = default_white_point(das[0]) if white_point is None else np.asarray(white_point, np.float64)
    reference = RUIFROK_HE if canonical_reference is None else dict(canonical_reference)
    return fit_decomposition_pooled(
        das, masks, image_keys, method, params, bg, reference=reference, max_angle_deg=max_angle_deg
    )

I'd also do

def fit_reinhard_pooled(
    das: list[xr.DataArray],
    masks: list[np.ndarray | None],
    params: ReinhardParams,
    image_keys: list[str | None],
) -> StainReference:
    """Fit Reinhard stats from the pooled tissue Lab pixels of one or more slides."""
    cols = [_tissue_lab_pixels(da, params, m, image_key=k) for da, m, k in zip(das, masks, image_keys, strict=True)]
    return _reinhard_from_pixels(np.concatenate(cols, axis=1))


def fit_reinhard(
    image_rgb: xr.DataArray, params: ReinhardParams, *, tissue_mask: np.ndarray | None = None
) -> StainReference:
    """Single-image Reinhard fit — a pool of one."""
    return fit_reinhard_pooled([image_rgb], [tissue_mask], params, [None])

or just have fit_reainhard(str|list[str]) tbh

[timtreis]

Done in 3a026a5 — image_key/tissue_mask_key are normalised to lists at the top of fit_stain_reference, one pipeline for both; _fit_pooled and both *_pooled functions are gone. fit_reinhard/fit_decomposition take one image or a sequence (pool of one), per your sketch with _tissue_lab_pixels.

[selmanozleyen]

please do the changes I mentioned. Overall writing the code as if all the inputs are [str] is a good idea and normalizing str to [str] will save duplicate computation and code

[selmanozleyen]

I like to first assess this before going on with the experimental functions: #1279.

It's about the design and the structure. I can look into this PR meanwhile separately but I'd prefer to do after