Important MIES concepts for developers¶
This document should help new developers understand some of the guiding principles behind MIES.
Can be found here.
Our documentation toolchain consists of doxygen/breathe/sphinx. All
documentation for the code should be in procedure files. All public accessible
functions should have a documentation block, for complex interfaces the use of
@param is recommended. See
AFH_ExtractOneDimDataFromSweep() for an
Caller/Callee graphs can be created by executing doxygen in Packages/doc and can be browsed at Packages/doc/html/index.html.
The full documentation can be generated with tools/build-documentation.sh.
Global objects like variables, strings, waves and datafolders should only be used if necessary. Local variables, strings, free waves and free datafolders should therefore be preferred if possible.
Reasons to use global objects:
All access to global objects must be handled via getter functions in File MIES_WaveDataFolderGetters.ipf or File MIES_GlobalStringAndVariableAccess.ipf. The documentation for these getter functions must include the wave layout, and purpose of the object. This documentation should be the primary, and only, source for finding out what the object holds. Using a single access point for global objects allows to quickly find all users of that object.
For waves we use wave versioning, see Group WaveVersioningSupport. This is done in order to enable a smooth upgrade when the wave layout changes and old experiments are loaded with the old wave layout.
The use of dimension labels in waves for better readability is recommended.
User data on GUI objects or traces should only be used sparingly.
Some Igor Pro functionality is wrapped in separate functions for better
readability and error checking. These include interacting with GUI controls,
see File MIES_GuiUtilities.ipf, checking strings
IsEmpty() or numbers
Setting GUI values programmatically must always be done via
PGC_SetAndActivateControl() as that calls the GUI procedure as well.
We employ assertions to check function invariants . The relevant
ASSERT_TS(). Adding assertions
to the code greatly improves the error reporting capabilities of MIES and
should be used where appropriate.
MIES uses the DEBUGGING_ENABLED symbol for toggling compilation with and
without debug output. The relevant functions are
DEBUGPRINTSTACKINFO(). The debug mode
can be toggled on a per-file basis from MIES Panels->Advanced->Open debug
panel or globally via
Dynamically growing waves¶
Often one is adding entries to a wave one at a time. In order to minimize the
performance cost one can employ a technique where the actual size of the wave
and the used size differ in order to minimize the number of resize operations.
The relevant functions are
EnsureLargeEnoughWave() (with example
The current data folder (cdf) should never be set or expected to be something
fixed. For dealing with that environment the following functions have been
Deleting waves and datafolders¶
Due to the way Igor Pro works deleting a datafolder/wave may not succeed as the
object is currently in use. Use
KillOrMoveToTrash() to work around
In order to avoid having to do the same lengthy calculation over and over again MIES has a wave cache. To use that cache you have to implement a function which derives a key from all the input parameters and is unique for the combination of parameters and different for all other combinations. This key is then used to store and retrieve the wave from the cache. See File MIES_Cache.ipf for further examples.
For DAQ we use a variety of background functions, all are listed at Group BackgroundFunctions. For debugging purposes the background watchdog panel from MIES Panels->Advanced->Start Background … allows to view the state of the background functions during execution.
Structured wave metadata¶
Structured metadata can be stored and retrieved into/from the wave note using
The main data acquisition panel is created via the window macro
DA_Ephys(). After changing it, be sure to call MIES
Panels->Advanced->Reset And Store … for setting the default values and
recreating the window macro.
Access to the GUI control settings is done via the GUI state wave which caches
the settings for performance reasons. The functions
DAG_GetTextualValue() can be used to
query the values of (nearly) all GUI controls.
All panels are versioned. The version number must be increased if a stored
panel in an old experiment would misbehave with new code. The relevant
For TabControl GUI elements we use routines from ACL_TabUtilities.ipf and ACL_UserdataEditor.ipf for convenient programming.