8d7edcc01119c237367453e240e05ae7ca4ac5d9
[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" 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             <itemizedlist>
97                 <listitem>
98                     If <varname>m</varname> is a scalar, then it is expanded to match the size of
99                     <code>mean(x)</code> along the <literal>n</literal>-th dimension.
100                 </listitem>
101                 <listitem>
102                     <literal>stdev()</literal> can be overloaded.
103                 </listitem>
104             </itemizedlist>
105         </note>
106     </refsection>
107     <refsection role="examples">
108         <title>Examples</title>
109         <programlisting role="example"><![CDATA[
110 A = [1 2 10; 7 7.1 7.01];
111 stdev(A)
112 stdev(A, 'r')
113 stdev(A, 'c')
114 stdev(A,  2 )
115
116 // Deviation from a known (a-priori, built-in) mean:
117 A = grand(10, 10, "nor", 7.5, 3);
118 stdev(A) / 3             // unknown mean => assessed from A before computing stdev
119 stdev(A, '*', 7.5) / 3   // using the theoretical built-in mean
120
121 // With an hypermatrix:
122 A = grand(3, 5, 30, "nor", 4.1, 1.5);
123 stdev(A) / 1.5
124 sd = stdev(A, 3, 4.1) / 1.5
125 mean(sd)
126  ]]></programlisting>
127     </refsection>
128     <refsection role="see also">
129         <title>See also</title>
130         <simplelist type="inline">
131             <member>
132                 <link linkend="nanstdev">nanstdev</link>
133             </member>
134             <member>
135                 <link linkend="stdevf">stdevf</link>
136             </member>
137             <member>
138                 <link linkend="sum">sum</link>
139             </member>
140             <member>
141                 <link linkend="median">median</link>
142             </member>
143             <member>
144                 <link linkend="mean">mean</link>
145             </member>
146         </simplelist>
147     </refsection>
148     <refsection role="history">
149         <title>History</title>
150         <revhistory>
151             <revision>
152                 <revnumber>5.5.0</revnumber>
153                 <revdescription>
154                     Can now compute the mean squared deviation using the a priori mean defined by <varname>m</varname>
155                 </revdescription>
156             </revision>
157             <revision>
158                 <revnumber>6.0.0</revnumber>
159                 <revdescription>
160                     stdev(x, orien>ndims(x)) no longer returns zeros(x) but yields an error.
161                 </revdescription>
162             </revision>
163             <revision>
164                 <revnumber>6.0.1</revnumber>
165                 <revdescription>
166                     stdev() is now overloadable.
167                 </revdescription>
168             </revision>
169         </revhistory>
170     </refsection>
171 </refentry>