slide2vec 6.2.0__tar.gz → 6.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.2.0
+Version: 6.3.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.2
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=5.1.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,7 @@ Requires-Dist: numpy<2; extra == "fm"
 Requires-Dist: pandas; extra == "fm"
 Requires-Dist: pillow; extra == "fm"
 Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.2; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=5.1.0; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "6.2.0"
+version = "6.3.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.2",
+    "hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=5.1.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -100,7 +100,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.2",
+    "hs2p[asap,cucim,openslide,sam2,tifffile,vips]>=5.1.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "6.2.0"
+current_version = "6.3.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

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

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

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

@@ -153,8 +153,10 @@ class PreprocessingConfig:
     #: explicitly (e.g. ``"openslide"``) when a precomputed tissue or annotation mask needs
     #: a different decoder than its slide — hs2p no longer silently falls back to another
     #: reader, so a mask the slide backend cannot decode fails unless overridden here.
-    #: Accepts the same values as :attr:`backend` plus ``"pil"`` for PNG/JPEG masks;
-    #: ``"auto"`` selects PIL for these masks. Ignored for slides with no source mask.
+    #: Accepts the same values as :attr:`backend` plus ``"pil"`` for PNG/JPEG masks and
+    #: ``"tifffile"`` for lossless label reads; ``"auto"`` selects PIL for PNG/JPEG masks
+    #: and ``"tifffile"`` for TIFF masks whose samples are not 8-bit unsigned.
+    #: Ignored for slides with no source mask.
     #: Masks need no spacing metadata, but must align to the slide's field of view and
     #: contain only declared label IDs. See :doc:`preprocessing` for hs2p 5 validation.
     mask_backend: str = "auto"
@@ -179,6 +181,10 @@ class PreprocessingConfig:
     read_tiles_from: Path | None = None
     #: Read and decode tiles on demand rather than pre-loading into memory.
     on_the_fly: bool = True
+    #: Write the extracted tiles to ``tiles/<sample_id>.tiles.tar`` next to the coordinate
+    #: artifacts. Tiles are also written when ``on_the_fly`` is ``False`` and
+    #: ``read_tiles_from`` is unset, because embedding then reads them from the archive.
+    save_tiles: bool = False
     #: Decode tiles on the GPU via CuCIM / nvImageCodec when ``True``.
     gpu_decode: bool = False
     #: Dynamically adjust batch size based on tile count.
@@ -285,6 +291,7 @@ class PreprocessingConfig:
                 Path(read_tiles_from) if read_tiles_from else None
             ),
             on_the_fly=on_the_fly,
+            save_tiles=bool(cfg.save_tiles),
             gpu_decode=gpu_decode,
             adaptive_batching=adaptive_batching,
             use_supertiles=bool(tiling.use_supertiles),
@@ -336,7 +343,8 @@ class ExecutionOptions:
     save_tile_embeddings: bool = False
     #: Persist slide embeddings to disk when running a patient-level model.
     save_slide_embeddings: bool = False
-    #: Persist encoder latent representations when available.
+    #: Return and persist the slide encoder's latent representations (PRISM). Encoders
+    #: without latents ignore it.
     save_latents: bool = False
 
     @classmethod
@@ -622,10 +630,13 @@ class EmbeddedSlide:
     mask_preview_path: Path | None = None
     #: Path to the tiling preview image, if generated.
     tiling_preview_path: Path | None = None
-    #: Encoder latent representations when available; ``None`` otherwise.
+    #: Slide encoder latent representations when ``ExecutionOptions.save_latents`` is set
+    #: and the encoder has them (PRISM: shape ``(512, 1280)``); ``None`` otherwise.
     latents: Any | None = None
     #: Factual square tensor side length immediately before tile encoding.
     encoder_input_size_px: int | None = None
+    #: Record of the image transform applied before tile encoding (JSON data).
+    transform: dict[str, Any] | None = None
 
 
 class Model:
@@ -892,8 +903,8 @@ class Model:
         dense transform, and written to ``dense_embeddings/[<class>/]<sample_id>/<x>_<y>.pt``
         plus a geometry sidecar. The run splits its ROIs across all visible GPUs
         (``execution.num_gpus``); ``num_gpus=1`` encodes fully in-process. Resume is
