Mercurial > hg > ltpda
diff m-toolbox/html_help/help/ug/ltpda_training_topic_1_3.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/ltpda_training_topic_1_3.html Wed Nov 23 19:22:13 2011 +0100 @@ -0,0 +1,382 @@ +<!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>Making a time-series AO (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= + "ltpda_training_topic_1_2.html"><img src="b_prev.gif" border="0" align= + "bottom" alt="Making AOs"></a> <a href= + "ltpda_training_topic_1_4.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Basic math with AOs"></a></td> + </tr> + </table> + + <h1 class="title"><a name="f3-12899" id="f3-12899"></a>Making a time-series AO</h1> + <hr> + + <p> + <h2>Exercise 4</h2> +<p> + Time-series data are stored in a data object of the class <tt>tsdata</tt>. + As a user, you don't need to care about this, but it's sometimes + nice to know how things work. There are various ways (constructors) + to build time-series AOs. For example, you can give a set of values and + a sample rate like +</p> +<div class="fragment"><pre> + a = ao([1 2 3 4 5], 2) +</pre></div> +<p> + The first argument is the Y data vector; the second, the sample rate. +</p> +<p> + If you run this command in the MATLAB terminal you should see +</p> +<div class="fragment"><pre> +>> a = ao([1 2 3 4 5], 2) +M: constructing from Y values and fs +----------- ao 01: a ----------- + + name: '' + data: (0,1) (0.5,2) (1,3) (1.5,4) (2,5) + -------- tsdata 01 ------------ + + fs: 2 + x: [1 5], double + y: [1 5], double + dx: [0 0], double + dy: [0 0], double + xunits: [s] + yunits: [] + nsecs: 2.5 + t0: 1970-01-01 00:00:00.000 + ------------------------------- + + hist: ao / ao / SId: fromXYVals.m,v 1.10 2011/05/07 05:15:26 mauro Exp S-->SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S +description: + UUID: 2484d029-4616-4b22-8229-7685c8d3e847 +-------------------------------- +</pre></div> +<p> + Now you see that the data type is <tt>tsdata</tt> and the X units are automatically + set to seconds ('s'). You can also see that the data series spans 2.5s + and that the first sample corresponds to 1970-01-01 00:00:00.000 UTC. + You can set further properties of the object, for example +</p> +<p> +<div class="fragment"><pre> +a.setT0(<span class="string">'2009-02-03 12:23:44'</span>); +a.setDescription(<span class="string">'My lovely time-series'</span>) +</pre></div> +</p> +<br> +<p> + You can do all of this in one block on the workbench. To do that: + <ol> + <li>Start the workbench and create a new pipeline</li> + <li>Drag an AO constructor block from the library (or use "Quick Block")</li> + <li>Select the block and select the "From XY Values" parameter set</li> + <li>Click the "Set" button to set the parameters to the block</li> + <li>Double-click the value cell for the key "YVALS" and enter some values, e.g., <tt>1:10</tt></li> + <li>Double-click the value cell for the key "FS" and enter a sample frequency, e.g., <tt>2</tt>. By + setting a set of values for the Y-data and a sample rate, we tell the AO constructor that we want to + build a <tt>tsdata</tt> AO.</li> + <li>To set the name of the block, double click the block and enter a name in the dialog box. Automatic + setting of AO names from the block name only happens for constructor blocks. To the set the name of AOs + which are outputs of all other block types, use the <tt>setName</tt> block. + </li> + <li>You'll notice that the parameter list doesn't contain a <tt>T0</tt> parameter by default, but you can + easily add this parameter by clicking on the "plus" button below the parameter list. Enter the key <tt>T0</tt> + in the dialog box, and an appropriate value in the next dialog box. (Note: parameter key names are case + insensitive.)</li> + <li>You can do the same for the description, or any other property of the AO.</li> + </ol> +</p> +<p> + The final parameter list in this case might look like: +</p> +<img src="images/ltpda_training_1/topic1/tsdata_pset.png" alt="Time-series parameter set" border="1"> + +<br> +<br> +<!-- Plists --> +<h2>Digression: Introducing parameter lists</h2> +<br> +<p> + The time has come to go back to that <tt>plist</tt> command we saw earlier when plotting + the AO history via the graphviz renderer. +</p> +<p> + The following two commands are equivalent: +</p> +<div class="fragment"><pre> +a = ao([1 2 3 4 5], 2); +a = ao(plist(<span class="string">'yvals'</span>, [1 2 3 4 5], <span class="string">'fs'</span>, 2)) +</pre></div> +<p> + Here we introduce the idea of parameter lists (<tt>plist</tt>). A <tt>plist</tt> is a list + of parameters, each parameter being defined by a key/value pair. The key of + a <tt>plist</tt> is always a string and is always case insensitive. The value can be + anything: a number, a string, another LTPDA object, a cell-array, a structure, etc. For more + information about parameter lists, see the <a href="plist_intro.html">appropriate section</a> + of the LTPDA user manual. +</p> +<p> + Going on with time-series objects: The following is almost equivalent: +</p> +<div class="fragment"><pre> + a = ao(plist(<span class="string">'xvals'</span>, [0 0.5 1 1.5 2], <span class="string">'yvals'</span>, [1 2 3 4 5])) +</pre></div> +<p> + The difference is, if you run this command, you will see that the resulting + AO has data of type <tt>xydata</tt>. To make this a time-series object, + we need to tell the constructor some more information. Either you need to + specify the sample-rate, or you can explicitly set the data type: +</p> +<div class="fragment"><pre> + a = ao(plist(<span class="string">'xvals'</span>, [0 0.5 1 1.5 2], <span class="string">'yvals'</span>, [1 2 3 4 5], <span class="string">'fs'</span>, 2)) + a = ao(plist(<span class="string">'xvals'</span>, [0 0.5 1 1.5 2], <span class="string">'yvals'</span>, [1 2 3 4 5], <span class="string">'type'</span>,... + <span class="string">'tsdata'</span>)) +</pre></div> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + The elipsis (<tt>...</tt>) in MATLAB means join the two lines. + </td> + </tr> + </table> +</p> +<p> + If you specify the samples rate with the key 'fs', then the 'xvals' + are just ignored. If you tell the data type with the key 'type', then + the sample rate is computed from the 'xvals'. +</p> +<p> + You can add additional parameters to these constructor lines. For example, +</p> +<div class="fragment"><pre> +a = ao(plist(<span class="string">'xvals'</span>, [0 0.5 1 1.5 2], <span class="string">'yvals'</span>, [1 2 3 4 5], ... + <span class="string">'type'</span>, <span class="string">'tsdata'</span>, ... + <span class="string">'name'</span>, <span class="string">'Bob'</span>, ... + <span class="string">'t0'</span>, <span class="string">'2008-09-01'</span>)) +</pre></div> +<p> + There are other constructors which make constructing time-series AOs from + simulated data more convenient. Two of these are discussed below. +</p> +<br> +<!-- Time-series f(t) --> +<h2>Times-series AO as a function of <tt>t</tt></h2> +<br> +<p> + If you want to specify your time-series as a function of the variable <tt>t</tt>, + then you can use the following constructor: +</p> +<div class="fragment"><pre> + a = ao(plist(<span class="string">'tsfcn'</span>, <span class="string">'t.^2 + t'</span>, ... + <span class="string">'fs'</span>, 10, <span class="string">'nsecs'</span>, 1000)) +</pre></div> +<p> + You specify the function of t with the key 'tsfcn', then give the sample + rate and the number of seconds. If you run this command you should see the output: +</p> +<div class="fragment"><pre> +>> a = ao(plist('tsfcn', 't.^2 + t', 'fs', 10, 'nsecs', 1000)) +M: constructing from plist +----------- ao 01: a ----------- + + name: '' + data: (0,0) (0.1,0.11) (0.2,0.24) (0.3,0.39) (0.4,0.56) ... + -------- tsdata 01 ------------ + + fs: 10 + x: [10000 1], double + y: [10000 1], double + dx: [0 0], double + dy: [0 0], double + xunits: [s] + yunits: [] + nsecs: 1000 + t0: 1970-01-01 00:00:00.000 + ------------------------------- + + hist: ao / ao / SId: fromTSfcn.m,v 1.22 2010/07/28 16:31:01 ingo Exp S-->SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S +description: + UUID: d01615d6-82ad-4736-8a0e-4096dc023149 +-------------------------------- +</pre></div> +<p> + You can write any valid MATLAB expression as a function of <tt>t</tt>. +</p> +<p> + Plists can be reused, of course. Suppose we define a recipe for an AO as +</p> +<div class="fragment"><pre> + pl = plist(<span class="string">'tsfcn'</span>, <span class="string">'randn(size(t))'</span>, <span class="string">'fs'</span>, 10, <span class="string">'nsecs'</span>, 1000) +</pre></div> +<p> + then we can make repeated AOs from this recipe: +</p> +<div class="fragment"><pre> +a1 = ao(pl) +a2 = ao(pl) +<span class="comment">% Or use the random factory:</span> +<span class="comment">% a = ao.randn(nsecs, fs)</span> +a3 = ao.randn(1000, 10) +</pre></div> +<p> + Here we have made three AOs with different random white-noise data vectors. +</p> +<br> +<h2>Digression: plotting the data</h2> +<br> +<p> + To plot the data in the AO, you can use the intelligent plotting method, <tt>iplot</tt>. + For example, type in the MATLAB terminal: +</p> +<div class="fragment"><pre> + a1.iplot +</pre></div> +<p> + and you should see a plot like the one below. +</p> +<img src="images/ltpda_training_1/topic1/iplot1.png" alt="iplot example 1" border="1"> +<p> + We can make a more interesting plot if we first specify some of the properties + of the AOs. For example, type the following commands to set the names and + Y units of the two AOs we made earlier: +</p> +<div class="fragment"><pre> +a1.setName +a2.setName +setYunits(a1,a2,<span class="string">'N'</span>) +</pre></div> +<p> + Now plot both time-series together with: +</p> +<div class="fragment"><pre> +iplot(a1,a2) +</pre></div> +<p> + and you shoud see a plot like the following: +</p> +<img src="images/ltpda_training_1/topic1/iplot2.png" alt="iplot example 2" border="1"> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + Calling the <tt>setName</tt> method with no input argument causes the AO to be + named with the variable name. + </td> + </tr> + </table> +</p> +<p> + <tt>iplot</tt> has many configurable parameters which are (mostly) documented in the help. +</p> +<br> +<!-- Time-series waveform --> +<h2>Times-series AO from built in waveforms</h2> +<br> +<p> + MATLAB has various functions for creating standard waveforms, for example, + sine waves, square waves, and saw-tooth signals. These are available as + convenient AO constructors. For example suppose we want to create a + square-wave pulse train with a 30% duty cycle at 2Hz sampled at + 100Hz lasting for 5s, then we can do +</p> +<div class="fragment"><pre> +sw = ao(plist(<span class="string">'waveform'</span>, <span class="string">'square wave'</span>, <span class="string">'f'</span>, 2, <span class="string">'duty'</span>, 30, ... + <span class="string">'fs'</span>, 100, <span class="string">'nsecs'</span>, 5)) +</pre></div> +<p> + If you run that command and plot the result, you should see the square wave you were expecting: +</p> +<img src="images/ltpda_training_1/topic1/iplot_squarewave.png" alt="iplot squarewave" border="1"> +<p> + You can construct various different waveforms, but each has different parameters + to set. The help of the AO method details the possibilities (<tt>help ao -> click on "Parameters Description" -> select "From Window"</tt>); here is the relevant extract: +</p> +<div class="fragment"><pre> + 'waveform' - a waveform description (see options below). + + You can also specify additional parameters: + 'fs' - sampling frequency [default: 10 Hz] + 'nsecs' - length in seconds [default: 10 s] + 't0' - time-stamp of the first data sample [default time(0)] + + and, for the following waveform types: + 'sine wave' - 'A', 'f', 'phi', 'nsecs', 'toff' + (can be vectors for sum of sine waves) + 'A' - Amplitude of the wave + 'f' - Frequency of the wave + 'phi' - Phase of the eave + 'nsecs' - Number of seconds (in seconds) + 'toff' - Offset of the wave (in seconds) + 'gaps' - Instead of defining an offset it is possible to + define a gap (in seconds) before the sine wave. + 'noise' - 'type' (can be 'Normal' or 'Uniform') + 'sigma' specify the standard deviation + 'chirp' - 'f0', 'f1', 't1' (help chirp) + 'gaussian pulse' - 'f0', 'bw' (help gauspuls) + 'square wave' - 'f', 'duty' (help square) + 'sawtooth' - 'f', 'width' (help sawtooth) + + You can also specify the initial time (t0) associated with + the time-series by passing a parameter 't0' with a value + that is a time object. +</pre></div> + + + + + + </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="ltpda_training_topic_1_2.html"><img src= + "b_prev.gif" border="0" align="bottom" alt= + "Making AOs"></a> </td> + + <td align="left">Making AOs</td> + + <td> </td> + + <td align="right">Basic math with AOs</td> + + <td align="right" width="20"><a href= + "ltpda_training_topic_1_4.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Basic math with AOs"></a></td> + </tr> + </table><br> + + <p class="copy">©LTP Team</p> +</body> +</html>