Engee documentation

std

The standard deviation.

Library

EngeeDSP

Syntax

Function call

  • S,M = std(A) — returns the standard deviation S elements A by the first dimension of the array, the size of which is not equal to 1. By default, the standard deviation is normalized by N-1, where N — the number of values. It also returns the mathematical expectation. M elements A, used to calculate the standard deviation. If S is the weighted standard deviation, then M — weighted average.

    • If A is a vector of quantities, then S — a scalar.

    • If A is a matrix whose columns are random variables and rows are scalar quantities, then S — vector is a row containing the standard deviation corresponding to each column.

    • If A — a multidimensional array, then std(A) it acts on the first dimension of the array, the size of which is not equal to 1 considering the elements as vectors. Size S in this dimension , it becomes equal to 1, while the dimensions of all other dimensions remain the same as in A.

    • If A — a scalar, then S equally 0.

    • If A — an empty array of size 0 on 0 Then S equally NaN.

  • S,M = std(A,w) — defines the weight scheme. By w = 0 (by default) the standard deviation has a normalization factor N-1, where N — the number of values. By w = 1 The standard deviation has a normalization factor equal to the number of values. Argument w It can also be a weight vector containing non-negative elements. In this case, the length is w It must be equal to the length of the measurement it is working on. std.

  • S,M = std(A,w,"all") — returns the standard deviation for all elements A When w equally 0 or 1.

  • S,M = std(A,w,dim) — returns the standard deviation of the measurement dim. To keep the default normalization when specifying the operation dimension, set w = 0 in the second argument.

  • S,M = std(A,w,vecdim) — returns the standard deviation of the measurements specified in the vector vecdim When w equally 0 or 1. For example, if A — the matrix, then std(A,0,[1 2]) returns the standard deviation for all elements in A since each element of the matrix is contained in a slice of the array defined by the dimensions 1 and 2.

  • S,M = std(___,missingflag) — determines whether to include or exclude missing values in A for any of the previous syntax options. For example, std(A,"omitmissing") ignores all missing values when calculating the standard deviation. By default std includes missing values.

Arguments

Input arguments

# A — input array

+ vector | the matrix | multidimensional array

Details

An input array specified as a vector, matrix, or multidimensional array. If A — a scalar, then std(A) returns 0. If A — an empty array of size 0 on 0 Then std(A) returns NaN.

Типы данных

Float32, Float64, DateTime
Support for complex numbers

Yes

# w — weight

+ 0 (default) | 1 | vector

Details

The weight set by one of the following values:

  • 0 — normalize by N-1, where N — the number of values. If there is only one value, the weight is 1.

  • 1 — normalize by N.

  • A vector consisting of non-negative scalar weights corresponding to the dimension A, which is used to calculate the standard deviation.

Типы данных

Float32, Float64

# dim — the measurement for which the operation is performed

+ a positive integer scalar

Details

The dimension on which the operation is performed is specified as a positive integer scalar. If no dimension is specified, the first dimension of the array is used by default, the size of which is not equal to 1.

Argument dim specifies a dimension whose length is reduced to 1. Meaning size(S,dim) equally 1, while the dimensions of all other dimensions remain the same.

Consider the input matrix A size m on n:

  • std(A,0,1) calculates the standard deviation of the elements in each column of the matrix A and returns a vector string of the size 1 on n.

    std 1

  • std(A,0,2) calculates the standard deviation of the elements in each row of the matrix A and returns a column vector of size m on 1.

    std 2

If dim more ndims(A) Then std(A) returns an array of zeros of the same size as A.

# vecdim — measurement vector

+ a vector of positive integers

Details

A vector of dimensions defined as a vector of positive integers. Each element represents a dimension of the input array. The length of the output data in the specified operating measurements is 1, while the other dimensions remain unchanged.

Consider the input array A size 2×3×3. Then std(A,0,[1 2]) returns an array of size 1×1×3, the elements of which represent the standard deviations calculated for each layer A.

std 3 en

# missingflag — condition for missing a value

+ "includemissing" (by default) | "includenan" | "includenat" | "omitmissing" | "omitnan" | "omitnat"

Details

The condition for missing a value, set as one of the values in this table.

Meaning Input data type Description

"includemissing"

All supported data types

When calculating the standard deviation, missing values are taken into account in A and w. If any element is missing in the working dimension, then the corresponding element in S absent.

"includenan"

Float64, Float32

"includenat"

DateTime

"omitmissing"

All supported data types

Missing values in A and w The standard deviation for a smaller number of points is ignored and calculated. If all the elements in the working dimension are missing, then the corresponding element in S absent.

"omitnan"

Float64, Float32

"omitnat"

DateTime

Output arguments

# S — standard deviation

+ scalar | vector | the matrix | multidimensional array

Details

