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>