[statistics] corrected %hm_stdev to fix all tests in statistics
[scilab.git] / scilab / modules / statistics / help / en_US / descriptive_statistics / stdev.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier: added mean squared deviation
5  *                                                         (third input argument)
6  * Copyright (C) 2000 - INRIA -
7  *
8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
9  *
10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
12  * This file was originally licensed under the terms of the CeCILL v2.1,
13  * and continues to be available under such terms.
14  * For more information, see the COPYING file which you should have received
15  * along with this program.
16  *
17  -->
18 <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="stdev">
19     <refnamediv>
20         <refname>stdev</refname>
21         <refpurpose>
22             standard deviation (row orcolumn-wise) of vector/matrix entries
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             y = stdev(x)
29             y = stdev(x, '*')
30             y = stdev(x, 'r'|1)
31             y = stdev(x, 'c'|2)
32             y = stdev(x, orien, m)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection role="parameters">
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>x, y</term>
40                 <listitem>
41                     <para>real vector, matrix or hypermatrix</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>y</term>
46                 <listitem>
47                     <para>real scalar, vector or matrix</para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>orien</term>
52                 <listitem>
53                     <para>
54                         <literal>"*"</literal> (default), <literal>"r"</literal> or 1,
55                         <literal>"c"</literal> or 2, or 0&lt;integer&lt;=ndims(x): direction along
56                         which calculations are performed.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>m</term>
62                 <listitem>
63                     <para>real scalar, vector or hypermatrix, the a priori mean</para>
64                 </listitem>
65             </varlistentry>
66         </variablelist>
67     </refsection>
68     <refsection role="description">
69         <title>Description</title>
70         <para>
71             stdev computes the "sample" standard deviation, that
72             is, it is normalized by N-1, where N is the sequence length.
73             If <varname>m</varname> is present, then <code>stdev</code> computes the
74             mean squared deviation (normalized by N) using the a priori mean defined by <varname>m</varname>.
75         </para>
76         <para>
77             For a vector or a matrix <literal>x</literal>, <literal>y=stdev(x)</literal> returns in the
78             scalar <literal>y</literal> the standard deviation of all the entries of <literal>x</literal>.
79         </para>
80         <para>
81             <literal>y=stdev(x,'r')</literal> (or, equivalently,
82             <literal>y=stdev(x,1)</literal>) is the rowwise standard deviation. It returns in each
83             entry of the row vector <literal>y</literal> the standard deviation of each column of <literal>x</literal>.
84         </para>
85         <para>
86             <literal>y=stdev(x,'c')</literal> (or, equivalently, <literal>y=stdev(x,2)</literal>)
87             is the columnwise stdev. It returns in each
88             entry of the column vector <literal>y</literal> the standard deviation of each row of
89           <literal>x</literal>.
90         </para>
91         <para>
92             By extension, <literal>y=stdev(x,n)</literal> with <literal>n</literal> a positive integer
93              returns the deviation along the <literal>n</literal>-th dimension.
94         </para>
95         <note>
96             If <varname>m</varname> is a scalar, then it is expanded to match the size of
97           <code>mean(x)</code> along the <literal>n</literal>-th dimension.
98         </note>
99     </refsection>
100     <refsection role="examples">
101         <title>Examples</title>
102         <programlisting role="example"><![CDATA[
103 A = [1 2 10; 7 7.1 7.01];
104 stdev(A)
105 stdev(A, 'r')
106 stdev(A, 'c')
107 stdev(A,  2 )
108
109 // Deviation from a known (a-priori, built-in) mean:
110 A = grand(10, 10, "nor", 7.5, 3);
111 stdev(A) / 3             // unknown mean => assessed from A before computing stdev
112 stdev(A, '*', 7.5) / 3   // using the theoretical built-in mean
113
114 // With an hypermatrix:
115 A = grand(3, 5, 30, "nor", 4.1, 1.5);
116 stdev(A) / 1.5
117 sd = stdev(A, 3, 4.1) / 1.5
118 mean(sd)
119  ]]></programlisting>
120     </refsection>
121     <refsection role="see also">
122         <title>See Also</title>
123         <simplelist type="inline">
124             <member>
125                 <link linkend="nanstdev">nanstdev</link>
126             </member>
127             <member>
128                 <link linkend="stdevf">stdevf</link>
129             </member>
130             <member>
131                 <link linkend="sum">sum</link>
132             </member>
133             <member>
134                 <link linkend="median">median</link>
135             </member>
136             <member>
137                 <link linkend="mean">mean</link>
138             </member>
139         </simplelist>
140     </refsection>
141     <refsection role="history">
142         <title>History</title>
143         <revhistory>
144             <revision>
145                 <revnumber>5.5.0</revnumber>
146                 <revdescription>
147                     Can now compute the mean squared deviation using the a priori mean defined by <varname>m</varname>
148                 </revdescription>
149             </revision>
150             <revision>
151                 <revnumber>6.0</revnumber>
152                 <revdescription>
153                     stdev(x, orien>ndims(x)) no longer returns zeros(x) but yields an error.
154                 </revdescription>
155             </revision>
156         </revhistory>
157     </refsection>
158 </refentry>