Commands

Commands provide extended functionality beyond Regions and Patterns.

Often, you will want to do more than present a fixed set of regions and patterns during a stimulus animation. For this purpose, LabMaestro projects can also include commands that allow you to play sound, show or hide regions at a specific point of epochs, or wait for one particular input. The various LabMaestro commands are documented in the following sections.

Show/Hide Region Commands

Within an experimental trial, you may want to place a region on the testing display for a specific interval and then remove it, perhaps replacing it with another region.

Hide Region

Hide a named region and its patterns.

Properties

Use the Region property to specify which region should be hidden.

Show Region

Show a previously hidden region and its patterns.

Properties

Use the Region property to specify which region should be revealed.

Flow Commands

Wait

Blocking command that pauses the timeline before proceeding to the following command. Often used after one or more Regions, as the last command in Epochs, to specify how long these will be displayed on the screen.

Properties

Enforce Frame Swap: This option forces a frame swap right before we start waiting. This way, the timer begins precisely at the point in the wait command's timeline.

Wait Duration: Specifies the duration of the pause in seconds.

Random Additional Delay: Maximum additional pause to Wait Duration. It applies random delay sampled from a uniform distribution; no delays are used by default.

Go To

The Go To command allows you to jump from one point in a timeline to another point in the timeline.

Properties

Use the Pointer property to specify the target point in the timeline.

Reset Timer

Resets the Time variable to 0.

By default, the time saved by Log is the time since the beginning of a timeline. However, there may be cases where you want to measure the time relative to some other reference point within the trial. In such situations, you can include the "Reset Timer" command in the timeline when you want to set time zero for your data.

Properties

The Reset Timer command has no properties.

Abort

The Abort command is used to exit the experiment now. It will skip any remaining trials or timelines.

Properties

Condition: This is the condition that is checked to know if the experiment should be aborted.

Set Variables

Used to change the value of a variable during an experiment. Sometimes, it can change a region or pattern characteristic during a timeline.

Properties

Variables: Specify variables to redefine, as well as their new values.

Schedule Commands

The schedule commands allow you to start recording data, as you would in other software. While the digital schedule records any transition in the VPixx device’s digital inputs, the analog recording has some settings related to the way the data will be recorded. The stop command is required to be called to save the data recorded.

Start Analog Recording

Start recording analog inputs (ADC) on the specified channel and at the specified rate. You can also specify a duration to record for only a specific amount of time.

Properties

Device: The VPixx device from which we are recording the analog inputs.

Frequency: How often the schedule records data, in Hz. This value is between 0 and 200 000 Hz.

Delay: How long (in seconds) before the schedule starts recording. The maximum value for this is 4.29 seconds.

Duration: How long (in seconds) to record data for.

Channels: The channels from which to record data. Channels correspond to the respective ADC on the device. For example, Channel00 is ADC0.

Stop Analog Recording

Stops recording analog inputs (ADC) on a specific device and saves them to a file.

Properties

Device: The VPixx device from which we are recording the digital inputs.

File Name: The name of the file in which we save the analog recorded data.

Start Digital Recording

Starts recording digital inputs (DIN) on a specific device. You can

Properties

Device: The VPixx device from which we are recording the digital inputs.

Stop Digital Recording

Stops recording digital inputs (DIN) on a specific device and saves them to a file

Properties

Device: The VPixx device from which we are recording the digital inputs.

File Name: The name of the file in which we save the digital input recorded data.

Input Commands

There are two ways to monitor inputs: one blocking call (WaitForInput) and one that registers the events (ListenForInputs).

These commands support:

• Keyboard via Key Down and Key Up. Key Down corresponds to when a key is pressed down, and Key Up to when a key is released.

• Digital Inputs monitored on a VPixx device. These can be accessed in multiple ways: Digital Input Value, Digital In Bits, RESPONSEPixx Down, RESPONSEPixx Up, RESPONSEPixx MRI Down, and RESPONSEPixx MRI Up.

In the case of Digital In Values, the values of the first 16 digital inputs must match the event provided.

In the case of Digital In Bits, you select all the bits that must be triggered simultaneously. For this condition to pass, all the selected bits must have transitioned.

For RESPONSEPixx Down or RESPONSEPixx MRI Down, any of the selected buttons must be pressed. If the selected event has two buttons, pressing either will cause the condition to pass.

In the case of RESPONSEPixx Up or RESPONSEPixx MRI Up, any of the selected buttons must be released. For instance, if the event you choose has two buttons, releasing any will cause the condition to pass.

Listen for Inputs

Non-blocking command that instructs LabMaestro to monitor inputs during the experiment. Supports keyboard inputs, as well as the following standard RESPONSEPixx and their buttons:

Microsecond-precision response boxes

