careamics 0.0.19__py3-none-any.whl

careamics/config/noise_model/noise_model_config.py

@@ -0,0 +1,149 @@
+"""Noise models config."""
+
+from pathlib import Path
+from typing import Annotated, Literal, Self, Union
+
+import numpy as np
+import torch
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PlainSerializer,
+    PlainValidator,
+    model_validator,
+)
+
+from careamics.utils.serializers import _array_to_json, _to_numpy
+
+# TODO: this is a temporary solution to serialize and deserialize array fields
+# in pydantic models. Specifically, the aim is to enable saving and loading configs
+# with such arrays to/from JSON files during, resp., training and evaluation.
+Array = Annotated[
+    Union[np.ndarray, torch.Tensor],
+    PlainSerializer(_array_to_json, return_type=str),
+    PlainValidator(_to_numpy),
+]
+"""Annotated array type, used to serialize arrays or tensors to JSON strings
+and deserialize them back to arrays."""
+
+
+# TODO: add histogram-based noise model
+
+
+class GaussianMixtureNMConfig(BaseModel):
+    """Gaussian mixture noise model."""
+
+    model_config = ConfigDict(
+        protected_namespaces=(),
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+        extra="allow",
+    )
+    # model type
+    model_type: Literal["GaussianMixtureNoiseModel"] = "GaussianMixtureNoiseModel"
+
+    path: Union[Path, str] | None = None
+    """Path to the directory where the trained noise model (*.npz) is saved in the
+    `train` method."""
+
+    # TODO remove and use as parameters to the NM functions?
+    signal: Union[str, Path, np.ndarray] | None = Field(default=None, exclude=True)
+    """Path to the file containing signal or respective numpy array."""
+
+    # TODO remove and use as parameters to the NM functions?
+    observation: Union[str, Path, np.ndarray] | None = Field(default=None, exclude=True)
+    """Path to the file containing observation or respective numpy array."""
+
+    weight: Array | None = None
+    """A [3*n_gaussian, n_coeff] sized array containing the values of the weights
+    describing the GMM noise model, with each row corresponding to one
+    parameter of each gaussian, namely [mean, standard deviation and weight].
+    Specifically, rows are organized as follows:
+    - first n_gaussian rows correspond to the means
+    - next n_gaussian rows correspond to the weights
+    - last n_gaussian rows correspond to the standard deviations
+    If `weight=None`, the weight array is initialized using the `min_signal`
+    and `max_signal` parameters."""
+
+    n_gaussian: int = Field(default=1, ge=1)
+    """Number of gaussians used for the GMM."""
+
+    n_coeff: int = Field(default=2, ge=2)
+    """Number of coefficients to describe the functional relationship between gaussian
+    parameters and the signal. 2 implies a linear relationship, 3 implies a quadratic
+    relationship and so on."""
+
+    min_signal: float = Field(default=0.0, ge=0.0)
+    """Minimum signal intensity expected in the image."""
+
+    max_signal: float = Field(default=1.0, ge=0.0)
+    """Maximum signal intensity expected in the image."""
+
+    min_sigma: float = Field(default=200.0, ge=0.0)  # TODO took from nb in pn2v
+    """Minimum value of `standard deviation` allowed in the GMM.
+    All values of `standard deviation` below this are clamped to this value."""
+
+    tol: float = Field(default=1e-10)
+    """Tolerance used in the computation of the noise model likelihood."""
+
+    @model_validator(mode="after")
+    def validate_path(self: Self) -> Self:
+        """Validate that the path points to a valid .npz file if provided.
+
+        Returns
+        -------
+        Self
+            Returns itself.
+
+        Raises
+        ------
+        ValueError
+            If the path is provided but does not point to a valid .npz file.
+        """
+        if self.path is not None:
+            path = Path(self.path)
+            if not path.exists():
+                raise ValueError(f"Path {path} does not exist.")
+            if path.suffix != ".npz":
+                raise ValueError(f"Path {path} must point to a .npz file.")
+            if not path.is_file():
+                raise ValueError(f"Path {path} must point to a file.")
+        return self
+
+    # @model_validator(mode="after")
+    # def validate_path_to_pretrained_vs_training_data(self: Self) -> Self:
+    #     """Validate paths provided in the config.
+
+    #     Returns
+    #     -------
+    #     Self
+    #         Returns itself.
+    #     """
+    #     if self.path and (self.signal is not None or self.observation is not None):
+    #         raise ValueError(
+    #             "Either only 'path' to pre-trained noise model should be"
+    #             "provided or only signal and observation in form of paths"
+    #             "or numpy arrays."
+    #         )
+    #     if not self.path and (self.signal is None or self.observation is None):
+    #         raise ValueError(
+    #             "Either only 'path' to pre-trained noise model should be"
+    #             "provided or only signal and observation in form of paths"
+    #             "or numpy arrays."
+    #         )
+    #     return self
+    # TODO revisit validation
+
+
+# The noise model is given by a set of GMMs, one for each target
+# e.g., 2 target channels, 2 noise models
+class MultiChannelNMConfig(BaseModel):
+    """Noise Model config aggregating noise models for single output channels."""
+
+    # TODO: check that this model config is OK
+    model_config = ConfigDict(
+        validate_assignment=True, arbitrary_types_allowed=True, extra="allow"
+    )
+    noise_models: list[GaussianMixtureNMConfig]
+    """List of noise models, one for each target channel."""

