Timing script functions

Runtime functions

Version 1 specific

Version 2 specific

Adapters for Version 2

Command window functions

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);
    • dashboard(line_number, text, color, property1, value1, property2, value2, ...);
    • dashboard(line_number, text, property1, value1, property2, value2, ...);

    Input arguments:

    • line_number: Currently you can display 10 lines of strings.

    Example:

    • dashboard(1, 'DMS Task');
    • dashboard(2, sprintf('Choice: %d', choice), [1 1 1], 'bgcolor', [0 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 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. For the purpose of marking onset times of stimuli or rewards, you should 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 value is 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 that the origin argument is not provided or empty, this function determines the new origin like the following.

        • - [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 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.
        • toggleobject(1, 'status', 'on');
        toggleobject(1, 'status', 'off');
        toggleobject(2, 'status', 'on');   % The last two commands can be combined as below

        toggleobject(1, 'status', 'on');
        toggleobject([1 2]);               % 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 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 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:

    • 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
    • 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);   % 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)
    • 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);   % 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 does not change its Success state until the button is pressed at least for one frame, 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 use NotAdapter or 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 HI. If the button has been pushed before the beginning of the scene, it has to be released first to be counted as the first pulse.

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 beginning, that does not count as the onset. What this adapter detects is a change from false to true.
    • 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 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:

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]
    • 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 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] 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 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', [-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

    Remarks:

    • To show multiple images at the same time, put each of them in a different row ot the List property.
    • 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 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 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 1:

    • 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

    Example 2:

    • 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 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; ...
        [], [], 15, []; ...   % 15 frames' blank
        {'B.bmp','D.bmp'}, [5 5; -5 -5], 15, 102; ...
        [], [], 15, []; ...
        {'C.bmp','A.bmp'}, [5 5; -5 -5], 15, 103; ...
        [], [], 15, []; ...
        {'D.bmp','B.bmp'}, [5 5; -5 -5], 15, 104; ...
        [], [], 15, []; };   % The images in each row will be shown for 15 frames in turn.
    • 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:

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:

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

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 (*.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 destination folder
    • mlexportstim(destination_path, datafile);

mlexportwebcam

    This function reads webcam videos from the data file and saves them as AVI (R2011b or earlier) or MP4 (R2012a or later). You can also 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 (AVIs or MP4s) back to the data file. If the video files are not in the same folder as the data file, you can provide the path to the videos.

    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; *.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. It works, whether the videos are stored in the data file or exported as separate files.

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

The National Institute of Mental Health (NIMH) is part of the National Institutes of Health (NIH), a component of the U.S. Department of Health and Human Services.