Instruments on LabBench, Version 6.0

Button

Mon, 01 Jan 0001 00:00:00 +0000

Represents a button-based response device used to capture discrete participant inputs (press/release events, active states, and reaction times).

Availability:

context.Instruments.<ButtonName>

Properties

Name	Type	Description
`ReactionTime`	`float`	Reaction time associated with the most recent latched button activation (typically milliseconds).
`Activations`	`List[IButtonActivation]`	List of recorded button activation events (press/release with timestamps).

Methods

Name	Signature	Description
`Reset`	`Reset()` → `None`	Resets the button state and clears latched/active states.
`GetActive`	`GetActive()` → `str`	Returns the currently active (pressed) button as a string.
`IsActive`	`IsActive(button: str)` → `bool`	Returns `True` if the specified button is currently pressed.
`GetLatched`	`GetLatched()` → `str`	Returns the latched button (first detected press since last reset).
`IsLatched`	`IsLatched(button: str)` → `bool`	Returns `True` if the specified button is latched.

Button identifiers

Button methods that take a button: str argument expect specific string literals. These correspond to physical buttons or logical controls.

Image Display

Mon, 01 Jan 0001 00:00:00 +0000

Provides visual stimulus presentation by displaying images on a screen with optional timing and fiducial marking.

Availability:

context.Instruments.<ImageDisplayName>

Properties

Name	Type	Description
`Width`	`int`	Width of the display in pixels.
`Height`	`int`	Height of the display in pixels.

Methods

Name	Signature	Description
`Default`	`Default(image)` → `None`	Sets the default image shown when the display is cleared.
`Display`	`Display(image, fiducial=False)` → `None`	Displays an image immediately. If `fiducial=True`, marks the frame for synchronization.
`Display`	`Display(image, time, fiducial=False)` → `None`	Displays an image for a fixed duration (`time` in milliseconds). Optionally marks the frame with a fiducial.
`Clear`	`Clear()` → `None`	Clears the current image and restores the default image (if defined).

Typical usage example

display = context.Instruments.ImageDisplay

# Query display size
width = display.Width
height = display.Height

# Set default background
display.Default(background_image)

# Show stimulus
display.Display(stimulus_image, 200, fiducial=True)

# Clear display
display.Clear()

Notes / gotchas

Image format (LabBenchImage) must match the expected format of the instrument (not validated here).
time is specified in milliseconds.
Fiducial marking is typically used for synchronization with external devices.
Clear() restores the default image if one has been set; otherwise behavior depends on the device.
Display calls are immediate; timing precision depends on the underlying hardware and system.

Interval Scale

Mon, 01 Jan 0001 00:00:00 +0000

Represents a numerical rating scale with discrete, equally spaced values. Used to collect interval-based responses such as Likert or numerical rating scales.

Availability:

context.Instruments.<IntervalScaleName>

Properties

Name	Type	Description
`Maximum`	`int`	Maximum value of the scale.
`Minimum`	`int`	Minimum value of the scale.

Methods

Name	Signature	Description
`GetCurrentRating`	`GetCurrentRating()` → `int`	Returns the current rating selected on the scale.
`GetIntervalRating`	`GetIntervalRating()` → `int`	Returns the current rating value (same scale domain as `Minimum` to `Maximum`).
`SetIntervalRating`	`SetIntervalRating(rating: int)` → `None`	Sets the current rating on the scale. Updates the device state.

Typical usage example

scale = context.Instruments.IntervalScale

# Read current rating
rating = scale.GetCurrentRating()

# Set rating programmatically
scale.SetIntervalRating(5)

# Access scale bounds
min_val = scale.Minimum
max_val = scale.Maximum

Notes / gotchas

Valid rating values are within [Minimum, Maximum]; behavior outside this range is undefined.
SetIntervalRating directly modifies the device state and may affect participant interaction.
GetCurrentRating and GetIntervalRating return integer values; no fractional ratings are supported.

Joystick

Mon, 01 Jan 0001 00:00:00 +0000

Provides access to a joystick input device, allowing continuous sampling of its position along one or more axes.

Availability:

context.Instruments.<JoystickName>

Properties

No public properties.

Methods

Name	Signature	Description
`Read`	`Read()` → `JoystickPosition`	Returns the current joystick position as a `JoystickPosition` object containing axis values.

JoystickPosition

Represents the current position of the joystick.

Properties

