Skip to content

configuration_factories

Convenience functions to create configurations for training and inference.

algorithm_factory(algorithm) #

Create an algorithm model for training CAREamics.

Parameters:

Name Type Description Default
algorithm dict

Algorithm dictionary.

required

Returns:

Type Description
N2VAlgorithm or N2NAlgorithm or CAREAlgorithm

Algorithm model for training CAREamics.

Source code in src/careamics/config/configuration_factories.py
def algorithm_factory(
    algorithm: dict[str, Any],
) -> Union[N2VAlgorithm, N2NAlgorithm, CAREAlgorithm]:
    """
    Create an algorithm model for training CAREamics.

    Parameters
    ----------
    algorithm : dict
        Algorithm dictionary.

    Returns
    -------
    N2VAlgorithm or N2NAlgorithm or CAREAlgorithm
        Algorithm model for training CAREamics.
    """
    adapter: TypeAdapter = TypeAdapter(
        Annotated[
            Union[N2VAlgorithm, N2NAlgorithm, CAREAlgorithm],
            Field(discriminator="algorithm"),
        ]
    )
    return adapter.validate_python(algorithm)

create_care_configuration(experiment_name, data_type, axes, patch_size, batch_size, num_epochs, augmentations=None, independent_channels=True, loss='mae', n_channels_in=None, n_channels_out=None, logger='none', model_params=None, optimizer='Adam', optimizer_params=None, lr_scheduler='ReduceLROnPlateau', lr_scheduler_params=None, train_dataloader_params=None, val_dataloader_params=None, checkpoint_params=None) #

Create a configuration for training CARE.

If "Z" is present in axes, then path_size must be a list of length 3, otherwise 2.

If "C" is present in axes, then you need to set n_channels_in to the number of channels. Likewise, if you set the number of channels, then "C" must be present in axes.

To set the number of output channels, use the n_channels_out parameter. If it is not specified, it will be assumed to be equal to n_channels_in.

By default, all channels are trained together. To train all channels independently, set independent_channels to True.

By setting augmentations to None, the default transformations (flip in X and Y, rotations by 90 degrees in the XY plane) are applied. Rather than the default transforms, a list of transforms can be passed to the augmentations parameter. To disable the transforms, simply pass an empty list.

Parameters:

Name Type Description Default
experiment_name str

Name of the experiment.

required
data_type Literal['array', 'tiff', 'czi', 'custom']

Type of the data.

required
axes str

Axes of the data (e.g. SYX).

required
patch_size List[int]

Size of the patches along the spatial dimensions (e.g. [64, 64]).

required
batch_size int

Batch size.

required
num_epochs int

Number of epochs.

required
augmentations list of transforms

List of transforms to apply, either both or one of XYFlipModel and XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y) and XYRandomRotate90 (in XY) to the images.

None
independent_channels bool

Whether to train all channels independently, by default False.

True
loss Literal['mae', 'mse']

Loss function to use.

"mae"
n_channels_in int or None

Number of channels in.

None
n_channels_out int or None

Number of channels out.

None
logger Literal['wandb', 'tensorboard', 'none']

Logger to use.

"none"
model_params dict

UNetModel parameters.

None
optimizer Literal['Adam', 'Adamax', 'SGD']

Optimizer to use.

"Adam"
optimizer_params dict

Parameters for the optimizer, see PyTorch documentation for more details.

None
lr_scheduler Literal['ReduceLROnPlateau', 'StepLR']

Learning rate scheduler to use.

"ReduceLROnPlateau"
lr_scheduler_params dict

Parameters for the learning rate scheduler, see PyTorch documentation for more details.

None
train_dataloader_params dict

Parameters for the training dataloader, see the PyTorch docs for DataLoader. If left as None, the dict {"shuffle": True} will be used, this is set in the GeneralDataConfig.

None
val_dataloader_params dict

Parameters for the validation dataloader, see PyTorch the docs for DataLoader. If left as None, the empty dict {} will be used, this is set in the GeneralDataConfig.

None
checkpoint_params dict

Parameters for the checkpoint callback, see PyTorch Lightning documentation (ModelCheckpoint) for the list of available parameters.

None

Returns:

Type Description
Configuration

Configuration for training CARE.

Examples:

Minimum example:

>>> config = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100
... )

To disable transforms, simply set augmentations to an empty list:

>>> config = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[]
... )

A list of transforms can be passed to the augmentations parameter to replace the default augmentations:

>>> from careamics.config.transformations import XYFlipModel
>>> config = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[
...         # No rotation and only Y flipping
...         XYFlipModel(flip_x = False, flip_y = True)
...     ]
... )

If you are training multiple channels they will be trained independently by default, you simply need to specify the number of channels input (and optionally, the number of channels output):

>>> config = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="array",
...     axes="YXC", # channels must be in the axes
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels_in=3, # number of input channels
...     n_channels_out=1 # if applicable
... )

If instead you want to train multiple channels together, you need to turn off the independent_channels parameter:

