careamics 0.0.19__py3-none-any.whl

careamics/config/data/patch_filter/__init__.py

@@ -0,0 +1,15 @@
+"""Pydantic models representing coordinate and patch filters."""
+
+__all__ = [
+    "FilterConfig",
+    "MaskFilterConfig",
+    "MaxFilterConfig",
+    "MeanSTDFilterConfig",
+    "ShannonFilterConfig",
+]
+
+from .filter_config import FilterConfig
+from .mask_filter_config import MaskFilterConfig
+from .max_filter_config import MaxFilterConfig
+from .meanstd_filter_config import MeanSTDFilterConfig
+from .shannon_filter_config import ShannonFilterConfig

careamics/config/data/patch_filter/filter_config.py

@@ -0,0 +1,16 @@
+"""Base class for patch and coordinate filtering models."""
+
+from pydantic import BaseModel, Field
+
+
+class FilterConfig(BaseModel):
+    """Base class for patch and coordinate filtering models."""
+
+    name: str
+    """Name of the filter."""
+
+    p: float = Field(1.0, ge=0.0, le=1.0)
+    """Probability of applying the filter to a patch or coordinate."""
+
+    seed: int | None = Field(default=None, gt=0)
+    """Seed for the random number generator for reproducibility."""

careamics/config/data/patch_filter/mask_filter_config.py

