moment

Central moment

collapse all in page

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.

example

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

example

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

example

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.

example

Examples

collapse all

Find Central Moment for Specified Order

Open Live Script

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

Open Live Script

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

Open Live Script

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])

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

Input Arguments

collapse all

`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.

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

`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 - μ)}^{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} \sum_{i = 1}^{n} {(x_{i} - \bar{x})}^{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 Automatic dimension restriction (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

moment

Syntax

Description

Examples

Find Central Moment for Specified Order

Find Central Moment Along Given Dimension

Find Central Moment Along Vector of Dimensions

Input Arguments

X — Input data vector | matrix | multidimensional array

order — Order of central moment positive integer

dim — Dimension positive integer

vecdim — Vector of dimensions positive integer vector

Output Arguments

m — Central moments scalar | vector | matrix | multidimensional array

Algorithms

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

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

Version History

See Also

`X` — Input data
vector | matrix | multidimensional array

`order` — Order of central moment
positive integer

`dim` — Dimension
positive integer

`vecdim` — Vector of dimensions
positive integer vector

`m` — Central moments
scalar | vector | matrix | multidimensional array

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

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