A response box must be connected to a supported video I/O hub.

RESPONSEPixx: Reliable, ergonomic response boxes for use in behavioral research laboratories. Standard models support input from 4 or 5 buttons.

RESPONSEPixx MRI: Fiber-optic versions of our RESPONSEPixx button boxes for MRI, MEGs, OPMs, etc. Standard models support 4 or 10 buttons.

Properties

Log Event: Toggle to record the properties of the input in the data file. The log includes the key pressed, the time of the key press, and the time of the key release.

Save to Variable: Save the input properties to a variable defined earlier in the experiment.

Inputs: Define which keys the command should listen for. An input for a key not defined in this property will be ignored. If no keys are defined, all inputs are recorded.

Wait for Inputs

Blocking command that instructs LabMaestro to monitor inputs during the experiment. It supports the same as ListenForInputs but blocks until input is found or the time-out property is reached.

Properties

Enforce Frame Swap: This option forces a frame swap right before we start waiting. This way, the timer begins precisely at the point in the wait command's timeline.

Redefines Expected Inputs: Toggle to redefine which inputs should be monitored. This property is relevant if multiple commands listen for inputs throughout an epoch. If it is turned off, the previous inputs are used.

Inputs: Define which keys the command should listen for. An input for a key not in this property will be ignored. If no keys are defined, all inputs are recorded.

Last Event: This read-only field tells you which information can be accessed by a future expression from this WaitForInputs command.

Audio Commands

Play Sound

Play a pre-recorded sound in your experiment. Cognitive experiments often require the presentation of auditory stimuli, such as recorded speech. Sounds can be played on any output device, including VPixx devices.

Properties

Device: Specify playback device.

Sound Type: Specify the type of sound played.

• If Media: Use the Resource property to specify which audio file to play. Audio files must be imported into the Project tab under Resources.

• If Tone: Use the Tone property to specify the parameters of the audio playback. You may define Amplitude, DC Offset, Symmetry, Frequency, and Shape.

Volume: Adjust the audio playback volume on a scale of 0 to 100.

Duration: Specify the length of the audio playback in seconds. If set to 0, the sound will repeat until a Pause Sound command is triggered. If it is shorter than the length of the sound file, it will cease once the time has elapsed.

Pause Sound

Optionally used after a Play Sound command to pause the audio.

Properties

All: Toggle to pause all sounds.

Sound: If All is off, specify which sound should be paused.

Resume Sound

Optionally, this command can resume playing the audio after a Pause Sound command.

Properties

All: Toggle to resume all sounds.

Sound: If All is off, specify which sound should be resumed.

Eye Tracker Commands

Calibrate Tracker

Calibration routine for the eye tracker (TRACKPixx3 and TRACKPixx /mini). Multiple calibration properties can be customized using this command. The Calibrate Tracker command displays visual targets at predetermined screen coordinates and samples eye tracker data accordingly. Eye-tracking calibration is essential for collecting and reporting data in calibrated screen pixel space.

Properties

Mode: The calibration procedure used to display calibration targets and collect gaze samples

• Automatic: During an automatic calibration, a calibration target is presented for the duration specified by Target Stabilization Time, after which gaze samples are automatically collected.

• Triggered: Tracker sampling begins only when the participant explicitly confirms that they are fixating on the target by pressing the Trigger Key.

• Manual: This advanced mode requires two displays and active experimenter control. It allows users to accept, reject, and retry different points while accessing calibration results.

Target Count: Indicates the number of calibration targets used in the calibration process.
The calibration allows up to 25 target locations to calibrate the eye tracker, and calibrations can be run using various subsets of these 25 calibration targets. The standard calibration grid for a 16:9 aspect ratio display is a 13-point calibration.

A subset of size n contains the first n calibration targets defined in :

Acceptable Offset (DVA): Indicates the threshold for calibration target offset in degrees of visual angle (DVA). This value should be modified based on your requirements.

Vertical Coverage: Specifies the proportion of the screen height to be calibrated as a ratio of the total screen height. The default setting is 80 percent.

Horizontal Coverage: Specifies the proportion of the screen width to be calibrated as a ratio of the total screen width. The default setting is 80 percent.

Background Color: Specifies the calibration screen background color.

Foreground Color A: Specifies the first color of the calibration target. Color A is the color of the outer ring.

Foreground Color B: Specifies the second color of the calibration target. Color B is the color of the inner ring.

Target Stabilization Time: Specify the number of milliseconds before collecting each target’s gaze samples. If the target properties include size or color changes, the targets will be animated during this time.

Target Min Size: Indicates the minimum radius of each calibration target in pixels.

Target Max Size: Indicates the maximum radius of each calibration target in pixels.

Custom Target: Selects an image or video media from your project’s Resources to use as a calibration target. This property is optional.

