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

careamics/config/support/supported_algorithms.py

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

careamics/config/support/supported_architectures.py

@@ -0,0 +1,20 @@
+"""Architectures supported by CAREamics."""
+
+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,109 @@
+"""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.
+    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_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.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.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_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,27 @@
+"""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"
+    # CE = "ce"
+    # DICE = "dice"
+    # CUSTOM = "custom" # TODO create mechanism for that

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_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,11 @@
+"""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"
+    N2V_MANIPULATE = "N2VManipulate"

careamics/config/tile_information.py

@@ -0,0 +1,65 @@
+"""Pydantic model representing the metadata of a prediction tile."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from annotated_types import Len
+from pydantic import BaseModel, ConfigDict
+
+DimTuple = Annotated[tuple, Len(min_length=3, max_length=4)]
+
+
+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.
+
+    Array shape should be C(Z)YX, where Z is an optional dimensions.
+    """
+
+    model_config = ConfigDict(validate_default=True)
+
+    array_shape: DimTuple  # TODO: find a way to add custom error message?
+    """Shape of the original (untiled) array."""
+
+    last_tile: bool = False
+    """Whether this tile is the last one of the array."""
+
+    overlap_crop_coords: tuple[tuple[int, ...], ...]
+    """Inner coordinates of the tile where to crop the prediction in order to stitch
+    it back into the original image."""
+
+    stitch_coords: tuple[tuple[int, ...], ...]
+    """Coordinates in the original image where to stitch the cropped tile back."""
+
+    sample_id: int
+    """Sample ID of the tile."""
+
+    # TODO: Test that ZYX axes are not singleton ?
+
+    def __eq__(self, other_tile: object):
+        """Check if two tile information objects are equal.
+
+        Parameters
+        ----------
+        other_tile : object
+            Tile information object to compare with.
+
+        Returns
+        -------
+        bool
+            Whether the two tile information objects are equal.
+        """
+        if not isinstance(other_tile, TileInformation):
+            return NotImplemented
+
+        return (
+            self.array_shape == other_tile.array_shape
+            and self.last_tile == other_tile.last_tile
+            and self.overlap_crop_coords == other_tile.overlap_crop_coords
+            and self.stitch_coords == other_tile.stitch_coords
+            and self.sample_id == other_tile.sample_id
+        )

careamics/config/training_model.py

@@ -0,0 +1,72 @@
+"""Training configuration."""
+
+from __future__ import annotations
+
+from pprint import pformat
+from typing import Literal, Optional
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+from .callback_model import CheckpointModel, EarlyStoppingModel
+
+
+class TrainingConfig(BaseModel):
+    """
+    Parameters related to the training.
+
+    Mandatory parameters are:
+        - num_epochs: number of epochs, greater than 0.
+        - batch_size: batch size, greater than 0.
+        - augmentation: whether to use data augmentation or not (True or False).
+
+    Attributes
+    ----------
+    num_epochs : int
+        Number of epochs, greater than 0.
+    """
+
+    # Pydantic class configuration
+    model_config = ConfigDict(
+        validate_assignment=True,
+    )
+
+    num_epochs: int = Field(default=20, ge=1)
+    """Number of epochs, greater than 0."""
+
+    logger: Optional[Literal["wandb", "tensorboard"]] = None
+    """Logger to use during training. If None, no logger will be used. Available
+    loggers are defined in SupportedLogger."""
+
+    checkpoint_callback: CheckpointModel = CheckpointModel()
+    """Checkpoint callback configuration, following PyTorch Lightning Checkpoint
+    callback."""
+
+    early_stopping_callback: Optional[EarlyStoppingModel] = Field(
+        default=None, validate_default=True
+    )
+    """Early stopping callback configuration, following PyTorch Lightning Checkpoint
+    callback."""
+
+    def __str__(self) -> str:
+        """Pretty string reprensenting the configuration.
+
+        Returns
+        -------
+        str
+            Pretty string.
+        """
+        return pformat(self.model_dump())
+
+    def has_logger(self) -> bool:
+        """Check if the logger is defined.
+
+        Returns
+        -------
+        bool
+            Whether the logger is defined or not.
+        """
+        return self.logger is not None

careamics/config/transformations/__init__.py

@@ -0,0 +1,15 @@
+"""CAREamics transformation Pydantic models."""
+
+__all__ = [
+    "N2VManipulateModel",
+    "XYFlipModel",
+    "NormalizeModel",
+    "XYRandomRotate90Model",
+    "XorYFlipModel",
+]
+
+
+from .n2v_manipulate_model import N2VManipulateModel
+from .normalize_model import NormalizeModel
+from .xy_flip_model import XYFlipModel
+from .xy_random_rotate90_model import XYRandomRotate90Model

careamics/config/transformations/n2v_manipulate_model.py

@@ -0,0 +1,64 @@
+"""Pydantic model for the N2VManipulate transform."""
+
+from typing import Literal
+
+from pydantic import ConfigDict, Field, field_validator
+
+from .transform_model import TransformModel
+
+
+class N2VManipulateModel(TransformModel):
+    """
+    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)
+    masked_pixel_percentage: float = Field(default=0.2, ge=0.05, le=1.0)
+    strategy: Literal["uniform", "median"] = Field(default="uniform")
+    struct_mask_axis: Literal["horizontal", "vertical", "none"] = Field(default="none")
+    struct_mask_span: int = Field(default=5, ge=3, le=15)
+
+    @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

