* Bug #7858 fixed - Statistics: variance and variancef 76/13176/4
Samuel GOUGEON [Tue, 19 Nov 2013 09:23:38 +0000 (10:23 +0100)]
After commit https://codereview.scilab.org/#/c/13009/ ,
variance and variancef help pages reworked
and fix for variancef.

CHANGES file already modified, in mentioned commit.

Change-Id: I640e1b256514459831d84012c5a8f256b7b459aa

scilab/modules/statistics/help/en_US/descriptive_statistics/variance.xml
scilab/modules/statistics/help/en_US/descriptive_statistics/variancef.xml
scilab/modules/statistics/help/fr_FR/descriptive_statistics/variance.xml
scilab/modules/statistics/help/fr_FR/descriptive_statistics/variancef.xml [new file with mode: 0644]
scilab/modules/statistics/macros/variance.sci
scilab/modules/statistics/macros/variancef.sci
scilab/modules/statistics/tests/nonreg_tests/bug_7858.dia.ref
scilab/modules/statistics/tests/nonreg_tests/bug_7858.tst
scilab/modules/statistics/tests/unit_tests/variancef.dia.ref
scilab/modules/statistics/tests/unit_tests/variancef.tst

index 2260c2b..1b7d66d 100644 (file)
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2000 - INRIA - Carlos Klimann
  * Copyright (C) 2013 - Samuel GOUGEON
+ * Copyright (C) 2000 - INRIA - Carlos Klimann
  *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
 <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">
     <refnamediv>
         <refname>variance</refname>
-        <refpurpose>variance and mean of the values of a vector or matrix (or hypermatrix) real or complex</refpurpose>
+        <refpurpose>variance (and mean) of a vector or matrix (or hypermatrix) of real or complex numbers</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
         <synopsis>
-            s = variance(x [,orien [,m]])
-            [s, m] = variance(x, 'r') or s = variance(x, 1)
-            [s, m] = variance(x, 'c') or s = variance(x, 2)
-            [s, m] = variance(x, '*', m)
-            [s, m] = variance(x, 'r', m)
-            [s, m] = variance(x, 'c', m)
+            [s [,mc]] = variance(x [,orien [,m]])
+            
+            [s, mc] = variance(x)
+            [s, mc] = variance(x, "r"|1 )
+            [s, mc] = variance(x, "c"|2 )
+            [s, mc] = variance(x, "*"  , %nan)
+            [s, mc] = variance(x, "r"|1, %nan)
+            [s, mc] = variance(x, "c"|2, %nan)
+            s = variance(x, "*", m)
+            s = variance(x, "r"|1, m)
+            s = variance(x, "c"|2, m)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
@@ -34,7 +39,7 @@
                 <term>x</term>
                 <listitem>
                     <para>
-                        real or complex vector or matrix. An hypermatrix is accepted only for undirectional computations <literal>variance(x)</literal> or <literal>variance(x,"*",1)</literal>
+                        real or complex vector or matrix. A hypermatrix is accepted only for undirectional computations <literal>variance(x)</literal> or <literal>variance(x,"*",m)</literal>
                     </para>
                 </listitem>
             </varlistentry>
                 <listitem>
                     <para>the orientation of the computation. Valid values are
                         <itemizedlist>
-                            <listitem>1 or "r" : result is a row, after a column-wise computation.</listitem>
-                            <listitem>2 or "c" : result is a column, after a row-wise computation.</listitem>
+                            <listitem>1 or "r": result is a row, after a column-wise computation.</listitem>
+                            <listitem>2 or "c": result is a column, after a row-wise computation.</listitem>
                             <listitem>
-                                "*" : full undirectional computation (default); useful explicitly when <literal>w</literal> is used.
+                                "*": full undirectional computation (default); explicitly required when <varname>m</varname> is used.
                             </listitem>
                         </itemizedlist>
                     </para>
                 <term>m</term>
                 <listitem>
                     <para>
-                        m: the a priori mean. If it is passed to <literal>variance</literal>, then the sum is normalized by
-                        <literal>n</literal>, the function returns the second moment around the mean.
-                        Otherwise, it is normalized by <literal>n-1</literal> and <literal>variance</literal> provides the best unbiased estimator of the variance.
+                        The known mean of the underlying statistical distribution law (assuming that it is known).
+                        <itemizedlist>
+                            <listitem>
+                                "*" mode (default): <varname>m</varname> must be scalar
+                            </listitem>
+                            <listitem>
+                                "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>.
+                            </listitem>
+                            <listitem>
+                                "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>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                    <para>
+                        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)).
+                    </para>
+                    <para>
+                        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.
                     </para>
+                    <para>
+                        When the special value <literal>m = %nan</literal> is provided, the variance is still normalized by n (not n-1) but is computed using
+                        <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.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>s</term>
+                <listitem>
+                    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>.
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mc</term>
+                <listitem>
+                    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.
                 </listitem>
             </varlistentry>
         </variablelist>
     <refsection>
         <title>Description</title>
         <para>
-            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.
+            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.
         </para>
         <para>
-            For a vector, a matrix, or an hypermatrix <literal>x</literal>, <literal>s = variance(x)</literal> or <literal>s = variance(x, "*", 1)</literal>
-            returns in the scalar <literal>s</literal> the variance of all the entries of <literal>x</literal>.
+            For a vector, a matrix, or a hypermatrix <varname>x</varname>, <code>s = variance(x)</code>
+            returns in the scalar <varname>s</varname> the variance of all the entries of <varname>x</varname>.
         </para>
         <para>
-            <literal>s = variance(x,'c')</literal> (or,  equivalently, <literal>s = variance(x,2)</literal>)
-            is the columnwise variance: s is a column vector, with <literal>s(j) = variance(x(j,:))</literal>.
+            <code>s = variance(x,"c")</code> (or,  equivalently, <code>s = variance(x,2)</code>)
+            is the columnwise variance: <varname>s</varname> is a column vector, with <code>s(j) = variance(x(j,:))</code>.
         </para>
         <para>
-            <literal>s = variance(x,'r')</literal> (or,  equivalently, <literal>s = variance(x,1)</literal>)
-            is the rowwise variance: s is a row vector, with s(i) the variance of <literal>s(i) = variance(x(:,i))</literal>.
+            <code>s = variance(x,"r")</code> (or,  equivalently, <code>s = variance(x,1)</code>)
+            is the rowwise variance: <varname>s</varname> is a row vector, with <code>s(i) = variance(x(:,i))</code>.
         </para>
         <para>
