careamics 0.0.19__py3-none-any.whl

careamics/dataset_ng/patch_filter/shannon_filter.py

@@ -0,0 +1,188 @@
+"""Filter patches based on Shannon entropy threshold."""
+
+from collections.abc import Sequence
+
+import numpy as np
+from skimage.measure import shannon_entropy
+from tqdm import tqdm
+
+from careamics.dataset_ng.image_stack_loader import load_arrays
+from careamics.dataset_ng.patch_extractor import PatchExtractor
+from careamics.dataset_ng.patch_filter.patch_filter_protocol import PatchFilterProtocol
+from careamics.dataset_ng.patching_strategies import TilingStrategy
+
+
+class ShannonPatchFilter(PatchFilterProtocol):
+    """
+    Filter patches based on Shannon entropy threshold.
+
+    Attributes
+    ----------
+    threshold : float
+        Threshold for the Shannon entropy of the patch.
+    p : float
+        Probability of applying the filter to a patch.
+    rng : np.random.Generator
+        Random number generator for stochastic filtering.
+    """
+
+    def __init__(
+        self, threshold: float, p: float = 1.0, seed: int | None = None
+    ) -> None:
+        """
+        Create a ShannonEntropyFilter.
+
+        This filter removes patches whose Shannon entropy is below a specified
+        threshold.
+
+        Parameters
+        ----------
+        threshold : float
+            Threshold for the Shannon entropy of the patch.
+        p : float, default=1
+            Probability of applying the filter to a patch. Must be between 0 and 1.
+        seed : int | None, default=None
+            Seed for the random number generator for reproducibility.
+
+        Raises
+        ------
+        ValueError
+            If threshold is negative.
+        ValueError
+            If p is not between 0 and 1.
+        """
+        if threshold < 0:
+            raise ValueError("Threshold must be non-negative.")
+        if not (0 <= p <= 1):
+            raise ValueError("Probability p must be between 0 and 1.")
+
+        self.threshold = threshold
+
+        self.p = p
+        self.rng = np.random.default_rng(seed)
+
+    def filter_out(self, patch: np.ndarray) -> bool:
+        """
+        Determine whether to filter out a patch based on its Shannon entropy.
+
+        Parameters
+        ----------
+        patch : numpy.NDArray
+            The patch to evaluate.
+
+        Returns
+        -------
+        bool
+            True if the patch should be filtered out, False otherwise.
+        """
+        if self.rng.uniform(0, 1) < self.p:
+            return shannon_entropy(patch) < self.threshold
+        return False
+
+    @staticmethod
+    def filter_map(
+        image: np.ndarray,
+        patch_size: Sequence[int],
+    ) -> np.ndarray:
+        """
+        Compute the Shannon entropy map of an image.
+
+        The entropy is computed over non-overlapping patches. This method can be used
+        to assess a useful threshold for the Shannon entropy filter.
+
+        Parameters
+        ----------
+        image : numpy.NDArray
+            The image for which to compute the entropy map, must be 2D or 3D.
+        patch_size : Sequence[int]
+            The size of the patches to compute the entropy over. Must be a sequence
+            of two integers.
+
+        Returns
+        -------
+        numpy.NDArray
+            The Shannon entropy map of the patch.
+
+        Raises
+        ------
+        ValueError
+            If the image is not 2D or 3D.
+
+        Example
+        -------
+        The `filter_map` method can be used to assess a useful threshold for the
+        Shannon entropy filter. Below is an example of how to compute and visualize
+        the Shannon entropy map of a random image and visualize thresholded versions
+        of the map.
+        >>> import numpy as np
+        >>> from matplotlib import pyplot as plt
+        >>> from careamics.dataset_ng.patch_filter import ShannonPatchFilter
+        >>> rng = np.random.default_rng(42)
+        >>> image = rng.binomial(20, 0.1, (256, 256)).astype(np.float32)
+        >>> image[64:192, 64:192] += rng.normal(50, 5, (128, 128))
+        >>> image[96:160, 96:160] = rng.poisson(image[96:160, 96:160])
+        >>> patch_size = (16, 16)
+        >>> entropy_map = ShannonPatchFilter.filter_map(image, patch_size)
+        >>> fig, ax = plt.subplots(1, 5, figsize=(20, 5)) # doctest: +SKIP
+        >>> for i, thresh in enumerate([2 + 1.5 * i for i in range(5)]):
+        ...     ax[i].imshow(entropy_map >= thresh, cmap="gray") #doctest: +SKIP
+        ...     ax[i].set_title(f"Threshold: {thresh}") #doctest: +SKIP
+        >>> plt.show() # doctest: +SKIP
+        """
+        if len(image.shape) < 2 or len(image.shape) > 3:
+            raise ValueError("Image must be 2D or 3D.")
+
+        axes = "YX" if len(patch_size) == 2 else "ZYX"
+
+        shannon_img = np.zeros_like(image, dtype=float)
+
+        image_stacks = load_arrays(source=[image], axes=axes)
+        extractor = PatchExtractor(image_stacks)
+        tiling = TilingStrategy(
+            data_shapes=[(1, 1, *image.shape)],
+            patch_size=patch_size,
+            overlaps=(0,) * len(patch_size),  # no overlap
+        )
+
+        for idx in tqdm(range(tiling.n_patches), desc="Computing Shannon Entropy map"):
+            patch_spec = tiling.get_patch_spec(idx)
+            patch = extractor.extract_patch(
+                data_idx=0,
+                sample_idx=0,
+                coords=patch_spec["coords"],
+                patch_size=patch_size,
+            )
+
+            coordinates = tuple(
+                slice(patch_spec["coords"][i], patch_spec["coords"][i] + p)
+                for i, p in enumerate(patch_size)
+            )
+            shannon_img[coordinates] = shannon_entropy(patch)
+
+        return shannon_img
+
+    @staticmethod
+    def apply_filter(
+        filter_map: np.ndarray,
+        threshold: float,
+    ) -> np.ndarray:
+        """
+        Apply the Shannon entropy filter to a precomputed filter map.
+
+        The filter map is the output of the `filter_map` method.
+
+        Parameters
+        ----------
+        filter_map : numpy.NDArray
+            The precomputed Shannon entropy map of the image.
+        threshold : float
+            The Shannon entropy threshold for filtering.
+
+        Returns
+        -------
+        numpy.NDArray
+            A boolean array where True indicates that the patch should be kept
+            (not filtered out) and False indicates that the patch should be filtered
+            out.
+        """
+        return filter_map >= threshold

