Mercurial > hg > ltpda
view m-toolbox/html_help/help/ug/ltpda_training_topic_1_2.html @ 21:8be9deffe989 database-connection-manager
Update ltpda_uo.update
| author | Daniele Nicolodi <nicolodi@science.unitn.it> |
|---|---|
| date | Mon, 05 Dec 2011 16:20:06 +0100 |
| parents | f0afece42f48 |
| children |
line wrap: on
line source
<!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>