cutmix_batch#

composer.functional.cutmix_batch(input, target, length=None, alpha=1.0, bbox=None, indices=None, uniform_sampling=False)[source]#

Create new samples using combinations of pairs of samples.

This is done by masking a region of each image in input and filling the masked region with the corresponding content from a random different image in``input``.

The position of the masked region is determined by drawing a center point uniformly at random from all spatial positions.

The area of the masked region is computed using either length or alpha. If length is provided, it directly determines the size of the masked region. If it is not provided, the fraction of the input area to mask is drawn from a Beta(alpha, alpha) distribution. The original paper uses a fixed value of alpha = 1.

Alternatively, one may provide a bounding box to mask directly, in which case alpha is ignored and length must not be provided.

The same masked region is used for the whole batch.

Note

The masked region is clipped at the spatial boundaries of the inputs. This means that there is no padding required, but the actual region used may be smaller than the nominal size computed using length or alpha.

Parameters

  • input (Tensor) โ€“ input tensor of shape (N, C, H, W).

  • target (Tensor) โ€“ target tensor of either shape N or (N, num_classes). In the former case, elements of target must be integer class ids in the range 0..num_classes. In the latter case, rows of target may be arbitrary vectors of targets, including, e.g., one-hot encoded class labels, smoothed class labels, or multi-output regression targets.

  • length (float, optional) โ€“ Relative side length of the masked region. If specified, length is interpreted as a fraction of H and W, and the resulting box is of size (length * H, length * W). Default: None.

  • alpha (float, optional) โ€“ parameter for the Beta distribution over the fraction of the input to mask. Ignored if length is provided. Default: 1.

  • bbox (tuple, optional) โ€“ predetermined (x1, y1, x2, y2) coordinates of the bounding box. Default: None.

  • indices (Tensor, optional) โ€“ Permutation of the samples to use. Default: None.

  • uniform_sampling (bool, optional) โ€“ If True, sample the bounding box such that each pixel has an equal probability of being mixed. If False, defaults to the sampling used in the original paper implementation. Default: False.

Returns

  • input_mixed (torch.Tensor) โ€“ batch of inputs after cutmix has been applied.

  • target_perm (torch.Tensor) โ€“ The labels of the mixed-in examples

  • area (float) โ€“ The fractional area of the unmixed region.

  • bounding_box (tuple) โ€“ the (left, top, right, bottom) coordinates of the bounding box that defines the mixed region.

Raises

ValueError โ€“ If both length and bbox are provided.

Example

import torch
from composer.functional import cutmix_batch

N, C, H, W = 2, 3, 4, 5
num_classes = 10
X = torch.randn(N, C, H, W)
y = torch.randint(num_classes, size=(N,))
X_mixed, target_perm, area, _ = cutmix_batch(X, y, alpha=0.2)