Data Augmentation

This module provides a framework for integrating Torchvision Transforms with a configurable schema, allowing dynamic configuration and extension of transforms. It also enables the addition of custom data augmentations by inheriting from the BaseDataAugmentation class.

For more information about Torchvision Transforms, please refer to the Torchvision Transforms v2 documentation.

Overview

The module is designed to be used within a dataset, where the data augmentation configuration becomes part of the dataset configuration. Each augmentation is applied sequentially according to the order specified in the configuration list.

Note

Important: Management of ``ToTensor``

  • The configuration should include a ToTensor augmentation to ensure that the final output is a Tensor.

  • If no ToTensor augmentation is provided by the user, a default ToTensor transform is automatically appended to the configuration.

  • Although there is no strict constraint on the order of augmentations, care must be taken when adding new augmentations. The placement of the ToTensor transform should be handled similarly to a Torch Compose (see: torchvision.transforms.Compose) to avoid type errors.

  • Note: The input to the augmentation pipeline is expected to be NumPy arrays, while the final output must be a torch.Tensor.

Usage

This module is intended to be used as part of a dataset. Below is an example configuration:

data_augmentations = [
    {"type": "ToTensor", "dType": "float32"},
    {"type": "CenterCrop", "name": "center_crop", "size": 10},
    {"type": "NoiseDataAugmentation", "name": "input", "keys_to_augment": ["patch"], "noise_var": 0.1}
]

Key Points: - Sequential Application: Each augmentation is applied sequentially in the order provided. - Mandatory Parameters: Parameters such as name (for custom augmentations) and keys_to_augment may be required to differentiate augmentations and selectively apply transformations. - Selective Augmentation: Use the parameter keys_to_augment to specify which data elements should be augmented. Leaving it empty applies the augmentation to all keys.

DataAugmentations Class

The main class responsible for applying the augmentations is DataAugmentations. Its key functionalities include:

  • Configuration Validation: Ensures that the provided configuration is a list.

  • Default Addition of ``ToTensor``: If the configuration does not include a ToTensor augmentation, one is automatically appended.

  • Sequential Processing: Iterates through the list of configured augmentations and applies each one to the input data.

  • Final Type Check: After applying all augmentations, a type check is performed to ensure that each data element is a torch.Tensor (or a list of torch.Tensor objects). If not, an error is raised indicating a potential misplacement of the ToTensor transform.

class lis2.datasets.data_augmentation.DataAugmentations(augmentations_configs: list[dict[str, Any]])[source]

Bases: object

This class acts as a “Controller” to apply a list of data augmentations to given data.

For each element of the data, the augmentations are applied in the order they are specified in the list. The class is also checking the keys_to_augment value in each configuration, to ensure that only the data corresponding to the specified keys is augmented.

Notes

  • The configuration should include a ToTensor augmentation to ensure that the final output is a Tensor.

  • If no ToTensor augmentation is provided by the user, the module automatically appends a default ``ToTensor`` transform to the configuration.

  • Although there is no strict constraint regarding the order of augmentations, care must be taken when adding new augmentations. The placement of the ToTensor transform should be handled similarly to a Torch Compose (see: torchvision.transforms.Compose) to avoid type errors.

  • Note: The input to the augmentation pipeline is expected to be NumPy arrays, while the final output must be a torch.Tensor.

compute(data)[source]

Augmentation Zoo

Custom Augmentations

class lis2.datasets.data_augmentation.NoiseDataAugmentation(*args, **kwargs)[source]

Bases: BaseDataAugmentationWithKeys

Applies random Gaussian noise to dataset patches for data augmentation.

This class applies random Gaussian noise to the specified dataset patches. The level of noise is controlled by the noise_var parameter, which defines the variance of the noise. Noise is applied only to the keys listed in the keys_to_augment configuration.

Configuration:
  • type (str): Type of data augmentation (required).

  • name (str): Name of the augmentation technique (required).

  • keys_to_augment (list[str]): List of keys in the dataset to apply the augmentation to (default: [] => all), e.g., [“patch”, “spines”].

  • noise_var (float): Variance of the Gaussian noise to be applied (default: 0).

