careamics 0.0.19__py3-none-any.whl

careamics/dataset_ng/patch_filter/__init__.py

@@ -0,0 +1,20 @@
+"""Patch filtering strategies."""
+
+__all__ = [
+    "CoordinateFilterProtocol",
+    "MaskCoordFilter",
+    "MaxPatchFilter",
+    "MeanStdPatchFilter",
+    "PatchFilterProtocol",
+    "ShannonPatchFilter",
+    "create_coord_filter",
+    "create_patch_filter",
+]
+
+from .coordinate_filter_protocol import CoordinateFilterProtocol
+from .filter_factory import create_coord_filter, create_patch_filter
+from .mask_filter import MaskCoordFilter
+from .max_filter import MaxPatchFilter
+from .mean_std_filter import MeanStdPatchFilter
+from .patch_filter_protocol import PatchFilterProtocol
+from .shannon_filter import ShannonPatchFilter

careamics/dataset_ng/patch_filter/coordinate_filter_protocol.py

@@ -0,0 +1,27 @@
+"""A protocol for patch filtering."""
+
+from typing import Protocol
+
+from careamics.dataset_ng.patching_strategies import PatchSpecs
+
+
+class CoordinateFilterProtocol(Protocol):
+    """
+    An interface for implementing coordinate filtering strategies.
+    """
+
+    def filter_out(self, patch: PatchSpecs) -> bool:
+        """
+        Determine whether to filter out a given patch based on its coordinates.
+
+        Parameters
+        ----------
+        patch : PatchSpecs
+            The patch coordinates to evaluate.
+
+        Returns
+        -------
+        bool
+            True if the patch should be filtered out (excluded), False otherwise.
+        """
+        ...

careamics/dataset_ng/patch_filter/filter_factory.py

@@ -0,0 +1,95 @@
+"""Factories for coordinate and patch filters."""
+
+from typing import Union
+
+from careamics.config.data.patch_filter import (
+    FilterConfig,
+    MaskFilterConfig,
+    MaxFilterConfig,
+    MeanSTDFilterConfig,
+    ShannonFilterConfig,
+)
+from careamics.config.support.supported_filters import (
+    SupportedCoordinateFilters,
+    SupportedPatchFilters,
+)
+from careamics.dataset_ng.image_stack import GenericImageStack
+from careamics.dataset_ng.patch_extractor import PatchExtractor
+
+from .mask_filter import MaskCoordFilter
+from .max_filter import MaxPatchFilter
+from .mean_std_filter import MeanStdPatchFilter
+from .shannon_filter import ShannonPatchFilter
+
+PatchFilter = Union[
+    MaxPatchFilter,
+    MeanStdPatchFilter,
+    ShannonPatchFilter,
+]
+
+
+CoordFilter = Union[MaskCoordFilter]
+
+
+def create_coord_filter(
+    filter_model: FilterConfig, mask: PatchExtractor[GenericImageStack]
+) -> CoordFilter:
+    """Factory function to create coordinate filter instances based on the filter name.
+
+    Parameters
+    ----------
+    filter_model : FilterModel
+        Pydantic model of the filter to be created.
+    mask : PatchExtractor[GenericImageStack]
+        Mask extractor to be used for the mask filter.
+
+    Returns
+    -------
+    CoordFilter
+        Instance of the mask patch filter.
+    """
+    if filter_model.name == SupportedCoordinateFilters.MASK:
+        assert isinstance(filter_model, MaskFilterConfig)
+        return MaskCoordFilter(
+            mask_extractor=mask,
+            coverage=filter_model.coverage,
+            p=filter_model.p,
+            seed=filter_model.seed,
+        )
+    else:
+        raise ValueError(f"Unknown filter name: {filter_model}")
+
+
+def create_patch_filter(filter_model: FilterConfig) -> PatchFilter:
+    """Factory function to create patch filter instances based on the filter name.
+
+    Parameters
+    ----------
+    filter_model : FilterModel
+        Pydantic model of the filter to be created.
+
+    Returns
+    -------
+    PatchFilter
+        Instance of the requested patch filter.
+    """
+    if filter_model.name == SupportedPatchFilters.MAX:
+        assert isinstance(filter_model, MaxFilterConfig)
+        return MaxPatchFilter(
+            threshold=filter_model.threshold, p=filter_model.p, seed=filter_model.seed
+        )
+    elif filter_model.name == SupportedPatchFilters.MEANSTD:
+        assert isinstance(filter_model, MeanSTDFilterConfig)
+        return MeanStdPatchFilter(
+            mean_threshold=filter_model.mean_threshold,
+            std_threshold=filter_model.std_threshold,
+            p=filter_model.p,
+            seed=filter_model.seed,
+        )
+    elif filter_model.name == SupportedPatchFilters.SHANNON:
+        assert isinstance(filter_model, ShannonFilterConfig)
+        return ShannonPatchFilter(
+            threshold=filter_model.threshold, p=filter_model.p, seed=filter_model.seed
+        )
+    else:
+        raise ValueError(f"Unknown filter name: {filter_model}")

