kaiko-eva 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

eva/core/trainers/trainer.py

@@ -3,11 +3,14 @@
 import os
 from typing import Any
 
+import loguru
 from lightning.pytorch import loggers as pl_loggers
 from lightning.pytorch import trainer as pl_trainer
 from lightning.pytorch.utilities import argparse
+from lightning_fabric.utilities import cloud_io
 from typing_extensions import override
 
+from eva.core import loggers as eva_loggers
 from eva.core.data import datamodules
 from eva.core.models import modules
 from eva.core.trainers import _logging, functional
@@ -65,13 +68,23 @@ class Trainer(pl_trainer.Trainer):
             subdirectory: Whether to append a subdirectory to the output log.
         """
         self._log_dir = os.path.join(self.default_root_dir, self._session_id, subdirectory)
-        os.fspath(self._log_dir)
 
-        for logger in self.loggers:
-            if isinstance(logger, (pl_loggers.CSVLogger, pl_loggers.TensorBoardLogger)):
-                logger._root_dir = self.default_root_dir
-                logger._name = self._session_id
-                logger._version = subdirectory
+        enabled_loggers = []
+        if isinstance(self.loggers, list) and len(self.loggers) > 0:
+            for logger in self.loggers:
+                if isinstance(logger, (pl_loggers.CSVLogger, pl_loggers.TensorBoardLogger)):
+                    if not cloud_io._is_local_file_protocol(self.default_root_dir):
+                        loguru.logger.warning(
+                            f"Skipped {type(logger).__name__} as remote storage is not supported."
+                        )
+                        continue
+                    else:
+                        logger._root_dir = self.default_root_dir
+                        logger._name = self._session_id
+                        logger._version = subdirectory
+                enabled_loggers.append(logger)
+
+        self._loggers = enabled_loggers or [eva_loggers.DummyLogger(self._log_dir)]
 
     def run_evaluation_session(
         self,
@@ -94,4 +107,5 @@ class Trainer(pl_trainer.Trainer):
             base_model=model,
             datamodule=datamodule,
             n_runs=self._n_runs,
+            verbose=self._n_runs > 1,
         )

eva/core/utils/__init__.py

@@ -1 +1,7 @@
 """Utilities and library level helper functionalities."""
+
+from eva.core.utils.clone import clone
+from eva.core.utils.memory import to_cpu
+from eva.core.utils.operations import numeric_sort
+
+__all__ = ["clone", "to_cpu", "numeric_sort"]

eva/core/utils/clone.py

@@ -0,0 +1,27 @@
+"""Clone related functions."""
+
+import functools
+from typing import Any, Dict, List
+
+import torch
+
+
+@functools.singledispatch
+def clone(tensor_type: Any) -> Any:
+    """Clone tensor objects."""
+    raise TypeError(f"Unsupported input type: {type(input)}.")
+
+
+@clone.register
+def _(tensor: torch.Tensor) -> torch.Tensor:
+    return tensor.clone()
+
+
+@clone.register
+def _(tensors: list) -> List[torch.Tensor]:
+    return list(map(clone, tensors))
+
+
+@clone.register
+def _(tensors: dict) -> Dict[str, torch.Tensor]:
+    return {key: clone(tensors[key]) for key in tensors}

eva/core/utils/memory.py

@@ -0,0 +1,28 @@
+"""Memory related functions."""
+
+import functools
+from typing import Any, Dict, List
+
+import torch
+
+
+@functools.singledispatch
+def to_cpu(tensor_type: Any) -> Any:
+    """Moves tensor objects to `cpu`."""
+    raise TypeError(f"Unsupported input type: {type(tensor_type)}.")
+
+
+@to_cpu.register
+def _(tensor: torch.Tensor) -> torch.Tensor:
+    detached_tensor = tensor.detach()
+    return detached_tensor.cpu()
+
+
+@to_cpu.register
+def _(tensors: list) -> List[torch.Tensor]:
+    return list(map(to_cpu, tensors))
+
+
+@to_cpu.register
+def _(tensors: dict) -> Dict[str, torch.Tensor]:
+    return {key: to_cpu(tensors[key]) for key in tensors}

eva/core/utils/operations.py

@@ -0,0 +1,26 @@
+"""Functional operations."""
+
+import re
+from typing import Iterable, List
+
+
+def numeric_sort(item: Iterable[str], /) -> List[str]:
+    """Sorts an iterable of strings treating embedded numbers as numeric values.
+
+    Here the strings are compared based on their numeric value rather than their
+    string representation.
+
+    Args:
+        item: An iterable of strings to be sorted.
+
+    Returns:
+        A list of strings sorted based on their numeric values.
+    """
+    return sorted(
+        item,
+        key=lambda value: re.sub(
+            r"(\d+)",
+            lambda num: f"{int(num[0]):010d}",
+            value,
+        ),
+    )

eva/core/utils/parser.py

@@ -0,0 +1,20 @@
+"""Parsing related helper functions."""
+
+from typing import Any, Dict
+
+import jsonargparse
+
+
+def parse_object(config: Dict[str, Any], expected_type: Any = Any) -> Any:
+    """Parse object which is defined as dictionary."""
+    parser = jsonargparse.ArgumentParser()
+    parser.add_argument("module", type=expected_type)
+    configuration = parser.parse_object({"module": config})
+    init_object = parser.instantiate_classes(configuration)
+    obj_module = init_object.module
+    if isinstance(obj_module, jsonargparse.Namespace):
+        raise ValueError(
+            f"Failed to parsed object '{obj_module.class_path}'. "
+            "Please check that the initialized arguments are valid."
+        )
+    return obj_module

eva/vision/__init__.py

@@ -1,7 +1,7 @@
 """eva vision API."""
 
 try:
-    from eva.vision import models, utils
+    from eva.vision import callbacks, losses, models, utils
     from eva.vision.data import datasets, transforms
 except ImportError as e:
     msg = (
@@ -11,4 +11,4 @@ except ImportError as e:
     )
     raise ImportError(str(e) + "\n\n" + msg) from e
 
-__all__ = ["models", "utils", "datasets", "transforms"]
+__all__ = ["callbacks", "losses", "models", "utils", "datasets", "transforms"]

eva/vision/callbacks/__init__.py

@@ -0,0 +1,5 @@
+"""Vision callbacks API."""
+
+from eva.vision.callbacks.loggers import SemanticSegmentationLogger
+
+__all__ = ["SemanticSegmentationLogger"]

eva/vision/callbacks/loggers/__init__.py

@@ -0,0 +1,5 @@
+"""Vision logging related callbacks API."""
+
+from eva.vision.callbacks.loggers.batch import SemanticSegmentationLogger
+
+__all__ = ["SemanticSegmentationLogger"]

eva/vision/callbacks/loggers/batch/__init__.py

@@ -0,0 +1,5 @@
+"""Batch related loggers callbacks API."""
+
+from eva.vision.callbacks.loggers.batch.segmentation import SemanticSegmentationLogger
+
+__all__ = ["SemanticSegmentationLogger"]

eva/vision/callbacks/loggers/batch/base.py

@@ -0,0 +1,130 @@
+"""Base batch callback logger."""
+
+import abc
+
+from lightning import pytorch as pl
+from lightning.pytorch.utilities.types import STEP_OUTPUT
+from typing_extensions import override
+
+from eva.core.models.modules.typings import INPUT_TENSOR_BATCH
+
+
+class BatchLogger(pl.Callback, abc.ABC):
+    """Logs training and validation batch assets."""
+
+    _batch_idx_to_log: int = 0
+    """The batch index log."""
+
+    def __init__(
+        self,
+        log_every_n_epochs: int | None = None,
+        log_every_n_steps: int | None = None,
+    ) -> None:
+        """Initializes the callback object.
+
+        Args:
+            log_every_n_epochs: Epoch-wise logging frequency.
+            log_every_n_steps: Step-wise logging frequency.
+        """
+        super().__init__()
+
+        if log_every_n_epochs is None and log_every_n_steps is None:
+            raise ValueError(
+                "Please configure the logging frequency though "
+                "`log_every_n_epochs` or `log_every_n_steps`."
+            )
+        if None not in [log_every_n_epochs, log_every_n_steps]:
+            raise ValueError(
+                "Arguments `log_every_n_epochs` and `log_every_n_steps` "
+                "are mutually exclusive. Please configure one of them."
+            )
+
+        self._log_every_n_epochs = log_every_n_epochs
+        self._log_every_n_steps = log_every_n_steps
+
+    @override
+    def on_train_batch_end(
+        self,
+        trainer: pl.Trainer,
+        pl_module: pl.LightningModule,
+        outputs: STEP_OUTPUT,
+        batch: INPUT_TENSOR_BATCH,
+        batch_idx: int,
+    ) -> None:
+        if self._skip_logging(trainer, batch_idx if self._log_every_n_epochs else None):
+            return
+
+        self._log_batch(
+            trainer=trainer,
+            batch=batch,
+            outputs=outputs,
+            tag="BatchTrain",
+        )
+
+    @override
+    def on_validation_batch_end(
+        self,
+        trainer: pl.Trainer,
+        pl_module: pl.LightningModule,
+        outputs: STEP_OUTPUT,
+        batch: INPUT_TENSOR_BATCH,
+        batch_idx: int,
+        dataloader_idx: int = 0,
+    ) -> None:
+        if self._skip_logging(trainer, batch_idx):
+            return
+
+        self._log_batch(
+            trainer=trainer,
+            batch=batch,
+            outputs=outputs,
+            tag="BatchValidation",
+        )
+
+    @abc.abstractmethod
+    def _log_batch(
+        self,
+        trainer: pl.Trainer,
+        outputs: STEP_OUTPUT,
+        batch: INPUT_TENSOR_BATCH,
+        tag: str,
+    ) -> None:
+        """Logs the batch data.
+
+        Args:
+            trainer: The trainer.
+            outputs: The output of the train / val step.
+            batch: The data batch.
+            tag: The log tag.
+        """
+
+    def _skip_logging(
+        self,
+        trainer: pl.Trainer,
+        batch_idx: int | None = None,
+    ) -> bool:
+        """Determines whether skip the logging step or not.
+
+        Args:
+            trainer: The trainer.
+            batch_idx: The batch index.
+
+        Returns:
+            A boolean indicating whether to skip the step execution.
+        """
+        if trainer.global_step in [0, 1]:
+            return False
+
+        skip_due_frequency = any(
+            [
+                (trainer.current_epoch + 1) % (self._log_every_n_epochs or 1) != 0,
+                (trainer.global_step + 1) % (self._log_every_n_steps or 1) != 0,
+            ]
+        )
+
+        conditions = [
+            skip_due_frequency,
+            not trainer.is_global_zero,
+            batch_idx != self._batch_idx_to_log if batch_idx else False,
+        ]
+        return any(conditions)

eva/vision/callbacks/loggers/batch/segmentation.py

@@ -0,0 +1,188 @@
+"""Segmentation datasets related data loggers."""
+
+from typing import List, Tuple
+
+import torch
+import torchvision
+from lightning import pytorch as pl
+from lightning.pytorch.utilities.types import STEP_OUTPUT
+from torch.nn import functional
+from typing_extensions import override
+
+from eva.core.loggers import log
+from eva.core.models.modules.typings import INPUT_TENSOR_BATCH
+from eva.core.utils import to_cpu
+from eva.vision.callbacks.loggers.batch import base
+from eva.vision.utils import colormap, convert
+
+
+class SemanticSegmentationLogger(base.BatchLogger):
+    """Log the segmentation batch."""
+
+    def __init__(
+        self,
+        max_samples: int = 10,
+        number_of_images_per_subgrid_row: int = 1,
+        log_images: bool = True,
+        mean: Tuple[float, ...] = (0.0, 0.0, 0.0),
+        std: Tuple[float, ...] = (1.0, 1.0, 1.0),
+        log_every_n_epochs: int | None = None,
+        log_every_n_steps: int | None = None,
+    ) -> None:
+        """Initializes the callback object.
+
+        Args:
+            max_samples: The maximum number of images displayed in the grid.
+            number_of_images_per_subgrid_row: Number of images displayed in each
+                row of each sub-grid (that is images, targets and predictions).
+            log_images: Whether to log the input batch images.
+            mean: The mean of the input images to de-normalize from.
+            std: The std of the input images to de-normalize from.
+            log_every_n_epochs: Epoch-wise logging frequency.
+            log_every_n_steps: Step-wise logging frequency.
+        """
+        super().__init__(
+            log_every_n_epochs=log_every_n_epochs,
+            log_every_n_steps=log_every_n_steps,
+        )
+
+        self._max_samples = max_samples
+        self._number_of_images_per_subgrid_row = number_of_images_per_subgrid_row
+        self._log_images = log_images
+        self._mean = mean
+        self._std = std
+
+    @override
+    def _log_batch(
+        self,
+        trainer: pl.Trainer,
+        outputs: STEP_OUTPUT,
+        batch: INPUT_TENSOR_BATCH,
+        tag: str,
+    ) -> None:
+        predictions = outputs.get("predictions") if isinstance(outputs, dict) else None
+        if predictions is None:
+            raise ValueError("Key `predictions` is missing from the output.")
+
+        data_batch, target_batch = batch[0], batch[1]
+        data, targets, predictions = _subsample_tensors(
+            tensors_stack=[data_batch, target_batch, predictions],
+            max_samples=self._max_samples,
+        )
+        data, targets, predictions = to_cpu([data, targets, predictions])
+        predictions = torch.argmax(predictions, dim=1)
+
+        target_images = list(map(_draw_semantic_mask, targets))
+        prediction_images = list(map(_draw_semantic_mask, predictions))
+        image_groups = [target_images, prediction_images]
+
+        if self._log_images:
+            images = list(map(self._format_image, data))
+            overlay_targets = [
+                _overlay_mask(image, mask) for image, mask in zip(images, targets, strict=False)
+            ]
+            overlay_predictions = [
+                _overlay_mask(image, mask) for image, mask in zip(images, predictions, strict=False)
+            ]
+            image_groups = [images, overlay_targets, overlay_predictions] + image_groups
+
+        image_grid = _make_grid_from_image_groups(
+            image_groups, self._number_of_images_per_subgrid_row
+        )
+
+        log.log_image(
+            trainer.loggers,
+            image=image_grid,
+            tag=tag,
+            step=trainer.global_step,
+        )
+
+    def _format_image(self, image: torch.Tensor) -> torch.Tensor:
+        """Descaled an image tensor to (0, 255) uint8 tensor."""
+        return convert.descale_and_denorm_image(image, mean=self._mean, std=self._std)
+
+
+def _subsample_tensors(
+    tensors_stack: List[torch.Tensor],
+    max_samples: int,
+) -> List[torch.Tensor]:
+    """Sub-samples tensors from a list of tensors in-place.
+
+    Args:
+        tensors_stack: A list of tensors.
+        max_samples: The maximum number of images
+            displayed in the grid.
+
+    Returns:
+        A sub-sample of the input tensors stack.
+    """
+    for i, tensor in enumerate(tensors_stack):
+        tensors_stack[i] = tensor[:max_samples]
+    return tensors_stack
+
+
+def _draw_semantic_mask(tensor: torch.Tensor) -> torch.Tensor:
+    """Draws a semantic mask to an image RGB tensor.
+
+    The input semantic mask is a (H x W) shaped tensor with
+    integer values which represent the pixel class id.
+
+    Args:
+        tensor: An image tensor of range [0., 1.].
+
+    Returns:
+        The image as a tensor of range [0., 255.].
+    """
+    tensor = torch.squeeze(tensor)
+    height, width = tensor.shape[-2], tensor.shape[-1]
+    red, green, blue = torch.zeros((3, height, width), dtype=torch.uint8)
+    for class_id, color in colormap.COLORMAP.items():
+        indices = tensor == class_id
+        red[indices], green[indices], blue[indices] = color
+    return torch.stack([red, green, blue])
+
+
+def _overlay_mask(image: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
+    """Overlays a segmentation mask onto an image.
+
+    Args:
+        image: A 3D tensor of shape (C, H, W) representing the image.
+        mask: A 2D tensor of shape (H, W) representing the segmentation mask.
+            Each pixel in the mask corresponds to a class label.
+
+    Returns:
+        A tensor of the same shape as the input image (C, H, W) with the
+        segmentation mask overlaid on top. The output image retains the
+        original color channels but with the mask applied, using the colors
+        from the predefined colormap.
+    """
+    binary_masks = functional.one_hot(mask).permute(2, 0, 1).to(dtype=torch.bool)
+    return torchvision.utils.draw_segmentation_masks(
+        image, binary_masks[1:], alpha=0.65, colors=colormap.COLORS[1:]  # type: ignore
+    )
+
+
+def _make_grid_from_image_groups(
+    image_groups: List[List[torch.Tensor]],
+    number_of_images_per_subgrid_row: int = 2,
+) -> torch.Tensor:
+    """Creates a single image grid from image groups.
+
+    For example, it can combine the input images, targets predictions into a single image.
+
+    Args:
+        image_groups: A list of lists of image tensors of shape (C x H x W)
+            all of the same size.
+        number_of_images_per_subgrid_row: Number of images displayed in each
+            row of the sub-grid.
+
+    Returns:
+        An image grid as a `torch.Tensor`.
+    """
+    return torchvision.utils.make_grid(
+        [
+            torchvision.utils.make_grid(image_group, nrow=number_of_images_per_subgrid_row)
+            for image_group in image_groups
+        ],
+        nrow=len(image_groups),
+    )

eva/vision/data/datasets/__init__.py

@@ -4,19 +4,39 @@ from eva.vision.data.datasets.classification import (
     BACH,
     CRC,
     MHIST,
+    PANDA,
+    Camelyon16,
     PatchCamelyon,
-    TotalSegmentatorClassification,
+    WsiClassificationDataset,
+)
+from eva.vision.data.datasets.segmentation import (
+    BCSS,
+    CoNSeP,
+    EmbeddingsSegmentationDataset,
+    ImageSegmentation,
+    LiTS,
+    MoNuSAC,
+    TotalSegmentator2D,
 )
-from eva.vision.data.datasets.segmentation import ImageSegmentation, TotalSegmentator2D
 from eva.vision.data.datasets.vision import VisionDataset
+from eva.vision.data.datasets.wsi import MultiWsiDataset, WsiDataset
 
 __all__ = [
     "BACH",
+    "BCSS",
     "CRC",
     "MHIST",
-    "ImageSegmentation",
+    "PANDA",
+    "Camelyon16",
     "PatchCamelyon",
-    "TotalSegmentatorClassification",
+    "WsiClassificationDataset",
+    "CoNSeP",
+    "EmbeddingsSegmentationDataset",
+    "ImageSegmentation",
+    "LiTS",
+    "MoNuSAC",
     "TotalSegmentator2D",
     "VisionDataset",
+    "MultiWsiDataset",
+    "WsiDataset",
 ]

eva/vision/data/datasets/_utils.py

@@ -1,6 +1,6 @@
 """Dataset related function and helper functions."""
 
-from typing import List, Tuple
+from typing import List, Sequence, Tuple
 
 
 def indices_to_ranges(indices: List[int]) -> List[Tuple[int, int]]:
@@ -33,11 +33,11 @@ def indices_to_ranges(indices: List[int]) -> List[Tuple[int, int]]:
     return ranges
 
 
-def ranges_to_indices(ranges: List[Tuple[int, int]]) -> List[int]:
+def ranges_to_indices(ranges: Sequence[Tuple[int, int]]) -> List[int]:
     """Unpacks a list of ranges to individual indices.
 
     Args:
