torchrelay.extra

Overview

Modules
`bounds`	Boundary conditions.
Padding
`pad`	Pad a tensor.
`ensure_shape`	Pad/crop a tensor so that it has a given shape.
`roll`	Like `torch.roll`, but with any boundary condition.
Labels
`isin`	Returns a mask for elements that belong to labels.
`one_hot`	One-hot encode a volume of labels.
`relabel`	Relabel a label tensor according to a lookup table.

ensure_shape

ensure_shape(inp, shape, mode='constant', value=0, side='post')

Pad/crop a tensor so that it has a given shape

Parameters:

Name	Type	Description	Default
`inp`	`tensor`	Input tensor	required
`shape`	`[sequence of] int`	Output shape	required
`mode`	`{'constant', 'replicate', 'reflect', 'mirror', 'circular'}`	Boundary mode	`'constant'`
`value`	`scalar`	Value for mode 'constant'	`0`
`side`	`{'pre', 'post', 'both'}`	Side to crop/pad	`'post'`

Returns:

Name	Type	Description
`out`	`tensor`	Padded tensor with shape `shape`

roll

roll(inp, shifts=1, dims=None, bound='circular')

Like torch.roll, but with any boundary condition

Warning

When dims is None, we do not flatten but shift all dimensions. This differs from the behavior of torch.roll .

Parameters:

Name	Type	Description	Default
`inp`	`tensor`	Input	required
`shifts`	`[sequence of] int`	Amount by which to roll. Positive shifts to the right, negative to the left.	`1`
`dims`	`[sequence of] int`	Dimensions to roll. By default, shifts apply to all dimensions if a scalar, or to the last N if a sequence.	`None`
`bound`	`{'constant', 'replicate', 'reflect', 'mirror', 'circular'}`	Boundary condition	`'circular'`

Returns:

Name	Type	Description
`out`	`tensor`	Rolled tensor

isin

isin(tensor, labels)

Returns a mask for elements that belong to labels

Parameters:

Name	Type	Description	Default
`tensor`	`(*shape_tensor) tensor_like`	Input tensor	required
`labels`	`(*shape_labels, nb_labels) tensor_like`	Labels. `shape_labels` and `shape_tensor` should be broadcastable.	required

Returns:

Name	Type	Description
`mask`	`(*shape) tensor[bool]`

one_hot

one_hot(x, dim=-1, exclude_labels=None, exclude_missing=False, max_label=None, implicit=False, implicit_index=0, dtype=None, return_lookup=False)

One-hot encode a volume of labels.

Note

This function extends torch.nn.functional.one_hot.

Parameters:

Name	Type	Description	Default
`x`	`tensor`	An integer-type tensor with label values.	required
`dim`	`int`	Dimension in which to insert the one-hot channel.	`-1`
`exclude_labels`	`sequence[int]`	A list of labels to exclude from one-hot encoding.	`None`
`exclude_missing`	`bool`	Exclude missing labels from one-hot encoding (their channel will be squeezed)	`False`
`max_label`	`int`	Maximum label value	`None`
`implicit`	`bool`	Make the returned tensor have an implicit background class. In this case, output probabilities do not sum to one, but to some value smaller than one.	`False`
`implicit_index`	`int`	Output channel to make implicit	`0`
`dtype`	`dtype`	Output data type.	`None`
`return_lookup`	`bool`	Return lookup table from one-hot indices to labels	`False`

Returns:

Name	Type	Description
`y`	`tensor`	One-hot tensor. The number of one-hot channels is equal to `x.max() - len(exclude) + 1` if not `implicit` else `x.max() - len(exclude)`.

pad

pad(inp, padsize, mode='constant', value=0, side=None)

Pad a tensor.

This function is a bit more generic than torch's native pad (torch.nn.functional.pad), but probably a bit slower:

works with any input type
works with arbitrarily large padding size
crops the tensor for negative padding values
implements additional padding modes

When used with defaults parameters (side=None), it behaves exactly like torch.nn.functional.pad

Boundary modes

Like in PyTorch's pad, boundary modes include:

'circular' (or 'dft')
'mirror' (or 'dct1')
'reflect' (or 'dct2')
'replicate' (or 'nearest')
'constant' (or 'zero')

as well as the following new modes:

'antimirror' (or 'dst1')
'antireflect' (or 'dst2')

Side modes

Side modes are 'pre', 'post', 'both' or None.

If side is not None, inp.dim() values (or less) should be provided.
If side is None, twice as many values should be provided, indicating different padding sizes for the 'pre' and 'post' sides.
If the number of padding values is less than the dimension of the input tensor, zeros are prepended.

Parameters:

Name	Type	Description	Default
`inp`	`tensor`	Input tensor	required
`padsize`	`[sequence of] int`	Amount of padding in each dimension.	required
`mode`	`{'constant', 'replicate', 'reflect', 'mirror', 'circular'}`	Padding mode	`'constant'`
`value`	`scalar`	Value to pad with in mode 'constant'.	`0`
`side`	`{'left', 'right', 'both', None}`	Use padsize to pad on left side ('pre'), right side ('post') or both sides ('both'). If None, the padding side for the left and right sides should be provided in alternate order.	`None`

Returns:

Type	Description
`tensor`	Padded tensor.

relabel

relabel(x, lookup=None)

Relabel a label tensor according to a lookup table

Parameters:

Name	Type	Description	Default
`x`	`tensor`	Tensor or input labels	required
`lookup`	`(dict or sequence) of [sequence of] int`	The input labels to map to each output label. If not provided, use contiguous labels (i.e., `lookup=x.unique().tolist()`).	`None`

Returns:

Name	Type	Description
`x`	`tensor`

Examples:

Contiguous relabeling

inp = torch.as_tensor([8, 5, 3, 5])
out = relabel(inp)
print(out.tolist())

Output

[2, 1, 0, 1]

List lookup

inp = torch.as_tensor([8, 5, 3, 5])
out = relabel(inp, [8, 3, 5])
print(out.tolist())

Output

[0, 2, 1, 2]

Dictionary lookup

inp = torch.as_tensor([8, 5, 3, 5])
out = relabel(inp, {10: 3, 11: 5, 12: 8})
print(out.tolist())

Output

[12, 11, 10, 11]

Merge lookup

inp = torch.as_tensor([8, 5, 3, 5])
out = relabel(inp, {3: 3, 5: [5, 8]})
print(out.tolist())

Output

[5, 5, 3, 5]