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