-            The second output argument <literal>m</literal> is the mean of the input, with respect to the <literal>orien</literal> parameter.
+            The second output argument <varname>m</varname> is the mean of the input, with respect to the <varname>orien</varname> parameter.
         </para>
         <para>
-            <note>
-                If <code>m=%nan</code>, then the biased variance is returned:
-                that is, the chosen a priori mean is that of <varname>x</varname> and the denominator is <code>n</code>.
-            </note>
+            <warning>
+                The <literal>variance(x, "*"|"c"|"r", 1)</literal> synopsis used only in Scilab 5.4.1 must be replaced with
+                <literal>variance(x, "*"|"c"|"r", %nan)</literal>. <literal>variance(x, "*"|"c"|"r", 1)</literal> will warn
+                the user until Scilab 6.0. Indeed, <literal>1</literal> will be now considered as <literal>m=1</literal>.
+                If <literal>1</literal> is the true value provided as <varname>m</varname>, the warning may be avoided entering <literal>1+%eps</literal> instead
+                of <literal>1</literal>.
+            </warning>
         </para>
     </refsection>
     <refsection>
@@ -98,23 +140,34 @@ x = [ 0.2113249 0.0002211 0.6653811; 0.7560439 0.4453586 0.6283918 ]
 s = variance(x)
 s = variance(x, "r")
 s = variance(x, "c")
-// If the a priori mean is known
-m_r = mean(x, "r");
-m_c = mean(x, "c");
-s = variance(x, "r", m_r)
-s = variance(x, "c", m_c)
 
-// with complex numbers
+// The underlying statistical distribution and its mean are known:
+x = grand(100, 5, "unf", 0, 7);      // Uniform distribution on [0, 7]
+// => the true asymptotic mean is (0+7)/2 = 3.5 and variance = (7-0)^2/12
+(7-0)^2/12                  // True asymptotic variance
+s = variance(x)             // Unbiased (division by n-1).
+s = variance(x, "*", 3.5)   // Unbiased (division by n). Always >= variance(x)
+s = variance(x, "*", %nan)    // Biased   (division by n). Always <= variance(x)
+// Across columns:
+s = variance(x, "c")
+s = variance(x, "c", 3.5)
+s = variance(x, "c", %nan)
+
+// With complex numbers uniformly distributed on [0,1] + [0,1].i:
 x = rand(4, 3) + rand(4, 3)*%i
 s = variance(x)
+s = variance(x, "*", 0.5 + 0.5*%i)
+s = variance(x, "*", %nan)
 s = variance(x, "r")
 s = variance(x, "c")
 
-// with an hypermatrix
-x = rand(3, 2, 2)
+// With a hypermatrix
+x = rand(3, 2, 2)    // Uniform distribution on [0, 1]
 s = variance(x)
-// s = variance(x, "r")  // is not supported for an hypermatrix
-// s = variance(x, "c")  // is not supported for an hypermatrix
+s = variance(x, "*", 0.5)
+s = variance(x, "*", %nan)
+// s = variance(x, "r")  // Is not supported for a hypermatrix
+// s = variance(x, "c")  // Is not supported for a hypermatrix
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -126,6 +179,9 @@ s = variance(x)
             <member>
                 <link linkend="mtlb_var">mtlb_var</link>
             </member>
+            <member>
+                <link linkend="stdev">stdev</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection>
@@ -139,10 +195,31 @@ s = variance(x)
         <revhistory>
             <revision>
                 <revnumber>5.5.0</revnumber>
-                <revdescription>variance(x,orien,***) introduced. Variance can now take the a priori mean.
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <para>variance(x, orien, 0|1) removed (as introduced in Scilab 5.4.1)</para>
+                        </listitem>
+                        <listitem>
+                            <para>variance(x, orien, m) introduced: the true mean m of the underlaying statistical law can be used.</para>
+                        </listitem>
+                        <listitem>
+                            <para>variance(x, orien, %nan) introduced: mean(x,..) is used but divided by n values (instead of n-1)</para>
+                        </listitem>
+                        <listitem>
+                            <para>[s, mc] = variance(x,..) introduced: the mean mc computed from x is now also returned</para>
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
+            </revision>
+            <revision>
                 <revnumber>5.4.1</revnumber>
-                <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
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <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>
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
index 1daf7e8..4a24846 100644 (file)
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Samuel GOUGEON
  * Copyright (C) 2000 - INRIA - Carlos Klimann
  *
  * This file must be used under the terms of the CeCILL.
 <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">
     <refnamediv>
         <refname>variancef</refname>
-        <refpurpose>variance and mean of the values of a vector or matrix</refpurpose>
+        <refpurpose>variance (and mean) of a vector or matrix of frequency-weighted real or complex numbers</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
-        <synopsis>s = variancef(x, fre [,orien [,m]])
-            [s, m] = variancef(x, fre, 'r') or s = variancef(x, fre, 1)
-            [s, m] = variancef(x, fre, 'c') or s = variancef(x, fre, 2)
-            [s, m] = variancef(x, fre, 'r', m) or s = variancef(x, fre, m)
-            [s, m] = variancef(x, fre, 'c', m) or s = variancef(x, fre, m)
+        <synopsis>
+            [s [,mc]] = variancef(x, fre [,orien [,m]])
+            
+            [s, mc] = variancef(x)
+            [s, mc] = variancef(x, fre, "r"|1 )
+            [s, mc] = variancef(x, fre, "c"|2 )
+            [s, mc] = variancef(x, fre, "*"  , %nan)
+            [s, mc] = variancef(x, fre, "r"|1, %nan)
+            [s, mc] = variancef(x, fre, "c"|2, %nan)
+            s = variancef(x, fre, "*", m)
+            s = variancef(x, fre, "r", m)
+            s = variancef(x, fre, "c", m)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
             <varlistentry>
                 <term>x</term>
                 <listitem>
-                    <para>real or complex vector or matrix</para>
+                    <para>
+                        vector or matrix of real or complex numbers
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>fre</term>
+                <listitem>
+                    <para>
+                        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.
+                        <varname>fre</varname> and <varname>x</varname> have same sizes.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>orien</term>
+                <listitem>
+                    <para>the orientation of the computation. Valid values are:
+                        <itemizedlist>
+                            <listitem>1 or "r" : result is a row, after a column-wise computation.</listitem>
+                            <listitem>2 or "c" : result is a column, after a row-wise computation.</listitem>
+                            <listitem>
+                                "*" : full undirectional computation (default); explicitly required when <literal>m</literal> is used.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>m</term>
                 <listitem>
-                    <para>real or complex vector or matrix. The a priori weighted mean, to simplify computations</para>
+                    <para>
+                        The known mean of the underlying statistical distribution law (assuming that it is known).
+                        <itemizedlist>
+                            <listitem>
+                                "*" mode (default): <varname>m</varname> must be scalar
+                            </listitem>
+                            <listitem>
+                                "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>.
+                            </listitem>
+                            <listitem>
+                                "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>.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                    <para>
+                        Else, the <literal>variance</literal> is built dividing the quadratic distance of values to <varname>m</varname> by the number n of considered values.
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                    <para>
+                        When the special value <literal>m = %nan</literal> is provided, the variance is still normalized by n (not n-1) but is computed using
+                        <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.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>s</term>
+                <listitem>
+                    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>.
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mc</term>
+                <listitem>
+                    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.
                 </listitem>
             </varlistentry>
         </variablelist>
         <title>Description</title>
         <para>
             This function computes the variance of the values of a
-            vector or matrix <literal>x</literal>, each of them counted with a
-            frequency signaled by the corresponding values of the
-            integer vector or matrix <literal>fre</literal> with the same type of
-            <literal>x</literal>.
-        </para>
-        <para>
-            For a vector or matrix <literal>x</literal>, <literal>s=variancef(x,fre)</literal> (or
-            <literal>s=variancef(x,fre,'*')</literal>) returns in scalar <literal>s</literal> the
-            variance of all the entries of <literal>x</literal>, each value
-            counted with the multiplicity indicated by the
-            corresponding value of <literal>fre</literal>.
+            vector or matrix <varname>x</varname>, each of them <literal>x(i,j)</literal> being counted <literal>fre(i,j)</literal> times.
+            If <literal>x</literal> is complex, then <literal>variancef(x,fre,..) = variancef(real(x),fre,..) + variancef(imag(x),fre,..)</literal> is returned.
         </para>
         <para>
-            <literal>s=variancef(x,fre,'r')</literal>(or, equivalently,
-            <literal>s=variancef(x,fre,1)</literal>) returns in each entry of the row
-            vector <literal>s</literal> of type 1xsize(x,'c') the variance of
-            each column of <literal>x</literal>, each value counted with the
-            multiplicity indicated by the corresponding value of
-            <literal>fre</literal>.
+            <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>.
         </para>
         <para>
-            <literal>s=variancef(x,fre,'c')</literal>(or, equivalently,
-            <literal>s=variancef(x,fre,2)</literal>) returns in each entry of the
-            column vector <literal>s</literal> of type size(x,'c') x1 the variance
-            of each row of <literal>x</literal>, each value counted with the
-            multiplicity indicated by the corresponding value of
-            <literal>fre</literal>.
+            <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,
+            <literal>s(j) = variancef(x(:,j),fre(:,j),..)</literal>.
         </para>
         <para>
-            The second output argument <literal>m</literal> is the mean of the input,
-            with respect to the <literal>orien</literal> parameter.
+            <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,
+            <literal>s(i) = variancef(x(i,:),fre(i,:),..)</literal>.
         </para>
         <para>
-            If the weighted mean of <literal>x</literal> is known, then it can be passed to <literal>variancef</literal> to simplify its computations.
-        </para>
-        <para>
-            <note>
-                If <code>m=%nan</code>, then the biased variance is returned:
-                that is, the chosen a priori mean is that of <varname>x</varname> and the denominator is <code>size(x,"*")</code>.
-            </note>
+            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).
         </para>
     </refsection>
     <refsection>
@@ -96,11 +143,18 @@ fre = [1 2 3; 3 4 3]
 [s, m] = variancef(x, fre, "r")
 [s, m] = variancef(x, fre, "c")
 
-// If the weighted mean is known
-m_r = meanf(x, fre, "r");
-m_c = meanf(x, fre, "c");
-[s, m] = variancef(x, fre, "r", mean_r)
-[s, m] = variancef(x, fre, "c", mean_c)
+// Example #2:
+x0 = grand(20, 7, "uin", -9, 10)+0.4
+x = matrix((-9:10)+0.4, 5, 4)
+fre = members(x, x0)        // Computes the frequencies of x's elements in x0
+[s, m] = variancef(x, fre)  // Should be equal to variance(x0)
+[s, m] = variance(x0)
+
+// Example #2 (follow-up):
+m = (-9+10)/2+0.4               // Known asymptotic mean (if x0 had an infinite number of elements)
+s = variancef(x, fre, "*", m)   // Sample variance wrt the true mean
+s0 = (10 - (-9))^2 /12            // Known asymptotic variance
+s2 = variancef(x, fre, "*", %nan) // Takes m = meanf(x,fre) =>  always <= s
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -112,6 +166,9 @@ m_c = meanf(x, fre, "c");
             <member>
                 <link linkend="mtlb_var">mtlb_var</link>
             </member>
+            <member>
+                <link linkend="stdevf">stdevf</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection>
@@ -125,7 +182,21 @@ m_c = meanf(x, fre, "c");
         <revhistory>
             <revision>
                 <revnumber>5.5.0</revnumber>
-                <revdescription>variancef(x,fre,orien,***) introduced. Variancef can now take the a priori mean if it is known, not to compute it internally.
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <para>variancef(complexes,..) fixed.</para>
+                        </listitem>
+                        <listitem>
+                            <para>variancef(x, fre, orien, m) introduced: the true mean m of the underlying statistical law can be used.</para>
+                        </listitem>
+                        <listitem>
+                            <para>variancef(x, fre, orien, %nan) introduced: mean(x, fre,..) is used but divided by n values (instead of n-1)</para>
+                        </listitem>
+                        <listitem>
+                            <para>[s, mc] = variancef(x,fre,..) introduced : the mean mc computed from x and fre is now also returned</para>
+                        </listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
index da37752..bd83677 100644 (file)
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2000 - INRIA - Carlos Klimann
  * Copyright (C) 2013 - Samuel GOUGEON
+ * Copyright (C) 2000 - INRIA - Carlos Klimann
  *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
 <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">
     <refnamediv>
         <refname>variance</refname>
-        <refpurpose>variance des éléments d'un vecteur, matrice (voire hypermatrice) réel ou complexe</refpurpose>
+        <refpurpose>variance d'un vecteur, matrice (voire hypermatrice) de nombres réels ou complexes</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Séquence d'appel</title>
-        <synopsis>s = variance(x [,orien [,m]])
-            s = variance(x, 'r') or s = variance(x, 1)
-            s = variance(x, 'c') or s = variance(x, 2)
-            s = variance(x, '*', m)
-            s = variance(x, 'r', m)
-            s = variance(x, 'c', m)
+        <synopsis>
+            [s, [mc]] = variance(x [,orien [,m]])
+            
+            [s, mc] = variance(x)
+            [s, mc] = variance(x, "r"|1 )
+            [s, mc] = variance(x, "c"|2 )
+            [s, mc] = variance(x, "*"  , %nan)
+            [s, mc] = variance(x, "r"|1, %nan)
+            [s, mc] = variance(x, "c"|2, %nan)
+            s = variance(x, "*", m)
+            s = variance(x, "r", m)
+            s = variance(x, "c", m)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
@@ -33,7 +39,7 @@
                 <term>x</term>
                 <listitem>
                     <para>
-                        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,"*",1)</literal>
+                        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>
                     </para>
                 </listitem>
             </varlistentry>
                 <term>orien</term>
                 <listitem>
                     <para>
-                        variance selon les lignes ou les colonnes de <literal>x</literal>. Les valeurs possibles sont
+                        variance selon les lignes ou les colonnes de <varname>x</varname>. Les valeurs possibles sont
                         <itemizedlist>
                             <listitem>
-                                1 or "r" : calcul par colonne. Le résultat est un vecteur <literal>r</literal>angée (ligne)
+                                1 or "r" : calcul par colonne. Le résultat est un vecteur <varname>r</varname>angée (ligne)
                             </listitem>
                             <listitem>
-                                2 or "c" : calcul par ligne. Le résultat est une <literal>c</literal>olonne
+                                2 or "c" : calcul par ligne. Le résultat est une <varname>c</varname>olonne
                             </listitem>
                             <listitem>
-                                "*" : calcul tous éléments de <literal>x</literal> confondus (mode utilisé a priori); utile si le 3ème paramètre <literal>w</literal> doit par ailleurs être indiqué.
+                                "*" : 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é.
                             </listitem>
                         </itemizedlist>
                     </para>
                 <term>m</term>
                 <listitem>
                     <para>
-                        m: la moyenne a priori. Si cet argument est présent, alors la somme est normalisée par
-                        <literal>n</literal>.
-                        Sinon, elle est normalisée par <literal>n-1</literal> et <literal>variance</literal> retourne le mielleur estimateur non-biaisé de la variance.
+                        Espérance mathématique de la loi de distribution de probabilité sous-jacente (supposée connue).
+                        <itemizedlist>
+                            <listitem>
+                                mode "*" (par défaut) : <varname>m</varname> doit être scalaire
+                            </listitem>
+                            <listitem>
+                                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.
+                            </listitem>
+                            <listitem>
+                                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.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                    <para>
+                        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 :
+                        <itemizedlist>
+                            <listitem>
+                                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.
+                            </listitem>
+                            <listitem>
+                                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"
+                                <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.
+                            </listitem>
+                        </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
+            <varlistentry>
+                <term>s</term>
+                <listitem>
+                    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.
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mc</term>
+                <listitem>
+                    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.
+                </listitem>
+            </varlistentry>
         </variablelist>
     </refsection>
     <refsection>
             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.
         </para>
         <para>
-            Pour un vecteur, une matrice ou une hypermatrice <literal>x</literal>, <literal>s = variance(x)</literal> ou <literal>s = variance(x, "*", 1)</literal>
-            retourne  dans le scalaire <literal>s</literal> la variance de tous les éléments de <literal>x</literal>.
+            Pour un vecteur, une matrice ou une hypermatrice <varname>x</varname>, <literal>s = variance(x)</literal> ou <literal>s = variance(x, "*")</literal>
+            retourne  dans le scalaire <varname>s</varname> la variance de tous les éléments de <varname>x</varname>.
         </para>
         <para>
-            <literal>s = variance(x,'c')</literal> (ou indifféremment <literal>s = variance(x, 2)</literal>) calcule la variance de chaque ligne.
-            Le vecteur colonne <literal>s</literal> est retourné, avec <literal>s(j) = variance(x(j,:),..)</literal>.
+            <literal>s = variance(x,"c")</literal> (ou indifféremment <literal>s = variance(x, 2)</literal>) calcule la variance de chaque ligne.
+            Le vecteur colonne <varname>s</varname> est retourné, avec <literal>s(j) = variance(x(j,:),..)</literal>.
         </para>
         <para>
-            <literal>s = variance(x,'r')</literal> (ou indifféremment <literal>s = variance(x,1)</literal>) calcule la variance de chaque colonne.
-            Le vecteur ligne <literal>s</literal> est retourné, avec <literal>s(i) = variance(x(:,i),..)</literal>.
+            <literal>s = variance(x,"r")</literal> (ou indifféremment <literal>s = variance(x,1)</literal>) calcule la variance de chaque colonne.
+            Le vecteur ligne <varname>s</varname> est retourné, avec <literal>s(i) = variance(x(:,i),..)</literal>.
         </para>
         <para>
-            <note>
-                Si <code>m=%nan</code>, alors la variance biaisée est retournée;
-                c'est-à-dire que la moyenne a priori choisie est celle de <varname>x</varname> et le dénominateur est <code>n</code>.
-            </note>
+            <warning>
+                La syntaxe <literal>variance(x, "*"|"c"|"r", 1)</literal> utilisable uniquement en Scilab 5.4.1 doit être remplacée par
+                <literal>variance(x,"*"|"c"|"r", %nan)</literal>. <literal>variance(x, "*"|"c"|"r", 1)</literal> émettra une alerte
+                jusqu'en Scilab 6.0. En effet, <literal>1</literal> est désormais compris comme <literal>m=1</literal>.
+                Si <literal>1</literal> est la valeur de l'espérance <varname>m</varname>à fournir, l'alerte peut être évitée
+                en indiquant<literal>1+%eps</literal> au lieu de <literal>1</literal>.
+            </warning>
         </para>
     </refsection>
     <refsection>
         <title>Exemples</title>
         <programlisting role="example"><![CDATA[
-x = [ 0.2113249 0.0002211 0.6653811;0.7560439 0.4453586 0.6283918 ]
+x = [ 0.2113249 0.0002211 0.6653811; 0.7560439 0.4453586 0.6283918 ]
 s = variance(x)
 s = variance(x, "r")
 s = variance(x, "c")
 
-// Si la moyenne est connue a priori
-m_r = mean(x, "r");
-m_c = mean(x, "c");
-s = variance(x, "r", m_r)
-s = variance(x, "c", m_c)
+// La loi de distribution de probabilité sous-jacente et son espérance (moyenne) sont connues :
+x = grand(100,5,"unf",0,7);      // Distribution uniforme sur [0, 7]
+// => espérance = (0+7)/2 = 3.5  et variance = (7-0)^2/12
+(7-0)^2/12                             // Variance asymptotique vraie
+s = variance(x)             // Estimation non biaisée (division par n-1).
+s = variance(x, "*", 3.5)   // Estimation non biaisée (division par n). Toujours >= variance(x)
+s = variance(x, "*", %nan)     // Estimation biaisée     (division par n). Toujours <= variance(x)
+// A travers les colonnes (le long des lignes) => résultat en colonne :
+s = variance(x, "c")
+s = variance(x, "c", 3.5)
+s = variance(x, "c", %nan)
 
-// avec des nombres complexes
-x = rand(4,3) + rand(4,3)*%i
+// Nombres complexes uniformément distribués sur [0,1] + [0,1].i :
+x = rand(4, 3) + rand(4, 3)*%i
 s = variance(x)
+s = variance(x, "*", 0.5 + 0.5*%i)
+s = variance(x, "*", %nan)
 s = variance(x, "r")
 s = variance(x, "c")
 
-// avec une hypermatrice
-x = rand(3, 2, 2)
+// Nombres fournis en hypermatrice :
+x = rand(3, 2, 2)      // Distribution uniforme sur [0, 1]
 s = variance(x)
-// s = variance(x, "r")  // utilisation non admise pour une hypermatrice
-// s = variance(x, "c")  // utilisation non admise pour une hypermatrice
+s = variance(x, "*", 0.5)
+s = variance(x, "*", %nan)
+// s = variance(x, "r")  //  Utilisation non admise pour une hypermatrice
+// s = variance(x, "c")  //  Utilisation non admise pour une hypermatrice
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
         <title>Voir aussi</title>
         <simplelist type="inline">
             <member>
+                <link linkend="variancef">variancef</link>
+            </member>
+            <member>
                 <link linkend="mtlb_var">mtlb_var</link>
             </member>
+            <member>
+                <link linkend="stdev">stdev</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection>
@@ -137,10 +198,34 @@ s = variance(x)
         <title>Historique</title>
         <revhistory>
             <revision>
+                <revnumber>5.5.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <para>variance(x, orien, 0|1) supprimée (utilisable uniquement avec Scilab 5.4.1)</para>
+                        </listitem>
+                        <listitem>
+                            <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>
+                        </listitem>
+                        <listitem>
+                            <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>
+                        </listitem>
+                        <listitem>
+                            <para>[s, mc] = variance(x,..) introduite : la moyenne mc calculée sur l'échantillon x peut être obtenue en second résultat</para>
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+            <revision>
                 <revnumber>5.4.1</revnumber>
-                <revdescription>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</revdescription>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <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>
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
             </revision>
         </revhistory>
     </refsection>
-    
 </refentry>
diff --git a/scilab/modules/statistics/help/fr_FR/descriptive_statistics/variancef.xml b/scilab/modules/statistics/help/fr_FR/descriptive_statistics/variancef.xml
new file mode 100644 (file)
index 0000000..55b7d5a
--- /dev/null
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
+ * Copyright (C) 2013 - Samuel Gougeon
+ * Copyright (C) 2000 - INRIA - Carlos Klimann
+ *
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at
+ * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
+ *
+ -->
+<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">
+    <refnamediv>
+        <refname>variancef</refname>
+        <refpurpose>variance (et moyenne) d'un vecteur ou d'une matrice réelle ou complexe de nombres pondérés en fréquence</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Séquence d'appel</title>
+        <synopsis>
+            [s [,mc]] = variancef(x, fre [,orien [,m]])
+            
+            [s, mc] = variancef(x)
+            [s, mc] = variancef(x, fre, "r"|1 )
+            [s, mc] = variancef(x, fre, "c"|2 )
+            [s, mc] = variancef(x, fre, "*"  , %nan)
+            [s, mc] = variancef(x, fre, "r"|1, %nan)
+            [s, mc] = variancef(x, fre, "c"|2, %nan)
+            s = variancef(x, fre, "*", m)
+            s = variancef(x, fre, "r", m)
+            s = variancef(x, fre, "c", m)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Paramètres</title>
+        <variablelist>
+            <varlistentry>
+                <term>x</term>
+                <listitem>
+                    <para>
+                        vecteur ou matrice réel(le) ou complexe
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>fre</term>
+                <listitem>
+                    <para>
+                        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é.
+                        <varname>fre</varname> et <varname>x</varname> doivent être de même taille.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>orien</term>
+                <listitem>
+                    <para>l'orientation du calcul. Les valeurs acceptées sont:
+                        <itemizedlist>
+                            <listitem>1 ou "r" : le résultat est une rangée, après un calcul en colonne.</listitem>
+                            <listitem>2 ou "c" : le résultat est une colonne, après un calcul en ligne.</listitem>
+                            <listitem>
+                                "*" : 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é.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>m</term>
+                <listitem>
+                    <para>
+                        Espérance mathématique de la loi de distribution de probabilité sous-jacente (supposée connue).
+                        <itemizedlist>
+                            <listitem>
+                                "*" mode (par défaut): <varname>m</varname> doit être scalaire
+                            </listitem>
+                            <listitem>
+                                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.
+                            </listitem>
+                            <listitem>
+                                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.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                    <para>
+                        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.
+                    </para>
+                    <para>
+                        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 :
+                        <itemizedlist>
+                            <listitem>
+                                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.
+                            </listitem>
+                            <listitem>
+                                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"
+                                <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.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>s</term>
+                <listitem>
+                    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.
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>mc</term>
+                <listitem>
+                    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.
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            Cette fonction calcule la variance des valeurs d'un vecteur ou une matrice
+            <varname>x</varname>, chacun des <literal>x(i,j)</literal> étant compté <literal>fre(i,j)</literal> fois.
+            If <varname>x</varname> est complexe, alors <literal>variancef(x, fre,..) = variancef(real(x), fre,..) + variancef(imag(x), fre,..)</literal> est retourné.
+        </para>
+        <para>
+            <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>.
+        </para>
+        <para>
+            <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,
+            <literal>s(j) = variancef(x(:,j),fre(:,j),..)</literal>.
+        </para>
+        <para>
+            <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,
+            <literal>s(i) = variancef(x(i,:),fre(i,:),..)</literal>.
+        </para>
+        <para>
+            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).
+        </para>
+    </refsection>
+    <refsection>
+        <title>Exemples</title>
+        <programlisting role="example"><![CDATA[
+x = [0.2113249 0.0002211 0.6653811; 0.7560439 0.9546254 0.6283918]
+fre = [1 2 3; 3 4 3]
+[s, m] = variancef(x, fre)
+[s, m] = variancef(x, fre, "r")
+[s, m] = variancef(x, fre, "c")
+
+// Exemple #2:
+x0 = grand(20, 7, "uin", -9,10)+0.4
+x = matrix((-9:10)+0.4, 5, 4)
+fre = members(x, x0)        // Calcule les fréquences des éléments de x dans x0
+[s, m] = variancef(x, fre)  // Doit être égal à variance(x0)
+[s, m] = variance(x0)
+
+// Exemple #2 (suite):
+m = (-9+10)/2+0.4               // Moyenne asymptotique connue (si x0 avait un nombre infini d'éléments)
+s = variancef(x, fre, "*", m)   // Variance "échantillon" en regard de la vraie moyenne
+s0 = (10 - (-9))^2 /12          // Variance asymptotique connue
+s2 = variancef(x, fre, "*", %nan)
+ ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>Voir aussi</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="variance">variance</link>
+            </member>
+            <member>
+                <link linkend="mtlb_var">mtlb_var</link>
+            </member>
+            <member>
+                <link linkend="stdevf">stdevf</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection>
+        <title>Bibliographie</title>
+        <para>
+            Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Historique</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.5.0</revnumber>
+                <revdescription>
+                    <itemizedlist>
+                        <listitem>
+                            <para>variancef() peut être appelée avec des nombres complexes.</para>
+                        </listitem>
+                        <listitem>
+                            <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>
+                        </listitem>
+                        <listitem>
+                            <para>variancef(x, fre, orien, %nan) introduit: mean(x, fre,..) est utilisé mais divisé par n valeurs (à la place de n-1)</para>
+                        </listitem>
+                        <listitem>
+                            <para>[s, mc] = variancef(x,fre,..) introduit : la moyenne mc évaluée à partir de x et fre est maintenant retournée</para>
+                        </listitem>
+                    </itemizedlist>
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>
index c100349..d9d39b6 100644 (file)
@@ -76,8 +76,8 @@ function [s, m] = variance(x, orien, m)
             orien = "r"
         end
     else
-        tmp = gettext("%s: Wrong value for input argument: ''%s'', ''%s'', %d or %d expected.\n")
-        error(msprintf(tmp, "variance", "c", "r", 1, 2))
+        tmp = gettext("%s: Wrong value for input argument #%d: ''%s'', ''%s'', %d or %d expected.\n")
+        error(msprintf(tmp, "variance", 2, "c", "r", 1, 2))
     end
 
     // Calculations
index 7d30847..b36d14c 100644 (file)
-
-// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2000 - INRIA - Carlos Klimann
-//
-// This file must be used under the terms of the CeCILL.
-// This source file is licensed as described in the file COPYING, which
-// you should have received as part of this distribution.  The terms
-// are also available at
-// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
-//
-
-function [s,m]=variancef(x,fre,orien,m)
-    //
-    //This function  computes  the variance  of the values  of   a vector or
-    //matrix x, each  of  them  counted with  a  frequency signaled   by the
-    //corresponding values of the integer vector or matrix fre with the same
-    //type of x.
-    //
-    //For a vector or matrix  x, s=variancef(x,fre) (or s=variancef(x,fre,'*') returns
-    //in scalar s the variance  of all the  entries of x, each value counted
-    //with the multiplicity indicated by the corresponding value of fre.
-    //
-    //s=variancef(x,fre,'r')(or,   equivalently, s=variancef(x,fre,1)) returns in each
-    //entry of the row vector s  of type 1xsize(x,'c')  the variance of each
-    //column of x, each value counted with the multiplicity indicated by the
-    //corresponding value of fre.
-    //
-    //s=variancef(x,fre,'c')(or, equivalently,   s=variancef(x,fre,2)) returns in each
-    //entry of  the column vector  s of type   size(x,'c')x1 the variance of
-    //each row of  x, each value counted with  the multiplicity indicated by
-    //the corresponding value of fre.
-    //
-    //The input argument m represents the a priori mean. If it is present, then the sum is
-    //divided by n. Otherwise ("sample variance"), it is divided by n-1.
-    //
-    //
-    if x==[] then s=%nan, return, end
-    [lhs,rhs]=argn(0)
-    if rhs<2|rhs>4 then
-        error(msprintf(gettext("%s: Wrong number of input arguments: %d to %d expected.\n"),"variancef",2,4)),
-    end
-    if x==[]|fre==[]|fre==0, s=%nan;return,end
-    if rhs==2 then
-        sumfre=sum(fre)
-        if sumfre <= 1 then error(msprintf(gettext("%s: Wrong value for input argument #%d: Must be > %d.\n"),"variancef", 2, 1)), end
-        m = meanf(x,fre)
-        s=(sum(((x-m).^2).*fre))/(sumfre-1),
-        return,
-    end
-    biased = %f
-    if rhs==4 then
-        if typeof(m)~="constant" then
-            tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")
-            error(msprintf(tmp, "variance", ))
-        elseif orien=="*" then
-            if ~isscalar(m) then
-                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")
-                error(msprintf(tmp, "variance", ))
-            end
-        elseif orien=="r" | orien==1 then
-            if size(m)~=[1 size(x,"c")] & ~isscalar(m) then
-                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")
-                error(msprintf(tmp, "variance", ))
-            end
-        elseif orien=="c" | orien==2 then
-            if size(m)~=[size(x,"r") 1] & ~isscalar(m) then
-                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")
-                error(msprintf(tmp, "variance", ))
-            end
-        end
-        if isnan(m) then
-            biased = %t; // Compute the biased variance
-        end
-    end
-    if orien=="*",
-        sumfre=sum(fre)
-        if sumfre <= 1 then error(msprintf(gettext("%s: Wrong value for input argument #%d: Must be > %d.\n"),"variancef", 2, 1)),end
-        if rhs<4 then
-            m = meanf(x,fre)
-            s=(sum(((x-m).^2).*fre))/(sumfre-1),
-        elseif biased == %t
-            m = meanf(x,fre)
-            s=(sum(((x-m).^2).*fre))/sumfre,
-        else
-            s=(sum(((x-m).^2).*fre))/sumfre,
-        end
-    elseif orien=="r"|orien==1,
-        sumfre=sum(fre,"r")
-        if or(sumfre==0) then error(msprintf(gettext("%s: Wrong value for input argument #%d: Must be > %d.\n"),"variancef",2,1)),end
-        if rhs<4 | biased == %t then
-            m = meanf(x,fre,"r")
-        elseif isscalar(m) then
-            m = m*ones(1, size(x,"c"));
-        end
-        m2 = ones(size(x,"r"),1)*m
-        if rhs<4 then
-            s=(sum(((x-m2).^2).*fre))./(sumfre-1)
-        else
-            s=(sum(((x-m2).^2).*fre))./sumfre
-        end
-    elseif orien=="c"|orien==2,
-        sumfre=sum(fre,"c")
-        if or(sumfre==0) then error(msprintf(gettext("%s: Wrong value for input argument #%d: Must be > %d.\n"),"variancef",2,1)),end
-        if rhs<4 | biased == %t then
-            m = meanf(x,fre,"c")
-        elseif isscalar(m) then
-            m = m*ones(size(x,"r"), 1);
-        end
-        m2 = m*ones(1,size(x,"c"))
-        if rhs<4 then
-            s=(sum((x-m2).^2,"c"))./(sumfre-1)
-        else
-            s=(sum((x-m2).^2,"c"))./sumfre
-        end
-    else error(msprintf(gettext("%s: Wrong value for input argument #%d: ''%s'', ''%s'', ''%s'', %d or %d expected.\n"),"variancef",3,"*","c","r",1,2))
-    end
-
-endfunction
+\r
+// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab\r
+// Copyright (C) 2013 - Scilab Enterprises - Paul BIGNIER : m parameter added\r
+// Copyright (C) 2013 - Samuel GOUGEON : http://bugzilla.scilab.org/11209 fixed\r
+// Copyright (C) 2000 - INRIA - Carlos Klimann\r
+//\r
+// This file must be used under the terms of the CeCILL.\r
+// This source file is licensed as described in the file COPYING, which\r
+// you should have received as part of this distribution.  The terms\r
+// are also available at\r
+// http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt\r
+//\r
+\r
+function [s, m] = variancef(x, fre, orien, m)\r
+    //\r
+    //This function  computes  the variance  of the values  of   a vector or\r
+    //matrix x, each  of  them  counted with  a  frequency signaled   by the\r
+    //corresponding values of the integer vector or matrix fre with the same\r
+    //type of x.\r
+    //\r
+    //For a vector or matrix  x, s=variancef(x,fre) (or s=variancef(x,fre,'*') returns\r
+    //in scalar s the variance  of all the  entries of x, each value counted\r
+    //with the multiplicity indicated by the corresponding value of fre.\r
+    //\r
+    //s=variancef(x,fre,'r')(or,   equivalently, s=variancef(x,fre,1)) returns in each\r
+    //entry of the row vector s  of type 1xsize(x,'c')  the variance of each\r
+    //column of x, each value counted with the multiplicity indicated by the\r
+    //corresponding value of fre.\r
+    //\r
+    //s=variancef(x,fre,'c')(or, equivalently,   s=variancef(x,fre,2)) returns in each\r
+    //entry of  the column vector  s of type   size(x,'c')x1 the variance of\r
+    //each row of  x, each value counted with  the multiplicity indicated by\r
+    //the corresponding value of fre.\r
+    //\r
+    //The input argument m represents the a priori mean. If it is present, then the sum is\r
+    //divided by n. Otherwise ("sample variance"), it is divided by n-1.\r
+    //\r
+    //\r
+\r
+    [lhs,rhs] = argn(0)\r
+    if rhs<2 | rhs>4 then\r
+        msg = gettext("%s: Wrong number of input arguments: %d to %d expected.\n")\r
+        error(msprintf(msg, "variancef", 2, 4))\r
+    end\r
+    if x==[] | fre==[] | fre==0\r
+        s = %nan\r
+        return\r
+    end\r
+    if rhs==2 then\r
+        sumfre = sum(fre)\r
+        if sumfre <= 1 then\r
+            msg = gettext("%s: Wrong value for input argument #%d: Must be > %d.\n")\r
+        error(msprintf(msg, "variancef", 2, 1)), end\r
+        m = meanf(x,fre)\r
+        s = sum((abs(x-m).^2).*fre) / (sumfre-1)\r
+        return\r
+    end\r
+    biased = %f\r
+    if rhs==4 then\r
+        if typeof(m)~="constant" then\r
+            tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")\r
+            error(msprintf(tmp, "variancef", ))\r
+        elseif orien=="*" then\r
+            if ~isscalar(m) then\r
+                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")\r
+                error(msprintf(tmp, "variancef", ))\r
+            end\r
+        elseif orien=="r" | orien==1 then\r
+            if size(m)~=[1 size(x,"c")] & ~isscalar(m) then\r
+                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")\r
+                error(msprintf(tmp, "variancef", ))\r
+            end\r
+        elseif orien=="c" | orien==2 then\r
+            if size(m)~=[size(x,"r") 1] & ~isscalar(m) then\r
+                tmp = gettext("%s: Wrong value of m : a priori mean expected.\n")\r
+                error(msprintf(tmp, "variancef", ))\r
+            end\r
+        end\r
+        if isnan(m) then\r
+            biased = %t; // Compute the biased variance\r
+        end\r
+    end\r
+    if orien=="*",\r
+        sumfre = sum(fre)\r
+        if sumfre <= 1 then\r
+            msg = _("%s: Wrong value for input argument #%d: Must be > %d.\n")\r
+        error(msprintf(msg, "variancef", 2, 1)),end\r
+        if rhs<4 then\r
+            m = meanf(x,fre)\r
+            s = sum((abs(x-m).^2).*fre) / (sumfre-1)\r
+        elseif biased == %t\r
+            m = meanf(x,fre)\r
+            s = sum((abs(x-m).^2).*fre) / sumfre\r
+        else\r
+            s = sum((abs(x-m).^2).*fre) / sumfre\r
+        end\r
+    elseif orien=="r" | orien==1,\r
+        sumfre = sum(fre, "r")\r
+        if or(sumfre==0) then\r
+            msg = _("%s: Wrong value for input argument #%d: Must be > %d.\n")\r
+            error(msprintf(msg, "variancef", 2, 1))\r
+        end\r
+        if rhs<4 | biased == %t then\r
+            m = meanf(x,fre,"r")\r
+        elseif isscalar(m) then\r
+            m = m*ones(1, size(x,"c"));\r
+        end\r
+        m2 = ones(size(x,"r"),1)*m\r
+        if rhs<4 then\r
+            s = sum((abs(x-m2).^2).*fre, "r") ./ (sumfre-1)\r
+        else\r
+            s = sum((abs(x-m2).^2).*fre, "r") ./ sumfre\r
+        end\r
+    elseif orien=="c" | orien==2,\r
+        sumfre = sum(fre, "c")\r
+        if or(sumfre==0) then\r
+            msg = _("%s: Wrong value for input argument #%d: Must be > %d.\n")\r
+            error(msprintf(msg, "variancef", 2, 1))\r
+        end\r
+        if rhs<4 | biased == %t then\r
+            m = meanf(x,fre,"c")\r
+        elseif isscalar(m) then\r
+            m = m*ones(size(x,"r"), 1);\r
+        end\r
+        m2 = m*ones(1,size(x,"c"))\r
+        if rhs<4 then\r
+            s = sum((abs(x-m2).^2).*fre, "c") ./ (sumfre-1)\r
+        else\r
+            s = sum((abs(x-m2).^2).*fre, "c") ./ sumfre\r
+        end\r
+    else\r
+        msg = _("%s: Wrong value for input argument #%d: ''%s'', ''%s'', ''%s'', %d or %d expected.\n")\r
+        error(msprintf(msg, "variancef", 3, "*", "c", "r", 1, 2))\r
+    end\r
+\r
+endfunction\r
index 5e3e732..499e4bc 100644 (file)
@@ -49,14 +49,14 @@ x = [0.2113249 0.0002211 0.6653811; 0.7560439 0.9546254 0.6283918];
 fre = [1 2 3; 3 4 3];
 orien = "r";
 refM = [1 1 1];
-refV = [0.889522663062 0.593015108708 0.593015108708];
+refV = [0.200138037385 0.334558519179 0.125031231272];
 [v, m] = variancef( x, fre, orien, ones(meanf(x,fre,orien)) );
 assert_checkalmostequal([v m], [refV refM]);
 [v, m] = variancef( x, fre, orien, 1 );
 assert_checkalmostequal([v m], [refV refM]);
 orien = "c";
 refM = [1; 1];
-refV = [0.288922678414; 0.019966608736];
+refV = [0.492838922640; 0.060105711640];
 [v, m] = variancef( x, fre, orien, ones(meanf(x,fre,orien)) );
 assert_checkalmostequal([v m], [refV refM]);
 [v, m] = variancef( x, fre, orien, 1 );
index c44b5a9..7fab7e8 100644 (file)
@@ -55,7 +55,7 @@ x = [0.2113249 0.0002211 0.6653811; 0.7560439 0.9546254 0.6283918];
 fre = [1 2 3; 3 4 3];
 orien = "r";
 refM = [1 1 1];
-refV = [0.889522663062 0.593015108708 0.593015108708];
+refV = [0.200138037385 0.334558519179 0.125031231272];
 
 [v, m] = variancef( x, fre, orien, ones(meanf(x,fre,orien)) );
 assert_checkalmostequal([v m], [refV refM]);
@@ -65,7 +65,7 @@ assert_checkalmostequal([v m], [refV refM]);
 
 orien = "c";
 refM = [1; 1];
-refV = [0.288922678414; 0.019966608736];
+refV = [0.492838922640; 0.060105711640];
 [v, m] = variancef( x, fre, orien, ones(meanf(x,fre,orien)) );
 assert_checkalmostequal([v m], [refV refM]);
 
index 3cb5eaf..255d64a 100644 (file)
@@ -13,11 +13,11 @@ refV = 0.096057419504;
 [v, m] = variancef(x, fre);
 assert_checkalmostequal([v m], [refV refM]);
 refM = [0.61986415 0.636490633333 0.64688645];
-refV = [0.479702720446 0.287821632267 0.287821632267];
+refV = [0.074179697240 0.242903351429 0.000410462494];
 [v, m] = variancef(x, fre, "r");
 assert_checkalmostequal([v m], [refV refM]);
 refM = [0.367985066667; 0.79718087];
-refV = [0.049647428728; 0.006107864498];
+refV = [0.112075256021; 0.021077902385];
 [v, m] = variancef(x, fre, "c");
 assert_checkalmostequal([v m], [refV refM]);
 // With the a priori mean
@@ -26,11 +26,11 @@ refV = 0.090053830785;
 [v, m] = variancef(x, fre, "*", meanf(x,fre));
 assert_checkalmostequal([v m], [refV refM]);
 refM = [0.61986415 0.636490633333 0.64688645];
-refV = [0.35977704 0.23985136 0.23985136];
+refV = [0.055634772930 0.202419459524 0.000342052079];
 [v, m] = variancef(x, fre, "r", meanf(x,fre,"r"));
 assert_checkalmostequal([v m], [refV refM]);
 refM = [0.367985066667; 0.79718087];
-refV = [0.041372857273; 0.005497078047];
+refV = [0.093396046684; 0.018970112146];
 [v, m] = variancef(x, fre, "c", meanf(x,fre,"c"));
 assert_checkalmostequal([v m], [refV refM]);
 // Biased variance
index 15d3c91..66630d2 100644 (file)
@@ -16,12 +16,12 @@ refV = 0.096057419504;
 assert_checkalmostequal([v m], [refV refM]);
 
 refM = [0.61986415 0.636490633333 0.64688645];
-refV = [0.479702720446 0.287821632267 0.287821632267];
+refV = [0.074179697240 0.242903351429 0.000410462494];
 [v, m] = variancef(x, fre, "r");
 assert_checkalmostequal([v m], [refV refM]);
 
 refM = [0.367985066667; 0.79718087];
-refV = [0.049647428728; 0.006107864498];
+refV = [0.112075256021; 0.021077902385];
 [v, m] = variancef(x, fre, "c");
 assert_checkalmostequal([v m], [refV refM]);
 
@@ -32,12 +32,12 @@ refV = 0.090053830785;
 assert_checkalmostequal([v m], [refV refM]);
 
 refM = [0.61986415 0.636490633333 0.64688645];
-refV = [0.35977704 0.23985136 0.23985136];
+refV = [0.055634772930 0.202419459524 0.000342052079];
 [v, m] = variancef(x, fre, "r", meanf(x,fre,"r"));
 assert_checkalmostequal([v m], [refV refM]);
 
 refM = [0.367985066667; 0.79718087];
-refV = [0.041372857273; 0.005497078047];
+refV = [0.093396046684; 0.018970112146];
 [v, m] = variancef(x, fre, "c", meanf(x,fre,"c"));
 assert_checkalmostequal([v m], [refV refM]);