careamics 0.1.0rc2__py3-none-any.whl → 0.1.0rc3__py3-none-any.whl

careamics/config/references/algorithm_descriptions.py

@@ -0,0 +1,131 @@
+"""Descriptions of the algorithms used in CAREmics."""
+from pydantic import BaseModel
+
+CUSTOM = "Custom"
+N2V = "Noise2Void"
+N2V2 = "N2V2"
+STRUCT_N2V = "StructN2V"
+STRUCT_N2V2 = "StructN2V2"
+N2N = "Noise2Noise"
+CARE = "CARE"
+
+
+N2V_DESCRIPTION = (
+    "Noise2Void is a UNet-based self-supervised algorithm that "
+    "uses blind-spot training to denoise images. In short, in every "
+    "patches during training, random pixels are selected and their "
+    "value replaced by a neighboring pixel value. The network is then "
+    "trained to predict the original pixel value. The algorithm "
+    "relies on the continuity of the signal (neighboring pixels have "
+    "similar values) and the pixel-wise independence of the noise "
+    "(the noise in a pixel is not correlated with the noise in "
+    "neighboring pixels)."
+)
+
+
+class AlgorithmDescription(BaseModel):
+    """Description of an algorithm.
+
+    Attributes
+    ----------
+    description : str
+        Description of the algorithm.
+    """
+
+    description: str
+
+
+class N2VDescription(AlgorithmDescription):
+    """Description of Noise2Void.
+
+    Attributes
+    ----------
+    description : str
+        Description of Noise2Void.
+    """
+
+    description: str = N2V_DESCRIPTION
+
+
+class N2V2Description(AlgorithmDescription):
+    """Description of N2V2.
+
+    Attributes
+    ----------
+    description : str
+        Description of N2V2.
+    """
+
+    description: str = (
+        "N2V2 is a variant of Noise2Void. "
+        + N2V_DESCRIPTION
+        + "\nN2V2 introduces blur-pool layers and removed skip "
+        "connections in the UNet architecture to remove checkboard "
+        "artefacts, a common artefacts ocurring in Noise2Void."
+    )
+
+
+class StructN2VDescription(AlgorithmDescription):
+    """Description of StructN2V.
+
+    Attributes
+    ----------
+    description : str
+        Description of StructN2V.
+    """
+
+    description: str = (
+        "StructN2V is a variant of Noise2Void. "
+        + N2V_DESCRIPTION
+        + "\nStructN2V uses a linear mask (horizontal or vertical) to replace "
+        "the pixel values of neighbors of the masked pixels by a random "
+        "value. Such masking allows removing 1D structured noise from the "
+        "the images, the main failure case of the original N2V."
+    )
+
+
+class StructN2V2Description(AlgorithmDescription):
+    """Description of StructN2V2.
+
+    Attributes
+    ----------
+    description : str
+        Description of StructN2V2.
+    """
+
+    description: str = (
+        "StructN2V2 is a a variant of Noise2Void that uses both "
+        "structN2V and N2V2. "
+        + N2V_DESCRIPTION
+        + "\nStructN2V2 uses a linear mask (horizontal or vertical) to replace "
+        "the pixel values of neighbors of the masked pixels by a random "
+        "value. Such masking allows removing 1D structured noise from the "
+        "the images, the main failure case of the original N2V."
+        "\nN2V2 introduces blur-pool layers and removed skip connections in "
+        "the UNet architecture to remove checkboard artefacts, a common "
+        "artefacts ocurring in Noise2Void."
+    )
+
+
+class N2NDescription(AlgorithmDescription):
+    """Description of Noise2Noise.
+
+    Attributes
+    ----------
+    description : str
+        Description of Noise2Noise.
+    """
+
+    description: str = "Noise2Noise"  # TODO
+
+
+class CAREDescription(AlgorithmDescription):
+    """Description of CARE.
+
+    Attributes
+    ----------
+    description : str
+        Description of CARE.
+    """
+
+    description: str = "CARE"  # TODO

careamics/config/references/references.py