>>> config = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="array",
...     axes="YXC", # channels must be in the axes
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     independent_channels=False,
...     n_channels_in=3,
...     n_channels_out=1 # if applicable
... )

If you would like to train on CZI files, use "czi" as data_type and "SCYX" as axes for 2-D or "SCZYX" for 3-D denoising. Note that "SCYX" can also be used for 3-D data but spatial context along the Z dimension will then not be taken into account.

>>> config_2d = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="czi",
...     axes="SCYX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels_in=1,
... )
>>> config_3d = create_care_configuration(
...     experiment_name="care_experiment",
...     data_type="czi",
...     axes="SCZYX",
...     patch_size=[16, 64, 64],
...     batch_size=16,
...     num_epochs=100,
...     n_channels_in=1,
... )
Source code in src/careamics/config/configuration_factories.py
def create_care_configuration(
    experiment_name: str,
    data_type: Literal["array", "tiff", "czi", "custom"],
    axes: str,
    patch_size: list[int],
    batch_size: int,
    num_epochs: int,
    augmentations: list[Union[XYFlipModel, XYRandomRotate90Model]] | None = None,
    independent_channels: bool = True,
    loss: Literal["mae", "mse"] = "mae",
    n_channels_in: int | None = None,
    n_channels_out: int | None = None,
    logger: Literal["wandb", "tensorboard", "none"] = "none",
    model_params: dict | None = None,
    optimizer: Literal["Adam", "Adamax", "SGD"] = "Adam",
    optimizer_params: dict[str, Any] | None = None,
    lr_scheduler: Literal["ReduceLROnPlateau", "StepLR"] = "ReduceLROnPlateau",
    lr_scheduler_params: dict[str, Any] | None = None,
    train_dataloader_params: dict[str, Any] | None = None,
    val_dataloader_params: dict[str, Any] | None = None,
    checkpoint_params: dict[str, Any] | None = None,
) -> Configuration:
    """
    Create a configuration for training CARE.

    If "Z" is present in `axes`, then `path_size` must be a list of length 3, otherwise
    2.

    If "C" is present in `axes`, then you need to set `n_channels_in` to the number of
    channels. Likewise, if you set the number of channels, then "C" must be present in
    `axes`.

    To set the number of output channels, use the `n_channels_out` parameter. If it is
    not specified, it will be assumed to be equal to `n_channels_in`.

    By default, all channels are trained together. To train all channels independently,
    set `independent_channels` to True.

    By setting `augmentations` to `None`, the default transformations (flip in X and Y,
    rotations by 90 degrees in the XY plane) are applied. Rather than the default
    transforms, a list of transforms can be passed to the `augmentations` parameter. To
    disable the transforms, simply pass an empty list.

    Parameters
    ----------
    experiment_name : str
        Name of the experiment.
    data_type : Literal["array", "tiff", "czi", "custom"]
        Type of the data.
    axes : str
        Axes of the data (e.g. SYX).
    patch_size : List[int]
        Size of the patches along the spatial dimensions (e.g. [64, 64]).
    batch_size : int
        Batch size.
    num_epochs : int
        Number of epochs.
    augmentations : list of transforms, default=None
        List of transforms to apply, either both or one of XYFlipModel and
        XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y)
        and XYRandomRotate90 (in XY) to the images.
    independent_channels : bool, optional
        Whether to train all channels independently, by default False.
    loss : Literal["mae", "mse"], default="mae"
        Loss function to use.
    n_channels_in : int or None, default=None
        Number of channels in.
    n_channels_out : int or None, default=None
        Number of channels out.
    logger : Literal["wandb", "tensorboard", "none"], default="none"
        Logger to use.
    model_params : dict, default=None
        UNetModel parameters.
    optimizer : Literal["Adam", "Adamax", "SGD"], default="Adam"
        Optimizer to use.
    optimizer_params : dict, default=None
        Parameters for the optimizer, see PyTorch documentation for more details.
    lr_scheduler : Literal["ReduceLROnPlateau", "StepLR"], default="ReduceLROnPlateau"
        Learning rate scheduler to use.
    lr_scheduler_params : dict, default=None
        Parameters for the learning rate scheduler, see PyTorch documentation for more
        details.
    train_dataloader_params : dict, optional
        Parameters for the training dataloader, see the PyTorch docs for `DataLoader`.
        If left as `None`, the dict `{"shuffle": True}` will be used, this is set in
        the `GeneralDataConfig`.
    val_dataloader_params : dict, optional
        Parameters for the validation dataloader, see PyTorch the docs for `DataLoader`.
        If left as `None`, the empty dict `{}` will be used, this is set in the
        `GeneralDataConfig`.
    checkpoint_params : dict, default=None
        Parameters for the checkpoint callback, see PyTorch Lightning documentation
        (`ModelCheckpoint`) for the list of available parameters.

    Returns
    -------
    Configuration
        Configuration for training CARE.

    Examples
    --------
    Minimum example:
    >>> config = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100
    ... )

    To disable transforms, simply set `augmentations` to an empty list:
    >>> config = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[]
    ... )

    A list of transforms can be passed to the `augmentations` parameter to replace the
    default augmentations:
    >>> from careamics.config.transformations import XYFlipModel
    >>> config = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[
    ...         # No rotation and only Y flipping
    ...         XYFlipModel(flip_x = False, flip_y = True)
    ...     ]
    ... )

    If you are training multiple channels they will be trained independently by default,
    you simply need to specify the number of channels input (and optionally, the number
    of channels output):
    >>> config = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="array",
    ...     axes="YXC", # channels must be in the axes
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels_in=3, # number of input channels
    ...     n_channels_out=1 # if applicable
    ... )

    If instead you want to train multiple channels together, you need to turn off the
    `independent_channels` parameter:
    >>> config = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="array",
    ...     axes="YXC", # channels must be in the axes
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     independent_channels=False,
    ...     n_channels_in=3,
    ...     n_channels_out=1 # if applicable
    ... )

    If you would like to train on CZI files, use `"czi"` as `data_type` and `"SCYX"` as
    `axes` for 2-D or `"SCZYX"` for 3-D denoising. Note that `"SCYX"` can also be used
    for 3-D data but spatial context along the Z dimension will then not be taken into
    account.
    >>> config_2d = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="czi",
    ...     axes="SCYX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels_in=1,
    ... )
    >>> config_3d = create_care_configuration(
    ...     experiment_name="care_experiment",
    ...     data_type="czi",
    ...     axes="SCZYX",
    ...     patch_size=[16, 64, 64],
    ...     batch_size=16,
    ...     num_epochs=100,
    ...     n_channels_in=1,
    ... )
    """
    return Configuration(
        **_create_supervised_config_dict(
            algorithm="care",
            experiment_name=experiment_name,
            data_type=data_type,
            axes=axes,
            patch_size=patch_size,
            batch_size=batch_size,
            num_epochs=num_epochs,
            augmentations=augmentations,
            independent_channels=independent_channels,
            loss=loss,
            n_channels_in=n_channels_in,
            n_channels_out=n_channels_out,
            logger=logger,
            model_params=model_params,
            optimizer=optimizer,
            optimizer_params=optimizer_params,
            lr_scheduler=lr_scheduler,
            lr_scheduler_params=lr_scheduler_params,
            train_dataloader_params=train_dataloader_params,
            val_dataloader_params=val_dataloader_params,
            checkpoint_params=checkpoint_params,
        )
    )

