slide2vec 6.3.0__tar.gz → 6.3.2__tar.gz

{slide2vec-6.3.0 → slide2vec-6.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.3.0
+Version: 6.3.2
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0

{slide2vec-6.3.0 → slide2vec-6.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "6.3.0"
+version = "6.3.2"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "6.3.0"
+current_version = "6.3.2"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec/__init__.py

@@ -31,7 +31,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "6.3.0"
+__version__ = "6.3.2"
 
 __all__ = [
     "Model",

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec/api.py

@@ -688,6 +688,44 @@ class Model:
         # Construction fact, not an encode: see _load_backend_without_transform.
         return int(self._load_backend_without_transform().feature_dim)
 
+    def pooled_identity_differences(
+        self,
+        recorded: Mapping[str, Any],
+        *,
+        preprocessing: PreprocessingConfig | None,
+        execution: ExecutionOptions | None = None,
+    ) -> dict[str, tuple[Any, Any]]:
+        """Compare a pooled sidecar's ``compatibility`` block with the current recipe.
+
+        Returns ``{field: (recorded, current)}`` for differing fields held by both
+        identities. Missing fields retain the extraction resume semantics: they
+        cannot be verified and are accepted. The caller owns the policy for an
+        unrecorded identity or a difference.
+
+        Explicitly pass ``preprocessing=None`` for pre-cropped images, whose shipped
+        transform determines geometry. Pass a :class:`PreprocessingConfig` for
+        tiles read from slides; its unset fields resolve as in pooled extraction.
+        ``execution`` defaults to the model's recommended precision and needs no
+        output directory.
+
+        Only a recorded ``transform`` loads weights, on an isolated CPU model.
+        Slide and patient models load their registered tile encoder and tile output
+        variant, without loading aggregation weights. This method does not change
+        this model's input contract or loaded backend, encode pixels, or write files.
+        """
+        from slide2vec.runtime.feature_identity import pooled_identity_differences
+
+        resolved_execution = _coerce_execution_options(execution, model=self)
+        resolved_preprocessing = (
+            None if preprocessing is None else _resolve_direct_api_preprocessing(self, preprocessing)
+        )
+        return pooled_identity_differences(
+            self,
+            dict(recorded),
+            execution=resolved_execution,
+            preprocessing=resolved_preprocessing,
+        )
+
     def prepare_dense_encoder(
         self,
         *,

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec/data/tile_reader.py

@@ -40,31 +40,20 @@ class SuperTileBatchSampler:
 
 
 def _open_wsi_backend(image_path: str, backend: str, gpu_decode: bool):
-    """Open a WSI file with the given backend and return the reader."""
-    if backend == "cucim":
-        from hs2p.wsi.backends.cucim import CuCIMReader
-        return CuCIMReader(image_path, gpu_decode=gpu_decode)
-    elif backend == "openslide":
-        from hs2p.wsi.backends.openslide import OpenSlideReader
-        return OpenSlideReader(image_path)
-    elif backend == "vips":
-        from hs2p.wsi.backends.vips import VIPSReader
-        return VIPSReader(image_path)
-    elif backend == "asap":
-        from hs2p.wsi.backends.asap import ASAPReader
-        with suppress_c_stderr():
-            return ASAPReader(image_path)
-    else:
-        raise ValueError(
-            f"Unknown backend: {backend!r}. "
-            "Choose from: cucim, openslide, vips, asap"
-        )
+    """Open a slide with the backend tiling resolved for it and return the reader.
 
+    hs2p's ``open_slide`` knows every backend tiling can resolve, ``pil`` for flat
+    PNG/JPEG slides included. Reads address pyramid levels and level-0 pixels only, so a
+    slide without spacing metadata opens without it.
+    """
+    from hs2p.wsi.reader import open_slide
 
-class WSITileReader:
-    """Random-access tile reader for WSI files supporting four backends.
+    with suppress_c_stderr() if backend == "asap" else nullcontext():
+        return open_slide(image_path, backend, gpu_decode=gpu_decode, require_spacing=False)
 
-    Backends: ``"cucim"`` (default), ``"openslide"``, ``"vips"``, ``"asap"``.
+
+class WSITileReader:
+    """Random-access tile reader over any slide backend hs2p can open.
 
     When ``use_supertiles=True``, tiles are grouped into 8×8/4×4/2×2 blocks so
     that one region read covers multiple tiles.  ``num_cucim_workers`` and

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec/runtime/feature_identity.py

@@ -136,6 +136,42 @@ def differing_fields(
     }
 
 
+def pooled_identity_differences(
+    model,
+    recorded: dict[str, Any],
+    *,
+    execution,
+    preprocessing=None,
+) -> dict[str, tuple[Any, Any]]:
+    """Compare a recorded pooled identity with the resolved current request."""
+
+    def resolve_transform() -> dict[str, Any]:
+        from slide2vec.api import Model
+
+        encoder_name, output_variant = model.name, model._output_variant
+        if model.level != "tile":
+            info = encoder_registry.info(model.name)
+            encoder_name = info["tile_encoder"]
+            output_variant = info["tile_encoder_output_variant"]
+        source = Model.from_preset(
+            encoder_name,
+            device="cpu",
+            output_variant=output_variant,
+            allow_non_recommended_settings=model.allow_non_recommended_settings,
+        )
+        if preprocessing is None:
+            source._declare_given_encoder_input(emit_run_info=False)
+        else:
+            source._declare_encoder_input(preprocessing, emit_run_info=False)
+        return transform_record(source._load_backend().transforms)
+
+    return differing_fields(
+        recorded,
+        pooled_feature_identity(model, execution=execution, preprocessing=preprocessing),
+        resolve_transform=resolve_transform,
+    )
+
+
 class PooledResumeCheck:
     """Compare the completed pooled artifacts of one resume with the run's feature identity.
 

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.3.0
+Version: 6.3.2
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0

{slide2vec-6.3.0 → slide2vec-6.3.2}/slide2vec.egg-info/SOURCES.txt

@@ -160,6 +160,7 @@ tests/test_patient_manifest.py
 tests/test_phaet.py
 tests/test_pooled_encoder_input.py
 tests/test_pooled_geometry.py
+tests/test_pooled_identity_api.py
 tests/test_prism.py
 tests/test_prism2.py
 tests/test_process_list_performance.py

{slide2vec-6.3.0 → slide2vec-6.3.2}/tests/test_hs2p5_integration.py

@@ -90,6 +90,34 @@ def test_tile_archive_is_written_when_requested_or_not_reading_on_the_fly(
         assert Path(pd.read_csv(process_list).iloc[0]["tiles_tar_path"]) == archive_path
 
 
+@pytest.mark.parametrize("use_supertiles", [True, False], ids=["supertiles", "single-tiles"])
+def test_flat_slide_tiles_are_read_on_the_fly_with_the_backend_tiling_resolved(
+    tmp_path, use_supertiles
+):
+    from slide2vec.data.tile_reader import OnTheFlyBatchTileCollator
+
+    slide = _flat_slide(tmp_path, np.ones((32, 32), dtype=np.uint8))
+    pixels = np.random.default_rng(0).integers(0, 256, (128, 128, 3), dtype=np.uint8)
+    Image.fromarray(pixels).save(slide.image_path)
+
+    _, (result,), _ = prepare_tiled_slides(
+        [slide], _preprocessing(), output_dir=tmp_path / "out", num_workers=1
+    )
+    collator = OnTheFlyBatchTileCollator(
+        image_path=slide.image_path,
+        tiling_result=result,
+        backend=result.backend,
+        use_supertiles=use_supertiles,
+    )
+    indices, tiles, _ = collator(list(range(len(result.x))))
+
+    assert result.backend == "pil"
+    assert tiles.shape == (16, 3, 32, 32)
+    for index, tile in zip(indices.tolist(), tiles):
+        x, y = int(result.x[index]), int(result.y[index])
+        np.testing.assert_array_equal(tile.permute(1, 2, 0).numpy(), pixels[y : y + 32, x : x + 32])
+
+
 @pytest.mark.parametrize("output_mode", ["per_annotation", "merged"])
 def test_spacingless_annotation_mask_groups_values_and_preserves_bag_identity(tmp_path, output_mode):
     labels = np.full((32, 32), 2, dtype=np.uint8)

slide2vec-6.3.2/tests/test_pooled_identity_api.py

@@ -0,0 +1,283 @@
+"""The public comparison of recorded pooled identities with the current extraction recipe.
+
+Failure modes: wrong metadata differences, eager or GPU model loading, using the
+wrong input regime or tile dependency, changing the caller's model, and requiring
+artifact writes for a metadata comparison. Expected differences are literal records.
+"""
+
+import pytest
+import torch
+from PIL import Image
+from torchvision.transforms import v2
+
+from slide2vec import ExecutionOptions, ImageSpec, Model, PreprocessingConfig
+from slide2vec.encoders import PatientEncoder, SlideEncoder, TileEncoder, encoder_registry, register_encoder
+
+TILE_ENCODER = "identity-api-tile"
+SHIPPED_TRANSFORM = {
+    "normalize": {"mean": [0.5, 0.5, 0.5], "std": [0.5, 0.5, 0.5]},
+    "resize": {"size": [40], "interpolation": "bicubic"},
+    "center_crop": {"size": [32, 32]},
+}
+OLD_TRANSFORM = {
+    "normalize": {"mean": [0.25, 0.5, 0.5], "std": [0.5, 0.5, 0.5]},
+    "resize": {"size": [40], "interpolation": "bicubic"},
+    "center_crop": {"size": [32, 32]},
+}
+NORMALIZATION_ONLY = {
+    "normalize": {"mean": [0.5, 0.5, 0.5], "std": [0.5, 0.5, 0.5]},
+    "resize": None,
+    "center_crop": None,
+}
+ALTERNATE_NORMALIZATION = {
+    "normalize": {"mean": [0.25, 0.5, 0.5], "std": [0.5, 0.5, 0.5]},
+    "resize": None,
+    "center_crop": None,
+}
+
+
+@pytest.fixture
+def tile_encoder(monkeypatch):
+    """A weight-free provider with known transforms and observable device selection."""
+    monkeypatch.setattr(encoder_registry, "_entries", dict(encoder_registry._entries))
+
+    @register_encoder(
+        TILE_ENCODER,
+        output_variants={"default": {"encode_dim": 3}, "alternate": {"encode_dim": 3}},
+        default_output_variant="default",
+        input_size=32,
+        supports_variable_input_size=True,
+        supported_spacing_um=[0.5],
+        default_spacing_um=0.5,
+        precision="fp16",
+    )
+    class TestTileEncoder(TileEncoder):
+        variants = []
+        devices = []
+        encoded_images = 0
+
+        def __init__(self, *, output_variant=None, allow_non_recommended_settings=False):
+            self._device = torch.device("cpu")
+            self.output_variant = output_variant or "default"
+            type(self).variants.append(self.output_variant)
+
+        @property
+        def encode_dim(self):
+            return 3
+
+        @property
+        def device(self):
+            return self._device
+
+        def to(self, device):
+            self._device = torch.device(device)
+            type(self).devices.append(str(self._device))
+            return self
+
+        def get_normalization_transform(self):
+            mean = [0.25, 0.5, 0.5] if self.output_variant == "alternate" else [0.5, 0.5, 0.5]
+            return v2.Compose([
+                v2.ToImage(),
+                v2.ToDtype(torch.float32, scale=True),
+                v2.Normalize(mean=mean, std=[0.5, 0.5, 0.5]),
+            ])
+
+        def get_transform(self):
+            return v2.Compose([
+                v2.Resize(40, interpolation=v2.InterpolationMode.BICUBIC),
+                v2.CenterCrop(32),
+                self.get_normalization_transform(),
+            ])
+
+        def encode_tiles(self, batch):
+            type(self).encoded_images += int(batch.shape[0])
+            return batch.mean(dim=(-1, -2))
+
+    return TestTileEncoder
+
+
+@pytest.fixture
+def aggregate_encoders(tile_encoder):
+    class AggregationLifecycle:
+        def __init__(self, **kwargs):
+            raise AssertionError("Identity comparison must not load aggregation weights")
+
+        @property
+        def encode_dim(self):
+            return 3
+
+        @property
+        def device(self):
+            return torch.device("cpu")
+
+        def to(self, device):
+            return self
+
+        def encode_slide(self, tile_features, coordinates=None, *, tile_size_lv0=None):
+            return tile_features.mean(dim=0)
+
+    class TestSlideEncoder(AggregationLifecycle, SlideEncoder):
+        pass
+
+    class TestPatientEncoder(AggregationLifecycle, PatientEncoder):
+        def encode_patient(self, slide_embeddings):
+            return slide_embeddings.mean(dim=0)
+
+    names = {"slide": "identity-api-slide", "patient": "identity-api-patient"}
+    for level, cls in (("slide", TestSlideEncoder), ("patient", TestPatientEncoder)):
+        register_encoder(
+            names[level],
+            level=level,
+            tile_encoder=TILE_ENCODER,
+            tile_encoder_output_variant="alternate",
+            output_variants={"default": {"encode_dim": 3}},
+            default_output_variant="default",
+            supported_spacing_um=[0.5],
+            default_spacing_um=0.5,
+            precision="fp32",
+        )(cls)
+    return names
+
+
+def test_pooled_identity_comparison_reports_recorded_and_current_metadata():
+    model = Model.from_preset("virchow2", device="cuda")
+    recorded = {
+        "encoder_name": "older-encoder",
+        "output_variant": "cls",
+        "precision": "bf16",
+        "feature_dtype": "fp16",
+        "older_field": "accepted",
+    }
+
+    differences = model.pooled_identity_differences(
+        recorded,
+        preprocessing=None,
+        execution=ExecutionOptions(precision="fp32", output_dtype="fp32", num_gpus=1),
+    )
+
+    assert differences == {
+        "encoder_name": ("older-encoder", "virchow2"),
+        "output_variant": ("cls", "cls_patch_mean"),
+        "precision": ("bf16", "fp32"),
+        "feature_dtype": ("fp16", "fp32"),
+    }
+
+
+def test_pooled_identity_comparison_reads_the_shipped_transform_on_cpu(tile_encoder):
+    model = Model.from_preset(TILE_ENCODER, device="cuda")
+
+    differences = model.pooled_identity_differences(
+        {"transform": OLD_TRANSFORM},
+        preprocessing=None,
+        execution=ExecutionOptions(precision="fp32", num_gpus=1),
+    )
+
+    assert differences == {"transform": (OLD_TRANSFORM, SHIPPED_TRANSFORM)}
+    assert tile_encoder.devices == ["cpu"]
+    assert tile_encoder.encoded_images == 0
+
+
+def test_pooled_identity_comparison_reads_the_declared_transform(tile_encoder):
+    differences = Model.from_preset(TILE_ENCODER).pooled_identity_differences(
+        {"transform": SHIPPED_TRANSFORM},
+        preprocessing=PreprocessingConfig(requested_tile_size_px=32, requested_spacing_um=0.5),
+        execution=ExecutionOptions(precision="fp32", num_gpus=1),
+    )
+
+    assert differences == {"transform": (SHIPPED_TRANSFORM, NORMALIZATION_ONLY)}
+
+
+@pytest.mark.parametrize("level", ["slide", "patient"])
+def test_pooled_identity_comparison_uses_the_registered_tile_dependency(
+    tile_encoder, aggregate_encoders, level
+):
+    model = Model.from_preset(aggregate_encoders[level], device="cuda")
+
+    differences = model.pooled_identity_differences(
+        {"tile_encoder_output_variant": "default", "transform": NORMALIZATION_ONLY},
+        preprocessing=PreprocessingConfig(requested_tile_size_px=32, requested_spacing_um=0.5),
+        execution=ExecutionOptions(precision="fp32", num_gpus=1),
+    )
+
+    assert differences == {
+        "tile_encoder_output_variant": ("default", "alternate"),
+        "transform": (NORMALIZATION_ONLY, ALTERNATE_NORMALIZATION),
+    }
+    assert tile_encoder.variants == ["alternate"]
+    assert tile_encoder.devices == ["cpu"]
+
+
+def test_pooled_identity_comparison_accepts_missing_fields_without_loading_weights(tile_encoder):
+    differences = Model.from_preset(TILE_ENCODER, device="cuda").pooled_identity_differences(
+        {},
+        preprocessing=None,
+        execution=ExecutionOptions(precision="fp32", num_gpus=1),
+    )
+
+    assert differences == {}
+    assert tile_encoder.variants == []
+    assert tile_encoder.devices == []
+
+
+@pytest.mark.parametrize("execution", [None, ExecutionOptions(num_gpus=1)])
+def test_pooled_identity_comparison_resolves_the_extraction_precision_default(tile_encoder, execution):
+    differences = Model.from_preset(TILE_ENCODER).pooled_identity_differences(
+        {"precision": "fp32", "feature_dtype": "fp32"},
+        preprocessing=None,
+        execution=execution,
+    )
+
+    assert differences == {"precision": ("fp32", "fp16"), "feature_dtype": ("fp32", "fp16")}
+    assert tile_encoder.variants == []
+
+
+def test_pooled_identity_comparison_resolves_hierarchical_geometry(tile_encoder):
+    differences = Model.from_preset(TILE_ENCODER).pooled_identity_differences(
+        {
+            "requested_tile_size_px": 64,
+            "encoder_input_size_px": 64,
+            "region_tile_multiple": 3,
+            "requested_region_size_px": 96,
+        },
+        preprocessing=PreprocessingConfig(region_tile_multiple=2),
+        execution=ExecutionOptions(precision="fp32", num_gpus=1),
+    )
+
+    assert differences == {
+        "requested_tile_size_px": (64, 32),
+        "encoder_input_size_px": (64, 32),
+        "region_tile_multiple": (3, 2),
+        "requested_region_size_px": (96, 64),
+    }
+
+
+def test_pooled_identity_comparison_preserves_a_model_used_for_image_extraction(tmp_path, tile_encoder):
+    image_path = tmp_path / "image.png"
+    Image.new("RGB", (48, 48), color=(255, 255, 255)).save(image_path)
+    model = Model.from_preset(TILE_ENCODER, device="cpu")
+    execution = ExecutionOptions(
+        output_dir=tmp_path / "artifacts",
+        precision="fp32",
+        num_gpus=1,
+        num_workers_per_gpu=0,
+    )
+    (artifact,) = model.embed_images([ImageSpec(sample_id="first", image_path=image_path)], execution=execution)
+    sidecar_before = artifact.metadata_path.read_bytes()
+
+    differences = model.pooled_identity_differences(
+        artifact.metadata["compatibility"],
+        preprocessing=PreprocessingConfig(requested_tile_size_px=32, requested_spacing_um=0.5),
+        execution=execution,
+    )
+
+    assert differences == {"transform": (SHIPPED_TRANSFORM, NORMALIZATION_ONLY)}
+    assert tile_encoder.encoded_images == 1
+    assert artifact.metadata_path.read_bytes() == sidecar_before
+
+    (next_artifact,) = model.embed_images([ImageSpec(sample_id="second", image_path=image_path)], execution=execution)
+
+    # One original backend and one comparison copy; extraction reuses the original.
+    assert tile_encoder.variants == ["default", "default"]
+    assert tile_encoder.encoded_images == 2
+    assert next_artifact.metadata["compatibility"]["transform"] == SHIPPED_TRANSFORM
+    assert torch.equal(torch.load(next_artifact.path, weights_only=True), torch.tensor([1.0, 1.0, 1.0]))