careamics/dataset_ng/patching_strategies/__init__.py

@@ -0,0 +1,26 @@
+__all__ = [
+    "FixedRandomPatchingStrategy",
+    "PatchSpecs",
+    "PatchingStrategy",
+    "RandomPatchingStrategy",
+    "RegionSpecs",
+    "SequentialPatchingStrategy",
+    "TileSpecs",
+    "TilingStrategy",
+    "WholeSamplePatchingStrategy",
+    "create_patching_strategy",
+    "is_tile_specs",
+]
+
+from .patching_strategy_factory import create_patching_strategy
+from .patching_strategy_protocol import (
+    PatchingStrategy,
+    PatchSpecs,
+    RegionSpecs,
+    TileSpecs,
+    is_tile_specs,
+)
+from .random_patching import FixedRandomPatchingStrategy, RandomPatchingStrategy
+from .sequential_patching import SequentialPatchingStrategy
+from .tiling_strategy import TilingStrategy
+from .whole_sample import WholeSamplePatchingStrategy

careamics/dataset_ng/patching_strategies/patching_strategy_factory.py

@@ -0,0 +1,50 @@
+"""Patching strategy factory."""
+
+from collections.abc import Sequence
+
+from careamics.config.data.ng_data_config import PatchingConfig
+from careamics.config.support.supported_patching_strategies import (
+    SupportedPatchingStrategy,
+)
+
+from .patching_strategy_protocol import PatchingStrategy
+from .random_patching import FixedRandomPatchingStrategy, RandomPatchingStrategy
+from .tiling_strategy import TilingStrategy
+from .whole_sample import WholeSamplePatchingStrategy
+
+
+def create_patching_strategy(
+    data_shapes: list[Sequence[int]], patching_config: PatchingConfig
+) -> PatchingStrategy:
+    """Factory function to create a patching strategy based on the provided config.
+
+    Parameters
+    ----------
+    data_shapes : list of Sequence of int
+        The shapes of the data stacks to be patched.
+    patching_config: PatchingConfig
+        The configuration for the desired patching strategy.
+
+    Returns
+    -------
+    PatchingStrategy
+        An instance of the specified patching strategy.
+    """
+    patch_class = None
+    match patching_config.name:
+        case SupportedPatchingStrategy.RANDOM:
+            patch_class = RandomPatchingStrategy
+        case SupportedPatchingStrategy.FIXED_RANDOM:
+            patch_class = FixedRandomPatchingStrategy
+        case SupportedPatchingStrategy.TILED:
+            patch_class = TilingStrategy
+        case SupportedPatchingStrategy.WHOLE:
+            patch_class = WholeSamplePatchingStrategy
+        case _:
+            raise ValueError(f"Unsupported patching strategy: {patching_config.name}")
+
+    # remove `name` to match the class signatures
+    # tiling requires `tile_size` instead of `patch_size`, hence the aliasing
+    return patch_class(
+        data_shapes=data_shapes, **patching_config.model_dump(exclude={"name"})
+    )

careamics/dataset_ng/patching_strategies/patching_strategy_protocol.py

