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>