[doc] misc. fix & improvements
[scilab.git] / scilab / modules / statistics / help / en_US / 3_dispersion_widths / 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"
19           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
20           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
21           xml:lang="en" xml:id="stdev">
22     <refnamediv>
23         <refname>stdev</refname>
24         <refpurpose>
25             standard deviation (row or column-wise) of vector/matrix entries
26         </refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29         <title>Syntax</title>
30         <synopsis>
31             y = stdev(x)
32             y = stdev(x, '*')
33             y = stdev(x, 'r'|1)
34             y = stdev(x, 'c'|2)
35             y = stdev(x, orien, m)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection role="parameters">
39         <title>Arguments</title>
40         <variablelist>
41             <varlistentry>
42                 <term>x, y</term>
43                 <listitem>
44                     <para>real vector, matrix or hypermatrix</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>y</term>
49                 <listitem>
50                     <para>real scalar, vector or matrix</para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>orien</term>
55                 <listitem>
56                     <para>
57                         <literal>"*"</literal> (default), <literal>"r"</literal> or 1,
58                         <literal>"c"</literal> or 2, or 0&lt;integer&lt;=ndims(x): direction along
59                         which calculations are performed.
60                     </para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>m</term>
65                 <listitem>
66                     <para>real scalar, vector or hypermatrix, the a priori mean</para>
67                 </listitem>
68             </varlistentry>
69         </variablelist>
70     </refsection>
71     <refsection role="description">
72         <title>Description</title>
73         <para>
74             stdev computes the "sample" standard deviation, that
75             is, it is normalized by N-1, where N is the sequence length.
76             If <varname>m</varname> is present, then <code>stdev</code> computes the
77             mean squared deviation (normalized by N) using the a priori mean defined by <varname>m</varname>.
78         </para>
79         <para>
80             For a vector or a matrix <literal>x</literal>, <literal>y=stdev(x)</literal> returns in the
81             scalar <literal>y</literal> the standard deviation of all the entries of <literal>x</literal>.
82         </para>
83         <para>
84             <literal>y=stdev(x,'r')</literal> (or, equivalently,
85             <literal>y=stdev(x,1)</literal>) is the rowwise standard deviation. It returns in each
86             entry of the row vector <literal>y</literal> the standard deviation of each column of <literal>x</literal>.
87         </para>
88         <para>
89             <literal>y=stdev(x,'c')</literal> (or, equivalently, <literal>y=stdev(x,2)</literal>)
90             is the columnwise stdev. It returns in each
91             entry of the column vector <literal>y</literal> the standard deviation of each row of
92           <literal>x</literal>.
93         </para>
94         <para>
95             By extension, <literal>y=stdev(x,n)</literal> with <literal>n</literal> a positive integer
96              returns the deviation along the <literal>n</literal>-th dimension.
97         </para>
98         <note>
99             <itemizedlist>
100                 <listitem>
101                     If <varname>m</varname> is a scalar, then it is expanded to match the size of
102                     <code>mean(x)</code> along the <literal>n</literal>-th dimension.
103                 </listitem>
104                 <listitem>
105                     <literal>stdev()</literal> can be overloaded.
106                 </listitem>
107             </itemizedlist>
108         </note>
109     </refsection>
110     <refsection role="examples">
111         <title>Examples</title>
112         <programlisting role="example"><![CDATA[
113 A = [1 2 10; 7 7.1 7.01];
114 stdev(A)
115 stdev(A, 'r')
116 stdev(A, 'c')
117 stdev(A,  2 )
118
119 // Deviation from a known (a-priori, built-in) mean:
120 A = grand(10, 10, "nor", 7.5, 3);
121 stdev(A) / 3             // unknown mean => assessed from A before computing stdev
122 stdev(A, '*', 7.5) / 3   // using the theoretical built-in mean
123
124 // With an hypermatrix:
125 A = grand(3, 5, 30, "nor", 4.1, 1.5);
126 stdev(A) / 1.5
127 sd = stdev(A, 3, 4.1) / 1.5
128 mean(sd)
129  ]]></programlisting>
130     </refsection>
131     <refsection role="see also">
132         <title>See also</title>
133         <simplelist type="inline">
134             <member>
135                 <link linkend="nanstdev">nanstdev</link>
136             </member>
137             <member>
138                 <link linkend="stdevf">stdevf</link>
139             </member>
140             <member>
141                 <link linkend="sum">sum</link>
142             </member>
143             <member>
144                 <link linkend="median">median</link>
145             </member>
146             <member>
147                 <link linkend="mean">mean</link>
148             </member>
149         </simplelist>
150     </refsection>
151     <refsection role="history">
152         <title>History</title>
153         <revhistory>
154             <revision>
155                 <revnumber>5.5.0</revnumber>
156                 <revdescription>
157                     Can now compute the mean squared deviation using the a priori mean defined by <varname>m</varname>
158                 </revdescription>
159             </revision>
160             <revision>
161                 <revnumber>6.0.0</revnumber>
162                 <revdescription>
163                     stdev(x, orien>ndims(x)) no longer returns zeros(x) but yields an error.
164                 </revdescription>
165             </revision>
166             <revision>
167                 <revnumber>6.0.1</revnumber>
168                 <revdescription>
169                     stdev() is now overloadable.
170                 </revdescription>
171             </revision>
172         </revhistory>
173     </refsection>
174 </refentry>