Mercurial > hg > ltpda
diff m-toolbox/html_help/help/ug/ltpda_training_topic_1_2.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_2.html Wed Nov 23 19:22:13 2011 +0100 @@ -0,0 +1,447 @@ +<!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 AOs (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_1.html"><img src="b_prev.gif" border="0" align= + "bottom" alt="Introducing Analysis Objects"></a> <a href= + "ltpda_training_topic_1_3.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Making a time-series AO"></a></td> + </tr> + </table> + + <h1 class="title"><a name="f3-12899" id="f3-12899"></a>Making AOs</h1> + <hr> + + <p> + +<h2>Exercise 1 - Your first Analysis Object</h2> + +<p> + AOs can be constructed in many different ways. Each of the different ways is + called a constructor. For example, there is a constructor to make an AO from + a set of numeric values, there is also a constructor to make an AO from a data file. + Each time you construct an AO, you make an instance of the class, <tt>ao</tt>. The variable + you have in MATLAB is then just a reference to the object you constructed. +</p> +<p> + This may all sound confusing to start with, but will become clearer as we go + through the examples below. +</p> +<p> + Let's make an AO. On the MATLAB terminal, type the following: <tt>a = ao</tt> and hit return. + You should see an output like the following: +</p> +<div class="fragment"><pre> +>> a = ao() +M: running ao/ao +M: running ao/display +----------- ao 01: a ----------- + + name: '' + data: None + hist: ao / ao / SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S +description: + UUID: bd0eb230-9fdf-40a1-85d7-c965532d7c7d +-------------------------------- +</pre></div> +<p> +Note that the number of lines beginning with the "M:" syntax may vary depending on the level of "verbosity" + that can be set via the <a href="setup.html#prefs">LTPDA Preferences</a> + You have just made your first AO. It's not a very exciting AO since it + contains no data, but it is an AO nontheless. So now let's make an AO + with some data in it. Type the following in to the MATLAB terminal: + <tt>a = ao(1)</tt> and hit return. You should see +</p> + <div class="fragment"><pre> +>> a = ao(1) +----------- ao 01: a ----------- + + name: '' + data: 1 + -------- cdata 01 ------------ + y: [1x1], double + dy: [0x0], double + yunits: [] + ------------------------------ + + 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 +description: + UUID: ff0c5bcc-3b79-473f-b608-c9585684fdee +-------------------------------- +</pre></div> +<p> + Now you can see that your AO has some data. The data is of type <tt>cdata</tt> + (more on that later), it has no Y units, and it contains a single value, 1. +</p> +<p> + Note also that the information shown in the "hist" field may vary depending on the version of the LTPDA Toolbox you installed. +</p> +<p> + In addition to the standard MATLAB scripting interface, LTPDA offers a + graphical programming environment where the user can put together signal + processing pipelines by dragging and dropping blocks on to a canvas, then + joining up the blocks. +</p> +<p> + This graphical programming environment is called an LTPDA Workbench. To start + the workbench, issue the following command on the MATLAB terminal, or click on the + "LTPDA Workbench" button on the launch bay. +</p> +<div class="fragment"><pre> + LTPDAworkbench +</pre></div> +<p> + You should see a window like the one below: +</p> +<img src="images/ltpda_training_1/topic1/workbench_start.png" alt="Empty workbench" width="800px" border="1"> +<p> + + The use of the LTPDA workbench is quite intuitive, so hopefully playing around is sufficient. + Further details of using the workbench environment can be found in the <a href="lwb_intro.html">appropriate section</a> + of the user manual. +</p> +<p> + To construct the simple AO as we did above on the terminal, first create an empty pipeline in the + workbench by going to "Pipeline->New Pipeline" or hit <tt>ctrl-n</tt> (<tt>cmd-n</tt> on OS X). + Then you can drag an AO constructor block from the + Library on the left. You can also double click on the block in the library to add it to the canvas. +</p> +<br> +<br> +<img src="images/ltpda_training_1/topic1/lwb_ao_1.png" alt="AO1" border="2"> +<br> +<br> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + Blocks can be added to the canvas using the "Quick Block" dialog. Hit <tt>ctrl-b</tt> (<tt>cmd-b</tt> on OS X) + on the canvas to open the quick block dialog. Begin typing to find the block you want (e.g. 'a' 'o') the + hit <tt>enter</tt> to add that block to the canvas. Hit <tt>enter</tt> to add multiple blocks the same. Hit + <tt>escape</tt> to dismiss the dialog. + </td> + </tr> + </table> +</p> +<p> + To set the value as we did on the terminal (<tt>ao(1)</tt>) we set some parameters on the block. + Follow these steps: + <ol> + <li>Click on the AO block to select it</li> + <li>It is not already selected, choose the "Properties" tab at the left of the workbench</li> + <li>Select the pre-defined parameter set "From Values" from the + drop-down menu located at the center of the tab<br> + <img src="images/ltpda_training_1/topic1/sets_combo.png" alt="Sets Combo Box" width="200px" border="2"> + </li> + <li>You should see the parameter list like<br> + <img src="images/ltpda_training_1/topic1/fromValues_pset.png" alt="From Values Parameters" width="200px" border="2"> + </li> + <li>To set this parameter list to the block, click the <tt>Set</tt> button below the parameter table</li> + <li>You can now edit this parameter list, for example, add or remove parameters or edit parameter key names and values.</li> + <li>Edit the value for the key "VALS" by double clicking on the table cell</li> + <li>A more sophisticated way to edit the parameter is available by clicking on the "Edit" symbol</li> + <li>Enter a new value (any MATLAB expression) in the dialog box and click the OK button</li> + <li>To set the name of the block, double-click it and enter a new name in the dialog box</li> + </ol> +</p> +<p> + 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">. + To display the result of your pipeline, select the blocks you are interested in the outputs of, then + you can click on the various 'output' buttons, available in the + "Control" tab: +</p> +<img src="images/ltpda_training_1/topic1/output_btns.png" alt="Output buttons" border="2"> + <br> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + These output buttons only work if the pipeline has been successfully executed so that the + variables corresponding to the various blocks are in the MATLAB workspace. If the block + property "Keep Result" is set to "false", then the output buttons won't work for that block + because the result of executing that block is cleared from the MATLAB workspace as soon as + the result is no longer needed by other blocks. + </td> + </tr> + </table> +</p> + +<br> +<br> +<!-- Setting properties --> +<h2>Exercise 2 - Setting properties of AOs</h2> +<br> +<br> + +<p> + We can now go on and manipulate this AO. For example, suppose we want to + set its name. Type the following in to the MATLAB terminal: <tt>a.setName('Bob')</tt> + and hit enter. You should see: +</p> + <div class="fragment"><pre> +>> a.setName('Bob') +----------- ao 01: Bob ----------- + + name: Bob + data: 1 + -------- cdata 01 ------------ + y: [1x1], double + dy: [0x0], double + yunits: [] + ------------------------------ + + hist: ltpda_uoh / setName / SId: setName.m,v 1.18 2011/04/08 08:56:30 hewitson Exp S +description: + UUID: f87a3bc7-af10-4631-b9ad-6970bf38bf90 +---------------------------------- +</pre></div> +<p> + The ao has a new name. The function (or more strictly, method) <tt>setName</tt> has acted on the AO, <tt>a</tt>. + An equivalent statement would be: <tt>setName(a, 'Bob')</tt>. +</p> +<p> + By doing this, you have modified <tt>a</tt>. If instead you do +</p> +<div class="fragment"><pre> + b = setName(a, <span class="string">'Bob'</span>) +</pre></div> +<p> + or +</p> +<div class="fragment"><pre> + b = a.setName(<span class="string">'Bob'</span>) +</pre></div> +<p> + then you get a new variable, <tt>b</tt>, which is a distinct (deep) copy of <tt>a</tt>. + The original AO, <tt>a</tt>, has not been modified. Try this out. +</p> +<p> + You can do the same on the workbench by using a <tt>setName</tt> block. To use the 'modifier' behaviour, + you set the block to be a modifier in the 'block properties' table: +</p> +<img src="images/ltpda_training_1/topic1/modifier_property.png" alt="Modifier Property" border="2"> +<br> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + <p>On the workbench, the <tt>setName</tt> method is automatically called on the output of + constructor blocks so that the 'name' you give to a constructor block is set to the object + that's constructed. More about this later. + </td> + </tr> + </table> +</p> + +<!-- Viewing history --> +<h2>Exercise 3 - Viewing the history</h2> +<p> + We can now look at the history of this object (in case our memory is really short). + The history can be viewed in different ways. For short history trees, the easiest + is to use the MATLAB-based history plotter built in to LTPDA. In the MATLAB terminal, + type plot(a.hist) and hit return. You should get a MATLAB figure looking something + like the picture below. You can see the only things we have done are to construct the + object and set its name. +</p> +<img src="images/ltpda_training_1/topic1/basic_history.png" alt="Basic History Plot" width="200px" border="1"> +<p> + For very complicated history plots, LTPDA also supports viewing the history + using <a href="additional_progs.html">Graphviz</a>. If your machine has + graphviz already installed, and you've set this up in the <a href="ltpda_training_topic_1.html">LTPDA Preferences</a>, + then you can immediately do: +</p> +<div class="fragment"><pre> +dotview(a.hist, plist(<span class="string">'filename'</span>, <span class="string">'tmp.pdf'</span>)) +<span class="comment">% or</span> +a.viewHistory(); +</pre></div> +<p> + and you should get a figure something like that below in your system pdf + viewer. +</p> +<img src="images/ltpda_training_1/topic1/dot_history.png" alt="Dot History Plot" width="300px" border="1"> +<p> + <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1"> + <tr width="90%"> + <td> + <img src="images/ltpda_training_1/topic1/display_history_btn.png" alt="History Btn" border="1"><br> + When you click on the 'display history' button on the workbench, a filename created from combining + the pipeline name and the block name is used in the + call to <tt>dotview</tt>. You will find the PDF file in the current MATLAB working directory. + </td> + </tr> + </table> +</p> +<p> + Don't worry about all this <tt>plist</tt> business, we'll get to that soon + enough. For now it's enough to know that the conversion to pdf is done by + the graphviz engine, and this needs to write the pdf to a file. + That's the 'filename' specified in that last command. +</p> +<p> + Installation of graphviz is covered in the LTPDA user manual under the + section <a href="sysreqts.html">System Requirements</a>. +</p> +<p> + There is a third option for viewing the history: using the LTPDA Explorer. + On the MATLAB terminal, type <tt>ltpda_explorer</tt> and hit return, or click the + "Object Explorer" button on the LTPDA launch bay (see figure below). If the + launch bay is not open, you can open it with the command: <tt>ltpdalauncher</tt>. +</p> +<img src="images/ltpda_training_1/topic1/launchbay_explorer.png" alt="Launchbay with explorer highlighted" border="1"> + <br> +<p> + Once you have launched the explorer, you can navigate through the various + LTPDA objects that are in your MATLAB workspace. Currently, if you add objects + to the MATLAB workspace, they will not appear in the LTPDA Explorer until you restart it. +</p> +<img src="images/ltpda_training_1/topic1/explorer.png" alt="Explorer" border="1"> +<p> + We said earlier that the AO we created has no Y units set. If you look at + the output on the MATLAB terminal you will see that the Y units is actually + a property of the data, not of the AO. This is because the data inside the AO + is actually an object in its own right. There exist 4* data types in LTPDA: +</p> +<table cellspacing="0" class="body" cellpadding="2" border="0" width="80%"> + <colgroup> + <col width="25%"/> + <col width="75%"/> + </colgroup> + <thead> + <tr valign="top"> + <th class="categorylist">Data class</th> + <th class="categorylist">Description</th> + </tr> + </thead> + <tbody> + <!-- cdata --> + <tr valign="top"> + <td bgcolor="#f3f4f5"> + <p><tt>cdata</tt></p> + </td> + <td bgcolor="#f3f4f5"> + <p>Intended for storing an arbitrary matrix of values. This class has + two main fields: the data itself is stored in the field <tt>y</tt>, and the + units of the data in <tt>yunits</tt>.</p> + </td> + </tr> + + <!-- tsdata --> + <tr valign="top"> + <td bgcolor="#f3f4f5"> + <p><tt>tsdata</tt></p> + </td> + <td bgcolor="#f3f4f5"> + <p>Intended for storing time-series data. More details on this one later.</p> + </td> + </tr> + + <!-- fsdata --> + <tr valign="top"> + <td bgcolor="#f3f4f5"> + <p><tt>fsdata</tt></p> + </td> + <td bgcolor="#f3f4f5"> + <p>For storing frequency-series data.</p> + </td> + </tr> + + <!-- xydata --> + <tr valign="top"> + <td bgcolor="#f3f4f5"> + <p><tt>xydata</tt></p> + </td> + <td bgcolor="#f3f4f5"> + <p>For storing an arbitrary set of x-y data pairs.</p> + </td> + </tr> + + </tbody> +</table> + +<p> + <i>* there is actually a 5th data type in development for storing X-Y-Z data, for example for time-frequency maps.</i> +</p> + +<p> + Getting back to our Y units. To set the value of the Y units, the AO class + has a method called (not surprisingly) <tt>setYunits</tt>. To set the Y units + of this AO, type the following in to the MATLAB terminal: <tt>a.setYunits('km')</tt> + and hit return. You should see the following output: +</p> +<div class="fragment"><pre> +>> a.setYunits('km') +----------- ao 01: Bob ----------- + + name: Bob + data: 1 + -------- cdata 01 ------------ + y: [1x1], double + dy: [0x0], double + yunits: [km] + ------------------------------ + + hist: ao / setYunits / SId: setYunits.m,v 1.26 2011/04/08 08:56:11 hewitson Exp S +description: + UUID: 6d2a14d6-a958-4a11-819f-164541b14783 +---------------------------------- +</pre></div> +<p> + Now you see that the AO has Y units of 'km'. (To get a list of supported + units in ltpda, type the following command in to the MATLAB terminal: + <tt>unit.supportedUnits</tt>. To get a list of supported prefixes, + type <tt>unit.supportedPrefixes</tt>.) +</p> + + + + </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_1.html"><img src= + "b_prev.gif" border="0" align="bottom" alt= + "Introducing Analysis Objects"></a> </td> + + <td align="left">Introducing Analysis Objects</td> + + <td> </td> + + <td align="right">Making a time-series AO</td> + + <td align="right" width="20"><a href= + "ltpda_training_topic_1_3.html"><img src="b_next.gif" border="0" align= + "bottom" alt="Making a time-series AO"></a></td> + </tr> + </table><br> + + <p class="copy">©LTP Team</p> +</body> +</html>