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>