create_n2n_configuration(experiment_name, data_type, axes, patch_size, batch_size, num_epochs, augmentations=None, independent_channels=True, loss='mae', n_channels_in=None, n_channels_out=None, logger='none', model_params=None, optimizer='Adam', optimizer_params=None, lr_scheduler='ReduceLROnPlateau', lr_scheduler_params=None, train_dataloader_params=None, val_dataloader_params=None, checkpoint_params=None) #

Create a configuration for training Noise2Noise.

If "Z" is present in axes, then path_size must be a list of length 3, otherwise 2.

If "C" is present in axes, then you need to set n_channels_in to the number of channels. Likewise, if you set the number of channels, then "C" must be present in axes.

To set the number of output channels, use the n_channels_out parameter. If it is not specified, it will be assumed to be equal to n_channels_in.

By default, all channels are trained together. To train all channels independently, set independent_channels to True.

By setting augmentations to None, the default transformations (flip in X and Y, rotations by 90 degrees in the XY plane) are applied. Rather than the default transforms, a list of transforms can be passed to the augmentations parameter. To disable the transforms, simply pass an empty list.

Parameters:

Name Type Description Default
experiment_name str

Name of the experiment.

required
data_type Literal['array', 'tiff', 'czi', 'custom']

Type of the data.

required
axes str

Axes of the data (e.g. SYX).

required
patch_size List[int]

Size of the patches along the spatial dimensions (e.g. [64, 64]).

required
batch_size int

Batch size.

required
num_epochs int

Number of epochs.

required
augmentations list of transforms

List of transforms to apply, either both or one of XYFlipModel and XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y) and XYRandomRotate90 (in XY) to the images.

None
independent_channels bool

Whether to train all channels independently, by default False.

True
loss Literal['mae', 'mse']

Loss function to use, by default "mae".

'mae'
n_channels_in int or None

Number of channels in.

None
n_channels_out int or None

Number of channels out.

None
logger Literal['wandb', 'tensorboard', 'none']

Logger to use, by default "none".

'none'
model_params dict

UNetModel parameters.

None
optimizer Literal['Adam', 'Adamax', 'SGD']

Optimizer to use.

"Adam"
optimizer_params dict

Parameters for the optimizer, see PyTorch documentation for more details.

None
lr_scheduler Literal['ReduceLROnPlateau', 'StepLR']

Learning rate scheduler to use.

"ReduceLROnPlateau"
lr_scheduler_params dict

Parameters for the learning rate scheduler, see PyTorch documentation for more details.

None
train_dataloader_params dict

Parameters for the training dataloader, see the PyTorch docs for DataLoader. If left as None, the dict {"shuffle": True} will be used, this is set in the GeneralDataConfig.