@@ -0,0 +1,38 @@
+"""References for the CAREamics algorithms."""
+from bioimageio.spec.generic.v0_3 import CiteEntry
+
+N2VRef = CiteEntry(
+    text='Krull, A., Buchholz, T.O. and Jug, F., 2019. "Noise2Void - Learning '
+    'denoising from single noisy images". In Proceedings of the IEEE/CVF '
+    "conference on computer vision and pattern recognition (pp. 2129-2137).",
+    doi="10.1109/cvpr.2019.00223",
+)
+
+N2V2Ref = CiteEntry(
+    text="Höck, E., Buchholz, T.O., Brachmann, A., Jug, F. and Freytag, A., "
+    '2022. "N2V2 - Fixing Noise2Void checkerboard artifacts with modified '
+    'sampling strategies and a tweaked network architecture". In European '
+    "Conference on Computer Vision (pp. 503-518).",
+    doi="10.1007/978-3-031-25069-9_33",
+)
+
+StructN2VRef = CiteEntry(
+    text="Broaddus, C., Krull, A., Weigert, M., Schmidt, U. and Myers, G., 2020."
+    '"Removing structured noise with self-supervised blind-spot '
+    'networks". In 2020 IEEE 17th International Symposium on Biomedical '
+    "Imaging (ISBI) (pp. 159-163).",
+    doi="10.1109/isbi45749.2020.9098336",
+)
+
+N2NRef = CiteEntry(
+    text="Lehtinen, J., Munkberg, J., Hasselgren, J., Laine, S., Karras, T., "
+    'Aittala, M. and Aila, T., 2018. "Noise2Noise: Learning image restoration '
+    'without clean data". arXiv preprint arXiv:1803.04189.',
+    doi="10.48550/arXiv.1803.04189",
+)
+
+CARERef = CiteEntry(
+    text='Weigert, Martin, et al. "Content-aware image restoration: pushing the '
+    'limits of fluorescence microscopy." Nature methods 15.12 (2018): 1090-1097.',
+    doi="10.1038/s41592-018-0216-7",
+)

careamics/config/support/__init__.py

@@ -0,0 +1,33 @@
+"""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__ = [
+    "SupportedArchitecture",
+    "SupportedActivation",
+    "SupportedOptimizer",
+    "SupportedScheduler",
+    "SupportedLoss",
+    "SupportedAlgorithm",
+    "SupportedPixelManipulation",
+    "SupportedTransform",
+    "SupportedData",
+    "SupportedExtractionStrategy",
+    "SupportedStructAxis",
+    "SupportedLogger",
+]
+
+
+from .supported_activations import SupportedActivation
+from .supported_algorithms import SupportedAlgorithm
+from .supported_architectures import SupportedArchitecture
+from .supported_data import SupportedData
+from .supported_extraction_strategies import SupportedExtractionStrategy
+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,24 @@
+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"

careamics/config/support/supported_algorithms.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from careamics.utils import BaseEnum
+
+
+class SupportedAlgorithm(str, BaseEnum):
+    """Algorithms available in CAREamics.
+
+    # TODO
+    """
+
+    N2V = "n2v"
+    CUSTOM = "custom"
+    CARE = "care"
+    N2N = "n2n"
+    # PN2V = "pn2v"
+    # HDN = "hdn"
+    # SEG = "segmentation"

careamics/config/support/supported_architectures.py

@@ -0,0 +1,18 @@
+from careamics.utils import BaseEnum
+
+
+class SupportedArchitecture(str, BaseEnum):
+    """Supported architectures.
+
+    # TODO add details, in particular where to find the API for the models
+
+    - UNet: classical UNet compatible with N2V2
+    - VAE: variational Autoencoder
+    - Custom: custom model registered with `@register_model` decorator
+    """
+
+    UNET = "UNet"
+    VAE = "VAE"
+    CUSTOM = (
+        "Custom"  # TODO all the others tags are small letters, except the architect
+    )

careamics/config/support/supported_data.py

@@ -0,0 +1,82 @@
+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.
+    CUSTOM : str
+        Custom data.
+    """
+
+    ARRAY = "array"
+    TIFF = "tiff"
+    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(cls, data_type: Union[str, SupportedData]) -> str:
+        """
+        Path.rglob and fnmatch compatible extension.
+
+        Parameters
+        ----------
+        data_type : SupportedData
+            Data type.
+
+        Returns
+        -------
+        str
+            Corresponding extension.
+        """
+        if data_type == cls.ARRAY:
+            raise NotImplementedError(f"Data {data_type} are not loaded from file.")
+        elif data_type == cls.TIFF:
+            return "*.tif*"
+        elif data_type == cls.CUSTOM:
+            return "*.*"
+        else:
+            raise ValueError(f"Data type {data_type} is not supported.")

careamics/{dataset/extraction_strategy.py → config/support/supported_extraction_strategies.py}

@@ -3,19 +3,22 @@ Extraction strategy module.
 
 This module defines the various extraction strategies available in CAREamics.
 """
-from enum import Enum
+from careamics.utils import BaseEnum
 
 
-class ExtractionStrategy(str, Enum):
+class SupportedExtractionStrategy(str, BaseEnum):
     """
     Available extraction strategies.
 
     Currently supported:
         - random: random extraction.
