NIMH ML: Docs

bhv_code

This function puts string labels to numeric behavioral codes.

Syntax:

bhv_code(code_number1, code_name1, code_number2, code_name2, ...);

Example:

bhv_code(10, 'Fixation cue on', 20, 'Sample', 30, 'Delay', 40, 'Go', 50, 'Reward');

bhv_variable

This function stores variables to the data file.

Syntax:

bhv_variable(var_name1, var_value1, var_name2, var_value2, ...);

Example:

bhv_variable('direction', direction, 'choice', choice);

dashboard

This function displays user texts immediately on the control screen.

Syntax:

dashboard(line_number, text, color);

Input arguments:

line_number: Currently you can display 10 lines of strings.

Example:

dashboard(1, 'DMS Task', [1 0 0]);

editable

This function registers variables to the edit menu.

Syntax:

editable(var_name1, var_name2, ...);
editable(type, var_name);
editable(type, {var_name1, var_name2, ...});

Input arguments:

type: '-file', '-dir', '-color', '-category' or '-range'

Example:

editable('fix_duration', 'sample_duration', 'delay_duration');
editable('-file', 'parameter_file');
editable('fix_size', '-color', {'face_color', 'edge_color'}); % mixed usage

category1 = {'Red', 'Green', 'Blue', 'Blue'}; % the last element indicates the selected item
editable('-category', category1);

range1 = [0 1000 100 300]; % [min max step value]
editable('-range', range1); % you can use a slider control to adjust the value

Remarks:

The type argument allows users to use MATLAB GUI controls to pick up a filename, a directory name or a color.
Variables with no type should be logical or double with 6 or less elements.
The variable types for '-file' and '-dir' should be 'char'. The '-color' variable should be a 1-by-3 vector, [R G B].
The category type must be a cell string array. Its last element is the currently selected item.
The range type must be a 1-by-4 vector, [min max step value]. Its last element is the currently determined value.

escape_screen

This function pauses the task after the current trial.

Syntax:

escape_screen;

eventmarker

This function marks the current time with the eventcodes. The eventcodes can also be sent to external devices, if Behavioral Codes and Strobe Bit are assigned on the main menu I/O panel.

Syntax:

eventmarker(eventcodes);

Example:

eventmarker([10 20 30]);

eye_position / eye2_position / joystick_position / joystick2_position

These functions return the current eye or joystick position. The return value is in degrees.

Syntax:

xy_deg = eye_position;
[x_deg y_deg] = eye_position;

get_analog_data

This function returns analog input samples of the specified signal.

Syntax:

data = get_analog_data(sig_name, duration);

Input arguments:

sig_name: Case-insensitive.

'eye'
'eye2'
'joy' or 'joystick'
'joy2' or 'joystick2'
'touch'
'mouse'
'mousebutton'
'key'
'gen#' or 'general#' (e.g., 'gen1', 'general1')
'btn#' or 'button#' (e.g., 'btn1', 'button1')

Return values:

data is always sampled at 1 kHz, regardless of the AI sample rate on the main menu.

Example:

data = get_analog_data('eye', 1000); % data will be a 1000-by-2 matrix

get_movie_duration

Syntax:

duration = get_movie_duration;
duration = get_movie_duration(taskobjects);
[duration, num_frame] = get_movie_duration(___);

Example:

duration = get_movie_duration; % get durations (in milliseconds) of all movies

get_sound_duration

Syntax:

duration = get_sound_duration;
duration = get_sound_duration(taskobjects);

Example:

duration = get_sound_duration; % get durations (in milliseconds) of all sounds

getkeypress

This function waits for a key input.

Syntax:

[scancode, rt] = getkeypress(max_time);

Remarks:

To retrieve the scancode of a particular key, type kbdkeycode or kbdpcscancodes on the MATLAB command window. They are under the kbd directory of NIMH ML.

goodmonkey

This function triggers reward devices.

Syntax:

goodmonkey(duration);
goodmonkey(duration, option1, value1, option2, value2, ...);

Input arguments:

options: Case-insensitive. All options should be paired with values.

NumReward - Number of drops
PauseTime - Interval between drops, in milliseconds
TriggerVal - Triggering voltage, for analogoutput only
JuiceLine - Reward channel to trigger, for digital output only. Multiple lines need to be assigned to Reward in the Input/Output menu.
EventMarker - Behavioral(s) code to stamp for each drop. Multiple codes can be given. For example, [10 20 30] will mark 10 for the 1st drop, 20 for the 2nd and 30 for the 3rd.
NonBlocking - Deliver reward in the background so that the task is not blocked.
- 0 (blocking, by default)
- 1 (non-blocking, yield to other threads)
- 2 (non-blocking, do not yield, more precise timing)

Example:

goodmonkey(100, 'juiceline', 2, 'numreward', 3, 'pausetime', 300, 'eventmarker', 90, 'nonblocking', 2);

hotkey

This function defines a key macro.

Syntax:

hotkey(key, things-to-do);

Input arguments:

key: one letter among '`1234567890-=qwertyuiop[]\asdfghjkl;''zxcvbnm,./'
or 'esc', 'rarr', 'larr', 'uarr', 'darr', 'numrarr', 'numlarr', 'numuarr', 'numdarr', 'space', 'bksp', 'f1' - 'f12'

Example:

hotkey('r', 'goodmonkey(reward_dur, ''juiceline'', MLConfig.RewardFuncArgs.JuiceLine, ''eventmarker'', 14, ''nonblocking'', 1);'); % manual reward

hotkey('x', 'escape_screen(); assignin(''caller'',''continue_'',false);'); % stop the task immediately

idle

Syntax:

idle(duration);
idle(duration, screen_color);
idle(duration, screen_color, eventcodes);

Input arguments:

duration: In milliseconds
screen_color: New background color, [R G B]; can be an empty vector ([]) if the change is not necessary
eventcode: Code(s) to stamp when the screen color changes

Remarks:

When the screen_color is given, the background color changes for the duration and goes back to the initial color. See set_bgcolor, for how to change it permanently.

istouching

Syntax:

tf = istouching;

Return values:

tf: true if the screen is being touched. Otherwise, false.

mouse_position

This function returns the current mouse position and the button state.

Syntax:

xy_deg = mouse_position;
[xy_deg, buttons] = mouse_position;

Return values:

buttons: a 1-by-2 logical vector, [left right]; 1 - clicked, 0 - not clicked

reposition_object

This function moves graphic objects to new locations.

Syntax:

reposition_object(taskobjects, xy_degs);

Input arguments:

xy_degs: An n-by-2 matrix.

Example:

reposition_object([1 2], [-5 0; 5 0]); % move TaskObject#1 to [-5 0] and TaskObject#2 to [5 0]

rescale_object

This function changes the size of graphic objects to the given scale.

Syntax:

rescale_object(taskobjects, scale);

Input arguments:

scale: A scalar. 1 indicates the original size.

Example:

rescale_object([1 2], 2); % make TaskObject#1 & #2 twice larger

rotate_object

This function rotates graphic objects.

Syntax:

rotate_object(taskobjects, angle);

Input arguments:

angle: In degrees.

Example:

rotate_object([1 2], [45 60]); % rotate TaskObject#1 & #2 by 45 and 60 degrees, respectively

rewind_movie / rewind_sound

rewind_sound is the same as rewind_movie except that it works for SND objects, instead of MOVs.

Syntax:

rewind_movie;
rewind_movie(taskobjects);
rewind_movie(taskobjects, position);

Input arguments:

position: Zero, by default, if not given. In milliseconds.

Example:

rewind_movie; % rewind all movies to Time 0
rewind_movie([1 2], 1000); % move the playback position of both movies to 1 sec
rewind_movie([1 2], [500 1000]); % move the playback position of them to 0.5 sec and 1 sec

set_bgcolor

This function changes the background color of the subject screen.

Syntax:

set_bgcolor(bgcolor);

Input arguments:

bgcolor: New background color, [R G B]; can be an empty vector ([]) to switch back to the original background