None
val_dataloader_params dict

Parameters for the validation dataloader, see PyTorch the docs for DataLoader. If left as None, the empty dict {} will be used, this is set in the GeneralDataConfig.

None
checkpoint_params dict

Parameters for the checkpoint callback, see PyTorch Lightning documentation (ModelCheckpoint) for the list of available parameters.

None

Returns:

Type Description
Configuration

Configuration for training Noise2Noise.

Examples:

Minimum example:

>>> config = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100
... )

To disable transforms, simply set augmentations to an empty list:

>>> config = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[]
... )

A list of transforms can be passed to the augmentations parameter to replace the default augmentations:

>>> from careamics.config.transformations import XYFlipModel
>>> config = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[
...         # No rotation and only Y flipping
...         XYFlipModel(flip_x = False, flip_y = True)
...     ]
... )

If you are training multiple channels they will be trained independently by default, you simply need to specify the number of channels input (and optionally, the number of channels output):

>>> config = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="array",
...     axes="YXC", # channels must be in the axes
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels_in=3, # number of input channels
...     n_channels_out=1 # if applicable
... )

If instead you want to train multiple channels together, you need to turn off the independent_channels parameter:

>>> config = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="array",
...     axes="YXC", # channels must be in the axes
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     independent_channels=False,
...     n_channels_in=3,
...     n_channels_out=1 # if applicable
... )

If you would like to train on CZI files, use "czi" as data_type and "SCYX" as axes for 2-D or "SCZYX" for 3-D denoising. Note that "SCYX" can also be used for 3-D data but spatial context along the Z dimension will then not be taken into account.

