# variance

variance (and mean) of a vector or matrix (or hypermatrix) of real or complex numbers

## Calling Sequence

                [s [,mc]] = variance(x [,orien [,m]])

                [s, mc] = variance(x)
                [s, mc] = variance(x, "r"|1 )
                [s, mc] = variance(x, "c"|2 )
                [s, mc] = variance(x, "*"  , %nan)
                [s, mc] = variance(x, "r"|1, %nan)
                [s, mc] = variance(x, "c"|2, %nan)
                s = variance(x, "*", m)
                s = variance(x, "r"|1, m)
                s = variance(x, "c"|2, m)

## Arguments

x

  real or complex vector or matrix. A hypermatrix is accepted only for undirectional computations `variance(x)` or `variance(x,"*",m)`

orien

  the orientation of the computation. Valid values are

  - 1 or "r": result is a row, after a column-wise computation.
  - 2 or "c": result is a column, after a row-wise computation.
  - "*": full undirectional computation (default); explicitly required when `m` is used.
m

  The known mean of the underlying statistical distribution law (assuming that it is known).

  - "*" mode (default): `m` must be scalar
  - "r" or 1 mode: `m` is a row of length `size(x,2)`. The variance along the column #j is computed using `m(j)` as the mean for the considered column. If `m(j)` is the same for all columns, it can be provided as a scalar `m`.
  - "c" or 2 mode: `m` is a column of length `size(x,1)`. The variance along the row #i is computed using `m(i)` as the mean for the considered row. If `m(i)` is the same for all rows, it can be provided as a scalar `m`.

  When `m` is not provided, the `variance` is built dividing the quadratic distance of `n` values to `mean(x)` (or `mean(x,"c")` or `mean(x,"r")`) by `n-1` (`n` being `length(x)` or `size(x,1)` or `size(x,2)`). If the elements of `x` are mutually independent, the result is then statistically unbiased.

  Else, the `variance` is built dividing the quadratic distance of values to `m` by the number n of considered values (n being length(x) or size(x,1) or size(x,2)).

  If a true value `m` independent from x elements is used, `x` and `m` values are mutually independent, and the result is then unbiased.

  When the special value `m = %nan` is provided, the variance is still normalized by n (not n-1) but is computed using `m=mean(x)` instead (or `m = mean(x,"c")` or `m = mean(x,"r")`). This `m` does not bring independent information, and yields a statistically biased result.

s
  The variance of unweighted values of `x` elements. It is a scalar or a column vector or a row vector according to `orien`.
mc
  Scalar or `orien`-wise mean of `x` elements (unweighted) (`= mean(x,..)`), as computed before and used as reference in the variance.

## Description

This function computes the variance of the real or complex numbers stored into a vector or matrix `x`. If `x` is complex, `variance(x,..) = variance(real(x),..) + variance(imag(x),..)` is returned.

For a vector, a matrix, or a hypermatrix `x`, `s = variance(x)` returns in the scalar `s` the variance of all the entries of `x`.

`s = variance(x,"c")` (or, equivalently, `s = variance(x,2)`) is the columnwise variance: `s` is a column vector, with `s(j) = variance(x(j,:))`.

`s = variance(x,"r")` (or, equivalently, `s = variance(x,1)`) is the rowwise variance: `s` is a row vector, with `s(i) = variance(x(:,i))`.

The second output argument `m` is the mean of the input, with respect to the `orien` parameter.

The `variance(x, "*"|"c"|"r", 1)` synopsis used only in Scilab 5.4.1 must be replaced with `variance(x, "*"|"c"|"r", %nan)`. `variance(x, "*"|"c"|"r", 1)` will warn the user until Scilab 6.0. Indeed, `1` will be now considered as `m=1`. If `1` is the true value provided as `m`, the warning may be avoided entering `1+%eps` instead of `1`.

## Examples

    x = [ 0.2113249 0.0002211 0.6653811; 0.7560439 0.4453586 0.6283918 ]
    s = variance(x)
    s = variance(x, "r")
    s = variance(x, "c")

    // The underlying statistical distribution and its mean are known:
    x = grand(100, 5, "unf", 0, 7);      // Uniform distribution on [0, 7]
    // => the true asymptotic mean is (0+7)/2 = 3.5 and variance = (7-0)^2/12
    (7-0)^2/12                  // True asymptotic variance
    s = variance(x)             // Unbiased (division by n-1).
    s = variance(x, "*", 3.5)   // Unbiased (division by n). Always >= variance(x)
    s = variance(x, "*", %nan)    // Biased   (division by n). Always <= variance(x)
    // Across columns:
    s = variance(x, "c")
    s = variance(x, "c", 3.5)
    s = variance(x, "c", %nan)

    // With complex numbers uniformly distributed on [0,1] + [0,1].i:
    x = rand(4, 3) + rand(4, 3)*%i
    s = variance(x)
    s = variance(x, "*", 0.5 + 0.5*%i)
    s = variance(x, "*", %nan)
    s = variance(x, "r")
    s = variance(x, "c")

    // With a hypermatrix
    x = rand(3, 2, 2)    // Uniform distribution on [0, 1]
    s = variance(x)
    s = variance(x, "*", 0.5)
    s = variance(x, "*", %nan)
    // s = variance(x, "r")  // Is not supported for a hypermatrix
    // s = variance(x, "c")  // Is not supported for a hypermatrix

## See Also

- variancef
- mtlb_var
- stdev

## Bibliography

Wonacott, T.H. & Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley & Sons, 1990.

## History

5.5.0

- variance(x, orien, 0|1) removed (as introduced in Scilab 5.4.1)

- variance(x, orien, m) introduced: the true mean m of the underlying statistical law can be used.

- variance(x, orien, %nan) introduced: mean(x,..) is used but divided by n values (instead of n-1)

- [s, mc] = variance(x,..) introduced: the mean mc computed from x is now also returned

5.4.1

- variance(complexes) fixed. variance(x,"*",1) introduced. Vectorization of the code for directional usages variance(x,"r"|"c"). Full revision of the help page