clarena.cl_datasets.permuted_facescrub

  1r"""
  2The submodule in `cl_datasets` for Permuted FaceScrub dataset.
  3"""
  4
  5__all__ = ["PermutedFaceScrub"]
  6
  7import logging
  8from typing import Callable
  9
 10import torch
 11from torch.utils.data import Dataset, random_split
 12from torchvision.transforms import transforms
 13
 14from clarena.cl_datasets import CLPermutedDataset
 15from clarena.stl_datasets.raw import FaceScrub10, FaceScrub20, FaceScrub50, FaceScrub100
 16
 17# always get logger for built-in logging in each module
 18pylogger = logging.getLogger(__name__)
 19
 20
 21class PermutedFaceScrub(CLPermutedDataset):
 22    r"""Permuted FaceScrub dataset. The [original FaceScrub dataset](https://vintage.winklerbros.net/facescrub.html) is a collection of human face images. It consists 106,863 images of 530 people (classes), each high resolution color image.
 23
 24    To make it simple, [this version](https://github.com/nkundiushuti/facescrub_subset) uses subset of the official [Megaface FaceScrub challenge](http://megaface.cs.washington.edu/participate/challenge.html), cropped and resized to 32x32. We have [FaceScrub-10](https://github.com/nkundiushuti/facescrub_subset/blob/master/data/facescrub_10.zip), [FaceScrub-20](https://github.com/nkundiushuti/facescrub_subset/blob/master/data/facescrub_20.zip), [FaceScrub-50](https://github.com/nkundiushuti/facescrub_subset/blob/master/data/facescrub_50.zip), [FaceScrub-100](https://github.com/nkundiushuti/facescrub_subset/blob/master/data/facescrub_100.zip) datasets where the number of classes are 10, 20, 50 and 100 respectively.
 25    """
 26
 27    def __init__(
 28        self,
 29        root: str,
 30        size: str,
 31        num_tasks: int,
 32        validation_percentage: float,
 33        batch_size: int | dict[int, int] = 1,
 34        num_workers: int | dict[int, int] = 0,
 35        custom_transforms: (
 36            Callable
 37            | transforms.Compose
 38            | None
 39            | dict[int, Callable | transforms.Compose | None]
 40        ) = None,
 41        repeat_channels: int | None | dict[int, int | None] = None,
 42        to_tensor: bool | dict[int, bool] = True,
 43        resize: tuple[int, int] | None | dict[int, tuple[int, int] | None] = None,
 44        permutation_mode: str = "first_channel_only",
 45        permutation_seeds: dict[int, int] | None = None,
 46    ) -> None:
 47        r"""
 48        **Args:**
 49        - **root** (`str`): the root directory where the original FaceScrub data 'FaceScrub/' live.
 50        - **size** (`str`): the size of the dataset; one of:
 51            1. '10': 10 classes (10 people).
 52            2. '20': 20 classes (20 people).
 53            3. '50': 50 classes (50 people).
 54            4. '100': 100 classes (100 people).
 55        - **num_tasks** (`int`): the maximum number of tasks supported by the CL dataset. This decides the valid task IDs from 1 to `num_tasks`.
 56        - **validation_percentage** (`float`): the percentage to randomly split some training data into validation data.
 57        - **batch_size** (`int` | `dict[int, int]`): the batch size for train, val, and test dataloaders.
 58        If it is a dict, the keys are task IDs and the values are the batch sizes for each task. If it is an `int`, it is the same batch size for all tasks.
 59        - **num_workers** (`int` | `dict[int, int]`): the number of workers for dataloaders.
 60        If it is a dict, the keys are task IDs and the values are the number of workers for each task. If it is an `int`, it is the same number of workers for all tasks.
 61        - **custom_transforms** (`transform` or `transforms.Compose` or `None` or dict of them): the custom transforms to apply ONLY to the TRAIN dataset. Can be a single transform, composed transforms, or no transform. `ToTensor()`, normalization, permute, and so on are not included.
 62        If it is a dict, the keys are task IDs and the values are the custom transforms for each task. If it is a single transform or composed transforms, it is applied to all tasks. If it is `None`, no custom transforms are applied.
 63        - **repeat_channels** (`int` | `None` | dict of them): the number of channels to repeat for each task. Default is `None`, which means no repeat.
 64        If it is a dict, the keys are task IDs and the values are the number of channels to repeat for each task. If it is an `int`, it is the same number of channels to repeat for all tasks. If it is `None`, no repeat is applied.
 65        - **to_tensor** (`bool` | `dict[int, bool]`): whether to include the `ToTensor()` transform. Default is `True`.
 66        If it is a dict, the keys are task IDs and the values are whether to include the `ToTensor()` transform for each task. If it is a single boolean value, it is applied to all tasks.
 67        - **resize** (`tuple[int, int]` | `None` or dict of them): the size to resize the images to. Default is `None`, which means no resize.
 68        If it is a dict, the keys are task IDs and the values are the sizes to resize for each task. If it is a single tuple of two integers, it is applied to all tasks. If it is `None`, no resize is applied.
 69        - **permutation_mode** (`str`): the mode of permutation; one of:
 70            1. 'all': permute all pixels.
 71            2. 'by_channel': permute channel by channel separately. All channels are applied the same permutation order.
 72            3. 'first_channel_only': permute only the first channel.
 73        - **permutation_seeds** (`dict[int, int]` | `None`): the dict of seeds for permutation operations used to construct each task. Keys are task IDs and the values are permutation seeds for each task. Default is `None`, which creates a dict of seeds from 0 to `num_tasks`-1.
 74        """
 75
 76        if size == "10":
 77            self.original_dataset_python_class: type[Dataset] = FaceScrub10
 78        elif size == "20":
 79            self.original_dataset_python_class: type[Dataset] = FaceScrub20
 80        elif size == "50":
 81            self.original_dataset_python_class: type[Dataset] = FaceScrub50
 82        elif size == "100":
 83            self.original_dataset_python_class: type[Dataset] = FaceScrub100
 84            r"""The original dataset class."""
 85
 86        super().__init__(
 87            root=root,
 88            num_tasks=num_tasks,
 89            batch_size=batch_size,
 90            num_workers=num_workers,
 91            custom_transforms=custom_transforms,
 92            repeat_channels=repeat_channels,
 93            to_tensor=to_tensor,
 94            resize=resize,
 95            permutation_mode=permutation_mode,
 96            permutation_seeds=permutation_seeds,
 97        )
 98
 99        self.validation_percentage: float = validation_percentage