The standard deviation returned as a scalar, vector, matrix, or multidimensional array.

  • If A is a vector of quantities, then S — a scalar.

  • If A is a matrix whose columns are random variables and rows are scalar variables, then S — vector is a row containing the standard deviation corresponding to each column.

  • If A — a multidimensional array, then std(A) it acts on the first dimension of the array, the size of which is not equal to 1 considering the elements as vectors. Size S in this dimension , it becomes equal to 1, while the dimensions of all other dimensions remain the same as in A.

  • If A — a scalar, then S equally 0.

  • If A — an empty array of size 0 on 0 Then S equally NaN.

# M — mathematical expectation

+ scalar | vector | the matrix | multidimensional array

Details

The mathematical expectation returned as a scalar, vector, matrix, or multidimensional array.

  • If A is a vector of quantities, then M — a scalar.

  • If A is a matrix whose columns are random variables and rows are scalar quantities, then M — vector is a row containing the mathematical expectation for each column.

  • If A — a multidimensional array, then std(A) it acts on the first dimension of an array, the size of which is not equal to 1 considering the elements as vectors. Size M in this dimension , it becomes equal to 1, while the dimensions of all other dimensions remain the same as in A.

  • If A — a scalar, then M equally A.

  • If A — an empty array of size 0 on 0 Then M equally NaN.

If S is the weighted standard deviation, then M — weighted average.

Examples

The standard deviation of the matrix columns

Details

Let’s create a matrix and calculate the standard deviation of each column.

import EngeeDSP.Functions: std

A = [4 -5 1; 2 3 5; -9 1 7]
S = std(A).S
1×3 Matrix{Float64}:
 7.0  4.16333  3.05505

Standard deviation of a three-dimensional array

Details

Let’s create a three-dimensional array and calculate the standard deviation for the first dimension.

import EngeeDSP.Functions: std

A = cat([2 4; -2 1], [9 13; -5 7], [4 4; 8 -3]; dims=3)
S = std(A).S
1×2×3 Array{Float64, 3}:
[:, :, 1] =
 2.82843  2.12132

[:, :, 2] =
 9.89949  4.24264

[:, :, 3] =
 2.82843  4.94975

Specifying the weighting coefficients of the standard deviation

Details

Let’s create a matrix and calculate the standard deviation of each column according to the weight vector. w.

import EngeeDSP.Functions: std

A = [1 5; 3 7; -9 2]
w = [1 1 0.5]
S = std(A, w).S
1×2 Matrix{Float64}:
 4.48999  1.83303

The standard deviation across the rows of the matrix

Details

Let’s create a matrix and calculate the standard deviation for each row.

import EngeeDSP.Functions: std

A = [6 4 23 -3; 9 -10 4 11; 2 8 -5 1]
S = std(A, 0, 2).S
3×1 Matrix{Float64}:
 11.030261405182864
  9.46924847422786
  5.32290647422377

The standard deviation of the array layer

Details

Let’s create a three-dimensional array and calculate the standard deviation for each data layer (rows and columns).

import EngeeDSP.Functions: std

A = cat([2 4; -2 1], [9 13; -5 7], [4 4; 8 -3]; dims=3)
S = std(A, 0, [1 2]).S
1×1×3 Array{Float64, 3}:
[:, :, 1] =
 2.5

[:, :, 2] =
 7.745966692414834

[:, :, 3] =
 4.573474244670748

Standard deviation without missing values

Details

Create a matrix containing the values NaN.

A = [1.77 NaN -2.95; NaN 0.34 0.19]
2×3 Matrix{Float64}:
   1.77  NaN     -2.95
 NaN       0.34   0.19

Calculate the standard deviation of the matrix, excluding the missing values. For matrix columns containing any value NaN, function std calculated using all elements except NaN.

import EngeeDSP.Functions: std

S = std(A, "omitmissing").S
1×3 Matrix{Float64}:
 0.0  0.0  2.22032

Standard deviation and mathematical expectation

Details

Let’s create a matrix and calculate the standard deviation and mathematical expectation for each column.

import EngeeDSP.Functions: std

A = [4 -5 1; 2 3 5; -9 1 7]
S, M = std(A)
(S = [7.0 4.163331998932266 3.055050463303893], M = [-1.0 -0.3333333333333333 4.333333333333333])

Let’s create a matrix and calculate the weighted standard deviation and weighted average of each column according to the weight vector. w.

A = [1 5; 3 7; -9 2]
w = [1 1 0.5]
S, M = std(A, w)
(S = [4.48998886412873 1.8330302779823362], M = [-0.2 5.2])

Additional Info

Standard deviation

Details

For the vector of finite length, consisting of for scalar quantities, the standard deviation is defined as

where — mathematical expectation :

The standard deviation is the square root of the variance.

Some definitions of standard deviation use a normalization factor. Instead of . A normalization factor can be used by specifying the weight 1, which gives the square root of the second moment of the sample relative to its mathematical expectation.

Regardless of the normalization factor for the standard deviation, it is assumed that the expectation value has a normalization factor .

Weighted standard deviation

Details

For the vector of finite length, consisting of scalar quantities and weight schemes , the weighted standard deviation is defined as

where — weighted average .

Weighted average

Details

For a random variable vector , consisting of scalar quantities and weight schemes , the weighted average is defined as