@@ -0,0 +1,17 @@
+"""Pydantic model for the mask coordinate filter."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from .filter_config import FilterConfig
+
+
+class MaskFilterConfig(FilterConfig):
+    """Pydantic model for the mask coordinate filter."""
+
+    name: Literal["mask"] = "mask"
+    """Name of the filter."""
+
+    coverage: float = Field(0.5, ge=0.0, le=1.0)
+    """Percentage of masked pixels required to keep a patch."""

careamics/config/data/patch_filter/max_filter_config.py

@@ -0,0 +1,15 @@
+"""Pydantic model for the max patch filter."""
+
+from typing import Literal
+
+from .filter_config import FilterConfig
+
+
+class MaxFilterConfig(FilterConfig):
+    """Pydantic model for the max patch filter."""
+
+    name: Literal["max"] = "max"
+    """Name of the filter."""
+
+    threshold: float
+    """Threshold for the minimum of the max-filtered patch."""

careamics/config/data/patch_filter/meanstd_filter_config.py

@@ -0,0 +1,18 @@
+"""Pydantic model for the mean std patch filter."""
+
+from typing import Literal
+
+from .filter_config import FilterConfig
+
+
+class MeanSTDFilterConfig(FilterConfig):
+    """Pydantic model for the mean std patch filter."""
+
+    name: Literal["mean_std"] = "mean_std"
+    """Name of the filter."""
+
+    mean_threshold: float
+    """Minimum mean intensity required to keep a patch."""
+
+    std_threshold: float | None = None
+    """Minimum standard deviation required to keep a patch."""

careamics/config/data/patch_filter/shannon_filter_config.py

@@ -0,0 +1,15 @@
+"""Pydantic model for the Shannon entropy patch filter."""
+
+from typing import Literal
+
+from .filter_config import FilterConfig
+
+
+class ShannonFilterConfig(FilterConfig):
+    """Pydantic model for the Shannon entropy patch filter."""
+
+    name: Literal["shannon"] = "shannon"
+    """Name of the filter."""
+
+    threshold: float
+    """Minimum Shannon entropy required to keep a patch."""

careamics/config/data/patching_strategies/__init__.py

@@ -0,0 +1,15 @@
+"""Patching strategies Pydantic models."""
+
+__all__ = [
+    "FixedRandomPatchingConfig",
+    "RandomPatchingConfig",
+    "SequentialPatchingConfig",
+    "TiledPatchingConfig",
+    "WholePatchingConfig",
+]
+
+
+from .random_patching_config import FixedRandomPatchingConfig, RandomPatchingConfig
+from .sequential_patching_config import SequentialPatchingConfig
+from .tiled_patching_config import TiledPatchingConfig
+from .whole_patching_config import WholePatchingConfig

careamics/config/data/patching_strategies/_overlapping_patched_config.py

@@ -0,0 +1,102 @@
+"""Sequential patching Pydantic model."""
+
+from collections.abc import Sequence
+
+from pydantic import Field, ValidationInfo, field_validator
+
+from ._patched_config import _PatchedConfig
+
+
+class _OverlappingPatchedConfig(_PatchedConfig):
+    """Overlapping patching Pydantic model.
+
+    This model is only used for inheritance and validation purposes.
+
+    Attributes
+    ----------
+    patch_size : list of int
+        The size of the patch in each spatial dimension, each patch size must be a power
+        of 2 and larger than 8.
+    overlaps : sequence of int, optional
+        The overlaps between patches in each spatial dimension. If `None`, no overlap is
+        applied. The overlaps must be smaller than the patch size in each spatial
+        dimension, and the number of dimensions be either 2 or 3.
+    """
+
+    overlaps: Sequence[int] | None = Field(
+        default=None,
+        min_length=2,
+        max_length=3,
+    )
+    """The overlaps between patches in each spatial dimension. If `None`, no overlap is
+    applied. The overlaps must be smaller than the patch size in each spatial dimension,
+    and the number of dimensions be either 2 or 3.
+    """
+
+    @field_validator("overlaps")
+    @classmethod
+    def overlap_smaller_than_patch_size(
+        cls, overlaps: Sequence[int] | None, values: ValidationInfo
+    ) -> Sequence[int] | None:
+        """
+        Validate overlap.
+
+        Overlaps must be smaller than the patch size in each spatial dimension.
+
+        Parameters
+        ----------
+        overlaps : Sequence of int
+            Overlap in each dimension.
+        values : ValidationInfo
+            Dictionary of values.
+
+        Returns
+        -------
+        Sequence of int
+            Validated overlap.
+        """
+        if overlaps is None:
+            return None
+
+        patch_size = values.data["patch_size"]
+
+        if len(overlaps) != len(patch_size):
+            raise ValueError(
+                f"Overlaps must have the same number of dimensions as the patch size. "
+                f"Got {len(overlaps)} dimensions for overlaps and {len(patch_size)} "
+                f"dimensions for patch size."
+            )
+
+        if any(o >= p for o, p in zip(overlaps, patch_size, strict=False)):
+            raise ValueError(
+                f"Overlap must be smaller than the patch size, got {overlaps} versus "
+                f"{patch_size}."
+            )
+
+        return overlaps
+
+    @field_validator("overlaps")
+    @classmethod
+    def overlap_even(cls, overlaps: Sequence[int] | None) -> Sequence[int] | None:
+        """
+        Validate overlaps.
+
+        Overlap must be even.
+
+        Parameters
+        ----------
+        overlaps : Sequence of int
+            Overlaps.
+
+        Returns
+        -------
+        Sequence of int
+            Validated overlap.
+        """
+        if overlaps is None:
+            return None
+
+        if any(o % 2 != 0 for o in overlaps):
+            raise ValueError(f"Overlaps must be even, got {overlaps}.")
+
+        return overlaps

careamics/config/data/patching_strategies/_patched_config.py

@@ -0,0 +1,56 @@
+"""Generic patching Pydantic model."""
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from careamics.config.validators import patch_size_ge_than_8_power_of_2
+
+
+class _PatchedConfig(BaseModel):
+    """Generic patching Pydantic model.
+
+    This model is only used for inheritance and validation purposes.
+    """
+
+    model_config = ConfigDict(
+        extra="ignore",  # default behaviour, make it explicit
+    )
+
+    name: str
+    """The name of the patching strategy."""
+
+    patch_size: Sequence[int] = Field(..., min_length=2, max_length=3)
+    """The size of the patch in each spatial dimensions, each patch size must be a power
+    of 2 and larger than 8."""
+
+    @field_validator("patch_size")
+    @classmethod
+    def all_elements_power_of_2_minimum_8(
+        cls, patch_list: Sequence[int]
+    ) -> Sequence[int]:
+        """
+        Validate patch size.
+
+        Patch size must be powers of 2 and minimum 8.
+
+        Parameters
+        ----------
+        patch_list : Sequence of int
+            Patch size.
+
+        Returns
+        -------
+        Sequence of int
+            Validated patch size.
+
+        Raises
+        ------
+        ValueError
+            If the patch size is smaller than 8.
+        ValueError
+            If the patch size is not a power of 2.
+        """
+        patch_size_ge_than_8_power_of_2(patch_list)
+
+        return patch_list

careamics/config/data/patching_strategies/random_patching_config.py

@@ -0,0 +1,45 @@
+"""Random patching Pydantic model."""
+
+from typing import Literal
+
+from pydantic import Field
+
+from ._patched_config import _PatchedConfig
+
+
+class RandomPatchingConfig(_PatchedConfig):
+    """Random patching Pydantic model.
+
+    Attributes
+    ----------
+    name : "random"
+        The name of the patching strategy.
+    patch_size : sequence of int
+        The size of the patch in each spatial dimension, each patch size must be a power
+        of 2 and larger than 8.
+    """
+
+    name: Literal["random"] = "random"
+    """The name of the patching strategy."""
+
+    seed: int | None = Field(default=None, gt=0)
+    """Random seed for patch sampling, set to None for random seeding."""
+
+
+class FixedRandomPatchingConfig(_PatchedConfig):
+    """Fixed random patching Pydantic model.
+
+    Attributes
+    ----------
+    name : "fixed_random"
+        The name of the patching strategy.
+    patch_size : sequence of int
+        The size of the patch in each spatial dimension, each patch size must be a power
+        of 2 and larger than 8.
+    """
+
+    name: Literal["fixed_random"] = "fixed_random"
+    """The name of the patching strategy."""
+
+    seed: int | None = Field(default=None, gt=0)
+    """The random seed to use for patch sampling."""

careamics/config/data/patching_strategies/sequential_patching_config.py

@@ -0,0 +1,25 @@
+"""Sequential patching Pydantic model."""
+
+from typing import Literal
+
+from ._overlapping_patched_config import _OverlappingPatchedConfig
+
+
+class SequentialPatchingConfig(_OverlappingPatchedConfig):
+    """Sequential patching Pydantic model.
+
+    Attributes
+    ----------
+    name : "sequential"
+        The name of the patching strategy.
+    patch_size : sequence of int
+        The size of the patch in each spatial dimension, each patch size must be a power
+        of 2 and larger than 8.
+    overlaps : list of int, optional
+        The overlaps between patches in each spatial dimension. If `None`, no overlap is
+        applied. The overlaps must be smaller than the patch size in each spatial
+        dimension, and the number of dimensions be either 2 or 3.
+    """
+
+    name: Literal["sequential"] = "sequential"
+    """The name of the patching strategy."""

careamics/config/data/patching_strategies/tiled_patching_config.py

@@ -0,0 +1,40 @@
+"""Tiled patching Pydantic model."""
+
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import Field
+
+from ._overlapping_patched_config import _OverlappingPatchedConfig
+
+
+# TODO with UNet tiling must obey different rules than sequential tiling
+#   - needs to validated at the level of the configuration
+class TiledPatchingConfig(_OverlappingPatchedConfig):
+    """Tiled patching Pydantic model.
+
+    Attributes
+    ----------
+    name : "tiled"
+        The name of the patching strategy.
+    patch_size : sequence of int
+        The size of the patch in each spatial dimension, each patch size must be a power
+        of 2 and larger than 8.
+    overlaps : sequence of int
+        The overlaps between patches in each spatial dimension. The overlaps must be
+        smaller than the patch size in each spatial dimension, and the number of
+        dimensions be either 2 or 3.
+    """
+
+    name: Literal["tiled"] = "tiled"
+    """The name of the patching strategy."""
+
+    overlaps: Sequence[int] = Field(
+        ...,
+        min_length=2,
+        max_length=3,
+    )
+    """The overlaps between patches in each spatial dimension. The overlaps must be
+    smaller than the patch size in each spatial dimension, and the number of dimensions
+    be either 2 or 3.
+    """

careamics/config/data/patching_strategies/whole_patching_config.py

@@ -0,0 +1,12 @@
+"""Whole image patching Pydantic model."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class WholePatchingConfig(BaseModel):
+    """Whole image patching Pydantic model."""
+
+    name: Literal["whole"] = "whole"
+    """The name of the patching strategy."""

