<?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>
<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>
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">
<member>
<link linkend="mtlb_var">mtlb_var</link>
</member>
+ <member>
+ <link linkend="stdev">stdev</link>
+ </member>
</simplelist>
</refsection>
<refsection>
<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>
<?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>
[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">
<member>
<link linkend="mtlb_var">mtlb_var</link>
</member>
+ <member>
+ <link linkend="stdevf">stdevf</link>
+ </member>
</simplelist>
</refsection>
<refsection>
<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>
<?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>
<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>
<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>
--- /dev/null
+<?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. & Wonacott, R.J.; Introductory Statistics, fifth edition, J.Wiley & 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>
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
-
-// 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
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 );
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]);
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);
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
[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
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]);
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]);
projects / scilab.git / commitdiff