Lightning

Create a CAREamics Lightning module.

This function exposes parameters used to create an AlgorithmModel instance, triggering parameters validation.

Parameters:

• algorithm (SupportedAlgorithm or str) –

  Algorithm to use for training (see SupportedAlgorithm).

• loss (SupportedLoss or str) –

  Loss function to use for training (see SupportedLoss).

• architecture (SupportedArchitecture or str) –

  Model architecture to use for training (see SupportedArchitecture).

• use_n2v2 (bool, default: False ) –

  Whether to use N2V2 or Noise2Void.

• struct_n2v_axis ("horizontal", "vertical", or "none", default: "none" ) –

  Axis of the StructN2V mask.

• struct_n2v_span (int, default: 5 ) –

  Span of the StructN2V mask.

• model_parameters (dict, default: None ) –

  Model parameters to use for training, by default {}. Model parameters are defined in the relevant torch.nn.Module class, or Pyddantic model (see careamics.config.architectures).

• optimizer (SupportedOptimizer or str, default: 'Adam' ) –

  Optimizer to use for training, by default "Adam" (see SupportedOptimizer).

• optimizer_parameters (dict, default: None ) –

  Optimizer parameters to use for training, as defined in torch.optim, by default {}.

• lr_scheduler (SupportedScheduler or str, default: 'ReduceLROnPlateau' ) –

  Learning rate scheduler to use for training, by default "ReduceLROnPlateau" (see SupportedScheduler).

• lr_scheduler_parameters (dict, default: None ) –

  Learning rate scheduler parameters to use for training, as defined in torch.optim, by default {}.

Returns:

• CAREamicsModule –

  CAREamics Lightning module.

Create a CAREamics prediction Lightning datamodule.

This function is used to explicitly pass the parameters usually contained in an inference_model configuration.

Since the lightning datamodule has no access to the model, make sure that the parameters passed to the datamodule are consistent with the model's requirements and are coherent. This can be done by creating a Configuration object beforehand and passing its parameters to the different Lightning modules.

The data module can be used with Path, str or numpy arrays. To use array data, set data_type to array and pass a numpy array to train_data.

By default, CAREamics only supports types defined in careamics.config.support.SupportedData. To read custom data types, you can set data_type to custom and provide a function that returns a numpy array from a path. Additionally, pass a fnmatch and Path.rglob compatible expression (e.g. "*.jpeg") to filter the files extension using extension_filter.

In dataloader_params, you can pass any parameter accepted by PyTorch dataloaders, except for batch_size, which is set by the batch_size parameter.

Parameters:

• pred_data (str or Path or ndarray) –

  Prediction data.

• data_type ((array, tiff, custom), default: "array" ) –

  Data type, see SupportedData for available options.

• axes (str) –

  Axes of the data, chosen among SCZYX.

• image_means (list of float) –

  Mean values for normalization, only used if Normalization is defined.

• image_stds (list of float) –

  Std values for normalization, only used if Normalization is defined.

• tile_size (tuple of int, default: None ) –

  Tile size, 2D or 3D tile size.

• tile_overlap (tuple of int, default: None ) –

  Tile overlap, 2D or 3D tile overlap.

• batch_size (int, default: 1 ) –

  Batch size.

• tta_transforms (bool, default: True ) –

  Use test time augmentation, by default True.

• read_source_func (Callable, default: None ) –

  Function to read the source data, used if data_type is custom, by default None.

• extension_filter (str, default: '' ) –

  Filter for file extensions, used if data_type is custom, by default "".

• dataloader_params (dict, default: None ) –

  Pytorch dataloader parameters, by default {}.

Returns:

• PredictDataModule –

  CAREamics prediction datamodule.

Create a TrainDataModule.

This function is used to explicitly pass the parameters usually contained in a GenericDataConfig to a TrainDataModule.

Since the lightning datamodule has no access to the model, make sure that the parameters passed to the datamodule are consistent with the model's requirements and are coherent.

The default augmentations are XY flip and XY rotation. To use a different set of augmentations, you can pass a list of transforms to transforms.