careamics/config/data/tile_information.py

@@ -0,0 +1,65 @@
+"""Pydantic model representing the metadata of a prediction tile."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from annotated_types import Len
+from pydantic import BaseModel, ConfigDict
+
+DimTuple = Annotated[tuple, Len(min_length=3, max_length=4)]
+
+
+class TileInformation(BaseModel):
+    """
+    Pydantic model containing tile information.
+
+    This model is used to represent the information required to stitch back a tile into
+    a larger image. It is used throughout the prediction pipeline of CAREamics.
+
+    Array shape should be C(Z)YX, where Z is an optional dimensions.
+    """
+
+    model_config = ConfigDict(validate_default=True)
+
+    array_shape: DimTuple  # TODO: find a way to add custom error message?
+    """Shape of the original (untiled) array."""
+
+    last_tile: bool = False
+    """Whether this tile is the last one of the array."""
+
+    overlap_crop_coords: tuple[tuple[int, ...], ...]
+    """Inner coordinates of the tile where to crop the prediction in order to stitch
+    it back into the original image."""
+
+    stitch_coords: tuple[tuple[int, ...], ...]
+    """Coordinates in the original image where to stitch the cropped tile back."""
+
+    sample_id: int
+    """Sample ID of the tile."""
+
+    # TODO: Test that ZYX axes are not singleton ?
+
+    def __eq__(self, other_tile: object):
+        """Check if two tile information objects are equal.
+
+        Parameters
+        ----------
+        other_tile : object
+            Tile information object to compare with.
+
+        Returns
+        -------
+        bool
+            Whether the two tile information objects are equal.
+        """
+        if not isinstance(other_tile, TileInformation):
+            return NotImplemented
+
+        return (
+            self.array_shape == other_tile.array_shape
+            and self.last_tile == other_tile.last_tile
+            and self.overlap_crop_coords == other_tile.overlap_crop_coords
+            and self.stitch_coords == other_tile.stitch_coords
+            and self.sample_id == other_tile.sample_id
+        )

careamics/config/lightning/__init__.py

@@ -0,0 +1,15 @@
+"""Training and lightning related Pydantic configurations."""
+
+__all__ = [
+    "CheckpointConfig",
+    "EarlyStoppingConfig",
+    "LrSchedulerConfig",
+    "OptimizerConfig",
+    "TrainerConfig",
+    "TrainingConfig",
+]
+
+
+from .callbacks import CheckpointConfig, EarlyStoppingConfig
+from .optimizer_configs import LrSchedulerConfig, OptimizerConfig
+from .training_config import TrainingConfig

careamics/config/lightning/callbacks/__init__.py

@@ -0,0 +1,8 @@
+"""Callbacks Pydantic configurations."""
+
+__all__ = [
+    "CheckpointConfig",
+    "EarlyStoppingConfig",
+]
+
+from .callback_config import CheckpointConfig, EarlyStoppingConfig

careamics/config/lightning/callbacks/callback_config.py

@@ -0,0 +1,116 @@
+"""Callback Pydantic models."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+
+class CheckpointConfig(BaseModel):
+    """Checkpoint saving callback Pydantic model.
+
+    The parameters corresponds to those of
+    `pytorch_lightning.callbacks.ModelCheckpoint`.
+
+    See:
+    https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.callbacks.ModelCheckpoint.html#modelcheckpoint
+    """
+
+    model_config = ConfigDict(validate_assignment=True, validate_default=True)
+
+    monitor: Literal["val_loss"] | str | None = Field(default="val_loss")
+    """Quantity to monitor, currently only `val_loss`."""
+
+    verbose: bool = Field(default=False)
+    """Verbosity mode."""
+
+    save_weights_only: bool = Field(default=False)
+    """When `True`, only the model's weights will be saved (model.save_weights)."""
+
+    save_last: Literal[True, False, "link"] | None = Field(default=True)
+    """When `True`, saves a last.ckpt copy whenever a checkpoint file gets saved."""
+
+    save_top_k: int = Field(
+        default=3,
+        ge=-1,
+        le=100,
+    )
+    """If `save_top_k == k, the best k models according to the quantity monitored
+    will be saved. If `save_top_k == 0`, no models are saved. if `save_top_k == -1`,
+    all models are saved."""
+
+    mode: Literal["min", "max"] = Field(default="min")
+    """One of {min, max}. If `save_top_k != 0`, the decision to overwrite the current
+    save file is made based on either the maximization or the minimization of the
+    monitored quantity. For 'val_acc', this should be 'max', for 'val_loss' this should
+    be 'min', etc.
+    """
+
+    auto_insert_metric_name: bool = Field(default=False)
+    """When `True`, the checkpoints filenames will contain the metric name."""
+
+    every_n_train_steps: int | None = Field(default=None, ge=1, le=1000)
+    """Number of training steps between checkpoints."""
+
+    train_time_interval: timedelta | None = Field(default=None)
+    """Checkpoints are monitored at the specified time interval."""
+
+    every_n_epochs: int | None = Field(default=None, ge=1, le=100)
+    """Number of epochs between checkpoints."""
+
+
+class EarlyStoppingConfig(BaseModel):
+    """Early stopping callback Pydantic model.
+
+    The parameters corresponds to those of
+    `pytorch_lightning.callbacks.ModelCheckpoint`.
+
+    See:
+    https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.callbacks.EarlyStopping.html#lightning.pytorch.callbacks.EarlyStopping
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        validate_default=True,
+    )
+
+    monitor: Literal["val_loss"] = Field(default="val_loss")
+    """Quantity to monitor."""
+
+    min_delta: float = Field(default=0.0, ge=0.0, le=1.0)
+    """Minimum change in the monitored quantity to qualify as an improvement, i.e. an
+    absolute change of less than or equal to min_delta, will count as no improvement."""
+
+    patience: int = Field(default=3, ge=1, le=10)
+    """Number of checks with no improvement after which training will be stopped."""
+
+    verbose: bool = Field(default=False)
+    """Verbosity mode."""
+
+    mode: Literal["min", "max", "auto"] = Field(default="min")
+    """One of {min, max, auto}."""
+
+    check_finite: bool = Field(default=True)
+    """When `True`, stops training when the monitored quantity becomes `NaN` or
+    `inf`."""
+
+    stopping_threshold: float | None = Field(default=None)
+    """Stop training immediately once the monitored quantity reaches this threshold."""
+
+    divergence_threshold: float | None = Field(default=None)
+    """Stop training as soon as the monitored quantity becomes worse than this
+    threshold."""
+
+    check_on_train_epoch_end: bool | None = Field(default=False)
+    """Whether to run early stopping at the end of the training epoch. If this is
+    `False`, then the check runs at the end of the validation."""
+
+    log_rank_zero_only: bool = Field(default=False)
+    """When set `True`, logs the status of the early stopping callback only for rank 0
+    process."""