--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/html_help/help/ug/ao_create_content.html	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,341 @@
+<!-- $Id: ao_create_content.html,v 1.9 2009/09/30 21:39:43 ingo Exp $ -->
+  <p>Analysis objects can be created in MATLAB in many ways. Apart from being created by the many
+    algorithms in the LTPDA Toolbox, AOs can also be created from initial data or descriptions
+    of data. The various <i>constructors</i>
+    are listed in the function help: <a href="matlab:doc('ao')">ao help</a>.</p>
+
+      <h3>Examples of creating AOs</h3>
+
+    <p>The following examples show some ways to create Analysis Objects.</p>
+
+    <ul>
+        <li><a href="ao_create.html#text">Creating AOs from text files</a></li>
+        <li><a href="ao_create.html#xml">Creating AOs from XML or MAT files</a></li>
+        <li><a href="ao_create.html#fcn">Creating AOs from MATLAB functions</a></li>
+        <li><a href="ao_create.html#tsfcn">Creating AOs from functions of time</a></li>
+        <li><a href="ao_create.html#window">Creating AOs from window functions</a></li>
+        <li><a href="ao_create.html#waveform">Creating AOs from waveform descriptions</a></li>
+        <li><a href="ao_create.html#pzmodel">Creating AOs from pole zero models</a></li>
+    </ul>
+
+    <hr>
+    <h4><a name="text"></a>Creating AOs from text files.</h4>
+
+    <p>Analysis Objects can be created from text files containing two columns of ASCII numbers. Files
+        ending in '.txt' or '.dat' will be handled as ASCII file inputs. The
+    first column is taken to be the time instances; the second column is taken to be the amplitude
+    samples. The created AO is of type <tt>tsdata</tt> with the sample rate set by the difference
+    between the time-stamps of the first two samples in the file. The name of the resulting AO is
+    set to the filename (without the file extension). The filename is also stored as a parameter in
+    the history parameter list. The following code shows this in action:</p>
+
+    <div class="fragment"><pre>
+        >> a = ao(<span class="string">'data.txt'</span>)
+        ----------- ao 01: data.txt_01_02 -----------
+ 
+               name:  data.txt_01_02
+               data: (0,-1.06421341288933) (0.1,1.60345729812004) (0.2,1.23467914689078) ...
+                     -------- tsdata 01 ------------
+              
+                         fs:  10
+                          x:  [100 1], double
+                          y:  [100 1], double
+                         dx:  [0 0], double
+                         dy:  [0 0], double
+                     xunits:  [s]
+                     yunits:  []
+                      nsecs:  10
+                         t0:  1970-01-01 00:00:00.000
+                     -------------------------------
+              
+               hist:  ao / ao / SId: fromDatafile ... $-->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  e6ccfcb6-da49-4f4c-8c2c-3054fe5d2762
+        ---------------------------------------------
+    </pre></div>
+    <p>As with most constructor calls, an equivalent action can be achieved using an input
+        <a href="plist_intro.html">Parameter List</a>.</p>
+
+    <div class="fragment"><pre>
+        >> a = ao(plist(<span class="string">'filename'</span>, <span class="string">'data.txt'</span>))
+    </pre></div>
+
+    <hr>
+    <h4><a name="xml"></a>Creating AOs from XML or .mat files</h4>
+
+    <p>AOs can be saved as both XML and .MAT files. As such, they can also be created from these
+        files.</p>
+
+    <div class="fragment"><pre>
+        >> a = ao(<span class="string">'a.xml'</span>)
+        ----------- ao 01: a -----------
+        
+               name:  None
+               data: (0,-0.493009815316451) (0.1,-0.180739356415037) (0.2,0.045841105713705) ...
+                     -------- tsdata 01 ------------
+              
+                         fs:  10
+                          x:  [100 1], double
+                          y:  [100 1], double
+                         dx:  [0 0], double
+                         dy:  [0 0], double
+                     xunits:  [s]
+                     yunits:  []
+                      nsecs:  10
+                         t0:  1970-01-01 00:00:01.000
+                     -------------------------------
+                      
+               hist:  ao / ao / SId: fromVals ... $-->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  2fed6155-6468-4533-88f6-e4b27bc6e1aa
+        --------------------------------
+    </pre></div>
+
+    <hr>
+    <h4><a name="fcn"></a>Creating AOs from MATLAB functions</h4>
+
+    <p>AOs can be created from any valid MATLAB function which returns a vector or matrix of values.
+        For such calls, a parameter list is used as input. For example, the following code creates
+        an AO containing 1000 random numbers:</p>
+
+    <div class="fragment"><pre>
+        >> a = ao(plist(<span class="string">'fcn'</span>, <span class="string">'randn(1000,1)'</span>))
+        ----------- ao 01: a -----------
+ 
+               name:  None
+               data: -1.28325610460477 -2.32895451628334 0.901931466951714 -1.83563868373519 0.06675 ...
+                     -------- cdata 01 ------------
+                          y:  [1000x1], double
+                         dy:  [0x0], double
+                     yunits:  []
+                     ------------------------------
+              
+               hist:  ao / ao / SId: fromFcn ... $-->$Id ... $
+            mdlfile:  empty
+        description:  
+               UUID:  0072f8d0-f804-472b-a4aa-e9ec6a8de803
+        --------------------------------
+    </pre></div>
+  <p>Here you can see that the AO is a <tt>cdata</tt> type and the name is set to be the function
+    that was input.</p>
+
+    <hr>
+    <h4><a name="tsfcn"></a>Creating AOs from functions of time</h4>
+
+    <p>AOs can be created from any valid MATLAB function which is a function of the variable
+        <tt>t</tt>. For such calls, a parameter list is used as input. For example, the following
+        code creates an AO containing sinusoidal signal at 1Hz with some additional Gaussian noise:</p>
+
+    <div class="fragment"><pre>
+        pl = plist();
+        pl = append(pl, <span class="string">'nsecs'</span>, 100);
+        pl = append(pl, <span class="string">'fs'</span>, 10);
+        pl = append(pl, <span class="string">'tsfcn'</span>, <span class="string">'sin(2*pi*1*t)+randn(size(t))'</span>);
+        a = ao(pl)
+        ----------- ao 01: a -----------
+ 
+               name:  None
+               data: (0,1.37694916561229) (0.1,-0.820427237640771) (0.2,1.09228819960292) ...
+                     -------- tsdata 01 ------------
+              
+                         fs:  10
+                          x:  [1000 1], double
+                          y:  [1000 1], double
+                         dx:  [0 0], double
+                         dy:  [0 0], double
+                     xunits:  [s]
+                     yunits:  []
+                      nsecs:  100
+                         t0:  1970-01-01 00:00:00.000
+                     -------------------------------
+              
+               hist:  ao / ao / SId: fromTSfcn ... $-->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  c0f481cf-4bdd-4a91-bc78-6d34f8222313
+        --------------------------------
+     </pre></div>
+  <p>Here you can see that the AO is a <tt>tsdata</tt> type, as you would expect. Also note that you
+    need to specify the sample rate (<tt>fs</tt>) and the number of seconds of data you would like
+    to have (<tt>nsecs</tt>).</p>
+
+    <hr>
+    <h4><a name="window"></a>Creating AOs from window functions</h4>
+
+    <p>The LTPDA Toolbox contains a class for designing spectral windows
+        (see <a href="specwin.html">Spectral Windows</a>). A spectral window object can
+        also be used to create an Analysis Object as follows:</p>
+
+    <div class="fragment"><pre>
+        >> w = specwin(<span class="string">'Hanning'</span>, 1000)
+        ------ specwin/1 -------
+            type: Hanning
+           alpha: 0
+            psll: 31.5
+             rov: 50
+           nenbw: 1.5
+            w3db: 1.4382
+        flatness: -1.4236
+              ws: 500
+             ws2: 375.000000000001
+             win: [0 9.86957193144233e-06 3.94778980919441e-05 8.88238095955174e-05 0.0001579 ...
+         version: SId: specwin.m,v 1.67 2009/09/01 09:25:24 ingo Exp S
+        ------------------------
+
+        >> a = ao(w)
+        ----------- ao 01: ao(Hanning) -----------
+ 
+               name:  ao(Hanning)
+               data: 0 9.86957193144233e-06 3.94778980919441e-05 8.88238095955174e-05 0.0001579 ...
+                     -------- cdata 01 ------------
+                          y:  [1x1000], double
+                         dy:  [0x0], double
+                     yunits:  []
+                     ------------------------------
+              
+               hist:  ao / ao / SId: fromSpecWin ... $-->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  ea1a9036-b9f5-4bdb-b3a3-211e9d697060
+        ------------------------------------------
+    </pre></div>
+    <p>
+      It is also possible to pass the information about the window as a plist to the ao constructor.
+    </p>
+    <div class="fragment"><pre>
+        >> ao(plist(<span class="string">'win'</span>, <span class="string">'Hanning'</span>, <span class="string">'length'</span>, 1000))
+        ----------- ao 01: ao(Hanning) -----------
+ 
+               name:  ao(Hanning)
+               data: 0 9.86957193144233e-06 3.94778980919441e-05 8.88238095955174e-05 0.0001579 ...
+                     -------- cdata 01 ------------
+                          y:  [1x1000], double
+                         dy:  [0x0], double
+                     yunits:  []
+                     ------------------------------
+              
+               hist:  ao / ao / SId: fromSpecWin ... -->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  5b81f67a-45b9-43f8-a74a-bc5161fd718f
+        ------------------------------------------
+    </pre></div>
+    
+  <p>
+    The example code above creates a Hanning window object with 1000 points. The call to the AO
+    constructor then creates a <tt>cdata</tt> type AO with 1000 points. This AO can then be multiplied
+    against other AOs in order to window the data.
+    </p>
+
+    <hr>
+    <h4><a name="waveform"></a>Creating AOs from waveform descriptions</h4>
+
+    <p>
+        MATLAB contains various functions for creating different waveforms, for example,
+        <tt>square</tt>, <tt>sawtooth</tt>. Some of these functions can be called upon to create
+        Analysis Objects. The following code creates an AO with a sawtooth waveform:
+    </p>
+
+    <div class="fragment"><pre>
+        pl = plist();
+        pl = append(pl, <span class="string">'fs'</span>, 100);
+        pl = append(pl, <span class="string">'nsecs'</span>, 5);
+        pl = append(pl, <span class="string">'waveform'</span>, 'Sawtooth');
+        pl = append(pl, <span class="string">'f'</span>, 1);
+        pl = append(pl, <span class="string">'width'</span>, 0.5);
+
+        asaw = ao(pl)
+        ----------- ao 01: Sawtooth -----------
+ 
+               name:  Sawtooth
+               data: (0,-1) (0.01,-0.96) (0.02,-0.92) (0.03,-0.88) (0.04,-0.84) ...
+                     -------- tsdata 01 ------------
+              
+                         fs:  100
+                          x:  [500 1], double
+                          y:  [500 1], double
+                         dx:  [0 0], double
+                         dy:  [0 0], double
+                     xunits:  [s]
+                     yunits:  []
+                      nsecs:  5
+                         t0:  1970-01-01 00:00:00.000
+                     -------------------------------
+              
+               hist:  ao / ao / SId: fromWaveform ... $-->$Id: ao ... S
+            mdlfile:  empty
+        description:  
+               UUID:  cb76c866-ee3f-47e6-bb29-290074666e43
+        ---------------------------------------
+   </pre></div>
+  <p>
+    You can call the <tt>iplot</tt> function to view the resulting waveform:
+    </p>
+    <div class="fragment"><pre>
+        iplot(asaw);
+    </pre></div>
+  <img src="images/ao_create_sawtooth.png" alt="Sawtooth waveform" border="3" width="600px">
+
+	<hr>
+  <h4><a name="pzmodel"></a>Creating AOs from pole zero models</h4>
+
+  <p>
+      When generating an AO from a pole zero model, the noise generator function is called.
+	  This a method to generate arbitrarily long time series with a prescribed spectral density.
+	  The algorithm is based on the following paper:
+  </p>
+  <p>Franklin, Joel N.:
+<i> Numerical simulation of stationary and non-stationary gaussian
+random processes </i>, SIAM review, Volume {<b> 7</b>}, Issue 1, page 68--80, 1965.
+  </p>
+  <p>
+ 	The Document <i> Generation of Random time series with prescribed spectra </i> by Gerhard Heinzel (S2-AEI-TN-3034) <br> corrects a mistake in the aforesaid paper and describes the practical implementation.
+      The following code creates an AO with a time series having a prescribed spectral density,
+	  defined by the input pole zero model:
+  </p>
+
+  <div class="fragment"><pre>
+	f1    = 5;
+	f2    = 10;
+	f3    = 1;
+	gain  = 1;
+	fs    = 10;  <span class="comment">%sampling frequancy</span>
+	nsecs = 100; <span class="comment">%number of seconds to be generated</span>
+  
+  p = [pz(f1) pz(f2)];
+	z = [pz(f3)];
+	pzm = pzmodel(gain, p, z);
+	a = ao(pzm, nsecs, fs)
+	----------- ao 01: noisegen(None) -----------
+ 
+	       name:  noisegen(None)
+	       data: (0,9.20287001568168) (0.1,-3.88425345108961) (0.2,6.31042718242658) ...
+	             -------- tsdata 01 ------------
+              
+	                 fs:  10
+	                  x:  [1000 1], double
+	                  y:  [1000 1], double
+	                 dx:  [0 0], double
+	                 dy:  [0 0], double
+	             xunits:  [s]
+	             yunits:  []
+	              nsecs:  100
+	                 t0:  1970-01-01 00:00:00.000
+	             -------------------------------
+              
+	       hist:  ao / ao / SId: fromPzmodel ... $-->$Id: ao ... S
+	    mdlfile:  empty
+	description:  
+	       UUID:  4a89d910-8672-475f-91cd-4fcc4b52a6b4
+	---------------------------------------------
+  </pre></div>
+<p>
+  You can call the <tt>iplot</tt> function to view the resulting noise.
+  </p>
+  <div class="fragment"><pre>
+      iplot(a);
+  </pre></div>
+<img src="images/ao_create_niose.png" alt="Random time series" border="3" width="600px">
+