Remarks:

To make this color change shown, one of the screen update calls (toggleobject, eyejoytrack, idle or run_scene) should be followed

Example:

set_bgcolor([1 0 0]); % change the background color to red
idle(1000);
set_bgcolor([]); % change it back to the original color
idle(0); % show the original background

set_iti

This function overwrites the default inter-trial interval set on the main menu.

Syntax:

set_iti(duration);

Remarks:

If this function is not called, the ITI is reset to the initial value set on the main menu.

showcursor / showcursor2

This function turns on and off the joystick cursor. By default, it is off. showcursor2 is for the 2nd joystick.

Syntax:

showcursor(status);

Input arguments:

status: Can be 'on'/'off' (char) or true/false (logical).

Example:

showcursor('on');

Remarks:

In the simulation mode, 'off' turns off the joystick cursor on the control screen as well.

touch_position

This function returns xy coordinates of the places that are currently being touched.

Syntax:

xy_deg = touch_position;

Return values:

xy_deg: a 1-by-(2 * # of touches) vector, like [x1 y1 x2 y2 x3 y3 ...]. If the touchscreen is not enabled, it is empty.

Remarks:

The total number of touches that can be simultaneously tracked can be set on the main menu. It is also dependent on the touchscreen's capability.
Untouched/detached coordinates are filled with NaN.

trialerror

This function records the success status of the trial to the TrialRecord structure.

Syntax:

trialerror(number);
trialerror(string); % case-insensitive

Input arguments:

error_code:

0 - Correct
1 - No response
2 - Late response
3 - Break fixation
4 - No fixation
5 - Early response
6 - Incorrect
7 - Lever break
8 - Ignored
9 - Aborted

trialtime

This function returns the current time in milliseconds.

Syntax:

time = trialtime;

user_text / user_warning

This function displays user texts on the control screen GUI at the end of a trial.

Syntax:

user_text(message);
user_warning(message);

Remarks:

user_text displays messages in blue and user_warning, in red.

eyejoytrack

This function monitors behavioral signal inputs.

Syntax:

[ontarget, rt] = eyejoytrack(tracking_type, taskobject(s), threshold, duration);
[ontarget, rt] = eyejoytrack(tracking_type1, taskobject(s)1, threshold1, tracking_type2, taskobject(s)2, threshold2, ..., duration);

Input arguments:

tracking_type: Choose one according to the signal type and the behavior type (acquisition or hold).

Signal type	Acquisition	Hold	Inverse acquisition
eye	'acquirefix'	'holdfix'
eye2	'acquirefix2'	'holdfix2'
joystick	'acquiretarget'	'holdtarget'
joystick2	'acquiretarget2'	'holdtarget2'
touch	'touchtarget'	'releasetarget'	'~touchtarget'
button	'acquiretouch'	'holdtouch'
function	'acquirefunc'	'holdfunc'

taskobject: TaskObject# (for eye, joystick, touch) or Button# (for button)
threshold: The target window size (for eye, joystick, touch) or voltage threshold (for button). Multiple rectangular windows can be set like [w1 h1; w2 h2; ...].
duration: In milliseconds

Remarks:

'acquirefix', 'acquiretarget', and 'touchtarget' return 1 immediately, when the XY input enters the threshold window. 'acquiretouch' also returns 1, when the button input becomes above the threshold. They all return 0 otherwise. You can provide multiple TaskObjects for these tracking types and, in that case, the return value, ontarget, is the ordinal number of the acquired target.

ontarget = eyejoytrack('acquirefix', 1, 3, 5000); % ontarget will be 1 if the eye comes in the 3-deg window around TaskObject#1 within 5000 ms
ontarget = eyejoytrack('acquiretarget', [2 3 5], 3, 2000); % ontarget will be 3 if the joystick captures TaskObject#5, because TaskObject#5 is the third object in the list

'holdfix', 'holdtarget' and 'releasetarget' returns 1, if the XY signal stays within the the threshold window for the given duration. 'holdtouch' does so, if the button input remains higher than the threshold for the duration. They all return 0 otherwise. These tracking types require only one TaskObject.
For button input, put Button# from the main menu I/O panel, instead of TaskObject#.

[ontarget, rt] = eyejoytrack('holdtouch', 2, 5, 500); % Button #2; input voltage should be larger than 5V to be ON
[ontarget, rt] = eyejoytrack('holdtouch', 2, [], 500); % use the default threshold; 3 for analog buttons and 0.5 for digital button

'~touchtarget' is a tracking type available for touch input only. eyejoytrack will return 1 when the outside of the threshold window is touched.
'acquirefunc' and 'holdfunc' allow using a user function as a signal source. The user function should return true or false to mimic the acquisition and loss of signals, respectively.

[ontarget, rt] = eyejoytrack('acquirefunc', @function_handle, input_args, duration); % input_args can be a cell, if multiple input arguments need to be provided

If multiple tracking types are provided, eyejoytrack returns a vector, in which each element indicates the success state of those tracking types. eyejoytrack will stop when any one of the tracking types succeeds.

ontarget = eyejoytrack('acquirefix', 1, 3, 'holdtouch', 1, [], 2000); % ontarget will be a 1-by-2 vector

eye fixation OFF & button NOT TOUCHED ⇒ eyejoytrack returns immediately & ontarget will be [0 0].
eye fixation ON & button NOT TOUCHED ⇒ eyejoytrack returns immediately & ontarget will be [1 0].
eye fixation OFF & button TOUCHED ⇒ eyejoytrack returns after 2 sec & ontarget will be [0 1].
eye fixation ON & button TOUCHED ⇒ eyejoytrack returns immediately & ontarget will be [1 1].

set_frame_event

This function marks the time with eventcodes when particular frames are presented.

Syntax:

set_frame_event(taskobject, frame_numbers, eventcodes);

Input arguments:

frame_numbers & eventcodes: The lengths of both vectors must be the same.

set_frame_order

This function rearranges the order of movie frames.

Syntax:

set_frame_event(taskobject, frame_order);

Input arguments:

frame_order: If empty, the frames are reset to the original order.

set_object_path

This function translates a graphic object through a given path.

Syntax:

set_object_path(taskobject, xy_deg);
set_object_path(taskobject, x_deg, y_deg);

Remarks:

To show the motion, either idle or eyejoytrack needs to be called.

toggleobject

This function turns on and off TaskObjects.

Syntax:

fliptime = toggleobject(taskobjects);
fliptime = toggleobject(taskobjects, option1, value1, option2, value2, ...);

Input arguments:

options: Case-insensitive. All options should be paired with values.

EventMarker - Behavioral code(s) to stamp at the presentation of the taskobject.
Status - 'on' or 'off'. Manually determines the status of the taskobjects
MovieStartFrame, MovieStep, StartPosition, PositionStep - These options are deprecated. To adjust the speed of movies, change their frame time with movie editing software.

Return values:

fliptime: The trialtime at which the screen "flip" occurs. In milliseconds.

Example:

toggleobject([1 2], 'eventmarker', 90, 'status', 'off'); % turn off both objects

Remarks:

If only non-visual stimuli (SND, STM and TTL) are provided, they are presented immediately without waiting for the screen flip.
When non-visual and visual stimuli are given together, the presentation of non-visual stimuli is synchronized with the screen flip timing.
To ensure the precise timing, avoid using multiple toggleobject commands, if possible.

'status'

'on'

'status'

'off'

'status'

'on'

% The last two commands can be combined as below

'status'

'on'

% TaskObject#1 will be off and TaskObject#2 will be on

create_scene

This function collects the information of the adapter chain for the offline trial replay.

Syntax:

scene = create_scene(adapter, taskobjects);

Input arguments:

taskobjects: TaskObject# to present during the scene. Can be a vector for multiple TaskObjects

Example:

fix = SingleTarget(eye_);
fix.Target = 1; % TaskObject#1
fix.Threshold = 3; % 3 deg
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth, [1 2]); % TaskObject#1 & #2
run_scene(scene);