-        automatic — only ROIs whose sidecar has the same source-spacing declaration and
-        resolved hs2p read plan are skipped. Returns one
+        automatic — only ROIs whose sidecar has the same source-spacing declaration,
+        resolved hs2p read plan and feature identity are skipped. Returns one
         :class:`~slide2vec.artifacts.DenseRegionArtifact` per input ROI.
 
         The effective encoder input — the padded ROI for a whole-tile run, one
@@ -971,8 +982,9 @@ class Model:
         to ``image_embeddings/<sample_id>.pt`` plus a provenance sidecar. The run splits its
         images across all visible GPUs (``execution.num_gpus``); ``num_gpus=1`` encodes
         fully in-process. Resume is automatic — images whose sidecar already exists are
-        skipped. Returns one :class:`~slide2vec.artifacts.ImageEmbeddingArtifact` per input
-        image, in input order.
+        skipped, and a sidecar that records a different feature identity raises. Returns
+        one :class:`~slide2vec.artifacts.ImageEmbeddingArtifact` per input image, in input
+        order.
 
         Unlike the pooled and dense paths there is no geometry to declare: the images are
         heterogeneously sized (2048x1536 beside 96x96) and were never requested, so the

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/artifacts.py

@@ -316,13 +316,15 @@ def _write_dense_grid(
 ) -> np.ndarray:
     """Publish one dense grid: payload atomically, then the sidecar. Returns the array.
 
-    The single write order every dense artifact follows (D6), whatever named it: payload to
-    a temp file in the destination directory → ``os.replace`` into place (atomic on the same
-    filesystem) → then the ``.meta.json`` sidecar. A payload present without its sidecar
-    therefore unambiguously means an incomplete unit, and resume treats the sidecar as the
-    done-marker.
+    The single write order every dense artifact follows (D6), whatever named it: remove any
+    existing sidecar → payload to a temp file in the destination directory → ``os.replace``
+    into place (atomic on the same filesystem) → then the ``.meta.json`` sidecar. A payload
+    present without its sidecar therefore unambiguously means an incomplete unit, and resume
+    treats the sidecar as the done-marker. Removing the old sidecar first keeps a rewrite
+    interrupted between the two writes from pairing it with the new payload.
     """
     grid_array = _ensure_array(grid)
+    metadata_path.unlink(missing_ok=True)
     write_atomically(payload_path, lambda tmp_path: torch.save(_ensure_tensor(grid), tmp_path))
     _write_metadata(metadata_path, metadata)
     return grid_array

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/cli.py

@@ -2,7 +2,7 @@ import argparse
 
 from slide2vec.api import ExecutionOptions, Model, Pipeline, PreprocessingConfig
 from slide2vec.progress import activate_progress_reporter, create_cli_progress_reporter
-from slide2vec.utils.config import setup, hf_login
+from slide2vec.utils.config import setup
 
 
 def get_args_parser(add_help: bool = True):
@@ -24,7 +24,6 @@ def parse_args(argv=None):
 
 def build_model_and_pipeline(args):
     cfg, _cfg_path = setup(args)