Name	Type	Description
`X`	`float`	Position along the X-axis (horizontal).
`Y`	`float`	Position along the Y-axis (vertical).
`Z`	`float`	Position along the Z-axis (e.g., rotation or throttle, if available).

Typical usage example

joystick = context.Instruments.Joystick

pos = joystick.Read()

x = pos.X
y = pos.Y
z = pos.Z

Notes / gotchas

Axis ranges and scaling are device-dependent (no normalization guaranteed).
Z may not be meaningful on all devices.
Sampling is pull-based; call Read() each time a new value is needed.

Ordinal Scale

Mon, 01 Jan 0001 00:00:00 +0000

Represents a categorical rating scale where responses are selected from ordered categories without assuming equal spacing between them.

Availability:

context.Instruments.<OrdinalScaleName>

Properties

Name	Type	Description
`NumberOfCategories`	`int`	Total number of categories available on the scale.
`Categories`	`List[IAnchor]`	List of category definitions (labels and enabled state).

Methods

Name	Signature	Description
`GetSelectedCategory`	`GetSelectedCategory()` → `int`	Returns the currently selected category index.
`SetSelectedCategory`	`SetSelectedCategory(category: int)` → `None`	Sets the selected category by index. Updates the device state.

Category (`IAnchor`)

Represents a single category on the ordinal scale.

Pressure Algometer

Mon, 01 Jan 0001 00:00:00 +0000

The PressureAlgometer instrument represent an abstraction of computerised cuff pressure algometry devices.

context.Instruments.PressureAlgometer

String Literals

Outlet

Value	Definition
`'outlet-1'`	Pressure outlet 1
`'outlet-2'`	Pressure outlet 2

Channel

Value	Definition
`'none'`	Used for declaring no waveform channel is mapped to an outlet.
`'channel-1'`	Waveform channel 1.
`'channel-2'`	Waveform channel 2.

Criterion

Value	Definition
`'stop-on-maximal-rating'`	Stimulation will stop on a VAS of 10cm.
`'stop-when-button-pressed'`	Stimulation will stop when the button is pressed.
`'stop-when-button-released'`	Stimulation will stop when the button is released.

Properties

Name	Type	Description
`CompressorMode`	`AlgometerCompressorMode`	Compressor operation mode (`auto` or `manual`).
`MaximalPressure`	`double`	Maximum pressure the device can generate.
`Pressure`	`double[]`	Current pressure values per channel.
`UpdateRate`	`double`	Update rate for pressure generation.
`SamplePeriod`	`double`	Sampling period for pressure and ratings.
`State`	`AlgometerState`	Current device state.
`DeviceError`	`string`	Error message if the device cannot start stimulation.
`SupplyPressure`	`double`	Current supply pressure.
`FinalRating`	`double`	Final VAS rating after stimulation.
`Rating`	`double`	Current VAS rating.
`VasConnected`	`bool`	Indicates if a VAS device is connected.
`VasReady`	`bool`	Indicates if the VAS device is ready.
`PressureAvailable`	`bool`	Indicates if sufficient pressure is available.
`StopCondition`	`AlgometerStopCondition`	Stop condition that ended the stimulation.
`NumberOfPressureChannels`	`int`	Number of available pressure channels.
`Channels`	`IList<IPressureChannel>`	Available pressure channels.

Methods

Name	Signature	Description
`GetCompressorMode`	`GetCompressorMode()` → `str`	Returns compressor mode as string (`"auto"` or `"manual"`).
`GetState`	`GetState()` → `str`	Returns current state as string.
`GetStopCondition`	`GetStopCondition()` → `str`	Returns stop condition as string.
`ResetAlgometer`	`ResetAlgometer()`	Resets device configuration to default.
`ConfigurePressureOutput`	`ConfigurePressureOutput(outlet, channel)`	Maps a pressure channel to an outlet.
`StartStimulation`	`StartStimulation(criterion, forcedStart, externalTrigger=False)`	Starts pressure stimulation with specified stop criterion.
`StopStimulation`	`StopStimulation()`	Stops pressure stimulation.
`StartUpdates`	`StartUpdates()`	Starts streaming updates from the device.
`StopUpdates`	`StopUpdates()`	Stops streaming updates.
`GetUpdates`	`GetUpdates()` → `list`	Returns collected update data.
`GetTime`	`GetTime(sample)` → `float`	Returns time corresponding to a sample index.

Typical usage