>>> config_2d = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="czi",
...     axes="SCYX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels_in=1,
... )
>>> config_3d = create_n2n_configuration(
...     experiment_name="n2n_experiment",
...     data_type="czi",
...     axes="SCZYX",
...     patch_size=[16, 64, 64],
...     batch_size=16,
...     num_epochs=100,
...     n_channels_in=1,
... )
Source code in src/careamics/config/configuration_factories.py
def create_n2n_configuration(
    experiment_name: str,
    data_type: Literal["array", "tiff", "czi", "custom"],
    axes: str,
    patch_size: list[int],
    batch_size: int,
    num_epochs: int,
    augmentations: list[Union[XYFlipModel, XYRandomRotate90Model]] | None = None,
    independent_channels: bool = True,
    loss: Literal["mae", "mse"] = "mae",
    n_channels_in: int | None = None,
    n_channels_out: int | None = None,
    logger: Literal["wandb", "tensorboard", "none"] = "none",
    model_params: dict | None = None,
    optimizer: Literal["Adam", "Adamax", "SGD"] = "Adam",
    optimizer_params: dict[str, Any] | None = None,
    lr_scheduler: Literal["ReduceLROnPlateau", "StepLR"] = "ReduceLROnPlateau",
    lr_scheduler_params: dict[str, Any] | None = None,
    train_dataloader_params: dict[str, Any] | None = None,
    val_dataloader_params: dict[str, Any] | None = None,
    checkpoint_params: dict[str, Any] | None = None,
) -> Configuration:
    """
    Create a configuration for training Noise2Noise.

    If "Z" is present in `axes`, then `path_size` must be a list of length 3, otherwise
    2.

    If "C" is present in `axes`, then you need to set `n_channels_in` to the number of
    channels. Likewise, if you set the number of channels, then "C" must be present in
    `axes`.

    To set the number of output channels, use the `n_channels_out` parameter. If it is
    not specified, it will be assumed to be equal to `n_channels_in`.

    By default, all channels are trained together. To train all channels independently,
    set `independent_channels` to True.

    By setting `augmentations` to `None`, the default transformations (flip in X and Y,
    rotations by 90 degrees in the XY plane) are applied. Rather than the default
    transforms, a list of transforms can be passed to the `augmentations` parameter. To
    disable the transforms, simply pass an empty list.

    Parameters
    ----------
    experiment_name : str
        Name of the experiment.
    data_type : Literal["array", "tiff", "czi", "custom"]
        Type of the data.
    axes : str
        Axes of the data (e.g. SYX).
    patch_size : List[int]
        Size of the patches along the spatial dimensions (e.g. [64, 64]).
    batch_size : int
        Batch size.
    num_epochs : int
        Number of epochs.
    augmentations : list of transforms, default=None
        List of transforms to apply, either both or one of XYFlipModel and
        XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y)
        and XYRandomRotate90 (in XY) to the images.
    independent_channels : bool, optional
        Whether to train all channels independently, by default False.
    loss : Literal["mae", "mse"], optional
        Loss function to use, by default "mae".
    n_channels_in : int or None, default=None
        Number of channels in.
    n_channels_out : int or None, default=None
        Number of channels out.
    logger : Literal["wandb", "tensorboard", "none"], optional
        Logger to use, by default "none".
    model_params : dict, default=None
        UNetModel parameters.
    optimizer : Literal["Adam", "Adamax", "SGD"], default="Adam"
        Optimizer to use.
    optimizer_params : dict, default=None
        Parameters for the optimizer, see PyTorch documentation for more details.
    lr_scheduler : Literal["ReduceLROnPlateau", "StepLR"], default="ReduceLROnPlateau"
        Learning rate scheduler to use.
    lr_scheduler_params : dict, default=None
        Parameters for the learning rate scheduler, see PyTorch documentation for more
        details.
    train_dataloader_params : dict, optional
        Parameters for the training dataloader, see the PyTorch docs for `DataLoader`.
        If left as `None`, the dict `{"shuffle": True}` will be used, this is set in
        the `GeneralDataConfig`.
    val_dataloader_params : dict, optional
        Parameters for the validation dataloader, see PyTorch the docs for `DataLoader`.
        If left as `None`, the empty dict `{}` will be used, this is set in the
        `GeneralDataConfig`.
    checkpoint_params : dict, default=None
        Parameters for the checkpoint callback, see PyTorch Lightning documentation
        (`ModelCheckpoint`) for the list of available parameters.

    Returns
    -------
    Configuration
        Configuration for training Noise2Noise.

    Examples
    --------
    Minimum example:
    >>> config = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100
    ... )

    To disable transforms, simply set `augmentations` to an empty list:
    >>> config = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[]
    ... )

    A list of transforms can be passed to the `augmentations` parameter to replace the
    default augmentations:
    >>> from careamics.config.transformations import XYFlipModel
    >>> config = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[
    ...         # No rotation and only Y flipping
    ...         XYFlipModel(flip_x = False, flip_y = True)
    ...     ]
    ... )

    If you are training multiple channels they will be trained independently by default,
    you simply need to specify the number of channels input (and optionally, the number
    of channels output):
    >>> config = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="array",
    ...     axes="YXC", # channels must be in the axes
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels_in=3, # number of input channels
    ...     n_channels_out=1 # if applicable
    ... )

    If instead you want to train multiple channels together, you need to turn off the
    `independent_channels` parameter:
    >>> config = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="array",
    ...     axes="YXC", # channels must be in the axes
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     independent_channels=False,
    ...     n_channels_in=3,
    ...     n_channels_out=1 # if applicable
    ... )

    If you would like to train on CZI files, use `"czi"` as `data_type` and `"SCYX"` as
    `axes` for 2-D or `"SCZYX"` for 3-D denoising. Note that `"SCYX"` can also be used
    for 3-D data but spatial context along the Z dimension will then not be taken into
    account.
    >>> config_2d = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="czi",
    ...     axes="SCYX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels_in=1,
    ... )
    >>> config_3d = create_n2n_configuration(
    ...     experiment_name="n2n_experiment",
    ...     data_type="czi",
    ...     axes="SCZYX",
    ...     patch_size=[16, 64, 64],
    ...     batch_size=16,
    ...     num_epochs=100,
    ...     n_channels_in=1,
    ... )
    """
    return Configuration(
        **_create_supervised_config_dict(
            algorithm="n2n",
            experiment_name=experiment_name,
            data_type=data_type,
            axes=axes,
            patch_size=patch_size,
            batch_size=batch_size,
            num_epochs=num_epochs,
            augmentations=augmentations,
            independent_channels=independent_channels,
            loss=loss,
            n_channels_in=n_channels_in,
            n_channels_out=n_channels_out,
            logger=logger,
            model_params=model_params,
            optimizer=optimizer,
            optimizer_params=optimizer_params,
            lr_scheduler=lr_scheduler,
            lr_scheduler_params=lr_scheduler_params,
            train_dataloader_params=train_dataloader_params,
            val_dataloader_params=val_dataloader_params,
            checkpoint_params=checkpoint_params,
        )
    )

create_n2v_configuration(experiment_name, data_type, axes, patch_size, batch_size, num_epochs, augmentations=None, independent_channels=True, use_n2v2=False, n_channels=None, roi_size=11, masked_pixel_percentage=0.2, struct_n2v_axis='none', struct_n2v_span=5, logger='none', model_params=None, optimizer='Adam', optimizer_params=None, lr_scheduler='ReduceLROnPlateau', lr_scheduler_params=None, train_dataloader_params=None, val_dataloader_params=None, checkpoint_params=None) #

Create a configuration for training Noise2Void.

N2V uses a UNet model to denoise images in a self-supervised manner. To use its variants structN2V and N2V2, set the struct_n2v_axis and struct_n2v_span (structN2V) parameters, or set use_n2v2 to True (N2V2).

N2V2 modifies the UNet architecture by adding blur pool layers and removes the skip connections, thus removing checkboard artefacts. StructN2V is used when vertical or horizontal correlations are present in the noise; it applies an additional mask to the manipulated pixel neighbors.

If "Z" is present in axes, then path_size must be a list of length 3, otherwise 2.

If "C" is present in axes, then you need to set n_channels to the number of channels.

By default, all channels are trained independently. To train all channels together, set independent_channels to False.

