Starting EPHUS - Anatomy of a Startup File

Background

To start EPHUS, one must invoke a startup file at the MATLAB command line. The file is a MATLAB function file (i.e., .m extension), located in the current directory or somewhere on the user's MATLAB path. Every user/rig requires a customized startup file.

The best way to create this file is to modify one of the supplied example files, which are constantly maintained on this site. 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 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'

The Head

Here's the beginning of our startup file 'specimen':

function gephus

%% STARTUP BOILERPLATE 
%Set up a wait bar to show the progress.
wb = waitbarWithCancel(0, 'Starting ephus...', 'Name', 'Loading software...');
pos = get(wb, 'Position');
pos(2) = pos(2) - pos(4);
set(wb, 'Position', pos);

This section contains the function declaration, with the name of the startup file – in this case, 'gephus'.

The next section (%%Startup Boilerplate) should not be modified, as the name implies. This section is common to all startup files.

The double-parenthesis(%%) signifies a MATLAB M-file cell. They are used throughout the startup file to help clearly demarcate the different file sections, when viewed in the MATLAB editor.

Device/Channel Configuration

This section contains the configuration information for each of the devices & channels connected to this installation of EPHUS:

%% DEVICE/CHANNEL CONFIGURATION

%Amplifier objects for ephys
patch{1} = multi_clamp('text_file_location', 'C:\MATLAB6p1\work\Physiology\MClamp700BChannel1.txt', 'scaledOutputBoardID', 1, 'scaledOutputChannelID', 0, ...
    'vComBoardID', 1, 'vComChannelID', 0, 'channel', 1, 'name', '700B-1');

patch{2} = multi_clamp('text_file_location', 'C:\MATLAB6p1\work\Physiology\MClamp700BChannel2.txt', 'scaledOutputBoardID', 1, 'scaledOutputChannelID', 4, ...
    'vComBoardID', 1, 'vComChannelID', 1, 'channel', 2, 'name', '700B-2');

%Acquirer channels 
acqChannelNames = {'photodiode1'};
acqBoardIDs =   [2];
acqChanIDs =    [0];

%Stimulator channels 
stimChannelNames = {'pockelsCell' 'shutter0' 'xMirror' 'yMirror' 'shutter1' 'ao5' 'ao6' 'ao7'};
stimBoardIDs = [3 3 3 3 3 3 3 3];
stimChanIDs =  [0 1 2 3 4 5 6 7];

EPHUS programs sometimes employ specialized devices, which are implemented as MATLAB objects. In this case, for instance, the ephys program employs amplifier objects. All objects require a constructor in order to be created – this is a function which must be called and typically consists of several arguments initializing the particular object's properties. In EPHUS, all devices must be 'constructed' upon startup, and presumed to exist 'forever' (until EPHUS is closed).

In this case, the multi_clamp function calls create a particular type of amplifier – this refers to the MultiClamp 700B patch-clamp amplifier from Axon Instruments. The multi_clamp object definition is a 'class' (or, technically, a 'subclass') of amplifier. Another amplifier class that could be (but isn't) constructed here, is an axopatch200B, referring to the Axopatch 200B instrument, also from Axon Instruments.

The Device Constructors page documents the syntax for the various devices presently supported by EPHUS, such as the MultiClamp 700B and Axopatch 200B.

In addition to devices, EPHUS contains two programs – acquirer and stimulator – which are included in virtually every EPHUS deployment. These programs allow a number of National Instruments A/D, D/A, and buffered digital output channels to be user-defined and controlled. As with devices, the channels must be configured on EPHUS startup, and persist until EPHUS is closed (it is presumed that users are not re-connecting signals during an experiment!).

For A/D channels, handled by the acquirer, three variables must be entered: acqChannelNames, acqBoardIDs, acqChanIDs. The variable acqChannelNames is a MATLAB cell array, while acqBoardIDs and acqChanIDs are numeric arrays of integers. Each of the arrays is a 'row vector' of the same length.

• acqChannelNames: A cell array of strings specifying descriptive names for each of the A/D channels.
• acqBoardIDs: An array of integers specifying the numeric indices of the National Instruments (NI) boards associated with each of the named channels in acqChannelNames. The Board IDs are defined in the NI Measurement and Automation Explorer program included with the DAQmx driver. The NI convention is that boards are named 'Dev#', i.e. 'Dev1', 'Dev2', etc. EPHUS presumes this convention is followed, and the BoardID refers to the number following 'Dev'.
• acqChanIDs: An array of integers specifying the A/D channel indices corresponding to each of the named channels in acqChannelNames. Different boards have differing numbers of supported A/D indices. Channel indices for NI begin with 0.

The D/A channels are specified to initialize the stimulator in a similar fashion, with the variables stimChannelNames, stimBoardIDs, and stimChanIDs.

Configuration Variables

The next section contains configuration variables that can/should be modified by the user. In our sample file, we see:

%% CONFIGURATION VARIABLES
triggerOrigin = '/dev1/port0/line0'; %Specifies the digital line terminal on which the trigger pulse is output at the start of each acquisition
triggerDest = 'PFI0'; %Specifies the digital line terminal on which the trigger pulse is received. On /every/ board, this must be connected to the triggerOriginal terminal

xsgStartDirectory = 'C:\Data\'; %Default directory in which to save data files

pockelsOn=1; %Logical value specifying whether Pockels Cell is in fact attached/active on 

%Size, in microns, of the camera FOV (a camera application is required by the mapper program)
xVideoScaleFactor =  2625;
yVideoScaleFactor = 1980;

%% *************************END OF CONFIGURATION***************************************

The number and names of the configuration variables in a startup file will depend on the particular application (as determined by the application sections below). Generally, they should be well-documented via MATLAB comments as seen here.

Some variables appear in virtually all EPHUS deployments. For instance, triggerOrigin and triggerDest are used in all cases to specify, respectively, the digital line on which the trigger pulse for each acquisition is output and the terminal on which each board expects to receive this trigger signal, ensuring all boards begin acquisition at the same moment.

The end of this section is marked as the 'END OF CONFIGURATION'. The following sections represent the application areas of the startup file, and are only intended for modification by developers and power-users.

Timing/Clock Setup Application section

Program Startup Application section

User Fcns Application section

The Tail

Final Comments

Like Labview
Like