-    hf_login()
     model = Model.from_preset(
         cfg.model.name,
         output_variant=cfg.model.output_variant,

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/configs/default.yaml

@@ -26,7 +26,7 @@ tiling:
   read_coordinates_from: # path to an existing directory containing pre-extracted `.coordinates.npz` / `.coordinates.meta.json` artifacts to reuse instead of starting tiling from scratch
   read_tiles_from: # path to an existing directory containing pre-extracted `.tiles.tar` tile stores to reuse instead of starting tiling from scratch
   backend: "auto" # backend to use for slide reading; "auto" tries cucim -> vips -> openslide -> asap. Pin a backend for stable decoder selection across upgrades.
-  mask_backend: "auto" # backend for reading source masks (precomputed tissue / annotation), resolved independently from the mask path; "auto" probes openability like `backend`. Set explicitly (e.g. "openslide") when a mask needs a different decoder than its slide — hs2p (>=4.3.0) no longer silently falls back
+  mask_backend: "auto" # backend for reading source masks (precomputed tissue / annotation), resolved independently from the mask path; "auto" probes openability like `backend`. Set explicitly (e.g. "openslide") when a mask needs a different decoder than its slide — hs2p never silently falls back. "auto" selects "tifffile" for TIFF masks whose samples are not 8-bit unsigned (e.g. 16-bit labels)
   independent_sampling: true # selection strategy when annotation sampling is active. true: sample each class independently against its own binary mask (independent selection); false: sample once over the union of active classes, then post-filter per class by coverage (joint selection). Ignored when the masks vocabulary is left at the tissue-only default.
   masks:
     # Annotation-mask vocabulary forwarded to hs2p's sampling resolver. The shipped default

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/distributed/dense_worker.py

@@ -27,6 +27,7 @@ def get_args_parser(add_help: bool = True):
 def main(argv=None) -> int:
     from slide2vec.progress import emit_progress
     from slide2vec.runtime.dense_shard import run_dense_shard
+    from slide2vec.runtime.feature_identity import dense_feature_identity
     from slide2vec.runtime.dense_stage import (
         region_specs_from_request,
         resolve_output_torch_dtype,
@@ -68,6 +69,7 @@ def main(argv=None) -> int:
             dense=dense,
             batch_size=int(execution.batch_size),
             device=loaded.device,
+            identity=dense_feature_identity(model, dense=dense, execution=execution),
             precision=execution.precision,
             output_dtype=resolve_output_torch_dtype(execution),
             num_workers=execution.resolved_num_workers_per_gpu(),

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/distributed/direct_embed_worker.py

@@ -55,6 +55,7 @@ def main(argv=None) -> int:
         work_unit_shard_stem,
     )
     from slide2vec.runtime.embedding import tiling_result_annotation
+    from slide2vec.runtime.feature_identity import transform_record
 
     load_successful_tiled_slides_fn = getattr(inference, "load_successful_tiled_slides", None)
     if not callable(load_successful_tiled_slides_fn):
@@ -84,6 +85,8 @@ def main(argv=None) -> int:
             shard_stem = work_unit_shard_stem(*decode_work_unit(work_unit))
             slide, tiling_result = paired_by_unit[work_unit]
             loaded = model._load_backend()
+            # The parent writes the sidecar without loading the encoder; hand it the record.
+            transform = transform_record(getattr(loaded, "transforms", None))
             if is_hierarchical_preprocessing(preprocessing):
                 geometry = resolve_hierarchical_geometry(preprocessing, tiling_result)
                 index = build_hierarchical_index(
@@ -113,6 +116,7 @@ def main(argv=None) -> int:
                     "flat_index": torch.as_tensor(shard_indices, dtype=torch.long),
                     "tile_embeddings": tile_embeddings.detach().cpu() if torch.is_tensor(tile_embeddings) else torch.as_tensor(tile_embeddings),
                     "encoder_input_size_px": getattr(loaded, "encoder_input_size_px", None),
+                    "transform": transform,
                 }
                 torch.save(payload, coordination_dir / f"{shard_stem}.hier.rank{global_rank}.pt")
             else:
@@ -140,6 +144,7 @@ def main(argv=None) -> int:
                     "tile_index": torch.as_tensor(tile_indices, dtype=torch.long),
                     "tile_embeddings": tile_embeddings.detach().cpu() if torch.is_tensor(tile_embeddings) else torch.as_tensor(tile_embeddings),
                     "encoder_input_size_px": getattr(loaded, "encoder_input_size_px", None),
+                    "transform": transform,
                 }
                 torch.save(payload, coordination_dir / f"{shard_stem}.tiles.rank{global_rank}.pt")
             return 0
@@ -156,6 +161,7 @@ def main(argv=None) -> int:
                 "slide_embedding": _to_cpu_payload(embedded_slide.slide_embedding),
                 "latents": _to_cpu_payload(embedded_slide.latents),
                 "encoder_input_size_px": embedded_slide.encoder_input_size_px,
+                "transform": embedded_slide.transform,
             }
             # Stem by (sample_id, annotation) so two classes of one slide never overwrite each
             # other; flat units keep the bare-sample_id filename for backward compatibility.

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/distributed/image_worker.py

@@ -26,6 +26,7 @@ def get_args_parser(add_help: bool = True):
 
 def main(argv=None) -> int:
     from slide2vec.progress import emit_progress
