MonkeyLogic

Behavioral Control in MATLAB

 



Example Task

Provided here are the conditions file and timing script for a simple DMS (Delayed-Match-to-Sample) task. The subject sees a picture, and then must select that picture from two choices presented after a brief delay. Note that the inter-trial-interval is set in the main menu, and the timing script controls only the within-trial events.

DMS task

These files are available in a zip folder, along with four sample stimuli. All these files should be placed into an experiment directory (e.g., named "dms_task"). Once the conditions file is loaded from the main menu, the appropriate options set, and a data file name entered, the run button should become active. To run this task, X & Y eye inputs must be defined in the main menu (because it uses the acquirefix and holdfix options of the eyejoytrack command, which expect an eye-signal, as described in the timing script section), although a joystick may be connected, or no actual hardware at all. In addition, an output should be selected for the reward. Note: if using a joystick to play the task, some of the times may need to be increased to account for slower reaction times and movements of a joystick compared to saccades, for which this code was written.

Conditions file (dms.txt):

Condition Frequency Block Timing File TaskObject#1 TaskObject#2 TaskObject#3 TaskObject#4
1 1 1 3 dms.m fix(0,0) pic(A,0,0) pic(A,-4,0) pic(B,4,0)
2 1 1 3 dms.m fix(0,0) pic(A,0,0) pic(A,4,0) pic(B,-4,0)
3 1 1 3 dms.m fix(0,0) pic(B,0,0) pic(B,-4,0) pic(A,4,0)
4 1 1 3 dms.m fix(0,0) pic(B,0,0) pic(B,4,0) pic(A,-4,0)
5 1 2 3 dms.m fix(0,0) pic(C,0,0) pic(C,-4,0) pic(D,4,0)
6 1 2 3 dms.m fix(0,0) pic(C,0,0) pic(C,4,0) pic(D,-4,0)
7 1 2 3 dms.m fix(0,0) pic(D,0,0) pic(D,-4,0) pic(C,4,0)
8 1 2 3 dms.m fix(0,0) pic(D,0,0) pic(D,4,0) pic(C,-4,0)

This file is structured so that the sample is always TaskObject#2 and the target is TaskObject#3, while the distractor is TaskObject#4. This organization makes writing the timing file very straightforward, as all it needs to do is display TaskObject #1 (the fix-spot), then display TaskObject #2 (the sample), then after extinguishing TaskObject #2 and a subsequent delay, it puts up TaskObjects #3 and #4. So long as the subject chooses TaskObject #3, the timing script knows s/he has chosen correctly - without knowing anything about the actual stimuli themselves.

Three blocks are defined: running blocks 1 or 2 will use stimuli A & B, or C & D, respectively, while running block 3 will use all the stimuli. Note, however, that without additional conditions, objects A & B can never serve as distractors for C & D, or vice versa.

Timing script (dms.m) :

%Delayed Match-to-Sample (DMS) timing script

% This task requires that either an "eye" input or joystick (attached to the
% eye input channels) is available to perform the necessary responses.
%
% During a real experiment, a task such as this should make use of the
% "eventmarker" command to keep track of key actions and state changes (for
% instance, displaying or extinguishing an object, initiating a movement, etc).

% give names to the TaskObjects defined in the conditions file:
fixation_point = 1;
sample = 2;
target = 3;
distractor = 4;

% define time intervals (in ms):
wait_for_fix = 1000;
initial_fix = 1000;
sample_time = 500;
delay = 1500;
max_reaction_time = 500;
saccade_time = 80;
hold_target_time = 300;

% fixation window (in degrees):
fix_radius = 1;

% TASK:

% initial fixation:
toggleobject(fixation_point);
ontarget = eyejoytrack('acquirefix', fixation_point, fix_radius, wait_for_fix);
if ~ontarget,
     trialerror(4); % no fixation
     toggleobject(fixation_point)
     return
end
ontarget = eyejoytrack('holdfix', fixation_point, fix_radius, initial_fix);
if ~ontarget,
     trialerror(3); % broke fixation
     toggleobject(fixation_point)
     return
end

% sample epoch
toggleobject(sample
); % turn on sample
ontarget = eyejoytrack('holdfix', fixation_point, fix_radius, sample_time);
if ~ontarget,
     trialerror(3); % broke fixation
     toggleobject([fixation_point sample])
     return
end
toggleobject(sample); % turn off sample

% delay epoch
ontarget = eyejoytrack('holdfix', fixation_point, fix_radius, delay);
if ~ontarget,
     trialerror(3); % broke fixation
     toggleobject(fixation_point)
     return
end

% choice presentation and response
toggleobject([fixation_point target distractor]); % simultaneously turns of fix point and displays target & distractor
[ontarget rt] = eyejoytrack('holdfix', fixation_point, fix_radius, max_reaction_time); % rt will be used to update the graph on the control screen
if ontarget, % max_reaction_time has elapsed and is still on fix spot
     trialerror(1); % no response
     toggleobject([target distractor])
     return
end
ontarget = eyejoytrack('acquirefix', [target distractor], fix_radius, saccade_time);
if ~ontarget,
     trialerror(2); % no or late response (did not land on either the target or distractor)
     toggleobject([target distractor])
    return
elseif ontarget == 2,
     trialerror(6); % chose the wrong (second) object among the options [target distractor]
     toggleobject([target distractor])
     return
end

% hold target then reward
ontarget = eyejoytrack('holdfix', target, fix_radius, hold_target_time);
if ~ontarget,
     trialerror(5); % broke fixation
     toggleobject([target distractor])
     return
end
trialerror(0); % correct
goodmonkey(50, 'NumReward', 3); % 50ms of juice x 3

toggleobject([target distractor]); %turn off remaining objects

Note that MonkeyLogic functions available only in timing scripts are shown here in different colors (except for comments, they will not appear this color in the Matlab editor).

Generally, a timing script begins by redefining TaskObject numbers as readable names, and by defining the temporal intervals that will be used in the experiment (in milliseconds). Then toggleobject and eyejoytrack are interleaved such as to present stimuli at the appropriate times as contingent upon the subject's behavior. Whenever a behavioral error is encountered, a "trialerror" is recorded and any currently visible stimuli are turned off with a call to toggleobject (although these stimuli will be extinguished at some point during the inter-trial-interval, it is good programming practice to turn them off explicitly so that the times of all events are predictable and consistent across trials).

In addition to the code shown here, the eventmarker command, and the eventmarker option of toggleobject, should be employed generously to mark salient events (e.g., a stimulus is turned on or off, the subject acquires fixation, initiates a response, acquires a target, etc.). These event-markers allow one to align neural signals with behavioral events post-hoc with millisecond-level accuracy.

 



This site last updated: May, 2014
© 2008-2014