+        # TODO
         - sequential: grid extraction, can miss edge values.
         - tiled: tiled extraction, covers the whole image.
     """
 
     RANDOM = "random"
+    RANDOM_ZARR = "random_zarr"
     SEQUENTIAL = "sequential"
     TILED = "tiled"
+    NONE = "none"

careamics/config/support/supported_loggers.py

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

careamics/config/support/supported_losses.py

@@ -0,0 +1,25 @@
+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"
+    # CE = "ce"
+    # DICE = "dice"
+    # CUSTOM = "custom" # TODO create mechanism for that

careamics/config/support/supported_optimizers.py

@@ -0,0 +1,55 @@
+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"
+    ReduceLROnPlateau = "ReduceLROnPlateau"
+    # SequentialLR = "SequentialLR"
+    StepLR = "StepLR"

careamics/config/support/supported_pixel_manipulations.py

@@ -0,0 +1,15 @@
+from careamics.utils import BaseEnum
+
+
+class SupportedPixelManipulation(str, BaseEnum):
+    """_summary_.
+
+    - Uniform: Replace masked pixel value by a (uniformly) randomly selected neighbor
+        pixel value.
+    - Median: Replace masked pixel value by the mean of the neighborhood.
+    """
+
+    # TODO docs
+
+    UNIFORM = "uniform"
+    MEDIAN = "median"

careamics/config/support/supported_struct_axis.py

@@ -0,0 +1,19 @@
+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,23 @@
+from careamics.utils import BaseEnum
+
+
+class SupportedTransform(str, BaseEnum):
+    """Transforms officially supported by CAREamics.
+
+    - Flip: from Albumentations, randomly flip the input horizontally, vertically or
+        both, parameter `p` can be used to set the probability to apply the transform.
+    - XYRandomRotate90: #TODO
+    - Normalize # TODO add details, in particular about the parameters
+    - ManipulateN2V # TODO add details, in particular about the parameters
+    - NDFlip
+
+    Note that while any Albumentations (see https://albumentations.ai/) transform can be
+    used in CAREamics, no check are implemented to verify the compatibility of any other
+    transforms than the ones officially supported.
+    """
+
+    NDFLIP = "NDFlip"
+    XY_RANDOM_ROTATE90 = "XYRandomRotate90"
+    NORMALIZE = "Normalize"
+    N2V_MANIPULATE = "N2VManipulate"
+    # CUSTOM = "Custom"

careamics/config/tile_information.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+
+class TileInformation(BaseModel):
+    """
+    Pydantic model containing tile information.
+
+    This model is used to represent the information required to stitch back a tile into
+    a larger image. It is used throughout the prediction pipeline of CAREamics.
+    """
+
+    model_config = ConfigDict(validate_default=True)
+
+    array_shape: Tuple[int, ...]
+    tiled: bool = False
+    last_tile: bool = False
+    overlap_crop_coords: Optional[Tuple[Tuple[int, ...], ...]] = Field(default=None)
+    stitch_coords: Optional[Tuple[Tuple[int, ...], ...]] = Field(default=None)
+
+    @field_validator("array_shape")
+    @classmethod
+    def no_singleton_dimensions(cls, v: Tuple[int, ...]):
+        """
+        Check that the array shape does not have any singleton dimensions.
+
+        Parameters
+        ----------
+        v : Tuple[int, ...]
+            Array shape to check.
+
+        Returns
+        -------
+        Tuple[int, ...]
+            The array shape if it does not contain singleton dimensions.
+
+        Raises
+        ------
+        ValueError
+            If the array shape contains singleton dimensions.
+        """
+        if any(dim == 1 for dim in v):
+            raise ValueError("Array shape must not contain singleton dimensions.")
+        return v
+
+    @field_validator("last_tile")
+    @classmethod
+    def only_if_tiled(cls, v: bool, values: ValidationInfo):
+        """
+        Check that the last tile flag is only set if tiling is enabled.
+
+        Parameters
+        ----------
+        v : bool
+            Last tile flag.
+        values : ValidationInfo
+            Validation information.
+
+        Returns
+        -------
+        bool
+            The last tile flag.
+        """
+        if not values.data["tiled"]:
+            return False
+        return v
+
+    @field_validator("overlap_crop_coords", "stitch_coords")
+    @classmethod
+    def mandatory_if_tiled(
+        cls, v: Optional[Tuple[int, ...]], values: ValidationInfo
+    ) -> Optional[Tuple[int, ...]]:
+        """
+        Check that the coordinates are not `None` if tiling is enabled.
+
+        The method also return `None` if tiling is not enabled.
+
+        Parameters
+        ----------
+        v : Optional[Tuple[int, ...]]
+            Coordinates to check.
+        values : ValidationInfo
+            Validation information.
+
+        Returns
+        -------
+        Optional[Tuple[int, ...]]
+            The coordinates if tiling is enabled, otherwise `None`.
+
+        Raises
+        ------
+        ValueError
+            If the coordinates are `None` and tiling is enabled.
+        """
+        if values.data["tiled"]:
+            if v is None:
+                raise ValueError("Value must be specified if tiling is enabled.")
+
+            return v
+        else:
+            return None