Mercurial > hg > ltpda

comparison m-toolbox/html_help/help/ug/ltpda_training_topic_1_2.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 AOs (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_1.html"><img src="b_prev.gif" border="0" align=
30 "bottom" alt="Introducing Analysis Objects"></a>&nbsp;&nbsp;&nbsp;<a href=
31 "ltpda_training_topic_1_3.html"><img src="b_next.gif" border="0" align=
32 "bottom" alt="Making a time-series AO"></a></td>
33 </tr>
34 </table>
35
36 <h1 class="title"><a name="f3-12899" id="f3-12899"></a>Making AOs</h1>
37 <hr>
38
39 <p>
40
41 <h2>Exercise 1 - Your first Analysis Object</h2>
42
43 <p>
44 AOs can be constructed in many different ways. Each of the different ways is
45 called a constructor. For example, there is a constructor to make an AO from
46 a set of numeric values, there is also a constructor to make an AO from a data file.
47 Each time you construct an AO, you make an instance of the class, <tt>ao</tt>. The variable
48 you have in MATLAB is then just a reference to the object you constructed.
49 </p>
50 <p>
51 This may all sound confusing to start with, but will become clearer as we go
52 through the examples below.
53 </p>
54 <p>
55 Let's make an AO. On the MATLAB terminal, type the following: <tt>a = ao</tt> and hit return.
56 You should see an output like the following:
57 </p>
58 <div class="fragment"><pre>
59 >> a = ao()
60 M: running ao/ao
61 M: running ao/display
62 ----------- ao 01: a -----------
63
64 name: ''
65 data: None
66 hist: ao / ao / SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S
67 description:
68 UUID: bd0eb230-9fdf-40a1-85d7-c965532d7c7d
69 --------------------------------
70 </pre></div>
71 <p>
72 Note that the number of lines beginning with the "M:" syntax may vary depending on the level of "verbosity"
73 that can be set via the <a href="setup.html#prefs">LTPDA Preferences</a>
74 You have just made your first AO. It's not a very exciting AO since it
75 contains no data, but it is an AO nontheless. So now let's make an AO
76 with some data in it. Type the following in to the MATLAB terminal:
77 <tt>a = ao(1)</tt> and hit return. You should see
78 </p>
79 <div class="fragment"><pre>
80 >> a = ao(1)
81 ----------- ao 01: a -----------
82
83 name: ''
84 data: 1
85 -------- cdata 01 ------------
86 y: [1x1], double
87 dy: [0x0], double
88 yunits: []
89 ------------------------------
90
91 hist: ao / ao / SId: fromVals.m,v 1.36 2011/05/07 05:15:26 mauro Exp S-->SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S
92 description:
93 UUID: ff0c5bcc-3b79-473f-b608-c9585684fdee
94 --------------------------------
95 </pre></div>
96 <p>
97 Now you can see that your AO has some data. The data is of type <tt>cdata</tt>
98 (more on that later), it has no Y units, and it contains a single value, 1.
99 </p>
100 <p>
101 Note also that the information shown in the "hist" field may vary depending on the version of the LTPDA Toolbox you installed.
102 </p>
103 <p>
104 In addition to the standard MATLAB scripting interface, LTPDA offers a
105 graphical programming environment where the user can put together signal
106 processing pipelines by dragging and dropping blocks on to a canvas, then
107 joining up the blocks.
108 </p>
109 <p>
110 This graphical programming environment is called an LTPDA Workbench. To start
111 the workbench, issue the following command on the MATLAB terminal, or click on the
112 "LTPDA Workbench" button on the launch bay.
113 </p>
114 <div class="fragment"><pre>
115 LTPDAworkbench
116 </pre></div>
117 <p>
118 You should see a window like the one below:
119 </p>
120 <img src="images/ltpda_training_1/topic1/workbench_start.png" alt="Empty workbench" width="800px" border="1">
121 <p>
122
123 The use of the LTPDA workbench is quite intuitive, so hopefully playing around is sufficient.
124 Further details of using the workbench environment can be found in the <a href="lwb_intro.html">appropriate section</a>
125 of the user manual.
126 </p>
127 <p>
128 To construct the simple AO as we did above on the terminal, first create an empty pipeline in the
129 workbench by going to "Pipeline->New Pipeline" or hit <tt>ctrl-n</tt> (<tt>cmd-n</tt> on OS X).
130 Then you can drag an AO constructor block from the
131 Library on the left. You can also double click on the block in the library to add it to the canvas.
132 </p>
133 <br>
134 <br>
135 <img src="images/ltpda_training_1/topic1/lwb_ao_1.png" alt="AO1" border="2">
136 <br>
137 <br>
138 <p>
139 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
140 <tr width="90%">
141 <td>
142 Blocks can be added to the canvas using the "Quick Block" dialog. Hit <tt>ctrl-b</tt> (<tt>cmd-b</tt> on OS X)
143 on the canvas to open the quick block dialog. Begin typing to find the block you want (e.g. 'a' 'o') the
144 hit <tt>enter</tt> to add that block to the canvas. Hit <tt>enter</tt> to add multiple blocks the same. Hit
145 <tt>escape</tt> to dismiss the dialog.
146 </td>
147 </tr>
148 </table>
149 </p>
150 <p>
151 To set the value as we did on the terminal (<tt>ao(1)</tt>) we set some parameters on the block.
152 Follow these steps:
153 <ol>
154 <li>Click on the AO block to select it</li>
155 <li>It is not already selected, choose the "Properties" tab at the left of the workbench</li>
156 <li>Select the pre-defined parameter set "From Values" from the
157 drop-down menu located at the center of the tab<br>
158 <img src="images/ltpda_training_1/topic1/sets_combo.png" alt="Sets Combo Box" width="200px" border="2">
159 </li>
160 <li>You should see the parameter list like<br>
161 <img src="images/ltpda_training_1/topic1/fromValues_pset.png" alt="From Values Parameters" width="200px" border="2">
162 </li>
163 <li>To set this parameter list to the block, click the <tt>Set</tt> button below the parameter table</li>
164 <li>You can now edit this parameter list, for example, add or remove parameters or edit parameter key names and values.</li>
165 <li>Edit the value for the key "VALS" by double clicking on the table cell</li>
166 <li>A more sophisticated way to edit the parameter is available by clicking on the "Edit" symbol</li>
167 <li>Enter a new value (any MATLAB expression) in the dialog box and click the OK button</li>
168 <li>To set the name of the block, double-click it and enter a new name in the dialog box</li>
169 </ol>
170 </p>
171 <p>
172 You can now execute the pipeline by clicking on the play button <img src="images/ltpda_training_1/topic1/play_btn.png" width="30px" alt="Play">.
173 To display the result of your pipeline, select the blocks you are interested in the outputs of, then
174 you can click on the various 'output' buttons, available in the
175 "Control" tab:
176 </p>
177 <img src="images/ltpda_training_1/topic1/output_btns.png" alt="Output buttons" border="2">
178 <br>
179 <p>
180 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
181 <tr width="90%">
182 <td>
183 These output buttons only work if the pipeline has been successfully executed so that the
184 variables corresponding to the various blocks are in the MATLAB workspace. If the block
185 property "Keep Result" is set to "false", then the output buttons won't work for that block
186 because the result of executing that block is cleared from the MATLAB workspace as soon as
187 the result is no longer needed by other blocks.
188 </td>
189 </tr>
190 </table>
191 </p>
192
193 <br>
194 <br>
195 <!-- Setting properties -->
196 <h2>Exercise 2 - Setting properties of AOs</h2>
197 <br>
198 <br>
199
200 <p>
201 We can now go on and manipulate this AO. For example, suppose we want to
202 set its name. Type the following in to the MATLAB terminal: <tt>a.setName('Bob')</tt>
203 and hit enter. You should see:
204 </p>
205 <div class="fragment"><pre>
206 >> a.setName('Bob')
207 ----------- ao 01: Bob -----------
208
209 name: Bob
210 data: 1
211 -------- cdata 01 ------------
212 y: [1x1], double
213 dy: [0x0], double
214 yunits: []
215 ------------------------------
216
217 hist: ltpda_uoh / setName / SId: setName.m,v 1.18 2011/04/08 08:56:30 hewitson Exp S
218 description:
219 UUID: f87a3bc7-af10-4631-b9ad-6970bf38bf90
220 ----------------------------------
221 </pre></div>
222 <p>
223 The ao has a new name. The function (or more strictly, method) <tt>setName</tt> has acted on the AO, <tt>a</tt>.
224 An equivalent statement would be: <tt>setName(a, 'Bob')</tt>.
225 </p>
226 <p>
227 By doing this, you have modified <tt>a</tt>. If instead you do
228 </p>
229 <div class="fragment"><pre>
230 b = setName(a, <span class="string">'Bob'</span>)
231 </pre></div>
232 <p>
233 or
234 </p>
235 <div class="fragment"><pre>
236 b = a.setName(<span class="string">'Bob'</span>)
237 </pre></div>
238 <p>
239 then you get a new variable, <tt>b</tt>, which is a distinct (deep) copy of <tt>a</tt>.
240 The original AO, <tt>a</tt>, has not been modified. Try this out.
241 </p>
242 <p>
243 You can do the same on the workbench by using a <tt>setName</tt> block. To use the 'modifier' behaviour,
244 you set the block to be a modifier in the 'block properties' table:
245 </p>
246 <img src="images/ltpda_training_1/topic1/modifier_property.png" alt="Modifier Property" border="2">
247 <br>
248 <p>
249 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
250 <tr width="90%">
251 <td>
252 <p>On the workbench, the <tt>setName</tt> method is automatically called on the output of
253 constructor blocks so that the 'name' you give to a constructor block is set to the object
254 that's constructed. More about this later.
255 </td>
256 </tr>
257 </table>
258 </p>
259
260 <!-- Viewing history -->
261 <h2>Exercise 3 - Viewing the history</h2>
262 <p>
263 We can now look at the history of this object (in case our memory is really short).
264 The history can be viewed in different ways. For short history trees, the easiest
265 is to use the MATLAB-based history plotter built in to LTPDA. In the MATLAB terminal,
266 type plot(a.hist) and hit return. You should get a MATLAB figure looking something
267 like the picture below. You can see the only things we have done are to construct the
268 object and set its name.
269 </p>
270 <img src="images/ltpda_training_1/topic1/basic_history.png" alt="Basic History Plot" width="200px" border="1">
271 <p>
272 For very complicated history plots, LTPDA also supports viewing the history
273 using <a href="additional_progs.html">Graphviz</a>. If your machine has
274 graphviz already installed, and you've set this up in the <a href="ltpda_training_topic_1.html">LTPDA Preferences</a>,
275 then you can immediately do:
276 </p>
277 <div class="fragment"><pre>
278 dotview(a.hist, plist(<span class="string">'filename'</span>, <span class="string">'tmp.pdf'</span>))
279 <span class="comment">% or</span>
280 a.viewHistory();
281 </pre></div>
282 <p>
283 and you should get a figure something like that below in your system pdf
284 viewer.
285 </p>
286 <img src="images/ltpda_training_1/topic1/dot_history.png" alt="Dot History Plot" width="300px" border="1">
287 <p>
288 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
289 <tr width="90%">
290 <td>
291 <img src="images/ltpda_training_1/topic1/display_history_btn.png" alt="History Btn" border="1"><br>
292 When you click on the 'display history' button on the workbench, a filename created from combining
293 the pipeline name and the block name is used in the
294 call to <tt>dotview</tt>. You will find the PDF file in the current MATLAB working directory.
295 </td>
296 </tr>
297 </table>
298 </p>
299 <p>
300 Don't worry about all this <tt>plist</tt> business, we'll get to that soon
301 enough. For now it's enough to know that the conversion to pdf is done by
302 the graphviz engine, and this needs to write the pdf to a file.
303 That's the 'filename' specified in that last command.
304 </p>
305 <p>
306 Installation of graphviz is covered in the LTPDA user manual under the
307 section <a href="sysreqts.html">System Requirements</a>.
308 </p>
309 <p>
310 There is a third option for viewing the history: using the LTPDA Explorer.
311 On the MATLAB terminal, type <tt>ltpda_explorer</tt> and hit return, or click the
312 "Object Explorer" button on the LTPDA launch bay (see figure below). If the
313 launch bay is not open, you can open it with the command: <tt>ltpdalauncher</tt>.
314 </p>
315 <img src="images/ltpda_training_1/topic1/launchbay_explorer.png" alt="Launchbay with explorer highlighted" border="1">
316 <br>
317 <p>
318 Once you have launched the explorer, you can navigate through the various
319 LTPDA objects that are in your MATLAB workspace. Currently, if you add objects
320 to the MATLAB workspace, they will not appear in the LTPDA Explorer until you restart it.
321 </p>
322 <img src="images/ltpda_training_1/topic1/explorer.png" alt="Explorer" border="1">
323 <p>
324 We said earlier that the AO we created has no Y units set. If you look at
325 the output on the MATLAB terminal you will see that the Y units is actually
326 a property of the data, not of the AO. This is because the data inside the AO
327 is actually an object in its own right. There exist 4* data types in LTPDA:
328 </p>
329 <table cellspacing="0" class="body" cellpadding="2" border="0" width="80%">
330 <colgroup>
331 <col width="25%"/>
332 <col width="75%"/>
333 </colgroup>
334 <thead>
335 <tr valign="top">
336 <th class="categorylist">Data class</th>
337 <th class="categorylist">Description</th>
338 </tr>
339 </thead>
340 <tbody>
341 <!-- cdata -->
342 <tr valign="top">
343 <td bgcolor="#f3f4f5">
344 <p><tt>cdata</tt></p>
345 </td>
346 <td bgcolor="#f3f4f5">
347 <p>Intended for storing an arbitrary matrix of values. This class has
348 two main fields: the data itself is stored in the field <tt>y</tt>, and the
349 units of the data in <tt>yunits</tt>.</p>
350 </td>
351 </tr>
352
353 <!-- tsdata -->
354 <tr valign="top">
355 <td bgcolor="#f3f4f5">
356 <p><tt>tsdata</tt></p>
357 </td>
358 <td bgcolor="#f3f4f5">
359 <p>Intended for storing time-series data. More details on this one later.</p>
360 </td>
361 </tr>
362
363 <!-- fsdata -->
364 <tr valign="top">
365 <td bgcolor="#f3f4f5">
366 <p><tt>fsdata</tt></p>
367 </td>
368 <td bgcolor="#f3f4f5">
369 <p>For storing frequency-series data.</p>
370 </td>
371 </tr>
372
373 <!-- xydata -->
374 <tr valign="top">
375 <td bgcolor="#f3f4f5">
376 <p><tt>xydata</tt></p>
377 </td>
378 <td bgcolor="#f3f4f5">
379 <p>For storing an arbitrary set of x-y data pairs.</p>
380 </td>
381 </tr>
382
383 </tbody>
384 </table>
385
386 <p>
387 <i>* there is actually a 5th data type in development for storing X-Y-Z data, for example for time-frequency maps.</i>
388 </p>
389
390 <p>
391 Getting back to our Y units. To set the value of the Y units, the AO class
392 has a method called (not surprisingly) <tt>setYunits</tt>. To set the Y units
393 of this AO, type the following in to the MATLAB terminal: <tt>a.setYunits('km')</tt>
394 and hit return. You should see the following output:
395 </p>
396 <div class="fragment"><pre>
397 >> a.setYunits('km')
398 ----------- ao 01: Bob -----------
399
400 name: Bob
401 data: 1
402 -------- cdata 01 ------------
403 y: [1x1], double
404 dy: [0x0], double
405 yunits: [km]
406 ------------------------------
407
408 hist: ao / setYunits / SId: setYunits.m,v 1.26 2011/04/08 08:56:11 hewitson Exp S
409 description:
410 UUID: 6d2a14d6-a958-4a11-819f-164541b14783
411 ----------------------------------
412 </pre></div>
413 <p>
414 Now you see that the AO has Y units of 'km'. (To get a list of supported
415 units in ltpda, type the following command in to the MATLAB terminal:
416 <tt>unit.supportedUnits</tt>. To get a list of supported prefixes,
417 type <tt>unit.supportedPrefixes</tt>.)
418 </p>
419
420
421
422 </p>
423
424 <br>
425 <br>
426 <table class="nav" summary="Navigation aid" border="0" width=
427 "100%" cellpadding="0" cellspacing="0">
428 <tr valign="top">
429 <td align="left" width="20"><a href="ltpda_training_topic_1_1.html"><img src=
430 "b_prev.gif" border="0" align="bottom" alt=
431 "Introducing Analysis Objects"></a>&nbsp;</td>
432
433 <td align="left">Introducing Analysis Objects</td>
434
435 <td>&nbsp;</td>
436
437 <td align="right">Making a time-series AO</td>
438
439 <td align="right" width="20"><a href=
440 "ltpda_training_topic_1_3.html"><img src="b_next.gif" border="0" align=
441 "bottom" alt="Making a time-series AO"></a></td>
442 </tr>
443 </table><br>
444
445 <p class="copy">&copy;LTP Team</p>
446 </body>
447 </html>