qfeval_functions.functions.nansum

nansum(x, dim=(), keepdim=False)[source]

Compute the sum of tensor elements along specified dimensions, ignoring NaN values.

This function calculates the sum of all valid (non-NaN) elements in a tensor along the specified dimension(s). Unlike PyTorch’s torch.nansum, this function returns NaN when no valid elements are found along a dimension, rather than returning 0. This behavior is more mathematically consistent for statistical operations where the absence of data should be explicitly represented as NaN.

The NaN-aware sum is computed as:

\[\text{nansum}(X) = \sum_{i \text{ valid}} X_i\]

where the sum is over all valid (non-NaN) values.

Parameters:

x (Tensor) – The input tensor containing values.
dim (Union[int, Tuple[int, ...]]) – The dimension(s) along which to compute the sum. If not specified (default is empty tuple), the sum is computed over all dimensions.
keepdim (bool) – Whether the output tensor has dim retained or not. Default is False.

Returns:

The sum values computed only over valid (non-NaN) values. When no valid values exist along a dimension, the result is NaN (unlike torch.nansum which returns 0). The shape depends on the input dimensions, dim, and keepdim parameters.

Return type:

Tensor

Example

>>> # Simple sum with NaN values
>>> x = torch.tensor([1.0, 2.0, nan, 4.0, 5.0])
>>> QF.nansum(x)
tensor(12.)

>>> # Compare with torch.nansum (returns 0 for all-NaN)
>>> all_nan = torch.tensor([nan, nan, nan])
>>> QF.nansum(all_nan)
tensor(nan)
>>> torch.nansum(all_nan)
tensor(0.)

>>> # 2D tensor with sum along columns
>>> x = torch.tensor([[1.0, nan, 3.0],
...                   [4.0, 5.0, nan]])
>>> QF.nansum(x, dim=0)
tensor([5., 5., 3.])

>>> # Sum along rows
>>> QF.nansum(x, dim=1)
tensor([4., 9.])

>>> # All dimensions
>>> x = torch.tensor([[1.0, 2.0],
...                   [nan, 4.0]])
>>> QF.nansum(x)
tensor(7.)

>>> # With keepdim
>>> x = torch.tensor([[1.0, nan, 3.0],
...                   [4.0, 5.0, nan]])
>>> QF.nansum(x, dim=1, keepdim=True)
tensor([[4.],
        [9.]])

>>> # All NaN slice returns NaN
>>> x = torch.tensor([[1.0, 2.0],
...                   [nan, nan]])
>>> QF.nansum(x, dim=1)
tensor([3., nan])

>>> # Multiple dimensions
>>> x = torch.tensor([[[1.0, nan], [3.0, 4.0]],
...                   [[nan, 6.0], [7.0, nan]]])
>>> QF.nansum(x, dim=(1, 2))
tensor([ 8., 13.])

Note

This function provides more mathematically consistent behavior than torch.nansum by returning NaN when no valid values are present, rather than 0. This is particularly important for statistical computations where the absence of data should be distinguished from a sum of zero.

Warning

When all values along a dimension are NaN, this function returns NaN (not 0 like torch.nansum). This behavior difference should be considered when replacing torch.nansum with this function.