NIMH ML: Docs

bhv_code

This function assigns 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 on the control screen.

Syntax:

dashboard(line_number, text, color);
dashboard(line_number, text, color, property1, value1, property2, value2, ...);
dashboard(line_number, text, property1, value1, property2, value2, ...);

Input arguments:

line_number: Ten lines of strings can be displayed.

Example:

dashboard(1, 'DMS Task');
dashboard(2, sprintf('Choice: %d', choice), [1 1 1], 'bgcolor', [0 0 0]);

Remarks:

This function does not update the screen itself. For the text to be displayed, one of screen update commands (toggleobject, eyejoytrack, idle or run_scene) should be followed.
The text stays on the screen even after the end of a trial, until it is modified by another dashboard call. To delete it, assign an empty string ('').

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');

face_color = [0.5 0.5 0.5]; edge_color = [1 0 0]; % color should be between 0 and 1
editable('fix_size', '-color', {'face_color', 'edge_color'});

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:

Editable variables must be initialized in the timing script with specific values (numbers or characters). They cannot be initialized with other variables or return values of functions.
var1 = 1000;
editable('var1'); % okay

var1 = 1000;
var2 = var1;
editable('var2'); % error!!!
Variables with no type should be logical or double with 6 elements or fewer.
The type argument allows users to invoke MATLAB GUI controls to pick up a filename, a directory name or a color.
The variable types for '-file' and '-dir' should be char.
The '-color' variable should be a 1-by-3 vector, [R G B], between 0 and 1.
The '-category' type must be a cell char 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.
For editable variables, trial-by-trial change histories are recorded in the data file. Check the VariableChanges field in the data file.

escape_screen

This function pauses the task after the current trial.

Syntax:

escape_screen;

eventmarker

This function marks the current time with 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.

To more accurately mark onset times of stimuli or rewards, use the eventmarker option of toggleobject and goodmonkey or the eventcode argument of run_scene, instead of this function.

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 values are in degrees.

Syntax:

xy_deg = eye_position;
[x_deg y_deg] = eye_position;

forced_eye_drift_correction

This function translates the current eye calibration grid to a new origin.

Syntax:

forced_eye_drift_correction;
forced_eye_drift_correction(origin);
forced_eye_drift_correction(origin, eye_num);

Input arguments:

origin: [x y] in degrees
eye_num: 1 for eye1 (default), 2 for eye2

Example:

forced_eye_drift_correction; % correct eye 1. see the remarks.
forced_eye_drift_correction([], 2); % correct eye 2. see the remarks.
forced_eye_drift_correction([1 0], 2); % [1 0] will be the new center of eye2

Remarks:

In case the origin argument is not provided or is empty, this function determines the new origin based on these rules.

- [0 0], if there is no visual object on the screen
- The position of the visual object, if there is only one on the screen
- The position of the visual object closest to the current eye position, if there are multiple objects on the screen

The position of the new origin will be recorded in the VariableChanges field of the data file at the end of each trial.

get_analog_data

This function returns the most recently acquired analog samples of the specified signal.

Syntax:

data = get_analog_data(sig_name);
data = get_analog_data(sig_name, num_samples);
[data, sample_rate] = get_analog_data(__);

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')
'high#' or 'highfrequency#' (e.g., 'high1', 'highfrequency1')
'voice'

num_samples: Number of samples to return. 1 by default.

Return values:

data is an n-by-1 vector or an n-by-2 matrix, depending on the signal type.
sample_rate is the actual sample rate of the signal. See the remarks below for more information.

Example:

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

Remarks:

This function takes a snapshot of the most recently acquired data backward in time and returns immediately.
The size of data can be less than num_samples, if the number of recorded samples is small.
Check sample_rate for the actual sample rate of data. The rate of online sampling may be different from what is chosen on the menu. For example, analog signals (except for high frequency channels and voice) are internally sampled at 1 kHz, regardless of the [AI sample rate] setting on the main menu, and then resampled before stored in the data file.

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 initiates timed reward pulses to reward devices.