careamics/config/support/__init__.py

@@ -0,0 +1,31 @@
+"""Supported configuration options.
+
+Used throughout the code to ensure consistency. These should be kept in sync with the
+corresponding configuration options in the Pydantic models.
+"""
+
+__all__ = [
+    "SupportedActivation",
+    "SupportedAlgorithm",
+    "SupportedArchitecture",
+    "SupportedData",
+    "SupportedLogger",
+    "SupportedLoss",
+    "SupportedOptimizer",
+    "SupportedPixelManipulation",
+    "SupportedScheduler",
+    "SupportedStructAxis",
+    "SupportedTransform",
+]
+
+
+from .supported_activations import SupportedActivation
+from .supported_algorithms import SupportedAlgorithm
+from .supported_architectures import SupportedArchitecture
+from .supported_data import SupportedData
+from .supported_loggers import SupportedLogger
+from .supported_losses import SupportedLoss
+from .supported_optimizers import SupportedOptimizer, SupportedScheduler
+from .supported_pixel_manipulations import SupportedPixelManipulation
+from .supported_struct_axis import SupportedStructAxis
+from .supported_transforms import SupportedTransform

careamics/config/support/supported_activations.py

@@ -0,0 +1,27 @@
+"""Activations supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedActivation(str, BaseEnum):
+    """Supported activation functions.
+
+    - None, no activation will be used.
+    - Sigmoid
+    - Softmax
+    - Tanh
+    - ReLU
+    - LeakyReLU
+
+    All activations are defined in PyTorch.
+
+    See: https://pytorch.org/docs/stable/nn.html#loss-functions
+    """
+
+    NONE = "None"
+    SIGMOID = "Sigmoid"
+    SOFTMAX = "Softmax"
+    TANH = "Tanh"
+    RELU = "ReLU"
+    LEAKYRELU = "LeakyReLU"
+    ELU = "ELU"

careamics/config/support/supported_algorithms.py

@@ -0,0 +1,40 @@
+"""Algorithms supported by CAREamics."""
+
+from __future__ import annotations
+
+from careamics.utils import BaseEnum
+
+
+class SupportedAlgorithm(str, BaseEnum):
+    """Algorithms available in CAREamics.
+
+    These definitions are the same as the keyword `name` of the algorithm
+    configurations.
+    """
+
+    N2V = "n2v"
+    """Noise2Void algorithm, a self-supervised approach based on blind denoising."""
+
+    CARE = "care"
+    """Content-aware image restoration, a supervised algorithm used for a variety
+    of tasks."""
+
+    N2N = "n2n"
+    """Noise2Noise algorithm, a self-supervised denoising scheme based on comparing
+    noisy images of the same sample."""
+
+    MUSPLIT = "musplit"  # TODO remove
+    """An image splitting approach based on ladder VAE architectures."""
+
+    MICROSPLIT = "microsplit"
+    """A micro-level image splitting approach based on ladder VAE architectures."""
+
+    DENOISPLIT = "denoisplit"
+    """An image splitting and denoising approach based on ladder VAE architectures."""
+
+    HDN = "hdn"
+    """Hierarchical Denoising Network, an unsupervised denoising algorithm"""
+
+    PN2V = "pn2v"
+    """Probabilistic Noise2Void. A extension of Noise2Void is not restricted to Gaussian
+    noise models or Gaussian intensity predictions."""

careamics/config/support/supported_architectures.py

@@ -0,0 +1,13 @@
+"""Architectures supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedArchitecture(str, BaseEnum):
+    """Supported architectures."""
+
+    UNET = "UNet"
+    """UNet architecture used with N2V, CARE and Noise2Noise."""
+
+    LVAE = "LVAE"
+    """Ladder Variational Autoencoder used for muSplit and denoiSplit."""

