* Bug #7858 fixed - Statistics: variance and variancef
[scilab.git] / scilab / modules / statistics / help / fr_FR / descriptive_statistics / variancef.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
5  * Copyright (C) 2013 - Samuel Gougeon
6  * Copyright (C) 2000 - INRIA - Carlos Klimann
7  *
8  * This file must be used under the terms of the CeCILL.
9  * This source file is licensed as described in the file COPYING, which
10  * you should have received as part of this distribution.  The terms
11  * are also available at
12  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
13  *
14  -->
15 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="fr" xml:id="variancef">
16     <refnamediv>
17         <refname>variancef</refname>
18         <refpurpose>variance (et moyenne) d'un vecteur ou d'une matrice réelle ou complexe de nombres pondérés en fréquence</refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Séquence d'appel</title>
22         <synopsis>
23             [s [,mc]] = variancef(x, fre [,orien [,m]])
24             
25             [s, mc] = variancef(x)
26             [s, mc] = variancef(x, fre, "r"|1 )
27             [s, mc] = variancef(x, fre, "c"|2 )
28             [s, mc] = variancef(x, fre, "*"  , %nan)
29             [s, mc] = variancef(x, fre, "r"|1, %nan)
30             [s, mc] = variancef(x, fre, "c"|2, %nan)
31             s = variancef(x, fre, "*", m)
32             s = variancef(x, fre, "r", m)
33             s = variancef(x, fre, "c", m)
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection>
37         <title>Paramètres</title>
38         <variablelist>
39             <varlistentry>
40                 <term>x</term>
41                 <listitem>
42                     <para>
43                         vecteur ou matrice réel(le) ou complexe
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>fre</term>
49                 <listitem>
50                     <para>
51                         vecteur ou matrice d'entiers positifs = fréquences: <code>fre(i,j)</code> est le nombre de fois que <code>x(i,j)</code> doit être compté.
52                         <varname>fre</varname> et <varname>x</varname> doivent être de même taille.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>orien</term>
58                 <listitem>
59                     <para>l'orientation du calcul. Les valeurs acceptées sont:
60                         <itemizedlist>
61                             <listitem>1 ou "r" : le résultat est une rangée, après un calcul en colonne.</listitem>
62                             <listitem>2 ou "c" : le résultat est une colonne, après un calcul en ligne.</listitem>
63                             <listitem>
64                                 "*" : calcul tous les éléments de <varname>x</varname> confondus (mode utilisé par défaut); utile si le 3ème paramètre <varname>m</varname> doit par ailleurs être indiqué.
65                             </listitem>
66                         </itemizedlist>
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>m</term>
72                 <listitem>
73                     <para>
74                         Espérance mathématique de la loi de distribution de probabilité sous-jacente (supposée connue).
75                         <itemizedlist>
76                             <listitem>
77                                 "*" mode (par défaut): <varname>m</varname> doit être scalaire
78                             </listitem>
79                             <listitem>
80                                 mode "r" or 1 : <varname>m</varname> un vecteur ligne à <literal>size(x,2)</literal> éléments. La variance des éléments de la colonne #j de <varname>x</varname> est calculée en utilisant <literal>m(j)</literal> comme moyenne pour la colonne. Si <varname>m</varname> est la même pour toutes les colonnes, sa valeur scalaire peut être fournie au lieu d'une ligne.
81                             </listitem>
82                             <listitem>
83                                 mode "c" ou 2 : <varname>m</varname> un vecteur colonne à <literal>size(x,1)</literal> éléments. La variance des éléments de la ligne #i de <varname>x</varname> est calculée en utilisant <literal>m(i)</literal> comme moyenne pour la ligne. Si <varname>m</varname> est la même pour toutes les lignes, sa valeur scalaire peut être fournie au lieu d'une colonne.
84                             </listitem>
85                         </itemizedlist>
86                     </para>
87                     <para>
88                         Lorsque <varname>m</varname> n'est pas indiquée, la <literal>variance</literal> est estimée en divisant par (n-1) (non n) la distance quadratique totale des n valeurs à la moyenne calculée <literal>mean(x)</literal>(ou <literal>mean(x,"c")</literal> ou <literal>mean(x,"r")</literal>) (n vaut length(x) ou size(x,1) ou size(x,2)). Si les éléments de <varname>x</varname> sont indépendants entre eux, l'estimation de la variance retournée est non biaisée.
89                     </para>
90                     <para>
91                         Sinon, la <literal>variance</literal> est estimée en divisant par <literal>n</literal> (au lieu de <literal>n-1</literal>) la distance quadratique totale des valeurs <literal>x(k)</literal> à <varname>m</varname> (<literal>n</literal> valant toujours <literal>length(x)</literal> ou <literal>size(x,1)</literal> ou <literal>size(x,2)</literal>). Alors :
92                         <itemizedlist>
93                             <listitem>
94                                 Si une véritable valeur <varname>m</varname> indépendante des éléments de x est fournie, elle est utilisée comme moyenne de référence dans le calcul de la <literal>variance</literal>. La valeur obtenue et retournée pour celle-ci est alors réputée non biaisée.
95                             </listitem>
96                             <listitem>
97                                 Si la valeur spéciale <literal>m=%nan</literal> est fournie, la <literal>variance</literal> est toujours "normalisée" par n (non n-1) mais est estimée en utilisant l'estimation "empirique"
98                                 <literal>m=mean(x)</literal> de la moyenne de référence (ou <literal>m = mean(x,"c")</literal> ou <literal>m = mean(x,"r")</literal>). Comme <varname>m=%nan</varname> n'apporte aucune information nouvelle à "l'équation", celle-ci retourne une estimation biaisée de la variance.
99                             </listitem>
100                         </itemizedlist>
101                     </para>
102                 </listitem>
103             </varlistentry>
104             <varlistentry>
105                 <term>s</term>
106                 <listitem>
107                     Estimation de la variance des valeurs de <varname>x</varname> (pondérées). <varname>s</varname> est un scalaire ou un vecteur ligne ou colonne selon l'option <varname>orien</varname> utilisée.
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>mc</term>
112                 <listitem>
113                     Moyenne pondérée calculée à partir de <varname>x</varname> (<literal>= mean(x,..)</literal>) et utilisée comme référence dans le calcul de la variance. Valeur scalaire ou en vecteur colonne ou ligne, selon l'option <varname>orien</varname> utilisée.
114                 </listitem>
115             </varlistentry>
116         </variablelist>
117     </refsection>
118     <refsection>
119         <title>Description</title>
120         <para>
121             Cette fonction calcule la variance des valeurs d'un vecteur ou une matrice
122             <varname>x</varname>, chacun des <literal>x(i,j)</literal> étant compté <literal>fre(i,j)</literal> fois.
123             If <varname>x</varname> est complexe, alors <literal>variancef(x, fre,..) = variancef(real(x), fre,..) + variancef(imag(x), fre,..)</literal> est retourné.
124         </para>
125         <para>
126             <literal>s = variancef(x,fre)</literal> (ou <literal>s=variancef(x,fre,"*")</literal>) retourne la variance scalaire calculée à partir de toutes les valeurs de <varname>x</varname>.
127         </para>
128         <para>
129             <literal>s = variancef(x,fre,"r")</literal>(ou <literal>s = variancef(x,fre,1)</literal>) retourne un vecteur ligne <varname>s</varname> tel que pour chaque j,
130             <literal>s(j) = variancef(x(:,j),fre(:,j),..)</literal>.
131         </para>
132         <para>
133             <literal>s = variancef(x,fre,"c")</literal>(ou <literal>s = variancef(x,fre,2)</literal>) retourne un vecteur colonne <varname>s</varname> tel que pour chaque i,
134             <literal>s(i) = variancef(x(i,:),fre(i,:),..)</literal>.
135         </para>
136         <para>
137             Quand la moyenne <varname>m</varname> 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 <varname>x</varname> (à moins qu'elle ne soit égale à <code>%nan</code> : Voir la description de <varname>m</varname>). Ceci permet de calculer la variance d'un échantillon <varname>x</varname> en regard d'un modèle statistique donné (plutôt que d'extraire une dispersion empirique pour construire le modèle).
138         </para>
139     </refsection>
140     <refsection>
141         <title>Exemples</title>
142         <programlisting role="example"><![CDATA[
143 x = [0.2113249 0.0002211 0.6653811; 0.7560439 0.9546254 0.6283918]
144 fre = [1 2 3; 3 4 3]
145 [s, m] = variancef(x, fre)
146 [s, m] = variancef(x, fre, "r")
147 [s, m] = variancef(x, fre, "c")
148
149 // Exemple #2:
150 x0 = grand(20, 7, "uin", -9,10)+0.4
151 x = matrix((-9:10)+0.4, 5, 4)
152 fre = members(x, x0)        // Calcule les fréquences des éléments de x dans x0
153 [s, m] = variancef(x, fre)  // Doit être égal à variance(x0)
154 [s, m] = variance(x0)
155
156 // Exemple #2 (suite):
157 m = (-9+10)/2+0.4               // Moyenne asymptotique connue (si x0 avait un nombre infini d'éléments)
158 s = variancef(x, fre, "*", m)   // Variance "échantillon" en regard de la vraie moyenne
159 s0 = (10 - (-9))^2 /12          // Variance asymptotique connue
160 s2 = variancef(x, fre, "*", %nan)
161  ]]></programlisting>
162     </refsection>
163     <refsection role="see also">
164         <title>Voir aussi</title>
165         <simplelist type="inline">
166             <member>
167                 <link linkend="variance">variance</link>
168             </member>
169             <member>
170                 <link linkend="mtlb_var">mtlb_var</link>
171             </member>
172             <member>
173                 <link linkend="stdevf">stdevf</link>
174             </member>
175         </simplelist>
176     </refsection>
177     <refsection>
178         <title>Bibliographie</title>
179         <para>
180             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
181         </para>
182     </refsection>
183     <refsection>
184         <title>Historique</title>
185         <revhistory>
186             <revision>
187                 <revnumber>5.5.0</revnumber>
188                 <revdescription>
189                     <itemizedlist>
190                         <listitem>
191                             <para>variancef() peut être appelée avec des nombres complexes.</para>
192                         </listitem>
193                         <listitem>
194                             <para>variancef(x, fre, orien, m) introduit: la vraie moyenne m de la loi de distribution de probabilité sous-jacente peut être utilisée.</para>
195                         </listitem>
196                         <listitem>
197                             <para>variancef(x, fre, orien, %nan) introduit: mean(x, fre,..) est utilisé mais divisé par n valeurs (à la place de n-1)</para>
198                         </listitem>
199                         <listitem>
200                             <para>[s, mc] = variancef(x,fre,..) introduit : la moyenne mc évaluée à partir de x et fre est maintenant retournée</para>
201                         </listitem>
202                     </itemizedlist>
203                 </revdescription>
204             </revision>
205         </revhistory>
206     </refsection>
207 </refentry>