Mercurial > hg > ltpda
diff m-toolbox/html_help/help/ug/ao_create.html @ 0:f0afece42f48
Import.
| author | Daniele Nicolodi <nicolodi@science.unitn.it> |
|---|---|
| date | Wed, 23 Nov 2011 19:22:13 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/m-toolbox/html_help/help/ug/ao_create.html Wed Nov 23 19:22:13 2011 +0100 @@ -0,0 +1,406 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd"> + +<html lang="en"> +<head> + <meta name="generator" content= + "HTML Tidy for Mac OS X (vers 1st December 2004), see www.w3.org"> + <meta http-equiv="Content-Type" content= + "text/html; charset=us-ascii"> + + <title>Creating Analysis Objects (LTPDA Toolbox)</title> + <link rel="stylesheet" href="docstyle.css" type="text/css"> + <meta name="generator" content="DocBook XSL Stylesheets V1.52.2"> + <meta name="description" content= + "Presents an overview of the features, system requirements, and starting the toolbox."> + </head> + +<body> + <a name="top_of_page" id="top_of_page"></a> + + <p style="font-size:1px;"> </p> + + <table class="nav" summary="Navigation aid" border="0" width= + "100%" cellpadding="0" cellspacing="0"> + <tr> + <td valign="baseline"><b>LTPDA Toolbox</b></td><td><a href="../helptoc.html">contents</a></td> + + <td valign="baseline" align="right"><a href= + "ao_intro.html"><img src="b_prev.gif" border="0" align= + "bottom" alt="Analysis Objects"></a> <a href= + "ao_save.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Saving Analysis Objects"></a></td> + </tr> + </table> + + <h1 class="title"><a name="f3-12899" id="f3-12899"></a>Creating Analysis Objects</h1> + <hr> + + <p> + <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"> + + + </p> + + <br> + <br> + <table class="nav" summary="Navigation aid" border="0" width= + "100%" cellpadding="0" cellspacing="0"> + <tr valign="top"> + <td align="left" width="20"><a href="ao_intro.html"><img src= + "b_prev.gif" border="0" align="bottom" alt= + "Analysis Objects"></a> </td> + + <td align="left">Analysis Objects</td> + + <td> </td> + + <td align="right">Saving Analysis Objects</td> + + <td align="right" width="20"><a href= + "ao_save.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Saving Analysis Objects"></a></td> + </tr> + </table><br> + + <p class="copy">©LTP Team</p> +</body> +</html>