[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / signal_processing / help / en_US / correlation_convolution / corr.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
3           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
4           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
5           xml:lang="en" xml:id="corr">
6     <refnamediv>
7         <refname>corr</refname>
8         <refpurpose>correlation, covariance</refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Syntax</title>
12         <synopsis>
13             [cov,Mean] = corr(x,[y],nlags)
14             [cov,Mean] = corr('fft',xmacro,[ymacro],n,sect)
15
16             [w,xu] = corr('updt',x1,[y1],w0)
17             [w,xu] = corr('updt',x2,[y2],w,xu)
18             ...
19             wk = corr('updt',xk,[yk],w,xu)
20         </synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>x</term>
27                 <listitem>
28                     <para>a real vector</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>y</term>
33                 <listitem>
34                     <para>a real vector, default value x.</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>nlags</term>
39                 <listitem>
40                     <para>integer, number of correlation coefficients desired.</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>xmacro</term>
45                 <listitem>
46                     <para>a scilab external (see below).</para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>ymacro</term>
51                 <listitem>
52                     <para>a scilab external (see below), default value xmacro</para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>n</term>
57                 <listitem>
58                     <para>an integer, total size of the sequence (see below).</para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>sect</term>
63                 <listitem>
64                     <para>size of sections of the sequence (see below).</para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>xi</term>
69                 <listitem>
70                     <para>a real vector</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>yi</term>
75                 <listitem>
76                     <para>a real vector,default value xi.</para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>cov</term>
81                 <listitem>
82                     <para>real vector, the correlation coefficients</para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>Mean</term>
87                 <listitem>
88                     <para>real number or vector,  the mean of x and if given y</para>
89                 </listitem>
90             </varlistentry>
91         </variablelist>
92     </refsection>
93     <refsection>
94         <title>Description</title>
95         <para>
96             <literal>corr(x,y,…)</literal> computes
97             <latex alt="cov(m)=sum_{k=1}^{n-m} (x(k)-mean(x))(y(m+k)-mean(y)) / n">
98             cov(m)=\sum_{k=1}^{n-m} \left(x(k)-mean(x)\right)\left(y(m+k)-mean(y)\right) / n
99             </latex>
100             for <literal>m = 0, …, nlag-1</literal>.
101         </para>
102         <para>
103             Note that if x and y sequences are differents corr(x,y,...) is
104             different with corr(y,x,...)
105         </para>
106         <variablelist>
107             <varlistentry>
108                 <term>Short sequences</term>
109                 <listitem>
110                     <para>
111                         <literal>[cov,Mean]=corr(x,[y],nlags)</literal> returns the first nlags
112                         correlation coefficients and Mean = <literal>mean(x)</literal>
113                         (mean of <literal>[x,y]</literal> if <literal>y</literal> is an argument).
114                         The sequence <literal>x</literal> (resp. <literal>y</literal>) is assumed real, and <literal>x</literal>
115                         and <literal>y</literal> are of same dimension n.
116                     </para>
117                 </listitem>
118             </varlistentry>
119             <varlistentry>
120                 <term>Long sequences</term>
121                 <listitem>
122                     <para>
123                         <literal>[cov,Mean]=corr('fft',xmacro,[ymacro],n,sect)</literal>.
124                         Here <literal>xmacro</literal> is either
125                     </para>
126                     <itemizedlist>
127                         <listitem>
128                             <para>
129                                 a function of type <literal>[xx]=xmacro(sect,istart)</literal> which
130                                 returns a vector <literal>xx</literal> of dimension
131                                 <literal>nsect</literal> containing the part of the sequence with
132                                 indices from <literal>istart</literal> to
133                                 <literal>istart+sect-1</literal>.
134                             </para>
135                         </listitem>
136                         <listitem>
137                             <para>
138                                 a fortran subroutine or C procedure which performs the same
139                                 calculation. (See the source code of <literal>dgetx</literal> for an
140                                 example).
141                             </para>
142                         </listitem>
143                     </itemizedlist>
144                     <para>
145                           <literal>n</literal> = total size of the sequence.
146                           <literal>sect</literal> = size of sections of the sequence.
147                           <literal>sect</literal> must be a power of 2.
148                           <literal>cov</literal> has dimension <literal>sect</literal>.
149                           Calculation is performed by FFT.
150                     </para>
151                 </listitem>
152             </varlistentry>
153             <varlistentry>
154                 <term>Updating method</term>
155                 <listitem>
156                     <programlisting role=""><![CDATA[
157 [w,xu]=corr('updt',x1,[y1],w0)
158 [w,xu]=corr('updt',x2,[y2],w,xu)
159  ...
160 wk=corr('updt',xk,[yk],w,xu)
161  ]]></programlisting>
162                     <para>
163                         With this syntax the calculation is updated at each
164                         call to <literal>corr</literal>.
165                     </para>
166                     <programlisting role=""><![CDATA[
167 w0 = 0*ones(1,2*nlags);
168 nlags = power of 2.
169  ]]></programlisting>
170                     <para>
171                         <literal>x1,x2,...</literal> are parts of <literal>x</literal> such that
172                         <literal>x=[x1,x2,...]</literal> and sizes of <literal>xi</literal> a power of
173                         2.  To get <literal>nlags</literal> coefficients a final fft must be
174                         performed <literal>c=fft(w,1)/n</literal>; <literal>cov=c(1nlags)</literal>
175                         (<literal>n</literal> is the size of <literal>x (y)</literal>).  Caution: this
176                         syntax assumes that <literal>xmean = ymean = 0</literal>.
177                     </para>
178                 </listitem>
179             </varlistentry>
180         </variablelist>
181     </refsection>
182     <refsection>
183         <title>Examples</title>
184         <programlisting role="example"><![CDATA[
185 x=%pi/10:%pi/10:102.4*%pi;
186 rand('seed');rand('normal');
187 y=[.8*sin(x)+.8*sin(2*x)+rand(x);.8*sin(x)+.8*sin(1.99*x)+rand(x)];
188 c=[];
189 for j=1:2,for k=1:2,c=[c;corr(y(k,:),y(j,:),64)];end;end;
190 c=matrix(c,2,128);cov=[];
191 for j=1:64,cov=[cov;c(:,(j-1)*2+1:2*j)];end;
192 rand('unif')
193
194 rand('normal');x=rand(1,256);y=-x;
195 deff('[z]=xx(inc,is)','z=x(is:is+inc-1)');
196 deff('[z]=yy(inc,is)','z=y(is:is+inc-1)');
197 [c,mxy]=corr(x,y,32);
198 x=x-mxy(1)*ones(x);y=y-mxy(2)*ones(y);  //centring
199 c1=corr(x,y,32);c2=corr(x,32);
200 norm(c1+c2,1)
201 [c3,m3]=corr('fft',xx,yy,256,32);
202 norm(c1-c3,1)
203 [c4,m4]=corr('fft',xx,256,32);
204 norm(m3,1),norm(m4,1)
205 norm(c3-c1,1),norm(c4-c2,1)
206 x1=x(1:128);x2=x(129:256);
207 y1=y(1:128);y2=y(129:256);
208 w0=0*ones(1:64);   //32 coeffs
209 [w1,xu]=corr('u',x1,y1,w0);w2=corr('u',x2,y2,w1,xu);
210 zz=real(fft(w2,1))/256;c5=zz(1:32);
211 norm(c5-c1,1)
212 [w1,xu]=corr('u',x1,w0);w2=corr('u',x2,w1,xu);
213 zz=real(fft(w2,1))/256;c6=zz(1:32);
214 norm(c6-c2,1)
215 rand('unif')
216
217 // test for Fortran or C external
218 //
219 deff('[y]=xmacro(sec,ist)','y=sin(ist:(ist+sec-1))');
220 x=xmacro(100,1);
221 [cc1,mm1]=corr(x,2^3);
222 [cc,mm]=corr('fft',xmacro,100,2^3);
223 [cc2,mm2]=corr('fft','corexx',100,2^3);
224 [max(abs(cc-cc1)),max(abs(mm-mm1)),max(abs(cc-cc2)),max(abs(mm-mm2))]
225
226 deff('[y]=ymacro(sec,ist)','y=cos(ist:(ist+sec-1))');
227 y=ymacro(100,1);
228 [cc1,mm1]=corr(x,y,2^3);
229 [cc,mm]=corr('fft',xmacro,ymacro,100,2^3);
230 [cc2,mm2]=corr('fft','corexx','corexy',100,2^3);
231 [max(abs(cc-cc1)),max(abs(mm-mm1)),max(abs(cc-cc2)),max(abs(mm-mm2))]
232  ]]></programlisting>
233     </refsection>
234     <refsection role="see also">
235         <title>See also</title>
236         <simplelist type="inline">
237             <member>
238                 <link linkend="xcorr">xcorr</link>
239             </member>
240             <member>
241                 <link linkend="xcov">xcov</link>
242             </member>
243             <member>
244                 <link linkend="correl">correl</link>
245             </member>
246             <member>
247                 <link linkend="cov">cov</link>
248             </member>
249             <member>
250                 <link linkend="covar">covar</link>
251             </member>
252         </simplelist>
253     </refsection>
254 </refentry>