nitorch_fastmath.reduce

Overview

This first section reimplements several reduction functions (sum, mean, max...), with a more consistent API than the native pytorch one:

• all functions can reduce across multiple dimensions simultaneously
• min/max/median functions only return the reduced tensor by default (not the original indices of the returned elements). They have a specific argument return_indices to request these indices.
• all functions have an omitnan argument, or alternatively a nan version (e.g., nansum) where omitnan=True by default.

The typical API for all functions is:

def fn(input, dim=None, keepdim=False, omitnan=False, inplace=False, out=None): ...
  """
  input   : tensor, Input tensor
  dim     : int or sequence[int], Dimensions to reduce (default: all)
  keepdim : bool, Do not sequeeze reduced dimensions (default: False)
  omitnan : bool, Discard NaNs form the reduction (default: False)
  inplace : bool, Allow the input tensor to be modified (default: False)
                  (only useful in conjunction with `omitnan=True`)
  out     : tensor, Output placeholder
  """

Reduction functions that pick a value from the input tensor (e.g., max) have the additional argument:

def fn(..., return_indices=False): ...
  """
  return_indices : bool, Also return indices of the picked elements
  """

---

max

max(input, dim=None, keepdim=False, omitnan=False, inplace=False, return_indices=False, out=None)

Multi-dimensional max reduction.

Signatures

max(input) -> Tensor
max(input, dim) -> Tensor
max(input, dim, return_indices=True) -> (Tensor, Tensor)

Warning