Remarks:

The name of the adapter provided to create_scene is important, because run_scene finishes when that adapter stops.
See How to create adapter chains.

run_scene

This function runs the adapter chain.

Syntax:

fliptime = run_scene(scene, eventcodes);

Input arguments:

scene: This is the return value of create_scene.
eventcodes: Eventcode(s) to send out when the first frame of the scene is presented.

Return values:

fliptime: The trialtime (in milliseconds) at which the first frame of the screen is presented

Example:

fix = SingleTarget(eye_);
fix.Target = 1; % TaskObject#1
fix.Threshold = 3; % 3 deg
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth, 1); % TaskObject#1
fliptime = run_scene(scene, 10); % Eventcode 10 will be marked when the first frame is presented

Remarks:

This function does not end until the analyze function of the top-most adapter in the chain (the one provided to create_scene) returns false.

EyeTracker, Eye2Tracker, JoyTracker, Joy2Tracker, TouchTracker, ButtonTracker, MouseTracker, NullTracker

Users do not need to create tracker objects. They are pre-defined with reserved names in the timing script: eye_, eye2_, joy_, joy2_, touch_, button_, mouse_ and null_.

Success Condition:

Success: true if there are data samples read; otherwise, false

Stop Condition:

Trackers never stop the scene and should be used with other adapters.

Tracker Properties:

All trackers have common properties like the following.

Signal: The name of the signal that it reads ('Eye', 'Eye2', 'Joystick', 'Joystick2', 'Touch', 'Button', 'Mouse', 'Null')
Screen: The instance of the mlscreen object
DAQ: Data acquisition object
TaskObject: Task objects
CalFun: Calibration object

Every adapter in a chain can access the above objects via its Tracker property, which is a convenient way to get the information about screens, data sources and TaskObjects from the inside of the adapter.

obj.Tracker.Signal
obj.Tracker.Screen
obj.Tracker.DAQ
obj.Tracker.TaskObject
obj.Tracker.CalFun

The trackers also have the following data fields for different types.

eye_, eye2_ joy_, joy2_ touch_ button_ mouse_ null_

XYData
LastSamplePosition XYData
LastSamplePosition XYData
LastSamplePosition ClickData
LastSamplePosition XYData
ClickData
KeyInput
LastSamplePosition

XYData: An n-by-2 XY position matrix in screen pixels. In case of touch, 2 more columns are added per an additional touch (e.g., [x1 y1 x2 y2 ...]) and they are filled with [NaN NaN] when there is no touch.
ClickData: States of buttons; logical true (pressed) or false (released)
KeyInput: States of keys specified in the Mouse/Key menu; logical true (pressed) or false (released)
LastSamplePosition: Cumulative number of samples acquired before XYData, MouseData and ClickData were read. So the total number of samples read so far is LastSamplePosition + size(XYData,1).

These fields are continuously updated with data acquired during the previous frame (or data acquired before the scene start, if it is the very first frame of the scene). So, at a refresh rate of 60 Hz, about 16-17 samples are kept in each of them (except LastSamplePosition) from moment to moment.

Tracker Methods:

The thresholds of buttons can be adjusted like the following.

