Mercurial > hg > ltpda

comparison m-toolbox/html_help/help/ug/ltpda_training_topic_1_3.html @ 0:f0afece42f48

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import.
author Daniele Nicolodi <nicolodi@science.unitn.it>
date Wed, 23 Nov 2011 19:22:13 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:f0afece42f48
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
3
4 <html lang="en">
5 <head>
6 <meta name="generator" content=
7 "HTML Tidy for Mac OS X (vers 1st December 2004), see www.w3.org">
8 <meta http-equiv="Content-Type" content=
9 "text/html; charset=us-ascii">
10
11 <title>Making a time-series AO (LTPDA Toolbox)</title>
12 <link rel="stylesheet" href="docstyle.css" type="text/css">
13 <meta name="generator" content="DocBook XSL Stylesheets V1.52.2">
14 <meta name="description" content=
15 "Presents an overview of the features, system requirements, and starting the toolbox.">
16 </head>
17
18 <body>
19 <a name="top_of_page" id="top_of_page"></a>
20
21 <p style="font-size:1px;">&nbsp;</p>
22
23 <table class="nav" summary="Navigation aid" border="0" width=
24 "100%" cellpadding="0" cellspacing="0">
25 <tr>
26 <td valign="baseline"><b>LTPDA Toolbox</b></td><td><a href="../helptoc.html">contents</a></td>
27
28 <td valign="baseline" align="right"><a href=
29 "ltpda_training_topic_1_2.html"><img src="b_prev.gif" border="0" align=
30 "bottom" alt="Making AOs"></a>&nbsp;&nbsp;&nbsp;<a href=
31 "ltpda_training_topic_1_4.html"><img src="b_next.gif" border="0" align=
32 "bottom" alt="Basic math with AOs"></a></td>
33 </tr>
34 </table>
35
36 <h1 class="title"><a name="f3-12899" id="f3-12899"></a>Making a time-series AO</h1>
37 <hr>
38
39 <p>
40 <h2>Exercise 4</h2>
41 <p>
42 Time-series data are stored in a data object of the class <tt>tsdata</tt>.
43 As a user, you don't need to care about this, but it's sometimes
44 nice to know how things work. There are various ways (constructors)
45 to build time-series AOs. For example, you can give a set of values and
46 a sample rate like
47 </p>
48 <div class="fragment"><pre>
49 a = ao([1 2 3 4 5], 2)
50 </pre></div>
51 <p>
52 The first argument is the Y data vector; the second, the sample rate.
53 </p>
54 <p>
55 If you run this command in the MATLAB terminal you should see
56 </p>
57 <div class="fragment"><pre>
58 >> a = ao([1 2 3 4 5], 2)
59 M: constructing from Y values and fs
60 ----------- ao 01: a -----------
61
62 name: ''
63 data: (0,1) (0.5,2) (1,3) (1.5,4) (2,5)
64 -------- tsdata 01 ------------
65
66 fs: 2
67 x: [1 5], double
68 y: [1 5], double
69 dx: [0 0], double
70 dy: [0 0], double
71 xunits: [s]
72 yunits: []
73 nsecs: 2.5
74 t0: 1970-01-01 00:00:00.000
75 -------------------------------
76
77 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
78 description:
79 UUID: 2484d029-4616-4b22-8229-7685c8d3e847
80 --------------------------------
81 </pre></div>
82 <p>
83 Now you see that the data type is <tt>tsdata</tt> and the X units are automatically
84 set to seconds ('s'). You can also see that the data series spans 2.5s
85 and that the first sample corresponds to 1970-01-01 00:00:00.000 UTC.
86 You can set further properties of the object, for example
87 </p>
88 <p>
89 <div class="fragment"><pre>
90 a.setT0(<span class="string">'2009-02-03 12:23:44'</span>);
91 a.setDescription(<span class="string">'My lovely time-series'</span>)
92 </pre></div>
93 </p>
94 <br>
95 <p>
96 You can do all of this in one block on the workbench. To do that:
97 <ol>
98 <li>Start the workbench and create a new pipeline</li>
99 <li>Drag an AO constructor block from the library (or use "Quick Block")</li>
100 <li>Select the block and select the "From XY Values" parameter set</li>
101 <li>Click the "Set" button to set the parameters to the block</li>
102 <li>Double-click the value cell for the key "YVALS" and enter some values, e.g., <tt>1:10</tt></li>
103 <li>Double-click the value cell for the key "FS" and enter a sample frequency, e.g., <tt>2</tt>. By
104 setting a set of values for the Y-data and a sample rate, we tell the AO constructor that we want to
105 build a <tt>tsdata</tt> AO.</li>
106 <li>To set the name of the block, double click the block and enter a name in the dialog box. Automatic
107 setting of AO names from the block name only happens for constructor blocks. To the set the name of AOs
108 which are outputs of all other block types, use the <tt>setName</tt> block.
109 </li>
110 <li>You'll notice that the parameter list doesn't contain a <tt>T0</tt> parameter by default, but you can
111 easily add this parameter by clicking on the "plus" button below the parameter list. Enter the key <tt>T0</tt>
112 in the dialog box, and an appropriate value in the next dialog box. (Note: parameter key names are case
113 insensitive.)</li>
114 <li>You can do the same for the description, or any other property of the AO.</li>
115 </ol>
116 </p>
117 <p>
118 The final parameter list in this case might look like:
119 </p>
120 <img src="images/ltpda_training_1/topic1/tsdata_pset.png" alt="Time-series parameter set" border="1">
121
122 <br>
123 <br>
124 <!-- Plists -->
125 <h2>Digression: Introducing parameter lists</h2>
126 <br>
127 <p>
128 The time has come to go back to that <tt>plist</tt> command we saw earlier when plotting
129 the AO history via the graphviz renderer.
130 </p>
131 <p>
132 The following two commands are equivalent:
133 </p>
134 <div class="fragment"><pre>
135 a = ao([1 2 3 4 5], 2);
136 a = ao(plist(<span class="string">'yvals'</span>, [1 2 3 4 5], <span class="string">'fs'</span>, 2))
137 </pre></div>
138 <p>
139 Here we introduce the idea of parameter lists (<tt>plist</tt>). A <tt>plist</tt> is a list
140 of parameters, each parameter being defined by a key/value pair. The key of
141 a <tt>plist</tt> is always a string and is always case insensitive. The value can be
142 anything: a number, a string, another LTPDA object, a cell-array, a structure, etc. For more
143 information about parameter lists, see the <a href="plist_intro.html">appropriate section</a>
144 of the LTPDA user manual.
145 </p>
146 <p>
147 Going on with time-series objects: The following is almost equivalent:
148 </p>
149 <div class="fragment"><pre>
150 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]))
151 </pre></div>
152 <p>
153 The difference is, if you run this command, you will see that the resulting
154 AO has data of type <tt>xydata</tt>. To make this a time-series object,
155 we need to tell the constructor some more information. Either you need to
156 specify the sample-rate, or you can explicitly set the data type:
157 </p>
158 <div class="fragment"><pre>
159 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))
160 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>,...
161 <span class="string">'tsdata'</span>))
162 </pre></div>
163 <p>
164 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
165 <tr width="90%">
166 <td>
167 The elipsis (<tt>...</tt>) in MATLAB means join the two lines.
168 </td>
169 </tr>
170 </table>
171 </p>
172 <p>
173 If you specify the samples rate with the key 'fs', then the 'xvals'
174 are just ignored. If you tell the data type with the key 'type', then
175 the sample rate is computed from the 'xvals'.
176 </p>
177 <p>
178 You can add additional parameters to these constructor lines. For example,
179 </p>
180 <div class="fragment"><pre>
181 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], ...
182 <span class="string">'type'</span>, <span class="string">'tsdata'</span>, ...
183 <span class="string">'name'</span>, <span class="string">'Bob'</span>, ...
184 <span class="string">'t0'</span>, <span class="string">'2008-09-01'</span>))
185 </pre></div>
186 <p>
187 There are other constructors which make constructing time-series AOs from
188 simulated data more convenient. Two of these are discussed below.
189 </p>
190 <br>
191 <!-- Time-series f(t) -->
192 <h2>Times-series AO as a function of <tt>t</tt></h2>
193 <br>
194 <p>
195 If you want to specify your time-series as a function of the variable <tt>t</tt>,
196 then you can use the following constructor:
197 </p>
198 <div class="fragment"><pre>
199 a = ao(plist(<span class="string">'tsfcn'</span>, <span class="string">'t.^2 + t'</span>, ...
200 <span class="string">'fs'</span>, 10, <span class="string">'nsecs'</span>, 1000))
201 </pre></div>
202 <p>
203 You specify the function of t with the key 'tsfcn', then give the sample
204 rate and the number of seconds. If you run this command you should see the output:
205 </p>
206 <div class="fragment"><pre>
207 >> a = ao(plist('tsfcn', 't.^2 + t', 'fs', 10, 'nsecs', 1000))
208 M: constructing from plist
209 ----------- ao 01: a -----------
210
211 name: ''
212 data: (0,0) (0.1,0.11) (0.2,0.24) (0.3,0.39) (0.4,0.56) ...
213 -------- tsdata 01 ------------
214
215 fs: 10
216 x: [10000 1], double
217 y: [10000 1], double
218 dx: [0 0], double
219 dy: [0 0], double
220 xunits: [s]
221 yunits: []
222 nsecs: 1000
223 t0: 1970-01-01 00:00:00.000
224 -------------------------------
225
226 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
227 description:
228 UUID: d01615d6-82ad-4736-8a0e-4096dc023149
229 --------------------------------
230 </pre></div>
231 <p>
232 You can write any valid MATLAB expression as a function of <tt>t</tt>.
233 </p>
234 <p>
235 Plists can be reused, of course. Suppose we define a recipe for an AO as
236 </p>
237 <div class="fragment"><pre>
238 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)
239 </pre></div>
240 <p>
241 then we can make repeated AOs from this recipe:
242 </p>
243 <div class="fragment"><pre>
244 a1 = ao(pl)
245 a2 = ao(pl)
246 <span class="comment">% Or use the random factory:</span>
247 <span class="comment">% a = ao.randn(nsecs, fs)</span>
248 a3 = ao.randn(1000, 10)
249 </pre></div>
250 <p>
251 Here we have made three AOs with different random white-noise data vectors.
252 </p>
253 <br>
254 <h2>Digression: plotting the data</h2>
255 <br>
256 <p>
257 To plot the data in the AO, you can use the intelligent plotting method, <tt>iplot</tt>.
258 For example, type in the MATLAB terminal:
259 </p>
260 <div class="fragment"><pre>
261 a1.iplot
262 </pre></div>
263 <p>
264 and you should see a plot like the one below.
265 </p>
266 <img src="images/ltpda_training_1/topic1/iplot1.png" alt="iplot example 1" border="1">
267 <p>
268 We can make a more interesting plot if we first specify some of the properties
269 of the AOs. For example, type the following commands to set the names and
270 Y units of the two AOs we made earlier:
271 </p>
272 <div class="fragment"><pre>
273 a1.setName
274 a2.setName
275 setYunits(a1,a2,<span class="string">'N'</span>)
276 </pre></div>
277 <p>
278 Now plot both time-series together with:
279 </p>
280 <div class="fragment"><pre>
281 iplot(a1,a2)
282 </pre></div>
283 <p>
284 and you shoud see a plot like the following:
285 </p>
286 <img src="images/ltpda_training_1/topic1/iplot2.png" alt="iplot example 2" border="1">
287 <p>
288 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
289 <tr width="90%">
290 <td>
291 Calling the <tt>setName</tt> method with no input argument causes the AO to be
292 named with the variable name.
293 </td>
294 </tr>
295 </table>
296 </p>
297 <p>
298 <tt>iplot</tt> has many configurable parameters which are (mostly) documented in the help.
299 </p>
300 <br>
301 <!-- Time-series waveform -->
302 <h2>Times-series AO from built in waveforms</h2>
303 <br>
304 <p>
305 MATLAB has various functions for creating standard waveforms, for example,
306 sine waves, square waves, and saw-tooth signals. These are available as
307 convenient AO constructors. For example suppose we want to create a
308 square-wave pulse train with a 30% duty cycle at 2Hz sampled at
309 100Hz lasting for 5s, then we can do
310 </p>
311 <div class="fragment"><pre>
312 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, ...
313 <span class="string">'fs'</span>, 100, <span class="string">'nsecs'</span>, 5))
314 </pre></div>
315 <p>
316 If you run that command and plot the result, you should see the square wave you were expecting:
317 </p>
318 <img src="images/ltpda_training_1/topic1/iplot_squarewave.png" alt="iplot squarewave" border="1">
319 <p>
320 You can construct various different waveforms, but each has different parameters
321 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:
322 </p>
323 <div class="fragment"><pre>
324 'waveform' - a waveform description (see options below).
325
326 You can also specify additional parameters:
327 'fs' - sampling frequency [default: 10 Hz]
328 'nsecs' - length in seconds [default: 10 s]
329 't0' - time-stamp of the first data sample [default time(0)]
330
331 and, for the following waveform types:
332 'sine wave' - 'A', 'f', 'phi', 'nsecs', 'toff'
333 (can be vectors for sum of sine waves)
334 'A' - Amplitude of the wave
335 'f' - Frequency of the wave
336 'phi' - Phase of the eave
337 'nsecs' - Number of seconds (in seconds)
338 'toff' - Offset of the wave (in seconds)
339 'gaps' - Instead of defining an offset it is possible to
340 define a gap (in seconds) before the sine wave.
341 'noise' - 'type' (can be 'Normal' or 'Uniform')
342 'sigma' specify the standard deviation
343 'chirp' - 'f0', 'f1', 't1' (help chirp)
344 'gaussian pulse' - 'f0', 'bw' (help gauspuls)
345 'square wave' - 'f', 'duty' (help square)
346 'sawtooth' - 'f', 'width' (help sawtooth)
347
348 You can also specify the initial time (t0) associated with
349 the time-series by passing a parameter 't0' with a value
350 that is a time object.
351 </pre></div>
352
353
354
355
356
357 </p>
358
359 <br>
360 <br>
361 <table class="nav" summary="Navigation aid" border="0" width=
362 "100%" cellpadding="0" cellspacing="0">
363 <tr valign="top">
364 <td align="left" width="20"><a href="ltpda_training_topic_1_2.html"><img src=
365 "b_prev.gif" border="0" align="bottom" alt=
366 "Making AOs"></a>&nbsp;</td>
367
368 <td align="left">Making AOs</td>
369
370 <td>&nbsp;</td>
371
372 <td align="right">Basic math with AOs</td>
373
374 <td align="right" width="20"><a href=
375 "ltpda_training_topic_1_4.html"><img src="b_next.gif" border="0" align=
376 "bottom" alt="Basic math with AOs"></a></td>
377 </tr>
378 </table><br>
379
380 <p class="copy">&copy;LTP Team</p>
381 </body>
382 </html>