alg = context.Instruments.PressureAlgometer
alg.StartStimulation("stop-on-maximal-rating", forcedStart=False)

# Read current rating
rating = alg.Rating

alg.StopStimulation()

Pressure Channel (`IPressureChannel`)

Represents a single pressure output channel capable of executing stimulus programs.

Ratio Scale

Mon, 01 Jan 0001 00:00:00 +0000

Represents a continuous rating scale (e.g., Visual Analog Scale) where responses are given as a real-valued position along a defined length.

Availability:

context.Instruments.<RatioScaleName>

Properties

Name	Type	Description
`Length`	`float`	Total length of the scale. Defines the maximal possible rating value.

Methods

Name	Signature	Description
`GetCurrentRating`	`GetCurrentRating()` → `float`	Returns the current rating value on the scale.
`GetRatioRating`	`GetRatioRating()` → `float`	Returns the current rating value (same scale domain as `0` to `Length`).
`SetRatioRating`	`SetRatioRating(rating: float)` → `None`	Sets the current rating on the scale. Updates the device state.

Typical usage example

scale = context.Instruments.RatioScale

# Read current rating
rating = scale.GetCurrentRating()

# Set rating programmatically
scale.SetRatioRating(5.0)

# Access scale length
max_val = scale.Length

Notes / gotchas

Valid rating values are typically within [0, Length]; behavior outside this range is undefined.
Ratings are continuous (floating-point), unlike interval or ordinal scales.
SetRatioRating directly modifies the device state and may affect participant interaction.
GetCurrentRating and GetRatioRating return equivalent values.

Scales

Mon, 01 Jan 0001 00:00:00 +0000

Represents a composite rating device that provides access to multiple rating scales simultaneously.

Availability:

context.Instruments.<ScalesName>

Properties

Name	Type	Description
`Scales`	`List[IRatingScale]`	Collection of rating scale instances available on the device. Each element implements a specific scale type (e.g., ratio, interval, ordinal).

Methods

Name	Signature	Description
`InitializeRating`	`InitializeRating()` → `None`	Initializes or resets all contained rating scales. Typically prepares the device for a new rating session.

Typical usage example

scales = context.Instruments.Scales

# Initialize all scales
scales.InitializeRating()

# Access individual scales
for scale in scales.Scales:
    # Use scale depending on its type
    pass

Notes / gotchas

The specific type of each scale in Scales depends on the experimental setup.
Access to scale-specific methods requires knowledge of the concrete scale type.
InitializeRating() should typically be called before collecting responses.

Sound Player

Mon, 01 Jan 0001 00:00:00 +0000

Provides audio stimulus playback by sending waveform data to an output device.

Availability:

context.Instruments.<SoundPlayerName>

Properties

No public properties.

Methods

Name	Signature	Description
`Play`	`Play(waveform: bytes)` → `None`	Plays a waveform provided as raw byte data.
`Play`	`Play(waveform: Waveform)` → `None`	Plays a single waveform object on the default output channel.
`Play`	`Play(waveforms: List[Waveform])` → `None`	Plays multiple waveforms simultaneously, where each waveform is mapped to a separate output channel (first → channel 1, second → channel 2, etc.).
`Playsc`	`Playsc(waveform: Waveform)` → `None`	Plays a waveform scaled to full output amplitude on the default channel.
`Playsc`	`Playsc(waveforms: List[Waveform])` → `None`	Plays multiple waveforms scaled to full output amplitude, each assigned to separate output channels.

Typical usage example

player = context.Instruments.SoundPlayer

# Play a single waveform on all output channels.
player.Play(waveform)

# Play on multiple channels
player.Play([waveform_left, waveform_right])

# Play scaled waveform on all output channels.
player.Playsc(waveform)

Notes / gotchas

When passing a list, each waveform is assigned to a separate channel in order.
Playsc scales waveforms to full output amplitude before playback.
Waveform format must match the expectations of the underlying device.
Playback is triggered immediately when calling the method.
Channel count is determined by the number of waveforms provided.

Stimulator

Mon, 01 Jan 0001 00:00:00 +0000

Provides generation of physical stimuli (e.g., electrical, thermal, mechanical) based on defined stimulus waveforms, with configurable triggering and output control.

Availability:

context.Instruments.<StimulatorName>

Properties

