A to-be-written HOWTO covering how to write (and add) submodules for and to the toolbox.

Suppose you use the toolbox frequently but are very much interested in an additional set of functions that most probably cover a specific problem. That would be the perfect scenario for writing your own submodule that integrates seamlessly with the toolbox.

The following guide will try to help you sorting things out and give you a few ideas that might prove useful in writing your own modules.

Please note: Although having modular design in mind from the very beginning, some of the very useful (and perhaps even necessary) functions to integrate modules in the toolbox still have to be developed. Therefore, this is work in progress.

Familiarise yourself with the basic concepts and the directory structure of the toolbox.

Furthermore, it is a good idea to read through the developer's basics, if you haven't already done so.

The first step is probably to decide about a proper short name for your module, as all your function files that you write for this module that do the actual work (including the GUI files, if you plan to add a GUI) go into that directory.

An example could be “sim” for a module performing simulations.

<note tip>Why is this important? The easy answer: If you follow these rules for your directory layout, every user interested in installing your module could easily just take the ZIP file of your module (given that the ZIP archive preserves the internal directory structure of your module) and unzip it into the main directory of his toolbox. Additionally, using git and submodules makes it very convenient in development to have the complete module residing in one subdirectory.</note>

If you plan to add a GUI, things become a bit more complex, as you should follow the generic directory structure of the toolbox to allow for seamless integration of your module. Therefore, add the following additional directories to your module (below your modules/<modulename> directory):

• GUI
  • private
    • helptexts
    • conf

Your main GUI routine will reside in the GUI directory, your help files for that GUI¹⁾ in GUI/private/helptexts/.

Your GUI helpwindow (and any additional GUI windows that neeed to be accessible solely from within your GUI) will reside in GUI/private and should have a generic name:

trEPRgui_<YourModuleName>_helpwindow.m

Taken together, the complete directory structure of a module (including a GUI and other things) might look as follows (as subdirectory residing in the modules directory of the trEPR toolbox):

• <YourModuleName>
  • Contents.(This file is particularly important and has to follow a certain scheme. For details see the section Version Numbers of Modules below.))
  • GUI
    • private
      • helptexts
      • conf
    • internal
  • internal
    • trEPR<YourModuleName>info.m
  • IO

Of course, you can add as many subdirectories below your main module directory <YourModuleName> as you wish. Nevertheless, it seems sensible to stick to the generic directory structure of the toolbox as much as possible.

Please note that directories called private are of course possible in every subdirectory, but that the access to functions and files stored here is restricted to the direct parent directory of the particular private directory. Furthermore, files located in these private directories do not appear on the Matlab search path, what makes it a convenient way to store files that are just used internally by your module and for which you provide an interface via another function accessible to the user.

Although it can be debated whether GUIs are important or even necessary, they proved to be quite useful in case of the trEPR toolbox. Therefore, developers contributing their own modules might want to write GUIs as well for those.

To make life easier, a few ideas about how to write such GUIs and what aspects to take care of when developing are layed out on a separate page, together with code snippets that might be useful as well.

It may well be the case that you need to extend the toolbox data structure in order to store results from the tasks performed with your module²⁾ In order not to mess up with the toolbox data structure, it is good practice to add an additional struct at the top level of the data structure named identical to your module. There you can store all additional data and parameters that originate from tasks within your module.

Hint: It proved to be a good idea to have one central function defining the structure of the additional fields for the data structure, similar to the routines trEPRdataStructure and especially trEPRguiDataStructure. Whereas the former defines the toolbox data structure as such, the latter just provides the additional fields used for each dataset in combination with the GUI. This concept allows you to both centrally manage your data structure (if you wish even with version numbering inside your module-specific part of the data structure) and even to validate given structures.

Please note: If you plan to provide the user with a textual report, e.g. in case of simulations or fits, you should always make sure that the report does not contain additional information not stored otherwise in parameters in a key-value manner. This is insofar very important as you might want to create full textual reports with a separate (still to be written) report module/functionality that creates nice, human-readable overview reports of all informations contained in a dataset together with all tasks and operations performed.

The toolbox itself has a version number that gets added to every history record written for a dataset. As modules might well have versions independent of the main toolbox, it is equally important to implement a version numbering scheme and add that version number to each history record of tasks performed with the module to allow the user to always track which version was used for a particular task. In combination with a source code management system (such as git) this allows for identifying the exact code used for a particular task in retrospect.

For more details see the respective page on version numbers of modules that comes along with examples for both the Contents.m file and a function to read those contents and store even more information.