careamics/config/support/supported_data.py

@@ -0,0 +1,122 @@
+"""Data supported by CAREamics."""
+
+from __future__ import annotations
+
+from typing import Union
+
+from careamics.utils import BaseEnum
+
+
+class SupportedData(str, BaseEnum):
+    """Supported data types.
+
+    Attributes
+    ----------
+    ARRAY : str
+        Array data.
+    TIFF : str
+        TIFF image data.
+    CZI : str
+        CZI image data.
+    ZARR : str
+        Zarr data.
+    CUSTOM : str
+        Custom data.
+    """
+
+    ARRAY = "array"
+    TIFF = "tiff"
+    CZI = "czi"
+    CUSTOM = "custom"
+    ZARR = "zarr"
+
+    # TODO remove?
+    @classmethod
+    def _missing_(cls, value: object) -> str:
+        """
+        Override default behaviour for missing values.
+
+        This method is called when `value` is not found in the enum values. It converts
+        `value` to lowercase, removes "." if it is the first character and tries to
+        match it with enum values.
+
+        Parameters
+        ----------
+        value : object
+            Value to be matched with enum values.
+
+        Returns
+        -------
+        str
+            Matched enum value.
+        """
+        if isinstance(value, str):
+            lower_value = value.lower()
+
+            if lower_value.startswith("."):
+                lower_value = lower_value[1:]
+
+            # attempt to match lowercase value with enum values
+            for member in cls:
+                if member.value == lower_value:
+                    return member
+
+        # still missing
+        return super()._missing_(value)
+
+    @classmethod
+    def get_extension_pattern(cls, data_type: Union[str, SupportedData]) -> str:
+        """
+        Get Path.rglob and fnmatch compatible extension.
+
+        Parameters
+        ----------
+        data_type : SupportedData
+            Data type.
+
+        Returns
+        -------
+        str
+            Corresponding extension pattern.
+        """
+        if data_type == cls.ARRAY:
+            raise NotImplementedError(f"Data '{data_type}' is not loaded from a file.")
+        elif data_type == cls.TIFF:
+            return "*.tif*"
+        elif data_type == cls.ZARR:
+            return "*.zarr"
+        elif data_type == cls.CZI:
+            return "*.czi"
+        elif data_type == cls.CUSTOM:
+            return "*.*"
+        else:
+            raise ValueError(f"Data type {data_type} is not supported.")
+
+    @classmethod
+    def get_extension(cls, data_type: Union[str, SupportedData]) -> str:
+        """
+        Get file extension of corresponding data type.
+
+        Parameters
+        ----------
+        data_type : str or SupportedData
+            Data type.
+
+        Returns
+        -------
+        str
+            Corresponding extension.
+        """
+        if data_type == cls.ARRAY:
+            raise NotImplementedError(f"Data '{data_type}' is not loaded from a file.")
+        elif data_type == cls.TIFF:
+            return ".tiff"
+        elif data_type == cls.CZI:
+            return ".czi"
+        elif data_type == cls.ZARR:
+            return ".zarr"
+        elif data_type == cls.CUSTOM:
+            # TODO: improve this message
+            raise NotImplementedError("Custom extensions have to be passed elsewhere.")
+        else:
+            raise ValueError(f"Data type {data_type} is not supported.")

careamics/config/support/supported_filters.py

@@ -0,0 +1,17 @@
+"""Coordinate and patch filters supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedPatchFilters(str, BaseEnum):
+    """Supported patch filters."""
+
+    MAX = "max"
+    MEANSTD = "mean_std"
+    SHANNON = "shannon"
+
+
+class SupportedCoordinateFilters(str, BaseEnum):
+    """Supported coordinate filters."""
+
+    MASK = "mask"

careamics/config/support/supported_loggers.py

@@ -0,0 +1,10 @@
+"""Logger supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedLogger(str, BaseEnum):
+    """Available loggers."""
+
+    WANDB = "wandb"
+    TENSORBOARD = "tensorboard"

