ec3a1575f58f0be4e28245f2a87e86fc56c6004a
[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')
31             y = stdev(x, 'c')
32             y = stdev(x, orien, m)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
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                         string scalar or positive integer, can be <literal>"*"</literal>, <literal>"r"</literal> (or <literal>1</literal>) or <literal>"c"</literal> (or <literal>2</literal>)
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>m</term>
60                 <listitem>
61                     <para>real scalar, vector or hypermatrix, the a priori mean</para>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65     </refsection>
66     <refsection>
67         <title>Description</title>
68         <para>
69             stdev computes the "sample" standard deviation, that
70             is, it is normalized by N-1, where N is the sequence length.
71             If <varname>m</varname> is present, then <code>stdev</code> computes the
72             mean squared deviation (normalized by N) using the a priori mean defined by <varname>m</varname>.
73         </para>
74         <para>
75             For a vector or a matrix <literal>x</literal>, <literal>y=stdev(x)</literal> returns in the
76             scalar <literal>y</literal> the standard deviation of all the entries of <literal>x</literal>.
77         </para>
78         <para>
79             <literal>y=stdev(x,'r')</literal> (or, equivalently,
80             <literal>y=stdev(x,1)</literal>) is the rowwise standard deviation. It returns in each
81             entry of the row vector <literal>y</literal> the standard deviation of each column of <literal>x</literal>.
82         </para>
83         <para>
84             <literal>y=stdev(x,'c')</literal> (or, equivalently, <literal>y=stdev(x,2)</literal>) is the columnwise stdev. It returns in each
85             entry of the column vector <literal>y</literal> the standard deviation of each row of <literal>x</literal>.
86         </para>
87         <para>
88             By extension, <literal>y=stdev(x,n)</literal> with <literal>n</literal> a positive integer returns the deviation
89             along the <literal>n</literal>-th dimension, and if <literal>n>ndims(x)</literal>, then <literal>stdev(x,n)</literal> returns <literal>zeros(x)</literal>.
90         </para>
91         <note>
92             If <varname>m</varname> is a scalar, then it is expanded to match the size of <code>mean(x)</code> along the <literal>n</literal>-th dimension.
93         </note>
94     </refsection>
95     <refsection>
96         <title>Examples</title>
97         <programlisting role="example"><![CDATA[
98 A = [1 2 10; 7 7.1 7.01];
99 stdev(A)
100 stdev(A, 'r')
101 stdev(A, 'c')
102 stdev(A, 'c', mean(A,'c'))
103 stdev(A, 'c', 1)
104  ]]></programlisting>
105     </refsection>
106     <refsection role="see also">
107         <title>See Also</title>
108         <simplelist type="inline">
109             <member>
110                 <link linkend="nanstdev">nanstdev</link>
111             </member>
112             <member>
113                 <link linkend="stdevf">stdevf</link>
114             </member>
115             <member>
116                 <link linkend="sum">sum</link>
117             </member>
118             <member>
119                 <link linkend="median">median</link>
120             </member>
121             <member>
122                 <link linkend="mean">mean</link>
123             </member>
124         </simplelist>
125     </refsection>
126     <refsection>
127         <title>History</title>
128         <revhistory>
129             <revision>
130                 <revnumber>5.5.0</revnumber>
131                 <revdescription>
132                     Can now compute the mean squared deviation using the a priori mean defined by <varname>m</varname>
133                 </revdescription>
134             </revision>
135         </revhistory>
136     </refsection>
137 </refentry>