button_.threshold(button#, buttonThreshold);

Also you can invert the polarity of buttons as below, to make SingleButton respond to the button release, instead of the press.

button_.invert(button#);

SingleTarget

This adapter checks whether the position of a XY signal (eye_, joy_, and touch_) is within or outside the threshold window.

Success Condition:

Success: true while the position of the XY signal is within the threshold window; otherwise, false

Stop Condition:

When Success becomes true

Input properties:

Target: TaskObject# or a 2-element vector, [X Y], in degrees
Threshold: Size of the threshold window around the Target; a scalar (circle radius) or [width height] (rectangle) in degrees.
Color: Color of the threshold window shown on the control screen; [R G B]

Output properties:

Time: trialtime when the signal crosses the window; in milliseconds
TouchID: Touch # that is currently in the threshold window, in case that multi-touch is allowed

Example:

fix = SingleTarget(eye_); % Or other XY data sources, such as joy_ and touch_
fix.Target = [0 0]; % This can be TaskObject#
fix.Threshold = 3;
scene = create_scene(fix);
run_scene(scene); % The scene will end when the fixation is acquired

Remarks:

SingleTarget requires the XY signal to stay within the threshold window at least for one frame before changing its Success state, to prevent a jitter from being detected as a fixation/touch.

MultiTarget

This adapter creates a combination of SingleTarget and WaitThenHold for each target location, to check which target captures the XY signal.

Success Condition:

Success: true when one target is chosen AND the choice is held for HoldTime

Stop Condition:

When Success becomes true
When WaitTime is over without any fixation attempt or when the acquired fixation is broken before HoldTime passes

Input properties:

Target: TaskObject# or an n-by-2 matrix, [X1 Y1; X2 Y2; ...], in degrees
Threshold: Radius or [width height] of the detection window around the Target; in degrees
Color: Color of the threshold window shown on the control screen; [R G B]
WaitTime: Maximum time to wait until one of the targets is chosen; in milliseconds
HoldTime: Duration for which the choice should be held; in milliseconds
TurnOffUnchosen: true (by default) or false to determine whether to turn off unchosen targets during HoldTime

Output properties:

Waiting: true if the choice is never made
AcquiredTime: trialtime when the choice is made
ChosenTarget: Chosen TargetObject# or the row number of the chosen coordinates if the Target is a XY matrix.

Example:

mul = MultiTarget(eye_);
mul.Target = 1:4; % TaskObject 1-4
mul.Threshold = 3;
mul.WaitTime = 5000;
mul.HoldTime = 500;
scene = create_scene(mul, 1:4); % TaskObject 1-4
run_scene(scene);
if mul.Success
dashboard(1, sprintf('TaskObject#%d chosen', mul.ChosenTarget));
else
dashboard(1, '');
end
idle(1000);

Remarks:

In case that Target is TaskObjects, the ChosenTarget is TaskObject#, not the ordinal number of the chosen target.

WaitThenHold

This adapter checks if the Success state of the child adapter becomes true within WaitTime and stays true for HoldTime. It can be used to test if eye fixation or touch is acquired and maintained.

Success Condition:

Success: true if the Success of the child adapter becomes true within WaitTime AND stays true for HoldTime; false, until then.

Stop Condition:

When Success becomes true
When WaitTime is over without any fixation attempt or when the acquired fixation is broken before HoldTime passes

Input properties:

WaitTime: Maximum time to wait until the XY signal enters the threshold window; in milliseconds
HoldTime: Duration for which the fixation should be held; in milliseconds

Output properties:

Waiting: true if the fixation is never made
AcquiredTime: trialtime when the fixation is made

Example:

fix = SingleTarget(eye_);
fix.Target = [0 0];
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth);
run_scene(scene); % wth.Success will be true if the eye comes in the threshold window within 5 sec and stays for 0.5 sec
if wth.Success
dashboard(1, 'Success');
elseif wth.Waiting
dashboard(1, 'No fixation');
else
dashboard(1, 'Fixation break');
end
idle(1000);

Remarks:

Although SingleTarget is used as an example, WaitThenHold can track any adapter in which the Success property indicates its state change. See the "task\runtime v2\17 multi-input tracking 1" example.

FreeThenHold

This adapter is similar to WaitThenHold. The difference is that FreeThenHold allows breaking fixation and retrying, as long as MaxTime is not reached.

Success Condition:

Success: true if the fixation is made and maintained for HoldTime before MaxTime passes; false, until then.

Stop Condition:

When Success becomes true
When MaxTime is over with no fixation or broken fixations

Input properties:

MaxTime: Maximum time to allow trying fixation for; in milliseconds
HoldTime: Duration for which the fixation should be held; in milliseconds. HoldTime should be achieved before MaxTime is over.

Output properties:

BreakCount: Number of fixations that are made before the fixation succeeds or MaxTime is reached.
AcquiredTime: trialtime when the last fixation is made (i.e., the time of the last fixation window crossing)

Example:

fix = SingleTarget(eye_);
fix.Target = [0 0];
fix.Threshold = 3;
fth = FreeThenHold(fix);
fth.MaxTime = 5000;
fth.HoldTime = 500;
scene = create_scene(fth);
run_scene(scene); % fth.Success will be true if the eye comes in the threshold window within 5 sec and stays for 0.5 sec
if fth.Success
dashboard(1, 'Success');
elseif 0==fth.BreakCount
dashboard(1, 'No fixation');
else
dashboard(1, 'Fixation break');
end
idle(1000);

Remarks:

Although SingleTarget is used as an example, FreeThenHold can track any adapter in which the Success property indicates its state change.

LooseHold

This adapter checks if the Success state of the child adapter stays true for HoldTime. It allows brief state changes (i.e., to be false), as long as the change is shorter than BreakTime. This is useful to test if the previously acquired eye fixation is still maintained when temporary breaks due to blinking are okay.

Success Condition:

Success: true when the Success property of the child adapter remains true for HoldTime; false, until then.

Stop Condition:

When Success becomes true
When the Successfixation is broken for longer than BreakTime

Input properties:

HoldTime: Duration for which the fixation should be held; in milliseconds
BreakTime: Maximum duration to allow breaking fixation; in milliseconds

Example:

fix = SingleTarget(eye_);
fix.Target = [0 0];
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 0;
scene1 = create_scene(wth);
lh = LooseHold(fix);
lh.HoldTime = 3000;
lh.BreakTime = 500;
scene2 = create_scene(lh);
run_scene(scene1);
if wth.Success % We know the eye is fixating at this moment
run_scene(scene2); % lh.Success will be true if the fixation is hold for 3 sec without leaving the window for more than 0.5 sec
if lh.Success
dashboard(1, 'Success');
else
dashboard(1, 'Fixation break');
end
else
dashboard(1, 'No fixation');
end
idle(1000);

ComplementaryWindow

This adapter set a complementary window around the target(s) so that touching outside the window can be detected.

Success Condition:

Success: true if the outside of the window is touched; false, otherwise.

Stop Condition:

When Success becomes true

Input properties:

Target: TaskObject# or [x y] coordinates in degrees
Threshold: size of the window; a scalar or [w h] in degrees

Methods:

setTarget(arg1): arg1 can be either SingleTarget or MultiTarget object. Their target and threshold will be copied to ComplementaryWindow.

Example:

fix = SingleTarget(touch_);
fix.Target = [0 0];
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
out = ComplementaryWindow(touch_);
out.setTarget(fix);
ac = AllContinue(wth);
ac.add(out);
scene = create_scene(ac);
run_scene(scene);

SingleButton

This adapter checks if the specified button was pressed.

Success Condition:

Success: true while the button is pressed; false, otherwise.

Stop Condition:

When Success becomes true

Input properties:

Button: Button #

Output properties:

Time: trialtime when the button state changed last time; in milliseconds

Example:

btn = SingleButton(button_);
btn.Button = 1; % Button#1
scene = create_scene(btn);
run_scene(scene); % The scene will end when the button is pressed

Remarks:

SingleButton requires the button to be pressed at least for one frame before changing its Success property, to prevent a jitter from being detected as a normal button press.
To make SingleButton respond to the button release, instead of the press, you can invert the input via ButtonTracker (button_).

button_.invert(1); % Button#1

An inverted button is colored in red on the control screen and treated as a button sending out 0 when pressed.
The button threshold can be adjusted via ButtonTracker like the following.

button_.threshold(button#, buttonThreshold);

PulseCounter

This adapter counts the number of TTL pulses (or # of button presses).

Success Condition:

Success: true once a pulse is detected

Stop Condition:

When Success becomes true

Input properties:

Button: Button #

Output properties:

Count: Number of pulses (or button presses)
Time: trialtime(s) when the TTL input became HI (or the button was pressed) during the last frame; in milliseconds

Example:

pc = PulseCounter(button_);
pc.Button = 1; % Button#1
tc = TimeCounter(pc);
tc.Duration = 1000;
scene = create_scene(tc);
run_scene(scene);
dashboard(1, sprintf('Count: %d', pc.Count));
idle(1000);

Remarks:

Unlike SingleButton, PulseCounter does not require the button state to be stable for one frame and works with high-frequency input.
PulseCounter detects rising edges, not HI. If the button has been pushed before the beginning of the scene, it has to be released first.

OnsetDetector

This adapter detects when the child adapter's Success becomes true for the first time.

Success Condition:

Success: true once the Success of the child adapter becomes true

Stop Condition:

When Success becomes true

Input properties:

Time: trialtime of the first signal change

Example:

btn = SingleButton(button_);
btn.Button = 1; % Button#1
od = OnsetDetector(btn);
scene = create_scene(od);
run_scene(scene); % The scene will end when a signal change is detected
dashboard(1, sprintf('Onset time: %d ms', od.Time));
idle(1000);

Remarks:

PulseCounter also detects the onset, but OnsetDetector works with any adapter, not just with the buttons.
If the child's Success is true from the beginning, that does not count as the onset. What this adapter detects is a change from false to true.
If the child is one of the trackers, OnsetDetector becomes true from the beginning, since the trackers never become false.
Time is in millisecond resolution, only when the child adapter is SingleTarget, SingleButton, PulseCounter or KeyChecker. Otherwise, the precision drops to the multiple of the refresh rate.

KeyChecker

This adapter checks the state of a key. Key code(s) to monitor must be set in the non-DAQ devices menu first.

Success Condition:

Success: true once a key stroke is detected

Stop Condition:

When Success becomes true

Input properties:

KeyNum: Keycode number to track (the order in the keycodes given in the 'Mouse / Key' menu)

Output properties:

Count: Counts of key strokes
Time: trialtime(s) when the key was pressed

Example:

kc = KeyChecker(mouse_);
kc.KeyNum = 1; % 1st keycode
tc = TimeCounter(null_);
tc.Duration = 5000;
or = OrAdapter(kc);
or.add(tc);
scene = create_scene(or);
run_scene(scene);
if kc.Success, dashboard(1, sprintf('Key press time: %d ms', kc.Time(1))); end

Remarks:

This adapter requires MouseTracker (mouse_). To activate mouse_, check on 'Mouse / Key' in the non-DAQ devices menu and type keycodes that you want to monitor.

TimeCounter

This adapter measures a duration.

Success Condition:

Success: true when Duration has passed

Stop Condition:

When Success becomes true

Input properties:

Duration: In milliseconds

Example:

ttl = TTLOutput(null_);
ttl.Port = 1; % TTL #1 must be assigned in the I/O menu
tc = TimeCounter(ttl);
tc.Duration = 1000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

The stimuli will be presented for one frame even if the Duration is 0.
If the duration is not a multiple of the frame length, the actual duration can be longer up to one frame.
Stimuli will not turn themselves off, even after TimeCounter finishes. You need to call the idle command or present next scene to remove/stop them.

FrameCounter

This adapter measures a duration in terms of the number of frames.

Success Condition:

Success: true when the given number of frames (NumFrame) is presented

Stop Condition:

When Success becomes true

Input properties:

NumFrame: Number of frames

Example:

bhv_code(10, 'Scene start', 20, 'Image end');
img = ImageGraphic(null_);
img.List = { 'A.bmp', [0 0] };
fc = FrameCounter(img);
fc.NumFrame = 60; % 60 frames. Corresponds to 1 sec at a 60-Hz refresh rate
scene = create_scene(fc);
run_scene(scene, 10);
idle(500, [], 20); % Clear screen. This is time when the image goes off

Remarks:

FrameCounter will spend at least one frame, even if NumFrame is 0.
Stimuli will not turn themselves off, even after TimeCounter finishes. You need to call the idle command or present next scene to remove/stop them.

TriggerTimer

This adapter is used to delay the onset of stimuli that are created with adapters.

Success Condition:

Success: true when Delay has passed

Stop Condition:

When Success becomes true

Input properties:

Delay: In milliseconds.

Example:

trig = TriggerTimer(null_);
trig.Delay = 1000;
ttl = TTLOutput(trig);
ttl.Trigger = true; % This TTL will be triggered by TriggerTimer
ttl.Port = 1; % TTL #1 must be assigned in the I/O menu
tc = TimeCounter(ttl);
tc.Duration = 2000; % The TTL will last for the 2nd half of the 2000-ms period
scene = create_scene(tc);
run_scene(scene);

Remarks:

See How to Trigger Stimuli.

PhotoDiode

Normally the photodiode trigger is toggled only at the beginning of a scene, but this adapter makes it toggled every frame during the scene.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Example:

pd = PhotoDiode(null_);
tc = TimeCounter(pd);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

The photodiode trigger option should be selected on the main menu.

FrameMarker

This adapter stamps eventcode(s) when a particular frame is presented.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

FrameEvent: An n-by-2 cell or matrix. The 1st column is the frame number (1-based) and the 2nd column is the event(s).

Example:

bhv_code(2, 'Frame 10', 4, 'Frame 20');
fc = FrameCounter(null_);
fc.NumFrame = 60;
fm = FrameMarker(fc);
fm.FrameEvent = [10 2; 20 4]; % 2 when the 10th frame is presented and 4 when the 20th is presented
scene = create_scene(fm);
run_scene(scene);

Remarks:

Multiple codes can be provided as a cell.

OnOffMarker

This adapter sends out pre-set eventcodes when the state of the child adapter changes.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

OnMarker: Eventcode to send when the Success state of the child adapter changes from false to true
OffMarker: Eventcode to send when the Success state of the child adapter changes from true to false

Example:

bhv_code(0, 'Released', 1, 'Pressed');
btn = SingleButton(button_);
btn.Button = 1; % Button#1
oom = OnOffMarker(btn);
oom.OnMarker = 1;
oom.OffMarker = 0;
tc = TimeCounter(oom);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

The cycle of calling OnOffMarker is synchronized with the screen refresh rate, so the actual time of the state change can be earlier than the time of events by up to one frame length.

OnOffDisplay

This adapter displays pre-set messages depending on the state of the child adapter.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Dashboard: Dashboard line number
OnMessage: Message to show when the Success state of the child adapter is true
OffMessage: Message to show when the Success state of the child adapter is false
OnColor: Color of OnMessage
OffColor: Color of OffMessage

Example:

btn = SingleButton(button_);
btn.Button = 1; % Button#1
ood = OnOffDisplay(btn);
ood.Dashboard = 1;
ood.OnMessage = 'Pressed';
ood.OffMessage = 'Not pressed';
tc = TimeCounter(ood);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);
idle(0);

AnalogInputMonitor

This adapter draws a trace of a selected General Input on the control screen for a monitoring purpose.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Channel: General input number from the I/O menu
Position: [left top width height] of the monitor panel in pixels. The left-top corner of the control screen is [0 0] and the right-bottom is [800 600].
YLim: Voltage range ([ymin ymax]) of the selected General Input to display
Title: Name of the selected General Input
Color: [R G B]
Modulus: Number of frames per monitor update. 1, by default.

Example:

aim = AnalogInputMonitor(null_);
aim.Channel = 1; % General Input 1
aim.Position = [580 20 200 50]; % [left top width height]
aim.YLim = [0 5];
aim.Title = 'Heart beat';
aim.Modulus = 2; % redraw every 2 frames
tc = TimeCounter(aim);
tc.Duration = 10000;
scene = create_scene(tc);
run_scene(scene);

BoxGraphic

This adapter draws a square/rectangle.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

EdgeColor: [R G B]
FaceColor: [R G B]
Size: A scalar (square) or a 1-by-2 vector (rectangle), [width height]
Position: [X Y] in degrees
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: Use this property to create multiple objects at once.

box.List = { edgecolor1, facecolor1, size1, position1, scale1, angle1; ...
edgecolor2, facecolor2, size2, position2, scale2, angle2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

box = BoxGraphic(eye_);
box.EdgeColor = [1 0 0];
box.FaceColor = [0 0 1];
box.Size = [4 3];
box.Position = [-5 5];
fix = SingleTarget(box);
fix.Target = box.Position; % Use [X Y], instead of TaskObject#, since BoxGraphic is not TaskObject
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth);
run_scene(scene);

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

CircleGraphic

This adapter is the same as BoxGraphic except that this one draws a circle/oval.

Remarks:

For the Size argument, use a scalar for a circle (diameter, not radius) or a 1-by-2 vector for an oval ([width height]).

PieGraphic

This adapter draws a filled arc.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

EdgeColor: [R G B]
FaceColor: [R G B]
Size: A scalar (square) or a 1-by-2 vector (rectangle), [width height]
Position: [X Y] in degrees
StartDegree: Angle measured in degrees counter-clockwise from the x-axis to the first side of the pie shape
CenterAngle: Angle measured in degrees counter-clockwise from StartDegree to the second size of the pie shape
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: Use this property to create multiple objects at once.

pie.List = { edgecolor1, facecolor1, size1, position1, startdeg1, centerang1, scale1, angle1; ...
edgecolor2, facecolor2, size2, position2, startdeg2, centerang2, scale2, angle2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

pie = PieGraphic(eye_);
pie.EdgeColor = [1 0 0];
pie.FaceColor = [1 1 0];
pie.Size = [4 3];
pie.Position = [-5 5];
pie.StartDegree = 45;
pie.CenterAngle = 270;
fix = SingleTarget(pie);
fix.Target = pie.Position; % Use [X Y], instead of TaskObject#, since PieGraphic is not TaskObject
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth);
run_scene(scene);

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

PolygonGraphic

This adapter draws a user-defined polygon.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

EdgeColor: [R G B]
FaceColor: [R G B]
Size: A scalar (square) or a 1-by-2 vector (rectangle), [width height]
Position: [X Y] in degrees
Vertex: An n-by-2 matrix (n = number of vertices), [X1 Y1; X2 Y2; ...] in normalized coordinates (0 to 1)
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: Use this property to create multiple objects at once.

poly.List = { edgecolor1, facecolor1, size1, position1, vertex1, scale1, angle1; ...
edgecolor2, facecolor2, size2, position2, vertex2, scale2, angle2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

star = PolygonGraphic(eye_);
star.EdgeColor = [0 1 0];
star.FaceColor = [0 1 0];
star.Size = 2;
star.Position = [0 0];
star.Vertex = [0.5 1; 0.375 0.625; 0 0.625; 0.25 0.375; 0.125 0; 0.5 0.25; 0.875 0; 0.75 0.375; 1 0.625; 0.625 0.625];
fix = SingleTarget(star);
fix.Target = star.Position; % Use [X Y], instead of TaskObject#, since PolygonGraphic is not TaskObject
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene = create_scene(wth);
run_scene(scene);

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

TextGraphic

This adapter draws a user string.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Text: Text to display
Position: [X Y] in degrees
FontFace: Font name ('Arial', by default).
FontSize: In points (10, by default)
FontColor: [R G B] ([1 1 1], by default)
FontStyle: 'normal' (default), 'bold', 'italic', 'underline' or 'strikeout'
HorizontalAlignment: 'left' (default), 'center' or 'right'
VerticalAlignment: 'top' (default), 'middle' or 'bottom'
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: Use this property to create multiple objects at once.

text.List = { text1, position1, fontface1, fontsize1, fontcolor1, fontstyle1, halign1, valign1, scale1, angle1; ...
text2, position2, fontface2, fontsize2, fontcolor2, fontstyle2, halign2, valign2, scale2, angle2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

txt = TextGraphic(null_);
txt.Text = 'This is a test.';
txt.Position = [0 0];
txt.FontSize = 100;
txt.FontColor = [0 1 0];
txt.FontStyle = 'italic';
txt.HorizontalAlignment = 'center';
txt.VerticalAlignment = 'middle';
tc = TimeCounter(txt);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);
idle(0); % Clean up

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

ImageGraphic

This adapter presents static images.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Position: [X Y] in degrees
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: An n-by-2, n-by-3 or n-by-4 cell matrix. Use this propert to create image objects. Then you can change Position, Scale and Angle properties.

1st column: Image filename or image matrix (Y-by-X-by-3 or Y-by-X-by-4)
2nd column: Image XY position in visual angles, an n-by-2 matrix ([x1 y1; x2 y2; ...])
3rd column (optional): Colorkey, [R G B] that should look transparent
4th column (optional): Resize parameter. [Xsize Ysize] in pixels or a scalar (scale).
5th column (optional): Angle. In degrees.

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Output properties:

Size: Size of the created graphic. In degrees.

Example:

img = ImageGraphic(null_);
img.List = { {'A.bmp','B.bmp'}, [-3 0; 3 0] };
fc = FrameCounter(img);
fc.NumFrame = 60;
scene = create_scene(fc);
run_scene(scene);
idle(0); % Clear the screen

Remarks:

The image matrix should be double or uint8 and have values between 0 and 255. In case of double, the values can be numbers between 0 to 1, too.
Column 3 & 4 of List is optional. You can assign just an n-by-2 matrix.
When the scene ends, the image(s) will stay on the screen and need to be manually cleared with idle(0).

MovieGraphic

This adapter presents movies.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Position: [X Y] in degrees
Looping: 0 (do not repeate) or 1 (repeate)
Scale: Magnification. 1, by default.
Angle: Rotation in degrees. 0, by default.

List: An n-by-2 or n-by-3 cell matrix. Use this propert to create movie objects. Then you can change other properties.

1st column: Movie filename or movie matrix (Y-by-X-by-3-by-N or Y-by-X-by-4-by-N, N: # of frames)
2nd column: XY position in visual angles, an n-by-2 matrix ([x1 y1; x2 y2; ...])
3rd column (optional): Repeat (true) or not (false, by default) when the end of the movie is reached
4th column (optional): Scale. A scalar. 1 means no change in size.
5th column (optional): Angle. In degrees.

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Output properties:

Size: Size of the created graphic. In degrees.

Example:

mov = MovieGraphic(null_);
mov.List = { 'testmovie.avi', [0 0] };
tc = TimeCounter(mov);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);
idle(0); % Clear the screen

Remarks:

If the scene ends before the movie finishes, the last shown frame will stay on the screen. It will be cleared when the next scene starts or you can clear the screen manually with idle(0).

SineGrating

This adapter draws a sine grating.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Position: [X Y] in degrees
Radius: Radius of the aperture in degrees
Direction: Degree
SpatialFrequency: Cycles per degree
TemporalFrequency: Cycles per second
Phase: Degree
Color1: 1-by-3 RGB vector
Color2: 1-by-3 RGB vector
WindowType: 'none', 'circular' (default), 'triangular', 'sine' (or 'cosine'), 'hann', 'hamming', 'gaussian'
WindowSize: sigma for 'gaussian'

List: Use this property to create multiple objects at once.

grat.List = { position1, radius1, direction1, spatialfreq1, temporalfreq1, phase1, color11, color21, wintype1, winsize1; ...
position2, radius2, direction2, spatialfreq2, temporalfreq2, phase2, color12, color22, wintype2, winsize2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Output properties:

Size: Size of the created graphic. In degrees.

Example:

grat = SineGrating(null_);
grat.Position = [0 0];
grat.Radius = 3;
grat.Direction = 45;
grat.SpatialFrequency = 1;
grat.TemporalFrequency = 2;
grat.Color1 = [1 0 0];
grat.Color2 = [0 1 0];
grat.WindowType = 'gaussian';
grat.WindowSize = 1;
tc = TimeCounter(grat);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

RandomDotMotion

This adapter draws a random dot motion stimulus.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Position: [X Y] in degrees
Radius: Radius of the aperture in degrees
Coherence: 0 to 100
Direction: Degree
Speed: Degrees per sec
NumDot: Numbers of dots; 100, by default
DotSize: In degrees; 0.15, by default
DotColor: [R G B]; [1 1 1], by default
Interleaf: Number of frames interleaving; 3, by default
List: Use this property to create multiple objects at once.

rdm.List = { position1, radius1, coherence1, direction1, speed1, numdot1, dotsize1, dotcolor1, interleaf1; ...
position2, radius2, coherence2, direction2, speed2, numdot2, dotsize2, dotcolor2, interleaf2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

rdm = RandomDotMotion(null_);
rdm.Position = [0 0];
rdm.Radius = 5;
rdm.Coherence = 30;
rdm.Direction = 0;
rdm.Speed = 5;
tc = TimeCounter(rdm);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

The graphics created by adapters do not have TaskObject#. Use their [X Y] positions to set them as targets.

ImageChanger

This adapter presents multiple image sets in series.

Success Condition:

Success: true when all the images in the list are presented

Stop Condition:

When Success becomes true

Input properties:

List: An n-by-3 or n-by-4 or n-by-5 cell matrix.

1st column: Image filename(s)
2nd column: Image XY position(s) in visual angles, an n-by-2 matrix ([x1 y1; x2 y2; ...])
3rd column: Duration in number of frames (or in milliseconds. See the DurationUnit property below.)
4th column: Eventmarker(s); optional
5th column: Resize parameter, [Xsize Ysize] in pixels; optional

DurationUnit: 'frame' (by default) or 'msec'

Output properties:

Time: trialtime (an n-by-1 vector) when each image was presented during the scene. NaN for images not shown.

Example:

img = ImageChanger(null_);
img.List = { {'A.bmp','C.bmp'}, [5 5; -5 -5], 15, 101; ...
scene = create_scene(img);
run_scene(scene);

Remarks:

If multiple images are assigned in the same row of List, they will be displayed simultaneously.
The image matrix should be double or uint8 and have values between 0 and 255. In case of double, the values can be numbers between 0 to 1, too.
Column 4-5 of List are optional. You can assign just an n-by-3 (or n-by-4 or n-by-5) matrix. If you want to assign Column 5, you have to assign Column 4 as well.
This adapter takes one additional frame and clear the screen after the last image is presented.

AudioSound

This adapter presents audio sounds.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

List: Audio filename(s) or 1-by-2 vector(s) of [duration frequency].

sound.List = { filename1; ...
[2000 1000]; ...
filename2; ... }

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

snd = AudioSound(null_);
snd.List = [2000 1000]; % 1-kHz sine wave for 2 sec
tc = TimeCounter(snd);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);

Remarks:

If the List is [duration frequency], a sine-wave tone of the given duration and frequency will be played

Stimulator

This adapter delivers electrical stimulation via analog output.

Success Condition:

Success: true when the delivery of the current waveform is done

Stop Condition:

When Success becomes true

Input properties:

Channel: Stimulation# (scalar or vector) assigned on the I/O menu.
Waveform: A column vector, matrix (n-by-NumOfChannels) or cell array (for multiple waveforms) that contains the waveform data
Frequency: The rate of the waveform sample generation, samples per second
WaveformNumber: In case that multiple waveforms are loaded (as a cell array), this property indicates which waveform will be used.

Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

stim = Stimulator(null_);
stim.Channel = [1 2]; % Stimulation #1 & #2
stim.Waveform = {repmat([1 0.5; 0 0],5,1) [0.1 0.2 0.3 0.4 0.5 0; 0.5 0.4 0.3 0.2 0.1 0]'}; % two sets of waveforms
stim.Frequency = 100;
stim.WaveformNumber = 1; % waveform set #1
scene = create_scene(stim);
run_scene(scene); % send out the waveform set #1
stim.WaveformNumber = 2; % waveform set #2
run_scene(scene); % Do not create the Stimulator twice. Just recycle the same object.

Remarks:

You can trigger more than one analogoutput channel at once, but they have to be triggered simultaneously, not independently. This is a limitation of the DAQ device. If you want two independent stimulations, you need two DAQ boards.

TTLOutput

This adapter send out a TTL pulse via a digital line.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Input properties:

Port: TTL #. It should be assigned in the I/O menu.
Trigger: true or false. See How to Trigger Stimuli.
EventMarker: Event marker for the trigger

Example:

See TriggerTimer.

AndAdapter

This adapter combines multiple adapter chains and finishes the scene when all the chains succeed.

Success Condition:

Success: true when all child chains' Success property become true

Stop Condition:

When Success becomes true

Methods:

add(adapter): Add another adapter chain

Example:

btn = SingleButton(button_);
btn.Button = 1;
fix = SingleTarget(eye_);
fix.Target = [-5 5];
fix.Threshold = 3;
and = AndAdapter(btn);
and.add(fix);
scene = create_scene(and);
run_scene(scene); % The scene ends when the eye fixation is made AND the button is pressed

Remarks:

Note that AndAdapter's behavior is dependent on the child chains' success conditions, not the stop conditions.

OrAdapter

This adapter combines multiple adapter chains and finishes the scene when any one of them succeed.

Success Condition:

Success: true when the Success property of any one adapter chain becomes true

Stop Condition:

When Success becomes true

Methods:

add(adapter): Add another adapter chain

Example:

btn = SingleButton(button_);
btn.Button = 1;
fix = SingleTarget(eye_);
fix.Target = [-5 5];
fix.Threshold = 3;
or = OrAdapter(btn);
or.add(fix);
scene = create_scene(or);
run_scene(scene); % The scene ends when the eye fixation is made OR the button is pressed

Remarks:

Note that OrAdapter's behavior is dependent on the child chains' success conditions, not the stop conditions.

NotAdapter

This adapter negates the Success state of the child adapter.

Success Condition:

Success: the opposite of the child adapter's Success

Stop Condition:

When the child adapter stops

Example:

btn = SingleButton(button_);
btn.Button = 1;
nbtn = NotAdapter(btn); % invert the Success state of SingleButton
fix = SingleTarget(eye_);
fix.Target = [-5 5];
fix.Threshold = 3;
and = AndAdapter(nbtn);
and.add(fix);
scene = create_scene(and);
run_scene(scene); % The scene ends when the eye fixation is made AND the button is NOT pressed

TrueAdapter

This adapter's Success state is always true.

Success Condition:

Success: Always true

Stop Condition:

When the child adapter stops

Example:

fix1 = SingleTarget(eye_);
fix1.Target = [-5 0]; % left target
fix1.Threshold = 3;
fix2 = SingleTarget(eye_);
fix2.Target = [5 0]; % right target
fix2.Threshold = 3;
fix2t = TrueAdapter(fix2); % This adapter chain's Success is always true.
and = AndAdapter(fix1);
and.add(fix2t);
scene = create_scene(and);
run_scene(scene); % The scene ends when the left target is acquired

Remarks:

When combining multiple adapter chains, for example, with AndAdapter, you can prevent some of them from terminating the scene by setting their Success state always true. To set the Success property false, add NotAdapter.

Concurrent

This adapter runs multiple chains simultaneously, but its Success state and stop condition follow only those of the first adapter chain.

Success Condition:

Success: true when the top-most adapter of the first chain succeeds

Stop Condition:

When the top-most adapter of the first chain stops

Methods:

add(adapter): Add another adapter chain

Example:

fix = SingleTarget(eye_);
fix.Target = [0 0];
fix.Threshold = 3;
grat = SineGrating(null_); % Display a grating and a fixation point while checking eye signals
grat.Position = [5 5];
crc = CircleGraphic(grat);
crc.FaceColor = [1 0 0];
con = Concurrent(fix); % Only SingleTarget determines when this scene will end
con.add(crc);
scene = create_scene(con);
run_scene(scene); % The scene ends when the fixation is acquired
idle(0);

Remarks:

This adapter is useful to run additional chains that are irrelevant to behavior tracking.

AllContinue

This adapter continues the scene only when all adapter chains continue.

Success Condition:

Success: true if all child chains continue.

Stop Condition:

When any child chain stops.

Methods:

add(adapter): Add another adapter chain

AnyContinue

This adapter continues the scene if any of the child adapter chains continues.

Success Condition:

Success: true if any child chain continues.

Stop Condition:

When all child chains stop.

Methods:

add(adapter): Add another adapter chain

Sequential

This adapter runs multiple chains sequentially.

Success Condition:

Success: true when the last chain is finished succesfully

Stop Condition:

When any chain stops with its Success false or when the last chain is finished

Input properties:

EventMarker: Event marker(s) to send out, when each chain begins. Use NaN to skip a particular chain.

Output properties:

CurrentChain: Chain # that is currently running or the last chain that ran, if the adapter stopped before finishing all the chains.

Methods:

add(adapter): Add another adapter chain

Example:

% any1 -- seq1a -- tc1a -- box1
% | +--- tc1b
% |
% +--- seq1b -- tc1c
% +--- tc1d -- crc1
box1 = BoxGraphic(null_); % 1st chain of seq1a
box1.List = { [1 1 1], [1 1 1], 1, [-5 0], 1, 0 };
tc1a = TimeCounter(box1);
tc1a.Duration = 2000;
tc1b = TimeCounter(null_); % 2nd chain of seq1a
tc1b.Duration = 1000;
seq1a = Sequential(tc1a);
seq1a.add(tc1b); % seq1a runs two chains sequentially. A box for 2 s and a blank for 1 s
tc1c = TimeCounter(null_); % 1st chain of seq1b
tc1c.Duration = 1000;
crc1 = CircleGraphic(null_); % 2nd chain of seq1b
crc1.List = { [1 1 1], [1 1 1], 1, [5 0], 1, 0 };
tc1d = TimeCounter(crc1);
tc1d.Duration = 2000;
seq1b = Sequential(tc1c);
seq1b.add(tc1d); % seq1b runs two chains sequentially. A blank for 1 s and then a circle for 2 s
any1 = AnyContinue(seq1a); % Run both seq1a and seq1b simultaneously.
any1.add(seq1b); % The box and the circle will be overlapped in time for 1 s.
scene1 = create_scene(any1);
run_scene(scene1);
idle(0);

Remarks:

This adapter can be used to combine multiple scenes into one.

CurveTracer

This adapter translates the position of a TaskObject along the given path.

Success Condition:

Success: true when the trajectory is traced to the end

Stop Condition:

When Success becomes true

Input properties:

Target: TaskObject#
Trajectory: An n-by-2 matrix, [X1 Y1; X2 Y2; ...]

Output properties:

Time: trialtime (an n-by-1 vector) when the position was changed during the scene. NaN for unused coordinates.

Example:

t = linspace(0, 2*pi, 1000)';
x = 6 * sin(3 * t);
y = 9 * sin(4 * t) ./ 1.5;
ct = CurveTracer(null_);
ct.Target = 1; % TaskObject#1
ct.Trajectory = [x y];
scene = create_scene(ct, ct.Target);
run_scene(scene);

SmoothPursuit

This adapter translates the position of a TaskObject along the path defined by the direction and speed parameters and checks if the XY signal remains inside the fixation threshold.

Success Condition:

Success: true when the target is followed for the Duration without the threshold window violated

Stop Condition:

When Duration has passed (i.e, when the Success becomes true)
When the gaze escapes the Threshold window before Duration is up

Input properties:

Target: TaskObject#
Threshold: Fixation window size in degrees
Color: [R G B]
Origin: [X Y] in degrees
Direction: Degree
Speed: Degrees per second
Duration: In milliseconds

Output properties:

Time: Time of the threshold window crossing, if happened

Example:

fix = SingleTarget(eye_);
fix.Target = 1; % TaskObject#1
fix.Threshold = 2;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
scene1 = create_scene(wth, fix.Target);
sp = SmoothPursuit(eye_);
sp.Target = 1; % TaskObject#1
sp.Threshold = 2;
sp.Origin = [0 0];
sp.Direction = 45;
sp.Speed = 3;
sp.Duration = 2500;
scene2 = create_scene(sp, sp.Target);
run_scene(scene1);
run_scene(scene2); % The scene will be done, whether the eye follows TaskObject#1 for 2.5 sec successfully or escapes the threshold window

FixTimeAnalyzer

This adapter counts how long a XY signal stays in the threshold window.

Success Condition:

Success: true when the child adapter's Success is true

Stop Condition:

When the child adapter stops

Output properties:

FixTime: Total accumulated fixation time in milliseconds

Example:

fix.Target = [0 0];
fix.Threshold = 3;
fta = FixTimeAnalyzer(fix);
tc = TimeCounter(fta);
tc.Duration = 5000;
scene = create_scene(tc);
run_scene(scene);
dashboard(1, sprintf('Fixation time: %d ms',fta.FixTime));

Remarks:

FixTime will be different from the actual time in the simulation mode.

DragAndDrop

This adapter tracks the selected graphic stimulus until it is released from the previous hold. If the released location is close to the destination, the stimulus is pulled to the destination like a magnet. Otherwise, it goes back to the initial location.

Success Condition:

Success: true when the stimulus is dropped on the destination

Stop Condition:

When the stimulus is released from the hold (i.e., dropped) and moved to either destination or initial location.

Input properties:

Destination: [x y] in degrees
Gravity: degrees per second
GravityWindow: radius in degrees; [width height] for a rectangular window
Color: color of the gravity window. radius in degrees; [width height] for a rectangular window

Output properties:

DropTime: trialtime when the stimulus is released

Methods:

setTarget(graphic_obj, index): Either graphic TaskObject or graphic adapter. If the graphic adapter has multiple objects created with the List property, use the optional index argument, to indicate which one is selected.
reset(): Return the target to its initial position.

Example:

txt1 = TextGraphic(null_);
txt1.Text = '+';
txt1.Position = [5 0];
txt1.FontSize = 30;
txt1.HorizontalAlignment = 'center';
txt1.VerticalAlignment = 'middle';

crc1 = CircleGraphic(null_);
crc1.EdgeColor = [1 0 0];
crc1.FaceColor = [0 0 01];
crc1.Size = 3;
crc1.Position = [-5 0];

tar1 = SingleTarget(touch_);
tar1.Target = crc1.Position;
tar1.Threshold = 3;
wth1 = WaitThenHold(tar1);
wth1.WaitTime = 10000;
wth1.HoldTime = 50;
con1 = Concurrent(wth1);
con1.add(crc1);
con1.add(txt1);
scene1 = create_scene(con1);

dd2 = DragAndDrop(touch_);
dd2.Destination = txt1.Position;
dd2.GravityWindow = 3;
dd2.setTarget(crc1);
con2 = Concurrent(dd2);
con2.add(txt1);
scene2 = create_scene(con2);

dashboard(1,'');

run_scene(scene1);
if wth1.Success
run_scene(scene2);
end

if ~wth1.Success
dashboard(1,'Not picked!');
elseif ~dd2.Success
dashboard(1,'Not on the destination!');
else
dashboard(1,'Good job!');
end

Remarks:

This adapter requires touch input.
Before DragAndDrop is called, the target should be being touched. Confirm the finger touch first in the previous scene, as shown in the above example.

behaviorsummary

This function reads data files (*.bhv2; *.h5; *.mat) and shows a performance summary.

bhv2mat

This function converts BHV2 files (*.bhv2) to MAT files (*.mat). The converted MAT files are still readable with mlread.

Syntax:

bhv2mat; % This will open a file dialog. Multiple files can be selected
bhv2mat(filelist); % filelist can be a cell string array for multiple files

mlconcatenate

This function combines trial-by-trial analog data into one large matrix and adjusts all timestamps accordingly, as if they are recorded in one single trial. It is useful when reading data files that are continuously recorded through inter-trial intervals.

Syntax:

data = mlconcatenate;
data = mlconcatenate(filename);
[data, MLConfig, TrialRecord, filename] = mlconcatenate;

mlexportstim

This function extracts saved stimuli from the data file.

Syntax:

stim_path = mlexportstim; % open dialogs to pick up the data file and the save destination
mlexportstim(destination_path, datafile);

mlexportwebcam

This function reads webcam video from the data file and save it as AVI (R2011b or earlier) or MP4 (R2012a or later). If the remove_cam option (false, by default) is true, a new data file that has no cam data is created additionally. The name of the new file is suffixed with '_edited' so that the original file is not modified.

Syntax:

mlexportwebcam
mlexportwebcam(datafile)
mlexportwebcam(datafile, remove_cam)

mlplayer

This function opens a trial-replay and video-exporting dialog.

mlread

This function provides a unified read interface for all the data formats (*.bhv2; *.h5; *.mat). It returns trial-by-trial data in a 1-by-n array of structures.

Syntax:

data = mlread;
data = mlread(filename);
[data, MLConfig, TrialRecord, filename] = mlread(__);

mlreadwebcam

This function reads webcam video from the data file.

Syntax:

video = mlreadwebcam(trial_num);
video = mlreadwebcam(trial_num, cam_num); % cam_num: 1-4
video = mlreadwebcam(trial_num, cam_num, filename);
[video, timestamp] = mlreadwebcam(__);

Adapters for Version 2
EyeTracker Eye2Tracker JoyTracker Joy2Tracker TouchTracker ButtonTracker MouseTracker NullTracker SingleTarget MultiTarget WaitThenHold FreeThenHold LooseHold ComplementaryWindow SingleButton PulseCounter OnsetDetector KeyChecker TimeCounter FrameCounter TriggerTimer PhotoDiode FrameMarker OnOffMarker OnOffDisplay AnalogInputMonitor	BoxGraphic CircleGraphic PieGraphic PolygonGraphic TextGraphic ImageGraphic MovieGraphic SineGrating RandomDotMotion ImageChanger AudioSound Stimulator TTLOutput AndAdapter OrAdapter NotAdapter TrueAdapter Concurrent AllContinue AnyContinue Sequential CurveTracer SmoothPursuit FixTimeAnalyzer DragAndDrop

eye_, eye2_	joy_, joy2_	touch_	button_	mouse_	null_
XYData LastSamplePosition	XYData LastSamplePosition	XYData LastSamplePosition	ClickData LastSamplePosition	XYData ClickData KeyInput LastSamplePosition

Timing script functions

Runtime functions

Version 1 specific

Version 2 specific

Adapters for Version 2

Command window functions

bhv_code

bhv_variable

dashboard

editable

escape_screen

eventmarker

eye_position / eye2_position / joystick_position / joystick2_position

get_analog_data

get_movie_duration

get_sound_duration

getkeypress

goodmonkey

hotkey

idle

istouching

mouse_position

reposition_object

rescale_object

rotate_object

rewind_movie / rewind_sound

set_bgcolor

set_iti

showcursor / showcursor2

touch_position

trialerror

trialtime

user_text / user_warning

eyejoytrack

set_frame_event

set_frame_order

set_object_path

toggleobject

create_scene

run_scene

EyeTracker, Eye2Tracker, JoyTracker, Joy2Tracker, TouchTracker, ButtonTracker, MouseTracker, NullTracker

SingleTarget

MultiTarget

WaitThenHold

FreeThenHold

LooseHold

ComplementaryWindow

SingleButton

PulseCounter

OnsetDetector

KeyChecker

TimeCounter

FrameCounter

TriggerTimer

PhotoDiode

FrameMarker

OnOffMarker

OnOffDisplay

AnalogInputMonitor

BoxGraphic

CircleGraphic

PieGraphic

PolygonGraphic

TextGraphic

ImageGraphic

MovieGraphic

SineGrating

RandomDotMotion

ImageChanger

AudioSound

Stimulator

TTLOutput

AndAdapter

OrAdapter

NotAdapter

TrueAdapter

Concurrent

AllContinue

AnyContinue

Sequential