Media Scaling: Magnification factor used to resize the media used as a custom target.

Trigger Key: When calibration mode is set to “triggered”, this specifies the keyboard input key, which initiates gaze sampling for the current calibration target.

Failure Prompt: When this is turned on, a prompt with information will appear if a calibration fails to complete.

Precalibration Countdown: This displays a specified value countdown before the calibration procedure begins. No countdown will be shown if the pre-calibration countdown is set to 0.

State: A read-only property describing the state of the calibration:

• Pending: The Calibrate Tracker component has not been reached yet.

• Ongoing: The calibration procedure defined by the Calibrate Tracker component is currently being executed.

• Succeeded: The previous calibration procedure attempt, defined by the Calibrate Tracker component, was completed successfully.

• Failed. The previous calibration procedure attempt, defined by the Calibrate Tracker, either failed or was aborted.

Calibrated: Read-only property reporting whether the calibration sequence was completed successfully.

Average Offset: The average offset between the gaze location and the target dot, calculated on the eyes identified in Eye Selection on the Setup TRACKPixx3 screen.

Validate Tracker Calibration

The validation routine for VPixx eye trackers can only be used after calibrating the tracker. Since it presents the same targets, it has the same properties as the calibration.

Start Tracker Recording

Initiates a TRACKPixx recording schedule. With a TRACKPixx3, this initiates a 2Khz binocular TRACKPixx3 recording schedule with the DATAPixx3’s microsecond precision clock and integrated video I/O subsystem. With a TRACKPixx/mini, this initiates a 120 Hz binocular recording.

Stop Tracker Recording

Always used after a Start Recording Tracker command to stop the recording schedule. This command saves the schedule in the Recordings section of the Project Panel. Recordings can be examined using LabMaestro’s Recordings and Built-In Data Visualization.

Properties

File Name: Name of the output file for fixation data.

Output Commands

There are multiple ways to send signals out of the VPixx devices. If you are used to Pixel Mode, this command is also available directly in LabMaestro. If you are used to sending triggers using digital output schedules, this is possible using the DATAPixx trigger output.

Pixel Mode

The pixel mode command allows you to send a specific trigger using only the top left pixel’s color value. This command automatically enables the right mode on the selected device to send the trigger for the requested duration.

Properties

Device: The device that will send the digital output trigger.

Pixel Mode: The chosen mode, which can be RGB (controls all 24 digital outputs), GB (controls the lower 16 digital outputs), B (DATAPixx3 Only, controls the lowest 8 digital outputs)

Value Mode: The mode to use to provide the trigger value. It can be an expression and thus depend on some other variable, a single value or multiple values (an RGB triplet).

If you pick a single value, you can define the value directly using the graphical tool that represents the digital output on your device.

Duration Mode: Specifies how long you want the trigger to last. This duration can be defined in video frames or seconds, or the trigger can continue until there is another pixel mode trigger or the experiment is completed.

Frames/Seconds: Time for the trigger in the respective unit.

DATAPixx trigger output

Configure the characteristics of a digital trigger signal generated from a VPixx video I/O hub. Once the instructions are received, the device sends the digital trigger command via USB and executes it.

Properties

Mode: Selects which types of trigger to send:

• “PositivePulse”: A single square wave pulse voltage change from 0V to 5V, returning to 0V.

• “NegativePulse”: A single square wave pulse voltage change from 5V to 0V, returning to 5V.

Digital Output: The digital output value you want to trigger. Please note that this is not the pin number; the mapping of a pin to the digital output can be found in the user manual.

Duration: Defines the duration of each pulse in milliseconds. In other words, how long does it stay at 0V or 5V before returning to its initial state?

Duty Cycle: Ratio of which the signal stays in the positive or negative state.

Repetitions: Specifies how many times the trigger pulse should be repeated, typically a single repetition.

System Commands

Capture Screen

This command captures an image of what is displayed on your screen at a particular moment and saves it as a picture file. The captured screen is saved as a JPG in the Recordings section of the Project Panel. The capture screen command helps generate images for publications and presentations.

Properties

File Name: The name of the output JPG file.

Log

This command allows you to record a text string or a number in the logs file. This can be used to put information that you want from variables or to help you during your post-experiment analysis.

Properties

Log Type: Number or text, depending on what you wish to store.

Value: The value to be logged.

System Command

This command runs a system command (e.g., a terminal command). It can be useful if a specific calculation, evaluation, or feature is not directly implemented in LabMaestro but can otherwise be done on your system. You can save the command's return value output directly to a variable for later use.

Properties

Command: The string of the command you want to run.

Blocking: Flag, which determines if the timeline should wait or not on the command to finish execution before continuing to the next instruction.

Save To Variable: The name of the variable to which the output of the command should be saved.