careamics/dataset_ng/patch_filter/mask_filter.py

@@ -0,0 +1,96 @@
+"""Filter using an image mask."""
+
+import numpy as np
+
+from careamics.dataset_ng.image_stack import GenericImageStack
+from careamics.dataset_ng.patch_extractor import PatchExtractor
+from careamics.dataset_ng.patch_filter.coordinate_filter_protocol import (
+    CoordinateFilterProtocol,
+)
+from careamics.dataset_ng.patching_strategies import PatchSpecs
+
+
+# TODO is it more intuitive to have a negative mask? (mask of what to avoid)
+class MaskCoordFilter(CoordinateFilterProtocol):
+    """
+    Filter patch coordinates based on an image mask.
+
+    Attributes
+    ----------
+    mask_extractor : PatchExtractor[GenericImageStack]
+        Patch extractor for the binary mask to use for filtering.
+    coverage_perc : float
+        Minimum percentage of masked pixels required to keep a patch.
+    p : float
+        Probability of applying the filter to a patch.
+    rng : np.random.Generator
+        Random number generator for stochastic filtering.
+    """
+
+    def __init__(
+        self,
+        mask_extractor: PatchExtractor[GenericImageStack],
+        coverage: float,
+        p: float = 1.0,
+        seed: int | None = None,
+    ) -> None:
+        """
+        Create a MaskCoordFilter.
+
+        This filter removes patches who fall below a threshold of masked pixels
+        percentage. The mask is expected to be a positive mask where masked pixels
+        correspond to regions of interest.
+
+        Parameters
+        ----------
+        mask_extractor : PatchExtractor[GenericImageStack]
+            The patch extractor for the mask used for filtering.
+        coverage : float
+            Minimum percentage of masked pixels required to keep a patch. Must be
+            between 0 and 1.
+        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 coverage is not between 0 and 1.
+        ValueError
+            If p is not between 0 and 1.
+        """
+
+        if not (0 <= coverage <= 1):
+            raise ValueError("Probability p must be between 0 and 1.")
+        if not (0 <= p <= 1):
+            raise ValueError("Probability p must be between 0 and 1.")
+
+        self.mask_extractor = mask_extractor
+        self.coverage = coverage
+
+        self.p = p
+        self.rng = np.random.default_rng(seed)
+
+    def filter_out(self, patch_specs: PatchSpecs) -> bool:
+        """
+        Determine whether to filter out a patch based an image mask.
+
+        Parameters
+        ----------
+        patch : PatchSpecs
+            The patch coordinates to evaluate.
+
+        Returns
+        -------
+        bool
+            True if the patch should be filtered out, False otherwise.
+        """
+
+        if self.rng.uniform(0, 1) < self.p:
+            mask_patch = self.mask_extractor.extract_patch(**patch_specs)
+
+            masked_fraction = np.sum(mask_patch) / mask_patch.size
+            if masked_fraction < self.coverage:
+                return True
+        return False

careamics/dataset_ng/patch_filter/max_filter.py