careamics/config/support/supported_losses.py

@@ -0,0 +1,32 @@
+"""Losses supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+# TODO register loss with custom_loss decorator?
+class SupportedLoss(str, BaseEnum):
+    """Supported losses.
+
+    Attributes
+    ----------
+    MSE : str
+        Mean Squared Error loss.
+    MAE : str
+        Mean Absolute Error loss.
+    N2V : str
+        Noise2Void loss.
+    """
+
+    MSE = "mse"
+    MAE = "mae"
+    N2V = "n2v"
+    PN2V = "pn2v"
+    HDN = "hdn"
+    MUSPLIT = "musplit"
+    MICROSPLIT = "microsplit"
+    DENOISPLIT = "denoisplit"
+    DENOISPLIT_MUSPLIT = (
+        "denoisplit_musplit"  # TODO refac losses, leave only microsplit
+    )
+    # CE = "ce"
+    # DICE = "dice"

careamics/config/support/supported_optimizers.py

@@ -0,0 +1,57 @@
+"""Optimizers and schedulers supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedOptimizer(str, BaseEnum):
+    """Supported optimizers.
+
+    Attributes
+    ----------
+    Adam : str
+        Adam optimizer.
+    SGD : str
+        Stochastic Gradient Descent optimizer.
+    """
+
+    # ASGD = "ASGD"
+    # Adadelta = "Adadelta"
+    # Adagrad = "Adagrad"
+    ADAM = "Adam"
+    # AdamW = "AdamW"
+    ADAMAX = "Adamax"
+    # LBFGS = "LBFGS"
+    # NAdam = "NAdam"
+    # RAdam = "RAdam"
+    # RMSprop = "RMSprop"
+    # Rprop = "Rprop"
+    SGD = "SGD"
+    # SparseAdam = "SparseAdam"
+
+
+class SupportedScheduler(str, BaseEnum):
+    """Supported schedulers.
+
+    Attributes
+    ----------
+    ReduceLROnPlateau : str
+        Reduce learning rate on plateau.
+    StepLR : str
+        Step learning rate.
+    """
+
+    # ChainedScheduler = "ChainedScheduler"
+    # ConstantLR = "ConstantLR"
+    # CosineAnnealingLR = "CosineAnnealingLR"
+    # CosineAnnealingWarmRestarts = "CosineAnnealingWarmRestarts"
+    # CyclicLR = "CyclicLR"
+    # ExponentialLR = "ExponentialLR"
+    # LambdaLR = "LambdaLR"
+    # LinearLR = "LinearLR"
+    # MultiStepLR = "MultiStepLR"
+    # MultiplicativeLR = "MultiplicativeLR"
+    # OneCycleLR = "OneCycleLR"
+    # PolynomialLR = "PolynomialLR"
+    REDUCE_LR_ON_PLATEAU = "ReduceLROnPlateau"
+    # SequentialLR = "SequentialLR"
+    STEP_LR = "StepLR"

careamics/config/support/supported_patching_strategies.py

@@ -0,0 +1,22 @@
+"""Patching strategies supported by Careamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedPatchingStrategy(str, BaseEnum):
+    """Patching strategies supported by Careamics."""
+
+    FIXED_RANDOM = "fixed_random"
+    """Fixed random patching strategy, used during training."""
+
+    RANDOM = "random"
+    """Random patching strategy, used during training."""
+
+    # SEQUENTIAL = "sequential"
+    # """Sequential patching strategy, used during training."""
+
+    TILED = "tiled"
+    """Tiled patching strategy, used during prediction."""
+
+    WHOLE = "whole"
+    """Whole image patching strategy, used during prediction."""

careamics/config/support/supported_pixel_manipulations.py

@@ -0,0 +1,15 @@
+"""Pixel manipulation methods supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedPixelManipulation(str, BaseEnum):
+    """Supported Noise2Void pixel manipulations.
+
+    - Uniform: Replace masked pixel value by a (uniformly) randomly selected neighbor
+        pixel value.
+    - Median: Replace masked pixel value by the mean of the neighborhood.
+    """
+
+    UNIFORM = "uniform"
+    MEDIAN = "median"

careamics/config/support/supported_struct_axis.py

