+
−<!-- 
+
−<p>
+
−  <ul>
+
−    <li><a href="#description">Description</a></li>
+
−    <li><a href="#call">Call</a></li>
+
−    <li><a href="#inputs">Inputs</a></li>
+
−    <li><a href="#outputs">Outputs</a></li>
+
−    <li><a href="#algorithm">Algorithm</a></li>
+
−    <li><a href="#parameters">Parameters</a></li>
+
−    <li><a href="#example">Example</a></li>
+
−  </ul>
+
−</p>
+
−-->
+
−<h2><a name="description">Description</a></h2>
+
−
+
−<p>
+
−  whiten1D whitens input time-series. Whitening filter is constructed
+
−  by a fitting procedure to the model provided. If no model is provided, a
+
−  fit is made to a log-spectral-density estimate of the
+
−  time-series (made using lpsd).
+
−  Note: The function assumes that the input model corresponds
+
−  to the one-sided psd of the data to be whitened.
+
−</p>
+
−
+
−<h2><a name="call">Call</a></h2>
+
−<div class="fragment">
+
−  <pre>
+
−    <br>
+
−    b = whiten1D(a, pl)
+
−    [b1,b2,...,bn] = whiten1D(a1,a2,...,an, pl);
+
−  </pre>
+
−</div>
+
−
+
−<h2><a name="inputs">Inputs</a></h2>
+
−
+
−<p>
+
−  <ul>
+
−    <li> a - is a tsdata analysis object or a vector of tsdata analysis objects
+
−    <li> pl - is a plist with the input parameters. See the list of function parameters below
+
−  </ul>
+
−</p>
+
−
+
−<h2><a name="outputs">Outputs</a></h2>
+
−
+
−<p>
+
−  <ul>
+
−    <li> b "whitened" time-series AOs. The whitening filters used
+
−    are stored in the objects procinfo field under the
+
−    parameter 'Filt'.
+
−  </ul>
+
−</p>
+
−
+
−<h2><a name="algorithm">Algorithm</a></h2>
+
−
+
−<p>
+
−  <ol>
+
−    <li> If no model provided, make lpsd of time-series and take it
+
−    as a model for the data power spectral density
+
−    <li> Fit a set of partial fraction z-domain filters using
+
−    utils.math.psd2wf. The fit is automatically stopped when
+
−    the accuracy tolerance is reached.
+
−    <li> Convert to bank of MIIR filters.
+
−    <li> Filter time-series in parallel
+
−  </ol>
+
−</p>
+
−<p>
+
−  Accuracy tolerance criteria
+
−  <ul>
+
−    <li> No model provided <br/>
+
−    In such a case the algorithm try to extract a smooth model
+
−    from lpsd noisy data. Fit residuals spectral flatness is
+
−    compared with the 'FitTolerance' parameter. Fit is stopped
+
−    when residuals spectral flatness is larger than the
+
−    'FitTolerance' parameter. Admitted values are 0 < tol < 1.
+
−    Recommended values are 0.5 < tol < 0.7. If out of range values
+
−    are provided the parameter is set to 0.5.
+
−    <li> Model provided <br/>
+
−    In such a case the algorithm try to exactly fit the input
+
−    model whitin the accuracy reported in 'FitTolerance'. Check
+
−    if the minimum of the logarithmic difference between data
+
−    and residuals is  larger than a specified value.
+
−    Admitted values are tol>0. Recommended values are
+
−    0.5 < tol < 2. if the conditioning value is 2, the function
+
−    ensures that the difference between data and residuals is
+
−    at lest 2 order of magnitude lower than data itsleves. If a
+
−    negative value is provided the tolerance is set to 1.
+
−  </ul>
+
−</p>
+
−
+
−
+
−<h2><a name="parameters">Parameters</a></h2>
+
−<p>
+
−  <ul>
+
−    <li> 'Model' - a frequency-series AO describing the model
+
−    response to build the filter from. [default: lpsd
+
−    of time-series].
+
−    <li> 'MaxIter' - Maximum number of iterations in fit routine
+
−    [default: 30]
+
−    <li> 'PoleType' - Choose the pole type for fitting:
+
−      <ul>
+
−        <li> 1 - use real starting poles.
+
−        <li> 2  - generates complex conjugate poles of the
+
−        type a.*exp(theta*pi*j)
+
−        with theta = linspace(0,pi,N/2+1).
+
−        <li> 3  - generates complex conjugate poles of the type
+
−        a.*exp(theta*pi*j)
+
−        with theta = linspace(0,pi,N/2+2) [default].
+
−      </ul>
+
−    </li>
+
−    <li> 'MinOrder' - Minimum order to fit with. [default: 2].
+
−    <li> 'MaxOrder' - Maximum order to fit with. [default: 25]
+
−    <li> 'Weights'  - choose weighting for the fit: [default: 2]
+
−      <ul>
+
−        <li> 1 - equal weights for each point.
+
−        <li> 2  - weight with 1/abs(model).
+
−        <li> 3  - weight with 1/abs(model).^2.
+
−        <li> 4  - weight with inverse of the square mean spread of the model.
+
−      </ul>
+
−    </li>
+
−    <li> 'Plot' - plot results of each fitting step. [default: false]
+
−    <li> 'Disp' - Display the progress of the fitting iteration.
+
−    [default: false]
+
−    <li> 'FitTolerance' - Stopping fit tolerance condition. Be sure to
+
−    read the algorithm description to provide the
+
−    correct value. [default: 0.6]
+
−    <li> 'RMSEVar'  - Root Mean Squared Error Variation - Check if the
+
−    variation of the RMS error is smaller than 10^(-b),
+
−    where b is the value given to the variable. This
+
−    option is useful for finding the minimum of Chi
+
−    squared. [default: 7].
+
−  </ul>
+
−  parameters passed to lpsd()
+
−  <ul>
+
−    <li> 'Jdes' - The number of points in the power spectrum.
+
−    [default: help lpsd].
+
−    <li> 'Win'   - Spectral window used in spectral estimation.
+
−    [default: help lpsd].
+
−    <li> 'Order' - order of segment detrending: [default: help lpsd]
+
−      <ul>
+
−        <li> -1 - no detrending
+
−        <li> 0 - subtract mean
+
−        <li> 1 - subtract linear fit
+
−        <li> N - subtract fit of polynomial, order N
+
−      </ul>
+
−  </ul>
+
−</p>
+
−
+
−<h2><a name="example">Example</a></h2>
+
−
+
−<div class="fragment">
+
−  <br>
+
−  <pre>
+
−   <span class="comment">% Generate white noise</span>
+
−  fs = 1;
+
−  a = ao(plist( <span class="string">'tsfcn'</span>,  <span class="string">'randn(size(t))'</span>,  <span class="string">'fs'</span>, fs,  <span class="string">'nsecs'</span>, 10000,  <span class="string">'yunits'</span>, <span class="string">'m'</span>, <span class="string">'name'</span>, <span class="string">'input'</span>));
+
−
+
−   <span class="comment">% filter </span>
+
−  pzm = pzmodel(1e-2, {0.01}, {0.1});
+
−  ft = miir(pzm,plist( <span class="string">'fs'</span>,fs));
+
−
+
−   <span class="comment">% coloring white noise </span>
+
−  af = filter(a, ft);
+
−
+
−   <span class="comment">% Whitening colored noise</span>
+
−  pl = plist(...
+
−       <span class="string">'model'</span>, [], ...
+
−       <span class="string">'MaxIter'</span>, 30, ...
+
−       <span class="string">'PoleType'</span>, 2, ...
+
−       <span class="string">'MinOrder'</span>, 2, ...
+
−       <span class="string">'MaxOrder'</span>, 9, ...
+
−       <span class="string">'Weights'</span>, 2, ...
+
−       <span class="string">'Plot'</span>, false,...
+
−       <span class="string">'Disp'</span>, false,...
+
−       <span class="string">'RMSEVar'</span>, 3,...
+
−       <span class="string">'FitTolerance'</span>, 0.6);  <span class="comment">% tolerancee on fit residuals spectral flatness</span>
+
−
+
−  aw = whiten1D(af,pl);
+
−
+
−   <span class="comment">% Calculate psd of colored and whitened data </span>
+
−  afxx = af.psd;
+
−  awxx = aw.psd;
+
−
+
−   <span class="comment">% plotting </span>
+
−  iplot(afxx,awxx)
+
−  </pre>
+
−</div>
+
−<br>
+
−<br>
+
−<p>
+
−  <div align="center">
+
−    <IMG src="images/whiten1D_1.png"  align="center" border="0">
+
−  </div>
+
−</p>
+
−
+
−
+
−
+
−
+
−
+
−
+
−
+
−
+
−			
+
−
+
−