ep_ExperimentDesign GUI

This GUI generates the parameters for variables defined in the RPvds circuit. Display this GUI by typing >> ep_ExperimentDesign in the Matlab command window.

This GUI allows you to define how RPvds parameters (such as frequency, amplitude, duration, etc.) are updated on a 'trial-by-trial' basis. In a behavior experiment (with or without electrophysiology; ep_RunExpt), we define 'trial' as a single measurement of the subjects response to some stimulus . In an electrophysiology experiment (typically anaesthetised or passive recordings; ep_EPhys), we define 'trial' as a single presentation of some stimulus.

The basic strategy for generating the experiment using this GUI is to:

Define which TDT hardware modules are in use
Enter parameter tag names from an RPvds circuit (or read parameter names directly from the file)
Specify the function of each parameter before/after each trial (read, write, or both read/write)
Enter one or more values (can be any Matlab expression, including function names) for all 'write' or 'read/write' parameters
Optionally select a calibration file corresponding to one or multiple parameters
If running a behavioral experiment with more than one subject simultaneously (i.e. multiple behavioral boxes), then create an experiment design for each subject, or duplicate the experiment design for each subject (see the 'Parameter Tag Modifiers' section below)

1. Define Hardware Modules

The first step in designing an experiment is to determine which TDT hardware modules will be running circuits that need to be updated on a trial-by-trial basis. This hardware may be an RX6 module if high-frequency sampling rates are required to produce ultrasonic sounds, or an RX8 module if an array of speakers are required for a sound localization experiment, etc. RPvds circuits should be created first and designed to meet the specific needs of the experiment. Once the RPvds circuits are created (they can be modified and refined later), add all modules to the ep_ExpeirmentMaker GUI by clicking the + sign.

If making a new experiment design, a prompt will appear asking whether the TDT OpenEx software. Typically, the OpenEx software is used in conjunction with electrophysiology experiments, with or without behavior. OpenEx can be used with behavior alone, however, this tends to increase the complexity and time spent on setup.

Next, a prompt will appear requesting an alias (a name) for the hardware module. If using OpenEx the module alias needs to be the same as the name used in the OpenWorkbench; otherwise, the alias is aribtrary, but required.

When Using OpenEx...

After specifying the module alias, a prompt will appear asking if you would like to read the parameter tags directly from an RPvds circuit file. If selecting yes (recommended), you will be prompted to locate an RPvds file. The software will then try to read all relevant parameter tags that exist in the selected RPvds file.

When Not Using OpenEx...

After specifying the module alias, prompts will appear requesting you to select the TDT hardware module type (RX6, RZ6, RX8, etc.) as well as the module index. The module index allows you to address individual modules of the same type on your rig. Most often, the module index will be '1', but if you have multiple RX6 modules, for example, then you can specify which of the RX6 modules the circuit will be running on.

Finally, you will be prompted to locate an RPvds circuit file (*.rcx) that will be associated with this module.

The module type, alias, and RPvds file can be updated at any time by clicking the menu item: Protocol > Update Module

2. Parameter Tags

Each row of the parameter table identifies the parameter tags that you would like updated in the RPvds circuit file on a 'trial-by-trial' basis. The 'Tag' column of the parameter table is the name of the parameter tags within the circuit. This field is case sensitive and should not contain any spaces. A find-and-replace search function is included in the menu: Protocol > FindReplace (ctrl+F) All tags named here should be located within the circuit (with the exception of the asterisk prefix flag discussed below).

Parameter Tag Modifiers

*ParameterName
If you would like to include parameters for use in custom 'Trial Selection functions' (discussed later in its own section), then you can add an asterisk (*) before the tag name. For example: *ParameterName. The software will ignore any parameter tags starting with an asterisk and will not attempt to update them before each trial begins. You can still update parameters beginning with an askerisk in your custom functions if you need to.
$ParameterName
The dollar sign prefix modifier will create a prompt each time you run the experiment to manually specify the value of that parameter. You can set default values in the Values column.
ParameterName~#
Although the tilde-number scheme is not actually identified by the software, it is common to use this to control a specific behavioral box on setups that run more than one box simultaneously from the same computer. For example, you can refer to the first behavior box with 'ParameterName~1', the second as 'ParameterName~2', etc. This flag can be combined with any of the prefix modifiers.
Tip: If running more than one subject at a time (i.e. multiple behavioral boxes), then use the ~# suffix to identify which parameters correspond to which subject. Each subject gets its own experiment protocol file, you may simply create a file for the first subject, for example 'ParameterName~1', and then use the Find & Replace function (ctrl+F) to search for ~1 and replace with ~2.

3. Parameter Function

The parameter function column defines how EPsych should interact with the parameters on a trial-by-trial basis. There are three options for this field: read, write, read/write

read indicates the parameter should be read and stored into a file after each trial is complete. This file can can be saved and analyzed.
write indicates the parameter should be updated with a new value before each trial begins.
read/write indicates the parameter should be both updated with a new value before each trial begins and that value should be read after the trial is complete.