-        ranges: The list of ranges to produce the indices from.
+        ranges: A sequence of ranges to produce the indices from.
 
     Return:
         A list of the indices.

eva/vision/data/datasets/_validators.py

@@ -13,7 +13,7 @@ _SUFFIX_ERROR_MESSAGE = "Please verify that the data are properly downloaded and
 def check_dataset_integrity(
     dataset: vision.VisionDataset,
     *,
-    length: int,
+    length: int | None,
     n_classes: int,
     first_and_last_labels: Tuple[str, str],
 ) -> None:
@@ -23,7 +23,7 @@ def check_dataset_integrity(
         ValueError: If the input dataset's values do not
             match the expected ones.
     """
-    if len(dataset) != length:
+    if length and len(dataset) != length:
         raise ValueError(
             f"Dataset's '{dataset.__class__.__qualname__}' length "
             f"({len(dataset)}) does not match the expected one ({length}). "
@@ -57,3 +57,16 @@ def check_dataset_exists(dataset_dir: str, download_available: bool) -> None:
         if download_available:
             error_message += " You can set `download=True` to download the dataset automatically."
         raise FileNotFoundError(error_message)
+
+
+def check_number_of_files(file_paths: List[str], expected_length: int, split: str | None) -> None:
+    """Verifies the number of files in the dataset.
+
+    Raise:
+        ValueError: If the number of files in the dataset does not match the expected one.
+    """
+    if len(file_paths) != expected_length:
+        raise ValueError(
+            f"Expected {expected_length} files, for split '{split}' found {len(file_paths)}. "
+            f"{_SUFFIX_ERROR_MESSAGE}"
+        )

eva/vision/data/datasets/classification/__init__.py

@@ -1,15 +1,19 @@
 """Image classification datasets API."""
 
 from eva.vision.data.datasets.classification.bach import BACH
+from eva.vision.data.datasets.classification.camelyon16 import Camelyon16
 from eva.vision.data.datasets.classification.crc import CRC
 from eva.vision.data.datasets.classification.mhist import MHIST
+from eva.vision.data.datasets.classification.panda import PANDA
 from eva.vision.data.datasets.classification.patch_camelyon import PatchCamelyon
-from eva.vision.data.datasets.classification.total_segmentator import TotalSegmentatorClassification
+from eva.vision.data.datasets.classification.wsi import WsiClassificationDataset
 
 __all__ = [
     "BACH",
     "CRC",
     "MHIST",
     "PatchCamelyon",
-    "TotalSegmentatorClassification",
+    "WsiClassificationDataset",
+    "PANDA",
+    "Camelyon16",
 ]