Typo fixes
[scilab.git] / scilab / modules / signal_processing / help / en_US / 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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="xcorr" xml:lang="en">
15     <refnamediv>
16         <refname>xcorr</refname>
17         <refpurpose>Computes discrete auto or cross correlation</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Syntax</title>
21         <synopsis>[c [,lagindex]] = xcorr(x [,maxlags [,scaling]])
22             [c [,lagindex]] = xcorr(x,y [,maxlags [,scaling]])
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Parameters</title>
27         <variablelist>
28             <varlistentry>
29                 <term>x</term>
30                 <listitem>
31                     <para>a vector of real or complex floating point numbers.</para>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>y</term>
36                 <listitem>
37                     <para>a vector of real or complex floating point numbers. The
38                         default value is <literal>x</literal>.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>maxlags</term>
44                 <listitem>
45                     <para>a scalar with integer value greater than 1. The default value
46                         is <literal>n</literal>. Where <literal>n</literal> is the maximum
47                         of the <literal>x</literal> and <literal>y</literal> vector
48                         length.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>scaling</term>
54                 <listitem>
55                     <para>a character string with possible value:
56                         <literal>"biased"</literal>, <literal>"unbiased"</literal>,
57                         <literal>"coeff"</literal>, <literal>"none"</literal>. The default
58                         value is <literal>"none"</literal>.
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>c</term>
64                 <listitem>
65                     <para>a vector of real or complex floating point numbers with same
66                         orientation as <literal>x</literal>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>lagindex</term>
72                 <listitem>
73                     <para>a row vector, containing the lags index corresponding to the
74                         <literal>c</literal> values.
75                     </para>
76                 </listitem>
77             </varlistentry>
78         </variablelist>
79     </refsection>
80     <refsection>
81         <title>Description</title>
82         <itemizedlist>
83             <listitem>
84                 <literal>c=xcorr(x)</literal>
85                 
86                 computes the un-normalized discrete auto correlation:
87                 
88                 <latex>{\begin{matrix}C_k = \sum_{i=1}^{n-k}
89                     {x_{i+k}*x^{*}_i}, k \geq 0 \\ C_k = C^{*}_{-k}, k \leq
90                     -1\end{matrix}.$
91                 </latex>
92                 
93                 and return in
94                 
95                 <literal>c</literal>
96                 
97                 the sequence of auto correlation lags
98                 
99                 <latex>$C_k,k=-n:n$</latex>
100                 
101                 with
102                 
103                 <literal>n</literal>
104                 
105                 is the length of
106                 
107                 <literal>x</literal>
108                 
109                 
110             </listitem>
111             <listitem>
112                 <literal>xcorr(x,y)</literal>
113                 
114                 computes the un-normalized discrete cross correlation:
115                 
116                 <latex>{\begin{matrix}C_k = \sum_{i=1}^{n-k}
117                     {x_{i+k}*y^{*}_i}, k \geq 0 \\ C_k = C^{*}_{-k}, k \leq
118                     -1\end{matrix}}.$
119                 </latex>
120                 
121                 and return in
122                 
123                 <literal>c</literal>
124                 
125                 the sequence of auto correlation lags
126                 
127                 <latex>$C_k,k=-n:n$</latex>
128                 
129                 with
130                 
131                 <literal>n</literal>
132                 
133                 is the maximum of
134                 
135                 <literal>x</literal>
136                 
137                 and
138                 
139                 <literal>y</literal>
140                 
141                 length's.
142             </listitem>
143         </itemizedlist>
144         <para>
145             If the <literal>maxlags</literal> argument is given
146             <literal>xcorr</literal> returns in <literal>c</literal> the sequence of
147             auto correlation lags <latex>$C_k,k=-maxlags:maxlags$</latex>. If
148             <literal>maxlags</literal> is greater than <literal>length(x)</literal>,
149             the first and last values of <literal>c</literal> are zero.
150         </para>
151         <para>
152             The <literal>scaling</literal> argument describes how
153             <latex>C(k)</latex> is normalized before being returned in
154             <literal>c</literal>: 
155             <itemizedlist>
156                 <listitem>
157                     <term>"biased"</term>:<literal>c=</literal><latex>$C$</latex><literal>/n</literal>.
158                 </listitem>
159                 <listitem>
160                     <term>"unbiased"</term>:<literal>c=</literal><latex>$C$</latex><literal>./(n-(-maxlags:maxlags))</literal>.
161                 </listitem>
162                 <listitem>
163                     <term>"coeff"</term>:<literal>c=</literal><latex>$C$</latex><literal>/(norm(x)*norm(y))</literal>.
164                 </listitem>
165             </itemizedlist>
166         </para>
167     </refsection>
168     <refsection>
169         <title>Remark</title>
170         
171         The
172         
173         <link linkend="corr">corr</link>
174         
175         function computes the "biased" covariance of
176         
177         <literal>x</literal>
178         
179         and
180         
181         <literal>y</literal>
182         
183         and only return in
184         
185         <literal>c</literal>
186         
187         the sequence of auto correlation lags
188         
189         <latex>$C_k,k \geq 0$</latex>
190         
191         .
192     </refsection>
193     <refsection>
194         <refsection>
195             <title>Method</title> This function computes
196             <latex>$C$</latex> using
197             <literal>ifft(fft(x).*conj(fft(y)))</literal>.
198         </refsection>
199         <refsection>
200             <title>Examples</title>
201             <programlisting role="example">t = linspace(0, 100, 2000);
202                 y = 0.8 * sin(t) + 0.8 * sin(2 * t);
203                 [c, ind] = xcorr(y, "biased");
204                 plot(ind, c)
205             </programlisting>
206             <scilab:image>
207                 t = linspace(0, 100, 2000);
208                 y = 0.8 * sin(t) + 0.8 * sin(2 * t);
209                 [c, ind] = xcorr(y, "biased");
210                 plot(ind, c)    
211             </scilab:image>
212         </refsection>
213         <refsection>
214             <title>See Also</title>
215             <simplelist type="inline">
216                 <member>
217                     <link linkend="xcov">xcov</link>
218                 </member>
219                 <member>
220                     <link linkend="corr">corr</link>
221                 </member>
222                 <member>
223                     <link linkend="fft">fft</link>
224                 </member>
225             </simplelist>
226         </refsection>
227         <refsection>
228             <title>Authors</title>
229             <simplelist type="vert">
230                 <member>Serge Steer, INRIA</member>
231             </simplelist>
232         </refsection>
233         <title>Used Functions</title>
234         <para>
235             <link linkend="fft">fft</link>
236         </para>
237     </refsection>
238     <refsection>
239         <title>History</title>
240         <revhistory>
241             <revision>
242                 <revnumber>5.4.0</revnumber>
243                 <revremark>xcorr added.</revremark>
244             </revision>
245         </revhistory>
246     </refsection>
247 </refentry>