Typically, most parameters use the read/write function if something has been entered into the Values field. If, however, you need to record a value that is generated by the experimental paradigm during runtime (ex: some randomized value or response latency), then you would typically choose read for that parameter. If you are just updating some value and don't care to include it in your data file, then you may choose write.

4. Parameter Values

The Values column in the parameter table defines what numerical values will be passed for each parameter during an experiment before each trial. If you enter something in this field, then you will use the write or read/write parameter function. If you leave this field empty, then you must select the read function.

The Values field will accept one or more numerical values, such as 123 for a scalar value or [1, 2, 3] for an array. In practice, you may enter any Matlab command that returns a scalar value or a 1xN numerical array. This allows you to use syntax like:

1:5 evaluates to [1, 2, 3, 4, 5]
1:3:9 evaluates to [1, 3, 9]
logspace(1,3,5) evaluates to [10.0000, 17.7828, 31.6228, 56.2341, 100.0000]
rand(1,5) evaluates to [0.0855, 0.2625, 0.8010, 0.0292, 0.9289], or 5 values chosen randomly from a uniform distribution
5+rand(1,5) evaluates to [5.0855, 5.2625, 5.8010, 5.0292, 5.9289]
MyFavoriteFunction(1234) evaluates to whatever you would like, as long as it returns a 1xN numerical array

The values you enter for each parameter are entirely up to you and your specific experiment design. As you update your parameter values, you should see an indicator on the left change color to red if something isn't right with the values you've entered. The protocol will not run properly if this indicator is red. Adjust your values until it is green. Once you've entered the values for all parameters you wish to be updated before each trial and the indicator on the left panel is green, then click the View Compiled button. This will compile the parameters, their values and options, and display a table in a new figure with a rundown of unique trials that will be selected from during the experiment.

5. Buddy Parameters

It is often useful to tie the values of two or more parameters together. This feature is especially useful when running experiments using multiple hardware modules. The values of parameters can be tied together by clicking the dropdown box and selecting < ADD >. Enter a meaningful name in the input box and click OK. The name is arbitrary, but should be something meaningful to you. This will create a new item with the entered name in all Buddy drop down boxes. Select this new Buddy for additional parameters on the same module or across modules. The values of buddied-up parameters will be tied together so that the first number in all buddied parameters will be locked together; the second number in all budied parameters will be locked, etc. You can create as many Buddy parameters as needed.

6. Options Panel

Randomize: Does just that. The order of the trials will be randomized during the experiment.
Operational Trigger: This option allows external control of trials. For example, if the experimenter wants to press a physical button to trigger a stimulus; another example would be to use a photodiode on an LCD monitor linked to a digital input on a TDT module to trigger a trial.

In order to implement this option, the OperationalTrigger macro must be placed in an RPvds circuit. This option is only effective for running experiments through ep_Ephys. The ITI value (below) is ignored if this option is checked.
# Reps: This field takes a scalar value that determines the number of repetions of all unique trials defined by the parameter table.
ITI: The Inter-Trigger Interval determines the interval between triggers, in milliseconds. A scalar value will present a trigger at a static interval. If two values are entered (ex: [500 1500]), then the ITI will be randomly selected from a uniform distribution bounded by the two values.
Important Note: When using ep_EPsych for passive recordings, the software does its best to trigger the next trial on time, Windows is not deterministic and this timing can not be guaranteed. While the ITI can vary to some degree (on the order of milliseconds), the actual trigger timestamp is recorded by the real-time TDT hardware and is highly accurate and precise. There are a few workarounds if you require highly accurate triggering. One strategy is to use the Operational Trigger option and macro (see above) triggerd by a PulseTrain component in the RPvds circuit. This is not an issue when running operant conditioning behavioral experiments using ep_RunExpt because the trial is initiated by the subject and not the Matlab software.

7. Trial Select Function

One of the more powerful uses of the EPsych software is the ability to write your own code to custoize how the experiment functions. While this is optional, more complex paradigms which utilize external software (such as the Psychtoolbox) or which adjust the next stimulus based on behavioral or neural responses can be accomplished by writing a custom function.
This custom trial selection function must take one input, a structure with the trial parameters and other information, and one output, either the next trial index (see below) or the entire structure (modified or not) that was received as an input to this function. The two prototypes for this function would be:

NextTrialID = MyCustomFunction(TRIALS)
TRIALS = MyCustomFunction(TRIALS)

The custom function needs to be somewhere on Matlab's path. Enter the function name into this field. I'll add more details on writing custom trial selection functions in the future, but please look in the UserFiles directory for lots of examples. By convention, the names of these custom functions begin with 'TrialFcn_', but that is up to you.

Epsych

ep_ExperimentDesign GUI

1. Define Hardware Modules

When Using OpenEx...

When Not Using OpenEx...

2. Parameter Tags

Parameter Tag Modifiers

3. Parameter Function

4. Parameter Values

5. Buddy Parameters

6. Options Panel

7. Trial Select Function

8 Calibration Files