* Bug #7858 fixed - Statistics: variance and variancef
[scilab.git] / scilab / modules / statistics / help / fr_FR / descriptive_statistics / variance.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 - Samuel GOUGEON
5  * Copyright (C) 2000 - INRIA - Carlos Klimann
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <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="variance">
15     <refnamediv>
16         <refname>variance</refname>
17         <refpurpose>variance d'un vecteur, matrice (voire hypermatrice) de nombres réels ou complexes</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Séquence d'appel</title>
21         <synopsis>
22             [s, [mc]] = variance(x [,orien [,m]])
23             
24             [s, mc] = variance(x)
25             [s, mc] = variance(x, "r"|1 )
26             [s, mc] = variance(x, "c"|2 )
27             [s, mc] = variance(x, "*"  , %nan)
28             [s, mc] = variance(x, "r"|1, %nan)
29             [s, mc] = variance(x, "c"|2, %nan)
30             s = variance(x, "*", m)
31             s = variance(x, "r", m)
32             s = variance(x, "c", m)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Paramètres</title>
37         <variablelist>
38             <varlistentry>
39                 <term>x</term>
40                 <listitem>
41                     <para>
42                         vecteur ou matrice de nombres réels ou complexes. Une hypermatrice est acceptable uniquement sans les options "r" ou "c" : <literal>variance(x)</literal> or <literal>variance(x,"*",m)</literal>
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>orien</term>
48                 <listitem>
49                     <para>
50                         variance selon les lignes ou les colonnes de <varname>x</varname>. Les valeurs possibles sont
51                         <itemizedlist>
52                             <listitem>
53                                 1 or "r" : calcul par colonne. Le résultat est un vecteur <varname>r</varname>angée (ligne)
54                             </listitem>
55                             <listitem>
56                                 2 or "c" : calcul par ligne. Le résultat est une <varname>c</varname>olonne
57                             </listitem>
58                             <listitem>
59                                 "*" : calcul tous les éléments de <varname>x</varname> confondus (mode utilisé par défaut); requis si le 3ème paramètre <varname>m</varname> doit être utilisé.
60                             </listitem>
61                         </itemizedlist>
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>m</term>
67                 <listitem>
68                     <para>
69                         Espérance mathématique de la loi de distribution de probabilité sous-jacente (supposée connue).
70                         <itemizedlist>
71                             <listitem>
72                                 mode "*" (par défaut) : <varname>m</varname> doit être scalaire
73                             </listitem>
74                             <listitem>
75                                 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.
76                             </listitem>
77                             <listitem>
78                                 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.
79                             </listitem>
80                         </itemizedlist>
81                     </para>
82                     <para>
83                         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.
84                     </para>
85                     <para>
86                         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 :
87                         <itemizedlist>
88                             <listitem>
89                                 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 variance. La valeur obtenue et retournée pour celle-ci est alors réputée non biaisée.
90                             </listitem>
91                             <listitem>
92                                 Si la valeur spéciale <literal>m=%nan</literal> est fournie, la variance est toujours "normalisée" par n (non n-1) mais est estimée en utilisant l'estimation "empirique"
93                                 <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.
94                             </listitem>
95                         </itemizedlist>
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>s</term>
101                 <listitem>
102                     Estimation de la variance des valeurs de <varname>x</varname> (non pondérées). <varname>s</varname> est un scalaire ou un vecteur ligne ou colonne selon l'option <varname>orien</varname> utilisée.
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>mc</term>
107                 <listitem>
108                     Moyenne 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.
109                 </listitem>
110             </varlistentry>
111         </variablelist>
112     </refsection>
113     <refsection>
114         <title>Description</title>
115         <para>
116             Cette fonction calcule la variance d'un ensemble de nombres réels ou complexes d'un vecteur, d'une matrice (voire d'une hypermatrice) <literal>x</literal>. Pour <literal>x</literal> à valeurs complexes, <literal>variance(x,..) = variance(real(x),..) + variance(imag(x),..)</literal> est retournée.
117         </para>
118         <para>
119             Pour un vecteur, une matrice ou une hypermatrice <varname>x</varname>, <literal>s = variance(x)</literal> ou <literal>s = variance(x, "*")</literal>
120             retourne  dans le scalaire <varname>s</varname> la variance de tous les éléments de <varname>x</varname>.
121         </para>
122         <para>
123             <literal>s = variance(x,"c")</literal> (ou indifféremment <literal>s = variance(x, 2)</literal>) calcule la variance de chaque ligne.
124             Le vecteur colonne <varname>s</varname> est retourné, avec <literal>s(j) = variance(x(j,:),..)</literal>.
125         </para>
126         <para>
127             <literal>s = variance(x,"r")</literal> (ou indifféremment <literal>s = variance(x,1)</literal>) calcule la variance de chaque colonne.
128             Le vecteur ligne <varname>s</varname> est retourné, avec <literal>s(i) = variance(x(:,i),..)</literal>.
129         </para>
130         <para>
131             <warning>
132                 La syntaxe <literal>variance(x, "*"|"c"|"r", 1)</literal> utilisable uniquement en Scilab 5.4.1 doit être remplacée par
133                 <literal>variance(x,"*"|"c"|"r", %nan)</literal>. <literal>variance(x, "*"|"c"|"r", 1)</literal> émettra une alerte
134                 jusqu'en Scilab 6.0. En effet, <literal>1</literal> est désormais compris comme <literal>m=1</literal>.
135                 Si <literal>1</literal> est la valeur de l'espérance <varname>m</varname>à fournir, l'alerte peut être évitée
136                 en indiquant<literal>1+%eps</literal> au lieu de <literal>1</literal>.
137             </warning>
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.4453586 0.6283918 ]
144 s = variance(x)
145 s = variance(x, "r")
146 s = variance(x, "c")
147
148 // La loi de distribution de probabilité sous-jacente et son espérance (moyenne) sont connues :
149 x = grand(100,5,"unf",0,7);       // Distribution uniforme sur [0, 7]
150 // => espérance = (0+7)/2 = 3.5  et variance = (7-0)^2/12
151 (7-0)^2/12                              // Variance asymptotique vraie
152 s = variance(x)             // Estimation non biaisée (division par n-1).
153 s = variance(x, "*", 3.5)   // Estimation non biaisée (division par n). Toujours >= variance(x)
154 s = variance(x, "*", %nan)      // Estimation biaisée     (division par n). Toujours <= variance(x)
155 // A travers les colonnes (le long des lignes) => résultat en colonne :
156 s = variance(x, "c")
157 s = variance(x, "c", 3.5)
158 s = variance(x, "c", %nan)
159
160 // Nombres complexes uniformément distribués sur [0,1] + [0,1].i :
161 x = rand(4, 3) + rand(4, 3)*%i
162 s = variance(x)
163 s = variance(x, "*", 0.5 + 0.5*%i)
164 s = variance(x, "*", %nan)
165 s = variance(x, "r")
166 s = variance(x, "c")
167
168 // Nombres fournis en hypermatrice :
169 x = rand(3, 2, 2)       // Distribution uniforme sur [0, 1]
170 s = variance(x)
171 s = variance(x, "*", 0.5)
172 s = variance(x, "*", %nan)
173 // s = variance(x, "r")  //  Utilisation non admise pour une hypermatrice
174 // s = variance(x, "c")  //  Utilisation non admise pour une hypermatrice
175  ]]></programlisting>
176     </refsection>
177     <refsection role="see also">
178         <title>Voir aussi</title>
179         <simplelist type="inline">
180             <member>
181                 <link linkend="variancef">variancef</link>
182             </member>
183             <member>
184                 <link linkend="mtlb_var">mtlb_var</link>
185             </member>
186             <member>
187                 <link linkend="stdev">stdev</link>
188             </member>
189         </simplelist>
190     </refsection>
191     <refsection>
192         <title>Bibliographie</title>
193         <para>
194             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
195         </para>
196     </refsection>
197     <refsection>
198         <title>Historique</title>
199         <revhistory>
200             <revision>
201                 <revnumber>5.5.0</revnumber>
202                 <revdescription>
203                     <itemizedlist>
204                         <listitem>
205                             <para>variance(x, orien, 0|1) supprimée (utilisable uniquement avec Scilab 5.4.1)</para>
206                         </listitem>
207                         <listitem>
208                             <para>variance(x, orien, m) introduite : l'espérance mathématique m connue de la distribution de probabilité sous-jacente peut être spécifiée et utilisée</para>
209                         </listitem>
210                         <listitem>
211                             <para>variance(x, orien, %nan) introduite : mean(x,..) est utilisée, mais la distance quadratique totale est divisée par la taille n de l'échantillon (au lieu de n-1)</para>
212                         </listitem>
213                         <listitem>
214                             <para>[s, mc] = variance(x,..) introduite : la moyenne mc calculée sur l'échantillon x peut être obtenue en second résultat</para>
215                         </listitem>
216                     </itemizedlist>
217                 </revdescription>
218             </revision>
219             <revision>
220                 <revnumber>5.4.1</revnumber>
221                 <revdescription>
222                     <itemizedlist>
223                         <listitem>
224                             <para>variance(complexes) corrigée. variance(x, "*", 1) introduite. Vectorisation du calcul pour variance(x, "r"|"c"). Révision complète de la page d'aide</para>
225                         </listitem>
226                     </itemizedlist>
227                 </revdescription>
228             </revision>
229         </revhistory>
230     </refsection>
231 </refentry>