Typo fixes
[scilab.git] / scilab / modules / signal_processing / help / en_US / xcov.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="xcov" xml:lang="en">
15     <refnamediv>
16         <refname>xcov</refname>
17         <refpurpose>Computes discrete auto or cross covariance</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Syntax</title>
21         <synopsis>[c [,lagindex]] = xcov(x [,maxlags [,scaling]])
22             [c [,lagindex]] = xcov(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=xcov(x)</literal>
85                 
86                 computes the un-normalized discrete covariance:
87                 
88                 <latex>{\begin{matrix}C_k = \sum_{i=0}^{n-k-1}
89                     {(x_{i+k}-\mu_x})({x_i-\mu_x})^{*} , k \geq 0 
90                     \mu_x=\sum_{i=0}^{n-1}{x_i} C_k = C^{*}_{-k}, k \leq
91                     -1\end{matrix}.}$
92                 </latex>
93                 
94                 and return in
95                 
96                 <literal>c</literal>
97                 
98                 the sequence of covariance lags
99                 
100                 <latex>$C_k,k=-n:n$</latex>
101                 
102                 with
103                 
104                 <literal>n</literal>
105                 
106                 is the length of
107                 
108                 <literal>x</literal>
109                 
110                 
111             </listitem>
112             <listitem>
113                 <literal>xcov(x,y)</literal>
114                 
115                 computes the un-normalized discrete cross covariance:
116                 
117                 <latex>${\begin{matrix}C_k = \sum_{i=1}^{n-k}
118                     {(x_{i+k}-\mu_x})*({y_i}-\mu_y)^{*}, k \geq 0
119                     \mu_x=\sum_{i=0}^{n-1}{x_i} \mu_y=\sum_{i=0}^{n-1}{y_i} C_k =
120                     C^{*}_{-k}, k \leq -1\end{matrix}.}$
121                 </latex>
122                 
123                 and return in
124                 
125                 <literal>c</literal>
126                 
127                 the sequence of cross covariance lags
128                 
129                 <latex>$C_k,k=-n:n$</latex>
130                 
131                 with
132                 
133                 <literal>n</literal>
134                 
135                 is the maximum of
136                 
137                 <literal>x</literal>
138                 
139                 and
140                 
141                 <literal>y</literal>
142                 
143                 length's.
144             </listitem>
145         </itemizedlist>
146         <para>
147             If the <literal>maxlags</literal> argument is given
148             <literal>xcov</literal> returns in <literal>c</literal> the sequence of
149             covariance lags <latex>$C_k,k=-maxlags:maxlags$</latex>. If
150             <literal>maxlags</literal> is greater than <literal>length(x)</literal>,
151             the first and last values of <literal>c</literal> are zero.
152         </para>
153         <para>
154             The <literal>scaling</literal> argument describes how
155             <latex>C(k)</latex> is normalized before being returned in
156             <literal>c</literal>: 
157             <itemizedlist>
158                 <listitem>
159                     <term>"biased"</term>:<literal>c=</literal><latex>$C$</latex><literal>/n</literal>.
160                 </listitem>
161                 <listitem>
162                     <term>"unbiased"</term>:<literal>c=</literal><latex>$C$</latex><literal>./(n-(-maxlags:maxlags))</literal>.
163                 </listitem>
164                 <listitem>
165                     <term>"coeff"</term>:<literal>c=</literal><latex>$C$</latex><literal>/(norm(x)*norm(y))</literal>.
166                 </listitem>
167             </itemizedlist>
168         </para>
169     </refsection>
170     <refsection>
171         <title>Remark</title>
172         
173         The
174         
175         <link linkend="corr">corr</link>
176         
177         function computes the "biased" covariance of
178         
179         <literal>x</literal>
180         
181         and
182         
183         <literal>y</literal>
184         
185         and only return in
186         
187         <literal>c</literal>
188         
189         the sequence of covariance lags
190         
191         <latex>$C_k,k \geq 0$</latex>
192         
193         .
194     </refsection>
195     <refsection>
196         <refsection>
197             <title>Method</title> This function computes
198             <latex>$C$</latex> using
199             <literal>xcorr(x-mean(x),y-mean(y),...)</literal>.
200         </refsection>
201         <refsection>
202             <title>Examples</title>
203             <programlisting role="example">t = linspace(0, 100, 2000);
204                 y = 0.8 * sin(t) + 0.8 * sin(2 * t);
205                 [c, ind] = xcov(y, "biased");
206                 plot(ind, c)
207             </programlisting>
208             <scilab:image>
209                 t = linspace(0, 100, 2000);
210                 y = 0.8 * sin(t) + 0.8 * sin(2 * t);
211                 [c, ind] = xcov(y, "biased");
212                 plot(ind, c)
213             </scilab:image>
214         </refsection>
215         <refsection>
216             <title>See Also</title>
217             <simplelist type="inline">
218                 <member>
219                     <link linkend="xcorr">xcorr</link>
220                 </member>
221                 <member>
222                     <link linkend="corr">corr</link>
223                 </member>
224                 <member>
225                     <link linkend="fft">fft</link>
226                 </member>
227             </simplelist>
228         </refsection>
229         <refsection>
230             <title>Authors</title>
231             <simplelist type="vert">
232                 <member>Serge Steer, INRIA</member>
233             </simplelist>
234         </refsection>
235         <title>Used Functions</title>
236         <para>
237             <link linkend="xcorr">xcorr</link>
238         </para>
239     </refsection>
240     <refsection>
241         <title>History</title>
242         <revhistory>
243             <revision>
244                 <revnumber>5.4.0</revnumber>
245                 <revremark>xcov added.</revremark>
246             </revision>
247         </revhistory>
248     </refsection>
249 </refentry>