Example Configuration (YAML):
type: "NoiseDataAugmentation"
name: "GaussianNoise"
keys_to_augment: ["patch", "spines"]
noise_var: 0.1
config_schema: Dict = {'keys_to_augment': Schema(type=list[str], aliases=[], optional=True, default=[]), 'noise_var': Schema(type=<class 'float'>, aliases=[], optional=True, default=0.0)}
transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Applies random noise to the tensors in the provided dictionary, only to the keys specified in self.keys_to_augment. Ensures that all tensors have the same size before applying the noise.

Parameters:

data (dict[str, Tensor]) – A dictionary where keys are string identifiers, and values are tensors.

Returns:

A dictionary with the same keys, but the tensors are

updated with noise applied to the specified keys.

Return type:

dict[str, Tensor]

class lis2.datasets.torch_data_augmentation.ToTensor(*args, **kwargs)[source]

Bases: BaseDataAugmentationWithKeys

Converts the specified keys in the dataset to PyTorch tensors.

Configuration:
  • type (str): Type of data augmentation (required).

  • dType (str): Data type to convert the tensors to (default: “float32”).

  • force_device (str): Force the tensors to be on a specific device (default: None).

Example Configuration (YAML):
type: "ToTensor"
dType: "float32"
force_device: "cuda"
config_schema: Dict = {'dType': Schema(type=<class 'str'>, aliases=[], optional=True, default=float32), 'force_device': Schema(type=<class 'str'>, aliases=[], optional=True, default=None)}
transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Converts all input data to tensors and ensures that they are on the same device as the model.

class lis2.datasets.torch_data_augmentation.RandomRotation(*args, **kwargs)[source]

Bases: BaseDataAugmentationWithKeys

Applies random rotation to the specified keys in the dataset.

A single rotation angle is sampled and applied consistently across all specified keys.

Configuration:
  • type (str): Type of data augmentation (required).

  • name (str): Name of the augmentation technique.

  • keys_to_augment (list[str]): List of keys in the dataset to apply the augmentation to (default: [] => all).

  • degrees (Union[float, tuple[float, float]]): Range of degrees for rotation. If a float is given, the range is (-degrees, +degrees). Default: 30.

  • expand (bool): Whether to expand the image to fit the rotated result (default: False).

Example Configuration (YAML):
type: "RandomRotation"
name: "RotationAugment"
keys_to_augment: ["patch", "spines"]
degrees: 45
expand: True

see also: https://pytorch.org/vision/stable/transforms.html#torchvision.transforms.RandomRotation

config_schema: Dict = {'degrees': Schema(type=typing.Union[numbers.Number, typing.Sequence], aliases=[], optional=False, default=None), 'expand': Schema(type=<class 'bool'>, aliases=[], optional=True, default=False), 'keys_to_augment': Schema(type=list[str], aliases=[], optional=True, default=[])}
transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Apply the augmentation to the dataset.

This method must be implemented by subclasses to define the specific transformation logic.

Parameters:
  • data (dict[str, Tensor]) – A dictionary where keys are dataset identifiers (strings) and values are tensors.

  • the (The dictionary will contain keys specified in keys_to_augment. These keys must be present in)

  • dataset

  • empty (which is provided by the Dataset class. If keys_to_augment is)

  • will (augmentation)

  • data. (be applied to all the keys in)

Returns:

A list or dictionary of tensors with applied augmentation, depending on the transformation.

Return type:

list[Tensor]

class lis2.datasets.torch_data_augmentation.RandomHorizontalFlip(*args, **kwargs)[source]

Bases: BaseDataAugmentationWithKeys

Applies random horizontal flip to all keys in the dataset.

A single flip decision is sampled and applied consistently across all keys.

Configuration:
  • type (str): Type of data augmentation (required).

  • name (str): Name of the augmentation technique.

  • p (float): Probability of flipping the input horizontally (default: 0.5).

