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