* Bug #7858 fixed - variance and variancef can now return mean
[scilab.git] / scilab / modules / statistics / help / en_US / 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) 2000 - INRIA - Carlos Klimann
5  * Copyright (C) 2013 - Samuel GOUGEON
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="en" xml:id="variance">
15     <refnamediv>
16         <refname>variance</refname>
17         <refpurpose>variance and mean of the values of a vector or matrix (or hypermatrix) real or complex</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>s = variance(x [,orien [,w]])
22             [s,m] = variance(x,'r') or s = variance(x,1)
23             [s,m] = variance(x,'c') or s = variance(x,2)
24             [s,m] = variance(x,'*',1)
25             [s,m] = variance(x,'r',1)
26             [s,m] = variance(x,'c',1)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>x</term>
34                 <listitem>
35                     <para>
36                         real or complex vector or matrix. An hypermatrix is accepted only for undirectional computations <literal>variance(x)</literal> or <literal>variance(x,"*",1)</literal>
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>orien</term>
42                 <listitem>
43                     <para>the orientation of the computation. Valid values are
44                         <itemizedlist>
45                             <listitem>1 or "r" : result is a row, after a column-wise computation.</listitem>
46                             <listitem>2 or "c" : result is a column, after a row-wise computation.</listitem>
47                             <listitem>
48                                 "*" : full undirectional computation (default); useful explicitly when <literal>w</literal> is used.
49                             </listitem>
50                         </itemizedlist>
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>w</term>
56                 <listitem>
57                     <para>w : type of normalization to use. Valid values are 
58                         <itemizedlist>
59                             <listitem>0 : provides the best unbiased estimator of the variance when the mean is not known a priori. This is the default.
60                                 The sum is normalized by 1/(nE-1), where nE is the number of summed elements 
61                                 (the number of rows nR if "r" is used; of columns nC if "c" is used; or by default nC*nR)
62                             </listitem>
63                             <listitem>1 : provides the second moment around the mean. The sum is normalized by 1/nE.
64                                 This estimation is unbiased only if the mean is known a priori.
65                             </listitem>
66                         </itemizedlist>
67                     </para>
68                 </listitem>
69             </varlistentry>
70         </variablelist>
71     </refsection>
72     <refsection>
73         <title>Description</title>
74         <para>
75             This function computes the variance of the real or complex numbers stored into a vector or matrix <literal>x</literal>. If <literal>x</literal> is complex, <literal>variance(x,..) = variance(real(x),..) + variance(imag(x),..)</literal> is returned.
76         </para>
77         <para>
78             For a vector, a matrix, or an hypermatrix <literal>x</literal>, <literal>s = variance(x)</literal> or <literal>s = variance(x, "*", 1)</literal>
79             returns in the scalar <literal>s</literal> the variance of all the entries of <literal>x</literal>.
80         </para>
81         <para>
82             <literal>s = variance(x,'c')</literal> (or,  equivalently, <literal>s = variance(x,2)</literal>)
83             is the columnwise variance: s is a column vector, with <literal>s(j) = variance(x(j,:))</literal>.
84         </para>
85         <para>
86             <literal>s = variance(x,'r')</literal> (or,  equivalently, <literal>s = variance(x,1)</literal>)
87             is the rowwise variance: s is a row vector, with s(i) the variance of <literal>s(i) = variance(x(:,i))</literal>.
88         </para>
89         <para>
90             The second output argument <literal>m</literal> is the mean of the input, with respect to the <literal>orien</literal> parameter.
91         </para>
92     </refsection>
93     <refsection>
94         <title>Examples</title>
95         <programlisting role="example"><![CDATA[ 
96 x = [ 0.2113249 0.0002211 0.6653811;0.7560439 0.4453586 0.6283918 ]
97 s = variance(x)
98 s = variance(x, "r")
99 s = variance(x, "c")
100
101 // with complex numbers
102 x = rand(4,3) + rand(4,3)*%i
103 s = variance(x)
104 s = variance(x, "*", 1) // should be smaller than the previous one
105 s = variance(x, "r")
106 s = variance(x, "r", 1)
107 s = variance(x, "c")
108
109 // with an hypermatrix
110 x = rand(3,2,2)
111 s = variance(x)
112 s = variance(x, "*", 1) // should be smaller than the previous one
113 // s = variance(x, "r")  // is not supported for an hypermatrix
114 // s = variance(x, "c")  // is not supported for an hypermatrix
115  ]]></programlisting>
116     </refsection>
117     <refsection role="see also">
118         <title>See Also</title>
119         <simplelist type="inline">
120             <member>
121                 <link linkend="variancef">variancef</link>
122             </member>
123             <member>
124                 <link linkend="mtlb_var">mtlb_var</link>
125             </member>
126         </simplelist>
127     </refsection>
128     <refsection>
129         <title>Bibliography</title>
130         <para>
131             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
132         </para>
133     </refsection>
134     <refsection>
135         <title>History</title>
136         <revhistory>
137             <revision>
138                 <revnumber>5.4.1</revnumber>
139                 <revdescription>variance(complexes) fixed. variance(x,"*",1) introduced. Vectorization of the code for directional usages variance(x,"r"|"c"). Full revision of the help page
140                 </revdescription>
141             </revision>
142         </revhistory>
143     </refsection>
144 </refentry>