By default, the transformations applied are a random flip along X or Y, and a random 90 degrees rotation in the XY plane. Normalization is always applied, as well as the N2V manipulation.

By setting augmentations to None, the default transformations (flip in X and Y, rotations by 90 degrees in the XY plane) are applied. Rather than the default transforms, a list of transforms can be passed to the augmentations parameter. To disable the transforms, simply pass an empty list.

The roi_size parameter specifies the size of the area around each pixel that will be manipulated by N2V. The masked_pixel_percentage parameter specifies how many pixels per patch will be manipulated.

The parameters of the UNet can be specified in the model_params (passed as a parameter-value dictionary). Note that use_n2v2 and 'n_channels' override the corresponding parameters passed in model_params.

If you pass "horizontal" or "vertical" to struct_n2v_axis, then structN2V mask will be applied to each manipulated pixel.

Parameters:

Name Type Description Default
experiment_name str

Name of the experiment.

required
data_type Literal['array', 'tiff', 'czi', 'custom']

Type of the data.

required
axes str

Axes of the data (e.g. SYX).

required
patch_size List[int]

Size of the patches along the spatial dimensions (e.g. [64, 64]).

required
batch_size int

Batch size.

required
num_epochs int

Number of epochs.

required
augmentations list of transforms

List of transforms to apply, either both or one of XYFlipModel and XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y) and XYRandomRotate90 (in XY) to the images.

None
independent_channels bool

Whether to train all channels together, by default True.

True
use_n2v2 bool

Whether to use N2V2, by default False.

False
n_channels int or None

Number of channels (in and out).

None
roi_size int

N2V pixel manipulation area, by default 11.

11
masked_pixel_percentage float

Percentage of pixels masked in each patch, by default 0.2.

0.2
struct_n2v_axis Literal['horizontal', 'vertical', 'none']

Axis along which to apply structN2V mask, by default "none".

'none'
struct_n2v_span int

Span of the structN2V mask, by default 5.

5
logger Literal['wandb', 'tensorboard', 'none']

Logger to use, by default "none".

'none'
model_params dict

UNetModel parameters.

None
optimizer Literal['Adam', 'Adamax', 'SGD']

Optimizer to use.

"Adam"
optimizer_params dict

Parameters for the optimizer, see PyTorch documentation for more details.

None
lr_scheduler Literal['ReduceLROnPlateau', 'StepLR']

Learning rate scheduler to use.

"ReduceLROnPlateau"
lr_scheduler_params dict

Parameters for the learning rate scheduler, see PyTorch documentation for more details.

None
train_dataloader_params dict

Parameters for the training dataloader, see the PyTorch docs for DataLoader. If left as None, the dict {"shuffle": True} will be used, this is set in the GeneralDataConfig.

None
val_dataloader_params dict

Parameters for the validation dataloader, see PyTorch the docs for DataLoader. If left as None, the empty dict {} will be used, this is set in the GeneralDataConfig.

None
checkpoint_params dict

Parameters for the checkpoint callback, see PyTorch Lightning documentation (ModelCheckpoint) for the list of available parameters.

None

Returns:

Type Description
Configuration

Configuration for training N2V.

Examples:

Minimum example:

>>> config = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100
... )

To disable transforms, simply set augmentations to an empty list:

>>> config = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[]
... )

A list of transforms can be passed to the augmentations parameter:

>>> from careamics.config.transformations import XYFlipModel
>>> config = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="array",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     augmentations=[
...         # No rotation and only Y flipping
...         XYFlipModel(flip_x = False, flip_y = True)
...     ]
... )

To use N2V2, simply pass the use_n2v2 parameter:

>>> config = create_n2v_configuration(
...     experiment_name="n2v2_experiment",
...     data_type="tiff",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     use_n2v2=True
... )

For structN2V, there are two parameters to set, struct_n2v_axis and struct_n2v_span:

>>> config = create_n2v_configuration(
...     experiment_name="structn2v_experiment",
...     data_type="tiff",
...     axes="YX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     struct_n2v_axis="horizontal",
...     struct_n2v_span=7
... )

If you are training multiple channels they will be trained independently by default, you simply need to specify the number of channels:

>>> config = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="array",
...     axes="YXC",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels=3
... )

If instead you want to train multiple channels together, you need to turn off the independent_channels parameter:

>>> config = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="array",
...     axes="YXC",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     independent_channels=False,
...     n_channels=3
... )

If you would like to train on CZI files, use "czi" as data_type and "SCYX" as axes for 2-D or "SCZYX" for 3-D denoising. Note that "SCYX" can also be used for 3-D data but spatial context along the Z dimension will then not be taken into account.

