[doc] misc. fix & improvements
[scilab.git] / scilab / modules / signal_processing / help / en_US / detrend.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="detrend">
3     <refnamediv>
4         <refname>detrend</refname>
5         <refpurpose>remove constant, linear or piecewise linear trend from a vector</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>y = detrend(x)
10             y = detrend(x,flag)
11             y = detrend(x,flag,bp)
12         </synopsis>
13     </refsynopsisdiv>
14     <refsection>
15         <title>Arguments</title>
16         <variablelist>
17             <varlistentry>
18                 <term>x</term>
19                 <listitem>
20                     <para>vector or matrix of real or complex numbers (the signal to treat)
21                     </para>
22                 </listitem>
23             </varlistentry>
24             <varlistentry>
25                 <term>flag</term>
26                 <listitem>
27                     <para>a string equal to "linear" (or "l") for linear or piecewise linear treatment
28                         or "constant" (or "c") for constant treatment.
29                     </para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>bp</term>
34                 <listitem>
35                     <para>the breakpoints to provide if you want a piecewise linear treatment.
36                     </para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>y</term>
41                 <listitem>
42                     <para>output, the signal x with the trend removed from it.
43                     </para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47     </refsection>
48     <refsection>
49         <title>Description</title>
50         <para>
51             This function removes the constant or linear or
52             piecewise linear trend from a vector <literal>x</literal>. In general
53             this can be useful before a fourier analysis. If <literal>x</literal> is
54             matrix this function removes the trend of each column of x.
55         </para>
56         <para>
57             When <literal>flag</literal> = "constant" or "c"  <literal>detrend</literal> removes the constant trend
58             (simply the mean of the signal) and when <literal>flag</literal> = "linear" or "l" the function
59             removes the linear trend. By adding a third argument <literal>bp</literal> it is possible to
60             remove a continuous <emphasis>piecewise linear</emphasis> trend. Note that the "instants" of the signal
61             <literal>x</literal> goes from 0 to m-1  (m = length(x) if x is a vector and m = size(x,1) in case
62             x is a matrix). So the breakpoints <literal>bp(i)</literal> must be reals in <emphasis>[0 m-1]</emphasis>
63             (breakpoints outside are simply removed from <literal>bp</literal> vector).
64         </para>
65         <para>
66             The trend is got by a least square fit of <literal>x</literal> on the appropriate function space.
67         </para>
68     </refsection>
69     <refsection>
70         <title>Examples</title>
71         <programlisting role="example"><![CDATA[
72 t = linspace(0,16*%pi,1000)';
73 x = -20 + t + 0.3*sin(0.5*t) + sin(t) + 2*sin(2*t) + 0.5*sin(3*t);
74 y = detrend(x);
75 clf()
76 plot2d(t,[x y],style=[2 5])
77 legend(["before detrend","after detrend"]);
78 xgrid()
79  ]]></programlisting>
80         <scilab:image>
81             t = linspace(0,16*%pi,1000)';
82             x = -20 + t + 0.3*sin(0.5*t) + sin(t) + 2*sin(2*t) + 0.5*sin(3*t);
83             y = detrend(x);
84             clf()
85             plot2d(t,[x y],style=[2 5])
86             legend(["before detrend","after detrend"]);
87             xgrid()
88         </scilab:image>
89         <programlisting role="example"><![CDATA[
90 t = linspace(0,32*%pi,2000)';
91 x = abs(t-16*%pi) + 0.3*sin(0.5*t) + sin(t) + 2*sin(2*t) + 0.5*sin(3*t);
92 y = detrend(x,"linear",1000);
93 clf()
94 plot2d(t,[x y],style=[2 5])
95 legend(["before detrend","after detrend"]);
96 xgrid()
97  ]]></programlisting>
98         <scilab:image>
99             t = linspace(0,32*%pi,2000)';
100             x = abs(t-16*%pi) + 0.3*sin(0.5*t) + sin(t) + 2*sin(2*t) + 0.5*sin(3*t);
101             y = detrend(x,"linear",1000);
102             clf()
103             plot2d(t,[x y],style=[2 5])
104             legend(["before detrend","after detrend"]);
105             xgrid()
106         </scilab:image>
107     </refsection>
108 </refentry>