Contrary to torch.max, this function cannot compute the maximum of two tensors, it only computes the maximum of one tensor (along a dimension).

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or sequence[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
omitnan	`bool`	Omit NaNs (else, the reduction of a NaN and any other value is NaN)	False
inplace	`bool`	Allow modifying the input tensor in-place (Only useful if omitnan == True)	False
return_indices	`bool`	Return index of the max value on top of the value	False
out	`tensor or (tensor, tensor),` optional	Output placeholder	None

Returns:

Name	Type	Description
output	`tensor`	Reduced tensor
indices	`(..., [len(dim)]) tensor`	Indices of the max values. If dim is a scalar, the last dimension is dropped.

min

min(input, dim=None, keepdim=False, omitnan=False, inplace=False, return_indices=False, out=None)

Multi-dimensional min reduction.

Signatures

min(input) -> Tensor
min(input, dim) -> Tensor
min(input, dim, return_indices=True) -> (Tensor, Tensor)

Warning

Contrary to torch.min, this function cannot compute the minimum of two tensors, it only computes the minimum of one tensor (along a dimension).

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or sequence[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
omitnan	`bool`	Omit NaNs (else, the reduction of a NaN and any other value is NaN)	False
inplace	`bool`	Allow modifying the input tensor in-place (Only useful if omitnan == True)	False
return_indices	`bool`	Return index of the min value on top of the value	False
out	`tensor or (tensor, tensor)`	Output placeholder	None

Returns:

Name	Type	Description
output	`tensor`	Reduced tensor
indices	`(..., [len(dim)]) tensor`	Indices of the min values. If dim is a scalar, the last dimension is dropped.

nanmax

nanmax(input, dim=None, keepdim=False, inplace=False, return_indices=False, out=None)

Multi-dimensional max reduction, excluding NaNs.

Signatures

nanmax(input) -> Tensor
nanmax(input, dim) -> Tensor
nanmax(input, dim, return_indices=True) -> (Tensor, Tensor)

Warning

Contrary to torch.max, this function cannot compute the maximum of two tensors, it only computes the maximum of one tensor (along a dimension).

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or sequence[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
inplace	`bool`	Allow modifying the input tensor in-place (Only useful if omitnan == True)	False
return_indices	`bool`	Return index of the max value on top of the value	False
out	`tensor or (tensor, tensor)`	Output placeholder	None

Returns:

Name	Type	Description
output	`tensor`	Reduced tensor
indices	`(..., [len(dim)]) tensor`	Indices of the max values. If dim is a scalar, the last dimension is dropped.

nanmin

nanmin(input, dim=None, keepdim=False, inplace=False, return_indices=False, out=None)

Multi-dimensional min reduction, excluding NaNs.

Signatures

nanmin(input) -> Tensor
nanmin(input, dim) -> Tensor
nanmin(input, dim, return_indices=True) -> (Tensor, Tensor)

Warning

Contrary to torch.min, this function cannot compute the minimum of two tensors, it only computes the minimum of one tensor (along a dimension).

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or sequence[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
inplace	`bool`	Allow modifying the input tensor in-place (Only useful if omitnan == True)	False
return_indices	`bool`	Return index of the min value on top of the value	False
out	`tensor or (tensor, tensor`)	Output placeholder	None

Returns:

Name	Type	Description
output	`tensor`	Reduced tensor
indices	`(..., [len(dim)]) tensor`	Indices of the min values. If dim is a scalar, the last dimension is dropped.

median

median(input, dim=None, keepdim=False, omitnan=False, inplace=False, return_indices=False, out=None)

Multi-dimensional median reduction.

Signatures

median(input) -> Tensor
median(input, dim) -> Tensor
median(input, dim, return_indices=True) -> (Tensor, Tensor)

Note

This function always omits NaNs

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or sequence[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
return_indices	`bool`	Return index of the median value on top of the value	False
out	`tensor or (tensor, tensor)`	Output placeholder	None

Returns:

Name	Type	Description
output	`tensor`	Reduced tensor
indices	`(..., [len(dim)]) tensor`	Indices of the median values. If dim is a scalar, the last dimension is dropped.

sum

sum(input, dim=None, keepdim=False, omitnan=False, inplace=False, dtype=None, out=None)

Compute the sum of a tensor.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
omitnan	`bool`	Omit NaNs in the sum.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype
out	`tensor`	Output placeholder.	None

Returns:

Name	Type	Description
out	`tensor`	Output tensor

nansum

nansum(input, dim=None, keepdim=False, inplace=False, dtype=None, out=None)

Compute the sum of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype
out	`tensor`	Output placeholder.	None

Returns:

Name	Type	Description
out	tensor	Output tensor

mean

mean(input, dim=None, keepdim=False, omitnan=False, inplace=False, dtype=None, out=None)

Compute the mean of a tensor.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
omitnan	`bool`	Omit NaNs in the sum.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype
out	`tensor`	Output placeholder.	None

Returns:

Name	Type	Description
out	tensor	Output tensor

nanmean

nanmean(input, dim=None, keepdim=False, inplace=False, dtype=None, out=None)

Compute the mean of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype
out	`tensor`	Output placeholder.	None

Returns:

Name	Type	Description
out	`tensor`	Output tensor

var

var(input, dim=None, keepdim=False, unbiased=True, omitnan=False, inplace=False, dtype=None, out=None)

Compute the variance of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
unbiased	`bool`	Whether to use the unbiased estimation or not.	True
omitnan	`bool`	Omit NaNs.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype

Returns:

Name	Type	Description
out	`tensor`	Output tensor

nanvar

nanvar(input, dim=None, keepdim=False, unbiased=True, inplace=False, dtype=None, out=None)

Compute the variance of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
unbiased	`bool`	Whether to use the unbiased estimation or not.	True
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype

Returns:

Name	Type	Description
out	`tensor`	Output tensor

std

std(input, dim=None, keepdim=False, unbiased=True, omitnan=False, inplace=False, dtype=None, out=None)

Compute the standard deviation of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
unbiased	`bool`	Whether to use the unbiased estimation or not.	True
omitnan	`bool`	Omit NaNs.	False
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype

Returns:

Name	Type	Description
out	`tensor`	Output tensor

nanstd

nanstd(input, dim=None, keepdim=False, unbiased=True, inplace=False, dtype=None, out=None)

Compute the standard deviation of a tensor, excluding nans.

Parameters:

Name	Type	Description	Default
input	`tensor`	Input tensor.	required
dim	`int or list[int]`	Dimensions to reduce.	None
keepdim	`bool`	Keep reduced dimensions.	False
unbiased	`bool`	Whether to use the unbiased estimation or not.	True
inplace	`bool`	Authorize working inplace.	False
dtype	`dtype`	Accumulator data type	input.dtype

Returns:

Name	Type	Description
out	`tensor`	Output tensor