--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/html_help/help/ug/whiten1D_content.html	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,204 @@
+<!-- 
+<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>
+
+
+
+
+
+
+
+
+			
+
+