@@ -0,0 +1,21 @@
+"""StructN2V axes supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedStructAxis(str, BaseEnum):
+    """Supported structN2V mask axes.
+
+    Attributes
+    ----------
+    HORIZONTAL : str
+        Horizontal axis.
+    VERTICAL : str
+        Vertical axis.
+    NONE : str
+        No axis, the mask is not applied.
+    """
+
+    HORIZONTAL = "horizontal"
+    VERTICAL = "vertical"
+    NONE = "none"

careamics/config/support/supported_transforms.py

@@ -0,0 +1,12 @@
+"""Transforms supported by CAREamics."""
+
+from careamics.utils import BaseEnum
+
+
+class SupportedTransform(str, BaseEnum):
+    """Transforms officially supported by CAREamics."""
+
+    XY_FLIP = "XYFlip"
+    XY_RANDOM_ROTATE90 = "XYRandomRotate90"
+    NORMALIZE = "Normalize"
+    N2V_MANIPULATE = "N2VManipulate"

careamics/config/transformations/__init__.py

@@ -0,0 +1,22 @@
+"""CAREamics transformation Pydantic models."""
+
+__all__ = [
+    "NORM_AND_SPATIAL_UNION",
+    "SPATIAL_TRANSFORMS_UNION",
+    "N2VManipulateConfig",
+    "NormalizeConfig",
+    "TransformConfig",
+    "XYFlipConfig",
+    "XYRandomRotate90Config",
+]
+
+
+from .n2v_manipulate_config import N2VManipulateConfig
+from .normalize_config import NormalizeConfig
+from .transform_config import TransformConfig
+from .transform_unions import (
+    NORM_AND_SPATIAL_UNION,
+    SPATIAL_TRANSFORMS_UNION,
+)
+from .xy_flip_config import XYFlipConfig
+from .xy_random_rotate90_config import XYRandomRotate90Config

careamics/config/transformations/n2v_manipulate_config.py

@@ -0,0 +1,79 @@
+"""Pydantic model for the N2VManipulate transform."""
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field, field_validator
+
+from .transform_config import TransformConfig
+
+
+# TODO should probably not be a TransformConfig anymore, no reason for it
+# `name` is used as a discriminator field in the transforms
+class N2VManipulateConfig(TransformConfig):
+    """
+    Pydantic model used to represent N2V manipulation.
+
+    Attributes
+    ----------
+    name : Literal["N2VManipulate"]
+        Name of the transformation.
+    roi_size : int
+        Size of the masking region, by default 11.
+    masked_pixel_percentage : float
+        Percentage of masked pixels, by default 0.2.
+    strategy : Literal["uniform", "median"]
+        Strategy pixel value replacement, by default "uniform".
+    struct_mask_axis : Literal["horizontal", "vertical", "none"]
+        Axis of the structN2V mask, by default "none".
+    struct_mask_span : int
+        Span of the structN2V mask, by default 5.
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+    )
+
+    name: Literal["N2VManipulate"] = "N2VManipulate"
+
+    roi_size: int = Field(default=11, ge=3, le=21)
+    """Size of the region where the pixel manipulation is applied."""
+
+    masked_pixel_percentage: float = Field(default=0.2, ge=0.05, le=10.0)
+    """Percentage of masked pixels per image."""
+
+    remove_center: bool = Field(default=True)  # TODO remove it
+    """Exclude center pixel from average calculation."""  # TODO rephrase this
+
+    strategy: Literal["uniform", "median"] = Field(default="uniform")
+    """Strategy for pixel value replacement."""
+
+    struct_mask_axis: Literal["horizontal", "vertical", "none"] = Field(default="none")
+    """Orientation of the structN2V mask. Set to `\"non\"` to not apply StructN2V."""
+
+    struct_mask_span: int = Field(default=5, ge=3, le=15)
+    """Size of the structN2V mask."""
+
+    @field_validator("roi_size", "struct_mask_span")
+    @classmethod
+    def odd_value(cls, v: int) -> int:
+        """
+        Validate that the value is odd.
+
+        Parameters
+        ----------
+        v : int
+            Value to validate.
+
+        Returns
+        -------
+        int
+            The validated value.
+
+        Raises
+        ------
+        ValueError
+            If the value is even.
+        """
+        if v % 2 == 0:
+            raise ValueError("Size must be an odd number.")
+        return v