Syntax:

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

Input arguments:

duration: In milliseconds
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/key state.

Syntax:

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

xy = mouse_position('raw');

Return values:

buttons: A 1-by-2 logical vector, [left right]; 1 - clicked, 0 - not clicked
keys: States of keys registered in the main menu, a 1-by-n logical vector; 1 - pressed, 0 - not pressed

Remarks:

If any argument is provided, the function returns Windows coordinates of the mouse cursor ("raw" values). Otherwise, the return value is in degrees.

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

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

Remarks:

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

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 value provided 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 error code of the current trial to the TrialRecord structure.

Syntax:

trialerror(number1,string1,number2,string2, ...); % overwrite the default error labels

trialerror(number); % put a single number to mark the error code
trialerror(string); % use a text label, instead; case-insensitive

Example:

trialerror(1, 'Error 1', 2, 'Error 2', 3, 'Error 3'); % change the labels of error codes 1, 2 and 3

trialerror(0); % mark the current trial as Correct
trialerror('Correct'); % the same as above

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

Remarks:

The first syntax can be used to overwrite the default error labels. The input argument should be number/label pairs. This has to be done before calling the function again for marking an error code.
The numeric code 0 always indicates a correct/succeeded trial, irrespective of its label.

trialtime

This function returns the time elapsed from the trial start 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 with a matrix [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. Multiple TaskObjects can be managed for these tracking types. 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 ends 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 top-most adapter in the chain (the one provided to create_scene) stops. For the stop conditions of adapters, see the description of each adapter.

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 for each 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:

button_.threshold(button#, buttonThreshold); % change the threshold of the analog button
button_.invert(button#); % invert the polarity of the button
button_.label(button#, str); % rename the button icon on the control screen

When a button is inverted with button_.invert(), the input from the button is saved in the data file as inverted. If you want to change the polarity of a button but not the saved values, use NotAdapter (see its usage example for details).

mouse_.Cursor = true; % whether to show the mouse cursor or not; true (default) or false
mouse_.Simulation = true; % let the experimenter control the mouse
mouse_.setCursorPos([xdeg ydeg]); % move the mouse cursor to the given location

If you want to show the mouse cursor for a particular scene, there is no need to use the mouse_.Cursor property. The cursor shows up automatically on the subject screen, if the scene includes the MouseTracker (mouse_). That property is for removing the cursor completely from both screens.

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 1:

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

Example 2:

t = linspace(0, 2*pi, 1000)';
x = 6 * sin(3 * t);
y = 9 * sin(4 * t) ./ 1.5;
ct = CurveTracer(eye_);
ct.Trajectory = [x y];
fix = SingleTarget(ct); % moving target with CurveTracer
fix.Threshold = 3;
scene = create_scene(fix);
run_scene(scene);

Remarks:

SingleTarget does not change its Success state until the XY signal stays within the threshold window at least for one frame, to prevent a jitter from being detected as a fixation/touch.
SingleTarget can be a moving target, if the Target property is not assigned and CurveTracer is a child adapter as shown in Example 2 above.

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#s (at least two) 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
RT: Reaction (or response) time, which is the difference between the time of the first frame of the scene and the AcquiredTime
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:

If Target is TaskObjects, then 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
RT: Reaction (or response) time, which is the difference between the time of the first frame of the scene and the AcquiredTime

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);
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 trying again, 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)
RT: Reaction (or response) time, which is the difference between the time of the first frame of the scene and the AcquiredTime

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);
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 to see 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 maintained while allowing for temporary breaks due to blinking.

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
run_scene(scene2);
if lh.Success
dashboard(1, 'Success');
else
dashboard(1, 'Fixation break');
end
else
dashboard(1, 'No fixation');
end
idle(1000);

ComplementaryWindow

This adapter sets a complementary window around the target(s) to detect touches outside the window.

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. Either SingleTarget or MultiTarget object can be assigned instead, to copy their target and threshold (see the example below).
Threshold: size of the window; a scalar or [w h] in degrees

Example:

fix = SingleTarget(touch_);
fix.Target = [0 0];
fix.Threshold = 3;
wth = WaitThenHold(fix);
wth.WaitTime = 5000;
wth.HoldTime = 500;
out = ComplementaryWindow(touch_);
out.Target = 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 #
TouchMode: true or false (default). See the remark.

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 does not change its Success state until the button is pressed/released for at least one frame, to prevent a jitter from being detected as a normal button press/release.
For a digital button that is less susceptible to noise, TouchMode can be enabled to increase the responsiveness of the button. If TouchMode is true, the Success state changes to true without waiting until the button push lasts for one frame. This does not apply to the button release.
To make SingleButton respond to the button release, instead of the press, 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)

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 (<500Hz).
PulseCounter detects rising edges, not high levels. If the button is already being pushed at the beginning of the scene, the first pulse does not count until it is released and pushed again.

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

