# variancef

variance (and mean) of a vector or matrix of frequency-weighted real or complex numbers

## Calling Sequence

                [s [,mc]] = variancef(x, fre [,orien [,m]])

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

## Arguments

x

  vector or matrix of real or complex numbers

fre

  vector or matrix of positive decimal integers = frequencies: `fre(i,j)` is the number of times that `x(i,j)` must be counted. `fre` and `x` have same sizes.

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,fre)`(or `mean(x,fre,"c")` or `mean(x,fre,"r")`) by (n-1) (n being sum(fre) or sum(fre,"c") or sum(fre,"r")). 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.

  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, fre)` instead (or `m = mean(x,fre,"c")` or `m = mean(x,fre,"r")`). This `m` does not bring independent information, and yields a statistically biased result.

s
  The variance of weighted 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 weighted `x` elements (`= mean(x, fre,..)`), as computed before and used as reference in the variance.

## Description

This function computes the variance of the values of a vector or matrix `x`, each of them `x(i,j)` being counted `fre(i,j)` times. If `x` is complex, then `variancef(x,fre,..) = variancef(real(x),fre,..) + variancef(imag(x),fre,..)` is returned.

`s = variancef(x,fre)` (or `s=variancef(x,fre,"*")`) returns the scalar variance computed over all values of `x`.

`s = variancef(x,fre,"r")`(or equivalently `s = variancef(x,fre,1)`) returns a row `s` such that for each j, `s(j) = variancef(x(:,j),fre(:,j),..)`.

`s = variancef(x,fre,"c")`(or equivalently `s = variancef(x,fre,2)`) returns a column `s` such that for each i, `s(i) = variancef(x(i,:),fre(i,:),..)`.

When the mean `m` is provided, it is used as reference in the variance computation instead of being internally estimated from `x` (unless it is equal to the special value `%nan`: See `m`'s description). This allows to compute the variance of a sample `x` with respect to a given statistical model (rather than extracting an empirical statistical dispersion in order to build the model).

## Examples

    x = [0.2113249 0.0002211 0.6653811; 0.7560439 0.9546254 0.6283918]
    fre = [1 2 3; 3 4 3]
    [s, m] = variancef(x, fre)
    [s, m] = variancef(x, fre, "r")
    [s, m] = variancef(x, fre, "c")

    // Example #2:
    x0 = grand(20, 7, "uin", -9, 10)+0.4
    x = matrix((-9:10)+0.4, 5, 4)
    fre = members(x, x0)        // Computes the frequencies of x's elements in x0
    [s, m] = variancef(x, fre)  // Should be equal to variance(x0)
    [s, m] = variance(x0)

    // Example #2 (follow-up):
    m = (-9+10)/2+0.4               // Known asymptotic mean (if x0 had an infinite number of elements)
    s = variancef(x, fre, "*", m)   // Sample variance wrt the true mean
    s0 = (10 - (-9))^2 /12            // Known asymptotic variance
    s2 = variancef(x, fre, "*", %nan) // Takes m = meanf(x,fre) =>  always <= s

## See Also

- variance
- mtlb_var
- stdevf

## Bibliography

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

## History

5.5.0

- variancef(complexes,..) fixed.

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

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

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