100        r"""The percentage to randomly split some training data into validation data."""
101
102    def prepare_data(self) -> None:
103        r"""Download the original FaceScrub dataset if haven't."""
104
105        if self.task_id != 1:
106            return  # download all original datasets only at the beginning of first task
107
108        self.original_dataset_python_class(root=self.root_t, train=True, download=True)
109        self.original_dataset_python_class(root=self.root_t, train=False, download=True)
110
111        pylogger.debug(
112            "The original FaceScrub dataset has been downloaded to %s.", self.root_t
113        )
114
115    def train_and_val_dataset(self) -> tuple[Dataset, Dataset]:
116        """Get the training and validation dataset of task `self.task_id`.
117
118        **Returns:**
119        - **train_and_val_dataset** (`tuple[Dataset, Dataset]`): the train and validation dataset of task `self.task_id`.
120        """
121        dataset_train_and_val = self.original_dataset_python_class(
122            root=self.root_t,
123            train=True,
124            transform=self.train_and_val_transforms(),
125            target_transform=self.target_transform(),
126            download=False,
127        )
128
129        return random_split(
130            dataset_train_and_val,
131            lengths=[1 - self.validation_percentage, self.validation_percentage],
132            generator=torch.Generator().manual_seed(
133                42
134            ),  # this must be set fixed to make sure the datasets across experiments are the same. Don't handle it to global seed as it might vary across experiments
135        )
136
137    def test_dataset(self) -> Dataset:
138        r"""Get the test dataset of task `self.task_id`.
139
140        **Returns:**
141        - **test_dataset** (`Dataset`): the test dataset of task `self.task_id`.
142        """
143        dataset_test = self.original_dataset_python_class(
144            root=self.root_t,
145            train=False,
146            transform=self.test_transforms(),
147            target_transform=self.target_transform(),
148            download=False,
149        )
150
151        return dataset_test