careamics 0.0.16__py3-none-any.whl → 0.0.17__py3-none-any.whl

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.patch_extractor.patch_extractor_factory import (
+    create_array_extractor,
+)
+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)
+
+        extractor = create_array_extractor(source=[image], axes=axes)
+        tiling = TilingStrategy(
+            data_shapes=[(1, 1, *image.shape)],
+            tile_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.patch_extractor.patch_extractor_factory import (
+    create_array_extractor,
+)
+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)
+
+        extractor = create_array_extractor(source=[image], axes=axes)
+        tiling = TilingStrategy(
+            data_shapes=[(1, 1, *image.shape)],
+            tile_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 .
+        """
+        ...

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.patch_extractor.patch_extractor_factory import (
+    create_array_extractor,
+)
+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)
+
+        extractor = create_array_extractor(source=[image], axes=axes)
+        tiling = TilingStrategy(
+            data_shapes=[(1, 1, *image.shape)],
+            tile_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/lightning/callbacks/data_stats_callback.py

@@ -7,12 +7,22 @@ from pytorch_lightning.callbacks import Callback
 class DataStatsCallback(Callback):
     """Callback to update model's data statistics from datamodule.
 
-    This callback ensures that the model has access to the data statistics (mean and std)
-    calculated by the datamodule before training starts.
+    This callback ensures that the model has access to the data statistics (mean and
+    std) calculated by the datamodule before training starts.
     """
 
     def setup(self, trainer: L.Trainer, module: L.LightningModule, stage: str) -> None:
-        """Called when trainer is setting up."""
+        """Called when trainer is setting up.
+
+        Parameters
+        ----------
+        trainer : Lightning.Trainer
+            The trainer instance.
+        module : Lightning.LightningModule
+            The model being trained.
+        stage : str
+            The current stage of training (e.g., 'fit', 'validate', 'test', 'predict').
+        """
         if stage == "fit":
             # Get data statistics from datamodule
             (data_mean, data_std), _ = trainer.datamodule.get_data_stats()