Name	Type	Description
`Modality`	`Modality`	Type of stimulus modality (e.g., electrical, pressure).
`Unit`	`Unit`	Unit of the stimulus intensity (e.g., mA, °C).
`Imax`	`float`	Maximum allowed stimulus intensity.
`Max`	`float`	Alias for maximum intensity.
`Imin`	`float`	Minimum allowed stimulus intensity.
`Min`	`float`	Alias for minimum intensity.
`Ineutral`	`float`	Neutral (baseline) intensity level.
`Neutral`	`float`	Alias for neutral intensity.
`Range`	`float`	Range of valid stimulus intensities (`Max - Min`).

Methods

Name	Signature	Description
`GetModality`	`GetModality()` → `str`	Returns the modality as a string.
`Initialize`	`Initialize(setup: IStimulatorSetup)` → `None`	Initializes the stimulator with a specific setup configuration.
`Generate`	`Generate(stimulus: IStimulus)` → `None`	Generates a stimulus using the device’s default trigger and update rate.
`Generate`	`Generate(startTrigger: str, stimulus: IStimulus)` → `None`	Generates a stimulus when triggered by the specified trigger source.
`Generate`	`Generate(startTrigger: str, restart: bool, stimulus: IStimulus)` → `None`	Generates a stimulus with explicit control over trigger source and restart behavior.
`SetDefaultOutput`	`SetDefaultOutput(value: float)` → `None`	Sets the default output level when no stimulus is active.

Trigger source (`startTrigger`)

The startTrigger argument specifies how stimulus generation is triggered.

Trigger Detector

Mon, 01 Jan 0001 00:00:00 +0000

Detects incoming trigger events and provides information about trigger state, timing, and count.

Availability:

context.Instruments.<TriggerDetectorName>

Properties

Name	Type	Description
`IsTriggered`	`bool`	Indicates whether a trigger event has been detected.
`Latency`	`float`	Latency associated with the detected trigger (unit depends on device, typically milliseconds).
`Count`	`int`	Number of detected trigger events since last reset.

Methods

Name	Signature	Description
`Reset`	`Reset()` → `None`	Resets the trigger detector state, clearing trigger flags and counters.

Typical usage example

detector = context.Instruments.TriggerDetector

# Check trigger state
if detector.IsTriggered:
    print("Trigger detected with latency:", detector.Latency)

# Read number of triggers
count = detector.Count

# Reset between trials
detector.Reset()

Notes / gotchas

Reset() should typically be called between trials to clear previous trigger events.
Latency is only meaningful when a trigger has been detected.
Trigger detection depends on correct hardware configuration and signal routing.

Trigger Generator

Mon, 01 Jan 0001 00:00:00 +0000

Generates trigger sequences for synchronization, event marking, or control of external devices.

Availability:

context.Instruments.<TriggerGeneratorName>

Properties

No public readable properties are defined.

Methods

Name	Signature	Description
`GenerateTriggerSequence`	`GenerateTriggerSequence(startTrigger: str, triggers: List[ITrigger]) -> None`	Generates a trigger sequence when the specified trigger source occurs.
`GenerateTriggerSequence`	`GenerateTriggerSequence(startTrigger: str, restart: bool, triggers: List[ITrigger]) -> None`	Same as above, with control over whether an ongoing sequence should be restarted.

Parameters

startTrigger (str) Defines when the trigger sequence should start. Supported values:

Instruments on LabBench, Version 6.0

Button

Properties

Methods

Button identifiers

Image Display

Properties

Methods

Typical usage example

Notes / gotchas

Interval Scale

Properties

Methods

Typical usage example

Notes / gotchas

Joystick

Properties

Methods

JoystickPosition

Properties

Typical usage example

Notes / gotchas

Ordinal Scale

Properties

Methods

Category (IAnchor)

Pressure Algometer

String Literals

Outlet

Channel

Criterion

Properties

Methods

Typical usage

Pressure Channel (IPressureChannel)

Ratio Scale

Properties

Methods

Typical usage example

Notes / gotchas

Scales

Properties

Methods

Typical usage example

Notes / gotchas

Sound Player

Properties

Methods

Typical usage example

Notes / gotchas

Stimulator

Properties

Methods

Trigger source (startTrigger)

Trigger Detector

Properties

Methods

Typical usage example

Notes / gotchas

Trigger Generator

Properties

Methods

Parameters

Category (`IAnchor`)

Pressure Channel (`IPressureChannel`)

Trigger source (`startTrigger`)