@@ -0,0 +1,188 @@
+"""Filter patch using a maximum filter."""
+
+from collections.abc import Sequence
+
+import numpy as np
+from scipy.ndimage import maximum_filter
+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
+from careamics.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MaxPatchFilter(PatchFilterProtocol):
+    """
+    A patch filter based on thresholding the maximum filter of the patch.
+
+    Inspired by the CSBDeep approach.
+
+    Attributes
+    ----------
+    threshold : float
+        Threshold for the maximum filter 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,
+        threshold_ratio: float = 0.25,
+        seed: int | None = None,
+    ) -> None:
+        """
+        Create a MaxPatchFilter.
+
+        This filter removes patches whose maximum filter valuepixels are below a
+        specified threshold.
+
+        Parameters
+        ----------
+        threshold : float
+            Threshold for the maximum filter of the patch.
+        p : float, default=1
+            Probability of applying the filter to a patch. Must be between 0 and 1.
+        threshold_ratio : float, default=0.25
+            Ratio of pixels that must be below threshold for patch to be filtered out.
+            Must be between 0 and 1.
+        seed : int | None, default=None
+            Seed for the random number generator for reproducibility.
+        """
+        self.threshold = threshold
+        self.threshold_ratio = threshold_ratio
+        self.p = p
+        self.rng = np.random.default_rng(seed)
+
+    def filter_out(self, patch: np.ndarray) -> bool:
+        if self.rng.uniform(0, 1) < self.p:
+
+            if np.max(patch) < self.threshold:
+                return True
+
+            patch_shape = [(p // 2 if p > 1 else 1) for p in patch.shape]
+            filtered = maximum_filter(patch, patch_shape, mode="constant")
+            return np.mean(filtered < self.threshold) > self.threshold_ratio
+
+        return False
+
+    @staticmethod
+    def filter_map(
+        image: np.ndarray,
+        patch_size: Sequence[int],
+    ) -> np.ndarray:
+        """
+        Compute the maximum map of an image.
+
+        The map is computed over non-overlapping patches. This method can be used
+        to assess a useful threshold for the MaxPatchFilter filter.
+
+        Parameters
+        ----------
+        image : numpy.NDArray
+            The image for which to compute the map, must be 2D or 3D.
+        patch_size : Sequence[int]
+            The size of the patches to compute the map over. Must be a sequence
+            of two integers.
+
+        Returns
+        -------
+        numpy.NDArray
+            The max 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 MaxPatchFilter
+        >>> 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)
+        >>> max_filtered = MaxPatchFilter.filter_map(image, patch_size)
+        >>> fig, ax = plt.subplots(1, 5, figsize=(20, 5)) # doctest: +SKIP
+        >>> for i, thresh in enumerate([50 + i*5 for i in range(5)]):
+        ...     ax[i].imshow(max_filtered >= 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"
+
+        max_filtered = 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
+        )
+        max_patch_size = [p // 2 for p in patch_size]
+
+        for idx in tqdm(range(tiling.n_patches), desc="Computing max 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)
+            )
+            max_filtered[coordinates] = maximum_filter(
+                patch.squeeze(), max_patch_size, mode="constant"
+            )
+
+        return max_filtered
+
+    @staticmethod
+    def apply_filter(
+        filter_map: np.ndarray,
+        threshold: float,
+    ) -> np.ndarray:
+        """
+        Apply the max filter to a filter map.
+
+        The filter map is the output of the `filter_map` method.
+
+        Parameters
+        ----------
+        filter_map : numpy.NDArray
+            The max filter map of the image.
+        threshold : float
+            The threshold to apply to the filter map.
+
+        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.
+        """
+        threshold_map = filter_map >= threshold
+        coverage = np.sum(threshold_map) * 100 / threshold_map.size
+        logger.info(f"Image coverage: {coverage:.2f}%")
+        return threshold_map

careamics/dataset_ng/patch_filter/mean_std_filter.py

@@ -0,0 +1,218 @@
+"""Filter using mean and standard deviation thresholds."""
+
+from collections.abc import Sequence
+
+import numpy as np
+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 MeanStdPatchFilter(PatchFilterProtocol):
+    """
+    Filter patches based on mean and standard deviation thresholds.
+
+    Attributes
+    ----------
+    mean_threshold : float
+        Threshold for the mean of the patch.
+    std_threshold : float
+        Threshold for the standard deviation 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,
+        mean_threshold: float,
+        std_threshold: float | None = None,
+        p: float = 1.0,
+        seed: int | None = None,
+    ) -> None:
+        """
+        Create a MeanStdPatchFilter.
+
+        This filter removes patches whose mean and standard deviation are both below
+        specified thresholds. The filtering is applied with a probability `p`, allowing
+        for stochastic filtering.
+
+        Parameters
+        ----------
+        mean_threshold : float
+            Threshold for the mean of the patch.
+        std_threshold : float | None, default=None
+            Threshold for the standard deviation of the patch. If None, then no
+            standard deviation filtering is applied.
+        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 mean_threshold or std_threshold is negative.
+        ValueError
+            If std_threshold is negative.
+        ValueError
+            If p is not between 0 and 1.
+        """
+
+        if mean_threshold < 0:
+            raise ValueError("Mean threshold must be non-negative.")
+        if std_threshold is not None and std_threshold < 0:
+            raise ValueError("Std threshold must be non-negative.")
+        if not (0 <= p <= 1):
+            raise ValueError("Probability p must be between 0 and 1.")
+
+        self.mean_threshold = mean_threshold
+        self.std_threshold = std_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 mean and std thresholds.
+
+        Parameters
+        ----------
+        patch : numpy.NDArray
+            The image patch to evaluate.
+
+        Returns
+        -------
+        bool
+            True if the patch should be filtered out, False otherwise.
+        """
+
+        if self.rng.uniform(0, 1) < self.p:
+            patch_mean = np.mean(patch)
+            patch_std = np.std(patch)
+
+            return (patch_mean < self.mean_threshold) or (
+                self.std_threshold is not None and patch_std < self.std_threshold
+            )
+        return False
+
+    @staticmethod
+    def filter_map(image: np.ndarray, patch_size: Sequence[int]) -> np.ndarray:
+        """
+        Compute the mean and std map of an image.
+
+        The mean and std are computed over non-overlapping patches. This method can be
+        used to assess a useful threshold for the MeanStd filter.
+
+        Parameters
+        ----------
+        image : numpy.NDArray
+            The full image to evaluate.
+        patch_size : Sequence[int]
+            The size of the patches to consider.
+
+        Returns
+        -------
+        np.ndarray
+            Stacked mean and std maps of the image.
+
+        Raises
+        ------
+        ValueError
+            If the image is not 2D or 3D.
+
+        Example
+        -------
+        The `filter_map` method can be used to assess useful thresholds for the
+        MeanStd filter.
+        >>> import numpy as np
+        >>> import matplotlib.pyplot as plt
+        >>> from careamics.dataset_ng.patch_filter import MeanStdPatchFilter
+        >>> 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, 3, (128, 128))
+        >>> image[96:160, 96:160] = rng.poisson(image[96:160, 96:160])
+        >>> patch_size = (16, 16)
+        >>> meanstd_map = MeanStdPatchFilter.filter_map(image, patch_size)
+        >>> fig, ax = plt.subplots(3, 3, figsize=(10, 10)) # doctest: +SKIP
+        >>> for i, mean_thresh in enumerate([48 + i for i in range(3)]):
+        ...     for j, std_thresh in enumerate([5 + i for i in range(3)]):
+        ...         ax[i, j].imshow(
+        ...             (meanstd_map[0, ...] > mean_thresh)
+        ...             & (meanstd_map[1, ...] > std_thresh),
+        ...             cmap="gray", vmin=0, vmax=1
+        ...         ) # doctest: +SKIP
+        ...         ax[i, j].set_title(
+        ...             f"Mean: {mean_thresh}, Std: {std_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"
+
+        mean = np.zeros_like(image, dtype=float)
+        std = 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 Mean/STD 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)
+            )
+            mean[coordinates] = np.mean(patch)
+            std[coordinates] = np.std(patch)
+
+        return np.stack([mean, std], axis=0)
+
+    @staticmethod
+    def apply_filter(
+        filter_map: np.ndarray,
+        mean_threshold: float,
+        std_threshold: float | None = None,
+    ) -> np.ndarray:
+        """
+        Apply mean and std thresholds to a filter map.
+
+        The filter map is the output of the `filter_map` method.
+
+        Parameters
+        ----------
+        filter_map : np.ndarray
+            Stacked mean and std maps of the image.
+        mean_threshold : float
+            Threshold for the mean of the patch.
+        std_threshold : float | None, default=None
+            Threshold for the standard deviation of the patch. If None, then no
+            standard deviation filtering is applied.
+
+        Returns
+        -------
+        np.ndarray
+            A binary map where True indicates patches that pass the filter.
+        """
+        if std_threshold is not None:
+            return (filter_map[0, ...] > mean_threshold) & (
+                filter_map[1, ...] > std_threshold
+            )
+        return filter_map[0, ...] > mean_threshold

careamics/dataset_ng/patch_filter/patch_filter_protocol.py

@@ -0,0 +1,50 @@
+"""A protocol for patch filtering."""
+
+from collections.abc import Sequence
+from typing import Protocol
+
+import numpy as np
+
+
+class PatchFilterProtocol(Protocol):
+    """
+    An interface for implementing patch filtering strategies.
+    """
+
+    def filter_out(self, patch: np.ndarray) -> bool:
+        """
+        Determine whether to filter out a given patch.
+
+        Parameters
+        ----------
+        patch : numpy.NDArray
+            The image patch to evaluate.
+
+        Returns
+        -------
+        bool
+            True if the patch should be filtered out (excluded), False otherwise.
+        """
+        ...
+
+    @staticmethod
+    def filter_map(
+        image: np.ndarray,
+        patch_size: Sequence[int],
+    ) -> np.ndarray:
+        """
+        Compute a filter map for the entire image based on the patch filtering criteria.
+
+        Parameters
+        ----------
+        image : numpy.NDArray
+            The full image to evaluate.
+        patch_size : Sequence[int]
+            The size of the patches to consider.
+
+        Returns
+        -------
+        numpy.NDArray
+            A map where each element is the .
+        """
+        ...