+    from slide2vec.runtime.feature_identity import pooled_feature_identity
     from slide2vec.runtime.image_shard import run_image_shard
     from slide2vec.runtime.image_specs import image_specs_from_request
     from slide2vec.runtime.model_settings import resolve_output_precision
@@ -60,6 +61,7 @@ def main(argv=None) -> int:
             out_dir=output_dir,
             batch_size=int(execution.batch_size),
             output_precision=resolve_output_precision(execution.output_dtype, execution.precision),
+            identity=pooled_feature_identity(model, execution=execution),
             output_format=execution.output_format,
             precision=execution.precision,
             num_workers=execution.resolved_image_num_workers_per_gpu(),

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/base.py

@@ -390,6 +390,20 @@ def attentions_tuple_to_grids(
     return torch.cat(grids, dim=1)
 
 
+class ProcessorTransform:
+    """Apply a Hugging Face processor to one image.
+
+    A class rather than a closure so the processor stays readable: the sidecar's
+    transform record is read from it.
+    """
+
+    def __init__(self, processor) -> None:
+        self.processor = processor
+
+    def __call__(self, image) -> Tensor:
+        return self.processor(images=image, return_tensors="pt")["pixel_values"].squeeze(0)
+
+
 class Encoder(ABC):
     """Shared lifecycle contract for all encoders."""
 
@@ -527,6 +541,19 @@ class SlideEncoder(Encoder):
         """Pool tile-level features into a single slide-level embedding."""
         ...
 
+    def encode_slide_with_latents(
+        self,
+        tile_features: Tensor,
+        coordinates: Tensor | None = None,
+        *,
+        tile_size_lv0: int | None = None,
+    ) -> tuple[Tensor, Tensor | None]:
+        """Return the slide embedding and the encoder's latent representations.
+
+        Encoders that have latents (PRISM) override this; the default returns ``None``.
+        """
+        return self.encode_slide(tile_features, coordinates, tile_size_lv0=tile_size_lv0), None
+
 
 class PatientEncoder(Encoder):
     """Base class for encoders that aggregate slide embeddings into patient embeddings."""

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/models/gigapath.py

@@ -93,7 +93,8 @@ class GigaPathSlideEncoder(SlideEncoder):
         # create_model given an "hf_hub:" name force-downloads into ~/.cache/ on every
         # load, ignoring HF_HOME; a local path skips that download.
         checkpoint_path = _slide_checkpoint_path()
-        self._model = create_model(checkpoint_path, "gigapath_slide_enc12l768d", 1536)
+        # create_model returns the module in training mode (dropout and drop-path active).
+        self._model = create_model(checkpoint_path, "gigapath_slide_enc12l768d", 1536).eval()
         self._device = preferred_default_device()
         self._output_variant = resolve_requested_output_variant(output_variant)
 

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/models/isight.py

@@ -84,6 +84,7 @@ from torchvision.transforms import v2
 from transformers import AutoProcessor, CLIPConfig, CLIPModel
 
 from slide2vec.encoders.base import (
+    ProcessorTransform,
     TileEncoder,
     attentions_tuple_to_grids,
     hf_eager_attention,
@@ -190,12 +191,7 @@ class ISight(TileEncoder):
         bicubic resize to 336, a 336 center crop, and OpenAI CLIP
         mean/std — the resize and crop are no-ops on tiles already cut at 336.
         """
-        processor = AutoProcessor.from_pretrained(_BASE_MODEL)
-
-        def transform(image):
-            return processor(images=image, return_tensors="pt")["pixel_values"].squeeze(0)
-
-        return transform
+        return ProcessorTransform(AutoProcessor.from_pretrained(_BASE_MODEL))
 
     def get_normalization_transform(self) -> Callable:
         image_processor = AutoProcessor.from_pretrained(_BASE_MODEL).image_processor

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/models/phikon.py

@@ -10,6 +10,7 @@ from torch import Tensor
 from transformers import AutoImageProcessor, AutoModel
 
 from slide2vec.encoders.base import (
+    ProcessorTransform,
     TileEncoder,
     attentions_tuple_to_grids,
     hf_eager_attention,
@@ -33,13 +34,7 @@ class _PhikonBase(TileEncoder):
         self._output_variant = resolve_requested_output_variant(output_variant)
 
     def get_transform(self) -> Callable:
-        processor = self._processor
-
-        def _transform(img):
-            inputs = processor(images=img, return_tensors="pt")
-            return inputs["pixel_values"].squeeze(0)
-
-        return _transform
+        return ProcessorTransform(self._processor)
 
     def get_normalization_transform(self) -> Callable:
         # Normalization only — no resize/crop.

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/models/prism.py

@@ -44,9 +44,22 @@ class PrismSlideEncoder(SlideEncoder):
         *,
         tile_size_lv0: int | None = None,
     ) -> torch.Tensor:
+        return self._slide_representations(tile_features)["image_embedding"].squeeze(0)
+
+    def encode_slide_with_latents(
+        self,
+        tile_features: torch.Tensor,
+        coordinates: torch.Tensor | None = None,
+        *,
+        tile_size_lv0: int | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        # image_latents: the Perceiver latents, [1, 512, 1280] for one slide.
+        reprs = self._slide_representations(tile_features)
+        return reprs["image_embedding"].squeeze(0), reprs["image_latents"].squeeze(0)
+
+    def _slide_representations(self, tile_features: torch.Tensor) -> dict[str, torch.Tensor]:
         if tile_features.ndim == 2:
             tile_features = tile_features.unsqueeze(0)
         # Stored feature precision can differ from PRISM's weights; CPU has no autocast.
         tile_features = tile_features.to(dtype=self._model.dtype)
-        reprs = self._model.slide_representations(tile_features)
-        return reprs["image_embedding"].squeeze(0)
+        return self._model.slide_representations(tile_features)

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/encoders/registry.py

@@ -247,6 +247,20 @@ def _supports_attention(encoder_cls: type) -> bool:
     )
 
 
+def supports_slide_latents(encoder_name: str) -> bool:
+    """Whether a registered encoder returns latents with its slide embedding.
+
+    Resolved from the class (an override of ``SlideEncoder.encode_slide_with_latents``),
+    so no model is constructed.
+    """
+    encoder_cls = encoder_registry.require(encoder_name)
+    return (
+        issubclass(encoder_cls, SlideEncoder)
+        and encoder_cls.encode_slide_with_latents
+        is not SlideEncoder.encode_slide_with_latents
+    )
+
+
 def _format_names(names: list[str]) -> str:
     if len(names) == 1:
         return names[0]

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/inference.py

@@ -13,6 +13,7 @@ from slide2vec.runtime import (
     embedding,
     embedding_persist,
     embedding_pipeline,
+    feature_identity,
     hierarchical,
     manifest,
     patient_pipeline,
@@ -302,8 +303,7 @@ def embed_slides(
                 zero_tile_pairs,
                 model=model,
                 preprocessing=preprocessing,
-                output_dir=execution.output_dir,
-                output_format=execution.output_format,
+                execution=execution,
             )
             emit_progress("embedding.started", slide_count=len(embeddable_slides))
             if execution.num_gpus > 1 and len(embeddable_slides) > 1:
@@ -433,6 +433,7 @@ def embed_patients(
             f"embed_patients() requires a patient-level model, but '{model.name}' "
             f"has level='{model.level}'. Use embed_slides() for slide-level models."
         )
+    patient_pipeline.reject_per_annotation_sampling(model, preprocessing)
     slide_records = [manifest.coerce_slide_spec(slide) for slide in slides]
     if not slide_records:
         raise ValueError("At least one slide is required")
@@ -611,6 +612,12 @@ def embed_tiles(
     # idempotent, so declaring in both places is intended.
     model._declare_encoder_input(resolved_preprocessing, emit_run_info=False)
     loaded = model._load_backend()
+    compatibility = feature_identity.pooled_feature_identity(
+        model,
+        execution=execution,
+        preprocessing=resolved_preprocessing,
+        transform=feature_identity.transform_record(getattr(loaded, "transforms", None)),
+    )
     hierarchical_mode = hierarchical.is_hierarchical_preprocessing(resolved_preprocessing)
     cpu_budget.log_on_the_fly_worker_override_once(
         resolved_preprocessing,
@@ -638,6 +645,7 @@ def embed_tiles(
                     mask_path=slide.mask_path,
                     backend=tiling.resolve_slide_backend(resolved_preprocessing.backend, tiling_result),
                     preprocessing=resolved_preprocessing,
+                    compatibility=compatibility,
                     encoder_input_size_px=getattr(loaded, "encoder_input_size_px", None),
                 ),
                 annotation=embedding.tiling_result_annotation(tiling_result),
@@ -658,6 +666,7 @@ def embed_tiles(
                 mask_path=slide.mask_path,
                 tile_size_lv0=int(tiling_result.tile_size_lv0),
                 backend=tiling.resolve_slide_backend(resolved_preprocessing.backend, tiling_result),
+                compatibility=compatibility,
                 encoder_input_size_px=getattr(loaded, "encoder_input_size_px", None),
             )
             artifact = embedding.write_tile_embedding_artifact(
@@ -701,20 +710,43 @@ def aggregate_tiles(
         tile_features = load_array(artifact.path)
         if not torch.is_tensor(tile_features):
             tile_features = torch.as_tensor(tile_features)
-        slide_embedding = slide_encode.encode_slide_from_tiles(
-            loaded,
-            tile_features,
-            tiling_result,
-            execution=execution,
-        )
+        if execution.save_latents:
+            slide_embedding, latents = slide_encode.encode_slide_with_latents_from_tiles(
+                loaded,
+                tile_features,
+                tiling_result,
+                execution=execution,
+            )
+        else:
+            slide_embedding = slide_encode.encode_slide_from_tiles(
+                loaded,
+                tile_features,
+                tiling_result,
+                execution=execution,
+            )
+            latents = None
+        # Aggregation encodes no tile: the tile geometry and transform are the ones
+        # recorded with the tile artifact.
+        tile_identity = metadata.get("compatibility") or {}
+        compatibility = {
+            **feature_identity.pooled_feature_identity(model, execution=execution),
+            **{
+                field: tile_identity[field]
+                for field in ("requested_tile_size_px", "encoder_input_size_px", "transform")
+                if field in tile_identity
+            },
+        }
         slide_artifact = embedding.write_slide_embedding_artifact(
             artifact.sample_id,
             slide_embedding,
             execution=execution,
             metadata=embedding.build_slide_embedding_metadata(
-                model, image_path=metadata["image_path"], tiling_result=tiling_result
+                model,
+                image_path=metadata["image_path"],
+                tiling_result=tiling_result,
+                compatibility=compatibility,
             ),
-            latents=None,
+            latents=latents,
         )
         outputs.append(slide_artifact)
     return outputs
@@ -748,9 +780,11 @@ def run_pipeline(
     if not tiling_only and execution.num_gpus > 1:
         distributed_stage.validate_multi_gpu_execution(model, execution)
 
+    resolved_preprocessing = tiling_pipeline.resolve_model_preprocessing(model, preprocessing)
+    if model.level == "patient" and not tiling_only:
+        patient_pipeline.reject_per_annotation_sampling(model, resolved_preprocessing)
     output_dir = Path(execution.output_dir)
     output_dir.mkdir(parents=True, exist_ok=True)
-    resolved_preprocessing = tiling_pipeline.resolve_model_preprocessing(model, preprocessing)
     distributed_stage.write_embedding_request(model, resolved_preprocessing, execution, output_dir)
     emit_progress(
         "run.started",
@@ -801,8 +835,7 @@ def run_pipeline(
             zero_tile_pairs,
             model=model,
             preprocessing=resolved_preprocessing,
-            output_dir=output_dir,
-            output_format=execution.output_format,
+            execution=execution,
         )
         emit_progress("embedding.started", slide_count=len(embeddable_slides))
 
@@ -877,9 +910,14 @@ def run_pipeline(
             persist_tile_embeddings=persist_tile_embeddings,
             persist_hierarchical_embeddings=persist_hierarchical_embeddings,
             include_slide_embeddings=include_slide_embeddings,
-            save_latents=execution.save_latents,
+            save_latents=embedding.should_persist_latents(model, execution),
             resume=resolved_preprocessing.resume,
-            requested_tile_size_px=resolved_preprocessing.requested_tile_size_px,
+            identity=feature_identity.pooled_feature_identity(
+                model, execution=execution, preprocessing=resolved_preprocessing
+            ),
+            resolve_transform=feature_identity.deferred_transform_record(
+                model, on_cpu_copy=False, preprocessing=resolved_preprocessing
+            ),
         )
         skipped_slide_count = len(embeddable_slides) - len(pending_slides)
         if resolved_preprocessing.resume and skipped_slide_count > 0:
@@ -992,8 +1030,7 @@ def run_pipeline_with_coordinates(
             zero_tile_pairs,
             model=model,
             preprocessing=resolved_preprocessing,
-            output_dir=output_dir,
-            output_format=execution.output_format,
+            execution=execution,
         )
         emit_progress("embedding.started", slide_count=len(embeddable_slides))
         if execution.num_gpus > 1:

{slide2vec-6.2.0 → slide2vec-6.3.0}/slide2vec/runtime/artifacts_collect.py

@@ -5,6 +5,7 @@ from typing import Callable, Sequence
 
 import pandas as pd
 from hs2p import SlideSpec
+from hs2p.fileops import read_csv_keyed_by_sample_id
 
 from slide2vec.api import EmbeddedSlide, ExecutionOptions, PreprocessingConfig
 from slide2vec.artifacts import (
@@ -15,8 +16,12 @@ from slide2vec.artifacts import (
 )
 from slide2vec.runtime.distributed_stage import run_distributed_embedding_stage
 from slide2vec.runtime.embedding_persist import persist_embedded_slide
+from slide2vec.runtime.feature_identity import (
+    deferred_transform_record,
+    pooled_feature_identity,
+)
 from slide2vec.runtime.hierarchical import is_hierarchical_preprocessing
-from slide2vec.runtime.embedding import should_persist_tile_embeddings
+from slide2vec.runtime.embedding import should_persist_latents, should_persist_tile_embeddings
 from slide2vec.runtime.persistence import (
     collect_pipeline_artifacts,
     update_process_list_after_embedding,
@@ -73,7 +78,7 @@ def _embeddable_annotation_groups(
     """
     if process_list_path is None or not Path(process_list_path).is_file():
         return {}
-    df = pd.read_csv(process_list_path)
+    df = read_csv_keyed_by_sample_id(process_list_path)
     if "sample_id" not in df.columns:
         return {}
     has_annotation = "annotation" in df.columns
@@ -164,6 +169,7 @@ def collect_distributed_pipeline_artifacts(
     persist_hierarchical_embeddings = is_hierarchical_preprocessing(preprocessing)
     include_slide_embeddings = model.level == "slide"
     include_tile_embeddings = persist_tile_embeddings and not persist_hierarchical_embeddings
+    save_latents = should_persist_latents(model, execution)
     # Every persisted embedding kind can fan out per (sample_id, annotation); the process list
     # (one row per pair after hs2p tiling) is the source of truth for which classes exist.
     annotation_aware = (
@@ -191,9 +197,13 @@ def collect_distributed_pipeline_artifacts(
         persist_tile_embeddings=persist_tile_embeddings,
         persist_hierarchical_embeddings=persist_hierarchical_embeddings,
         include_slide_embeddings=include_slide_embeddings,
-        save_latents=execution.save_latents,
+        save_latents=save_latents,
         resume=preprocessing.resume,
-        requested_tile_size_px=preprocessing.requested_tile_size_px,
+        identity=pooled_feature_identity(model, execution=execution, preprocessing=preprocessing),
+        # This parent never encodes: verify the transform without taking GPU memory.
+        resolve_transform=deferred_transform_record(
+            model, on_cpu_copy=True, preprocessing=preprocessing
+        ),
     )
     pending_annotations = [placeholder.annotation for placeholder in pending_placeholders]
     skipped_slide_count = len(successful_slides) - len(pending_slides)
@@ -228,7 +238,7 @@ def collect_distributed_pipeline_artifacts(
                 persist_tile_embeddings=persist_tile_embeddings,
                 persist_hierarchical_embeddings=persist_hierarchical_embeddings,
                 include_slide_embeddings=include_slide_embeddings,
-                save_latents=execution.save_latents,
+                save_latents=save_latents,
                 annotation=annotation,
             )
             for annotation in sample_annotations