...
The best way to create this file is to modify one of the supplied example files, which are constantly maintained on this site. The examples cover all of the major applications of EPHUS known to the developers at the present time. Startup files contain both configuration and application information. The vast majority of users only need to adjust the configuration information, which resides in clearly demarcated sections at the beginning of the startup file.
This guide steps through a typical startup file, which follows the most current conventions. For completeness, both the configuration and application sections are described. Only power-users, however, should modify the application sections, and limited support can be provided for such uses.
The 'Specimen'
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Wiki Markup |
|
The Ventral View (Configuration)
All the parts of the startup file that the typical user must interact with – the configuration sections – are conveniently located at the top of the file. This is the 'front side' of our speci
The Head
Here's the beginning of our startup file 'specimen':
...
The end of this section is marked as the 'END OF CONFIGURATION'. That's all that most users need to stomach.
The Dorsal View (Application)
For those with a strong stomach, let's look at the 'other side' of the startup file – the application sections.
...
The application sections of the startup file are less bound to convention, and hence are more likely to not be not completely and/or correctly described by this documentation.
...
The syntax for openprogram() is:
| Panel |
|---|
hProg = openprogram(progmanager,programName OR programInfo,constructorArg1, constructorArg2, ...) |
Let's step through the arguments:
- hProg: An instance of a program @program object, which can be treated regarded as a 'handle' to the program.
- progmanager: The (singleton) @progmanager object , which – this can be obtained by simply calling 'progmanager'the progmanager() function as shown here
- programName: For typical programs, this argument is used, specifying the name of the program to start. The program names are those in the <EPHUS>\Programs directory of the installation. The program's figure will have the same title as the name.
- programInfo: A cell array can be supplied instead of a simple string. This can be used for two purposes.
- A two-element cell array can be used to display the program GUI with a different title than the program name. Note that the alias 'xsg' is supplied before the actual program in the array.
- For programs which contain multiple GUIs (noted as such in EPHUS Programs), the cell array programInfo option must be used. For legacy reasons, both the first and second elements should be the program's alias, while the third element should be the actual program name (i.e. the M-file in <EPHUS>\Programs). Thereafter, elements are added in pairs; the first is the sub-gui's alias and the second is the sub-gui's actual name (an M filename found in the same directory as the main program M file).
...
The 'constructor' arguments provide the necessary (or highly typical) information required to initialize a program in a manner consistent with the configuration information supplied in the startup file. Occasionally, it may be useful to configure additional properties of the program upon startup. The names of properties for given programs can be found by inspecting the makeGlobalCellArray() function found within each program's main M file. To set the values of these properties, one uses the setLocal() and setLocalBatch() methods of the Program Manager. The syntax for the latter is:
| Panel |
|---|
setLocalBatch(progmanager,programHandle,'Property Name 1',Property Value 1, 'Property Name 2', Property Value 2, ...) |
As with openprogram(), the function progmanager() should simply be supplied for the first argument. The second argument, the programHandle refers to the object variable returned by openprogram(). Where setLocal() and setLocalBatch() are required, the handle returned by openprogram() must be saved to a local variable of the startup file.
...
Adding and removing programs
UserFcn Bindings
The Tail
Final Comments
Startup files designed for different EPHUS applications will employ different sets of programs. In many cases, one can simply remove (or add) programs from the list in the Program Startup section. Caution is required, however, because some programs assume that other programs have been started. For instance, the mapper assumes the stimulator has been started. In some cases, a program may requires program handles as a constructor argument; here, the pulseJacker is bound to the previously created ephys and stimulator program handles.
Generally, model startup files conservatively assume that all possible programs for an application will be used. This will cause several program windows to launch. However the user can close unneeded windows and save a configuration set accordingly to hide them. Thus, modification of the startup file is not really necessary.
UserFcn Bindings
In this section, various user functions (also referred to as 'callbacks') are 'registered' to respond to events generated by programs:
| Panel |
|---|
%% USERFCN BINDINGS if waitbarUpdate(0.84, wb, 'Setting up default (built-in) userFcns...');return;end userFcnCBM = getUserFcnCBM; fprintf(1, 'Default UserFcn mappings:\n'); %userFcns for LSPS/mapping customization fprintf(1, '----------------------------\n'); |
Bindings of events to user functions (callbacks) are maintained by a data object called a callbackmanager. EPHUS maintains a single callbackmanager for user function bindings – the 'UserFcnCBM'. This section of the startup file is reserved for registering 'user' functions which have in fact been created by developers. The user functions developed can contain critical functionality for particular programs. For example, the mapper_userFcn_ephysSamplesAcquired function, developed as a part of the mapper, is associated with an ephys program event ('SamplesAcquired').
These developer-specified 'user' functions will appear in the userFcns GUI, alongside any 'true' user functions developed by the user for the purpose of customizing EPHUS. Such user function bindings can be stored as part of the userFcns configuration, without requiring modification of the startup file.
The Tail
As with the beginning, the final section contains code common to all EPHUS startup files and should not be modified. In particular, upon opening & initialization of all the programs, the user is prompted to load their desired configuration set folder:
| Panel |
|---|
%% ENDING BOILERPLATE delete(wb); %Kill the waitbar. |
Final Comments
Let's summarize what we've learned during this 'laboratory':
- Startup file contain a mixture of configuration and application information.
- Most users should select an appropriate model startup file for their application, and modify only the configuration sections as needed for their particular rig/use.
The combination of configuration and application information into scripts that are executed is a common approach for adapatable programming. An example of this is LabView. In LabView, 'VI' files generally contain information about the hardware to use as well as the functions to perform with them. They may also contain constants that are not exposed to the VI's 'front panel'. Combinations of hardware/functionality/constants are generally distributed as model VIs; model EPHUS startup files are similar. In EPHUS, the program GUIs represent the 'front panel' and are quite flexible in that GUI settings can be captured into 'configuration sets' which are saved. Unlike LabView, EPHUS is not designed as a user programming environment, so that the application sections of startup files are not typically modified.
Finally, it is stressed that users should pay attention to the latest version that model startup files have been tested with (which will always be noted). As the underlying EPHUS code evolves, occasionally startup files may not function properly with newer versions. Startup file models will be regularly updated to be current, but may lag EPHUS updates for some applications.Like Labview
Version-to-version