@@ -0,0 +1,161 @@
+"""A module to contain type definitions relating to patching strategies."""
+
+from collections.abc import Sequence
+from typing import Protocol, TypedDict, TypeGuard, TypeVar
+
+RegionSpecs = TypeVar("RegionSpecs", bound="PatchSpecs")
+
+
+class PatchSpecs(TypedDict):
+    """A dictionary that specifies a single patch in a series of `ImageStacks`.
+
+    Attributes
+    ----------
+    data_idx: int
+        Determines which `ImageStack` a patch belongs to, within a series of
+        `ImageStack`s.
+    sample_idx: int
+        Determines which sample a patch belongs to, within an `ImageStack`.
+    coords: sequence of int
+        The top-left (and first z-slice for 3D data) of a patch. The sequence will have
+        length 2 or 3, for 2D and 3D data respectively.
+    patch_size: sequence of int
+        The size of the patch. The sequence will have length 2 or 3, for 2D and 3D data
+        respectively.
+    """
+
+    data_idx: int
+    sample_idx: int
+    coords: Sequence[int]
+    patch_size: Sequence[int]
+
+
+class TileSpecs(PatchSpecs):
+    """A dictionary that specifies a single patch in a series of `ImageStacks`.
+
+    Attributes
+    ----------
+    data_idx: int
+        Determines which `ImageStack` a patch belongs to, within a series of
+        `ImageStack`s.
+    sample_idx: int
+        Determines which sample a patch belongs to, within an `ImageStack`.
+    coords: sequence of int
+        The top-left (and first z-slice for 3D data) of a patch. The sequence will have
+        length 2 or 3, for 2D and 3D data respectively.
+    patch_size: sequence of int
+        The size of the patch. The sequence will have length 2 or 3, for 2D and 3D data
+        respectively.
+    crop_coords: sequence of int
+        The top-left side of where the tile will be cropped, in coordinates relative
+        to the tile.
+    crop_size: sequence of int
+        The size of the cropped tile.
+    stitch_coords: sequence of int
+        Where the tile will be stitched back into an image, taking into account
+        that the tile will be cropped, in coords relative to the image.
+    total_tiles: int
+        Number of tiles belonging to the same data.
+    """
+
+    crop_coords: Sequence[int]
+    crop_size: Sequence[int]
+    stitch_coords: Sequence[int]
+    total_tiles: int
+
+
+def is_tile_specs(specs: PatchSpecs) -> TypeGuard[TileSpecs]:
+    """Determine whether a given PatchSpecs is a TileSpecs.
+
+    Used for type checking.
+
+    Parameters
+    ----------
+    specs : PatchSpecs
+        A patch specification.
+
+    Returns
+    -------
+    bool
+        Whether the given specs is a TileSpecs.
+    """
+    return (
+        ("crop_coords" in specs)
+        and ("crop_size" in specs)
+        and ("stitch_coords" in specs)
+    )
+
+
+class PatchingStrategy(Protocol):
+    """
+    An interface for patching strategies.
+
+    Patching strategies are a component of the `CAREamicsDataset`; they determine
+    how patches are extracted from the underlying data.
+
+    Attributes
+    ----------
+    n_patches: int
+        The number of patches that the patching strategy will return.
+
+    Methods
+    -------
+    get_patch_spec(index: int) -> PatchSpecs
+        Get a patch specification for a given patch index.
+    """
+
+    @property
+    def n_patches(self) -> int:
+        """
+        The number of patches that the patching strategy will return.
+
+        It also determines the maximum index that can be given to `get_patch_spec`,
+        and the length of the `CAREamicsDataset`.
+
+        Returns
+        -------
+        int
+            Number of patches.
+        """
+        ...
+
+    def get_patch_spec(self, index: int) -> PatchSpecs:
+        """
+        Get a patch specification for a given patch index.
+
+        This method is intended to be called from within the
+        `CAREamicsDataset.__getitem__`. The index will be passed through from this
+        method.
+
+        Parameters
+        ----------
+        index : int
+            A patch index.
+
+        Returns
+        -------
+        PatchSpecs
+            A dictionary that specifies a single patch in a series of `ImageStacks`.
+        """
+        ...
+
+    # Note: this is used by the FileIterSampler
+    def get_patch_indices(self, data_idx: int) -> Sequence[int]:
+        """
+        Get the patch indices will return patches for a specific `image_stack`.
+
+        The `image_stack` corresponds to the given `data_idx`.
+
+        Parameters
+        ----------
+        data_idx : int
+            An index that corresponds to a given `image_stack`.
+
+        Returns
+        -------
+        sequence of int
+            A sequence of patch indices, that when used to index the `CAREamicsDataset
+            will return a patch that comes from the `image_stack` corresponding to the
+            given `data_idx`.
+        """
+        ...