[doc] misc. fix & improvements
[scilab.git] / scilab / modules / statistics / help / en_US / 3_dispersion_widths / 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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <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="en" xml:id="variance">
18     <refnamediv>
19         <refname>variance</refname>
20         <refpurpose>variance (and mean) of a vector or matrix (or hypermatrix) of real or complex numbers</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             [s [,mc]] = variance(x [,orien [,m]])
26
27             [s, mc] = variance(x)
28             [s, mc] = variance(x, "r"|1 )
29             [s, mc] = variance(x, "c"|2 )
30             [s, mc] = variance(x, "*"  , %nan)
31             [s, mc] = variance(x, "r"|1, %nan)
32             [s, mc] = variance(x, "c"|2, %nan)
33             s = variance(x, "*", m)
34             s = variance(x, "r"|1, m)
35             s = variance(x, "c"|2, m)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>x</term>
43                 <listitem>
44                     <para>
45                         real or complex vector or matrix. A hypermatrix is accepted only for undirectional computations <literal>variance(x)</literal> or <literal>variance(x,"*",m)</literal>
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>orien</term>
51                 <listitem>
52                     <para>the orientation of the computation. Valid values are
53                         <itemizedlist>
54                             <listitem>1 or "r": result is a row, after a column-wise computation.</listitem>
55                             <listitem>2 or "c": result is a column, after a row-wise computation.</listitem>
56                             <listitem>
57                                 "*": full undirectional computation (default); explicitly required when <varname>m</varname> is used.
58                             </listitem>
59                         </itemizedlist>
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>m</term>
65                 <listitem>
66                     <para>
67                         The known mean of the underlying statistical distribution law (assuming that it is known).
68                         <itemizedlist>
69                             <listitem>
70                                 "*" mode (default): <varname>m</varname> must be scalar
71                             </listitem>
72                             <listitem>
73                                 "r" or 1 mode: <varname>m</varname> is a row of length <literal>size(x,2)</literal>. The variance along the column #j is computed using <literal>m(j)</literal> as the mean for the considered column. If <literal>m(j)</literal> is the same for all columns, it can be provided as a scalar <varname>m</varname>.
74                             </listitem>
75                             <listitem>
76                                 "c" or 2 mode: <varname>m</varname> is a column of length <literal>size(x,1)</literal>. The variance along the row #i is computed using <literal>m(i)</literal> as the mean for the considered row. If <literal>m(i)</literal> is the same for all rows, it can be provided as a scalar <varname>m</varname>.
77                             </listitem>
78                         </itemizedlist>
79                     </para>
80                     <para>
81                         When <varname>m</varname> is not provided, the <literal>variance</literal> is built dividing the quadratic distance of <literal>n</literal> values to <literal>mean(x)</literal> (or <literal>mean(x,"c")</literal> or <literal>mean(x,"r")</literal>) by <literal>n-1</literal> (<literal>n</literal> being <literal>length(x)</literal> or <literal>size(x,1)</literal> or <literal>size(x,2)</literal>). If the elements of <varname>x</varname> are mutually independent, the result is then statistically unbiased.
82                     </para>
83                     <para>
84                         Else, the <literal>variance</literal> is built dividing the quadratic distance of values to <varname>m</varname> by the number n of considered values (n being length(x) or size(x,1) or size(x,2)).
85                     </para>
86                     <para>
87                         If a true value <varname>m</varname> independent from x elements is used, <varname>x</varname> and <varname>m</varname> values are mutually independent, and the result is then unbiased.
88                     </para>
89                     <para>
90                         When the special value <literal>m = %nan</literal> is provided, the variance is still normalized by n (not n-1) but is computed using
91                         <literal>m=mean(x)</literal> instead (or <literal>m = mean(x,"c")</literal> or <literal>m = mean(x,"r")</literal>). This <varname>m</varname> does not bring independent information, and yields a statistically biased result.
92                     </para>
93                 </listitem>
94             </varlistentry>
95             <varlistentry>
96                 <term>s</term>
97                 <listitem>
98                     The variance of unweighted values of <varname>x</varname> elements. It is a scalar or a column vector or a row vector according to <varname>orien</varname>.
99                 </listitem>
100             </varlistentry>
101             <varlistentry>
102                 <term>mc</term>
103                 <listitem>
104                     Scalar or <varname>orien</varname>-wise mean of <varname>x</varname> elements (unweighted) (<literal>= mean(x,..)</literal>), as computed before and used as reference in the variance.
105                 </listitem>
106             </varlistentry>
107         </variablelist>
108     </refsection>
109     <refsection>
110         <title>Description</title>
111         <para>
112             This function computes the variance of the real or complex numbers stored into a vector or matrix <varname>x</varname>. If <varname>x</varname> is complex, <literal>variance(x,..) = variance(real(x),..) + variance(imag(x),..)</literal> is returned.
113         </para>
114         <para>
115             For a vector, a matrix, or a hypermatrix <varname>x</varname>, <code>s = variance(x)</code>
116             returns in the scalar <varname>s</varname> the variance of all the entries of <varname>x</varname>.
117         </para>
118         <para>
119             <code>s = variance(x,"c")</code> (or,  equivalently, <code>s = variance(x,2)</code>)
120             is the columnwise variance: <varname>s</varname> is a column vector, with <code>s(j) = variance(x(j,:))</code>.
121         </para>
122         <para>
123             <code>s = variance(x,"r")</code> (or,  equivalently, <code>s = variance(x,1)</code>)
124             is the rowwise variance: <varname>s</varname> is a row vector, with <code>s(i) = variance(x(:,i))</code>.
125         </para>
126         <para>
127             The second output argument <varname>m</varname> is the mean of the input, with respect to the <varname>orien</varname> parameter.
128         </para>
129         <para>
130             <warning>
131                 The <literal>variance(x, "*"|"c"|"r", 1)</literal> synopsis used only in Scilab 5.4.1 must be replaced with
132                 <literal>variance(x, "*"|"c"|"r", %nan)</literal>. <literal>variance(x, "*"|"c"|"r", 1)</literal> will warn
133                 the user until Scilab 6.0. Indeed, <literal>1</literal> will be now considered as <literal>m=1</literal>.
134                 If <literal>1</literal> is the true value provided as <varname>m</varname>, the warning may be avoided entering <literal>1+%eps</literal> instead
135                 of <literal>1</literal>.
136             </warning>
137         </para>
138     </refsection>
139     <refsection>
140         <title>Examples</title>
141         <programlisting role="example"><![CDATA[
142 x = [ 0.2113249 0.0002211 0.6653811; 0.7560439 0.4453586 0.6283918 ]
143 s = variance(x)
144 s = variance(x, "r")
145 s = variance(x, "c")
146
147 // The underlying statistical distribution and its mean are known:
148 x = grand(100, 5, "unf", 0, 7);      // Uniform distribution on [0, 7]
149 // => the true asymptotic mean is (0+7)/2 = 3.5 and variance = (7-0)^2/12
150 (7-0)^2/12                  // True asymptotic variance
151 s = variance(x)             // Unbiased (division by n-1).
152 s = variance(x, "*", 3.5)   // Unbiased (division by n). Always >= variance(x)
153 s = variance(x, "*", %nan)    // Biased   (division by n). Always <= variance(x)
154 // Across columns:
155 s = variance(x, "c")
156 s = variance(x, "c", 3.5)
157 s = variance(x, "c", %nan)
158
159 // With complex numbers uniformly distributed on [0,1] + [0,1].i:
160 x = rand(4, 3) + rand(4, 3)*%i
161 s = variance(x)
162 s = variance(x, "*", 0.5 + 0.5*%i)
163 s = variance(x, "*", %nan)
164 s = variance(x, "r")
165 s = variance(x, "c")
166
167 // With a hypermatrix
168 x = rand(3, 2, 2)    // Uniform distribution on [0, 1]
169 s = variance(x)
170 s = variance(x, "*", 0.5)
171 s = variance(x, "*", %nan)
172 // s = variance(x, "r")  // Is not supported for a hypermatrix
173 // s = variance(x, "c")  // Is not supported for a hypermatrix
174  ]]></programlisting>
175     </refsection>
176     <refsection role="see also">
177         <title>See also</title>
178         <simplelist type="inline">
179             <member>
180                 <link linkend="variancef">variancef</link>
181             </member>
182             <member>
183                 <link linkend="mtlb_var">mtlb_var</link>
184             </member>
185             <member>
186                 <link linkend="stdev">stdev</link>
187             </member>
188         </simplelist>
189     </refsection>
190     <refsection>
191         <title>Bibliography</title>
192         <para>
193             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
194         </para>
195     </refsection>
196     <refsection>
197         <title>History</title>
198         <revhistory>
199             <revision>
200                 <revnumber>5.5.0</revnumber>
201                 <revdescription>
202                     <itemizedlist>
203                         <listitem>
204                             <para>variance(x, orien, 0|1) removed (as introduced in Scilab 5.4.1)</para>
205                         </listitem>
206                         <listitem>
207                             <para>variance(x, orien, m) introduced: the true mean m of the underlying statistical law can be used.</para>
208                         </listitem>
209                         <listitem>
210                             <para>variance(x, orien, %nan) introduced: mean(x,..) is used but divided by n values (instead of n-1)</para>
211                         </listitem>
212                         <listitem>
213                             <para>[s, mc] = variance(x,..) introduced: the mean mc computed from x is now also returned</para>
214                         </listitem>
215                     </itemizedlist>
216                 </revdescription>
217             </revision>
218             <revision>
219                 <revnumber>5.4.1</revnumber>
220                 <revdescription>
221                     <itemizedlist>
222                         <listitem>
223                             <para>variance(complexes) fixed. variance(x,"*",1) introduced. Vectorization of the code for directional usages variance(x,"r"|"c"). Full revision of the help page</para>
224                         </listitem>
225                     </itemizedlist>
226                 </revdescription>
227             </revision>
228         </revhistory>
229     </refsection>
230 </refentry>