The data module can be used with Path, str or numpy arrays. In the case of numpy arrays, it loads and computes all the patches in memory. For Path and str inputs, it calculates the total file size and estimate whether it can fit in memory. If it does not, it iterates through the files. This behaviour can be deactivated by setting use_in_memory to False, in which case it will always use the iterating dataset to train on a Path or str.

To use array data, set data_type to array and pass a numpy array to train_data.

By default, CAREamics only supports types defined in careamics.config.support.SupportedData. To read custom data types, you can set data_type to custom and provide a function that returns a numpy array from a path. Additionally, pass a fnmatch and Path.rglob compatible expression (e.g. "*.jpeg") to filter the files extension using extension_filter.

In the absence of validation data, the validation data is extracted from the training data. The percentage of the training data to use for validation, as well as the minimum number of patches to split from the training data for validation can be set using val_percentage and val_minimum_patches, respectively.

In dataloader_params, you can pass any parameter accepted by PyTorch dataloaders, except for batch_size, which is set by the batch_size parameter.

Parameters:

• train_data (Path or str or ndarray) –

  Training data.

• data_type ((array, tiff, custom), default: "array" ) –

  Data type, see SupportedData for available options.

• patch_size (list of int) –

  Patch size, 2D or 3D patch size.

• axes (str) –

  Axes of the data, chosen amongst SCZYX.

• batch_size (int) –

  Batch size.

• val_data (Path or str or ndarray, default: None ) –

  Validation data, by default None.

• transforms (list of Transforms, default: None ) –

  List of transforms to apply to training patches. If None, default transforms are applied.

• train_target_data (Path or str or ndarray, default: None ) –

  Training target data, by default None.

• val_target_data (Path or str or ndarray, default: None ) –

  Validation target data, by default None.

• read_source_func (Callable, default: None ) –

  Function to read the source data, used if data_type is custom, by default None.

• extension_filter (str, default: '' ) –

  Filter for file extensions, used if data_type is custom, by default "".

• val_percentage (float, default: 0.1 ) –

  Percentage of the training data to use for validation if no validation data is given, by default 0.1.

• val_minimum_patches (int, default: 5 ) –

  Minimum number of patches to split from the training data for validation if no validation data is given, by default 5.

• train_dataloader_params (dict, default: None ) –

  Pytorch dataloader parameters for the training data, by default {}.

• val_dataloader_params (dict, default: None ) –

  Pytorch dataloader parameters for the validation data, by default {}.

• use_in_memory (bool, default: True ) –

  Use in memory dataset if possible, by default True.

Returns:

• TrainDataModule –

  CAREamics training Lightning data module.

Examples:

Create a TrainingDataModule with default transforms with a numpy array:

>>> import numpy as np
>>> from careamics.compat.lightning import create_train_datamodule
>>> my_array = np.arange(256).reshape(16, 16)
>>> data_module = create_train_datamodule(
...     train_data=my_array,
...     data_type="array",
...     patch_size=(8, 8),
...     axes='YX',
...     batch_size=2,
... )

For custom data types (those not supported by CAREamics), then one can pass a read function and a filter for the files extension:

>>> import numpy as np
>>> from careamics.compat.lightning import create_train_datamodule
>>>
>>> def read_npy(path):
...     return np.load(path)
>>>
>>> data_module = create_train_datamodule(
...     train_data="path/to/data",
...     data_type="custom",
...     patch_size=(8, 8),
...     axes='YX',
...     batch_size=2,
...     read_source_func=read_npy,
...     extension_filter="*.npy",
... )

If you want to use a different set of augmentations, you can pass a list of transforms:

>>> import numpy as np
>>> from careamics.compat.lightning import create_train_datamodule
>>> from careamics.config.augmentations import XYFlipConfig
>>> from careamics.config.support import SupportedTransform
>>> my_array = np.arange(256).reshape(16, 16)
>>> my_transforms = [
...     XYFlipConfig(flip_y=False),
... ]
>>> data_module = create_train_datamodule(
...     train_data=my_array,
...     data_type="array",
...     patch_size=(8, 8),
...     axes='YX',
...     batch_size=2,
...     transforms=my_transforms,
... )