careamics 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

careamics/transforms/compose.py

@@ -0,0 +1,107 @@
+"""A class chaining transforms together."""
+
+from typing import Dict, List, Optional, Tuple, cast
+
+import numpy as np
+
+from careamics.config.data_model import TRANSFORMS_UNION
+
+from .n2v_manipulate import N2VManipulate
+from .normalize import Normalize
+from .xy_flip import XYFlip
+from .xy_random_rotate90 import XYRandomRotate90
+
+ALL_TRANSFORMS = {
+    "Normalize": Normalize,
+    "N2VManipulate": N2VManipulate,
+    "XYFlip": XYFlip,
+    "XYRandomRotate90": XYRandomRotate90,
+}
+
+
+def get_all_transforms() -> Dict[str, type]:
+    """Return all the transforms accepted by CAREamics.
+
+    Returns
+    -------
+    dict
+        A dictionary with all the transforms accepted by CAREamics, where the keys are
+        the transform names and the values are the transform classes.
+    """
+    return ALL_TRANSFORMS
+
+
+class Compose:
+    """A class chaining transforms together.
+
+    Parameters
+    ----------
+    transform_list : List[TRANSFORMS_UNION]
+        A list of dictionaries where each dictionary contains the name of a
+        transform and its parameters.
+
+    Attributes
+    ----------
+    _callable_transforms : Callable
+        A callable that applies the transforms to the input data.
+    """
+
+    def __init__(self, transform_list: List[TRANSFORMS_UNION]) -> None:
+        """Instantiate a Compose object.
+
+        Parameters
+        ----------
+        transform_list : List[TRANSFORMS_UNION]
+            A list of dictionaries where each dictionary contains the name of a
+            transform and its parameters.
+        """
+        # retrieve all available transforms
+        all_transforms = get_all_transforms()
+
+        # instantiate all transforms
+        self.transforms = [
+            all_transforms[t.name](**t.model_dump()) for t in transform_list
+        ]
+
+    def _chain_transforms(
+        self, patch: np.ndarray, target: Optional[np.ndarray]
+    ) -> Tuple[np.ndarray, Optional[np.ndarray]]:
+        """Chain transforms on the input data.
+
+        Parameters
+        ----------
+        patch : np.ndarray
+            Input data.
+        target : Optional[np.ndarray]
+            Target data, by default None.
+
+        Returns
+        -------
+        Tuple[np.ndarray, Optional[np.ndarray]]
+            The output of the transformations.
+        """
+        params = (patch, target)
+
+        for t in self.transforms:
+            params = t(*params)
+
+        return params
+
+    def __call__(
+        self, patch: np.ndarray, target: Optional[np.ndarray] = None
+    ) -> Tuple[np.ndarray, ...]:
+        """Apply the transforms to the input data.
+
+        Parameters
+        ----------
+        patch : np.ndarray
+            The input data.
+        target : Optional[np.ndarray], optional
+            Target data, by default None.
+
+        Returns
+        -------
+        Tuple[np.ndarray, ...]
+            The output of the transformations.
+        """
+        return cast(Tuple[np.ndarray, ...], self._chain_transforms(patch, target))

careamics/transforms/n2v_manipulate.py

