Mercurial > hg > ltpda

comparison m-toolbox/html_help/help/ug/extensions_intro.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>LTPDA Extension Modules (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 "repo_gui_retrieve.html"><img src="b_prev.gif" border="0" align=
30 "bottom" alt="Retrieving objects and collections from a repository"></a>&nbsp;&nbsp;&nbsp;<a href=
31 "class_desc_main.html"><img src="b_next.gif" border="0" align=
32 "bottom" alt="Class descriptions"></a></td>
33 </tr>
34 </table>
35
36 <h1 class="title"><a name="f3-12899" id="f3-12899"></a>LTPDA Extension Modules</h1>
37 <hr>
38
39 <p>
40 <p>
41 As of Version 2.4, LTPDA now supports extension modules. This should allow
42 users to extend LTPDA to provide more specific functionalities for their own
43 context.
44 </p>
45 <p>
46 <ul>
47 <li><a href="#whatis">What is an Extension Module?</a></li>
48 <li><a href="#building">Building your own Extension Module</a></li>
49 <li><a href="#installing">Installing Extension Modules</a></li>
50 <li><a href="#newmethods">Adding New Methods</a></li>
51 <li><a href="#userclasses">New User Classes</a></li>
52 <li><a href="#unittests">Unit Tests</a></li>
53 </ul>
54 </p>
55 <br><br>
56 <h2><a name="whatis">What is an Extension Module?</a></h2>
57 <p>
58 Extension modules are a collection of class methods, new user classes, built-in models,
59 utility functions, examples, source files, and unit tests. All extension modules have the
60 following structure on disk:
61 <pre>
62 My_Module/
63 |-- README.txt
64 |-- classes
65 | |-- README_classes.txt
66 |-- examples
67 |-- functions
68 | |-- README_functions.txt
69 |-- jar
70 | |-- README_jar.txt
71 |-- models
72 | |-- README_models.txt
73 |-- moduleinfo.xml
74 |-- pipelines
75 | |-- README_pipelines.txt
76 |-- tests
77 |-- README_tests.txt
78 |-- classes
79 | |-- README_class_tests.txt
80 |-- models
81 |-- README_model_tests.txt
82 </pre>
83 The file <tt>moduleinfo.xml</tt> contains the name and version of the module. It is
84 not necessary that the module name and the containing directory are the same, though
85 they may be. To build an extension module, see Section <a href="#building">Building your own Extension Module</a>. The various
86 directories and their uses are described in the following sections.
87 </p>
88
89 <h3>classes</h3>
90 <p>
91 The <tt>classes</tt> directory can contain either new LTPDA user classes (see Section <a href="#userclasses">New User Classes</a>)
92 or by adding methods to existing LTPDA user classes (see Section <a href="#newmethods">Adding New Methods</a>).
93 </p>
94
95 <h3>examples</h3>
96 <p>
97 The <tt>examples</tt> directory is meant to contain useful examples for users.
98 </p>
99
100 <h3>jar</h3>
101 <p>
102 Since MATLAB is built on top of java, one useful way to extend the functionalities is to create java classes and methods, or even
103 graphical user interfaces. The LTPDA startup script (<tt>ltpda_startup</tt>) will take care of properly installing any jar files (java archive files)
104 contained within this directory.
105 </p>
106
107 <h3>models</h3>
108 <p>
109 Here you should place any built-in models, either for existing LTPDA user classes, or for new user classes defined in this module. The LTPDA
110 built-in model framework looks in this directory (and any sub-directories) for built-in models.
111 </p>
112
113 <h3>pipelines</h3>
114 <p>
115 This directory is meant to hold any LTPDA pipelines or analysis workflows which you want to distribute to users.
116 </p>
117
118 <h3>tests</h3>
119 <p>
120 The <tt>tests</tt> directory should contain unit-tests for all new class methods, user classes and built-in models in this module. For help in writing
121 unit tests see Section <a href="#unittests">Unit Tests</a>.
122 </p>
123
124
125 <br><br>
126 <h2><a name="building">Building your own Extension Module</a></h2>
127
128 <p>
129 Building your own extension modules starts by preparing the directory structure on disk. For this
130 we have a convenient utility method:
131 </p>
132 <div class="fragment"><pre>
133 >> utils.modules.buildModule(<span class="string">'/some/path/'</span>, <span class="string">'My_Module'</span>)
134 </pre></div>
135
136 <br><br>
137 <h2><a name="installing">Installing Extension Modules</a></h2>
138 <p>
139 Installing an LTPDA Extension Module is straightforward. Start the LTPDA Preferences:
140 </p>
141 <div class="fragment"><pre>
142 >> LTPDAprefs
143 </pre></div>
144 <p>
145 Select the 'Extensions' tab. Click the 'Browse' button to locate the module directory on disk, or directly type the path to the module in the input text field.
146 Click the 'plus' button to add this extension to the list. You should see some activity on the MATLAB terminal as LTPDA will start installing any
147 extension methods for existing user classes. Removing an extension module is just a case of selecting the module in the list and clicking the 'minus'
148 button.
149 </p>
150 <p>
151 <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
152 <tr width="90%">
153 <td>
154 Note: after installing an extension module, in order to make new methods available to the workbench, you need to rebuild the
155 library from the workbench menu: "Tools -> Rebuild LTPDA Library". This will take a couple of minutes, but afterwards
156 the new methods from the extension module should be available on the workbench.
157 </td>
158 </tr>
159 </table>
160 </p>
161
162 <br><br>
163 <h2><a name="newmethods">Adding New Methods</a></h2>
164 <p>
165 New methods can be added to existing LTPDA user classes. For example, you can add a new method to the Analysis Object class (<tt>ao</tt>)
166 by creating a sub-directory of the <tt>classes</tt> directory called <tt>ao</tt> then put your new method in there. For example, suppose
167 we want to create a new AO method called <tt>myCalibration</tt>. We create a directory <tt>ao</tt> in <tt>My_Module/classes</tt> then add
168 the new file <tt>myCalibration.m</tt> to that directory. In order for the new method to work, the LTPDA startup function <tt>ltpda_startup</tt>
169 copies all methods for core LTPDA user classes in to their correct class directories. In order to write a correct LTPDA user-class method, it
170 is recommended to look at some examples, such as <tt>ao/abs</tt>, <tt>ao/average</tt>, or <tt>ao/psd</tt>. You can also extend other existing user
171 classes in the same way. Just make a directory of the correct class name (remember to leave off the <tt>@</tt> from the directory name; this is not supposed to
172 be a 'normal' MATLAB class directory) and put your new methods in there.
173 </p>
174
175 <br><br>
176 <h2><a name="userclasses">New User Classes</a></h2>
177 <p>
178 This is an advanced topic, and it is assumed that you are familiary with
179 creating MATLAB classes already. To get familiar, read the MATLAB documentation on Object-Oriented Programming in the user manual.
180 </p>
181 <p>
182 You can create new user classes in the <tt>classes</tt> directory. These follow MATLAB rules for classes, i.e., the directory name begins with a <tt>@</tt>
183 and contains a constructor file with the same name. For example, suppose we want to create a new user class which stores trigger events from some experiment.
184 Each trigger event has the following properties: a trigger time, an amplitude, and a frequency. We would create a new directory under <tt>classes</tt> called
185 <tt>@Trigger</tt> and an associated constructor file like this:
186
187 </p>
188 <div class="fragment"><pre>
189 >> cd <span class="string">'My_Module/classes'</span>
190 >> mkdir <span class="string">@Trigger</span>
191 >> edit <span class="string">@Trigger/Trigger.m</span>
192 </pre></div>
193 <p>
194 The constructor file should declare that this new Trigger class is a subclass of the LTPDA user-object base class <tt>ltpda_uoh</tt>.
195 </p>
196 <div class="fragment"><pre>
197 <span class="comment">% TRIGGER constructor for Trigger class.</span>
198 <span class="comment">%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%</span>
199 <span class="comment">%</span>
200 <span class="comment">% DESCRIPTION: TRIGGER constructor for Trigger class.</span>
201 <span class="comment">%</span>
202 <span class="comment">% CONSTRUCTOR:</span>
203 <span class="comment">%</span>
204 <span class="comment">% t = Trigger() - creates an empty trigger object</span>
205 <span class="comment">%</span>
206 <span class="comment">% <a href="matlab:utils.helper.displayMethodInfo('Trigger', 'Trigger')">Parameter Sets</a></span>
207 <span class="comment">%</span>
208 <span class="comment">% VERSION: $Id: extensions_intro_content.html,v 1.2 2011/04/29 07:23:31 hewitson Exp $</span>
209 <span class="comment">%</span>
210 <span class="comment">%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%</span>
211
212 classdef Trigger < ltpda_uoh
213
214 %---------- Public (read/write) Properties ----------
215 properties
216 time = time();
217 amplitude = [];
218 frequency = [];
219 end
220
221 methods
222 function obj = Trigger(varargin)
223
224 import utils.const.*
225 utils.helper.msg(msg.PROC3, <span class="string">'running %s/%s'</span>, mfilename(<span class="string">'class'</span>), mfilename);
226
227 <span class="comment">% do some initialisation of the object</span>
228
229 end <span class="comment">% End constructor</span>
230
231 end
232
233 end
234 </pre></div>
235 <p>
236 Various methods need to be defined by any new user class, in particular, the following abstract methods need to be created:
237 <table cellspacing="0" class="body" cellpadding="4" border="2">
238 <colgroup>
239 <col width="20%">
240 <col width="80%">
241 </colgroup>
242 <thead>
243 <tr valign="top">
244 <th bgcolor="#B2B2B2">Method name</th>
245 <th bgcolor="#B2B2B2">Description</th>
246 </tr>
247 </thead>
248 <tbody>
249 <!-- attachToDom -->
250 <tr valign="top">
251 <td bgcolor="#F2F2F2">
252 <p>attachToDom</p>
253 </td>
254 <td bgcolor="#F2F2F2">
255 <p>Defines how the object is serialized to an XML DOM.</p>
256 </td>
257 </tr>
258 <!-- char -->
259 <tr valign="top">
260 <td bgcolor="#F2F2F2">
261 <p>char</p>
262 </td>
263 <td bgcolor="#F2F2F2">
264 <p>Creates a character representation of the object, typically for use in display.</p>
265 </td>
266 </tr>
267 <!-- copy -->
268 <tr valign="top">
269 <td bgcolor="#F2F2F2">
270 <p>copy</p>
271 </td>
272 <td bgcolor="#F2F2F2">
273 <p>Makes a deep or shallow copy of the object, depending on the passed argument.</p>
274 </td>
275 </tr>
276 <!-- display -->
277 <tr valign="top">
278 <td bgcolor="#F2F2F2">
279 <p>display</p>
280 </td>
281 <td bgcolor="#F2F2F2">
282 <p>Defines how the object is displayed on the MATLAB terminal.</p>
283 </td>
284 </tr>
285 <!-- fromDom -->
286 <tr valign="top">
287 <td bgcolor="#F2F2F2">
288 <p>fromDom</p>
289 </td>
290 <td bgcolor="#F2F2F2">
291 <p>Constructs an object from an XML DOM.</p>
292 </td>
293 </tr>
294 <!-- loadobj -->
295 <tr valign="top">
296 <td bgcolor="#F2F2F2">
297 <p>loadobj</p>
298 </td>
299 <td bgcolor="#F2F2F2">
300 <p>This function is called is MATLAB is unable to load an object from a MAT file, for example if the class structure changes between versions. This gives an opportunity to update the loaded structure before trying to create an object from it. For more details, see MATLAB's help topic <tt>>>help loadobj</tt></p>
301 </td>
302 </tr>
303 <!-- update_struct -->
304 <tr valign="top">
305 <td bgcolor="#F2F2F2">
306 <p>update_struct</p>
307 </td>
308 <td bgcolor="#F2F2F2">
309 <p>Define rules how to update structure representation of an object between versions.</p>
310 </td>
311 </tr>
312 <!-- generateConstructorPlist -->
313 <tr valign="top">
314 <td bgcolor="#F2F2F2">
315 <p>generateConstructorPlist</p>
316 </td>
317 <td bgcolor="#F2F2F2">
318 <p>Given an instance of the user object, this method generates a plist which can be used to construct an object with the same properties.</p>
319 </td>
320 </tr>
321 </tbody>
322 </table>
323 In most cases, copying these methods from an existing LTPDA user class, for example, <tt>ao</tt>, is a good start.
324 </p>
325 <p>
326 In addition to defining these abstract methods, you typically need to overload some static methods (which we usually place inside the class constructor file). The following
327 code fragment shows the necessary methods needed to complete our Trigger example.
328 </p>
329
330 <div class="fragment"><pre>
331 methods (Static)
332
333 <span class="comment">% This provides the hook for the command <tt>&lt;class&gt;.getBuiltInModels</tt>. </span>
334 function mdls = getBuiltInModels(varargin)
335 mdls = ltpda_uo.getBuiltInModels(<span class="string">'Trigger'</span>);
336 end
337
338 <span class="comment">% Here we typically return the CVS version or some other version string </span>
339 function out = VEROUT()
340 out = <span class="string">'$Id: extensions_intro_content.html,v 1.2 2011/04/29 07:23:31 hewitson Exp $'</span>;
341 end
342
343 <span class="comment">% This provides the hook for the command <tt>&lt;class&gt;.getInfo</tt>. </span>
344 function ii = getInfo(varargin)
345 ii = utils.helper.generic_getInfo(varargin{:}, <span class="string">'Trigger'</span>);
346 end
347
348 <span class="comment">% Here we return a list of parameter sets that this constructor can handle. </span>
349 function out = SETS()
350 out = [SETS@ltpda_uoh, ...
351 {'<span class="string">Default'</span>} ...
352 ];
353 end
354
355
356 <span class="comment">% This returns a parameter list for a given parameter set. </span>
357 <span class="comment">% The use of the MATLAB 'persistent' keyword means we don't repeatedly build the same plist.</span>
358 function plout = getDefaultPlist(set)
359 persistent pl;
360 persistent lastset;
361 if exist(<span class="string">'pl'</span>, <span class="string">'var'</span>)==0 || isempty(pl) || ~strcmp(lastset, set)
362 pl = Trigger.buildplist(set);
363 lastset = set;
364 end
365 plout = pl;
366 end
367
368 <span class="comment">% This builds a parameter list for the given set name. </span>
369 function out = buildplist(set)
370
371 if ~utils.helper.ismember(lower(Trigger.SETS), lower(set))
372 error(<span class="string">'### Unknown set [%s]'</span>, set);
373 end
374
375 out = plist();
376 out = Trigger.addGlobalKeys(out);
377 out = buildplist@ltpda_uoh(out, set);
378
379 <span class="comment">% Build the requested parameter list.</span>
380 switch lower(set)
381 case <span class="string">'Default'</span>
382 % time
383 p = param({<span class="string">'time'</span>,<span class="string">'The time of the trigger. Give either a string representation or a time object.'</span>}, paramValue.EMPTY_STRING);
384 out.append(p);
385
386 % amplitude
387 p = param({<span class="string">'amplitude'</span>,<span class="string">'The trigger amplitude.'</span>}, paramValue.EMPTY_DOUBLE);
388 out.append(p);
389
390 % frequency
391 p = param({<span class="string">'frequency'</span>,<span class="string">'The trigger frequency.'</span>}, paramValue.EMPTY_DOUBLE);
392 out.append(p);
393
394 end
395 end % function out = getDefaultPlist(varargin)
396
397 <span class="comment">% This creates arrays of the given size containing empty Trigger objects.</span>
398 function obj = initObjectWithSize(n,m)
399 obj = Trigger.newarray([n m]);
400 for ii = 1:numel(obj)
401 obj(ii).UUID = char(java.util.UUID.randomUUID);
402 end
403 end
404
405 end <span class="comment">% End static methods</span>
406
407 methods (Static, Access=protected)
408
409 <span class="comment">% Global keys are added to all parameter lists so that properties common to all</span>
410 <span class="comment">% user objects can be set.</span>
411 function pl = removeGlobalKeys(pl)
412 pl.remove(<span class="string">'name'</span>);
413 pl.remove(<span class="string">'description'</span>);
414 end
415
416 function pl = addGlobalKeys(pl)
417 % Name
418 p = param({<span class="string">'Name'</span>,<span class="string">'The name of the constructed trigger object.'</span>}, paramValue.STRING_VALUE(<span class="string">'None'</span>));
419 pl.append(p);
420
421 % Description
422 p = param({<span class="string">'Description'</span>,<span class="string">'The description of the constructed trigger object.'</span>}, paramValue.EMPTY_STRING);
423 pl.append(p);
424 end
425
426 end <span class="comment">% End static, private methods</span>
427
428 methods (Static = true, Hidden = true)
429 varargout = loadobj(varargin)
430 varargout = update_struct(varargin);
431 end
432
433 methods
434 varargout = char(varargin)
435 varargout = display(varargin)
436 varargout = copy(varargin)
437 end
438
439 methods (Hidden = true)
440 varargout = attachToDom(varargin)
441 end
442
443 methods (Access = protected)
444 obj = fromStruct(obj, a_struct)
445 varargout = fromDom(varargin)
446 end
447 </pre></div>
448
449
450 <br><br>
451 <h2><a name="unittests">Unit Tests</a></h2>
452
453 <p>
454 LTPDA provides a unit test framework that aims to make it easy to test your new methods, classes and built-in models. Unit tests are methods of a
455 unit test class. These unit test classes should inherit from one of the base classes <tt>ltpda_utp</tt> or <tt>ltpda_builtin_model_utp</tt>. The
456 directory <tt>ltpda_toolbox/ltpda/classes/tests/</tt> contains these test classes and examples for testing classes and built-in models. To run
457 the unit tests you can use the unit test runner class <tt>ltpda_test_runner</tt>. For example,
458 </p>
459 <div class="fragment"><pre>
460 >> ltpda_test_runner.RUN_ALL_TESTS
461 >> ltpda_test_runner.RUN_TESTS(<span class="string">'@my_class_tests'</span>)
462 >> ltpda_test_runner.RUN_TESTS(<span class="string">'@my_class_tests'</span>, <span class="string">'test_a_particular_method_feature'</span>)
463 </pre></div>
464
465
466
467
468 </p>
469
470 <br>
471 <br>
472 <table class="nav" summary="Navigation aid" border="0" width=
473 "100%" cellpadding="0" cellspacing="0">
474 <tr valign="top">
475 <td align="left" width="20"><a href="repo_gui_retrieve.html"><img src=
476 "b_prev.gif" border="0" align="bottom" alt=
477 "Retrieving objects and collections from a repository"></a>&nbsp;</td>
478
479 <td align="left">Retrieving objects and collections from a repository</td>
480
481 <td>&nbsp;</td>
482
483 <td align="right">Class descriptions</td>
484
485 <td align="right" width="20"><a href=
486 "class_desc_main.html"><img src="b_next.gif" border="0" align=
487 "bottom" alt="Class descriptions"></a></td>
488 </tr>
489 </table><br>
490
491 <p class="copy">&copy;LTP Team</p>
492 </body>
493 </html>