[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / signal_processing / help / en_US / correlation_convolution / corr.xml
index 7f2fc7e..62f21d5 100644 (file)
@@ -1,18 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<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">
+<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">
     <refnamediv>
         <refname>corr</refname>
         <refpurpose>correlation, covariance</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>[cov,Mean]=corr(x,[y],nlags)
-            [cov,Mean]=corr('fft',xmacro,[ymacro],n,sect)
-            
-            [w,xu]=corr('updt',x1,[y1],w0)
-            [w,xu]=corr('updt',x2,[y2],w,xu)
+        <synopsis>
+            [cov,Mean] = corr(x,[y],nlags)
+            [cov,Mean] = corr('fft',xmacro,[ymacro],n,sect)
+
+            [w,xu] = corr('updt',x1,[y1],w0)
+            [w,xu] = corr('updt',x2,[y2],w,xu)
             ...
-            [wk]=corr('updt',xk,[yk],w,xu)
+            wk = corr('updt',xk,[yk],w,xu)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
     <refsection>
         <title>Description</title>
         <para>
-            Computes
-        </para>
-        <programlisting role=""><![CDATA[ 
-         n - m 
-         ====
-         \                                       1
-cov(m) =  >   (x(k) - xmean) (y(m+k) - ymean) * ---
-         /                                       n
-         ====
-         k = 1
- ]]></programlisting>
-        <para>
-            for   m=0,..,<literal>nlag-1</literal> and two vectors <literal>x=[x(1),..,x(n)]</literal>
-            <literal>y=[y(1),..,y(n)]</literal>
+            <literal>corr(x,y,…)</literal> computes
+            <latex alt="cov(m)=sum_{k=1}^{n-m} (x(k)-mean(x))(y(m+k)-mean(y)) / n">
+            cov(m)=\sum_{k=1}^{n-m} \left(x(k)-mean(x)\right)\left(y(m+k)-mean(y)\right) / n
+            </latex>
+            for <literal>m = 0, …, nlag-1</literal>.
         </para>
         <para>
             Note that if x and y sequences are differents corr(x,y,...) is
@@ -116,7 +111,7 @@ cov(m) =  >   (x(k) - xmean) (y(m+k) - ymean) * ---
                         <literal>[cov,Mean]=corr(x,[y],nlags)</literal> returns the first nlags
                         correlation coefficients and Mean = <literal>mean(x)</literal>
                         (mean of <literal>[x,y]</literal> if <literal>y</literal> is an argument).
-                        The sequence <literal>x</literal> (resp. <literal>y</literal>) is assumed real, and <literal>x</literal> 
+                        The sequence <literal>x</literal> (resp. <literal>y</literal>) is assumed real, and <literal>x</literal>
                         and <literal>y</literal> are of same dimension n.
                     </para>
                 </listitem>
@@ -125,11 +120,12 @@ cov(m) =  >   (x(k) - xmean) (y(m+k) - ymean) * ---
                 <term>Long sequences</term>
                 <listitem>
                     <para>
-                        <literal>[cov,Mean]=corr('fft',xmacro,[ymacro],n,sect)</literal> Here <literal>xmacro</literal> is either
+                        <literal>[cov,Mean]=corr('fft',xmacro,[ymacro],n,sect)</literal>.
+                        Here <literal>xmacro</literal> is either
                     </para>
                     <itemizedlist>
                         <listitem>
-                            <para> 
+                            <para>
                                 a function of type <literal>[xx]=xmacro(sect,istart)</literal> which
                                 returns a vector <literal>xx</literal> of dimension
                                 <literal>nsect</literal> containing the part of the sequence with
@@ -141,20 +137,23 @@ cov(m) =  >   (x(k) - xmean) (y(m+k) - ymean) * ---
                             <para>
                                 a fortran subroutine or C procedure which performs the same
                                 calculation. (See the source code of <literal>dgetx</literal> for an
-                                example). <literal>n</literal> = total size of the
-                                sequence. <literal>sect</literal> = size of sections of the
-                                sequence. <literal>sect</literal> must be a power of
-                                2. <literal>cov</literal> has dimension
-                                <literal>sect</literal>. Calculation is performed by FFT.
+                                example).
                             </para>
                         </listitem>
                     </itemizedlist>
+                    <para>
+                          <literal>n</literal> = total size of the sequence.
+                          <literal>sect</literal> = size of sections of the sequence.
+                          <literal>sect</literal> must be a power of 2.
+                          <literal>cov</literal> has dimension <literal>sect</literal>.
+                          Calculation is performed by FFT.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>Updating method</term>
                 <listitem>
-                    <programlisting role=""><![CDATA[ 
+                    <programlisting role=""><![CDATA[
 [w,xu]=corr('updt',x1,[y1],w0)
 [w,xu]=corr('updt',x2,[y2],w,xu)
  ...
@@ -164,7 +163,7 @@ wk=corr('updt',xk,[yk],w,xu)
                         With this syntax the calculation is updated at each
                         call to <literal>corr</literal>.
                     </para>
-                    <programlisting role=""><![CDATA[ 
+                    <programlisting role=""><![CDATA[
 w0 = 0*ones(1,2*nlags);
 nlags = power of 2.
  ]]></programlisting>
@@ -182,7 +181,7 @@ nlags = power of 2.
     </refsection>
     <refsection>
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
+        <programlisting role="example"><![CDATA[
 x=%pi/10:%pi/10:102.4*%pi;
 rand('seed');rand('normal');
 y=[.8*sin(x)+.8*sin(2*x)+rand(x);.8*sin(x)+.8*sin(1.99*x)+rand(x)];
@@ -215,7 +214,7 @@ zz=real(fft(w2,1))/256;c6=zz(1:32);
 norm(c6-c2,1)
 rand('unif')
 
-// test for Fortran or C external 
+// test for Fortran or C external
 //
 deff('[y]=xmacro(sec,ist)','y=sin(ist:(ist+sec-1))');
 x=xmacro(100,1);
@@ -236,7 +235,19 @@ y=ymacro(100,1);
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="fft">fft</link>
+                <link linkend="xcorr">xcorr</link>
+            </member>
+            <member>
+                <link linkend="xcov">xcov</link>
+            </member>
+            <member>
+                <link linkend="correl">correl</link>
+            </member>
+            <member>
+                <link linkend="cov">cov</link>
+            </member>
+            <member>
+                <link linkend="covar">covar</link>
             </member>
         </simplelist>
     </refsection>