Example Configuration (YAML):
type: "RandomHorizontalFlip"
name: "HorizontalFlipAugment"
p: 0.5

See also : https://pytorch.org/vision/stable/transforms.html#torchvision.transforms.RandomHorizontalFlip

config_schema: Dict = {'p': Schema(type=<class 'float'>, aliases=[], optional=True, default=0.5)}
transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Apply horizontal flip with probability p to all keys in the dataset.

Parameters:

data (dict[str, Tensor]) – Input dataset to augment.

Returns:

Augmented dataset.

Return type:

dict[str, Tensor]

class lis2.datasets.torch_data_augmentation.RandomVerticalFlip(*args, **kwargs)[source]

Bases: BaseDataAugmentationWithKeys

Applies random vertical flip to all keys in the dataset.

A single flip decision is sampled and applied consistently across all keys.

Configuration:
  • type (str): Type of data augmentation (required).

  • name (str): Name of the augmentation technique.

  • p (float): Probability of flipping the input vertically (default: 0.5).

Example Configuration (YAML):
type: "RandomVerticalFlip"
name: "VerticalFlipAugment"
p: 0.5

See also : https://pytorch.org/vision/stable/transforms.html#torchvision.transforms.RandomVerticalFlip

config_schema: Dict = {'p': Schema(type=<class 'float'>, aliases=[], optional=True, default=0.5)}
transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Apply vertical flip with probability p to all keys in the dataset.

Parameters:

data (dict[str, Tensor]) – Input dataset to augment.

Returns:

Augmented dataset.

Return type:

dict[str, Tensor]

Available Torchvision Augmentations

The following augmentations from torchvision.transforms.v2 are available (non-excluded):

Adding Custom Data Augmentation

The framework allows you to easily extend its capabilities by creating your own custom augmentation. To do so, simply extend one of the abstract base classes provided below.

For a generic augmentation, extend BaseDataAugmentation. If your augmentation needs to target specific keys within a dataset, extend BaseDataAugmentationWithKeys. When using BaseDataAugmentationWithKeys, the transformation will only be applied to the keys specified in the keys_to_augment configuration. If this list is empty, the augmentation is applied to all keys.

BaseDataAugmentation

class lis2.datasets.data_augmentation.BaseDataAugmentation(*args, **kwargs)[source]

Bases: ABC, TypedConfigurable

BaseDataAugmentation is an abstract class that extends TypedConfigurable

abstractmethod transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

BaseDataAugmentationWithKeys

class lis2.datasets.data_augmentation.BaseDataAugmentationWithKeys(*args, **kwargs)[source]

Bases: BaseDataAugmentation, ABC

Abstract base class for data augmentation techniques that apply to specific keys in a dataset.

This class is designed for augmentation techniques that require a list of dataset keys. If the keys_to_augment list is provided, augmentation will be applied only to those specific keys. If the list is empty, the augmentation will be applied to all keys in the dataset.

Configuration:
  • keys_to_augment (list[str]): List of keys in the dataset to apply augmentation (default: []). If empty, the augmentation is applied to all keys.

- __call__

Calls the transformation function to apply the augmentation.

- transformation

Abstract method to be implemented by subclasses to apply the actual transformation.

Example Configuration (YAML):
keys_to_augment: ["patch", "spines"]
config_schema: Dict = {'keys_to_augment': Schema(type=list[str], aliases=[], optional=True, default=[])}
abstractmethod transform(data: dict[str, Tensor]) → dict[str, Tensor][source]

Apply the augmentation to the dataset.

This method must be implemented by subclasses to define the specific transformation logic.

Parameters:
  • data (dict[str, Tensor]) – A dictionary where keys are dataset identifiers (strings) and values are tensors.

  • the (The dictionary will contain keys specified in keys_to_augment. These keys must be present in)

  • dataset

  • empty (which is provided by the Dataset class. If keys_to_augment is)

  • will (augmentation)

  • data. (be applied to all the keys in)

Returns:

A list or dictionary of tensors with applied augmentation, depending on the transformation.

Return type:

list[Tensor]