<!-- 
<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>