[doc] Misc. small improvements
[scilab.git] / scilab / modules / signal_processing / help / en_US / spectral_estimation / cspect.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:ns4="http://www.w3.org/1999/xhtml"
4           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
5           xmlns:scilab="http://www.scilab.org" xml:id="cspect" xml:lang="en">
6     <refnamediv>
7         <refname>cspect</refname>
8         <refpurpose>two sided cross-spectral estimate between 2 discrete time signals using
9             the correlation method
10         </refpurpose>
11     </refnamediv>
12     <refsynopsisdiv>
13         <title>Syntax</title>
14         <synopsis>
15             sm = cspect(nlags, npoints, wtype, x)
16             sm = cspect(nlags, npoints, wtype, x, y)
17             sm = cspect(nlags, npoints, wtype, nx)
18             sm = cspect(nlags, npoints, wtype, nx, ny)
19             [sm, cwp] = cspect(.., wpar)
20         </synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>x</term>
27                 <listitem>
28                     <para>vector, the data of the first signal.</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>y</term>
33                 <listitem>
34                     <para>
35                         vector, the data of the second signal. If <literal>y</literal>
36                         is omitted it is supposed to be equal to <literal>x</literal>
37                         (auto-correlation). If it is present, it must have the same number of
38                         element than <literal>x.</literal>
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>nx</term>
44                 <listitem>
45                     <para>
46                         a scalar : the number of points in the <literal>x</literal>
47                         signal. In this case the segments of the x signal are loaded by a
48                         user defined function named <literal>getx</literal> (see below).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>ny</term>
54                 <listitem>
55                     <para>a scalar : the number of points in the
56                         <literal>y</literal> signal. In this case the segments of
57                         the <literal>y</literal> signal are loaded by a user defined
58                         function named <literal>gety</literal> (see below). If
59                         present <literal>ny</literal> must be equal to
60                         <literal>nx</literal>.
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>nlags</term>
66                 <listitem>
67                     <para>number of correlation lags (positive integer)</para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>npoints</term>
72                 <listitem>
73                     <para>number of transform points (positive integer)</para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>wtype</term>
78                 <listitem>
79                     <para>The window type</para>
80                     <itemizedlist>
81                         <listitem>
82                             <para>
83                                 <literal>'re'</literal>: rectangular
84                             </para>
85                         </listitem>
86                         <listitem>
87                             <para>
88                                 <literal>'tr'</literal>: triangular
89                             </para>
90                         </listitem>
91                         <listitem>
92                             <para>
93                                 <literal>'hm'</literal>: Hamming
94                             </para>
95                         </listitem>
96                         <listitem>
97                             <para>
98                                 <literal>'hn'</literal>: Hann
99                             </para>
100                         </listitem>
101                         <listitem>
102                             <para>
103                                 <literal>'kr'</literal>: Kaiser, in this case the <literal>wpar</literal>
104                                 argument must be given
105                             </para>
106                         </listitem>
107                         <listitem>
108                             <para>
109                                 <literal>'ch'</literal>: Chebyshev, in this case the <literal>wpar</literal>
110                                 argument must be given
111                             </para>
112                         </listitem>
113                     </itemizedlist>
114                 </listitem>
115             </varlistentry>
116             <varlistentry>
117                 <term>wpar</term>
118                 <listitem>
119                     <para>
120                         optional parameters for Kaiser and Chebyshev windows:
121                     </para>
122                     <itemizedlist>
123                         <listitem>
124                             <para>
125                                 'kr': <literal>wpar</literal> must be a strictly positive number
126                             </para>
127                         </listitem>
128                         <listitem>
129                             <para>
130                                 'ch': <literal>wpar</literal> must be a 2 element vector
131                                 <literal> [main_lobe_width,side_lobe_height]</literal> with
132                                 <literal>0&lt;main_lobe_width&lt;.5</literal>, and
133                                 <literal>side_lobe_height&gt;0</literal>
134                             </para>
135                         </listitem>
136                     </itemizedlist>
137                 </listitem>
138             </varlistentry>
139             <varlistentry>
140                 <term>sm</term>
141                 <listitem>
142                     <para>The power spectral estimate in the interval
143                         <literal>[0,1]</literal> of the normalized frequencies. It
144                         is a row array of size <varname>npoints</varname>. The array
145                         is real in case of auto-correlation and complex in case of
146                         cross-correlation.
147                     </para>
148                 </listitem>
149             </varlistentry>
150             <varlistentry>
151                 <term>cwp</term>
152                 <listitem>
153                     <para>the unspecified Chebyshev window parameter in case of Chebyshev
154                         windowing, or an empty matrix.
155                     </para>
156                 </listitem>
157             </varlistentry>
158         </variablelist>
159     </refsection>
160     <refsection>
161         <title>Description</title>
162         <para>Computes the cross-spectrum estimate of two signals
163             <varname>x</varname> and <varname>y</varname> if both are given and the
164             auto-spectral estimate of <varname>x</varname> otherwise. Spectral
165             estimate obtained using the correlation method.
166         </para>
167         <para>
168             The cross-spectrum of two signal <varname>x</varname> and <varname>y</varname> is defined to be
169             <latex style="display"
170                 alt="S_xy(ω) = (∑{n=0…N-1} x(n) exp(-i ω n)).
171                                (∑{n=0…N-1} y'(n) exp(i ω n)) / N">
172                 S_{xy} (\omega) = {1 \over N}
173                 \left(\sum_{n=0}^{N-1} x(n)\,e^{-i \omega n}\right)
174                 \left( \sum_{n=0}^{N-1} \bar{y}(n)\,e^{i \omega n} \right)
175             </latex>
176         </para>
177         <para>The correlation method calculates the spectral estimate as the
178             Fourier transform of a modified estimate of the auto/cross correlation
179             function. This auto/cross correlation modified estimate consist of
180             repeatedly calculating estimates of the autocorrelation function from
181             overlapping sub-segments of the data, and then averaging these estimates
182             to obtain the result.
183         </para>
184         <para>The number of points of the window is
185             <literal>2*nlags-1.</literal>
186         </para>
187         <para>
188             For batch processing, the <varname>x</varname> and <varname>y</varname> data may be read
189             segment by segment using the  <literal>getx</literal> and <literal>gety</literal> user
190             defined functions. These functions have the following syntax:
191         </para>
192         <para>
193             <literal>xk=getx(ns,offset)</literal> and
194             <literal>yk=gety(ns,offset)</literal> where <varname>ns</varname> is the
195             segment size and <varname>offset</varname> is the index of the first
196             element of the segment in the full signal.
197         </para>
198     </refsection>
199     <refsection>
200         <title>Warning</title>
201         <para>For Scilab version up to 5.0.2 the returned value was the modulus of the current one.</para>
202     </refsection>
203     <refsection>
204         <title>Reference</title>
205         <para>Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing,
206             Upper Saddle River, NJ: Prentice-Hall, 1999
207         </para>
208     </refsection>
209     <refsection>
210         <title>Examples</title>
211         <programlisting role="example"><![CDATA[
212 rand('normal');
213 rand('seed',0);
214 x = rand(1:1024-33+1);
215
216 // make low-pass filter with eqfir
217 [nf, bedge, des, wate] = (33, [0 .1;.125 .5], [1 0], [1 1]);
218 h = eqfir(nf, bedge, des, wate);
219
220 // filter white data to obtain colored data
221 h1 = [h 0*ones(1:max(size(x))-1)];
222 x1 = [x 0*ones(1:max(size(h))-1)];
223 hf = fft(h1,-1);
224 xf = fft(x1,-1);
225 yf = hf .* xf;
226 y = real(fft(yf,1));
227 sm = cspect(100, 200, 'tr', y);
228 smsize = max(size(sm));
229 fr = (1:smsize)/smsize;
230
231 plot(fr, log(sm), 'r')
232  ]]></programlisting>
233     </refsection>
234     <refsection role="see also">
235         <title>See also</title>
236         <simplelist type="inline">
237             <member>
238                 <link linkend="pspect">pspect</link>
239             </member>
240             <member>
241                 <link linkend="mese">mese</link>
242             </member>
243             <member>
244                 <link linkend="corr">corr</link>
245             </member>
246         </simplelist>
247     </refsection>
248 </refentry>