[doc] misc. fix & improvements
[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>
22           [c, lagindex] = xcov(x)
23           [c, lagindex] = xcov(x, y)
24           [c, lagindex] = xcov(.., maxlags)
25           [c, lagindex] = xcov(.., maxlags, scaling)
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Parameters</title>
30         <variablelist>
31             <varlistentry>
32                 <term>x</term>
33                 <listitem>
34                     <para>a vector of real or complex floating point numbers.</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>y</term>
39                 <listitem>
40                     <para>a vector of real or complex floating point numbers. The
41                         default value is <literal>x</literal>.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>maxlags</term>
47                 <listitem>
48                     <para>a scalar with integer value greater than 1. The default value
49                         is <literal>n</literal>. Where <literal>n</literal> is the maximum
50                         of the <literal>x</literal> and <literal>y</literal> vector
51                         length.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>scaling</term>
57                 <listitem>
58                     <para>a character string with possible value:
59                         <literal>"biased"</literal>, <literal>"unbiased"</literal>,
60                         <literal>"coeff"</literal>, <literal>"none"</literal>. The default
61                         value is <literal>"none"</literal>.
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>c</term>
67                 <listitem>
68                     <para>a vector of real or complex floating point numbers with same
69                         orientation as <literal>x</literal>.
70                     </para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>lagindex</term>
75                 <listitem>
76                     <para>a row vector, containing the lags index corresponding to the
77                         <literal>c</literal> values.
78                     </para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83     <refsection>
84         <title>Description</title>
85         <itemizedlist>
86             <listitem>
87                 <literal>c=xcov(x)</literal>
88
89                 computes the un-normalized discrete covariance:
90                 <para>
91                   <latex>{\begin{matrix}C_k = \sum_{i=0}^{n-k-1}
92                       {(x_{i+k}-\mu_x})({x_i-\mu_x})^{*} , k \geq 0
93                       \mu_x=\sum_{i=0}^{n-1}{x_i} C_k = C^{*}_{-k}, k \leq
94                       -1\end{matrix}.}$
95                   </latex>
96                 </para>
97                 and return in
98                 <literal>c</literal>
99                 the sequence of covariance lags C<subscript>k=-n:n</subscript> where
100                 <literal>n</literal> is the length of <literal>x</literal>
101             </listitem>
102             <listitem>
103                 <literal>xcov(x,y)</literal>
104                 computes the un-normalized discrete cross covariance:
105                 <para>
106                   <latex>${\begin{matrix}C_k = \sum_{i=1}^{n-k}
107                       {(x_{i+k}-\mu_x})*({y_i}-\mu_y)^{*}, k \geq 0
108                       \mu_x=\sum_{i=0}^{n-1}{x_i} \mu_y=\sum_{i=0}^{n-1}{y_i} C_k =
109                       C^{*}_{-k}, k \leq -1\end{matrix}.}$
110                   </latex>
111                 </para>
112                 and return in <literal>c</literal> the sequence of cross covariance lags
113                 C<subscript>k=-n:n</subscript> where <literal>n</literal> is the maximum of
114                 <literal>x</literal> and <literal>y</literal> length's.
115             </listitem>
116         </itemizedlist>
117         <para>
118             If the <literal>maxlags</literal> argument is given
119             <literal>xcov</literal> returns in <literal>c</literal> the sequence of
120             covariance lags C<subscript>k=-maxlags:maxlags</subscript>. If
121             <literal>maxlags</literal> is greater than <literal>length(x)</literal>,
122             the first and last values of <literal>c</literal> are zero.
123         </para>
124         <para>
125             The <literal>scaling</literal> argument describes how
126             <emphasis>C(k)</emphasis> is normalized before being returned in
127             <literal>c</literal>:
128             <itemizedlist>
129                 <listitem>
130                     <term>"biased"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>/n</literal>.
131                 </listitem>
132                 <listitem>
133                     <term>"unbiased"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>./(n-(-maxlags:maxlags))</literal>.
134                 </listitem>
135                 <listitem>
136                     <term>"coeff"</term>: <literal>c=</literal><emphasis>C</emphasis><literal>/(norm(x)*norm(y))</literal>.
137                 </listitem>
138             </itemizedlist>
139         </para>
140     </refsection>
141     <refsection>
142         <title>Remark</title>
143         The <link linkend="corr">corr</link> function computes the "biased" covariance of
144         <literal>x</literal>  and <literal>y</literal> and only return in <literal>c</literal>
145          the sequence of covariance lags C<subscript>k≥0</subscript>
146         .
147       </refsection>
148       <refsection>
149         <title>Method</title>
150         This function computes <emphasis>C</emphasis> using
151         <literal>xcorr(x-mean(x),y-mean(y),...)</literal>.
152       </refsection>
153       <refsection>
154         <title>Examples</title>
155         <programlisting role="example">t = linspace(0, 100, 2000);
156           y = 0.8 * sin(t) + 0.8 * sin(2 * t);
157           [c, ind] = xcov(y, "biased");
158           plot(ind, c)
159         </programlisting>
160         <scilab:image>
161           t = linspace(0, 100, 2000);
162           y = 0.8 * sin(t) + 0.8 * sin(2 * t);
163           [c, ind] = xcov(y, "biased");
164           plot(ind, c)
165         </scilab:image>
166       </refsection>
167       <refsection role="see also">
168         <title>See also</title>
169         <simplelist type="inline">
170           <member>
171             <link linkend="xcorr">xcorr</link>
172           </member>
173           <member>
174             <link linkend="corr">corr</link>
175           </member>
176           <member>
177             <link linkend="fft">fft</link>
178           </member>
179         </simplelist>
180     </refsection>
181     <refsection>
182         <title>History</title>
183         <revhistory>
184             <revision>
185                 <revnumber>5.4.0</revnumber>
186                 <revremark>xcov added.</revremark>
187             </revision>
188         </revhistory>
189     </refsection>
190 </refentry>