Timing script functions

Runtime functions

Version 1 specific

Version 2 specific

Adapters for Version 2

Command window functions

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');
    • 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 invoke 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 elements or fewer.
    • 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.
    • For editable variables, trial-by-trial change histories are recorded in the data file. Check the VariableChanges field.

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 = mouse_position('raw');
    • xy_deg = mouse_position;
    • [xy_deg, buttons, keys] = mouse_position;

    Return values:

    • buttons: A 1-by-2 logical vector, [left right]; 1 - clicked, 0 - not clicked
    • keys: States of registered keys, 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 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 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.
      • 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 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:

      The thresholds of buttons can be adjusted.

        button_.threshold(button#, buttonThreshold);

      Also, the polarity of buttons can be inverted. This will make SingleButton respond to button release rather than 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:

    • 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);   % 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 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);   % 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 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   % 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 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 #

    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 for at least 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, 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 high levels. 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 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 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 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:

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.

    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 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 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; ...
        [], [], 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 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'
    • Value: A column vector of new property values
    • 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 = {'angle','scale'};  % multiple properties
    • gp.Value = [linspace(0,360,180)' repmat([linspace(1,3,30)'; linspace(3,1,30)'],3,1)];
    • scene = create_scene(gp);
    • run_scene(scene);

    Remarks:

    • For those properties with a scalar value, multiple properties can be manipulated together with one GraphicProperty adapter, like Example 2 above.

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:

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

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, it is possible to prevent some of them from terminating the scene by setting the Success state of those chains 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 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 (*.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. 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 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). 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 (AVIs or 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; *.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

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.