moment

Central moment

Syntax

m = moment(X,order)

m = moment(X,order,'all')

m = moment(X,order,dim)

m = moment(X,order,vecdim)

Description

m = moment(X,order) returns the central moment of X for the order specified by order.

• If X is a vector, then moment(X,order) returns a scalar value that is the k-order central moment of the elements in X.

• If X is a matrix, then moment(X,order) returns a row vector containing the k-order central moment of each column in X.

• If X is a multidimensional array, then moment(X,order) operates along the first nonsingleton dimension of X.

m = moment(X,order,'all') returns the central moment of the specified order for all elements of X.

m = moment(X,order,dim) takes the central moment along the operating dimension dim of X.

m = moment(X,order,vecdim) returns the central moment over the dimensions specified in the vector vecdim. For example, if X is a 2-by-3-by-4 array, then moment(X,1,[1 2]) returns a 1-by-1-by-4 array. Each element of the output array is the first-order central moment of the elements on the corresponding page of X.

Examples

Find Central Moment for Specified Order

Set the random seed for reproducibility of the results.

rng('default')

Generate a matrix with 6 rows and 5 columns.

X = randn(6,5)

X = 6×5

    0.5377   -0.4336    0.7254    1.4090    0.4889
    1.8339    0.3426   -0.0631    1.4172    1.0347
   -2.2588    3.5784    0.7147    0.6715    0.7269
    0.8622    2.7694   -0.2050   -1.2075   -0.3034
    0.3188   -1.3499   -0.1241    0.7172    0.2939
   -1.3077    3.0349    1.4897    1.6302   -0.7873

Find the third-order central moment of X.

m = moment(X,3)

m = 1×5

   -1.1143   -0.9973    0.1234   -1.1023   -0.1045

m is a row vector containing the third-order central moment of each column in X.

Find Central Moment Along Given Dimension

Find the central moment along different dimensions for a multidimensional array.

Set the random seed for reproducibility of the results.

rng('default') 

Create a 4-by-3-by-2 array of random numbers.

X = randn([4,3,2])

X = 
X(:,:,1) =

    0.5377    0.3188    3.5784
    1.8339   -1.3077    2.7694
   -2.2588   -0.4336   -1.3499
    0.8622    0.3426    3.0349


X(:,:,2) =

    0.7254   -0.1241    0.6715
   -0.0631    1.4897   -1.2075
    0.7147    1.4090    0.7172
   -0.2050    1.4172    1.6302

Find the fourth-order central moment of X along the default dimension.

m1 = moment(X,4)

m1 = 
m1(:,:,1) =

   11.4427    0.3553   33.6733


m1(:,:,2) =

    0.0360    0.4902    2.3821

By default, moment operates along the first dimension of X whose size does not equal 1. In this case, this dimension is the first dimension of X. Therefore, m1 is a 1-by-3-by-2 array.

Find the fourth-order central moment of X along the second dimension.

m2 = moment(X,4,2)

m2 = 
m2(:,:,1) =

    7.3476
   13.8702
    0.4625
    2.7741


m2(:,:,2) =

    0.0341
    2.2389
    0.0171
    0.6766

m2 is a 4-by-1-by-2 array.

Find the fourth-order central moment of X along the third dimension.

m3 = moment(X,4,3)

m3 = 4×3

    0.0001    0.0024    4.4627
    0.8093    3.8273   15.6340
    4.8866    0.7205    1.1412
    0.0811    0.0833    0.2433

m3 is a 4-by-3 matrix.

Find Central Moment Along Vector of Dimensions

Find the central moment over multiple dimensions by using the 'all' and vecdim input arguments.

Set the random seed for reproducibility of the results.

rng('default')

Create a 4-by-3-by-2 array of random numbers.

X = randn([4 3 2])

X = 
X(:,:,1) =

    0.5377    0.3188    3.5784
    1.8339   -1.3077    2.7694
   -2.2588   -0.4336   -1.3499
    0.8622    0.3426    3.0349


X(:,:,2) =

    0.7254   -0.1241    0.6715
   -0.0631    1.4897   -1.2075
    0.7147    1.4090    0.7172
   -0.2050    1.4172    1.6302

Find the third-order central moment of X.

mall = moment(X,3,'all')

mall = 
0.2431

mall is the third-order central moment of the entire input data set X.

Find the third-order moment of each page of X by specifying the first and second dimensions.

mpage = moment(X,3,[1 2])

mpage = 
mpage(:,:,1) =

    0.6002


mpage(:,:,2) =

   -0.3475

For example, mpage(1,1,2) is the third-order central moment of the elements in X(:,:,2).

Find the third-order moment of the elements in each X(i,:,:) slice by specifying the second and third dimensions.

mrow = moment(X,3,[2 3])

mrow = 4×1

    2.7552
    0.0443
   -0.7585
    0.5340

For example, mrow(1) is the third-order central moment of the elements in X(1,:,:).

Input Arguments

X — Input data

vector | matrix | multidimensional array

Input data that represents a sample from a population, specified as a vector, matrix, or multidimensional array.

• If X is a vector, then moment(X,order) returns a scalar value that is the k-order central moment of the elements in X.

• If X is a matrix, then moment(X,order) returns a row vector containing the k-order central moment of each column in X.

• If X is a multidimensional array, then moment(X,order) operates along the first nonsingleton dimension of X.

To specify the operating dimension when X is a matrix or an array, use the dim input argument.

Data Types: single | double

order — Order of central moment

positive integer

Order of the central moment, specified as a positive integer.

Data Types: single | double

dim — Dimension

positive integer

Dimension along which to operate, specified as a positive integer. If you do not specify a value for dim, then the default is the first nonsingleton dimension of X.

Consider the third-order central moment of a matrix X:

• If dim is equal to 1, then moment(X,3,1) returns a row vector that contains the third-order central moment of each column in X.

• If dim is equal to 2, then moment(X,3,2) returns a column vector that contains the third-order central moment of each row in X.

If dim is greater than ndims(X) or if size(X,dim) is 1, then moment returns an array of zeros the same size as X.

Data Types: single | double

vecdim — Vector of dimensions

positive integer vector

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

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

Data Types: single | double

Output Arguments

m — Central moments

scalar | vector | matrix | multidimensional array

Central moments, returned as a scalar, vector, matrix, or multidimensional array.

Algorithms

The central moment of order k for a distribution is defined as

$$m_k=E{(x-\mu )}^k,$$

where µ is the mean of x, and E(t) represents the expected value of the quantity t. The moment function computes a sample version of this population value.

$$m_k=\frac{1}{n}{\displaystyle \sum _{i=1}^n{\left(x_i-\overline{x}\right)}^k}.$$

Note that the first-order central moment is zero, and the second-order central moment is the variance computed using a divisor of n rather than n – 1, where n is the length of the vector x or the number of rows in the matrix X.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The 'all' and vecdim input arguments are not supported.

• The dim input argument must be a compile-time constant.

• If you do not specify the dim input argument, the working (or operating) dimension can be different in the generated code. As a result, run-time errors can occur. For more details, see Incompatibility with MATLAB for Default Dimension Selection (MATLAB Coder).

• If order is nonintegral and X is real, use moment(complex(X),order).

For more information on code generation, see Introduction to Code Generation and General Code Generation Workflow.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

• The 'all' and vecdim input arguments are not supported.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a