>>> config_2d = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="czi",
...     axes="SCYX",
...     patch_size=[64, 64],
...     batch_size=32,
...     num_epochs=100,
...     n_channels=1,
... )
>>> config_3d = create_n2v_configuration(
...     experiment_name="n2v_experiment",
...     data_type="czi",
...     axes="SCZYX",
...     patch_size=[16, 64, 64],
...     batch_size=16,
...     num_epochs=100,
...     n_channels=1,
... )
Source code in src/careamics/config/configuration_factories.py
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
def create_n2v_configuration(
    experiment_name: str,
    data_type: Literal["array", "tiff", "czi", "custom"],
    axes: str,
    patch_size: list[int],
    batch_size: int,
    num_epochs: int,
    augmentations: list[Union[XYFlipModel, XYRandomRotate90Model]] | None = None,
    independent_channels: bool = True,
    use_n2v2: bool = False,
    n_channels: int | None = None,
    roi_size: int = 11,
    masked_pixel_percentage: float = 0.2,
    struct_n2v_axis: Literal["horizontal", "vertical", "none"] = "none",
    struct_n2v_span: int = 5,
    logger: Literal["wandb", "tensorboard", "none"] = "none",
    model_params: dict | None = None,
    optimizer: Literal["Adam", "Adamax", "SGD"] = "Adam",
    optimizer_params: dict[str, Any] | None = None,
    lr_scheduler: Literal["ReduceLROnPlateau", "StepLR"] = "ReduceLROnPlateau",
    lr_scheduler_params: dict[str, Any] | None = None,
    train_dataloader_params: dict[str, Any] | None = None,
    val_dataloader_params: dict[str, Any] | None = None,
    checkpoint_params: dict[str, Any] | None = None,
) -> Configuration:
    """
    Create a configuration for training Noise2Void.

    N2V uses a UNet model to denoise images in a self-supervised manner. To use its
    variants structN2V and N2V2, set the `struct_n2v_axis` and `struct_n2v_span`
    (structN2V) parameters, or set `use_n2v2` to True (N2V2).

    N2V2 modifies the UNet architecture by adding blur pool layers and removes the skip
    connections, thus removing checkboard artefacts. StructN2V is used when vertical
    or horizontal correlations are present in the noise; it applies an additional mask
    to the manipulated pixel neighbors.

    If "Z" is present in `axes`, then `path_size` must be a list of length 3, otherwise
    2.

    If "C" is present in `axes`, then you need to set `n_channels` to the number of
    channels.

    By default, all channels are trained independently. To train all channels together,
    set `independent_channels` to False.

    By default, the transformations applied are a random flip along X or Y, and a random
    90 degrees rotation in the XY plane. Normalization is always applied, as well as the
    N2V manipulation.

    By setting `augmentations` to `None`, the default transformations (flip in X and Y,
    rotations by 90 degrees in the XY plane) are applied. Rather than the default
    transforms, a list of transforms can be passed to the `augmentations` parameter. To
    disable the transforms, simply pass an empty list.

    The `roi_size` parameter specifies the size of the area around each pixel that will
    be manipulated by N2V. The `masked_pixel_percentage` parameter specifies how many
    pixels per patch will be manipulated.

    The parameters of the UNet can be specified in the `model_params` (passed as a
    parameter-value dictionary). Note that `use_n2v2` and 'n_channels' override the
    corresponding parameters passed in `model_params`.

    If you pass "horizontal" or "vertical" to `struct_n2v_axis`, then structN2V mask
    will be applied to each manipulated pixel.

    Parameters
    ----------
    experiment_name : str
        Name of the experiment.
    data_type : Literal["array", "tiff", "czi", "custom"]
        Type of the data.
    axes : str
        Axes of the data (e.g. SYX).
    patch_size : List[int]
        Size of the patches along the spatial dimensions (e.g. [64, 64]).
    batch_size : int
        Batch size.
    num_epochs : int
        Number of epochs.
    augmentations : list of transforms, default=None
        List of transforms to apply, either both or one of XYFlipModel and
        XYRandomRotate90Model. By default, it applies both XYFlip (on X and Y)
        and XYRandomRotate90 (in XY) to the images.
    independent_channels : bool, optional
        Whether to train all channels together, by default True.
    use_n2v2 : bool, optional
        Whether to use N2V2, by default False.
    n_channels : int or None, default=None
        Number of channels (in and out).
    roi_size : int, optional
        N2V pixel manipulation area, by default 11.
    masked_pixel_percentage : float, optional
        Percentage of pixels masked in each patch, by default 0.2.
    struct_n2v_axis : Literal["horizontal", "vertical", "none"], optional
        Axis along which to apply structN2V mask, by default "none".
    struct_n2v_span : int, optional
        Span of the structN2V mask, by default 5.
    logger : Literal["wandb", "tensorboard", "none"], optional
        Logger to use, by default "none".
    model_params : dict, default=None
        UNetModel parameters.
    optimizer : Literal["Adam", "Adamax", "SGD"], default="Adam"
        Optimizer to use.
    optimizer_params : dict, default=None
        Parameters for the optimizer, see PyTorch documentation for more details.
    lr_scheduler : Literal["ReduceLROnPlateau", "StepLR"], default="ReduceLROnPlateau"
        Learning rate scheduler to use.
    lr_scheduler_params : dict, default=None
        Parameters for the learning rate scheduler, see PyTorch documentation for more
        details.
    train_dataloader_params : dict, optional
        Parameters for the training dataloader, see the PyTorch docs for `DataLoader`.
        If left as `None`, the dict `{"shuffle": True}` will be used, this is set in
        the `GeneralDataConfig`.
    val_dataloader_params : dict, optional
        Parameters for the validation dataloader, see PyTorch the docs for `DataLoader`.
        If left as `None`, the empty dict `{}` will be used, this is set in the
        `GeneralDataConfig`.
    checkpoint_params : dict, default=None
        Parameters for the checkpoint callback, see PyTorch Lightning documentation
        (`ModelCheckpoint`) for the list of available parameters.

    Returns
    -------
    Configuration
        Configuration for training N2V.

    Examples
    --------
    Minimum example:
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100
    ... )

    To disable transforms, simply set `augmentations` to an empty list:
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[]
    ... )

    A list of transforms can be passed to the `augmentations` parameter:
    >>> from careamics.config.transformations import XYFlipModel
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="array",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     augmentations=[
    ...         # No rotation and only Y flipping
    ...         XYFlipModel(flip_x = False, flip_y = True)
    ...     ]
    ... )

    To use N2V2, simply pass the `use_n2v2` parameter:
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v2_experiment",
    ...     data_type="tiff",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     use_n2v2=True
    ... )

    For structN2V, there are two parameters to set, `struct_n2v_axis` and
    `struct_n2v_span`:
    >>> config = create_n2v_configuration(
    ...     experiment_name="structn2v_experiment",
    ...     data_type="tiff",
    ...     axes="YX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     struct_n2v_axis="horizontal",
    ...     struct_n2v_span=7
    ... )

    If you are training multiple channels they will be trained independently by default,
    you simply need to specify the number of channels:
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="array",
    ...     axes="YXC",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels=3
    ... )

    If instead you want to train multiple channels together, you need to turn off the
    `independent_channels` parameter:
    >>> config = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="array",
    ...     axes="YXC",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     independent_channels=False,
    ...     n_channels=3
    ... )

    If you would like to train on CZI files, use `"czi"` as `data_type` and `"SCYX"` as
    `axes` for 2-D or `"SCZYX"` for 3-D denoising. Note that `"SCYX"` can also be used
    for 3-D data but spatial context along the Z dimension will then not be taken into
    account.
    >>> config_2d = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="czi",
    ...     axes="SCYX",
    ...     patch_size=[64, 64],
    ...     batch_size=32,
    ...     num_epochs=100,
    ...     n_channels=1,
    ... )
    >>> config_3d = create_n2v_configuration(
    ...     experiment_name="n2v_experiment",
    ...     data_type="czi",
    ...     axes="SCZYX",
    ...     patch_size=[16, 64, 64],
    ...     batch_size=16,
    ...     num_epochs=100,
    ...     n_channels=1,
    ... )
    """
    # if there are channels, we need to specify their number
    if "C" in axes and n_channels is None:
        raise ValueError("Number of channels must be specified when using channels.")
    elif "C" not in axes and (n_channels is not None and n_channels > 1):
        raise ValueError(
            f"C is not present in the axes, but number of channels is specified "
            f"(got {n_channels} channel)."
        )

    if n_channels is None:
        n_channels = 1

    # augmentations
    spatial_transforms = _list_spatial_augmentations(augmentations)

    # create the N2VManipulate transform using the supplied parameters
    n2v_transform = N2VManipulateModel(
        name=SupportedTransform.N2V_MANIPULATE.value,
        strategy=(
            SupportedPixelManipulation.MEDIAN.value
            if use_n2v2
            else SupportedPixelManipulation.UNIFORM.value
        ),
        roi_size=roi_size,
        masked_pixel_percentage=masked_pixel_percentage,
        struct_mask_axis=struct_n2v_axis,
        struct_mask_span=struct_n2v_span,
    )

    # algorithm
    algorithm_params = _create_algorithm_configuration(
        axes=axes,
        algorithm="n2v",
        loss="n2v",
        independent_channels=independent_channels,
        n_channels_in=n_channels,
        n_channels_out=n_channels,
        use_n2v2=use_n2v2,
        model_params=model_params,
        optimizer=optimizer,
        optimizer_params=optimizer_params,
        lr_scheduler=lr_scheduler,
        lr_scheduler_params=lr_scheduler_params,
    )
    algorithm_params["n2v_config"] = n2v_transform

    # data
    data_params = _create_data_configuration(
        data_type=data_type,
        axes=axes,
        patch_size=patch_size,
        batch_size=batch_size,
        augmentations=spatial_transforms,
        train_dataloader_params=train_dataloader_params,
        val_dataloader_params=val_dataloader_params,
    )

    # training
    training_params = _create_training_configuration(
        num_epochs=num_epochs,
        logger=logger,
        checkpoint_params=checkpoint_params,
    )

    return Configuration(
        experiment_name=experiment_name,
        algorithm_config=algorithm_params,
        data_config=data_params,
        training_config=training_params,
    )