# variancef

variance (et moyenne) d'un vecteur ou d'une matrice réelle ou complexe de nombres pondérés en fréquence

## Séquence d'appel

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

## Paramètres

x

  vecteur ou matrice réel(le) ou complexe

fre

  vecteur ou matrice d'entiers positifs = fréquences: `fre(i,j)` est le nombre de fois que `x(i,j)` doit être compté. `fre` et `x` doivent être de même taille.

orien

  l'orientation du calcul. Les valeurs acceptées sont:

  - 1 ou "r" : le résultat est une rangée, après un calcul en colonne.
  - 2 ou "c" : le résultat est une colonne, après un calcul en ligne.
  - "*" : calcul tous les éléments de `x` confondus (mode utilisé par défaut); utile si le 3ème paramètre `m` doit par ailleurs être indiqué.
m

  Espérance mathématique de la loi de distribution de probabilité sous-jacente (supposée connue).

  - "*" mode (par défaut): `m` doit être scalaire
  - mode "r" or 1 : `m` un vecteur ligne à `size(x,2)` éléments. La variance des éléments de la colonne #j de `x` est calculée en utilisant `m(j)` comme moyenne pour la colonne. Si `m` est la même pour toutes les colonnes, sa valeur scalaire peut être fournie au lieu d'une ligne.
  - mode "c" ou 2 : `m` un vecteur colonne à `size(x,1)` éléments. La variance des éléments de la ligne #i de `x` est calculée en utilisant `m(i)` comme moyenne pour la ligne. Si `m` est la même pour toutes les lignes, sa valeur scalaire peut être fournie au lieu d'une colonne.

  Lorsque `m` n'est pas indiquée, la `variance` est estimée en divisant par (n-1) (non n) la distance quadratique totale des n valeurs à la moyenne calculée `mean(x)`(ou `mean(x,"c")` ou `mean(x,"r")`) (n vaut length(x) ou size(x,1) ou size(x,2)). Si les éléments de `x` sont indépendants entre eux, l'estimation de la variance retournée est non biaisée.

  Sinon, la `variance` est estimée en divisant par `n` (au lieu de `n-1`) la distance quadratique totale des valeurs `x(k)` à `m` (`n` valant toujours `length(x)` ou `size(x,1)` ou `size(x,2)`). Alors :

  - Si une véritable valeur `m` indépendante des éléments de x est fournie, elle est utilisée comme moyenne de référence dans le calcul de la `variance`. La valeur obtenue et retournée pour celle-ci est alors réputée non biaisée.
  - Si la valeur spéciale `m=%nan` est fournie, la `variance` est toujours "normalisée" par n (non n-1) mais est estimée en utilisant l'estimation "empirique" `m=mean(x)` de la moyenne de référence (ou `m = mean(x,"c")` ou `m = mean(x,"r")`). Comme `m=%nan` n'apporte aucune information nouvelle à "l'équation", celle-ci retourne une estimation biaisée de la variance.
s
  Estimation de la variance des valeurs de `x` (pondérées). `s` est un scalaire ou un vecteur ligne ou colonne selon l'option `orien` utilisée.
mc
  Moyenne pondérée calculée à partir de `x` (`= mean(x,..)`) et utilisée comme référence dans le calcul de la variance. Valeur scalaire ou en vecteur colonne ou ligne, selon l'option `orien` utilisée.

## Description

Cette fonction calcule la variance des valeurs d'un vecteur ou une matrice `x`, chacun des `x(i,j)` étant compté `fre(i,j)` fois. If `x` est complexe, alors `variancef(x, fre,..) = variancef(real(x), fre,..) + variancef(imag(x), fre,..)` est retourné.

`s = variancef(x,fre)` (ou `s=variancef(x,fre,"*")`) retourne la variance scalaire calculée à partir de toutes les valeurs de `x`.

`s = variancef(x,fre,"r")`(ou `s = variancef(x,fre,1)`) retourne un vecteur ligne `s` tel que pour chaque j, `s(j) = variancef(x(:,j),fre(:,j),..)`.

`s = variancef(x,fre,"c")`(ou `s = variancef(x,fre,2)`) retourne un vecteur colonne `s` tel que pour chaque i, `s(i) = variancef(x(i,:),fre(i,:),..)`.

Quand la moyenne `m` est fournie, elle est utilisée comme référence dans le calcul de la variance au lieu d'être évaluée intérieurement à partir de `x` (à moins qu'elle ne soit égale à `%nan` : Voir la description de `m`). Ceci permet de calculer la variance d'un échantillon `x` en regard d'un modèle statistique donné (plutôt que d'extraire une dispersion empirique pour construire le modèle).

## Exemples

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

    // Exemple #2:
    x0 = grand(20, 7, "uin", -9,10)+0.4
    x = matrix((-9:10)+0.4, 5, 4)
    fre = members(x, x0)        // Calcule les fréquences des éléments de x dans x0
    [s, m] = variancef(x, fre)  // Doit être égal à variance(x0)
    [s, m] = variance(x0)

    // Exemple #2 (suite):
    m = (-9+10)/2+0.4               // Moyenne asymptotique connue (si x0 avait un nombre infini d'éléments)
    s = variancef(x, fre, "*", m)   // Variance "échantillon" en regard de la vraie moyenne
    s0 = (10 - (-9))^2 /12          // Variance asymptotique connue
    s2 = variancef(x, fre, "*", %nan)

## Voir aussi

- variance
- mtlb_var
- stdevf

## Bibliographie

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

## Historique

5.5.0

- variancef() peut être appelée avec des nombres complexes.

- variancef(x, fre, orien, m) introduit: la vraie moyenne m de la loi de distribution de probabilité sous-jacente peut être utilisée.

- variancef(x, fre, orien, %nan) introduit: mean(x, fre,..) est utilisé mais divisé par n valeurs (à la place de n-1)

- [s, mc] = variancef(x,fre,..) introduit : la moyenne mc évaluée à partir de x et fre est maintenant retournée