[doc] misc. fix & improvements
[scilab.git] / 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>