cutmix#
Core CutMix classes and functions.
Functions
Create new samples using combinations of pairs of samples. |
Classes
CutMix trains the network on non-overlapping combinations of pairs of examples and interpolated targets rather than individual examples and targets. |
- class composer.algorithms.cutmix.cutmix.CutMix(alpha=1.0, interpolate_loss=False, uniform_sampling=False, input_key=0, target_key=1)[source]#
Bases:
composer.core.algorithm.Algorithm
CutMix trains the network on non-overlapping combinations of pairs of examples and interpolated targets rather than individual examples and targets.
This is done by taking a non-overlapping combination of a given batch X with a randomly permuted copy of X. The area is drawn from a
Beta(alpha, alpha)
distribution.Training in this fashion sometimes reduces generalization error.
- Parameters
alpha (float, optional) โ the psuedocount for the Beta distribution used to sample area parameters. As
alpha
grows, the two samples in each pair tend to be weighted more equally. Asalpha
approaches 0 from above, the combination approaches only using one element of the pair. Default:1
.interpolate_loss (bool, optional) โ Interpolates the loss rather than the labels. A useful trick when using a cross entropy loss. Will produce incorrect behavior if the loss is not a linear function of the targets. Default:
False
uniform_sampling (bool, optional) โ If
True
, sample the bounding box such that each pixel has an equal probability of being mixed. IfFalse
, defaults to the sampling used in the original paper implementation. Default:False
.input_key (str | int | Tuple[Callable, Callable] | Any, optional) โ A key that indexes to the input from the batch. Can also be a pair of get and set functions, where the getter is assumed to be first in the pair. The default is 0, which corresponds to any sequence, where the first element is the input. Default:
0
.target_key (str | int | Tuple[Callable, Callable] | Any, optional) โ A key that indexes to the target from the batch. Can also be a pair of get and set functions, where the getter is assumed to be first in the pair. The default is 1, which corresponds to any sequence, where the second element is the target. Default:
1
.
Example
from composer.algorithms import CutMix algorithm = CutMix(alpha=0.2) trainer = Trainer( model=model, train_dataloader=train_dataloader, eval_dataloader=eval_dataloader, max_duration="1ep", algorithms=[algorithm], optimizers=[optimizer] )
- composer.algorithms.cutmix.cutmix.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
oralpha
. Iflength
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 aBeta(alpha, alpha)
distribution. The original paper uses a fixed value ofalpha = 1
.Alternatively, one may provide a bounding box to mask directly, in which case
alpha
is ignored andlength
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
oralpha
.- 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 oftarget
must be integer class ids in the range0..num_classes
. In the latter case, rows oftarget
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 ofH
andW
, 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. IfFalse
, 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
andbbox
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)