Main Content

nansum

(Not recommended) Sum, ignoring NaN values

nansum is not recommended. Use the MATLAB® function sum instead. With the sum function, you can specify whether to include or omit NaN values for the calculation. For more information, see Compatibility Considerations.

Description

example

y = nansum(X) returns the sum of the elements of X, computed after removing all NaN values.

  • If X is a vector, then nansum(X) is the sum of all the non-NaN elements of X.

  • If X is a matrix, then nansum(X) is a row vector of column sums, computed after removing NaN values.

  • If X is a multidimensional array, then nansum operates along the first nonsingleton dimension of X. The size of this dimension becomes 1 while the sizes of all other dimensions remain the same. nansum removes all NaN values.

For information on how nansum treats arrays of all NaN values, see Tips.

example

y = nansum(X,'all') returns the sum of all elements of X, computed after removing NaN values.

example

y = nansum(X,dim) returns the sum along the operating dimension dim of X, computed after removing NaN values.

example

y = nansum(X,vecdim) returns the sum over the dimensions specified in the vector vecdim. The function computes the sums after removing NaN values. For example, if X is a matrix, then nansum(X,[1 2]) is the sum of all non-NaN elements of X because every element of a matrix is contained in the array slice defined by dimensions 1 and 2.

Examples

collapse all

Find the column sums for matrix data with missing values.

X = magic(3);
X([1 6:9]) = NaN
X = 3×3

   NaN     1   NaN
     3     5   NaN
     4   NaN   NaN

y = nansum(X)
y = 1×3

     7     6     0

Find the sum of all the values in an array, ignoring missing values.

Create a 2-by-4-by-3 array X with some missing values.

X = reshape(1:24,[2 4 3]);
X([5:6 20]) = NaN
X = 
X(:,:,1) =

     1     3   NaN     7
     2     4   NaN     8


X(:,:,2) =

     9    11    13    15
    10    12    14    16


X(:,:,3) =

    17    19    21    23
    18   NaN    22    24

Find the sum of the elements of X.

y = nansum(X,'all')
y = 269

Find the row sums for matrix data with missing values by specifying to compute the sums along the second dimension.

X = magic(3);
X([1 6:9]) = NaN
X = 3×3

   NaN     1   NaN
     3     5   NaN
     4   NaN   NaN

y = nansum(X,2)
y = 3×1

     1
     8
     4

Find the sum of a multidimensional array over multiple dimensions.

Create a 2-by-4-by-3 array X with some missing values.

X = reshape(1:24,[2 4 3]);
X([5:6 20]) = NaN
X = 
X(:,:,1) =

     1     3   NaN     7
     2     4   NaN     8


X(:,:,2) =

     9    11    13    15
    10    12    14    16


X(:,:,3) =

    17    19    21    23
    18   NaN    22    24

Find the sum of each page of X by specifying dimensions 1 and 2 as the operating dimensions.

ypage = nansum(X,[1 2])
ypage = 
ypage(:,:,1) =

    25


ypage(:,:,2) =

   100


ypage(:,:,3) =

   144

For example, ypage(1,1,1) is the sum of the non-NaN elements in X(:,:,1).

Find the sum of the elements in each X(i,:,:) slice by specifying dimensions 2 and 3 as the operating dimensions.

yrow = nansum(X,[2 3])
yrow = 2×1

   139
   130

For example, yrow(2) is the sum of the non-NaN elements in X(2,:,:).

Input Arguments

collapse all

Input data, specified as a scalar, vector, matrix, or multidimensional array.

If X is an empty array, then nansum(X) is 0.

Data Types: single | double

Dimension to operate along, specified as a positive integer scalar. If you do not specify a value, then the default value is the first array dimension whose size does not equal 1.

dim indicates the dimension whose length reduces to 1. size(y,dim) is 1 while the sizes of all other dimensions remain the same.

Consider a two-dimensional array X:

  • If dim is equal to 1, then nansum(X,1) returns a row vector containing the sum for each column.

  • If dim is equal to 2, then nansum(X,2) returns a column vector containing the sum for each row.

If dim is greater than ndims(X) or if size(X,dim) is 1, then nansum returns X, with 0 values in the place of any missing values.

Data Types: single | double

Vector of dimensions, specified as a positive integer vector. Each element of vecdim represents a dimension of the input array X. The output y has length 1 in the specified operating dimensions. The other dimension lengths are the same for X and y.

For example, if X is a 2-by-3-by-3 array, then nansum(X,[1 2]) returns a 1-by-1-by-3 array. Each element of the output array is the sum of the elements on the corresponding page of X.

Mapping of input dimension of 2-by-3-by-3 to output dimension of 1-by-1-by-3

Data Types: single | double

Output Arguments

collapse all

Sum values, returned as a scalar, vector, matrix, or multidimensional array.

Tips

  • When nansum computes the sum of an array of all NaN values, the array is empty once the NaN values are removed and, therefore, the sum of the remaining elements is 0. The output 0 is not a sum of NaN values.

Extended Capabilities

Version History

Introduced before R2006a

collapse all

R2020b: nansum is not recommended

nansum is not recommended. Use the MATLAB function sum instead. There are no plans to remove nansum.

To update your code, change instances of the function name nansum to sum. Then specify the 'omitnan' option for the nanflag input argument.

The sum function has these advantages over the nansum function:

  • sum offers more extended capabilities for supporting tall arrays, GPU arrays, distribution arrays, C/C++ code generation, and GPU code generation.

  • sum returns an output value with a specified data type.

See Also

|