[doc] misc. fix & improvements
[scilab.git] / scilab / modules / statistics / help / en_US / 3_dispersion_widths / 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 - 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="variancef">
18     <refnamediv>
19         <refname>variancef</refname>
20         <refpurpose>variance (and mean) of a vector or matrix of frequency-weighted real or complex numbers</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             [s [,mc]] = variancef(x, fre [,orien [,m]])
26
27             [s, mc] = variancef(x)
28             [s, mc] = variancef(x, fre, "r"|1 )
29             [s, mc] = variancef(x, fre, "c"|2 )
30             [s, mc] = variancef(x, fre, "*"  , %nan)
31             [s, mc] = variancef(x, fre, "r"|1, %nan)
32             [s, mc] = variancef(x, fre, "c"|2, %nan)
33             s = variancef(x, fre, "*", m)
34             s = variancef(x, fre, "r", m)
35             s = variancef(x, fre, "c", m)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>x</term>
43                 <listitem>
44                     <para>
45                         vector or matrix of real or complex numbers
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>fre</term>
51                 <listitem>
52                     <para>
53                         vector or matrix of positive decimal integers = frequencies: <code>fre(i,j)</code> is the number of times that <code>x(i,j)</code> must be counted.
54                         <varname>fre</varname> and <varname>x</varname> have same sizes.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>orien</term>
60                 <listitem>
61                     <para>the orientation of the computation. Valid values are:
62                         <itemizedlist>
63                             <listitem>1 or "r" : result is a row, after a column-wise computation.</listitem>
64                             <listitem>2 or "c" : result is a column, after a row-wise computation.</listitem>
65                             <listitem>
66                                 "*" : full undirectional computation (default); explicitly required when <literal>m</literal> is used.
67                             </listitem>
68                         </itemizedlist>
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>m</term>
74                 <listitem>
75                     <para>
76                         The known mean of the underlying statistical distribution law (assuming that it is known).
77                         <itemizedlist>
78                             <listitem>
79                                 "*" mode (default): <varname>m</varname> must be scalar
80                             </listitem>
81                             <listitem>
82                                 "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>.
83                             </listitem>
84                             <listitem>
85                                 "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>.
86                             </listitem>
87                         </itemizedlist>
88                     </para>
89                     <para>
90                         When <varname>m</varname> is not provided, the <literal>variance</literal> is built dividing the quadratic distance of n values to <literal>mean(x,fre)</literal>(or <literal>mean(x,fre,"c")</literal> or <literal>mean(x,fre,"r")</literal>) by (n-1) (n being sum(fre) or sum(fre,"c") or sum(fre,"r")). If the elements of <varname>x</varname> are mutually independent, the result is then statistically unbiased.
91                     </para>
92                     <para>
93                         Else, the <literal>variance</literal> is built dividing the quadratic distance of values to <varname>m</varname> by the number n of considered values.
94                     </para>
95                     <para>
96                         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.
97                     </para>
98                     <para>
99                         When the special value <literal>m = %nan</literal> is provided, the variance is still normalized by n (not n-1) but is computed using
100                         <literal>m = mean(x, fre)</literal> instead (or <literal>m = mean(x,fre,"c")</literal> or <literal>m = mean(x,fre,"r")</literal>). This <varname>m</varname> does not bring independent information, and yields a statistically biased result.
101                     </para>
102                 </listitem>
103             </varlistentry>
104             <varlistentry>
105                 <term>s</term>
106                 <listitem>
107                     The variance of weighted values of <varname>x</varname> elements. It is a scalar or a column vector or a row vector according to <varname>orien</varname>.
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>mc</term>
112                 <listitem>
113                     Scalar or <varname>orien</varname>-wise mean of weighted <varname>x</varname> elements (<literal>= mean(x, fre,..)</literal>), as computed before and used as reference in the variance.
114                 </listitem>
115             </varlistentry>
116         </variablelist>
117     </refsection>
118     <refsection>
119         <title>Description</title>
120         <para>
121             This function computes the variance of the values of a
122             vector or matrix <varname>x</varname>, each of them <literal>x(i,j)</literal> being counted <literal>fre(i,j)</literal> times.
123             If <literal>x</literal> is complex, then <literal>variancef(x,fre,..) = variancef(real(x),fre,..) + variancef(imag(x),fre,..)</literal> is returned.
124         </para>
125         <para>
126             <literal>s = variancef(x,fre)</literal> (or <literal>s=variancef(x,fre,"*")</literal>) returns the scalar variance computed over all values of <varname>x</varname>.
127         </para>
128         <para>
129             <literal>s = variancef(x,fre,"r")</literal>(or equivalently <literal>s = variancef(x,fre,1)</literal>) returns a row <varname>s</varname> such that for each j,
130             <literal>s(j) = variancef(x(:,j),fre(:,j),..)</literal>.
131         </para>
132         <para>
133             <literal>s = variancef(x,fre,"c")</literal>(or equivalently <literal>s = variancef(x,fre,2)</literal>) returns a column <varname>s</varname> such that for each i,
134             <literal>s(i) = variancef(x(i,:),fre(i,:),..)</literal>.
135         </para>
136         <para>
137             When the mean <varname>m</varname> is provided, it is used as reference in the variance computation instead of being internally estimated from <varname>x</varname> (unless it is equal to the special value <code>%nan</code>: See <varname>m</varname>'s description). This allows to compute the variance of a sample <varname>x</varname> with respect to a given statistical model (rather than extracting an empirical statistical dispersion in order to build the model).
138         </para>
139     </refsection>
140     <refsection>
141         <title>Examples</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 // Example #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)        // Computes the frequencies of x's elements in x0
153 [s, m] = variancef(x, fre)  // Should be equal to variance(x0)
154 [s, m] = variance(x0)
155
156 // Example #2 (follow-up):
157 m = (-9+10)/2+0.4               // Known asymptotic mean (if x0 had an infinite number of elements)
158 s = variancef(x, fre, "*", m)   // Sample variance wrt the true mean
159 s0 = (10 - (-9))^2 /12            // Known asymptotic variance
160 s2 = variancef(x, fre, "*", %nan) // Takes m = meanf(x,fre) =>  always <= s
161  ]]></programlisting>
162     </refsection>
163     <refsection role="see also">
164         <title>See also</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>Bibliography</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>History</title>
185         <revhistory>
186             <revision>
187                 <revnumber>5.5.0</revnumber>
188                 <revdescription>
189                     <itemizedlist>
190                         <listitem>
191                             <para>variancef(complexes,..) fixed.</para>
192                         </listitem>
193                         <listitem>
194                             <para>variancef(x, fre, orien, m) introduced: the true mean m of the underlying statistical law can be used.</para>
195                         </listitem>
196                         <listitem>
197                             <para>variancef(x, fre, orien, %nan) introduced: mean(x, fre,..) is used but divided by n values (instead of n-1)</para>
198                         </listitem>
199                         <listitem>
200                             <para>[s, mc] = variancef(x,fre,..) introduced : the mean mc computed from x and fre is now also returned</para>
201                         </listitem>
202                     </itemizedlist>
203                 </revdescription>
204             </revision>
205         </revhistory>
206     </refsection>
207 </refentry>