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: .. code-block:: python 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. .. autoclass:: lis2.datasets.data_augmentation.DataAugmentations :members: :undoc-members: :show-inheritance: Augmentation Zoo ---------------- Custom Augmentations ~~~~~~~~~~~~~~~~~~~~ .. autoclass:: lis2.datasets.data_augmentation.NoiseDataAugmentation :members: :undoc-members: :show-inheritance: .. autoclass:: lis2.datasets.torch_data_augmentation.ToTensor :members: :undoc-members: :show-inheritance: .. autoclass:: lis2.datasets.torch_data_augmentation.RandomRotation :members: :undoc-members: :show-inheritance: .. autoclass:: lis2.datasets.torch_data_augmentation.RandomHorizontalFlip :members: :undoc-members: :show-inheritance: .. autoclass:: lis2.datasets.torch_data_augmentation.RandomVerticalFlip :members: :undoc-members: :show-inheritance: Available Torchvision Augmentations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following augmentations from ``torchvision.transforms.v2`` are available (non-excluded): - `AugMix `_ (alias: augmix) - `AutoAugment `_ (alias: autoaugment) - `CenterCrop `_ (alias: centercrop) - `ClampBoundingBoxes `_ (alias: clampboundingboxes) - `ColorJitter `_ (alias: colorjitter) - `ConvertBoundingBoxFormat `_ (alias: convertboundingboxformat) - `ConvertImageDtype `_ (alias: convertimagedtype) - `CutMix `_ (alias: cutmix) - `ElasticTransform `_ (alias: elastictransform) - `FiveCrop `_ (alias: fivecrop) - `GaussianBlur `_ (alias: gaussianblur) - `GaussianNoise `_ (alias: gaussiannoise) - `Grayscale `_ (alias: grayscale) - `Identity `_ (alias: identity) - `JPEG `_ (alias: jpeg) - `LinearTransformation `_ (alias: lineartransformation) - `MixUp `_ (alias: mixup) - `Normalize `_ (alias: normalize) - `PILToTensor `_ (alias: piltotensor) - `Pad `_ (alias: pad) - `RGB `_ (alias: rgb) - `Resize `_ (alias: resize) - `ScaleJitter `_ (alias: scalejitter) - `TenCrop `_ (alias: tencrop) - `ToDtype `_ (alias: todtype) - `ToImage `_ (alias: toimage) - `ToPILImage `_ (alias: topilimage) - `ToPureTensor `_ (alias: topuretensor) - `Transform `_ (alias: transform) .. _adding_augment: 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 ~~~~~~~~~~~~~~~~~~~~ .. autoclass:: lis2.datasets.data_augmentation.BaseDataAugmentation :members: :undoc-members: :show-inheritance: BaseDataAugmentationWithKeys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autoclass:: lis2.datasets.data_augmentation.BaseDataAugmentationWithKeys :members: :undoc-members: :show-inheritance: