* variance is now vectorized and allows the syntax variance(x,"*",w). 57/10757/4
Samuel GOUGEON [Fri, 8 Mar 2013 17:00:03 +0000 (18:00 +0100)]
  See bug #12362

Translation into French of the variance help page

Change-Id: I891328b07d336c90019e05c6425275d4aa7af446

scilab/CHANGES_5.4.X
scilab/modules/statistics/help/en_US/descriptive_statistics/variance.xml
scilab/modules/statistics/help/fr_FR/descriptive_statistics/variance.xml [new file with mode: 0644]
scilab/modules/statistics/macros/variance.sci

index a054e39..7062eed 100644 (file)
@@ -37,6 +37,8 @@ Improvements
 
 * Completion in Scilab is now case insensitive. See bug #6320.
 
+* variance is now vectorized and allows the syntax variance(x,"*",w).
+  See bug #12362
 
 
 Removed functions
index 36e6b95..edee47c 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) 2000 - INRIA - Carlos Klimann
+ * Copyright (C) 2013 - Samuel GOUGEON
  * 
  * 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 of  the values of a  vector or matrix</refpurpose>
+        <refpurpose>variance of the values of a vector or matrix (or hypermatrix) real or complex</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Calling Sequence</title>
-        <synopsis>s=variance(x[,orien[,w]])
-            s=variance(x,'r') or m=variance(x,1)
-            s=variance(x,'c') or m=variance(x,2)
+        <synopsis>s = variance(x [,orien [,w]])
+            s = variance(x,'r') or s = variance(x,1)
+            s = variance(x,'c') or s = variance(x,2)
+            s = variance(x,'*',1)
+            s = variance(x,'r',1)
+            s = variance(x,'c',1)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
             <varlistentry>
                 <term>x</term>
                 <listitem>
-                    <para>real or complex vector or matrix</para>
+                    <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>
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>orien</term>
                 <listitem>
-                    <para>the orientation of the computation. Valid values or the orien parameter
-                        are 1, "r", 2 and "c".
+                    <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); useful explicitly when <literal>w</literal> is used.
+                            </listitem>
+                        </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>w</term>
                 <listitem>
-                    <para>w : type of normalization to use. Valid values are 0 and 1. 
-                        This depends on the number of columns of x (if orien = 1 is chosen),
-                        the number of rows (if orien = 2 is chosen).
-                        If w = 0, normalizes with m-1, provides the best unbiased estimator of the variance (this is the default).
-                        If w = 1, normalizes with m, this provides the second moment around the mean.
-                        If no orien option is given, the normalization is done with n * m - 1, where n * m is the total 
-                        number of elements in the matrix.
+                    <para>w : type of normalization to use. Valid values are 
+                        <itemizedlist>
+                            <listitem>0 : provides the best unbiased estimator of the variance when the mean is not known a priori. This is the default.
+                                The sum is normalized by 1/(nE-1), where nE is the number of summed elements 
+                                (the number of rows nR if "r" is used; of columns nC if "c" is used; or by default nC*nR)
+                            </listitem>
+                            <listitem>1 : provides the second moment around the mean. The sum is normalized by 1/nE.
+                                This estimation is unbiased only if the mean is known a priori.
+                            </listitem>
+                        </itemizedlist>
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            This function  computes the variance of  the values of a
-            vector or matrix <literal>x</literal>.
+            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.
         </para>
         <para>
-            For a vector or a matrix <literal>x</literal>, <literal>s=variance(x)</literal> returns
-            in the scalar <literal>s</literal> the variance of all the entries of
-            <literal>x</literal>.
+            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>.
         </para>
         <para>
-            <literal>s=variance(x,'r')</literal> (or,  equivalently, <literal>s=variance(x,1)</literal>)
-            is the rowwise variance. It returns in each entry of the
-            row vector s the variance of each column of <literal>x</literal>.
-            The generalized formulae is used, which manages complex values.
+            <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>.
         </para>
         <para>
-            <literal>s=variance(x,'c')</literal> (or, equivalently,  <literal>s=variance(x,2)</literal>)
-            is the columnwise  standard  deviation.  It returns   in
-            each entry of the column vector  <literal>s</literal> the variance of
-            each row of <literal>x</literal>.
-            The generalized formulae is used, which manages complex values.
+            <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>.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[ 
-x=[0.2113249 0.0002211 0.6653811;0.7560439 0.4453586 0.6283918]
-s=variance(x)
-s=variance(x,'r')
-s=variance(x,'c')
+x = [ 0.2113249 0.0002211 0.6653811;0.7560439 0.4453586 0.6283918 ]
+s = variance(x)
+s = variance(x, "r")
+s = variance(x, "c")
+
+// with complex numbers
+x = rand(4,3) + rand(4,3)*%i
+s = variance(x)
+s = variance(x, "*", 1)        // should be smaller than the previous one
+s = variance(x, "r")
+s = variance(x, "r", 1)
+s = variance(x, "c")
+
+// with an hypermatrix
+x = rand(3,2,2)
+s = variance(x)
+s = variance(x, "*", 1)        // should be smaller than the previous one
+// s = variance(x, "r")  // is not supported for an hypermatrix
+// s = variance(x, "c")  // is not supported for an hypermatrix
  ]]></programlisting>
     </refsection>
     <refsection role="see also">
