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