careamics/config/transformations/normalize_model.py

@@ -0,0 +1,60 @@
+"""Pydantic model for the Normalize transform."""
+
+from typing import Literal, Optional
+
+from pydantic import ConfigDict, Field, model_validator
+from typing_extensions import Self
+
+from .transform_model import TransformModel
+
+
+class NormalizeModel(TransformModel):
+    """
+    Pydantic model used to represent Normalize transformation.
+
+    The Normalize transform is a zero mean and unit variance transformation.
+
+    Attributes
+    ----------
+    name : Literal["Normalize"]
+        Name of the transformation.
+    mean : float
+        Mean value for normalization.
+    std : float
+        Standard deviation value for normalization.
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+    )
+
+    name: Literal["Normalize"] = "Normalize"
+    image_means: list = Field(..., min_length=0, max_length=32)
+    image_stds: list = Field(..., min_length=0, max_length=32)
+    target_means: Optional[list] = Field(default=None, min_length=0, max_length=32)
+    target_stds: Optional[list] = Field(default=None, min_length=0, max_length=32)
+
+    @model_validator(mode="after")
+    def validate_means_stds(self: Self) -> Self:
+        """Validate that the means and stds have the same length.
+
+        Returns
+        -------
+        Self
+            The instance of the model.
+        """
+        if len(self.image_means) != len(self.image_stds):
+            raise ValueError("The number of image means and stds must be the same.")
+
+        if (self.target_means is None) != (self.target_stds is None):
+            raise ValueError(
+                "Both target means and stds must be provided together, or bot None."
+            )
+
+        if self.target_means is not None and self.target_stds is not None:
+            if len(self.target_means) != len(self.target_stds):
+                raise ValueError(
+                    "The number of target means and stds must be the same."
+                )
+
+        return self

careamics/config/transformations/transform_model.py

@@ -0,0 +1,45 @@
+"""Parent model for the transforms."""
+
+from typing import Any, Dict
+
+from pydantic import BaseModel, ConfigDict
+
+
+class TransformModel(BaseModel):
+    """
+    Pydantic model used to represent a transformation.
+
+    The `model_dump` method is overwritten to exclude the name field.
+
+    Attributes
+    ----------
+    name : str
+        Name of the transformation.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",  # throw errors if the parameters are not properly passed
+    )
+
+    name: str
+
+    def model_dump(self, **kwargs) -> Dict[str, Any]:
+        """
+        Return the model as a dictionary.
+
+        Parameters
+        ----------
+        **kwargs
+            Pydantic BaseMode model_dump method keyword arguments.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary representation of the model.
+        """
+        model_dict = super().model_dump(**kwargs)
+
+        # remove the name field
+        model_dict.pop("name")
+
+        return model_dict

careamics/config/transformations/xy_flip_model.py

@@ -0,0 +1,43 @@
+"""Pydantic model for the XYFlip transform."""
+
+from typing import Literal, Optional
+
+from pydantic import ConfigDict, Field
+
+from .transform_model import TransformModel
+
+
+class XYFlipModel(TransformModel):
+    """
+    Pydantic model used to represent XYFlip transformation.
+
+    Attributes
+    ----------
+    name : Literal["XYFlip"]
+        Name of the transformation.
+    p : float
+        Probability of applying the transform, by default 0.5.
+    seed : Optional[int]
+        Seed for the random number generator,  by default None.
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+    )
+
+    name: Literal["XYFlip"] = "XYFlip"
+    flip_x: bool = Field(
+        True,
+        description="Whether to flip along the X axis.",
+    )
+    flip_y: bool = Field(
+        True,
+        description="Whether to flip along the Y axis.",
+    )
+    p: float = Field(
+        0.5,
+        description="Probability of applying the transform.",
+        ge=0,
+        le=1,
+    )
+    seed: Optional[int] = None