@@ -0,0 +1,146 @@
+"""N2V manipulation transform."""
+
+from typing import Any, Literal, Optional, Tuple
+
+import numpy as np
+
+from careamics.config.support import SupportedPixelManipulation, SupportedStructAxis
+from careamics.transforms.transform import Transform
+
+from .pixel_manipulation import median_manipulate, uniform_manipulate
+from .struct_mask_parameters import StructMaskParameters
+
+
+class N2VManipulate(Transform):
+    """
+    Default augmentation for the N2V model.
+
+    This transform expects C(Z)YX dimensions.
+
+    Parameters
+    ----------
+    roi_size : int, optional
+        Size of the replacement area, by default 11.
+    masked_pixel_percentage : float, optional
+        Percentage of pixels to mask, by default 0.2.
+    strategy : Literal[ "uniform", "median" ], optional
+        Replaccement strategy, uniform or median, by default uniform.
+    remove_center : bool, optional
+        Whether to remove central pixel from patch, by default True.
+    struct_mask_axis : Literal["horizontal", "vertical", "none"], optional
+        StructN2V mask axis, by default "none".
+    struct_mask_span : int, optional
+        StructN2V mask span, by default 5.
+    seed : Optional[int], optional
+        Random seed, by default None.
+
+    Attributes
+    ----------
+    masked_pixel_percentage : float
+        Percentage of pixels to mask.
+    roi_size : int
+        Size of the replacement area.
+    strategy : Literal[ "uniform", "median" ]
+        Replaccement strategy, uniform or median.
+    remove_center : bool
+        Whether to remove central pixel from patch.
+    struct_mask : Optional[StructMaskParameters]
+        StructN2V mask parameters.
+    rng : Generator
+        Random number generator.
+    """
+
+    def __init__(
+        self,
+        roi_size: int = 11,
+        masked_pixel_percentage: float = 0.2,
+        strategy: Literal[
+            "uniform", "median"
+        ] = SupportedPixelManipulation.UNIFORM.value,
+        remove_center: bool = True,
+        struct_mask_axis: Literal["horizontal", "vertical", "none"] = "none",
+        struct_mask_span: int = 5,
+        seed: Optional[int] = None,
+    ):
+        """Constructor.
+
+        Parameters
+        ----------
+        roi_size : int, optional
+            Size of the replacement area, by default 11.
+        masked_pixel_percentage : float, optional
+            Percentage of pixels to mask, by default 0.2.
+        strategy : Literal[ "uniform", "median" ], optional
+            Replaccement strategy, uniform or median, by default uniform.
+        remove_center : bool, optional
+            Whether to remove central pixel from patch, by default True.
+        struct_mask_axis : Literal["horizontal", "vertical", "none"], optional
+            StructN2V mask axis, by default "none".
+        struct_mask_span : int, optional
+            StructN2V mask span, by default 5.
+        seed : Optional[int], optional
+            Random seed, by default None.
+        """
+        self.masked_pixel_percentage = masked_pixel_percentage
+        self.roi_size = roi_size
+        self.strategy = strategy
+        self.remove_center = remove_center  # TODO is this ever used?
+
+        if struct_mask_axis == SupportedStructAxis.NONE:
+            self.struct_mask: Optional[StructMaskParameters] = None
+        else:
+            self.struct_mask = StructMaskParameters(
+                axis=0 if struct_mask_axis == SupportedStructAxis.HORIZONTAL else 1,
+                span=struct_mask_span,
+            )
+
+        # numpy random generator
+        self.rng = np.random.default_rng(seed=seed)
+
+    def __call__(
+        self, patch: np.ndarray, *args: Any, **kwargs: Any
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Apply the transform to the image.
+
+        Parameters
+        ----------
+        patch : np.ndarray
+            Image patch, 2D or 3D, shape C(Z)YX.
+        *args : Any
+            Additional arguments, unused.
+        **kwargs : Any
+            Additional keyword arguments, unused.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray, np.ndarray]
+            Masked patch, original patch, and mask.
+        """
+        masked = np.zeros_like(patch)
+        mask = np.zeros_like(patch)
+        if self.strategy == SupportedPixelManipulation.UNIFORM:
+            # Iterate over the channels to apply manipulation separately
+            for c in range(patch.shape[0]):
+                masked[c, ...], mask[c, ...] = uniform_manipulate(
+                    patch=patch[c, ...],
+                    mask_pixel_percentage=self.masked_pixel_percentage,
+                    subpatch_size=self.roi_size,
+                    remove_center=self.remove_center,
+                    struct_params=self.struct_mask,
+                    rng=self.rng,
+                )
+        elif self.strategy == SupportedPixelManipulation.MEDIAN:
+            # Iterate over the channels to apply manipulation separately
+            for c in range(patch.shape[0]):
+                masked[c, ...], mask[c, ...] = median_manipulate(
+                    patch=patch[c, ...],
+                    mask_pixel_percentage=self.masked_pixel_percentage,
+                    subpatch_size=self.roi_size,
+                    struct_params=self.struct_mask,
+                    rng=self.rng,
+                )
+        else:
+            raise ValueError(f"Unknown masking strategy ({self.strategy}).")
+
+        # TODO why return patch?
+        return masked, patch, mask

careamics/transforms/normalize.py

@@ -0,0 +1,243 @@
+"""Normalization and denormalization transforms for image patches."""
+
+from typing import Optional
+
+import numpy as np
+from numpy.typing import NDArray
+
+from careamics.transforms.transform import Transform
+
+
+def _reshape_stats(stats: list[float], ndim: int) -> NDArray:
+    """Reshape stats to match the number of dimensions of the input image.
+
+    This allows to broadcast the stats (mean or std) to the image dimensions, and
+    thus directly perform a vectorial calculation.
+
+    Parameters
+    ----------
+    stats : list of float
+        List of stats, mean or standard deviation.
+    ndim : int
+        Number of dimensions of the image, including the C channel.
+
+    Returns
+    -------
+    NDArray
+        Reshaped stats.
+    """
+    return np.array(stats)[(..., *[np.newaxis] * (ndim - 1))]
+
+
+class Normalize(Transform):
+    """
+    Normalize an image or image patch.
+
+    Normalization is a zero mean and unit variance. This transform expects C(Z)YX
+    dimensions.
+
+    Not that an epsilon value of 1e-6 is added to the standard deviation to avoid
+    division by zero and that it returns a float32 image.
+
+    Parameters
+    ----------
+    image_means : list of float
+        Mean value per channel.
+    image_stds : list of float
+        Standard deviation value per channel.
+    target_means : list of float, optional
+        Target mean value per channel, by default None.
+    target_stds : list of float, optional
+        Target standard deviation value per channel, by default None.
+
+    Attributes
+    ----------
+    image_means : list of float
+        Mean value per channel.
+    image_stds : list of float
+        Standard deviation value per channel.
+    target_means :list of float, optional
+        Target mean value per channel, by default None.
+    target_stds : list of float, optional
+        Target standard deviation value per channel, by default None.
+    """
+
+    def __init__(
+        self,
+        image_means: list[float],
+        image_stds: list[float],
+        target_means: Optional[list[float]] = None,
+        target_stds: Optional[list[float]] = None,
+    ):
+        """Constructor.
+
+        Parameters
+        ----------
+        image_means : list of float
+            Mean value per channel.
+        image_stds : list of float
+            Standard deviation value per channel.
+        target_means : list of float, optional
+            Target mean value per channel, by default None.
+        target_stds : list of float, optional
+            Target standard deviation value per channel, by default None.
+        """
+        self.image_means = image_means
+        self.image_stds = image_stds
+        self.target_means = target_means
+        self.target_stds = target_stds
+
+        self.eps = 1e-6
+
+    def __call__(
+        self, patch: np.ndarray, target: Optional[NDArray] = None
+    ) -> tuple[NDArray, Optional[NDArray]]:
+        """Apply the transform to the source patch and the target (optional).
+
+        Parameters
+        ----------
+        patch : NDArray
+            Patch, 2D or 3D, shape C(Z)YX.
+        target : NDArray, optional
+            Target for the patch, by default None.
+
+        Returns
+        -------
+        tuple of NDArray
+            Transformed patch and target, the target can be returned as `None`.
+        """
+        if len(self.image_means) != patch.shape[0]:
+            raise ValueError(
+                f"Number of means (got a list of size {len(self.image_means)}) and "
+                f"number of channels (got shape {patch.shape} for C(Z)YX) do not match."
+            )
+
+        # reshape mean and std and apply the normalization to the patch
+        means = _reshape_stats(self.image_means, patch.ndim)
+        stds = _reshape_stats(self.image_stds, patch.ndim)
+        norm_patch = self._apply(patch, means, stds)
+
+        # same for the target patch
+        if (
+            target is not None
+            and self.target_means is not None
+            and self.target_stds is not None
+        ):
+            target_means = _reshape_stats(self.target_means, target.ndim)
+            target_stds = _reshape_stats(self.target_stds, target.ndim)
+            norm_target = self._apply(target, target_means, target_stds)
+        else:
+            norm_target = None
+
+        return norm_patch, norm_target
+
+    def _apply(self, patch: NDArray, mean: NDArray, std: NDArray) -> NDArray:
+        """
+        Apply the transform to the image.
+
+        Parameters
+        ----------
+        patch : NDArray
+            Image patch, 2D or 3D, shape C(Z)YX.
+        mean : NDArray
+            Mean values.
+        std : NDArray
+            Standard deviations.
+
+        Returns
+        -------
+        NDArray
+            Normalized image patch.
+        """
+        return ((patch - mean) / (std + self.eps)).astype(np.float32)
+
+
+class Denormalize:
+    """
+    Denormalize an image.
+
+    Denormalization is performed expecting a zero mean and unit variance input. This
+    transform expects C(Z)YX dimensions.
+
+    Note that an epsilon value of 1e-6 is added to the standard deviation to avoid
+    division by zero during the normalization step, which is taken into account during
+    denormalization.
+
+    Parameters
+    ----------
+    image_means : list or tuple of float
+        Mean value per channel.
+    image_stds : list or tuple of float
+        Standard deviation value per channel.
+
+    """
+
+    def __init__(
+        self,
+        image_means: list[float],
+        image_stds: list[float],
+    ):
+        """Constructor.
+
+        Parameters
+        ----------
+        image_means : list of float
+            Mean value per channel.
+        image_stds : list of float
+            Standard deviation value per channel.
+        """
+        self.image_means = image_means
+        self.image_stds = image_stds
+
+        self.eps = 1e-6
+
+    def __call__(self, patch: NDArray) -> NDArray:
+        """Reverse the normalization operation for a batch of patches.
+
+        Parameters
+        ----------
+        patch : NDArray
+            Patch, 2D or 3D, shape BC(Z)YX.
+
+        Returns
+        -------
+        NDArray
+            Transformed array.
+        """
+        if len(self.image_means) != patch.shape[1]:
+            raise ValueError(
+                f"Number of means (got a list of size {len(self.image_means)}) and "
+                f"number of channels (got shape {patch.shape} for BC(Z)YX) do not "
+                f"match."
+            )
+
+        means = _reshape_stats(self.image_means, patch.ndim)
+        stds = _reshape_stats(self.image_stds, patch.ndim)
+
+        denorm_array = self._apply(
+            patch,
+            np.swapaxes(means, 0, 1),  # swap axes as C channel is axis 1
+            np.swapaxes(stds, 0, 1),
+        )
+
+        return denorm_array.astype(np.float32)
+
+    def _apply(self, array: NDArray, mean: NDArray, std: NDArray) -> NDArray:
+        """
+        Apply the transform to the image.
+
+        Parameters
+        ----------
+        array : NDArray
+            Image patch, 2D or 3D, shape C(Z)YX.
+        mean : NDArray
+            Mean values.
+        std : NDArray
+            Standard deviations.
+
+        Returns
+        -------
+        NDArray
+            Denormalized image array.
+        """
+        return array * (std + self.eps) + mean