Output properties:

AcquiredTime: trialtime of the first signal change
RT: Reaction (or response) time, which is the difference between the time of the first frame of the scene and the AcquiredTime

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.AcquiredTime));
idle(1000);

Remarks:

If the child adapter's Success is true from the start of the scene, the OnserDetector will not indicate true. The adapter waits for a change from false to true.
Exception to the first rule. If the child adapter is one of the trackers, OnsetDetector becomes true from the beginning, since the trackers never become false.
AcquiredTime is in millisecond resolution only when the child adapter is SingleTarget, SingleButton, PulseCounter or KeyChecker. Otherwise, the precision drops to a multiple of the refresh rate.

KeyChecker

This adapter checks the state of a key. Key code(s) to monitor must be set in the [Other device settings] 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 [Other device settings] menu and type in the keycodes 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. To turn off the stimuli, call the idle command or present next scene.

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. To turn off the stimuli, call the idle command or present next scene.

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 a child adapter property 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
ChildProperty: A property of the child adapter to monitor. 'Success', by default.

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 a child adapter property.

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
ChildProperty: A property of the child adapter to monitor. 'Success', by default.

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);

PropertyMonitor

This adapter displays the value of a child adapter property on the dashboard during run_scene().

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
Color: Dashboard color
ChildProperty: A property of the child adapter to monitor. 'Success', by default.
Format: String format for dashboard (the same as formatSpec of the sprintf command). if empty, [property_name ': ' property_value] is displayed, by default.
UpdateInterval: Update intervals in frames. 30, by default.

Example:

btn = SingleButton(button_);
btn.Button = 1; % Button#1
pm = PropertyMonitor(btn); % display the state of Button#1 on the screen
pm.Dashboard = 1;
tc = TimeCounter(pm);
tc.Duration = 5000;
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]
UpdateInterval: Update intervals in frames. 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.UpdateInterval = 2; % redraw every 2 frames
tc = TimeCounter(aim);
tc.Duration = 10000;
scene = create_scene(tc);
run_scene(scene);

WebcamMonitor

This adapter displays images captured by webcams on the control screen.

Success Condition:

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

Stop Condition:

When the child adapter stops

Input properties:

CamNumber: Webcam number, 1-4
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].
UpdateInterval: Update intervals in frames. 2, by default.

Example:

cam = WebcamMonitor(null_);
cam.CamNumber = 1;
tc = TimeCounter(cam);
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] in degrees
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 ellipse ([major_axis minor_axis]).

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] in degrees
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] in degrees
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 isn't 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 property to create multiple image objects. Their Position, Scale and Angle properties can be changed afterward.

1st column: Image filename, function string (see Remarks) 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 of visual angle.

Example 1:

img = ImageGraphic(null_);
img.List = { 'A.bmp', [-3 0]; 'B.bmp', [3 0] }; % put only one image in each row
fc = FrameCounter(img);
fc.NumFrame = 60;
scene = create_scene(fc);
run_scene(scene);
idle(0); % clear the screen

