scilab/modules/signal_processing/help/en_US/correlation_convolution/xcorr.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3 This file is part Scilab
   4 Copyright (C) 2012 - INRIA - Serge Steer
   5 Copyright (C) 2012 - 2016 - Scilab Enterprises
   6
   7 This file is hereby licensed under the terms of the GNU GPL v2.0,
   8 pursuant to article 5.3.4 of the CeCILL v.2.1.
   9 This file was originally licensed under the terms of the CeCILL v2.1,
  10 and continues to be available under such terms.
  11 For more information, see the COPYING file which you should have received
  12 along with this program.
  13 -->
  14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  15           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
  16           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  17           xmlns:scilab="http://www.scilab.org" xml:id="xcorr" xml:lang="en">
  18     <refnamediv>
  19         <refname>xcorr</refname>
  20         <refpurpose>Computes discrete auto or cross correlation</refpurpose>
  21     </refnamediv>
  22     <refsynopsisdiv>
  23         <title>Syntax</title>
  24         <synopsis>
  25           [c, lagindex] = xcorr(x)
  26           [c, lagindex] = xcorr(x, y)
  27           [c, lagindex] = xcorr(.., maxlags)
  28           [c, lagindex] = xcorr(.., maxlags, scaling)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Parameters</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>x</term>
  36                 <listitem>
  37                     <para>a vector of real or complex floating point numbers.</para>
  38                 </listitem>
  39             </varlistentry>
  40             <varlistentry>
  41                 <term>y</term>
  42                 <listitem>
  43                     <para>a vector of real or complex floating point numbers. The
  44                         default value is <literal>x</literal>.
  45                     </para>
  46                 </listitem>
  47             </varlistentry>
  48             <varlistentry>
  49                 <term>maxlags</term>
  50                 <listitem>
  51                     <para>a scalar with integer value greater than 1. The default value
  52                         is <literal>n</literal>. Where <literal>n</literal> is the maximum
  53                         of the <literal>x</literal> and <literal>y</literal> vector
  54                         length.
  55                     </para>
  56                 </listitem>
  57             </varlistentry>
  58             <varlistentry>
  59                 <term>scaling</term>
  60                 <listitem>
  61                     <para>a character string with possible value:
  62                         <literal>"biased"</literal>, <literal>"unbiased"</literal>,
  63                         <literal>"coeff"</literal>, <literal>"none"</literal>. The default
  64                         value is <literal>"none"</literal>.
  65                     </para>
  66                 </listitem>
  67             </varlistentry>
  68             <varlistentry>
  69                 <term>c</term>
  70                 <listitem>
  71                     <para>a vector of real or complex floating point numbers with same
  72                         orientation as <literal>x</literal>.
  73                     </para>
  74                 </listitem>
  75             </varlistentry>
  76             <varlistentry>
  77                 <term>lagindex</term>
  78                 <listitem>
  79                     <para>a row vector, containing the lags index corresponding to the
  80                         <literal>c</literal> values.
  81                     </para>
  82                 </listitem>
  83             </varlistentry>
  84         </variablelist>
  85     </refsection>
  86     <refsection>
  87         <title>Description</title>
  88         <itemizedlist>
  89             <listitem>
  90                 <literal>c=xcorr(x)</literal>
  91
  92                 computes the un-normalized discrete auto correlation:
  93                 <para>
  94                   <latex>{\begin{matrix}C_k = \sum_{i=1}^{n-k}
  95                       {x_{i+k}*x^{*}_i}, k \geq 0 \\ C_k = C^{*}_{-k}, k \leq
  96                       -1\end{matrix}.$
  97                   </latex>
  98                 </para>
  99                 and return in <literal>c</literal> the sequence of auto correlation lags
 100                 C<subscript>k=-n:n</subscript>
 101                 where <literal>n</literal> is the length of <literal>x</literal>
 102             </listitem>
 103             <listitem>
 104                 <literal>xcorr(x,y)</literal>
 105
 106                 computes the un-normalized discrete cross correlation:
 107                 <para>
 108                   <latex>{\begin{matrix}C_k = \sum_{i=1}^{n-k}
 109                       {x_{i+k}*y^{*}_i}, k \geq 0 \\ C_k = C^{*}_{-k}, k \leq
 110                       -1\end{matrix}}.$
 111                   </latex>
 112                 </para>
 113                 and return in  <literal>c</literal> the sequence of auto correlation lags
 114                 C<subscript>k=-n:n</subscript>
 115                 where <literal>n</literal> is the maximum of <literal>x</literal> and
 116                 <literal>y</literal> lengths.
 117             </listitem>
 118         </itemizedlist>
 119         <para>
 120             If the <literal>maxlags</literal> argument is given
 121             <literal>xcorr</literal> returns in <literal>c</literal> the sequence of
 122             auto correlation lags C<subscript>k=-maxlags:maxlags</subscript>. If
 123             <literal>maxlags</literal> is greater than <literal>length(x)</literal>,
 124             the first and last values of <literal>c</literal> are zero.
 125         </para>
 126         <para>
 127             The <literal>scaling</literal> argument describes how
 128             <emphasis>C(k)</emphasis> is normalized before being returned in
 129             <literal>c</literal>:
 130             <itemizedlist>
 131                 <listitem>
 132                     <term>"biased"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>/n</literal>.
 133                 </listitem>
 134                 <listitem>
 135                     <term>"unbiased"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>./(n-(-maxlags:maxlags))</literal>.
 136                 </listitem>
 137                 <listitem>
 138                     <term>"coeff"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>/(norm(x)*norm(y))</literal>.
 139                 </listitem>
 140             </itemizedlist>
 141         </para>
 142       <para>
 143         <note>
 144           <para>
 145             The <link linkend="corr">corr</link> function computes the "biased" covariance of
 146             <literal>x</literal> and <literal>y</literal> and only return in <literal>c</literal>
 147             the sequence of auto correlation lags C<subscript>k≥0</subscript>.
 148           </para>
 149           <para>
 150             Method: This function computes <emphasis>C</emphasis> using
 151             <literal>ifft(fft(x).*conj(fft(y)))</literal>.
 152           </para>
 153         </note>
 154       </para>
 155     </refsection>
 156     <refsection>
 157           <title>Examples</title>
 158           <programlisting role="example">t = linspace(0, 100, 2000);
 159             y = 0.8 * sin(t) + 0.8 * sin(2 * t);
 160             [c, ind] = xcorr(y, "biased");
 161             plot(ind, c)
 162           </programlisting>
 163           <scilab:image>
 164             t = linspace(0, 100, 2000);
 165             y = 0.8 * sin(t) + 0.8 * sin(2 * t);
 166             [c, ind] = xcorr(y, "biased");
 167             plot(ind, c)
 168           </scilab:image>
 169       </refsection>
 170       <refsection role="see also">
 171           <title>See also</title>
 172           <simplelist type="inline">
 173             <member>
 174               <link linkend="xcov">xcov</link>
 175             </member>
 176             <member>
 177               <link linkend="corr">corr</link>
 178             </member>
 179             <member>
 180               <link linkend="fft">fft</link>
 181             </member>
 182           </simplelist>
 183       </refsection>
 184       <refsection>
 185         <title>History</title>
 186         <revhistory>
 187             <revision>
 188                 <revnumber>5.4.0</revnumber>
 189                 <revremark>xcorr added.</revremark>
 190             </revision>
 191         </revhistory>
 192       </refsection>
 193 </refentry>