rms

Root mean square value

Syntax

y = rms(x)

y = rms(x,"all")

y = rms(x,dim)

y = rms(x,vecdim)

y = rms(___,nanflag)

Description

y = rms(x) returns the root mean square (RMS) value of the input, x.

• If x is a row or column vector, then y is a real-valued scalar.

• If x is a matrix, then y is a row vector containing the RMS value for each column.

• If x is a multidimensional array, then y contains the RMS values computed along the first array dimension whose size does not equal 1. The size of y in this dimension is 1, while the sizes of all other dimensions remain the same as in x.

y = rms(x,"all") returns the RMS value of all elements in x.

y = rms(x,dim) operates along dimension dim. For example, if x is a matrix, then rms(x,2) operates on the elements in each row and returns a column vector containing the RMS value of each row..

y = rms(x,vecdim) operates along the dimensions specified in the vector vecdim. For example, if x is a matrix, then rms(x,[1 2]) operates on all the elements of x because every element of a matrix is contained in the array slice defined by dimensions 1 and 2.

y = rms(___,nanflag) specifies whether to include or omit NaN values in the calculation for any of the previous syntaxes. For example, rms(x,"omitnan") ignores NaN values when computing the RMS. By default, rms includes NaN values.

Examples

RMS Value of Vector

Compute the RMS value of a sinusoid.

t = 0:0.001:1-0.001;
x = cos(2*pi*100*t);
y = rms(x)

y = 
0.7071

RMS Values of Matrix Columns

Create a matrix and compute the RMS value of each column.

x = [4 -5 1; 2 3 5; -9 1 7];
y = rms(x)

y = 1×3

    5.8023    3.4157    5.0000

RMS Values of Matrix Rows

Create a matrix and compute the RMS value of each row by specifying the dimension as 2.

x = [6 4 23 -3; 9 -10 4 11; 2 8 -5 1];
y = rms(x,2)

y = 3×1

   12.1450
    8.9163
    4.8477

RMS Values of Array Pages

Create a 3-D array and compute the RMS value over each page of data (rows and columns).

x(:,:,1) = [2 4; -2 1];
x(:,:,2) = [9 13; -5 7];
x(:,:,3) = [4 4; 8 -3];
y = rms(x,[1 2])

y = 
y(:,:,1) =

    2.5000


y(:,:,2) =

     9


y(:,:,3) =

    5.1235

RMS Excluding Missing Values

Create a matrix containing NaN values.

x = [1.77 -0.005 NaN -2.95; NaN 0.34 NaN 0.19];

Compute the RMS values of the matrix, excluding NaN values. For matrix columns that contain any NaN value, rms computes with the non-NaN elements. For matrix columns that contain all NaN values, the RMS is NaN.

y = rms(x,"omitnan")

y = 1×4

    1.7700    0.2404       NaN    2.0903

Input Arguments

x — Input array

vector | matrix | multidimensional array

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

Data Types: single | double | logical | char
Complex Number Support: Yes

dim — Dimension to operate along

positive integer scalar

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

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

Consider an m-by-n input matrix, x:

• y = rms(x,1) computes the RMS value of the elements in each column of x and returns a 1-by-n row vector.

• y = rms(x,2) computes the RMS value of the elements in each row of x and returns an m-by-1 column vector.

vecdim — Vector of dimensions

vector of positive integers

Vector of dimensions to operate along, specified as a vector of positive integers. Each element represents a dimension of the input array. The length of the output in the specified operating dimensions is 1, while the other dimension lengths remain the same as the input.

For example, if x is a 2-by-3-by-3 array, then rms(x,[1 2]) returns a 1-by-1-by-3 array whose elements are the RMS values over each page of x.

nanflag — Missing value condition

"includemissing" (default) | "includenan" | "omitmissing" | "omitnan"

Missing value condition, specified as one of these values:

• "includemissing" or "includenan" — Include NaN values in x when computing the RMS. If any element in the operating dimension is NaN, then the corresponding element in y is NaN. "includemissing" and "includenan" have the same behavior.

• "omitmissing" or "omitnan" — Ignore NaN values in x when computing the RMS. If all elements in the operating dimension are NaN, then the corresponding element in y is NaN. "omitmissing" and "omitnan" have the same behavior.

More About

Root Mean Square Value

The root mean square value of an array x is

$$x_{\text{RMS}}=\sqrt{\frac{1}{N}{\displaystyle \sum _{n=1}^N{\left|x_n\right|}^2}},$$

with the summation performed along the specified dimension.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The rms function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

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

Usage notes and limitations:

• If used, the arguments dim, vecdim, and nanflag must be constant at code generation time.

• For input argument x:

  • If you do not specify a dimension, the code generator operates along the first dimension of the input array that is variable size or whose size does not equal 1. If this dimension is variable size at code generation time and is 1 at run time, a run-time error can occur. To avoid this error, specify the dimension.

  • If all dimensions of the input array are variable size at code generation time, this array cannot be empty at run time.

• Code generation does not support sparse matrix inputs for this function.

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

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2012a

R2023a: Specify missing value condition

Include or omit all missing values in the input array when computing the RMS by using the "includemissing" or "omitmissing" options. These options have the same behavior as the "includenan" and "omitnan" options, respectively.

R2022a: Calculate RMS for all elements

You can now calculate the RMS value of all elements of the input array by specifying "all". For example, rms(x,"all") returns the RMS value of all elements in the input array x.

R2022a: Calculate RMS along multiple dimensions

You can now calculate the RMS value along multiple dimensions by specifying a vector of positive integers. Use the vecdim input argument to specify the dimensions. For example, rms(x,[1 2]) operates along the first and second dimensions of x.

R2022a: Include or omit NaN values

You can now include or omit NaN values in the RMS calculation. Specify "includenan" to include NaN values, resulting in NaN. Specify "omitnan" to ignore all NaN values in the input. For example, rms(x,"includenan") includes NaN values when computing the RMS values, resulting in NaN.

R2022a: Moved to MATLAB from Signal Processing Toolbox

Previously, rms required Signal Processing Toolbox™.