Example 2:

img = ImageGraphic(null_);
img.List = { 'make_circle(100, [1 1 1], 1)', [0 0] }; % function string
tc = TimeCounter(img);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);
idle(0); % clear the screen

Remarks:

To show multiple images at the same time, put each of them in a different row of the List property.
The function string must be a char array that contains a function name and its argument(s), like 'make_circle(300,[1 1 1],1)'.
The image matrix should be double or uint8 and have values between 0 and 255. A double matrix can have values between 0 to 1, too. Using image matrices can increase the size of the data file, since they are stored in the data file.
Column 3 & 4 of List is optional. An n-by-2 matrix is all that required.
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 repeat) or 1 (repeat)
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 property to create multiple movie objects. The other properties can be changed afterward.

1st column: Movie filename, function string 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 1:

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

Example 2:

mov = MovieGraphic(null_);
mov.List = { sprintf('rand(100, 200, 3, 3 * %d)', Screen.RefreshRate), [0 0] }; % function string
tc = TimeCounter(mov);
tc.Duration = 3000;
scene = create_scene(tc);
run_scene(scene);
idle(0); % clear the screen

Example 3:

imdata = rand(100, 200, 3, 3 * Screen.RefreshRate); % Y-by-X-by-3-by-N
mov = MovieGraphic(null_);
mov.List = { imdata, [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 with idle(0).
Although a movie can be created from a matrix like Example 3, it increases the size of the data file rapidly because the matrix is saved for reconstructing initial conditions. Consider using a file or a function, like Example 1 & 2, to avoid such an issue.

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
DotShape: 'square' (by default) or 'circle'
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, dotshape1, interleaf1; ...
position2, radius2, coherence2, direction2, speed2, numdot2, dotsize2, dotcolor2, dotshape2, 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) or function string(s) (see Remarks)
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 function string is a char array that contains a function name and its argument(s), like 'make_circle(300,[1 1 1],1)'.
Column 4-5 of List are optional. An n-by-3 (or n-by-4 or n-by-5) matrix is sufficient. However, to assign something to Column 5, Column 4 must be defined.
This adapter takes one additional frame at the end of the scene to clear the screen after the last image.

GraphicProperty

This adapter changes properties of a graphic object over the course of the scene.

Success Condition:

Success: true when all the property values are used

Stop Condition:

When Success becomes true

Input properties:

Property: Name of the property to manipulate, such as 'EdgeColor', 'FaceColor', 'Size', 'Position', 'Scale' and 'Angle'. To change multiple properties, use a cell array (see Example 2).
Value: New property values; either a column vector or a matrix ordered in columns. To set multiple property values, use a 1-by-n cell array (see Example 2).
Step: Value change intervals in # of frames (1, by default)

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 should be used.

Example 1:

box = BoxGraphic(null_);
box.List = { [1 1 1], [1 1 1], [3 0.5], [0 0] };
gp = GraphicProperty(null_);
gp.setTarget(box);
gp.Property = 'size';
gp.Value = [linspace(3,6,60)' linspace(0.5,6,60)'];
scene = create_scene(gp);
run_scene(scene);

Example 2:

box = BoxGraphic(null_);
box.List = { [1 1 1], [1 1 1], [3 0.5], [0 0] };
gp = GraphicProperty(null_);
gp.setTarget(box);
gp.Property = {'size','angle','facecolor'}; % multiple properties
gp.Value = {[linspace(3,6,60)' linspace(0.5,6,60)'] linspace(0,360,60)' rand(60,3)};
scene = create_scene(gp);
run_scene(scene);

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), function string(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 1:

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);

Example 2:

snd = AudioSound(null_);
snd.List = { 'load_waveform({''sin'', 2, 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
Function strings must be char and contain all input arguments in the strings, like 'load_waveform({''sin'',1,1000})'.

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: can be one of the following.
- 1. A column vector (if only one channel was assigned to the Channel property)
- 2. A matrix (n-by-NumOfChannels) if multiple channels were assigned to the Channel property
- 3. A cell array that contains waveform data (1 or 2 above), to select a waveform on the fly
- 4. A MAT filename that contains one of the above waveform data. The waveform must be stored in a variable named 'y'. If there exists a variable, 'fs', in the MAT file, it will overwrite the Frequency property.
- 5. A char array that contains a function name and arguments (a.k.a. a funcion string), like 'load_waveform({''sin'',1,1000})'. The function must return [y, fs].
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:

It is possible to trigger more than one analogoutput channel at a time, but all must be triggered together. This is a limitation of the DAQ device. Two independent stimulations will require two DAQ boards.
Using numeric arrays/matrices for Waveform can increase the size of the data file quickly, since they are saved in the data file. Consider using a MAT file or a function string to avoid it.

TTLOutput

This adapter sends 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.

AllContinue

This adapter continues the scene while all child 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

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 succeeds.

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

Concurrent

This adapter runs multiple adapter chains simultaneously but watches only the first chain added. This adapter is useful to add extra graphics.

Success Condition:

Success: true when the first chain succeeds

Stop Condition:

When the first chain stops

Methods:

add(adapter): Add another adapter chain

Example:

fix = SingleTarget(eye_); % Child chain 1: check eye fixation on the center
fix.Target = [0 0];
fix.Threshold = 3;
grat = SineGrating(null_); % Child chain 2: display a grating and a fixation point
grat.Position = [5 5];
crc = CircleGraphic(grat);
crc.FaceColor = [1 0 0];
con = Concurrent(fix); % This scene will end when the fixation is acquired (i.e., when Child
con.add(crc); % chain 1 succeeds). Chain 2 is just for graphics.
scene = create_scene(con);
run_scene(scene);
idle(0);

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.

RewardScheduler

This adapter delivers rewards at given intervals while its child adapter's Success state is true.

Success Condition:

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

Stop Condition:

When the child adapter stops

Input properties:

Schedule: An n-by-5 matrix.

1st column: Min Success duration for the schedule in the row to be selected
2nd column: Min reward interval to next reward (in milliseconds)
3rd column: Max reward interval to next reward (in milliseconds)
4th column: Reward pulse length (in milliseconds)
5th column: Eventcode for reward (optional)

Example:

tc = TimeCounter(null_);
tc.Duration = 10000;
fix = SingleTarget(eye_);
fix.Target = [0 0];
fix.Threshold = 5;
rwd = RewardScheduler(fix);
rwd.Schedule = [0 1000 1000 100 90; % Once fixation starts, deliver a 100-ms reward every seconds
5000 500 500 200 90]; % if fix is maintained longer than 5 s, give a 200-ms reward every 500 ms
con = Concurrent(tc);
con.add(rwd);
scene = create_scene(con);
run_scene(scene);

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:

Trajectory: An n-by-2 matrix, [X1 Y1; X2 Y2; ...]
Step: Position change interval in # of frames (1, by default)

Output properties:

Position: [x y] that will be used in the upcoming frame
Time: trialtime (an n-by-1 vector) when the position was changed during the scene. NaN for unused coordinates.

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 should be used.

Example 1:

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

Example 2:

crc = CircleGraphic(null_);
crc.List = { [1 0 0], [1 0 0], 1; [0 1 0], [0 1 0], 1; }; % red & green circles
t = linspace(0, 2*pi, 1000)';
x = 6 * sin(3 * t);
y = 9 * sin(4 * t) ./ 1.5;
ct = CurveTracer(null_);
ct.setTarget(crc, 2); % use the 2nd circle in crc
ct.Trajectory = [x y];
scene = create_scene(ct);
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 can be different from the actual duration if the fixation already started before the scene or the task runs 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 one of the destinations

Stop Condition:

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

Input properties:

Destination: [x1 y1; x2 y2; ...] in degrees
Gravity: Degrees per second
GravityWindow: Radius in degrees; [width height] for a rectangular window
Color: Color of the gravity window

Output properties:

DropTime: trialtime when the stimulus is released
DroppedDestination: Index # of the dropped destination. 0, if not dropped on any destination.

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 already be touched. Confirm the finger touch first in the previous scene, as shown in the above example.

ImageStabilizer

This adapter cancels out trembles in an XY signal so that graphic stimuli can be presented in the same location relative to the current XY position.

Success Condition:

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

Stop Condition:

When the child adapter stops

Input properties:

Target: TaskObject(s) or a graphic adapter
FixPoint: [x y] in degrees
Axis: Axis to compensate movements for (0: none, 1: X axis only, 2: Y axis only, 3: both X & Y)

Example:

sample = SineGrating(null_);
sample.List = { [3 3], 3, 0, 1, 0, 0, [1 1 1], [0 0 0], 'gaussian', 1 };
is = ImageStabilizer(eye_);
is.Target = sample; % graphics to stabilize
is.FixPoint = [0 0]; % reference point of the XY signal
is.Axis = 3; % both X & Y
tc = TimeCounter(is);
tc.Duration = 1000;
scene = create_scene(tc);
run_scene(scene);

behaviorsummary

This function reads data files and shows a performance summary.

bhv2mat / bhv2bhvz

These functions convert BHV2 files to MAT or BHVZ (zipped BHV2) files, respectively. The converted 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. This command does not process webcams and high frequency channels, since loading them all at once can cause an out-of-memory error.

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 a data file and a destination folder
mlexportstim(destination_path, datafile);

mlexportwebcam

This function reads webcam videos from the data file and saves them as MP4. It is possible to strip off the videos completely from the data file by setting the delete_video option true. The original files will be kept in the "orig" folder.

Syntax:

mlexportwebcam
mlexportwebcam(datafile)
mlexportwebcam(datafile, delete_video)

mlimportwebcam

This function attaches exported webcam videos (MP4s) back to the data file. If the video files are not in the same folder as the data file, a path to the videos can be provided.

Syntax:

mlimportwebcam
mlimportwebcam(datafile)
mlimportwebcam(datafile, video_folder)

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; *.bhvz; *.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(__);

mlreadsignal

This function reads signals recorded at unconventional sample rates (i.e., not 1 kHz), such as High Frequency, Voice and Webcam. These data usually have a large size, so loading them up all at once with mlread or mlconcatenate may cause an out-of-memory error. Use this function instead.

Syntax:

signal = mlreadsignal(signal_type); % 'highfrequency1' (or 'high1'), 'voice',
% 'webcam1' (or 'cam1'), etc.
signal = mlreadsignal(signal_type, trial_number); % trial_number is 1, if not assigned
signal = mlreadsignal(signal_type, trial_number, filename);
[video, timestamp] = mlreadsignal('webcam1',__); % webcam returns timestamps as well

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 PropertyMonitor AnalogInputMonitor WebcamMonitor	BoxGraphic CircleGraphic PieGraphic PolygonGraphic TextGraphic ImageGraphic MovieGraphic SineGrating RandomDotMotion ImageChanger GraphicProperty AudioSound Stimulator TTLOutput AllContinue AnyContinue AndAdapter OrAdapter NotAdapter Concurrent Sequential RewardScheduler CurveTracer SmoothPursuit FixTimeAnalyzer DragAndDrop ImageStabilizer

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

forced_eye_drift_correction

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

PropertyMonitor

AnalogInputMonitor

WebcamMonitor

BoxGraphic

CircleGraphic

PieGraphic

PolygonGraphic

TextGraphic

ImageGraphic

MovieGraphic

SineGrating

RandomDotMotion

ImageChanger

GraphicProperty

AudioSound

Stimulator

TTLOutput

AllContinue

AnyContinue

AndAdapter

OrAdapter