@@ -102,4 +125,14 @@ s=variance(x,'c')
             Wonacott, T.H. &amp; Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley &amp; Sons, 1990.
         </para>
     </refsection>
+    <refsection>
+        <title>History</title>
+        <revhistory>
+            <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>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/statistics/help/fr_FR/descriptive_statistics/variance.xml b/scilab/modules/statistics/help/fr_FR/descriptive_statistics/variance.xml
new file mode 100644 (file)
index 0000000..e971d9f
--- /dev/null
@@ -0,0 +1,141 @@
+<?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
+ * 
+ * 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-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="variance">
+    <refnamediv>
+        <refname>variance</refname>
+        <refpurpose>variance des éléments d'un vecteur, matrice (voire hypermatrice) réel ou complexe</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Séquence d'appel</title>
+        <synopsis>s = variance(x [,orien [,w]])
+            s = variance(x,'r') or s = variance(x,1)
+            s = variance(x,'c') or s = variance(x,2)
+            s = variance(x,'*',1)
+            s = variance(x,'r',1)
+            s = variance(x,'c',1)
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection>
+        <title>Paramètres</title>
+        <variablelist>
+            <varlistentry>
+                <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>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>orien</term>
+                <listitem>
+                    <para>
+                        variance selon les lignes ou les colonnes de <literal>x</literal>. Les valeurs possibles sont
+                        <itemizedlist>
+                            <listitem>
+                                1 or "r" : calcul par colonne. Le résultat est un vecteur <literal>r</literal>angée (ligne)
+                            </listitem>
+                            <listitem>
+                                2 or "c" : calcul par ligne. Le résultat est une <literal>c</literal>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é.
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>w</term>
+                <listitem>
+                    <para>w : indique le type de normalisation de la variance : 
+                        <itemizedlist>
+                            <listitem>
+                                0 : la somme des écarts quadratiques est divisée par (nE-1), où nE est le nombre d'écarts sommés (mode de calcul utilisé a priori). La variance ainsi estimée est non biaisée (l'espérance de la variable aléatoire n'est pas connue a priori ; elle est estimée par la moyenne des valeurs de x). nE est le nombre nR de lignes de <literal>x</literal> si "r" est utilisée ; ou le nombre nC de colonnes si "c" est utilisée ; ou le nombre total nR*nC d'éléments, sinon.
+                            </listitem>
+                            <listitem>1 : la somme des écarts quadratiques est divisée par nE. La variance résultante est non biaisée uniquement si l'espérance de la variable aléatoire est connue (Scilab ne permet actuellement pas de l'indiquer en paramètre).
+                            </listitem>
+                        </itemizedlist>
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <title>Description</title>
+        <para>
+            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>.
+        </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>.
+        </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>.
+        </para>
+    </refsection>
+    <refsection>
+        <title>Exemples</title>
+        <programlisting role="example"><![CDATA[ 
+x = [ 0.2113249 0.0002211 0.6653811;0.7560439 0.4453586 0.6283918 ]
+s = variance(x)
+s = variance(x, "r")
+s = variance(x, "c")
+
+// with complex numbers
+x = rand(4,3) + rand(4,3)*%i
+s = variance(x)
+s = variance(x, "*", 1)        // doit être inférieure à la précédente valeur
+s = variance(x, "r")
+s = variance(x, "r", 1)
+s = variance(x, "c")
+
+// with an hypermatrix
+x = rand(3,2,2)
+s = variance(x)
+s = variance(x, "*", 1)        // doit être inférieure à la précédente valeur
+// 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="mtlb_var">mtlb_var</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.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>
+            </revision>
+        </revhistory>
+    </refsection>
+    
+</refentry>
index 1417695..588c206 100644 (file)
@@ -1,80 +1,81 @@
-
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) 2000 - INRIA - Carlos Klimann
-// 
+// Copyright (C) 2013 - Samuel GOUGEON
+//
 // 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-en.txt
-// 
-
-function [s]=variance(x,orien,w)
-//
-//This function computes  the  variance  of  the values of  a  vector or
-//matrix x.
-//
-//For a vector or   a matrix x,  s=variance(x)  returns in  the scalar s  the
-//variance of all the entries of x.
-//
-//s=variance(x,'r')    (or,  equivalently,    s=variance(x,1)) is     the  rowwise
-//variance. It returns in each entry of the row vector s the variance of
-//each column of x.
 //
-//s=variance(x,'c') (or, equivalently, s=variance(x,2)) is the columnwise standard
-//deviation.   It  returns in  each  entry  of the   column vector y the
-//variance of each row of x.
-//
-//
-  if x==[] then 
-    s=%nan;
-    return;
-  end
-  [lhs,rhs]=argn(0)
-  if rhs==0 then 
-    error(msprintf(gettext("%s: Wrong number of input arguments: %d to %d expected.\n"),"variance",1,2))
-  end
-  [m n]=size(x);
-  if rhs<=2 then 
-    w=0;
-  end
-  if rhs==1
-    s = sum(abs(x - mean(x)).^2) // equivalent to var(real(x)) + var(imag(x)) for x complexes
-    if w==0 then
-      s = s / (m*n-1);
-    elseif w==1 then
-      s = s / (m*n);
+
+function [s] = variance(x, orien, w)
+    //
+    //This function computes  the  variance  of  the values of  a  vector or
+    //matrix x.
+    //
+    //For a vector or   a matrix x,  s=variance(x)  returns in  the scalar s  the
+    //variance of all the entries of x.
+    //
+    //s=variance(x,'r')    (or,  equivalently,    s=variance(x,1)) is     the  rowwise
+    //variance. It returns in each entry of the row vector s the variance of
+    //each column of x.
+    //
+    //s=variance(x,'c') (or, equivalently, s=variance(x,2)) is the columnwise standard
+    //deviation.   It  returns in  each  entry  of the   column vector y the
+    //variance of each row of x.
+    //
+    //
+
+    // Checking and normalizing input arguments:
+    // ----------------------------------------
+    [lhs,rhs] = argn(0)
+    if rhs==0 then
+        tmp = gettext("%s: Wrong number of input arguments: %d to %d expected.\n")
+        error(msprintf(tmp, "variance", 1, 2))
+    end
+
+    if x==[] then
+        s = %nan
+        return
+    end
+
+    if ~isdef("orien","local") then
+        orien = "*"
+    end
+
+    transposed = %f // to refer and process as in "r", we priorly transpose any "c" request
+    if orien=="r" | orien==1 | orien=="c" | orien==2 | orien=="*"
+        if orien=="c" | orien==2 then
+            x = x.'
+            transposed = %t
+            orien = "r"
+        end
     else
-      error(msprintf(gettext("%s: Wrong value of w : %d; 0 or 1 expected.\n"),"variance",w))
+        tmp = gettext("%s: Wrong value for input argument: ''%s'', ''%s'', %d or %d expected.\n")
+        error(msprintf(tmp, "variance", "c", "r", 1, 2))
     end
-  elseif orien=='c'|orien==2 then
-    y(1:m,1:n) = x(1:m,1:n) -  mean(x,2) * ones(1,n);
-    s = ones(m,1);
-    for i=1:m
-      s(i) = real(y(i,1:n) * y(i,1:n)');
-      if w==0 then
-        s(i) = s(i) / (n - 1);
-      elseif w==1 then
-        s(i) = s(i) / n;
-      else
-        error(msprintf(gettext("%s: Wrong value of w : %d; 0 or 1 expected.\n"),"variance",w))
-      end
+
+    if rhs<3 then
+        w = 0
+    elseif typeof(w)~="constant" | and(w~=[0 1]) then
+        tmp = gettext("%s: Wrong value of w : %s; %d or %d expected.\n")
+        error(msprintf(tmp, "variance", string(w), 0, 1))
     end
-  elseif orien=='r'|orien==1 then
-    y(1:m,1:n) = x(1:m,1:n) - ones(m,1) * mean(x,1);
-    s = ones(1,n);
-    for i=1:n
-      s(i) = real(y(1:m,i)' * y(1:m,i));
-      if w==0 then
-        s(i) = s(i) / (m - 1);
-      elseif w==1 then
-        s(i) = s(i) / m;
-      else
-        error(msprintf(gettext("%s: Wrong value of w : %d; 0 or 1 expected.\n"),"variance",w))
-      end
+
+    // Calculations
+    // ------------
+    d = size(x, orien) - 1 + w    // denominator
+    if orien=="*" then
+        m = mean(x)
+    else
+        m = mean(x, orien).*.ones(size(x,1),1)
     end
-  else
-    error(msprintf(gettext("%s: Wrong value for input argument: ''%s'', ''%s'', %d or %d expected.\n"),"variance","c","r",1,2));
-  end
+    s = sum(abs(x - m).^2, orien) / d
+
+    if transposed
+        s = s.'
+    end
+
 endfunction