Language Specification

Definition of the LabBench Language

Experiment

Defines an entire experiment and contains the following elements:

<participant-validator>: defines the rule for valid participant/session IDs.
<experimental-setup> or <experimental-setup-variants>: defines the research equipment used in the protocol and assigns them to procedures in the protocol.
<protocol>: defines the protocol for the experiment. This protocol consists of a procedure (procedures).
<post-actions>: defines actions that should be executed when a session is completed.

Elements

Name	Use	Description
`<participant-validator>`	optional	A participant validator can guard against invalid participant/session IDs. Participant/session IDs are validated with regular expressions. This tutorial RegexLearn teaches how to write regular expressions. When writing regular expressions, it is beneficial to procedure them with a suitable tool regex101.
`<experimental-setup>`	optional	Defines the experimental setup for the experiment, which consists of defining and configuring the required research devices and assigning these to procedures in the protocol.
`<experimental-setup-variants>`	optional	Defines possible experimental setups for the protocol.
`<protocol>`	required	This element defines the protocol for the experiment. The main part of the protocol definition is the definition of the procedures (experimental procedures) performed in the experimental sessions. The procedure definitions must be performed for all protocols and are supported by optional elements. This protocol contains the following elements: `<languages>`: this optional element defines the languages/cultures for which the protocol is localized. If present, the startup wizard will display a page where the operator can select the language to use in the current experimental session. `<sessions>`: this optional element defines the sessions of the experiment. If present, the startup wizard will display a page where the operator can select the current session, and each procedure in the `<procedures>` element must define which session it belongs to. When the session is performed, the LabBench Runner will only display procedures for the current session. `<properties>`: this optional element defines properties of the protocol that modifies the execution of the procedures. `<randomisations>`: this optional element defines variables generated once a participant is created and exported with the recorded data. The primary use of these variables is randomization. However, they can be used for any variable that should be persisted in the data set. `<defines>`: this optional element defines variables that can have any type. Consequently, they can be used for complex variables not saved in the data set, such as Python classes created in backing scripts. They are created every time a session is started. `<templates>`: this optional element defines template variables and procedure templates that can be used to construct procedures at runtime in the `<procedures>` element. `<procedures>`: this mandatory element defines the procedures of the protocol. These can be directly defined in this element or constructed from procedure templates defined in the `<templates>` element. `<assets>`: this optional element defines external files that the procedures in the protocol can use. The order of these elements is significant and must be defined in the order given above.
`<post-actions>`	optional	The `<post-actions>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<export-to-csv>` `<export-data>` `<export-script>` `<export-log>` `<copy>`

TextValidator

A text validator can guard against invalid text input. Text is validated with regular expressions. This tutorial, RegexLearn, teaches how to write regular expressions. When writing regular expressions, it is beneficial to procedure them with a suitable tool regex101.

Attributes

Name	Use	Description
regex	required	The regular expression that are used to validate the text [ string ].
advice	required	An advice on how to write a correct text input [ string ].

ExperimentalSetup

The devices element lists the devices required for the experiment and specifies their configuration, whereas the device-mapping assigns these devices to the instruments required for each procedure.

All devices that a protocol requires are listed in the devices element as nested elements. These elements assign an ID that is used to identify the device when mapped to the Instruments required by procedures in the device-mapping element, and they also configure the devices for the experiment.

The devices elements specify and configure the research devices used in the experiment, but it does not configure which devices are used in the procedures in the protocol. Each procedure will require a set of Instruments to perform the experimental procedures. Each device that is assigned to an Instrument Name, required by a procedure, must implement the required Instrument for that name. Assigning a device that does not implement the required Instrument will result in an error that will prevent the experiment from being run by the LabBench interpreter.

Each mapping of a device to an Instrument is done with a device-assignment element, where the device-id is the id of the device from the devices element, instrument-name is the name of the Instrument from procedure, and procedure-type is the type of procedure that requires the Instrument.

Attributes

Name	Use	Description
id	optional	Identifier of the experimental setup [ string ].
name	optional	Name of the experimental setup that will be used to identify it in LabBench [ string ].

Elements

Name Use Description

Name	Use	Description
`<devices>`	optional	The `<devices>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<lio>` `<cpar>` `<cpar-plus>` `<sound>` `<joystick>` `<tcs>` `<display>` `<evas>`
`<device-mapping>`	optional	The `<device-mapping>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<device-assignment>`

<devices>

optional

The <devices> is an array element that can contain a sequence of elements. These elements can be of the following types:

<lio>
<cpar>
<cpar-plus>
<sound>
<joystick>
<tcs>
<display>
<evas>

<device-mapping>

optional

The <device-mapping> is an array element that can contain a sequence of elements. These elements can be of the following types:

<device-assignment>

LIOSetup

LabBench I/O

The LabBench I/O device serves as a central hub for experiments requiring precise coordination of stimulation, participant responses, and external equipment. It supports flexible experimental designs by integrating digital and analogue signaling for stimulus generation and response collection.

Common experimental applications include:

Precise Event Synchronization and Triggering: The device generates and routes digital triggers to synchronise experimental events with external systems such as EEG, EMG, motion capture, eye tracking, or imaging equipment. Trigger logic and voltage levels are adjustable to meet the requirements of various hardware platforms.
Electrical and Sensory Stimulation Control: Computer-controlled interfaces with external stimulators allow precise timing of electrical or sensory stimuli in psychophysical, nociceptive, or neurophysiological paradigms.
Reaction Time and Behavioral Response Tasks: The device collects button presses and response pad inputs for tasks, measuring reaction times and behavioural responses.
Psychophysical ratings: The device supports psychophysical rating scales for real-time reporting of subjective experiences, such as pain intensity, discomfort, or perceptual magnitude, during stimulation or after discrete events.
Externally Triggered and Closed-Loop Paradigms: The device detects auditory or visual events to trigger experimental actions, enabling closed-loop designs in which stimulation or task flow depends on the detected signals or participant behaviour.

Overall, the LabBench I/O device supports complex, multimodal experimental protocols that require precise timing and flexible configuration of stimulation, responses, and external recordings. It is well-suited for advanced psychophysics, systems neuroscience, and human neurophysiology studies.

Attributes

Name	Use	Description
default-analogue-output	optional	Voltage output on the STIMULATOR A when the device is idle [ double ]. This voltage must be between -10V and 10V.
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

Elements

Name Use Description

Name	Use	Description
`<trigger-setup>`	optional	Defines how digital trigger signals generated on the INTERFACE port are electrically and logically configured, specifying whether triggers use positive or negative logic and which voltage levels are driven on the high and low bytes, allowing the LabBench I/O device to be matched to the electrical requirements of connected external equipment.
`<stimulators>`	optional	Defines the external electrical stimulator controlled via the LabBench I/O device, specifying which stimulator hardware is connected and its initial current–voltage conversion setting, enabling LabBench to generate precisely timed and parameterized electrical stimulation as part of the experimental protocol.
`<response-devices>`	optional	Defines the set of participant response and event-detection devices connected to the LabBench I/O device, including trigger detectors, buttons, response pads, and rating scales. Up to two devices can be defined, corresponding to the two available response ports on the device. Devices are assigned to response ports in the order they are defined within this element: the first device is connected to response port 1 and the second to response port 2. As a consequence, it is possible to occupy only response port 1 without using response port 2, but not the other way around.

<trigger-setup>

optional

Defines how digital trigger signals generated on the INTERFACE port are electrically and logically configured, specifying whether triggers use positive or negative logic and which voltage levels are driven on the high and low bytes, allowing the LabBench I/O device to be matched to the electrical requirements of connected external equipment.

<stimulators>

optional

Defines the external electrical stimulator controlled via the LabBench I/O device, specifying which stimulator hardware is connected and its initial current–voltage conversion setting, enabling LabBench to generate precisely timed and parameterized electrical stimulation as part of the experimental protocol.

<response-devices>

optional

Defines the set of participant response and event-detection devices connected to the LabBench I/O device, including trigger detectors, buttons, response pads, and rating scales.

Up to two devices can be defined, corresponding to the two available response ports on the device.

Devices are assigned to response ports in the order they are defined within this element: the first device is connected to response port 1 and the second to response port 2. As a consequence, it is possible to occupy only response port 1 without using response port 2, but not the other way around.

LIOTriggerSetup

Attributes

Name	Use	Description
logic-system	required	Specifies the logic convention used when generating digital triggers with the INTERFACE port. In positive logic, a high voltage represents the active or true state, whereas in negative logic, a low voltage represents the active or true state and the interpretation of high and low is inverted.
low-byte-voltage-level	required	Voltage level for the low-order byte.
high-byte-voltage-level	required	Voltage level for the high-order byte.

LIOGeneratorSetup

Elements

Name	Use	Description
`<ds5>` `<noxistim>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

DS5

The Digitimer DS5 is a constant-current electrical stimulator widely used in neuroscience and psychophysics research to deliver precisely controlled electrical pulses to peripheral nerves or tissues, supporting reproducible stimulation across a wide range of experimental protocols.

Attributes

Name	Use	Description
name	optional	Name of the equipment that will be used to identify it to the operator in the LabBench Runner.
transconductance	optional	Initial transconductance of the stimulator. This can be changed during runtime in LabBech Runner.

NoxiSTIM

The NoxiSTIM is an isolated, current-controlled electrical stimulator developed for research use.

Attributes

Name	Use	Description
name	optional	Name of the equipment that will be used to identify it to the operator in the LabBench Runner.
transconductance	optional	Initial transconductance of the stimulator. This can be changed during runtime in LabBech Runner.

LIOResponseDeviceSetup

Defines the set of participant response and event-detection devices connected to the LabBench I/O device, including trigger detectors, buttons, response pads, and rating scales.

Up to two devices can be defined, corresponding to the two available response ports on the device.

Elements

Name	Use	Description
`<button>` `<visual-analogue-scale>` `<audio-trigger>` `<visual-trigger>` `<response-pad>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ButtonSetup

The LabBench BUTTON is a simple single-button response device used to collect discrete participant responses such as responses in yes/no response task. (e.g., for threshold estimation in perception threshold tracking).

Attributes

Name Use Description

required

Identification of the response device [ string ]. This id must be unique.

timing-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<map>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ButtonMap

A button configuration for the device. Each button configuration is activated based on the experimental-setup-id of the currently selected procedure in the protocol.

Attributes

Name	Use	Description
experimental-setup-id	optional	The experimental-setup-id that will activate the button configuration [ string ]. If this attribute is omitted, the button configuration will default to the device’s configuration, which will be activated if no configuration is found for the currently active experimental-setup-id.

Elements

Name	Use	Description
`<button-assignment>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ButtonAssignment

Assign a button function to a physical button on the device. Procedures and devices that use this device as their controller-device will need a specific set of button functions to operate.

Attributes

Name	Use	Description
code	required	The code that identifies the physical button on the device [ int ].
button	required	The button function to assign to the physical button on the device.
label	required	A descriptive label that will be used in LabBench Designer to explain the function of the button [ string ].

VisualAnalogScaleSetup

A visual analogue scale (VAS) represents a ratio scale along which observers report the perceived magnitude of a subjective sensation. A ratio scale means that responses are defined on a continuum, with a true zero corresponding to the absence of the perceptual quantity, and equal distances along the scale correspond to equal increments in perceived magnitude. As a consequence, ratios between values are interpretable (e.g., a response at 60 can be meaningfully understood as twice the perceived intensity of a response at 30, under the assumptions of the scale).

Attributes

Name	Use	Description
id	required	Identification of the response device [ string ]. This `id` must be unique.
sample-period	optional
timing-source	optional	Timing or trigger source: `none`: no source is configured. `internal`: the source is an internal opration such as start of a stimulus. `external`: a trigger event is received from external equipment. `button`: a trigger event is received from a button press on a connected response device attached to any response port. `response-port01`: a trigger is received on response port 1. `response-port02`: a trigger is received on response port 2. `response-port03`: a trigger is received on response port 3. `response-port04`: a trigger is received on response port 4.
length	optional	Physical length of the scale in centimeters [ double ].

Elements

Name Use Description

Name	Use	Description
`<anchors>`	optional	Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.
`<button-maps>`	optional	The `<button-maps>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<map>`

<anchors>

optional

Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.

<button-maps>

optional

The <button-maps> is an array element that can contain a sequence of elements. These elements can be of the following types:

<map>

AnchorDefinitions

Elements

Name	Use	Description
`<modality>`	required	The modality of the scale such as pain, itch, pleasentness, nausia, etc.
`<top-anchor>`	required	Definition of the top anchor for the scale.
`<bottom-anchor>`	required	Definition of the bottom anchor for the scale.

Anchor

Definition of a modality or anchor.

Attributes

Name	Use	Description
text	required	Text describing the element [ string ]. This text will be used if no localization `<localized-text>` for the element is found.

Elements

Name	Use	Description
`<localized-text>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

LocalizedText

Localization of the text, if a localized language is selected then that text will be used instead of the text defined in the text attribute.

Attributes

Name	Use	Description
language	required	Language code, which must be defined in one of the `<language>` definitions in the `<languages>` in the protocol [ string ].
text	required	Localized text to use for the language [ string ].

AudioTriggerDetectorSetup

Defines an audio trigger detector (LabBench ATG) that monitors an incoming audio signal and generates a precise trigger event when the signal exceeds a defined threshold. The arming period specifies a refractory interval after each detection to prevent repeated triggering from the same sound event, while the timing source determines how detected events are timestamped.

Attributes

Name Use Description

required

Identification of the response device [ string ]. This id must be unique.

arming-period

optional

Refractory interval in milliseconds after each detection to prevent repeated triggering from the same event [ int ].

timing-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

VisualTriggerDetectorSetup

Defines a visual trigger detector (LabBench VTG) that uses a photosensor to detect visual fiducials embedded in on-screen stimuli and generates precise trigger events when these fiducials are displayed. The arming period specifies a refractory interval to avoid multiple detections of the same visual event, while the timing source controls how detections are timestamped.

Attributes

Name Use Description

required

Identification of the response device [ string ]. This id must be unique.

arming-period

optional

Refractory interval in milliseconds after each detection to prevent repeated triggering from the same event [ int ].

timing-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

ResponsePadSetup

The LabBench PAD is a configurable multi-button response device used for collecting discrete participant responses during experiments.

Attributes

Name Use Description

required

Identification of the response device [ string ]. This id must be unique.

type

optional

Type of response pad

timing-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<map>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

CPARSetup

Nocitch CPAR

The Nocitech CPAR is a computer-controlled cuff pressure algometer that delivers precise, reproducible pressure stimulation for neuroscience research. It generates customisable piecewise-linear pressure waveforms with accurate temporal control, supporting advanced psychophysical protocols. The device enables automated cuff pressure algometry protocols that are not feasible with manual devices.

Possible protocols:

Cuff Pressure Pain Detection and Tolerance Thresholds: Automatically measures the pressure at which a participant first perceives pain (pain detection threshold) and when pain becomes intolerable (pain tolerance threshold).
Temporal Summation (TS): Applies repeated, identical pressure stimuli to assess increases in perceived pain over time, reflecting central facilitatory pain mechanisms (often referred to as “wind-up”).
Spatial Summation: Uses multiple cuffs or varied stimulation areas to study how pain perception changes with the spatial extent of stimulation.
Conditioned Pain Modulation (CPM): Implements a “pain-inhibits-pain” paradigm, where a conditioning stimulus at one site alters the pain response at another.

These protocols are commonly used in quantitative sensory testing (QST) to investigate peripheral and central sensitisation mechanisms in both healthy and clinical populations.

Attributes

Name	Use	Description
compressor-mode	optional	Control mode for the compressor; AUTO: The compressor will refill automatically after each procedure in the protocol, MANUAL: The compressor will only refill when the minimal working pressure has been reached: auto: the compressor will refill automatically after each procedure in the protocol. manual: the compressor will only refill when the minimal working pressure has been reached.
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

Name

Use

Description

compressor-mode

optional

Control mode for the compressor; AUTO: The compressor will refill automatically after each procedure in the protocol, MANUAL: The compressor will only refill when the minimal working pressure has been reached:

auto: the compressor will refill automatically after each procedure in the protocol.
manual: the compressor will only refill when the minimal working pressure has been reached.

required

Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

CPARPlusSetup

LabBench CPAR+

The LabBench CPAR+ is a computer-controlled cuff pressure algometer that delivers precise, reproducible pressure stimulation for neuroscience research. It generates customisable piecewise-linear pressure waveforms with accurate temporal control, supporting advanced psychophysical protocols. The device enables automated cuff pressure algometry protocols that are not feasible with manual devices.

Possible protocols:

Cuff Pressure Pain Detection and Tolerance Thresholds: Automatically measures the pressure at which a participant first perceives pain (pain detection threshold) and when pain becomes intolerable (pain tolerance threshold).
Temporal Summation (TS): Applies repeated, identical pressure stimuli to assess increases in perceived pain over time, reflecting central facilitatory pain mechanisms (often referred to as “wind-up”).
Spatial Summation: Uses multiple cuffs or varied stimulation areas to study how pain perception changes with the spatial extent of stimulation.
Conditioned Pain Modulation (CPM): Implements a “pain-inhibits-pain” paradigm, where a conditioning stimulus at one site alters the pain response at another.

These protocols are commonly used in quantitative sensory testing (QST) to investigate peripheral and central sensitisation mechanisms in both healthy and clinical populations.

The device synchronises with external recording and stimulation equipment via digital trigger inputs and outputs. It features two independently controllable cuff pressure channels and provides real-time pressure signals as analogue outputs. The CPAR+ requires an external air supply from standard compressors or compressed air bottles.

Attributes

Name	Use	Description
rating-scale	optional	Identification of an optional external rating scale to use with the LabBench CPAR+ [ string ]. If it is not specified or left blank the device will use the rating scale connected to its response port.
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.
button	optional	Identification of an optional external button to use with the LabBench CPAR+ [ string ]. If it is not specified or left blank the device will use the rating scale connected to its response port.

SoundSetup

Soundcard

Soundcards in LabBench enable precise generation of audio signals, making them suitable for a wide range of auditory, psychophysical, and neurophysiological experiments. By leveraging low-latency playback, multi-channel audio, and tight synchronisation with other LabBench devices, soundcards can be integrated into complex experimental protocols, including:

Auditory Detection and Discrimination Thresholds Presentation of pure tones, noise, or complex sounds to determine hearing thresholds, just-noticeable differences (JNDs), and frequency or intensity discrimination performance.
Psychophysical Scaling and Rating Experiments Delivery of controlled auditory stimuli while collecting subjective ratings (e.g. loudness, unpleasantness, or salience) using LabBench response devices or questionnaires.
Temporal Processing and Auditory Timing Tasks Protocols investigating temporal resolution, gap detection, sensitivity to amplitude or frequency modulation, and rhythm perception all rely on accurate stimulus timing.
Multisensory Integration Experiments Synchronization of auditory stimuli with visual, tactile, or nociceptive stimulation (e.g., LabBench CPAR+) to study cross-modal interactions and sensory integration mechanisms.
Event-Related and Continuous Stimulation Paradigms Generation of discrete auditory events or continuous sound streams aligned with digital triggers for EEG, MEG, or other physiological recordings.

Soundcards are commonly used in auditory neuroscience and psychophysics, where precise control over stimulus timing, waveform shape, and synchronisation is critical for reproducible experimental designs.

Attributes

Name	Use	Description
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

JoystickSetup

Joystick

This is a standard USB device used for tasks like answering questionnaires and making ratings. It supports different button setups, each marked by its experiment ID. The button setup changes depending on the chosen procedure.

The device implements the Button, Joystick, and Trigger instruments. The Trigger instrument is a dummy implementation with no functionality, implemented by the device, so it can act as a procedure device for protocols that would otherwise require a LabBench I/O device, or be used to create protocols that can be used with both a Joystick and a LabBench I/O device.

Attributes

Name	Use	Description
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

Elements

Name	Use	Description
`<map>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

TCSSetup

QSTLab TCS

The QSTLab Thermal Cutaneous Stimulator (TCS) is a portable, battery-powered device for controlled contact thermal stimulation in quantitative sensory testing and pain research, offering a 0–60 °C range with 0.1 °C precision and ramps up to 300 °C/sec, five independently settable stimulation zones, external computer control and triggers for EEG/ECG/MRI integration — ideal for automated QST protocols in LabBench.

Attributes

Name	Use	Description
minimal-temperature	optional	Minimal allowed temperature [ double ]. Must be zero or higher.
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.
neutral-temperature	required	Neutral temperature [ double ].
maximal-temperature	optional	Maximal allowed temperature [ double ]. Must be 60C or lower.
trigger-output	optional	Generate a trigger at the onset of stimuli [ bool ].

DisplaySetup

LabBench Display

This <display> device opens a fixed, always-on-top window on a monitor connected to the laboratory computer. Within an experiment, this window supports multiple instruments based on the selected procedure. Each instrument defines the experiment-setup-id that activates it, and each procedure specifies which experiment-setup-id will be used while it is selected.

Instruments that can be defined are:

Image Display: Displays instructions when procedures are inactive and visual stimuli when active.
Questionnaire: Displays questionnaires for participants to complete.
Visual Analog Scale: Displays a ratio scale for participants to rate perceptions.
Numerical Rating Scale: Displays an interval scale for participants to rate perceptions.
Categorical Rating Scale: Displays an ordinal scale for participants to rate perceptions.
Composite Scale: Displays a set of rating scales for participants to potentially rate multiple perceptions simultaneously.

Attributes

Name	Use	Description
normative-distance	optional	Normative distance for visual elements [ double:centimetres ]. This value is used with the monitor.distance to scale the elements so they have the same visual angle for the participant as if they where positioned at the normative distance.
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

Elements

Name Use Description

Name	Use	Description
`<typography>`	optional	Typography establishes the global typographic and colour standards for on-screen textual elements in questionnaires and rating scales. It defines default foreground, background, active, and inactive colours, as well as role-specific typography presets for titles, instructions, answers, scale modalities, anchors, and category labels across various question and scale types.
`<configurations>`	optional	The `<configurations>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<categorical-scale>` `<numerical-scale>` `<visual-analogue-scale>` `<composite-scale>` `<image-display>` `<questionnaire>`

<typography>

optional

Typography establishes the global typographic and colour standards for on-screen textual elements in questionnaires and rating scales. It defines default foreground, background, active, and inactive colours, as well as role-specific typography presets for titles, instructions, answers, scale modalities, anchors, and category labels across various question and scale types.

<configurations>

optional

The <configurations> is an array element that can contain a sequence of elements. These elements can be of the following types:

<categorical-scale>
<numerical-scale>
<visual-analogue-scale>
<composite-scale>
<image-display>
<questionnaire>

Typography

Attributes

Name	Use	Description
background-colour	optional	Background colour [ Text (default: #FFFFFF) ].
foreground-colour	optional	Foreground colour [ Text (default: #000000) ].
active-colour	optional	Active colour [ Text (default: #FF0000) ].
inactive-colour	optional	Inactive colour [ Text (default: #161616) ].

Elements

Name	Use	Description
`<title>`	optional	Typography for question titles in questionnaires.
`<instruction>`	optional	Typography for question instructions in questionnaires.
`<answer>`	optional	Typography for possible answers to boolean, list, and multiple-choice questions in questionnaires.
`<likert-category>`	optional	Typography for categories in likert and dimensional likert questions in questionnaires.
`<numerical-answer>`	optional	Typography for answers to numerical questions in questionnaires.
`<text-answer>`	optional	Typography for answers to text questions in questionnaires.
`<time-answer>`	optional	Typography for answers to time/date questions in questionnaires.
`<scale-modality>`	optional	Typography for scale modalities in numerical, categorical, and psychometric rating questions in questionnaires as well as for psychomeric rating scales.
`<top-anchor>`	optional	Typography for the top anchor in psychometric rating questions in questionnaires as well as for psychomeric rating scales.
`<bottom-anchor>`	optional	Typography for the bottom anchor in and psychometric rating questions in questionnaires as well as for psychomeric rating scales.
`<crs-category>`	optional	Typography for the categories in categorical rating questions in questionnaires as well as for categorical rating scales.
`<nrs-category>`	optional	Typography for the categories in numerical rating questions in questionnaires as well as for numerical rating scales.

ElementTypography

Typography of a screen element

Attributes

Name	Use	Description
size	required	Size of the font that is used for the element.
border-thickness	optional	Border thickness of the element.
style	optional	Style of the font, whether it is normal or in italic.
weight	optional	Indicates the visual weight (degree of blackness or thickness of strokes) of the characters in the font.
colour	optional	The colour of the element

DisplayCategoricalScaleSetup

A categorical rating scale (CRS) represents an ordered set of discrete response categories used to report the perceived magnitude or quality of a subjective sensation. CRS scales are ordinal scales, meaning that the ordering of categories is meaningful, but neither the magnitude of differences between adjacent categories nor ratios between categories is defined or assumed to be equal. As a result, comparisons are limited to statements of greater-than or less-than (e.g., category C indicates more perceived intensity than category B), without any metric interpretation of spacing.

The scale is defined by a modality and a finite set of semantically labelled categories spanning the response range from minimal to maximal perceived intensity.

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
controller-device	required	Identification of the device used to control this device [ string ].

Elements

Name Use Description

<anchors>

required

<categories>

optional

The <categories> is an array element that can contain a sequence of elements. These elements can be of the following types:

<category>

DisplayNumericalScaleSetup

With a numerical rating scale (NRS), observers report the perceived magnitude of a subjective sensation by selecting a value from an ordered numeric set. In LabBench, an NRS is treated as an interval scale, meaning that equal numeric differences are intended to correspond to equal differences in perceived magnitude, but the zero point does not constitute a true absence of the perceptual quantity in a measurement-theoretic sense. Consequently, differences between values are interpretable, whereas ratios are not (e.g., the difference between ratings 6 and 8 is meaningful, but a rating of 8 cannot be interpreted as “twice” the intensity of a rating of 4).

The scale is defined by a modality and the lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality. The anchors serve as reference points for minimal and maximal perceived intensity, without implying a physically or perceptually absolute zero. Responses are restricted to discrete steps between a minum and maximum integer value.

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
maximum	required	The maximal value for the scale [ int ].
minimum	required	The minimum value for the scale [ int ].
controller-device	required	Identification of the device used to control this device [ string ].

Elements

Name	Use	Description
`<anchors>`	required	Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.

DisplayVisualAnalogScaleSetup

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
length	optional	Physical length of the scale in centimetres [ double ].
controller-device	required	Identification of the device used to control this device [ string ].

Elements

Name	Use	Description
`<anchors>`	required	Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.

DisplayCompositeScaleSetup

A composite scale consists of one or more psychophysical rating scales, each of which can be a visual analog, numerical, or categorical scale. It is possible, but not recommended, to mix scales; the most common configuration is a single scale.

For its operation, it must be assigned a controller-device that must implement a Button instrument with the following button-assignments:

increase: increase the rating on the currently active scale.
decrease: decrease the rating on the current active scale.
previous: activate the previous scale in the defined set of scales.
next: activate the next scale in the defined set of scales.

If only one scale is defined, the previous and next buttons will have no effect.

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
controller-device	required	Identification of the device used to control this device [ string ].

Elements

Name	Use	Description
`<visual-analogue-scale>` `<numerical-scale>` `<categorical-scale>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

NestedVisualAnalogScaleSetup

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Identification of the scale [ string ].
length	optional	Physical length of the scale in centimetres [ double ].

Elements

Name	Use	Description
`<anchors>`	required	Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.

NestedNumericalScaleSetup

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Identification of the scale [ string ].
maximum	required	The maximal value for the scale [ int ].
minimum	required	The minimum value for the scale [ int ].

Elements

Name	Use	Description
`<anchors>`	required	Definition of the scale modality and its lower and upper anchors of the perceptual dimension. The lower anchor denotes the null intensity of the sensation, while the upper anchor denotes the maximum subjectively imaginable intensity for that modality.

NestedCategoricalScaleSetup

The scale is defined by a modality and a finite set of semantically labelled categories spanning the response range from minimal to maximal perceived intensity.

For its operation, its controller-device must implement a Button instrument with the following button-assignments:

increase: increase the rating on the scale.
decrease: decrease the rating on the scale.

Attributes

Name	Use	Description
id	required	Identification of the scale [ string ].

Elements

Name Use Description

<anchors>

required

<categories>

optional

The <categories> is an array element that can contain a sequence of elements. These elements can be of the following types:

<category>

ImageSetup

An instrument that can be used for the display of images. This can be used either to display instructions to participants when procedures are inactive or to display visual stimuli for experimental procedures such as visually evoked potentials and behavioural procedures (Stroop, Flanker, Stop-Signal tasks, etc.).

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
background-colour	optional	Setting this attribute will override the background colour defined by in the typography element for the display.

DisplayQuestionnaireSetup

Displays questionnaires for participants to complete, which can be used to ask the participants to provide answers to:

Boolean Questions: binary questions answered with either a true or false statement.
Numerical Questions: numbers provided by the participant but entered by the operator.
Text Questions: verbal answers provided by the participant but entered by the operator.
Likert Questions: A scale that captures how strongly someone agrees, disagrees, or feels about a statement using a fixed set of ordered response options.
List Questions: A set of binary statements that each can be either true or false.
Time Questions: a date and time provided by the participant, entered by the operator.
Map Questions: a set of regions, such as a body map, where each region can be marked.
Categorical Rating Questions: rating of a sensation on a categorical scale.
Numerical Rating Questions: rating of a sensation on a numerical scale.
Visual Rating Questions: rating of a sensation on a visual analog rating scale.

For the participants to fill out these questions, the controller-device must define the following buttons:

up, down: Is used by Boolean and Likert questions to set answers, and is used by List and Map questions to navigate between answers.
left, right: Is used by Map questions to navigate between answers.
increase, decrease: Is used by Map, List, Likert, and Rating questions to set answers.
previous, next: used to navigate between questions.

If the controller-device also implements the Joystick instrument, this joystick can be used to move between selected areas in map questions.

Attributes

Name	Use	Description
id	required	Device identification that will be used to identify the sub-device in device assignments [ string ].
experimental-setup-id	required	Identification of the experimental setup state where this device will be active [ string ].
controller-device	required	Identification of the device used to control this device [ string ].

EVASSetup

QSTLab eVAS

Attributes

Name	Use	Description
initialize-rating-to-zero	optional	Reset the rating to zero when a procedure is started [ bool ].
id	required	Identification of the device, which is used to identify the device when it is assigned to procedures in the protocol.

Elements

Name Use Description

<visual-analogue-scale>

optional

DeviceAssignment

Assignment of a device to an instrument required by one or more of the procedures in the protocol.

Attributes

Name	Use	Description
device-id	required	Identification of the device, this must be the ID of a device defined in the devices section of the experimental setup.
procedure-id	optional	If specified the device will only be assigned to one procedure in the protocol with has this specified `procedure-id.`
instrument-name	required	Instrument name that the procedures in the protocol has assigned to the instrument.

ExperimentalSetupCollection

Defines possible experimental setups for the protocol.

Attributes

Name	Use	Description
default	optional	Identifier of the default experimental setup. This setup will be used when an experiment is installed remotely.

Elements

Name	Use	Description
`<experimental-setup>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Protocol

This element defines the protocol for the experiment. The main part of the protocol definition is the definition of the procedures (experimental procedures) performed in the experimental sessions. The procedure definitions must be performed for all protocols and are supported by optional elements.

This protocol contains the following elements:

<languages>: this optional element defines the languages/cultures for which the protocol is localized. If present, the startup wizard will display a page where the operator can select the language to use in the current experimental session.
<sessions>: this optional element defines the sessions of the experiment. If present, the startup wizard will display a page where the operator can select the current session, and each procedure in the <procedures> element must define which session it belongs to. When the session is performed, the LabBench Runner will only display procedures for the current session.
<properties>: this optional element defines properties of the protocol that modifies the execution of the procedures.
<randomisations>: this optional element defines variables generated once a participant is created and exported with the recorded data. The primary use of these variables is randomization. However, they can be used for any variable that should be persisted in the data set.
<defines>: this optional element defines variables that can have any type. Consequently, they can be used for complex variables not saved in the data set, such as Python classes created in backing scripts. They are created every time a session is started.
<templates>: this optional element defines template variables and procedure templates that can be used to construct procedures at runtime in the <procedures> element.
<procedures>: this mandatory element defines the procedures of the protocol. These can be directly defined in this element or constructed from procedure templates defined in the <templates> element.
<assets>: this optional element defines external files that the procedures in the protocol can use.

The order of these elements is significant and must be defined in the order given above.

Elements

Name	Use	Description
`<languages>`	optional	The `<languages>` element can localize protocols. When specified, it must contain a list of languages, which will be shown to the operator in the Startup wizard in LabBench Runner. The operator can then select one language, and its language code will be added to the definition as the variable `Language`. Consequently, this `Language` variable can then be used in Python expressions and scripts to provide the correct translations of the text in the protocol. Protocol assets in the `<assets>` can also select different files based on the selected language code. Use of language codes from the ISO 639 standard is recommended, as this standard guarantees that protocols can be combined. A list of ISO 639 language codes can be found at List of ISO 639 language codes
`<sessions>`	optional	Defines the list of individual experimental sessions scheduled for each participant in the study. Each `<session>` entry within this block should include a unique id and a descriptive name. Use this tag to structure how data and procedures are grouped over time in your protocol. When LabBench Runner is started, the operator will choose an active session in the Startup Wizard. In Python code the `id` of the currently active session is available as `context.ActiveSession`.
`<properties>`	optional	Defines protocol level properties.
`<persistent-variables>`	optional	Defines persistent variables that are assigned once when a participant is enrolled in the study and remain constant across all sessions. These variables are used to for example represent participant-specific randomised factors such as treatment group assignment, stratification variables, or any random attributes that do not change over time. By defining them here, you ensure that these values are generated at participant creation and stay invariant throughout the entire experimental protocol. Use `<persistent-variables>` to organise all participant-level variables critical for consistent data labelling and analysis. These variables are included in the exported data set.
`<variables>`	optional	Definition of a variable that can be used in calculated parameters.
`<templates>`	optional	This element defines template variables and procedure templates that can be used to programmatically generate the procedures in the protocol. Procedures can be generated with procedure constructors in the `<procedures>` element. Using procedure templates to create procedures `<procedures>` element is called templating and can be seen as code-generating code. Constructors generate procedures at the place in the `<procedures>` element where the constructor is defined. Constructors can be organised into `<sequences>` and generated by `<foreach>` loops. Both `<sequences>` and `<foreach>` elements make it possible to perform randomisation of the order in which the generated procedures appear in the protocol.
`<procedures>`	optional	The `<procedures>` element defines the procedures of the protocol. These can be directly defined in this element or constructed from procedure templates defined in the `<templates>` element.
`<assets>`	optional	Files can be included in experiments in the form of assets within the `<assets>` element in the Experiment Definition File. This element consists of a set of `<file-asset>` that can be used in procedures and Python code. The following assets can be included: .py: Python code .md: Markdown Files .txt: Text Files .rtf: Rich Text Format .png: Portable Network Graphics .zip: Zip files .json: Data files .wav: Sound files .csv: Comma Separated Values .svg: Scalable Vector Graphics .ttf: True Type Fonts Within calculated parameters, assets can be referred to by the `id` with the following notation: `Asset.[AssetID]`. Files within zip archives can be further addressed as `Asset.[AssetID].[Name of file without extension]`. Please note that paths and extensions within zip files are not considered. Consequently, in a zip file, there must be only one file with a given name, regardless of its extension or location within the zip file.

LanguageCollection

The <languages> element can localize protocols. When specified, it must contain a list of languages, which will be shown to the operator in the Startup wizard in LabBench Runner. The operator can then select one language, and its language code will be added to the definition as the variable Language.

Consequently, this Language variable can then be used in Python expressions and scripts to provide the correct translations of the text in the protocol. Protocol assets in the <assets> can also select different files based on the selected language code.

Use of language codes from the ISO 639 standard is recommended, as this standard guarantees that protocols can be combined. A list of ISO 639 language codes can be found at List of ISO 639 language codes

Elements

Name	Use	Description
`<language>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Language

Definition of a language.

Attributes

Name	Use	Description
code	required	This attribute is the language code (ISO 639) used to identify the language in the protocol [ string ].
name	required	This attribute is the name of that language that will be shown in the Startup Wizard [ string ].

SessionConfiguration

Defines the list of individual experimental sessions scheduled for each participant in the study.

Each <session> entry within this block should include a unique id and a descriptive name. Use this tag to structure how data and procedures are grouped over time in your protocol. When LabBench Runner is started, the operator will choose an active session in the Startup Wizard.

In Python code the id of the currently active session is available as context.ActiveSession.

Elements

Name	Use	Description
`<session>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SessionDefinition

Defines a single experimental session within the overall study timeline.

A session represents one scheduled visit or timepoint when a participant engages in specific tasks or procedures. Each session must have a unique id (used for referencing and tracking) and a human-readable name (used for display and documentation).

Sessions are the building blocks of longitudinal and multi-phase protocols, allowing researchers to organise data collection across multiple timepoints such as baseline, intervention, and follow-up. The order and content of sessions are often tied to the study design and are critical for analysis and reproducibility.

Attributes:

id: A short, unique identifier (e.g., "SES01") this will be used to identify the session in the LabBench markup language and in included Python code.
name: A descriptive human-readable name (e.g., "Session 1" or "Pre-treatment Visit") this is the name that will be shown to the operator in the LabBench Runner startup wizard.

Example:

<session id="SES01" name="Session 1" />

Use one <session> element per visit to clearly define the structure of your experimental schedule.

Attributes

Name	Use	Description
id	required	A unique identifier for the session, used for referencing within the protocol.
name	required	A human-readable label for the session, used for display in the LabBench Runner Startup Wizard.

ProtocolProperties

Defines protocol level properties.

Elements

Name	Use	Description
`<rerun-policy>`	optional	Specifies a procedure rerun policy for the protocol. When a procedure is completed its results will automatically be saved in the current session. However, if a procedure is rerun these results will be discarded and replaced with the new results from the procedure. When a procedure is rerun a warning dialog will be displayed, which can be customised by this rerun policy to display a custom message and to require that a reason is provided before the procedure can be restarted.
`<incomplete-protocol-warning>`	optional	Display a warning if the protocol is incomplete when the LabBench Runner is closed.
`<allow-in-session-participant-creation>`	optional	Allow participants to be created during a session. The default is true.
`<in-session-display-of-participants>`	optional	Display the list of existing participants during in-session selection or creation of a participant. The default is true.

ProtocolRerunPolicy

Specifies a procedure rerun policy for the protocol. When a procedure is completed its results will automatically be saved in the current session. However, if a procedure is rerun these results will be discarded and replaced with the new results from the procedure. When a procedure is rerun a warning dialog will be displayed, which can be customised by this rerun policy to display a custom message and to require that a reason is provided before the procedure can be restarted.

Attributes

Name	Use	Description
message	optional	The message to be displayed to the operator [ dynamic string ]. The default value is ‘Rerunning the procedure will discard the current results.’.
require-reason	optional	Force the operator to provide a reason for rerunning the procedure that is entered into the session log.
force-warning	optional	Display the warning when a procedure that discards data is rerun. The default value is false.

BooleanValue

bool

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Boolean value [ bool ].

PersistentVariableGenerator

Defines persistent variables that are assigned once when a participant is enrolled in the study and remain constant across all sessions.

These variables are used to for example represent participant-specific randomised factors such as treatment group assignment, stratification variables, or any random attributes that do not change over time. By defining them here, you ensure that these values are generated at participant creation and stay invariant throughout the entire experimental protocol.

Use <persistent-variables> to organise all participant-level variables critical for consistent data labelling and analysis. These variables are included in the exported data set.

Elements

Name	Use	Description
`<integers>` `<integer>` `<strings>` `<string>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

IntegerListPersistentVariable

Defines a named set of integer values that can be used as fixed options or parameters within the experimental protocol.

This element uses a Python-style list ([1,2,3]) in the value attribute structured list syntax. The name attribute assigns a variable name to the set, and the value attribute provides the list of integers.

Attributes:

name: A descriptive name for the integer set (e.g., "Order") [ string ].
value: A list of integers enclosed in square brackets and separated by commas (e.g., "[1,2,3]") [ int = Calculated(context) ].

Examples:

Defined within the LabBench Markup Language:

<integers name="Order" value="[1,2,3]" />

Defined in a Python backing script:

<integers name="Order" value="func: Script.CreateOrder(context)" />

Within the LabBench Markup Language the created variable can be accessed by its name, and within a Python script it can be accessed as context.[Name].

Attributes

Name	Use	Description
name	required
value	required

IntegerPersistentVariable

Defines a single named integer value to be used as a fixed parameter in the experimental protocol.

The name attribute specifies the label for the value, and the value attribute holds the integer itself. This element is useful for defining constants such as counts, limits, or configuration parameters that apply across sessions or participants.

Attributes:

name: A descriptive name for the parameter (e.g., "NumberOfSites") [ string ].
value: A single integer value (e.g., "4") [ int = Calculated(context) ].

Example:

Defined within the LabBench Markup Language:

<strings name="NumberOfSites" value="4" />

Defined in a Python backing script:

<integers name="NumberOfSites" value="func: Script.CreateNumberOfSites(context)" />

Within the LabBench Markup Language the created variable can be accessed by its name, and within a Python script it can be accessed as context.[Name].

Attributes

Name	Use	Description
name	required
value	required

StringListPersistentVariable

Defines a named set of string values to be used as fixed options or parameters within the experimental protocol.

This element uses a Python-style list (['Cowhage','Histamine']) in the value attribute. The name attribute specifies the label, and the value attribute provides a list of string options.

Attributes:

name: A descriptive name for the string set (e.g., "Puritogens") [ string ].
value: A list of strings enclosed in square brackets and separated by commas, with each string in single quotes (e.g., ['Cowhage','Histamine']).

Example:

Defined within the LabBench Markup Language:

<strings name="Puritogens" value="['Cowhage','Histamine']" /> [ string[] = Calculated(context) ].

Defined in a Python backing script:

<integers name="Order" value="func: Script.CreatePruritogens(context)" />

Within the LabBench Markup Language the created variable can be accessed by its name, and within a Python script it can be accessed as context.[Name].

Attributes

Name	Use	Description
name	required
value	required

StringPersistentVariable

Defines a single named string value to be used as a fixed parameter in the experimental protocol.

The name attribute assigns a label to the value, and the value attribute provides the string itself. This is useful for specifying constant text values such as site names, condition labels, or protocol settings that do not change during the study.

Attributes:

name: A descriptive name for the parameter (e.g., "SiteName").
value: A single string value (e.g., "'Arm'"") [ string = Calculated(context) ].

Example:

Defined within the LabBench Markup Language:

<strings name="SiteName" value="'Arm'" />

Defined in a Python backing script:

<integers name="SiteName" value="func: Script.CreateSiteName(context)" />

Within the LabBench Markup Language the created variable can be accessed by its name, and within a Python script it can be accessed as context.[Name].

Attributes

Name	Use	Description
name	required
value	required

VariableCollection

Definition of a variable that can be used in calculated parameters.

Elements

Name	Use	Description
`<struct>` `<variable>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StructVariable

Grouping of variables into structs.

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].

Elements

Name	Use	Description
`<struct>` `<variable>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Variable

Definition of a variable that can be used in calculated parameters.

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].
value	required	The value of the variable [ Any = Calculated(context) ].

TemplateCollection

This element defines template variables and procedure templates that can be used to programmatically generate the procedures in the protocol. Procedures can be generated with procedure constructors in the <procedures> element. Using procedure templates to create procedures <procedures> element is called templating and can be seen as code-generating code. Constructors generate procedures at the place in the <procedures> element where the constructor is defined.

Constructors can be organised into <sequences> and generated by <foreach> loops. Both <sequences> and <foreach> elements make it possible to perform randomisation of the order in which the generated procedures appear in the protocol.

Elements

Name	Use	Description
`<includes>`	optional	The `<include>` element allows including templates from other protocols, enabling a repository of validated template protocols that can be used to construct protocols. When a protocol is included, everything in its `<templates>` element is included. If there are overlapping names between the items in the source and destination protocols, this will result in an error that prevents inclusion.
`<template-variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<protocol-variables>`	optional	Definition of variables that will be added to the protocol variables.
`<procedure-templates>`	optional	This element defines the procedure templates from which procedure constructors can generate procedures.
`<assets>`	optional	Definition of assets that will be added to the protocol assets.

IncludeGenerator

The <include> element allows including templates from other protocols, enabling a repository of validated template protocols that can be used to construct protocols. When a protocol is included, everything in its <templates> element is included. If there are overlapping names between the items in the source and destination protocols, this will result in an error that prevents inclusion.

Elements

Name	Use	Description
`<include>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

IncludeSpecification

Inclusion of the content of the <templates> element in a source protocol in the present protocol.

Attributes

Name	Use	Description
protocol-id	required	The protocol identifier (`id`) of the protocol to include [ string ]. This source protocol must reside in the same protocol repository as the destination protocol.

TemplateVariableCollection

Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in <foreach> loops and thus generate multiple procedures, each differing by an element in this list.

An example of the generated of a procedure ID from a template variable:

id="var: f'B05{p}'"

The keyword var: instructs the procedure constructor to generate the value of the id programmatically from the Python expression in the code; the template variable is named p, which comes from the following for each loop:

<foreach variable="p" in="procedures">

Elements

Name	Use	Description
`<string>` `<strings>` `<struct>` `<structs>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StringTemplateVariable

string

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].
value	required	Value of the variable [ string ].

StringListTemplateVariable

string[]

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].
value	required	Value of the variable [ string ]. List of strings are specified as strings seperated by semicolons `;`.

StructTemplateVariable

struct

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].

Elements

Name	Use	Description
`<string>` `<struct>` `<strings>` `<structs>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StructListTemplateVariable

struct[]

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].

Elements

Name	Use	Description
`<struct>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

UnnamedStructTemplateVariable

struct

Elements

Name	Use	Description
`<string>` `<struct>` `<strings>` `<structs>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ProtocolVariableTemplates

Definition of variables that will be added to the protocol variables.

Elements

Name	Use	Description
`<struct>` `<variable>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

TemplateList

This element defines the procedure templates from which procedure constructors can generate procedures.

Elements

Name	Use	Description
`<questionnaire>` `<sequential>` `<stimulation-sequence>` `<algometry-stimulus-response>` `<algometry-conditioned-pain-modulation>` `<algometry-temporal-summation>` `<algometry-static-temporal-summation>` `<algometry-stimulus-rating>` `<algometry-conditioned-pain-modulation-rating>` `<algometry-arbitrary-temporal-summation>` `<psychophysics-threshold-estimation>` `<psychophysics-cold-pressor>` `<psychophysics-manual-threshold-estimation>` `<psychophysics-response-recording>` `<psychophysics-stimulus-presentation>` `<thermal-rated-stimulation>` `<thermal-threshold-estimation>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

QuestionnaireTemplate

The questionnaire procedure allows either the operator or the participant to answer a set of questions. The questionnaire can consist of the following types of questions:

Boolean Questions: questions that have mutually exclusive binary answer, which usually consists of answering a true or false statement, but can also consist of dichotomies such as child/adult.
Numerical Questions: are questions that can be answered with numerical answers.
Text Questions: are questions that can be answered with either free or validated text.
Likert Questions: A scale that captures how strongly someone agrees, disagrees, or feels about a statement using a fixed set of ordered response options.
List Questions: A set of binary statements that each can be either true or false.
Time Questions: a date and time provided by the participant, entered by the operator.
Map Questions: is answered by marking one or more regions, such as areas on a body map.
Categorical Rating Questions: rating of a sensation on a categorical scale.
Numerical Rating Questions: rating of a sensation on a numerical scale.
Visual Rating Questions: rating of a sensation on a visual analog rating scale.

All questions are identified with an id and have a title and an instruction. If the questionnaire is to be answered by the participant, a Questionnaire instrument must be assigned to the procedure in the experimental setup.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
progress-format	optional	Controls the progress information that is provided by the procedure: `none`: no progresss information is provided. `percentage`: progress is provided as the percentage of completed questions. `index`: progress is provided as [current question no] / [total number of questions].
control	optional	Sets whether the questionnaire is filled out by the operator or the participant: `operator`: answers are provided by the operator. `participant`: answers are provided by the participant. In this mode a Questionnaire instrument must be assigned to the procedure.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<question-events>`	optional	Definition of calculated parameters that are executed when the state of questions changes; this makes it possible to extend the functionality of the Questionnaire procedure with additional functionality implemented in Python.
`<templates>`	optional	The `<templates>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<map>` `<text>` `<boolean>` `<numeric>` `<likert>` `<dimensional-likert>` `<list>` `<time>` `<visual-analogue-scale>` `<numerical-scale>` `<categorical-scale>`
`<content>`	optional	The `<content>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<map-constructor>` `<text-constructor>` `<boolean-constructor>` `<numeric-constructor>` `<likert-constructor>` `<dimensional-likert-constructor>` `<list-constructor>` `<time-constructor>` `<visual-analogue-scale-constructor>` `<numerical-scale-constructor>` `<categorical-scale-constructor>` `<foreach>`

ProcedureEventsTemplate

Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure.

This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.

Attributes

Name	Use	Description
start	optional	Specifies code that will be executed when the procedure is started [ bool = Calculated(context) ]. If False is returned the procedure will be aborted.
complete	optional	Specifies code that will be executed when the procedure is completed [ bool = Calculated(context) ]. If False is returned the procedure will be aborted.
abort	optional	Specifies code that will be executed when the procedure is aborted [ bool = Calculated(context) ]. Please note this calculated attribute must always return True.
selected	optional	Specifies code that will be executed when the procedure is selected regardsless of its state [ bool = Calculated(context) ]. Please note if a selected state is defined this will override the code provided in this attribute.
selected-blocked	optional	Specifies code that will be executed when the procedure is selected and is in the blocked state [ bool = Calculated(context) ].
selected-ready	optional	Specifies code that will be executed when the procedure is selected and is in the ready state [ bool = Calculated(context) ].
selected-completed	optional	Specifies code that will be executed when the procedure is selected and is in the completed state [ bool = Calculated(context) ].
selected-excluded	optional	Specifies code that will be executed when the procedure is selected and is in the excluded state [ bool = Calculated(context) ].

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

DeviceDescriptionTemplate

@Schema.Core.Setup.DeviceDescription.md

Attributes

Name	Use	Description
name	optional	Instrument name of the instrument. There must be a device assignment with that instrument name of the correct instrument type.
interface	required	Type of instrument.

ProcedurePropertiesTemplate

Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.

Elements

Name	Use	Description
`<auto-start>`	optional	Start the procedure when it is selected automatically when the previous procedure in the protocol has been completed. The procedure is only started automatically if the completion of a previous procedure selects the procedure. It is not started automatically if the operator manually selects the procedure. This procedure property can be used to speed up the execution of protocols. The default value of this procedure property is "false," meaning procedures will not be automatically started.
`<auto-advance>`	optional	This element controls whether the next procedure in the protocol will be automatically selected when the current procedure is completed. The default value is "true," meaning the next procedure will be automatically selected.
`<time-constraint>`	optional	This element places a time constraint on when the procedure can be started based on either the start time or completion time of another procedure in the protocol. The time constraint can impose a minimum (min attribute is specified) or maximum time (max attribute is specified) that must elapse before the procedure can be started or a time window (both min and max attributes are specified) within which the time can be started.
`<instructions>`	optional	This element specifies instructions for the operator when the procedure is not running. They will be shown in the procedure window instead of the procedure-specific user interface.
`<participant-instructions>`	optional	This element specifies instructions for the participant. They will be shown on an ImageDisplay instrument that must be assigned to the procedure in a device assignment in the experimental setup.
`<next>`	optional	Link to another procedure within the protocol.
`<annotations>`	optional	Custom data that can be added to procedure results either in the experiment definition file (*.expx) or by Python code.

TimeConstraintTemplate

This element places a time constraint on when the procedure can be started based on either the start time or completion time of another procedure in the protocol. The time constraint can impose a minimum (min attribute is specified) or maximum time (max attribute is specified) that must elapse before the procedure can be started or a time window (both min and max attributes are specified) within which the time can be started.

Attributes

Name	Use	Description
procedure-id	required	This attribute specifies the ID of the procedure to which the timing constraint is relative.
min	optional	If this attribute is specified, it specifies the minimum time to pass before the procedure can be started. If the max attribute is also specified, the timing constraint is a time window in which the procedure can only be started within the minimum (min attribute) and maximum (max attribute) time values.
max	optional	If this attribute is specified, it specifies the maximum time that the procedure can be started. If the min attribute is also specified, the timing constraint is a time window in which the procedure can only be started within the minimum (min attribute) and maximum (max attribute) time values.
notification	optional	This attribute controls whether a beep should be sounded when the timing constraint is satisfied.
time-reference	optional	This attribute specifies whether the timing constraint is relative to a procedure’s start or end (completion).

ProcedureInstructionsTemplate

This element specifies instructions for the operator when the procedure is not running. They will be shown in the procedure window instead of the procedure-specific user interface.

Attributes

Name	Use	Description
start-instruction	optional	Tooltip for the start button [ dynamic string ]. If specified, this will override the default text.
override-results	optional	This attribute controls whether instructions will be shown instead of procedure results in the procedure window for completed procedures. If set to true, instructions will be shown instead of the procedure results [ Boolean (true/false) ]. The default value is false.
default	optional	Instructions that will be shown if instructions are not specified for the current procedure state [ IAsset = Calculated(context) ].
blocked	optional	Instructions that will be shown when the procedure is in its BLOCKED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ]
ready	optional	Instructions that will be shown when the procedure is in its READY state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].
excluded	optional	Instructions that will be shown when the procedure is in its EXCLUDED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].
completed	optional	Instructions that will be shown when the procedure is in its COMPLETED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].

ParticipantInstructionsTemplate

This element specifies instructions for the participant. They will be shown on an ImageDisplay instrument that must be assigned to the procedure in a device assignment in the experimental setup.

Attributes

Name	Use	Description
experimental-setup-id	required	This attribute specifies the experimental setup ID that will activate the assigned ImageDisplay [ string ]. This ID can be different from the experimental setup ID for the procedure in general and will only be activated when the procedure is not running.
default	optional	Instructions that will be shown if instructions are not specified for the current procedure state [ IAsset = Calculated(context) ].
blocked	optional	Instructions that will be shown when the procedure is in its BLOCKED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
ready	optional	Instructions that will be shown when the procedure is in its READY state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
excluded	optional	Instructions that will be shown when the procedure is in its EXCLUDED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
completed	optional	Instructions that will be shown when the procedure is in its COMPLETED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.

ProcedureLinkTemplate

Link to another procedure within the protocol.

Attributes

Name	Use	Description
id	required	Identification (`id`) of the procedure that is linked to [ dynamic string ].

ProcedureAnnotationsTemplate

Custom data that can be added to procedure results either in the experiment definition file (*.expx) or by Python code.

Elements

Name	Use	Description
`<bool>` `<bools>` `<number>` `<numbers>` `<string>` `<strings>` `<integer>` `<integers>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanValueTemplate

bool

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required

BooleanListValueTemplate

bool[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<bool>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

NumberValueTemplate

double

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Value [ double ].

NumberListValueTemplate

double[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<number>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StringValueTemplate

string

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Value [ string ].

StringListValueTemplate

string[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<text>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

IntegerValueTemplate

int

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Integer value [ int ].

IntegerListValueTemplate

int[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<number>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ProcedureDependencyTemplate

Calculated parameters and Python code may use results from previously completed procedures. For example, a Stimulation sequence procedure may set the intensity (x="[ProcedureID].[ChannelID])of the stimuli to thresholds determined in a completed Threshold Estimation procedure. However, if the stimulation sequence procedure is started before the Threshold Estimation procedure has been completed, the code above would result in a runtime error.

Consequently, it must be declared if the results of a procedure are used in another procedure. This declaration is done with the <dependency> element within the <dependencies> element in the procedure definition.

These dependencies can be nonvirtual or virtual. If a procedure dependency is nonvirtual, rerunning the dependency will invalidate the dependent's results, meaning that after the dependency has completed, the dependent's results will be discarded. If a procedure dependency is virtual, it means it is a logical dependency that does not invalidate the results of the dependent. Consequently, in that case, the result of the dependent will not be discarded when the dependency is completed.

Attributes

Name	Use	Description
id	required	Identifier (`id`) of the procedure that the current procedure depends on [ string ].
virtual	optional	Is it a virtual dependency [ bool ].

ConditionTemplate

Makes it possible to exclude procedures based on the results of completed procedures.

Attributes

Name	Use	Description
expression	required	Condition on the execution of the procedure [ bool = Calculated(context) ]. If this calculated attribute is True the procedure will be included, otherwise it will be excluded.
help	required	This attribute must provide an explanation for why a procedure has been excluded [ dynamic string ].

QuestionEventsTemplate

Definition of calculated parameters that are executed when the state of questions changes; this makes it possible to extend the functionality of the Questionnaire procedure with additional functionality implemented in Python.

Attributes

Name	Use	Description
start	optional	Called when a question is started [ bool = Calculated(context) ].
complete	optional	Called when a question is completed [ bool = Calculated(context) ].
changed	optional	Called when a the answer to a question is changed [ bool = Calculated(context) ].

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AreaQuestionTemplate

The <map> question lets users select areas on an image, such as marking pain on a body map. If the map question is answered by the operator, they selected/deselected areas by clicking on the image in the LabBench Runner procedure window. If the participants answer the question, they will use a Button instrument to navigate between areas and to select/deselct them.

When participants answer the question, the following button functions must be defined in the button configuration:

up, down, left, right: are used to navigate between areas.
increase and decrease: are used to select/deselect areas.

If the assigned device also implements the Joystick instrument, joystick movement can be used to navigate between areas.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
image-map	required	An image that will provide the areas that can be selected [ image = Calculated(context) ]. Each area must be uniformly colored with a single color, and an `<area>` element for that colour must be defined for that. The question will then replace that colour with either the selected-color, deselected-color, active-selected-color, or active-deselected-color, depending on whether that area is selected/deselected and active or inactive.
overlay-image	optional	An overlay image that will be added on top of the processed area image [ image = Calculated(context) ]. Consequently, this image can be used to add information and a decal to the area image. For the areas to be visible, all pixels that do not provide information or a decal must be transparent.
selected-colour	required	The colour of areas that the participant have selected, but which is currently not active [ string ]. The colour must be specified in hex in the form of #RRGGBB.
active-selected-colour	required	The colour of areas that are selected and active [ string ]. The colour must be specified in hex in the form of #RRGGBB. Please not that the concept of active/inactive areas is only used when the questionnaire is answered by the participant. If the operator answers the questionnaire then this attribute has no effect.
deselected-colour	required	The colour of areas that the participant has not selected and which are currently not active [ string ]. This colour is typically the same as the background colour of the image, meaning deselected/not active areas will not be colored. The colour must be specified in hex in the form of #RRGGBB.
active-deselected-colour	required	The colour of areas that are active but not selected [ string ]. The colour must be specified in hex in the form of #RRGGBB. Please not that the concept of active/inactive areas is only used when the questionnaire is answered by the participant. If the operator answers the questionnaire then this attribute has no effect.
selection-mode	optional	Area selection mode: `single`: one a single area can be selected. If an area is selected and another area is allready selected then the other area will be automatically deselected. `multiple`: multiple areas can be selected simultaneously.
initial-active-area	optional	Sets which area is initially active [ string ]. This must be the ID of an `<area>` element.

Elements

Name	Use	Description
`<area>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AreaTemplate

An area on the image can be selected or deselected. Each area has an id and a colour, which matches the colour of the pixels in that area. The operator or participant will not see this color, as it will be replaced by one of the following:

deselected-colour: an area that is neither selected nor active.
selected-colour: an area that has been selected by the operator/participant but is not active.
active-deselected-colour: an area has not been selected and is active.
active-selected-colour: an area has been selected and is active.

The concept of an active/inactive area is relevant only when the participant completes the questionnaire. In that mode, it is the area currently in focus, and pressing the increase/decrease button selects/deselects the area, respectively.

When the participant answers the questionnaire, each area must also set up navigation to adjacent areas, specifying which area will be made active when the up, down, left, or right button is pressed. For each area, at least one button must be defined so the participant can’t get trapped and can't navigate away from the area.

Attributes

Name	Use	Description
id	required	Identification of the area [ string ]. This `id` must be unique.
colour	required	The colour that defines the area on the image [ string ]. Must be specified as a hex value #RRGGBB.
up	optional	Which area should be activated when the `up` button is pressed [ string ]. Must be the `id` of an area.
down	optional	Which area should be activated when the `down` button is pressed [ string ]. Must be the `id` of an area.
left	optional	Which area should be activated when the `left` button is pressed [ string ]. Must be the `id` of an area.
right	optional	Which area should be activated when the `right` button is pressed [ string ]. Must be the `id` of an area.

TextQuestionTemplate

The <text> question allows the participant or operator to provide a verbal free-form answer to a statement. The answer is in text that can be validated with a regular expression.

If the participant answers the question, the answer must be given verbally to the operator, who then enters it into the questionnaire. The operator's entered value will be displayed to the participant so they can confirm it is correct.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
maximal-length	optional	Maximal length of the answer [ int = Calculated(context) ].

Elements

Name	Use	Description
`<validation>`	optional	A text validator can guard against invalid text input. Text is validated with regular expressions. This tutorial, RegexLearn, teaches how to write regular expressions. When writing regular expressions, it is beneficial to procedure them with a suitable tool regex101.

TextValidatorTemplate

Attributes

Name	Use	Description
regex	required	The regular expression that are used to validate the text [ string ].
advice	required	An advice on how to write a correct text input [ string ].

BooleanQuestionTemplate

The <boolean> question asks a statement that can either be true or false. If the participant answers the question, the answer is selected with the up and down buttons.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
true-label	optional	Description of the true option [ dynamic string ].
false-label	optional	Description of the false option [ dynamic string ].

NumericalQuestionTemplate

The <numeric> question allows the participant or operator to provide a numerical answer to a statement. The answer can be validated to be within a given range.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<validation>`	optional	Validation that a number is within a given range.

NumberValidatorTemplate

Validation that a number is within a given range.

Attributes

Name	Use	Description
max	required	Maximal value for the number [ double ].
max-included	optional	Is the maximum included in the allowed range [ bool ].
min	required	Minimum value for the number [ double ].
min-included	optional	Is the minimum included in the allowed range [ bool ].

LikertQuestionTemplate

The <likert> question enables participants or operators to indicate their level of agreement, endorsement, or frequency using a Likert scale. A Likert scale is a symmetrically ordered set of response categories, from which a single option may be selected.

In LabBench, Likert scales are presented vertically. This vertical orientation allows for longer, more descriptive labels for response categories than horizontally displayed categorical rating scales. Participants select their response using the up and down button.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<choice>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

LikertChoiceTemplate

Definition of a response category on the Likert scale. Each response category is quantified by an integer value that corresponds to the Likert scale score if that category is selected.

Attributes

Name	Use	Description
value	required	Likert scale score if that category is selected [ int ].
label	required	Description of the category [ dynamic string ].

DimensionalLikertQuestionTemplate

The <dimensional-likert> question enables participants or operators to indicate their level of agreement, endorsement, or frequency using multiple Likert scales. A Likert scale is a symmetrically ordered set of response categories, from which a single option may be selected.

In LabBench, each Likert scale is presented horizontally. Participants select which Likert scale is active using the up and down buttons, and perform their rating with the increase and decrease buttons.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<dimension>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

LikertDimensionTemplate

An individual Likert scale on the multi-dimensional Likert scale question.

Attributes

Name	Use	Description
name	required	Description of the Likert scale [ dynamic string ].

Elements

Name	Use	Description
`<choice>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanListQuestionTemplate

The <list> question allows the participant or operator to provide answers to a set of statements, each of which can be true or false.

If the participant answers the question, the down and up buttons will navigate between questions, and pressing increase/decrease will set the answer to true/false, respectively.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<item>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanListItemTemplate

A statement that can either be true or false.

Attributes

Name	Use	Description
id	required	LabBench.Core.Procedures.Meta.Survey.Questions.BooleanListItem.ID
question	required	A statement that the participant or operator can answer is either true or false [ dynamic string ].

DateTimeQuestionTemplate

The <time> question allows the participant or operator to provide answers to a question when something occurred. The answer is in the form of a date and time.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

VisualAnalogScaleQuestionTemplate

The <visual-analogue-scale> question asks the participant or operator to rate a sensation on a visual analog rating scale. If the participant answers the question, the rating is increased/decreased by pressing the increase/decrease buttons, respectively.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
length	optional	Physical length of the scale in centimetres [ double ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

NumericalScaleQuestionTemplate

The <numerical-scale> question asks the participant or operator to rate a sensation on a numerical rating scale. If the participant answers the question, the rating is increased/decreased by pressing the increase/decrease buttons, respectively.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
maximum	required	The maximal value for the scale [ int ].
minimum	required	The minimum value for the scale [ int ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

CategoricalScaleQuestionTemplate

The <categorical-scale> question asks the participant or operator to rate a sensation on a categorical rating scale. If the participant answers the question, the rating is increased/decreased by pressing the increase/decrease buttons, respectively.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

Elements

Name	Use	Description
`<category>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

CategoryTemplate

Category definition.

Attributes

Name	Use	Description
value	required	Description that will be displayed to the participant [ dynamic string ].

AreaQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
selection-mode	optional	Area selection mode: `single`: one a single area can be selected. If an area is selected and another area is allready selected then the other area will be automatically deselected. `multiple`: multiple areas can be selected simultaneously.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

TextQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

BooleanQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

NumericalQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

LikertQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

DimensionalLikertQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

BooleanListQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

DateTimeQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

VisualAnalogScaleQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

NumericalScaleQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

CategoricalScaleQuestionConstructor

Construction of questions from templates

Attributes

Name	Use	Description
id	required	Identification of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the question [ string ].
title	optional	Title of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
instruction	optional	Instruction of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
condition	optional	Condition of the constructed question [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

QuestionConstructorForeach

Use a foreach loop with a template variable list to generate questions from templates programmatically.

Attributes

Name	Use	Description
variable	required	Variable name [ string ]. The `foreach` loop iterates over all values in the template variable list named by the `in` attribute, and for each iteration, the value is available in the variable named by the `variable` attribute.
in	required	Name of the template variable list to iterate over [ string ]. The attribute is named `in` to resemble the typical foreach programming construct `foreach (var n in variable)`.

Elements

Name	Use	Description
`<map>` `<text>` `<boolean>` `<numeric>` `<likert>` `<dimensional-likert>` `<list>` `<time>` `<visual-analogue-scale>` `<numerical-scale>` `<categorical-scale>` `<foreach>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SequentialProcedureTemplate

The sequential procedure makes it possible to use state machines to implement experimental procedures. Unlike most other procedures, it has no base functionality that can be configured in the LabBench Language; instead, its functionality must be implemented by a Python script that is called from its procedure events and state events.

In most cases, you will have access to instruments from the Python script to implement the intended experimental procedure. This access is provided by declaring the instruments in the <procedure-events> element. The instruments declared that they will be available for both the procedure events and state events.

The states in the state machine are defined in the <states> element, which also makes it possible to define which Python functions are called for the enter, leave, and update state events.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<update-rate-deterministic>` `<update-rate-random>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<states>`	required	Definition of the states in the state machine. The following state events define the functionality of these states: `enter`: a calculated attribute, that is executed when the state is entered. `leave`: a calculated attribute, that is executed when the state is left. `update`: a calculated attribute that is executed periodically. This attribute must return a string that controls whether the state machine will; "*") stay in the current state, State ID) go to the state with StateID, "abort") abort the procedure, "complete") complete the procedure. In the ProcedureContext `pc`, both procedure events and state events have access to a `pc.CurrentState` object that provides: `CurrentState.ID`: The State ID of the currently active state [ string(readonly)]. `CurrentState.RunningTime`: The running time in milliseconds of the currently active state [ int(readonly) ]. `CurrentState.Name`: Name of the currently active state [ string(readonly) ]. `CurrentState.Status`: A text that will be shown to the operator in the procedure window. Can be set by the events to provide information to the operator. `CurrentState.SetPlotter(lambda x, y)`: Events can set a Python function that must generate an image that will be shown to the operator in the procedure window.

DeterministicRateParameter

A determistic rate of procedure execution with a fixed period.

Attributes

Name	Use	Description
value	optional	Period of the procedure execution [ int = Calculated(tc) ].

UniformlyDistributedRateParameter

Active procedures are updated at regular intervals. This element defines an update interval that is randomly uniformly distributed between min and max.

Attributes

Name	Use	Description
min	optional	Minimum value for the update period [ double ].
max	optional	Maximal value for the update period [ double ].

SequentialProcedureStateCollectionTemplate

Definition of the states in the state machine. The following state events define the functionality of these states:

enter: a calculated attribute, that is executed when the state is entered.
leave: a calculated attribute, that is executed when the state is left.
update: a calculated attribute that is executed periodically. This attribute must return a string that controls whether the state machine will; "*") stay in the current state, State ID) go to the state with StateID, "abort") abort the procedure, "complete") complete the procedure.

In the ProcedureContext context, both procedure events and state events have access to a context.CurrentState object that provides:

CurrentState.ID: The State ID of the currently active state [ string(readonly)].
CurrentState.RunningTime: The running time in milliseconds of the currently active state [ int(readonly) ].
CurrentState.Name: Name of the currently active state [ string(readonly) ].
CurrentState.Status: A text that will be shown to the operator in the procedure window. Can be set by the events to provide information to the operator.
CurrentState.SetPlotter(lambda x, y): Events can set a Python function that must generate an image that will be shown to the operator in the procedure window.

Attributes

Name	Use	Description
enter	optional	Specifies code that will be executed when a state is entered [ bool = Calculated(context) ]. If False is returned, the procedure will be aborted.
leave	optional	Specifies code that will be executed when a state is left [ bool = Calculated(context) ]. If False is returned, the procedure will be aborted.
update	required	Specifies code that will be executed periodically while the procedure is active [ string = Calculated(context) ]. If text returned will control the next active state. How often the code is executed is controlled by the update rate of the procedure.

Elements

Name	Use	Description
`<state>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SequentialProcedureStateTemplate

Definition of a procedure state.

Attributes

Name	Use	Description
id	required	ID of the procedure state. Must be unique, and not one of the reserved keywords for state or procedure transitions. These keywoards are, *, abort, and complete.
name	optional	This optional attribute specifies a human readable name for the procedure state. If it is not specified the ID of the procedure state will be used instead.
experimental-setup-id	optional	This optional attribute, specifies the ID of the experimental setup that will be active will the procedure state is active. If none is specified the experimental setup for the procedure will be used instead.

StimulationSequenceProcedureTemplate

The <stimulation-sequence> procedure generates stimulus sequences for evoked potentials, behavioural tasks, or similar procedures. Construct the sequence by creating a stimulus pattern to control timing and a stimulus set to define which stimuli are delivered.

The stimulation pattern <stimulation-pattern>is constructed from a composition of sequences, which can be deterministic or random. However, to use this procedure, the stimulation pattern (number of stimuli and randomisation) is generated when the procedure starts. Consequently, it is not possible to change the stimulation pattern while the procedure is running, so it cannot depend on participant performance during the procedure. Use the <sequential> procedure if the stimulation pattern depends on the participant, as that procedure is more versatile but also more complex to implement than this stimulation sequence procedure.

The stimulation pattern is first generated, yielding a set of temporal stimulation slots that can be filled with stimuli; which stimuli are inserted into these stimulation slots is defined by the stimulus set <stimuli>. The stimuli set defines a set of stimuli and controls their randomisation. To fill the stimulation pattern, a batch of stimuli is first generated by the stimulus set. This batch of stimuli are inserted into the stimulation slots until all have been allocated, then a new batch is generated. This process is repeated until all stimulation slots have been allocated a stimulus.

The procedure delivers stimuli via the stimulation component, which, by default, uses the Stimulator and TriggerGenerator instruments to deliver stimuli and triggers, respectively. If more complex or multimodal stimuli are required, a <stimulation-scripts> can be defined to generate the stimuli/triggers from a Python script. When generations are done from a Python script, any visual, auditory or physical stimuli, and combinations thereof, that are possible with LabBench can be generated.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	optional	Update rate for stimulus generation [ int = Calculated(context) ].
trigger-update-rate	optional	Update rate for trigger generation [ int = Calculated(context) ]. If not defined, the stimulus generation update rate will be used.
response-collection	optional	Type of response collection that will be performed: `none`: no responses are collected for this procedure. `yes-no`: binary response collection using a button device. An `Button` instrument will need to be assigned to the procedure with a `<device-assignment>`. `ratio-rating`: continuous ratio-scale rating using a ratio scale device. An `RatioScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `numerical-rating`: numerical rating collection using an interval scale device. An `IntervalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `categorical-rating`: categorical response collection using an ordinal scale device. An `OrdinalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<stimulation-scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<stimulation-pattern>`	required	The `<stimulation-pattern>` element determines when stimuli are delivered. The pattern generates a set of time slots, each of which is either filled with stimuli from the `<stimuli>` set or with a pause. The stimulation pattern is generated from a composition of two types of sequences: `<sequence>`: a sequence with deterministic parameters. `<uniformly-distributed-sequence>`: a random sequence with an period that is uniformly distrubed between a minimum and maximal period. The time of a sequence is relative to the starting time of its parent sequence. If a sequence is root, meaning it has no parent, it is relative to time zero. For calcuated parameters the following variables will be in scope: `NumberOfStimuli`: Number of stimuli that will be generated by the `<stimuli>` element each time a new batch of stimuli is required.
`<stimuli>`	required	The `<stimuli>` defines a set of stimuli. These will be inserted into the time slots generated by the `<stimulation-pattern>`. The set consists of a series of `<stimulus>` elements. Each element may produce multiple stimuli based on its `count` attribute. The procedure supports randomisation of stimulation order based on the `order` attribute (`round-robin`, `random`, `block-random`, `latin-squares`, `generated`). Ensure that the number of stimulation time slots generated by the stimulation pattern is exactly divisible by the `NumberOfStimuli` in this element. Otherwise, any extra stimulation time slots that do not fit into a complete cycle defined by `NumberOfStimuli` will not be delivered. For calculated stimulus parameters and scripted stimulation, the stimulus `id` will be available as in the `StimulusName` variable. The currently active block is available in the `BlockNumber` variable.

ComponentConfiguration

Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.

Elements

Name	Use	Description
`<stimulation-generation>`	optional	Configuration of the stimulation start trigger
`<trigger-generation>`	optional	Configuration of the trigger generation start trigger

StimulationConfiguration

Configuration of the stimulation start trigger

Attributes

Name Use Description

trigger-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

TriggerConfiguration

Configuration of the trigger generation start trigger

Attributes

Name Use Description

trigger-source

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

ScriptedStimulationTemplate

Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.

Attributes

Name	Use	Description
initialize	optional	Calculated parameter that will be called when the procedure is started [ bool = Calculated(ts) ]. If False is returned, the procedure will be aborted; otherwise, it will be started.
stimulate	required	Calculated parameter that is called for each stimulation and which must implement the stimulation [ bool = Calculated(ts, x) ]. If False is returned, the procedure will be aborted.
stimulus-description	optional	Description of the stimulus.
stimulus-unit	optional	Unit for the stimulation modulity.

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulationPatternTemplate

The <stimulation-pattern> element determines when stimuli are delivered. The pattern generates a set of time slots, each of which is either filled with stimuli from the <stimuli> set or with a pause.

The stimulation pattern is generated from a composition of two types of sequences:

<sequence>: a sequence with deterministic parameters.
<uniformly-distributed-sequence>: a random sequence with an period that is uniformly distrubed between a minimum and maximal period.

The time of a sequence is relative to the starting time of its parent sequence. If a sequence is root, meaning it has no parent, it is relative to time zero.

For calcuated parameters the following variables will be in scope:

NumberOfStimuli: Number of stimuli that will be generated by the <stimuli> element each time a new batch of stimuli is required.

Attributes

Name Use Description

time-base

optional

Timebase for enclosing elements:

microseconds
milliseconds
seconds

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

DeterministicSequenceTemplate

Generate a deterministic sequence based on these parameters:

Iterations: indicates how many times to repeat the process for generating individual time slots. Each iteration produces one time slot inserted at a time according to the sequence attributes. If the 'Iterations' attribute is omitted, it defaults to 1.
Tperiod: The period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains.
Toffset: Time offset from the start of the sequence until insertion of the first time slot. Consequently, this attribute will offset all timeslots within the sequence.
stimulate: Fill the time slot with a stimulus.
pause: Insert a pause into the time slot.

Attributes

Name	Use	Description
iterations	optional	Number of sequence iterations [ double = Calculated(context) ]. For each sequence iteration, one time slot is generated.
stimulate	optional	Fill time slots with stimuli from the `<stimuli>` set [ bool ]. Please note that if `pause` is set to true, this attribute is ignored.
pause	optional	Fill time slots with pauses [ bool ]. Please note that this attribute will overrule the `stimulate` attribute.
Tperiod	optional	Period by which time slots are generated [ double = Calculated(context) ].
Toffset	optional	Time offset by which all generated time slots are delayed [ double = Calculated(context) ].

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

UniformlyDistributedSequenceTemplate

Generate a uniformly distributed sequence based on these parameters:

Iterations: indicates how many times to repeat the process for generating individual time slots. Each iteration produces one time slot inserted at a time according to the sequence attributes. If the 'Iterations' attribute is omitted, it defaults to 1.
maxTperiod: The maximal period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains. The period is uniformly distributed between minTperiod and maxTperiod.
minTperiod: The minimal period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains. The period is uniformly distributed between minTperiod and maxTperiod.
Toffset: Time offset from the start of the sequence until insertion of the first time slot. Consequently, this attribute will offset all timeslots within the sequence.
stimulate: Fill the time slot with a stimulus.
pause: Insert a pause into the time slot.

Attributes

Name	Use	Description
iterations	optional	Number of sequence iterations [ double = Calculated(context) ]. For each sequence iteration, one time slot is generated.
stimulate	optional	Fill time slots with stimuli from the `<stimuli>` set [ bool ]. Please note that if `pause` is set to true, this attribute is ignored.
pause	optional	Fill time slots with pauses [ bool ]. Please note that this attribute will overrule the `stimulate` attribute.
maxTperiod	required	Minimal value for the period [ double = Calculated(context) ]. The period is uniformly distributed between minTperiod and maxTperiod.
minTperiod	required	Maximal value for the period [ double = Calculated(context) ]. The period is uniformly distributed between minTperiod and maxTperiod.
Toffset	optional	Time offset by which all generated time slots are delayed [ double = Calculated(context) ].

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusSetTemplate

The <stimuli> defines a set of stimuli. These will be inserted into the time slots generated by the <stimulation-pattern>. The set consists of a series of <stimulus> elements. Each element may produce multiple stimuli based on its count attribute.

The procedure supports randomisation of stimulation order based on the order attribute (round-robin, random, block-random, latin-squares, generated). Ensure that the number of stimulation time slots generated by the stimulation pattern is exactly divisible by the NumberOfStimuli in this element. Otherwise, any extra stimulation time slots that do not fit into a complete cycle defined by NumberOfStimuli will not be delivered.

For calculated stimulus parameters and scripted stimulation, the stimulus id will be available as in the StimulusName variable. The currently active block is available in the BlockNumber variable.

Attributes

Name Use Description

order

optional

Method for generating a batch of stimuli from the stimulus set:

round-robin: stimuli are generated in the order they are defined in the stimulus set.
random: One batch of stimuli is generated such that the batch size matches the number of time slots to be filled. The stimuli in this batch are then randomised, ensuring that the order of stimulus presentation is fully randomized.
block-random: Multiple batches of stimuli are generated. Each batch contains all stimuli from the stimulus set (equal to the set size). After batch creation, the order of stimuli within each batch is randomised independently, meaning each batch is randomized but covers all stimuli.
latin-squares: Psydorandomisation of the stimulation order. Like block-random multiple batches, but each batch is pseudorandomized with Latin squares. Latin squares are a counterbalancing method that uses a Latin square design to ensure each condition appears equally often in each ordinal position across all stimulus batches, while still presenting the sequence in a seemingly random order.
generated: the order of the stimuli is implemented in Python. The Python function must return a list of length NumberOfStimuli that contains the order in which the current batch of stimuli will be ordered. The stimuli are identified in the returned list by their name.

generator

optional

Order by which the stimuli in a batch are reorganised when the order attribute is set to generated [ string[] = Calculated(context) ]. The list must be of length NumberOfStimuli and contain the names of the stimuli in the order they should be reordered.

Consequently, the generated order can only be used for <stimuli> sets for which all stimuli have their count set to one (1), as otherwise the stimulus names in the set are not unique.

Elements

Name	Use	Description
`<stimulus>` `<foreach>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusDeclarationConstructor

Definition of a stimulus in the stimulus set.

Attributes

Name	Use	Description
name	required	Name that will be used to identify the stimulus in results, calculated parameters, and Python scripts [ string ].
count	optional	Number of stimuli that will be generated from this stimulus declaration [ int = Calculated(context) ].
intensity	optional	Intensity (`x`) of that will be passed to the stimulus in calculated parameters [ double = Calculated(context) ].

Elements

Name Use Description

<triggers>

optional

Specifies a set of triggers to be generated. These triggers will all be generated with a given duration (duration) and delay (Tdelay). The delay is relative to the start time of its parent trigger sequence; if it has no parent trigger sequence, it is relative to time zero.

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

<stimulus>

optional

Definition of a stimulus.

TriggerDefinitionTemplate

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

TriggerSpecificationTemplate

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

Attributes

Name	Use	Description
Tdelay	optional	Trigger delay relative to the starting time of its parent sequence [ double = Calculated(context) ].
duration	required	Trigger duration [ double = Calculated(context) ].

Elements

Name	Use	Description
`<code>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

TriggerCodeTemplate

Trigger definitions that are defined by output and value. The output controls where the trigger is generated, and the value controls which trigger code is generated. The value attribute is optional and is default set to one (1).

Attributes

Name Use Description

output

required

Controls where a trigger will be delivered and what types of triggers can be generated:

trigger-output: Trigger OUT digital output. This output is a 1-bit trigger output, meaning that any trigger code different from zero will result in an active high output being
stimulator-trigger-output: Stimulator T digital output. This output is a 1-bit trigger output, meaning that any trigger code different from zero will result in an active high output being
trigger-interface: TRIGGER INTERFACE digital output. This is a 16-bit trigger output, meaning the trigger value will be generated.

Please note that the logic convention (positive/negative) applies only to the trigger-interface output; all other outputs use positive logic.

value

optional

Trigger code to be generated [ int = Calculated(context) ].

RepeatedTriggerSequenceTemplate

Repetition of enclosed triggers.

Attributes

Name	Use	Description
Tdelay	optional	The delay that the enclosed trigger sequence is delayed with before it is repeated `N` times with a period of `Tperiod` [ double = Calculated(context) ].
Tperiod	required	The period by which the enclosed triggers are repeated [ double = Calculated(context) ].
N	optional	The number of times the enclosed triggers are repeated [ int = Calculated(context) ].

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-trigger>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

CombinedTriggerSequenceTemplate

Generation of triggers from a composition of triggers and trigger sequences. The triggers of each enclosing trigger or trigger sequence will be merged together in time.

This will fail if the enclosed triggers or trigger sequences contain incompatible triggers, meaning that two or more distinct trigger codes are to be generated simultaneously on the same trigger output.

Attributes

Name	Use	Description
Tdelay	optional	Delay that all enclosed triggers are delayed with [ double = Calculated(context) ].

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusDefinitionTemplate

Definition of a stimulus.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>` `<multiple-outputs>` `<linear-segments>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

PulseTemplate

Rectangular stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity (Is) [ double = Calculated(context, x)].
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]

RampTemplate

A linearly increasing stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity (Is) is the change in the intensity at the end of the ramp from the stimulus offset (Ioffset) [ double = Calculated(context, x)].
Ioffset	optional	Stimulus intensity offset (Ioffset) is the value that all stimulus intensities during the stimulus are offset with [ double = Calculated(context, x)].
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]

SineTemplate

Sinusoidal stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity [ double = Calculated(context, x) ].
Ts	required	Stimulus duration in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay in milliseconds of the stimulus relative to its parent stimulus [ double = Calculated(context, x) ].
Frequency	required	Frequency of the sinusoidal stimulus [ double = Calculated(context, x) ].

ArbitraryTemplate

An arbitrary stimulus that is defined by a mathematical expression.

Attributes

Name	Use	Description
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]
expression	required	A mathematical expression that defines the stimulus. The expression must be a single-line Python statement that returns a double. In the scope of this expression are the current time (t) in milliseconds, a free parameter (x), a set of mathematical functions, and the results and definitions of the current protocol.

CombinedStimulusTemplate

A combined stimulus is the summation of a set of individual stimuli. The stimulus duration and delays of each stimulus in the set are relative to the combined stimulus's starting time.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

RepeatedStimulusTemplate

Repeats an enclosed stimulus.

Attributes

Name	Use	Description
Tdelay	optional	Delay in milliseconds of the repeated stimulus relative to its parent stimulus [ double = Calculated(context, x) ].
Tperiod	required	Period in milliseconds that the enclosed stimulus is repeated [ double = Calculated(context, x) ].
N	optional	Number of times the enclosed stimulus is repeated [ int = Calculated(context, x) ].

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

WindowTemplate

Window that gets multiplied on its enclosing stimuli.

Attributes

Name	Use	Description
window	required	Type of window that the enclosing stimulus is windowed with.
parameter	optional	Parameter if any of the window function.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

MultipleOutputStimulusTemplate

Represent a stimulus that spand over multiple stimulation outputs.

Elements

Name	Use	Description
`<output>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AnalogOutputTemplate

An analogue output channel in a multiple output stimulus.

Attributes

Name	Use	Description
channel	required	Number of the output channel. The stimulation device determines the meaning of this number.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

LinearSegmentsStimulusTemplate

A stimulus created from piecewise linear segments.

Attributes

Name	Use	Description
baseline	required	The baseline for the stimulus [ double = Calculated(context, x) ]. This baseline is the stimulus intensity outside the linear segments, and the starting value for the linear segments.

Elements

Name	Use	Description
`<segment>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SegmentTemplate

Definition of a segment of a piecewise-linear stimulus. The segment is defined by its duration and intensity at its end. Its starting intensity is defined by the end intensity of the previous segment or by the baseline intensity of the piecewise-linear stimulus.

Attributes

Name	Use	Description
duration	required	Duration of the segment in milliseconds [ double = Calculated(context, x) ].
value	required	End intensity of the segment [ double = Calculated(ts, x) ].

StimulusDeclarationConstructorForeach

Use a foreach loop with a template variable list to generate stimulus declarations from templates programmatically.

Example: Generate stimuli for a duration procedure using a foreach loop:

<stimuli>
    <foreach variable="duration" in="Durations">
        <stimulus name="var: f'S{duration}'">
            <stimulus>
                <pulse Is="x" Ts="var: f'{duration}'" />
            </stimulus>
        </stimulus>
    </foreach>
</stimuli>

When the template is used, the Durations list template variable is defined as in this example:

<stimulation-sequence-constructor id="T01" name="SR-Curve" template="SR">
    <variables>
        <strings name="Durations" value="50;100;200;400" />
    </variables>
</stimulation-sequence-constructor>

Attributes

Name	Use	Description
variable	required	Variable name [ string ]. The `foreach` loop iterates over all values in the template variable list named by the `in` attribute, and for each iteration, the value is available in the variable named by the `variable` attribute.
in	required	Name of the template variable list to iterate over [ string ]. The attribute is named `in` to resemble the typical foreach programming construct `foreach (var n in variable)`.

Elements

Name	Use	Description
`<stimulus>` `<foreach>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AlgometryStimulusResponseProcedureTemplate

Stimulus-response procedures determine the psychophysical rating (VAS Rating) to a linearly increasing pressure stimulus. From this stimulus-response curve, several psychophysical parameters can be determined:

PDT: The Pain Detection Threshold,
PTL: The Pain Tolerance Limit, and
PTT: The Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
vas-pdt	optional	The VAS score is interpreted as the Pain Detection Threshold (PDT) [ double = Calculated(context) ]. This attribute should be set to at least 0.1cm to allow for a small deadband in the button on the VAS meter, which is required so as not to risk that noise will accidentally trigger an early determination of the PDT. It can be set to higher than 0.1cm to allow for non-painful stimulations to be rated by the participant.
stop-mode	required	Stop mode for the procedure (stop-on-maximal-rating or stop-when-button-pressed). This attribute determines whether the VAS scale has two (2) or three anchor points (3). When set to stop-on-maximal-rating the VAS scale has two anchor points (pain detection threshold (PDT), pain tolerance threshold (PTT)). When set to stop-when-button-pressed the VAS scale has three anchor points (pain detection threshold (PDT), pain tolerance limit (PTL), pain tolerance threshold (PTT)).
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryConditionedPainProcedureTemplate

With the conditioned pain modulation procedure, one cuff applies static pressure while the other determines a stimulus-response curve. The stimulus-response curve determines the psychophysical rating (VAS Rating) to a linearly increasing pressure stimulus.

From this stimulus-response curve, several psychophysical parameters can be determined:

Pain Detection Threshold (PDT),
Pain Tolerance Limit (PTL),
Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
conditional-pressure	required	This attribute is the pressure that will be applied with the conditioning cuff [ double = Calculated(context) ].
delta-conditional-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied conditioning pressure [ double = Calculated(context) ].
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ y = Calculated(context) ].
vas-pdt	optional	The VAS score is interpreted as the Pain Detection Threshold (PDT) [ double = Calculated(context) ]. This attribute should be set to at least 0.1cm to allow for a small deadband in the button on the VAS meter, which is required so as not to risk that noise will accidentally trigger an early determination of the PDT. It can be set to higher than 0.1cm to allow for non-painful stimulations to be rated by the participant.
stop-mode	required	Stop mode for the procedure (stop-on-maximal-rating or stop-when-button-pressed). This attribute determines whether the VAS scale has two (2) or three anchor points (3). When set to stop-on-maximal-rating the VAS scale has two anchor points (pain detection threshold (PDT), pain tolerance threshold (PTT)). When set to stop-when-button-pressed the VAS scale has three anchor points (pain detection threshold (PDT), pain tolerance limit (PTL), pain tolerance threshold (PTT)).
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ double = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryTemporalSummationProcedureTemplate

The temporal summation procedure applies a series of rectangular pressure stimuli to one or both cuffs. The participant is asked to rate the pain sensation of these stimuli on the VAS meter as soon as possible after the cessation of a pressure stimulus. The VAS rating for a stimulus is recorded just before the next stimulus is given or would have been given if it had not been the last stimulus in the series.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
no-of-stimuli	optional	This attribute is the number of pressure stimuli applied during the procedure [ int = Calculated(context) ].
t-on	optional	This attribute is the duration of the rectangular stimuli [ double = Calculated(context) ].
t-off	optional	This attribute is the pause between the stimuli in the series [ double = Calculated(context) ].
pressure-stimulate	optional	This attribute is the pressure that will be applied during the rectangular pressure stimuli [ double = Calculated(context) ].
pressure-static	optional	This attribute is the pressure that will be applied in between the pressure stimuli [ double = Calculated(context) ]. This value is included as a slight static pressure between the stimuli can prevent the cuff from shifting during the procedure.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	optional	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryStaticTemporalSummationProcedureTemplate

The static temporal summation applies a constant pressure for a specified duration instead of a series of stimuli to determine the temporal summation of pressure stimulation.

During this pressure stimulation and for a period after the procedure, the participant's VAS score will be recorded as the result of the procedure.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
pressure-stimulate	optional	This attribute is the pressure that is applied during the static pressure stimulation [ double = Calculated(context) ].
stimulus-duration	optional	This attribute is the duration [s] of the constant pressure stimulation [ double = Calculated(context) ].
tail-duration	optional	This attribute is the duration after the cessation of the pressure stimulation in which the VAS score is recorded [ double = Calculated(context) ].
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	optional	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryStimulusRatingProcedureTemplate

The stimulus rating procedure provides a way to determine the Pain Detection Threshold (PDT), the Pain Tolerance Threshold (PTT), or both with an attached button.

The procedure is executed in the same way as the stimulus-response procedure and is defined by the same parameters, with the exception that it does not have a stop-mode parameter but instead has a measurement parameter.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].
measurement	required	Determine the Pain Detection Threshold (PDT), Pain Tolerance Threshold (PTT), or both. If the PDT or PTT is to be determined, the participant must press the button when the threshold is reached. If both the PDT and PTT are to be determined, the participant must press the button when the PDT is reached and release it when the PTT is reached.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryConditionedPainRatingProcedureTemplate

The conditioned pain modulation rating procedure is analogous to the conditioned pain modulation procedure that uses a button instead of the VAS to determine pain detection threshold (PDT), pain tolerance threshold (PTT), or both.

The same parameters define the procedure as the conditioned pain modulation procedure, with the addition of the measurement parameter that defines how the button is used to determine PDT, PTT, or both.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
conditional-pressure	required	This attribute is the pressure that will be applied with the conditioning cuff [ double = Calculated(context) ].
delta-conditional-pressure	optional	This attribute is the rate of increase [kPa/s] of the conditioning pressure [ double = Calculated(context) ].
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure. The maximal pressure for the device is 100kPa.
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ double = Calculated(context) ].
measurement	required	Determine the Pain Detection Threshold (PDT), Pain Tolerance Threshold (PTT), or both. If the PDT or PTT is to be determined, the participant must press the button when the threshold is reached. If both the PDT and PTT are to be determined, the participant must press the button when the PDT is reached and release it when the PTT is reached.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryArbitraryTemporalSummationProcedureTemplate

The arbitrary temporal summation procedure applies a series of rectangular pressure stimuli to one or both cuffs.

The participant is asked to rate the pain sensation of these stimuli on the VAS meter as soon as possible after the cessation of a pressure stimulus.

The VAS rating for a stimulus is recorded just before the next stimulus is given or would have been given if it had not been the last stimulus in the series. The arbitrary temporal summation procedure makes it possible to specify each stimulus in the series individually, and thus, each stimulus can have a different intensity and duration.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
pressure-static	optional	This attribute is the pressure that will be applied in between the pressure stimuli [ double = Calculated(context) ]. This value is included as a slight static pressure between the stimuli can prevent the cuff from shifting during the procedure.
second-cuff	optional	Inflate together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	required	Determines which cuff [1 or 2] that will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<stimuli>`	optional	The `<stimuli>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<stimulus>`

TemporalSummationStimulusTemplate

Specification of a pressure stimulus in the series of pressure stimuli.

Attributes

Name	Use	Description
pressure	required	Stimulation pressure [ double = Calculated(context) ].
t-on	required	Duration of the stimulus [ double = Calculated(context) ]
t-off	required	Pause between stimulations [ double = Calculated(context) ]

ThresholdEstimationProcedureTemplate

The threshold estimation procedure is used to estimate thresholds/psychometric functions when LabBench controls the stimulus generation automatically. Estimation of these thresholds/psychometric functions consists of three parts: the stimulus modality, response task, and estimation algorithm:

Stimulus modality: the type of stimulus, such as tactile, thermal, pressure, or electrical, presented to the participant and for which a threshold/psychometric function is estimated.
Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either true: the participant performed the task correctly, or false: the the participant failed to perform the task correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

The thresholds or psychometric functions are estimated for an independent variable (x). An increase in x is assumed to increase the probability that the participant will correctly perform the response task. If there is an inverted relationship, the independent variable (x) inversion must be performed in the stimulus specification.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	required	Update rate for stimulus generation [ int = Calculated(context) ].
trigger-update-rate	optional	Update rate for trigger generation [ int = Calculated(context) ]. If not defined, the stimulus generation update rate will be used.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<update-rate-deterministic>` `<update-rate-random>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<manual-yes-no-task>` `<yes-no-task>` `<forced-yes-no-task>` `<manual-interval-rating-task>` `<interval-rating-task>` `<manual-categorical-rating-task>` `<categorical-rating-task>` `<ratio-rating-task>` `<interval-forced-choice-task>` `<alternative-forced-choice-task>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<stimulation-scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<stimulus-channel-template>`	optional	A stimulus channel estimates the threshold or psychometric function of a single stimulus. This threshold or psychometric function is estimated with a dedicated estimation method (Psi-method, Up/Down method, and similar) that maintains its own state for the channel but uses the same response task to determine the relationship between a stimulus parameter (x) and the probabilistic behavioural response of the participants (i.e., whether they can perform the response task correctly). Once a threshold or psychometric function has been estimated, the result can be accessed by calculated parameters as `[ProcedureID].[ChannelID]`.
`<channels>`	optional	The `<channels>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<channel>` `<foreach>`

ManualYesNoResponseTemplate

In a Manual Yes/No response task, the experimenter asks the participant after each stimulation whether they felt the stimulus. This response is then entered into the algorithm manually by the experimenter. Consequently, the procedure will wait indefinitely until the participant has answered the experimenter.

Attributes

Name	Use	Description
instruction	required	Question that the experimenter must ask the participant that the participant must answer with either a Yes or No response [ string ].

YesNoResponseTemplate

In a Yes/No response task, the participant is asked to press the button each time a stimulus is felt. This response is timed, meaning that if the participant does not press the button before the next stimulus is given, then it will be assumed that the stimulus was not felt.

ForcedYesNoResponseTemplate

In the forced yes/no task, the stimulus is first presented to the participant, along with a cue that prompts the participant to attend to it.

Then a probe image is presented to the participant, with instructions to answer Yes or No to a stimulus quality; for example, if one or two stimuli could be felt, the participant presses one button for Yes and another for No. The task will wait indefinitely until the participant has answered the question.

This task is usually used for stimuli that are always felt but whose quality changes with increasing intensity. Examples of such stimuli are two-point stimuli or stimuli used to determine a just noticeable difference.

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to the Yes/No question [ Image = Calculated(context) ].
cue	required	Image that will be used to cue the participant to pay attention to the stimulus [ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of the cue and the display of the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].
yes-button	required	Button that the participant will use to indicate a Yes answer to the question [ Button ].
no-button	required	Button that the participant will use to indicate a No answer to the question [ Button ].

ManualIntervalResponseTemplate

In the Manual Interval Rating Task, the participant is asked to rate the stimuli's sensations on an interval rating scale by the experimenter. The participant provides this rating verbally, which the experimenter then manually enters into the algorithm. The response task will wait indefinitely until the experimenter has entered the participant's rating into the algorithm. If the participant rate exceeds the target, the response task is successful and returns True; otherwise, it returns False.

The Manual Interval Categorical Rating task is an example of a response task that enables determining the stimulus intensity required to evoke a supramaximal response, rather than determining the intensity required to evoke a threshold response, such as a perception or pain threshold.

Attributes

Name	Use	Description
instruction	optional	Question that the experimenter must ask to prompt the participant to rate the sensation on the interval rating scale [ string ].
target	required	Target rating for the response task [ int = Calculated(context) ].
minimum	optional	Minimum rating on the interval rating scale [ int ]. Default is 0.
maximum	optional	Maximal rating on the interval rating scale [ int ]. Default is 10.

IntervalResponseTemplate

In the Interval Rating Task, the participant is asked to rate the stimuli's sensations on an interval rating scale. If the participant rate exceeds the target, the response task is successful and returns True; otherwise, it returns False.

The Interval Rating task is an example of a response task that enables determining the stimulus intensity required to evoke a supramaximal response, rather than determining the intensity required to evoke a threshold response, such as a perception or pain threshold.

Attributes

Name	Use	Description
target	required	Target rating for the response task [ int = Calculated(context) ].

ManualCategoricalResponseTemplate

@Schema.Core.Procedures.Psychophysics.ThresholdEstimation.ResponseTasks.ManualCategoricalResponse.md

Attributes

Name	Use	Description
instruction	optional	Question that the experimenter must ask to prompt the participant to rate the sensation on the categorial rating scale [ string ].
target	required	Target rating for the response task [ int = Calculated(context) ].

Elements

Name	Use	Description
`<category>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ManualCategoryTemplate

In the Manual Categorial Rating Task, the participant is asked to rate the stimuli's sensations on a categorial rating scale by the experimenter. The participant provides this rating verbally, which the experimenter then manually enters into the algorithm. The response task will wait indefinitely until the experimenter has entered the participant 's rating into the algorithm. If the participant rate exceeds the target, the response task is successful and returns True; otherwise, it returns False.

The Manual Categorical Rating task is an example of a response task that enables determining the stimulus intensity required to evoke a supramaximal response, rather than determining the intensity required to evoke a threshold response, such as a perception or pain threshold.

Attributes

Name	Use	Description
text	required	Description of the category [ string. ]

CategoricalResponseTemplate

In the Categorial Rating Task, the participant is asked to rate the stimuli's sensations on a categorial rating scale. If the participant rate exceeds the target, the response task is successful and returns True; otherwise, it returns False.

The Categorical Rating task is an example of a response task that enables determining the stimulus intensity required to evoke a supramaximal response, in contrast to determining the intensity required to evoke a threshold response, such as a perception or pain threshold.

Attributes

Name	Use	Description
target	required	Target rating for the response task [ int = Calculated(context) ].

RatioResponseTemplate

In the Ratio Rating Task, the participant is asked to rate the stimuli's sensations on a ratio rating scale/visual analogue scale. If the participant rate exceeds the target, the response task is successful and returns True; otherwise, it returns False.

The Ratio Rating task is an example of a response task that enables determining the stimulus intensity required to evoke a supramaximal response, rather than determining the intensity required to evoke a threshold response, such as a perception or pain threshold.

Attributes

Name	Use	Description
target	required	Target rating for the response task [ int = Calculated(context) ].

IntervalForcedChoiceResponseTemplate

In an interval forced choice response task, the participant is presented with N time intervals in which the stimulus is given in one of them. The participant is asked to select the interval at which the stimulus was felt. If the participant can feel the stimulus, they will select the correct interval; if they cannot, they will have a 1/N chance to select the correct interval.

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to which stimulus interval the stimulus was presented when the cue was shown[ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of cues or the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].

Elements

Name	Use	Description
`<interval>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusInterval

Configuration of a stimulus interval. Stimuli will be generated for each stimulus interval in the order they are defined; when the stimulus is generated, the cue for that stimulus interval will be shown to the participant.

For each trial, one stimulus interval will be randomly selected as the one in which the stimulus is to be present. For that interval, the stimulus intensity (x) will be set to the current intensity determined by the estimation algorithm; for all other intervals, the stimulus intensity (x) will be set to Imin for the stimulus channel.

For calculated parameters, the currently active stimulus interval and selected stimulus interval are also available as the StimulusInterval and SelectedStimulusInterval parameters, respectively. These parameters contain the stimulus interval IDs.

Attributes

Name	Use	Description
id	required	ID of the stimulus interval [ string ].
image	required	Cue to be shown to participant in the stimulus interval [ Image = Calculated(context) ].
button	required	Button that the participant will use to indicate that the stimulus was present in the stimulus interval.

AlternativeForcedChoiceResponseTemplate

In an alternative forced choice response task, the participant is presented with one stimulus randomly selected from a set of N stimulus alternatives. Once the stimulus is complete, the participant will be asked to choose the given stimulus from the set of stimulus alternatives. If the participant can feel the stimulus, they will select the correct one; if they cannot, they will have a 1/N chance to select the correct stimulus.

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to which stimulus alternative was presented when the cue was shown[ Image = Calculated(context) ].
cue	required	Image that will be used to cue the participant to pay attention to the stimulus [ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of the cue and the display of the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].

Elements

Name	Use	Description
`<alternative>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusAlternativeTemplate

Configuration of a stimulus alternative where each is a different variant of the stimulus. For example, in a procedure that determines the just noticeable difference between three audible tones, there will be three different stimulus alternatives, for which either the first, middle, or last tone will be of a different intensity than the other tones.

For each trial, one stimulus alternative will be selected at random and presented to the participant. The selected one is available to calculated parameters in the StimulusAlternative parameter, whose value is the id attribute of the selected stimulus alternative.

Attributes

Name	Use	Description
id	required	Unique ID of the stimulus alternative [ string ].
button	required	Button that the participant will use to indicate if they felt this specific stimulus alternative.

StimulusChannelTemplate

A stimulus channel estimates the threshold or psychometric function of a single stimulus. This threshold or psychometric function is estimated with a dedicated estimation method (Psi-method, Up/Down method, and similar) that maintains its own state for the channel but uses the same response task to determine the relationship between a stimulus parameter (x) and the probabilistic behavioural response of the participants (i.e., whether they can perform the response task correctly).

Once a threshold or psychometric function has been estimated, the result can be accessed by calculated parameters as [ProcedureID].[ChannelID].

Attributes

Name	Use	Description
Imin	optional	Minimal stimulus intensity for the channel [ double = Calculated(context) ].
Imax	required	Maximal stimulus intensity for the channel [ double = Calculated(context) ].
confidence-level	optional	Confidence level when plotting estimated parameters for psychometric functions (alpha, beta, etc) [ double = Calculated(context) ].

Elements

Name	Use	Description
`<catch-trials>`	optional	Catch trials are intermittent trials in which the stimulus is presented at an unequivocally subthreshold level, allowing the experimenter to verify attention. By comparing responses on these impossible trials to their known correct outcomes, catch trials provide direct empirical estimates of guess rates, helping distinguish genuine perceptual limits from non-sensory errors.
`<psi-method>` `<up-down-method>` `<discrete-up-down-method>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

CatchTrialsTemplate

Catch trials are predefined control trials incorporated into an experimental protocol. These trials present either a stimulus with a known or obvious outcome or no stimulus, and serve to evaluate participant attention, task comprehension, and response compliance. Catch trials do not contribute to the primary experimental measurements.

Attributes

Name

Use

Description

order

required

Randomisation of the catch trial:

deterministic: Deterministic catch trials will occur with a fixed interval.
block-randomised: Block randomised will occur once within a block of interval number of stimuli.
randomised: Randomised catch trials will be generated with a probability of 1/interval.

interval

required

The interval, block-size, or probability with which the catch trial is generated [ int ].

PsiAlgorithmTemplate

This method implements the Psi method of Kontsevich & Tyler (1999). The Psi method is a Bayesian adaptive procedure that maintains a full joint posterior distribution over the threshold and slope of the psychometric function, while holding the guess and lapse rates fixed.

On each trial, the algorithm evaluates a set of candidate stimulus intensities and, for each one, computes the expected reduction in entropy of the current posterior if that stimulus were presented. It then selects the stimulus level that maximizes expected information gain, presents it to the observer, records the binary response, and updates the posterior via Bayes� rule.

This iterative cycle - predict information gain => choose optimal stimulus => observe response => update posterior - allows the method to rapidly converge on precise estimates of threshold and slope with high efficiency compared to traditional staircases or other adaptive schemes.

Attributes

Name	Use	Description
number-of-trials	required	Number of trials that are performed with the algorithm [ int = Calculated(context) ].

Elements

Name	Use	Description
`<quick>`	required	The psychometric function that links stimulus intensity to the probability of a correct or “yes” response, providing a quantitative model of perceptual sensitivity.
`<beta>`	required	The beta range specifies the set of slope values considered in the posterior distribution, constraining the possible steepnesses of the psychometric function that the algorithm can infer.
`<alpha>`	required	The alpha range defines the set of threshold values over which the algorithm computes and updates its posterior, effectively bounding the possible thresholds it can estimate.
`<intensity>`	required	The intensity range defines the allowable stimulus levels the algorithm can choose from on each trial when selecting the next, most informative stimulus.

PsychometricFunction

Psychometric function.

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

ArrayGeneratorTemplate

Generation of arrays.

Attributes

Name	Use	Description
type	required	Algorithm to use for the generation of values: linspace: the generated values are linearly spaced between the `x0` and `x1` values, both values included. A total of `n` values will be generated. logspace: the values are given as `x_n = base^xl_n`, where `xl_n` are the values of a `linspace` generated values. geomspace: the values are generated as a geometric progression between the `x0` and `x1` values, both values included. Consequently, each subsequent value `x_n + 1` is found as a common ratio `r` multiplied by the previous value `x_n`. The common ratio is calculated automatically, resulting in `n` values spaced geometrically between `x0` and `x1`. array: the values are generated from a calculated parameter [ double[] = Calculated(context) ].
n	optional	Number of samples to generate [ double = Calculated(context) ]. Value will be rounded down to nearest integer.
x0	optional	Starting value for the generated values [ double = Calculated(context) ].
x1	optional	End value for the generated values [ double = Calculated(context) ].
base	optional	Base value for logspace generated values [ double = Calculated(context) ].
value	optional	Value for array generated values [ double[] = Calculated(context) ].

UpDownAlgorithmTemplate

The up/down, also known as the staircase method, is an adaptive method that estimates a psychophysical threshold by increasing the intensity until the participant performs the response task correctly, then reversing the direction of intensity change and decreasing it until the participant fails to perform the response task correctly.

This pattern of increasing/decreasing the intensity until the participant either succeeds or fails the response task is repeated a set number of times. When complete, the algorithm finds the threshold as the average intensity at which the intensity change reversed, due to a change from failing (increasing threshold) to succeeding (decreasing threshold). The algorithm can be configured to either initially increase or decrease the intensity with the initial-direction attribute.

The step size of the intensity change can either be absolute or relative. If it is absolute, the step size is in the same unit as the intensity and changes the intensity by a fixed amount. If it is relative, its intensity changes by a given fraction of its current value. The step size can also be adaptive: initially higher to approach the threshold quickly, then decreasing with each reversal of the intensity change until a given maximal reduction is reached. When the step size is adaptive, the average will be weighted by the inverse of the step sizes.

Attributes

Name	Use	Description
reversal-rule	optional	The number of times the participants must either succeed or fail for the intensity change to change direction [int = Calculated(context)]. This attribute is used for both upward and downward directions unless either the `up-rule` or the `down-rule` is defined, respectively. The default value for this attribute is one (1).
up-rule	optional	The number of times the participants must succeed when the intensity is increased upward for the intensity change to change direction [int = Calculated(context)]. The default value for this attribute is one (1).
down-rule	optional	The number of times the participants must fail when the intensity is decreased upward for the intensity change to change direction [int = Calculated(context)]. The default value for this attribute is one (1).
step-size	optional	Will be used as the initial step size in both the up and down directions, unless the step-size-up or step-size-down is defined [double = Calculated(context)]. Default value is 0.1.
step-size-up	optional	Will be used as the initial step size in the upward direction [double = Calculated(context)]. If it is undefined, the step-size attribute will be used instead as the initial step size for the up direction.
step-size-down	optional	Will be used as the initial step size in the downward direction [double = Calculated(context)]. If it is undefined, the step-size attribute will be used instead as the initial step size for the downward direction.
step-size-reduction	optional	Used to configure adaptive step sizes [ double = Calculated(context) ]. The step size after a reversal will be `new-step-size` = (1 - `step-size-reduction`) * `old-step-size`. The default value is 0.5.
max-step-size-reduction	optional	The maximum by which step sizes will be reduced when adaptive step sizes are enabled by setting the `step-size-reduction` attribute to a non-zero value [ double = Calculated(context) ].
step-size-type	optional	Type of step size: absolute, the step size is added or subtracted to the current intensity, or relative, the step size is relative to the current intensity.
stop-rule	required	Number of reversals required before the algorithm is completed [ int = Calculated(context) ].
skip-rule	optional	The number of initial reversals that are skipped when calculating the threshold as the average of the intensity at the reversals [ int = Calculated(context) ]. Consequently, if this `skip-role` attribute is set to one (3) and the stop-rule is set to nine (9), the threshold will be calculated from the last six (6) reversals. The default value is zero (0).
start-intensity	required	Initial intensity for the algorithm [ double = Calculated(context) ].
initial-direction	optional	Initial direction for the intensity change.

Elements

Name	Use	Description
`<quick>`	optional	Psychometric function.

DiscreteUpDownAlgorithmTemplate

The up/down method, also known as the staircase method, is an adaptive method that estimates a psychophysical threshold by increasing the intensity until the participant performs the response task correctly, then reversing the direction of intensity change and decreasing it until the participant fails to perform the response task correctly. This discrete version of the method <discrete-up-down-method> is different from the continuous version of the method <up-down-method> in that stimulus intensities can only take on values from a discrete set of values instead of from a continuum of values between the minimum and maximum intensity values.

This pattern of increasing/decreasing the intensity until the participant either succeeds or fails the response task is repeated a set number of times. When complete, the algorithm finds the threshold as the average intensity at which the intensity change reverses, from failing (increasing threshold) to succeeding (decreasing threshold). The algorithm can be configured to either initially increase or decrease the intensity with the initial-direction attribute.

The index of the currently selected intensity is available to calculated parameters as the IntensityIndex variable.

Attributes

Name	Use	Description
stop-rule	required	Number of reversals required before the algorithm is completed [ int = Calculated(context) ].
initial-intensity	required	This attribute is used to select the initial intensity from the set of allowed intensities (‘intensities’) [ double = Calculated(context) ]. The initial intensity will be selected as the intensity in the set of allowed intensities closest to the value of this initial intensity attribute. If this attribute is not defined, the initial intensity will be set based on the initial direction. If the initial direction is upward, the smallest allowed intensity will be used; otherwise, the largest allowed intensity will be used.
intensities	required	The discrete set of allowed stimulus intensities in the form of an array of doubles [ double[] = Calculated(context) ]. These values must be ordered from the smallest to the largest and must be within the bounds of the Imin and Imax attributes for the stimulus channel.
initial-direction	optional	Initial direction for the intensity change.
initial-step-size	optional	Sets the initial step size [ int = Calculated(context) ]. The initial step size can be set to a value larger than one (1) to initially rapidly approach the threshold. Once a reversal has occurred, the step size will be set to one (1).
skip-rule	optional	The number of initial reversals that are skipped when calculating the threshold as the average of the intensity at the reversals [ int = Calculated(context) ]. Consequently, if this `skip-role` attribute is set to one (3) and the stop-rule is set to nine (9), the threshold will be calculated from the last six (6) reversals. The default value is zero (0).

StimulusChannelConstructor

Once a threshold or psychometric function has been estimated, the result can be accessed by calculated parameters as [ProcedureID].[ChannelID].

Attributes

Name	Use	Description
id	required	Unique ID of the stimulus channel [ string ].
name	required	Name of the channel [ string ].
Imin	optional	Minimal stimulus intensity for the channel [ double = Calculated(context) ].
Imax	optional	Maximal stimulus intensity for the channel [ double = Calculated(context) ].
confidence-level	optional	Confidence level when plotting estimated parameters for psychometric functions (alpha, beta, etc) [ double = Calculated(context) ].

Elements

Name	Use	Description
`<catch-trials>`	optional	Catch trials are intermittent trials in which the stimulus is presented at an unequivocally subthreshold level, allowing the experimenter to verify attention. By comparing responses on these impossible trials to their known correct outcomes, catch trials provide direct empirical estimates of guess rates, helping distinguish genuine perceptual limits from non-sensory errors.
`<psi-method>` `<up-down-method>` `<discrete-up-down-method>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<triggers>`	optional	Specifies a set of triggers to be generated. These triggers will all be generated with a given duration (`duration`) and delay (`Tdelay`). The delay is relative to the start time of its parent trigger sequence; if it has no parent trigger sequence, it is relative to time zero. A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested `<code>` element.
`<stimulus>`	optional	Definition of a stimulus.

StimulusChannelConstructorForeach

Use a foreach loop with a template variable list to generate stimulation channels from templates programmatically.

Attributes

Name	Use	Description
variable	required	Variable name [ string ]. The `foreach` loop iterates over all values in the template variable list named by the `in` attribute, and for each iteration, the value is available in the variable named by the `variable` attribute.
in	required	Name of the template variable list to iterate over [ string ]. The attribute is named `in` to resemble the typical foreach programming construct `foreach (var n in variable)`.

Elements

Name	Use	Description
`<stimulus>` `<foreach>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ColdPressorProcedureTemplate

The Cold Pressor procedure is a standardized experimental pain paradigm in which a participant immerses a hand or forearm in cold water to determine pain detection (PDT) and tolerance thresholds (PTT). The thresholds are measured as the time to pain onset and the time to pain tolerance.

The procedure can be configured to measure PDT, PTT, or both. When a single threshold is measured, time measurement is started with a button press when the hand is placed in the cold water and stopped with a second button press when the hand is withdrawn from the water. When both thresholds are measured, the second button press marks the PDT, and the third button press marks the PTT when the hand is withdrawn from the water.

While the procedure is designed for the Cold Pressor procedure, it can be used for any task for which detection and tolerance thresholds can be quantified by the time the participant experiences them. All instructions and descriptive texts can be customised to adapt the procedure for other tasks.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
control	optional	Configuration of who marks the events with a press of a button: the operator or the participant.
measurement	required	This attribute controls how the procedure interprets button presses and can be used to determine the PDT, PTT, or both: `pdt`: Determination of a detection threshold. `ptt`: Determination of a tolerance threshold. `both`: Determination of both a detection and tolerance threshold. For all measurements the first button press markes the start of the task.
time-limit	required	Time limit for the procedure in seconds [ double = Calculated(context) ]. If the end event has been marked within this time limit, the procedure will end automatically, and the participant will be marked as a non-responder.
button	required	Configuration of the button used to mark events during the procedure.
ready-instruction	optional	Instructions to be used when the procedure is ready to run [ dynamic procedure ]. The default text for this instruction is "Procedure is ready to run".
completed-instruction	optional	The default text for this instruction is "Procedure is completed".
pending-instruction	optional	Instructions to be used when the procedure is running and waiting for the first event to be marked [ dynamic string ]. For the cold-pressor procedure, the first event is when the participant’s hand is placed in the water. The default text for this instruction is "Press the button when the hand is placed in the water".
pain-instruction	optional	Instructions to be used when determining the pain detection threshold (PDT) [ dynamic string ]. This instruction applies to PDT and BOTH measurements. The default text for this instruction is "Press the button when pain is felt".
completion-instruction	optional	Instructions to be used for the final event [ dynamic string ]. For the cold-pressor procedure, this event is the withdrawal of the hand from the water. The default text for this instruction is "Press the button when the hand is withdrawn from the water".
pdt-label	optional	Label to be used for the PDT measurement [ dynamic string ]. The default value is cold pain detection threshold (CPD).
ptt-label	optional	Label to be used for the PTT measurement [ dynamic string ]. The default value is cold pain tolerance threshold (CPT)
non-responder-label	optional	Description of non-responders [ dynamic string ].
responder-label	optional	Description of responders [ dynamic string ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

ManualThresholdEstimationProcedureTemplate

The manual threshold estimation procedure is used to estimate thresholds/psychometric functions when LabBench cannot control the stimulus, and instead, the experimenter must manually apply the stimulus to the participant. Estimation of these thresholds/psychometric functions consists of two parts: response task and estimation algorithm:

Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either correct: the participant perceived the stimulus correctly, or incorrect: the stimulus intensity was too low, and the participant failed to perceive the stimulus correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

The stimulus is defined by the nature of the questions asked in the response task. The thresholds or psychometric functions are estimated for an independent variable (x). An increase in x is assumed to increase the probability that the participant will correctly perform the response task.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-unit	required

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<intensity-transformation>`	optional	The procedure instructs the experimenter which stimulus intensity to apply to the participant for each iteration of the estimation. For specific mechanical stimulators, there can be an offset between the scale that the experimenter uses to set the stimulus intensity and the actual intensity given by the stimulator to the participant. For example, when a custom-made two-point discriminator is made from a caliper, there might be a constant offset between the distance indicated on the caliper scale and the distance between the tips of the custom-made prongs attached to the caliper. The intensity-transformation allows the intensity displayed to the experimenter to be linearly transformed before it is shown to the experimenter, meaning that the experimenter will not need to apply this transformation mentally while following the procedure’s instructions.
`<catch-trials>`	optional	A catch trial is a trial in which no stimulus or the equivalent of no stimulus is presented.It is included to estimate the participant’s baseline tendency to respond positively without a stimulus.
`<psi-algorithm>` `<up-down-algorithm>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<yes-no-task>` `<two-interval-forced-choice-task>` `<one-interval-forced-choice-task>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

Transform

The procedure instructs the experimenter which stimulus intensity to apply to the participant for each iteration of the estimation.

For specific mechanical stimulators, there can be an offset between the scale that the experimenter uses to set the stimulus intensity and the actual intensity given by the stimulator to the participant. For example, when a custom-made two-point discriminator is made from a caliper, there might be a constant offset between the distance indicated on the caliper scale and the distance between the tips of the custom-made prongs attached to the caliper.

The intensity-transformation allows the intensity displayed to the experimenter to be linearly transformed before it is shown to the experimenter, meaning that the experimenter will not need to apply this transformation mentally while following the procedure's instructions.

Attributes

Name	Use	Description
a	optional	Slope (a) for the linear intensity transformation (y = ax + b) [ double ].
b	optional	Offset (b) for the linear intensity transformation (y = ax + b) [ double ].

ManualCatchTrialsTemplate

A catch trial is a trial in which no stimulus or the equivalent of no stimulus is presented.It is included to estimate the participant's baseline tendency to respond positively without a stimulus.

Attributes

Name	Use	Description
order	required	Randomisation of the catch trial: deterministic: Deterministic catch trials will occur with a fixed interval. block-randomised: Block randomised will occur once within a block of interval number of stimuli. randomised: Randomised catch trials will be generated with a probability of 1/interval.
interval	required	The interval, block-size, or probability with which the catch trial is generated [ int ].
image	optional	The image that is used to instruct the operator to perform a catch trial [ image = Calculated(context) ]
instruction	optional	The instruction used to inform the operator to perform a catch trial [ dynamic string ]

ManualPsiAlgorithmTemplate

The Psi Method, developed by Lenny Kontsevich and Christopher Tyler (1999), is a Bayesian adaptive psychometric procedure used to estimate perception thresholds and the shape of the psychometric function (like slope, lapse rate, etc.). It is more advanced than up/down staircases and offers greater efficiency and precision. The algorithm aims to estimate the full psychometric function for the perception of a stimulus instead of only determining a threshold. At each trial in the algorithm, a posterior probability distribution is maintained for the unknown parameters of the psychometric function (alpha, beta).

At each trial, the method will:

The posterior probability distributions for correct and incorrect results are calculated based on Bayes's Theorem from the a priori probability distribution (the posterior probability distribution from the previous step in the algorithm).
Determine the optimal stimulus intensity that reveals the most information on the unknown parameters of the psychometric function. This optimal procedure intensity is determined by minimizing the entropy based on Shannon entropy (H) calculated from the posterior probability distributions that will result from both a correct and incorrect response.
The response task (Yes/No, One Interval Forced Choice, or Two Interval Forced Choice) procedures the optimal stimulus intensity.
Depending on the participant's response to the response task, the posterior probability distribution for either the correct or incorrect response is selected as the a priori probability distribution for the next step in the algorithm.

Consequently, the algorithm will iteratively update its information on the most probable psychometric function. The algorithm is set to perform a fixed set of steps; thus, the execution time is known and fixed, in contrast to the Up/Down algorithm, whose execution time depends on the participant's responses.

Attributes

Name	Use	Description
intensities	required	Stimulation intensities [ double[] = Calculated(context) ].
intensity-labels	optional	When specified, labels provided by this attribute will be displayed instead of intensities [ string[] = Calculated(context) ]. The list of labels specified must have the same length as the list of intensities.
number-of-trials	required	Number of stimuli that will be presented to the participant [ int = Calculated(context) ].

Elements

Name	Use	Description
`<gumbel>` `<hyperbolic-secant>` `<logistics>` `<log-quick>` `<normal>` `<quick>` `<weibull>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<beta>`	required	Range of beta parameters.
`<alpha>`	required	Range of alpha parameters.

Gumbel

Gumbel Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

HyperbolicSecant

Hyperbolic Secant Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

Logistic

Logistic Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

LogQuick

Log-Quick Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

Normal

Normal Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

Quick

Quick Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

Weibull

Weibull Psychometric Function

Attributes

Name	Use	Description
alpha	optional	The alpha parameter of a psychometric function specifies its threshold, the stimulus intensity at which performance reaches a chosen criterion probability (i.e. 50% correct) [ double ].
beta	optional	The beta parameter of a psychometric function determines its slope, describing how rapidly response probability increases with stimulus intensity around the threshold [ double ].
lambda	optional	The lambda parameter of a psychometric function specifies the lapse rate, accounting for stimulus-independent errors by setting an upper performance bound below 100% [ double ].
gamma	optional	The gamma parameter of a psychometric function specifies the guess rate, representing the lower asymptote of performance due to chance-level responding.

ManualUpDownAlgorithmTemplate

The up/down algorithm, also known as the staircase method, is an adaptive method for estimating psychophysical minimal intensity (threshold) at which a participant perceives a stimulus with 50% reliability. The algorithm adjusts the intensity based on the participant's response; if the response is correct, the intensity is decreased (the stimulus becomes harder to perceive); if it is incorrect, the intensity is increased (the stimulus becomes easier to perceive).

The algorithm will initially either increase (initial-direction="increasing") or decrease (initial-direction="decreasing") the intensity from the lowest or highest possible intensity, respectively. It will continue to do so until the participant answers correctly or incorrectly, depending on the direction of intensity change, after which the direction of intensity change is reversed. At each reversal, the intensity is stored, and the threshold is calculated as the average of these intensities where the direction of intensity change was reversed.

Attributes

Name	Use	Description
intensities	required	Stimulation intensities [ double[] = Calculated(context) ].
intensity-labels	optional	When specified, labels provided by this attribute will be displayed instead of intensities [ string[] = Calculated(context) ]. The list of labels specified must have the same length as the list of intensities.
stop-rule	required	Number of intensity revarsel that must occur before the algorithm terminated [ int = Calculated(context) ].
initial-direction	optional	Initial direction of the intensity change [ increasing or decreasing ]. If not specified it is set to increasing.
initial-step-size	optional	Initial step size [ int = Calculated(context) ]. Once a intensity reversal have occured the step size will be set to one (1).
skip-rule	optional	Number of initial intensity reversal that will be discarded in the threshold calculation [ int = Calculated(context) ]. If not specified this attribute is set to zero.

ManualYesNoTaskTemplate

A Yes/No response task can be performed when the stimulus can elicit a positive response (Yes) or negative response (No). It is performed by asking the participant a question. For example, for a two-point discrimination procedure, "How many points did you feel touching the skin?" to which the participant can answer either "One" or "Two". In this example, if the participant answers Two, they correctly perceive the stimulus by answering positively.

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
task-illustration-image	required	The image that is used to illustrate the stimulation task for the operator [ image = Calculated(context) ]
positive-answer	required	The expected answer for positive responses [ dynamic string ].
negative-answer	required	The expected answer for negative responses [ dynamic string ].

ManualTwoIntervalForcedChoiceTaskTemplate

In a two-interval forced-choice task, the stimulus is presented in one of two time intervals. The participant is then asked to answer in which time interval the stimulus was presented. If the intensity makes it possible for the participant to perceive the stimulus, they will choose the correct interval. However, if the intensity is too low to be perceived, the participant will be forced to answer and will thus have a 50% chance of answering correctly. Consequently, the two-interval forced choice task is usually used with the Psi-Method, which can estimate psychometric functions for which the guess rate (gamma) is 50%.

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
no-stimulus-image	required	Image used to illustrate an interval where no stimulus should be presented [ image = Calculated(context) ].
stimulus-image	required	Image used to illustrate an interval where a stimulus should be presented [ image = Calculated(context) ].
interval-a	required	Name of interval A [ dynamic string ].
interval-b	required	Name of interval B [ dynamic string ].

ManualOneIntervalForcedChoiceTaskTemplate

In a one-interval forced-choice task, the participant is asked to choose between two alternatives based on the stimulus presented. If the intensity makes it possible for the participant to perceive the stimulus, they will choose the correct alternative. However, if the intensity is too low to be perceived, the participant will be forced to answer and will thus have a 50% chance of answering correctly. Consequently, the one-interval forced choice task is usually used with the Psi-Method, which can estimate psychometric functions for which the guess rate (gamma) is 50%.

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
alternative-a-image	required	Image used to demonstrate alternative A to the operator [ image = Calculated(context) ].
alternative-b-image	required	Image used to demonstrate alternative B to the operator [ image = Calculated(context) ].
alternative-a	required	Expected response when the participant can perceive alternative A [ dynamic string ].
alternative-b	required	Expected response when the participant can perceive alternative B [ dynamic string ].

ResponseRecordingProcedureTemplate

The response recording procedure allows for the collection of psychophysiological ratings over a specified time period or until the experimenter indicates a particular event. During this process, ratings can be recorded while also capturing a set of signals and/or marking events with predefined markers.

To function, the procedure must be assigned a Scales instrument in the device-mapping element of the experimental setup. The number and types of psychophysical ratings that are collected by the procedure are defined by the psychophysical rating scales that are defined in the Scales instrument.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
duration	required	Sample duration for the response recoding [ double = Calculated(context) ].
sample-rate	required	Sample rate for the response recording [ double = Calculated (context) ]. This sample rate is used both for the psychophysical responses and the defined signals if any.
response-weight	optional	Weight given to the psychophysical ratings in the user interface [ int ]. Default value is 1.
signal-weight	optional	Weight given to the recorded signals in the user interface [ int ]. Default value is 0.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<events-makers>`	optional	Used to define the markers that an experimenter can use to mark events while the procedure is running. Events could be events such as a pain detection or a pain tolerance threshold. Events are organised into event groups, where only one event group can be active at any time. When the experimenter marks an event, then the marker can be configured to activate another event group. Consequently, this can be used to define the sequential logical flow of events, such as enforcing that a pain detection threshold is always before a pain tolerance threshold. When the procedure is started, the first defined event group will be active.
`<signals>`	optional	Defines the signals that will be sampled simultaneously with the collection of psychophysiological ratings and the script that will be called for each recording time to sample the signals.

EventMarkerCollectionTemplate

Used to define the markers that an experimenter can use to mark events while the procedure is running. Events could be events such as a pain detection or a pain tolerance threshold. Events are organised into event groups, where only one event group can be active at any time. When the experimenter marks an event, then the marker can be configured to activate another event group. Consequently, this can be used to define the sequential logical flow of events, such as enforcing that a pain detection threshold is always before a pain tolerance threshold. When the procedure is started, the first defined event group will be active.

Elements

Name	Use	Description
`<group>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

EventMarkerGroupTemplate

Defines a group of events that are active simultaneously.

Attributes

Name	Use	Description
id	required	Unique identifier for the event group [ string ]. This identifier is used by event markers to identity the next active event group.

Elements

Name	Use	Description
`<marker>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

EventMarkerTemplate

Defines a marker for an event.

Attributes

Name	Use	Description
id	required	Unique identifier for the event marker [ string ].
name	optional	Name of the event [ dynamic string ]. If not specified the ID of the event will be used as its name.
complete	optional	Complete the procedure when the event is marked [ Boolean ]. Default value is false.
next-group	optional	Event group to activate when the event is marked [ string ]. This must be an ID of an event group, if no next-group is specified the currently active event group will remain active.

SignalGroupCollectionTemplate

Defines the signals that will be sampled simultaneously with the collection of psychophysiological ratings and the script that will be called for each recording time to sample the signals.

Attributes

Name	Use	Description
sample	required	This attribute specifies the script that will be used to sample the signals [ [double] = Calculated(context) ]. The script must return a list of the same length as the number of defined signals and in the same order.
min	required	Global minimum value for the sampled signals [ double = Calculated(context) ].
max	required	Global maximum value for the sampled signals [ double = Calculated(context) ].

Elements

Name	Use	Description
`<signal>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SignalDeclarationTemplate

Definition of a signal that will be sampled in the sample script that is defined as an attribute on the <signals> element. This sample script must return a list of values with the same length as the number of signals defined in the signals element.

Attributes

Name	Use	Description
id	required	Identifier for the signal [ string ]. This identifier must be unique for all the defined signals.
name	required	Name for the signal [ dynamic string ]. If no name is provided the ID of the signal will be used as its name.
type	optional	Type of signal that is sampled.
unit	optional	Unit of signal that is sampled [ string ].

StimulusPresentationProcedureTemplate

The Stimulus Presentation procedure allows a participant to become familiar with a stimulus and to rate its sensation on a psychophysical rating scale.

The procedure can also be used to manually find thresholds, as the last tested intensity is available in the calculated parameter [ProcedureID].Intensity upon completion.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	required	The update rate for the generated stimuli [ int = Calculated(context) ]. This update rate must be supported by the device that will deliver the stimuli.
trigger-update-rate	optional	The update rate for the generated triggers [ int = Calculated(context) ]. This update rate must be supported by the device that will deliver the stimuli, and if it is unspecified, the stimulus update rate will be used as the update rate for the trigger generation.

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<intensity>`	required	Specification of the intensities for the stimuli that the experimenter can choose during a session.
`<responses>`	optional	This element defines the response engine used by a procedure to collect behavioural or rating-based responses from the participant. The response engine supports multiple response modalities, including: Binary responses (yes/no, button presses) Numerical ratings (interval scales) Ratio ratings (continuous scales) Categorical ratings (ordinal scales) If no response collection mode is specified, the response engine is disabled and no response device is required for the procedure.
`<triggers>`	optional	Trigger generation.
`<stimulation>`	optional	Stimulation configuration that can either be delivered with a Stimulator instrument, or with any combination of instruments when the `´ element is defined.

ResponseEngineTemplate

This element defines the response engine used by a procedure to collect behavioural or rating-based responses from the participant.

The response engine supports multiple response modalities, including:

Binary responses (yes/no, button presses)
Numerical ratings (interval scales)
Ratio ratings (continuous scales)
Categorical ratings (ordinal scales)

If no response collection mode is specified, the response engine is disabled and no response device is required for the procedure.

Attributes

Name Use Description

response-collection

optional

Type of response collection that will be performed:

none: no responses are collected for this procedure.
yes-no: binary response collection using a button device. An Button instrument will need to be assigned to the procedure with a <device-assignment>.
ratio-rating: continuous ratio-scale rating using a ratio scale device. An RatioScale instrument will need to be assigned to the procedure with a <device-assignment>.
numerical-rating: numerical rating collection using an interval scale device. An IntervalScale instrument will need to be assigned to the procedure with a <device-assignment>.
categorical-rating: categorical response collection using an ordinal scale device. An OrdinalScale instrument will need to be assigned to the procedure with a <device-assignment>.

TriggerEngineTemplate

Trigger generation.

Attributes

Name Use Description

start-triggger

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

StimulationEngineTemplate

Stimulation configuration that can either be delivered with a Stimulator instrument, or with any combination of instruments when the `´ element is defined.

Attributes

Name Use Description

start-trigger

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<stimulus>`	optional	Definition of a stimulus.

ThermalRatedStimulationProcedureTemplate

The Thermal Rated Stimulation procedure allows a thermal stimulus to be delivered to a participant while simultaneously recording the participant's psychophysical rating of the sensation.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
response-collection	optional	Type of response collection that will be performed: `none`: no responses are collected for this procedure. `yes-no`: binary response collection using a button device. An `Button` instrument will need to be assigned to the procedure with a `<device-assignment>`. `ratio-rating`: continuous ratio-scale rating using a ratio scale device. An `RatioScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `numerical-rating`: numerical rating collection using an interval scale device. An `IntervalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `categorical-rating`: categorical response collection using an ordinal scale device. An `OrdinalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`.
sample-times	optional	Must return a list of the times the participant’s response should be sampled [ double[] = Calculated(context) ]. This attribute is only used if the `response-collection` is not set to `none`.
intensity	required	Intensity (`x`) that will be passed to the stimulus defined by the `<stimulus>` element [ double = Calculated(context) ].
minimal-display-temperature	optional	Used for displaying the thermal stimulus; it is the lower bound for the stimulation temperature [ double = Calculated(context) ].
maximal-display-temperature	optional	Used for displaying the thermal stimulus; it is the upper bound for the stimulation temperature [ double = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<stimulus>`	optional	Definition of a stimulus.

ThermalThresholdEstimationProcedureTemplate

The Thermal Threshold Estimation Procedure determines cold and heat thresholds by decreasing/increasing the temperature until the participants press a button. The temperature at the time of the button press is taken as the temperature threshold.

This procedure can be repeated a set number of times, and the threshold is taken as an average of the repeated threshold measurements.

Attributes

Name	Use	Description
id	required	Identifier for the template that must be unique within the protocol. This `id`is used to identify the procedure template from procedure constructors in the protocol.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
threshold-type	required	Configuration of the thermal threshold to be determined.
stimulation-rate	required	The rate of temperature change for the determination of thresholds [ double = Calculated(context) ].
maximal-temperature	required	Maximal temperature for the thermal stimulus [ double = Calculated(context) ]. Please note that this temperature is higher than the `neutral-temperature` for heat thresholds and lower for cold thresholds. This temperature must be within the output temperature range (`minimal-temperature` to `maximal-temperature`) of the Thermal Stimulator assigned to the procedure.
return-rate	required	Rate by which the temperature is returned to the neutral temperature once the threshold has been reached [ double = Calculated(context) ].
initial-stimulation-delay	required	Delay from start of the procedure in seconds to the start of the first threshold determination [ double = Calculated(context) ].
stimulation-interval	required	Interval between threshold determinations in seconds [ double = Calculated(context) ].
repetitions	required	Number of times the threshold is determined [ int = Calculated(context) ].

Elements

Name	Use	Description
`<variables>`	optional	Template variables are used to generate text and calculated parameter attributes in procedures. List procedure variables can also be iterated over in `<foreach>` loops and thus generate multiple procedures, each differing by an element in this list. An example of the generated of a procedure ID from a template variable: `id="var: f’B05{p}’"` The keyword `var:` instructs the procedure constructor to generate the value of the `id` programmatically from the Python expression in the code; the template variable is named `p`, which comes from the following for each loop: `<foreach variable="p" in="procedures">`
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

ProtocolAssetTemplates

Definition of assets that will be added to the protocol assets.

Elements

Name	Use	Description
`<file-asset>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Asset

File that is included in the Experiment Definition File and which can be referred to by its id.

Attributes

Name	Use	Description
id	optional	Identification of the file asset [ string ]. If this attribute is not set, the `id` will be its file name, excluding its extension.
file	required	File to include [ string ]. If the `id` is not set, the `id` will be its file name, excluding its extension.

Elements

Name Use Description

<localisation>

optional

Localisation of the file asset when multiple languages are defined in a <languages> element in the protocol.

<aliases>

optional

Zip files can be a convenient way to bundle content, such as images for visual stimuli, without requiring each file to be declared as an individual <file-asset>. Once included files within the archive can be accessed with the dot notation [AssetID].[FileNameWithoutExtension].

However, many workflows for creating visual stimuli, such as Open Office Impress → PDF → pandoc → png files, result in non-semantic filenames such as slide-1, slide-2, etc.

File aliases provide a mechanism for renaming zip file entries without manually or scriptually renaming the files after they are created using their chosen image generation workflow. When a file is looked up in a zip file asset, the lookup mechanism will first check if there is an alias for the given id of the asset. If there is, then the id will be replaced internally in the file asset manager by its alias. Consequently, it will then be possible to refer to a zip file entry as ParticipantInstructions instead of a non-semantic name such as slide-3.

AssetLocalizer

Localisation of the file asset when multiple languages are defined in a <languages> element in the protocol.

Elements

Name	Use	Description
`<language>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AssetLocalized

Files can be localized, meaning that if multiple languages are defined in the <languages> element in the protocol, different files can be used depending on the selected language when a session starts.

When an asset is loaded, it first checks whether there is a localized file for the active language code. If a localized file is found, then that file will be used instead of the file specified by the file attribute on the <file-asset> element.

Attributes

Name	Use	Description
code	required	This attribute is the language code (ISO 639) for which the asset is localized [ string ].
file	required	File to use for the localization [ string ].

AliasManager

However, many workflows for creating visual stimuli, such as Open Office Impress → PDF → pandoc → png files, result in non-semantic filenames such as slide-1, slide-2, etc.

Elements

Name	Use	Description
`<alias>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Alias

Definition of an alias for a file name used within zip archives.

Attributes

Name	Use	Description
replace	required	Name of the file within the zip archive [ string ]. The filename must be without its extension and path.
with	required	Alias to replace the filename with one that can be used in the rest of the protocol [ string ].

ProcedureCollection

The <procedures> element defines the procedures of the protocol. These can be directly defined in this element or constructed from procedure templates defined in the <templates> element.

Elements

Name	Use	Description
`<questionnaire>` `<stimulation-sequence>` `<sequential>` `<algometry-stimulus-response>` `<algometry-conditioned-pain-modulation>` `<algometry-temporal-summation>` `<algometry-static-temporal-summation>` `<algometry-stimulus-rating>` `<algometry-conditioned-pain-modulation-rating>` `<algometry-arbitrary-temporal-summation>` `<psychophysics-threshold-estimation>` `<psychophysics-cold-pressor>` `<psychophysics-manual-threshold-estimation>` `<psychophysics-response-recording>` `<psychophysics-stimulus-presentation>` `<thermal-rated-stimulation>` `<thermal-threshold-estimation>` `<questionnaire-constructor>` `<stimulation-sequence-constructor>` `<sequential-constructor>` `<algometry-stimulus-response-constructor>` `<algometry-conditioned-pain-modulation-constructor>` `<algometry-temporal-summation-constructor>` `<algometry-static-temporal-summation-constructor>` `<algometry-stimulus-rating-constructor>` `<algometry-conditioned-pain-modulation-rating-constructor>` `<algometry-arbitrary-temporal-summation-constructor>` `<psychophysics-threshold-estimation-constructor>` `<psychophysics-cold-pressor-constructor>` `<psychophysics-manual-threshold-estimation-constructor>` `<psychophysics-response-recording-constructor>` `<psychophysics-stimulus-presentation-constructor>` `<thermal-rated-stimulation-constructor>` `<thermal-threshold-estimation-constructor>` `<foreach>` `<sequence>` `<if>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

QuestionnaireProcedure

The questionnaire procedure allows either the operator or the participant to answer a set of questions. The questionnaire can consist of the following types of questions:

Boolean Questions: questions that have mutually exclusive binary answer, which usually consists of answering a true or false statement, but can also consist of dichotomies such as child/adult.
Numerical Questions: are questions that can be answered with numerical answers.
Text Questions: are questions that can be answered with either free or validated text.
Likert Questions: A scale that captures how strongly someone agrees, disagrees, or feels about a statement using a fixed set of ordered response options.
List Questions: A set of binary statements that each can be either true or false.
Time Questions: a date and time provided by the participant, entered by the operator.
Map Questions: is answered by marking one or more regions, such as areas on a body map.
Categorical Rating Questions: rating of a sensation on a categorical scale.
Numerical Rating Questions: rating of a sensation on a numerical scale.
Visual Rating Questions: rating of a sensation on a visual analog rating scale.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
progress-format	optional	Controls the progress information that is provided by the procedure: `none`: no progresss information is provided. `percentage`: progress is provided as the percentage of completed questions. `index`: progress is provided as [current question no] / [total number of questions].
control	optional	Sets whether the questionnaire is filled out by the operator or the participant: `operator`: answers are provided by the operator. `participant`: answers are provided by the participant. In this mode a Questionnaire instrument must be assigned to the procedure.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<question-events>`	optional	Definition of calculated parameters that are executed when the state of questions changes; this makes it possible to extend the functionality of the Questionnaire procedure with additional functionality implemented in Python.
`<content>`	optional	The `<content>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<map>` `<text>` `<boolean>` `<numeric>` `<likert>` `<dimensional-likert>` `<list>` `<time>` `<visual-analogue-scale>` `<numerical-scale>` `<categorical-scale>`

ProcedureEvents

Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure.

This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.

Attributes

Name	Use	Description
start	optional	Specifies code that will be executed when the procedure is started [ bool = Calculated(context) ]. If False is returned the procedure will be aborted.
complete	optional	Specifies code that will be executed when the procedure is completed [ bool = Calculated(context) ]. If False is returned the procedure will be aborted.
abort	optional	Specifies code that will be executed when the procedure is aborted [ bool = Calculated(context) ]. Please note this calculated attribute must always return True.
selected	optional	Specifies code that will be executed when the procedure is selected regardsless of its state [ bool = Calculated(context) ]. Please note if a selected state is defined this will override the code provided in this attribute.
selected-blocked	optional	Specifies code that will be executed when the procedure is selected and is in the blocked state [ bool = Calculated(context) ].
selected-ready	optional	Specifies code that will be executed when the procedure is selected and is in the ready state [ bool = Calculated(context) ].
selected-completed	optional	Specifies code that will be executed when the procedure is selected and is in the completed state [ bool = Calculated(context) ].
selected-excluded	optional	Specifies code that will be executed when the procedure is selected and is in the excluded state [ bool = Calculated(context) ].

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

DeviceDescription

Defines an instrument that is made available to the procedure or embedded python code, such as a Stimulator, Button, or RatioScale.

The name attribute identifies the instrument for referencing elsewhere in the code, while the interface attribute specifies the type of the instrument to be made available.

Attributes:

name: An optional escriptive name for the instrument (e.g., "ImageDisplay") [ string ]. If no name is specified the name will be inferred from its interface type, by removing the - from interface type and making it Camel Case (i.e. image-display becomes ImageDisplay)
interface: The insturment type to be provided (e.g., "image-display").

Attributes

Name	Use	Description
name	optional	Instrument name of the instrument. There must be a device assignment with that instrument name of the correct instrument type.
interface	required	The insturment type to be provided (e.g., `image-display`)

ProcedureProperties

Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.

Elements

Name	Use	Description
`<auto-start>`	optional	Start the procedure when it is selected automatically when the previous procedure in the protocol has been completed. The procedure is only started automatically if the completion of a previous procedure selects the procedure. It is not started automatically if the operator manually selects the procedure. This procedure property can be used to speed up the execution of protocols. The default value of this procedure property is "false," meaning procedures will not be automatically started.
`<auto-advance>`	optional	This element controls whether the next procedure in the protocol will be automatically selected when the current procedure is completed. The default value is "true," meaning the next procedure will be automatically selected.
`<time-constraint>`	optional	This element places a time constraint on when the procedure can be started based on either the start time or completion time of another procedure in the protocol. The time constraint can impose a minimum (min attribute is specified) or maximum time (max attribute is specified) that must elapse before the procedure can be started or a time window (both min and max attributes are specified) within which the time can be started.
`<instructions>`	optional	This element specifies instructions for the operator when the procedure is not running. They will be shown in the procedure window instead of the procedure-specific user interface.
`<participant-instructions>`	optional	This element specifies instructions for the participant. They will be shown on an ImageDisplay instrument that must be assigned to the procedure in a device assignment in the experimental setup.
`<next>`	optional	This attribute specifies the ID of the procedure that will be selected when the procedure is completed [ dynamic string ].
`<annotations>`	optional	Custom data that can be added to procedure results either in the experiment definition file (*.expx) or by Python code.

TimeConstraint

Attributes

Name	Use	Description
procedure-id	required	This attribute specifies the ID of the procedure to which the timing constraint is relative.
min	optional	If this attribute is specified, it specifies the minimum time to pass before the procedure can be started. If the max attribute is also specified, the timing constraint is a time window in which the procedure can only be started within the minimum (min attribute) and maximum (max attribute) time values.
max	optional	If this attribute is specified, it specifies the maximum time that the procedure can be started. If the min attribute is also specified, the timing constraint is a time window in which the procedure can only be started within the minimum (min attribute) and maximum (max attribute) time values.
notification	optional	This attribute controls whether a beep should be sounded when the timing constraint is satisfied.
time-reference	optional	This attribute specifies whether the timing constraint is relative to a procedure’s start or end (completion).

ProcedureInstructions

This element specifies instructions for the operator when the procedure is not running. They will be shown in the procedure window instead of the procedure-specific user interface.

Attributes

Name	Use	Description
start-instruction	optional	Tooltip for the start button [ dynamic string ]. If specified, this will override the default text.
override-results	optional	This attribute controls whether instructions will be shown instead of procedure results in the procedure window for completed procedures. If set to true, instructions will be shown instead of the procedure results [ Boolean (true/false) ]. The default value is false.
default	optional	Instructions that will be shown if instructions are not specified for the current procedure state [ IAsset = Calculated(context) ].
blocked	optional	Instructions that will be shown when the procedure is in its BLOCKED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ]
ready	optional	Instructions that will be shown when the procedure is in its READY state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].
excluded	optional	Instructions that will be shown when the procedure is in its EXCLUDED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].
completed	optional	Instructions that will be shown when the procedure is in its COMPLETED state. If this attribute is not specified, then the value of the default attribute will be shown instead [ IAsset = Calculated(context) ].

ParticipantInstructions

This element specifies instructions for the participant. They will be shown on an ImageDisplay instrument that must be assigned to the procedure in a device assignment in the experimental setup.

Attributes

Name	Use	Description
experimental-setup-id	required	This attribute specifies the experimental setup ID that will activate the assigned ImageDisplay [ string ]. This ID can be different from the experimental setup ID for the procedure in general and will only be activated when the procedure is not running.
default	optional	Instructions that will be shown if instructions are not specified for the current procedure state [ IAsset = Calculated(context) ].
blocked	optional	Instructions that will be shown when the procedure is in its BLOCKED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
ready	optional	Instructions that will be shown when the procedure is in its READY state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
excluded	optional	Instructions that will be shown when the procedure is in its EXCLUDED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.
completed	optional	Instructions that will be shown when the procedure is in its COMPLETED state [ IAsset = Calculated(context) ]. If this attribute is not specified, then the value of the default attribute will be shown instead.

ProcedureLink

Link to another procedure within the protocol.

Attributes

Name	Use	Description
id	required	Identification (`id`) of the procedure that is linked to [ dynamic string ].

ProcedureAnnotations

Custom data that can be added to procedure results either in the experiment definition file (*.expx) or by Python code.

Elements

Name	Use	Description
`<bool>` `<bools>` `<number>` `<numbers>` `<string>` `<strings>` `<integer>` `<integers>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanListValue

bool[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<bool>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

NumberValue

double

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Value [ double ].

NumberListValue

double[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<number>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StringValue

string

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Value [ string ].

StringListValue

string[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<text>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

IntegerValue

int

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].
value	required	Integer value [ int ].

IntegerListValue

int[]

Attributes

Name	Use	Description
name	optional	Name of the variable [ string ].

Elements

Name	Use	Description
`<number>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ProcedureDependency

Attributes

Name	Use	Description
id	required	Identifier (`id`) of the procedure that the current procedure depends on [ string ].
virtual	optional	Is it a virtual dependency [ bool ].

Condition

Makes it possible to exclude procedures based on the results of completed procedures.

Attributes

Name	Use	Description
expression	required	Condition on the execution of the procedure [ bool = Calculated(context) ]. If this calculated attribute is True the procedure will be included, otherwise it will be excluded.
help	required	This attribute must provide an explanation for why a procedure has been excluded [ dynamic string ].

QuestionEvents

Attributes

Name	Use	Description
start	optional	Called when a question is started [ bool = Calculated(context) ].
complete	optional	Called when a question is completed [ bool = Calculated(context) ].
changed	optional	Called when a the answer to a question is changed [ bool = Calculated(context) ].

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AreaQuestion

When participants answer the question, the following button functions must be defined in the button configuration:

up, down, left, right: are used to navigate between areas.
increase and decrease: are used to select/deselect areas.

If the assigned device also implements the Joystick instrument, joystick movement can be used to navigate between areas.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
image-map	optional	An image that will provide the areas that can be selected [ image = Calculated(context) ]. Each area must be uniformly colored with a single color, and an `<area>` element for that colour must be defined for that. The question will then replace that colour with either the selected-color, deselected-color, active-selected-color, or active-deselected-color, depending on whether that area is selected/deselected and active or inactive.
overlay-image	optional	An overlay image that will be added on top of the processed area image [ image = Calculated(context) ]. Consequently, this image can be used to add information and a decal to the area image. For the areas to be visible, all pixels that do not provide information or a decal must be transparent.
selected-colour	optional	The colour of areas that the participant have selected, but which is currently not active [ string ]. The colour must be specified in hex in the form of #RRGGBB.
deselected-colour	optional	The colour of areas that the participant has not selected and which are currently not active [ string ]. This colour is typically the same as the background colour of the image, meaning deselected/not active areas will not be colored. The colour must be specified in hex in the form of #RRGGBB.
active-selected-colour	optional	The colour of areas that are selected and active [ string ]. The colour must be specified in hex in the form of #RRGGBB. Please not that the concept of active/inactive areas is only used when the questionnaire is answered by the participant. If the operator answers the questionnaire then this attribute has no effect.
active-deselected-colour	optional	The colour of areas that are active but not selected [ string ]. The colour must be specified in hex in the form of #RRGGBB. Please not that the concept of active/inactive areas is only used when the questionnaire is answered by the participant. If the operator answers the questionnaire then this attribute has no effect.
selection-mode	optional	Area selection mode: `single`: one a single area can be selected. If an area is selected and another area is allready selected then the other area will be automatically deselected. `multiple`: multiple areas can be selected simultaneously.
initial-active-area	optional	Sets which area is initially active [ string ]. This must be the ID of an `<area>` element.

Elements

Name	Use	Description
`<area>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Area

deselected-colour: an area that is neither selected nor active.
selected-colour: an area that has been selected by the operator/participant but is not active.
active-deselected-colour: an area has not been selected and is active.
active-selected-colour: an area has been selected and is active.

Attributes

Name	Use	Description
id	required	Identification of the area [ string ]. This `id` must be unique.
colour	required	The colour that defines the area on the image [ string ]. Must be specified as a hex value #RRGGBB.
up	optional	Which area should be activated when the `up` button is pressed [ string ]. Must be the `id` of an area.
down	optional	Which area should be activated when the `down` button is pressed [ string ]. Must be the `id` of an area.
left	optional	Which area should be activated when the `left` button is pressed [ string ]. Must be the `id` of an area.
right	optional	Which area should be activated when the `right` button is pressed [ string ]. Must be the `id` of an area.

TextQuestion

The <text> question allows the participant or operator to provide a verbal free-form answer to a statement. The answer is in text that can be validated with a regular expression.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
maximal-length	optional	Maximal length of the answer [ int = Calculated(context) ].

Elements

Name	Use	Description
`<validation>`	optional	A text validator can guard against invalid text input. Text is validated with regular expressions. This tutorial, RegexLearn, teaches how to write regular expressions. When writing regular expressions, it is beneficial to procedure them with a suitable tool regex101.

BooleanQuestion

The <boolean> question asks a statement that can either be true or false. If the participant answers the question, the answer is selected with the up and down buttons.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
true-label	required	Description of the true option [ dynamic string ].
false-label	required	Description of the false option [ dynamic string ].

NumericalQuestion

The <numeric> question allows the participant or operator to provide a numerical answer to a statement. The answer can be validated to be within a given range.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<validation>`	optional	Validation that a number is within a given range.

NumberValidator

Validation that a number is within a given range.

Attributes

Name	Use	Description
max	optional	Maximal value for the number [ double ].
max-included	optional	Is the maximum included in the allowed range [ bool ].
min	optional	Minimum value for the number [ double ].
min-included	optional	Is the minimum included in the allowed range [ bool ].

LikertQuestion

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<choice>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

LikertChoice

Definition of a response category on the Likert scale. Each response category is quantified by an integer value that corresponds to the Likert scale score if that category is selected.

Attributes

Name	Use	Description
value	required	Likert scale score if that category is selected [ int ].
label	required	Description of the category [ dynamic string ].

DimensionalLikertQuestion

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<dimension>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

LikertDimension

An individual Likert scale on the multi-dimensional Likert scale question.

Attributes

Name	Use	Description
name	required	Description of the Likert scale [ dynamic string ].

Elements

Name	Use	Description
`<choice>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanListQuestion

The <list> question allows the participant or operator to provide answers to a set of statements, each of which can be true or false.

If the participant answers the question, the down and up buttons will navigate between questions, and pressing increase/decrease will set the answer to true/false, respectively.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

Elements

Name	Use	Description
`<item>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

BooleanListItem

A statement that can either be true or false.

Attributes

Name	Use	Description
id	required	Identification of the statement [ string ]. This `id` must be unique.
question	required	A statement that the participant or operator can answer is either true or false [ dynamic string ].

DateTimeQuestion

The <time> question allows the participant or operator to provide answers to a question when something occurred. The answer is in the form of a date and time.

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.

VisualAnalogScaleQuestion

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
length	optional	Physical length of the scale in centimetres [ double ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

NumericalScaleQuestion

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
maximum	required	The maximal value for the scale [ int ].
minimum	required	The minimum value for the scale [ int ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

CategoricalScaleQuestion

Attributes

Name	Use	Description
id	required	Identifier for the question [ string ]. This identifier must be unique and is used to reference the answer in calculated parameters and in exported data. The answer can be referenced in calculated parameters as `[ProcedureID].[QuestionID]`. The type of answer depends on the type of question. For example, the answer type for Boolean Questions is a bool, and a double for Numerical Questions.
title	optional	The title of the question [ dynamic string ].
instruction	optional	An instruction to the operator or participant on how to answer the question [ dynamic string ].
condition	optional	Places a condition on whether the question is asked [ bool = Calculated(context) ]. If the calculated parameter returns True, the question is asked; otherwise, it is skipped. Consequently, this attribute can be used to omit questions based on answers to previous questions or on the results of other procedures in the protocol.
top-anchor	required	Top anchor for the scale [ dynamic string ].
bottom-anchor	required	Bottom anchor for the scale [ dynamic string ].
active-colour	required	Colour for the active part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.
inactive-colour	required	Colour for the inactive part of the scale [ string ]. The string must encode a valid RGB colour value, either in hex as #RRGGBB or as a rgb(RRR,GGG,BBB). For the rgb() notation the colours are in base 10.

Elements

Name	Use	Description
`<category>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulationSequenceProcedure

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	optional	Update rate for stimulus generation [ int = Calculated(context) ].
trigger-update-rate	optional	Update rate for trigger generation [ int = Calculated(context) ]. If not defined, the stimulus generation update rate will be used.
response-collection	optional	Type of response collection that will be performed: `none`: no responses are collected for this procedure. `yes-no`: binary response collection using a button device. An `Button` instrument will need to be assigned to the procedure with a `<device-assignment>`. `ratio-rating`: continuous ratio-scale rating using a ratio scale device. An `RatioScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `numerical-rating`: numerical rating collection using an interval scale device. An `IntervalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `categorical-rating`: categorical response collection using an ordinal scale device. An `OrdinalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<stimulation-scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<stimulation-pattern>`	required	The `<stimulation-pattern>` element determines when stimuli are delivered. The pattern generates a set of time slots, each of which is either filled with stimuli from the `<stimuli>` set or with a pause. The stimulation pattern is generated from a composition of two types of sequences: `<sequence>`: a sequence with deterministic parameters. `<uniformly-distributed-sequence>`: a random sequence with an period that is uniformly distrubed between a minimum and maximal period. The time of a sequence is relative to the starting time of its parent sequence. If a sequence is root, meaning it has no parent, it is relative to time zero. For calcuated parameters the following variables will be in scope: `NumberOfStimuli`: Number of stimuli that will be generated by the `<stimuli>` element each time a new batch of stimuli is required.
`<stimuli>`	required	The `<stimuli>` defines a set of stimuli. These will be inserted into the time slots generated by the `<stimulation-pattern>`. The set consists of a series of `<stimulus>` elements. Each element may produce multiple stimuli based on its `count` attribute. The procedure supports randomisation of stimulation order based on the `order` attribute (`round-robin`, `random`, `block-random`, `latin-squares`, `generated`). Ensure that the number of stimulation time slots generated by the stimulation pattern is exactly divisible by the `NumberOfStimuli` in this element. Otherwise, any extra stimulation time slots that do not fit into a complete cycle defined by `NumberOfStimuli` will not be delivered. For calculated stimulus parameters and scripted stimulation, the stimulus `id` will be available as in the `StimulusName` variable. The currently active block is available in the `BlockNumber` variable.

ScriptedStimulation

Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.

Attributes

Name	Use	Description
initialize	optional	Calculated parameter that will be called when the procedure is started [ bool = Calculated(ts) ]. If False is returned, the procedure will be aborted; otherwise, it will be started.
stimulate	required	Calculated parameter that is called for each stimulation and which must implement the stimulation [ bool = Calculated(ts, x) ]. If False is returned, the procedure will be aborted.
stimulus-description	optional	Description of the stimulus.
stimulus-unit	optional	Unit for the stimulation modulity.

Elements

Name	Use	Description
`<instrument>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulationPattern

The stimulation pattern is generated from a composition of two types of sequences:

<sequence>: a sequence with deterministic parameters.
<uniformly-distributed-sequence>: a random sequence with an period that is uniformly distrubed between a minimum and maximal period.

The time of a sequence is relative to the starting time of its parent sequence. If a sequence is root, meaning it has no parent, it is relative to time zero.

For calcuated parameters the following variables will be in scope:

NumberOfStimuli: Number of stimuli that will be generated by the <stimuli> element each time a new batch of stimuli is required.

Attributes

Name Use Description

time-base

optional

Timebase for enclosing elements:

microseconds
milliseconds
seconds

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

DeterministicSequence

Generate a deterministic sequence based on these parameters:

Iterations: indicates how many times to repeat the process for generating individual time slots. Each iteration produces one time slot inserted at a time according to the sequence attributes. If the 'Iterations' attribute is omitted, it defaults to 1.
Tperiod: The period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains.
Toffset: Time offset from the start of the sequence until insertion of the first time slot. Consequently, this attribute will offset all timeslots within the sequence.
stimulate: Fill the time slot with a stimulus.
pause: Insert a pause into the time slot.

Attributes

Name	Use	Description
iterations	optional	Number of sequence iterations [ double = Calculated(context) ]. For each sequence iteration, one time slot is generated.
stimulate	optional	Fill time slots with stimuli from the `<stimuli>` set [ bool ]. Please note that if `pause` is set to true, this attribute is ignored.
pause	optional	Fill time slots with pauses [ bool ]. Please note that this attribute will overrule the `stimulate` attribute.
Tperiod	optional	Period by which time slots are generated [ double = Calculated(context) ].
Toffset	optional	Time offset by which all generated time slots are delayed [ double = Calculated(context) ].

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

UniformlyDistributedSequence

Generate a uniformly distributed sequence based on these parameters:

Iterations: indicates how many times to repeat the process for generating individual time slots. Each iteration produces one time slot inserted at a time according to the sequence attributes. If the 'Iterations' attribute is omitted, it defaults to 1.
maxTperiod: The maximal period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains. The period is uniformly distributed between minTperiod and maxTperiod.
minTperiod: The minimal period by which the sequence is repeated, meaning the time between the time slots that are generated by the sequence. If this attribute is omitted, the period will be automatically calculated based on the duration of the sequences it contains. The period is uniformly distributed between minTperiod and maxTperiod.
Toffset: Time offset from the start of the sequence until insertion of the first time slot. Consequently, this attribute will offset all timeslots within the sequence.
stimulate: Fill the time slot with a stimulus.
pause: Insert a pause into the time slot.

Attributes

Name	Use	Description
iterations	optional	Number of sequence iterations [ double = Calculated(context) ]. For each sequence iteration, one time slot is generated.
stimulate	optional	Fill time slots with stimuli from the `<stimuli>` set [ bool ]. Please note that if `pause` is set to true, this attribute is ignored.
pause	optional	Fill time slots with pauses [ bool ]. Please note that this attribute will overrule the `stimulate` attribute.
maxTperiod	required	Minimal value for the period [ double = Calculated(context) ]. The period is uniformly distributed between minTperiod and maxTperiod.
minTperiod	required	Maximal value for the period [ double = Calculated(context) ]. The period is uniformly distributed between minTperiod and maxTperiod.
Toffset	optional	Time offset by which all generated time slots are delayed [ double = Calculated(context) ].

Elements

Name	Use	Description
`<sequence>` `<uniformly-distributed-sequence>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusSet

Attributes

Name Use Description

order

optional

Method for generating a batch of stimuli from the stimulus set:

round-robin: stimuli are generated in the order they are defined in the stimulus set.
random: One batch of stimuli is generated such that the batch size matches the number of time slots to be filled. The stimuli in this batch are then randomised, ensuring that the order of stimulus presentation is fully randomized.
block-random: Multiple batches of stimuli are generated. Each batch contains all stimuli from the stimulus set (equal to the set size). After batch creation, the order of stimuli within each batch is randomised independently, meaning each batch is randomized but covers all stimuli.
latin-squares: Psydorandomisation of the stimulation order. Like block-random multiple batches, but each batch is pseudorandomized with Latin squares. Latin squares are a counterbalancing method that uses a Latin square design to ensure each condition appears equally often in each ordinal position across all stimulus batches, while still presenting the sequence in a seemingly random order.
generated: the order of the stimuli is implemented in Python. The Python function must return a list of length NumberOfStimuli that contains the order in which the current batch of stimuli will be ordered. The stimuli are identified in the returned list by their name.

generator

optional

Consequently, the generated order can only be used for <stimuli> sets for which all stimuli have their count set to one (1), as otherwise the stimulus names in the set are not unique.

Elements

Name	Use	Description
`<stimulus>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusDeclaration

Definition of a stimulus in the stimulus set.

Attributes

Name	Use	Description
name	required	Name that will be used to identify the stimulus in results, calculated parameters, and Python scripts [ string ].
count	optional	Number of stimuli that will be generated from this stimulus declaration [ int = Calculated(context) ].
intensity	optional	Intensity (`x`) of that will be passed to the stimulus in calculated parameters [ double = Calculated(context) ].

Elements

Name Use Description

<triggers>

optional

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

<stimulus>

optional

Definition of a stimulus.

TriggerDefinition

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

TriggerSpecification

A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested <code> element.

Attributes

Name	Use	Description
Tdelay	optional	Trigger delay relative to the starting time of its parent sequence [ double = Calculated(context) ].
duration	required	Trigger duration [ double = Calculated(context) ].

Elements

Name	Use	Description
`<code>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

TriggerCode

Attributes

Name Use Description

output

required

Controls where a trigger will be delivered and what types of triggers can be generated:

trigger-output: Trigger OUT digital output. This output is a 1-bit trigger output, meaning that any trigger code different from zero will result in an active high output being
stimulator-trigger-output: Stimulator T digital output. This output is a 1-bit trigger output, meaning that any trigger code different from zero will result in an active high output being
trigger-interface: TRIGGER INTERFACE digital output. This is a 16-bit trigger output, meaning the trigger value will be generated.

Please note that the logic convention (positive/negative) applies only to the trigger-interface output; all other outputs use positive logic.

value

optional

Trigger code to be generated [ int = Calculated(context) ].

RepeatedTriggerSequence

Repetition of enclosed triggers.

Attributes

Name	Use	Description
Tdelay	optional	The delay that the enclosed trigger sequence is delayed with before it is repeated `N` times with a period of `Tperiod` [ double = Calculated(context) ].
Tperiod	required	The period by which the enclosed triggers are repeated [ double = Calculated(context) ].
N	optional	The number of times the enclosed triggers are repeated [ int = Calculated(context) ].

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-trigger>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

CombinedTriggerSequence

Generation of triggers from a composition of triggers and trigger sequences. The triggers of each enclosing trigger or trigger sequence will be merged together in time.

Attributes

Name	Use	Description
Tdelay	optional	Delay that all enclosed triggers are delayed with [ double = Calculated(context) ].

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusDefinition

Definition of a stimulus.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>` `<multiple-outputs>` `<linear-segments>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

Pulse

Rectangular stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity (Is) [ double = Calculated(context, x)].
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]

Ramp

A linearly increasing stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity (Is) is the change in the intensity at the end of the ramp from the stimulus offset (Ioffset) [ double = Calculated(context, x)].
Ioffset	optional	Stimulus intensity offset (Ioffset) is the value that all stimulus intensities during the stimulus are offset with [ double = Calculated(context, x)].
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]

Sine

Sinusoidal stimulus.

Attributes

Name	Use	Description
Is	required	Stimulus intensity [ double = Calculated(context, x) ].
Ts	required	Stimulus duration in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay in milliseconds of the stimulus relative to its parent stimulus [ double = Calculated(context, x) ].
Frequency	required	Frequency of the sinusoidal stimulus [ double = Calculated(context, x) ].

Arbitrary

An arbitrary stimulus that is defined by a mathematical expression.

Attributes

Name	Use	Description
Ts	required	Duration of the stimulus in milliseconds [ double = Calculated(context, x) ].
Tdelay	optional	Delay of the stimulus in miliseconds [ double = Calculated(context, x) ]
expression	required	A mathematical expression that defines the stimulus. The expression must be a single-line Python statement that returns a double. In the scope of this expression are the current time (t) in milliseconds, a free parameter (x), a set of mathematical functions, and the results and definitions of the current protocol.

CombinedStimulus

A combined stimulus is the summation of a set of individual stimuli. The stimulus duration and delays of each stimulus in the set are relative to the combined stimulus's starting time.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

RepeatedStimulus

Repeats an enclosed stimulus.

Attributes

Name	Use	Description
Tdelay	optional	Delay in milliseconds of the repeated stimulus relative to its parent stimulus [ double = Calculated(context, x) ].
Tperiod	required	Period in milliseconds that the enclosed stimulus is repeated [ double = Calculated(context, x) ].
N	optional	Number of times the enclosed stimulus is repeated [ int = Calculated(context, x) ].

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

Window

Window that gets multiplied on its enclosing stimuli.

Attributes

Name	Use	Description
window	required	Type of window that the enclosing stimulus is windowed with.
parameter	optional	Parameter if any of the window function.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

MultipleOutputStimulus

Represent a stimulus that spand over multiple stimulation outputs.

Elements

Name	Use	Description
`<output>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AnalogOutput

An analogue output channel in a multiple output stimulus.

Attributes

Name	Use	Description
channel	required	Number of the output channel. The stimulation device determines the meaning of this number.

Elements

Name	Use	Description
`<pulse>` `<ramp>` `<sine>` `<arbitrary>` `<combined>` `<repeated>` `<window>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

LinearSegmentsStimulus

A stimulus created from piecewise linear segments.

Attributes

Name	Use	Description
baseline	required	The baseline for the stimulus [ double = Calculated(context, x) ]. This baseline is the stimulus intensity outside the linear segments, and the starting value for the linear segments.

Elements

Name	Use	Description
`<segment>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

Segment

Attributes

Name	Use	Description
duration	required	Duration of the segment in milliseconds [ double = Calculated(context, x) ].
value	required	End intensity of the segment [ double = Calculated(ts, x) ].

SequentialProcedure

The states in the state machine are defined in the <states> element, which also makes it possible to define which Python functions are called for the enter, leave, and update state events.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<update-rate-deterministic>` `<update-rate-random>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<states>`	required	Definition of the states in the state machine. The following state events define the functionality of these states: `enter`: a calculated attribute, that is executed when the state is entered. `leave`: a calculated attribute, that is executed when the state is left. `update`: a calculated attribute that is executed periodically. This attribute must return a string that controls whether the state machine will; "*") stay in the current state, State ID) go to the state with StateID, "abort") abort the procedure, "complete") complete the procedure. In the ProcedureContext `context`, both procedure events and state events have access to a `context.CurrentState` object that provides: `CurrentState.ID`: The State ID of the currently active state [ string(readonly)]. `CurrentState.RunningTime`: The running time in milliseconds of the currently active state [ int(readonly) ]. `CurrentState.Name`: Name of the currently active state [ string(readonly) ]. `CurrentState.Status`: A text that will be shown to the operator in the procedure window. Can be set by the events to provide information to the operator. `CurrentState.SetPlotter(lambda x, y)`: Events can set a Python function that must generate an image that will be shown to the operator in the procedure window.

SequentialProcedureStateCollection

Definition of the states in the state machine. The following state events define the functionality of these states:

enter: a calculated attribute, that is executed when the state is entered.
leave: a calculated attribute, that is executed when the state is left.
update: a calculated attribute that is executed periodically. This attribute must return a string that controls whether the state machine will; "*") stay in the current state, State ID) go to the state with StateID, "abort") abort the procedure, "complete") complete the procedure.

In the ProcedureContext context, both procedure events and state events have access to a context.CurrentState object that provides:

CurrentState.ID: The State ID of the currently active state [ string(readonly)].
CurrentState.RunningTime: The running time in milliseconds of the currently active state [ int(readonly) ].
CurrentState.Name: Name of the currently active state [ string(readonly) ].
CurrentState.Status: A text that will be shown to the operator in the procedure window. Can be set by the events to provide information to the operator.
CurrentState.SetPlotter(lambda x, y): Events can set a Python function that must generate an image that will be shown to the operator in the procedure window.

Attributes

Name	Use	Description
enter	optional	Specifies code that will be executed when a state is entered [ bool = Calculated(context) ]. If False is returned, the procedure will be aborted.
leave	optional	Specifies code that will be executed when a state is left [ bool = Calculated(context) ]. If False is returned, the procedure will be aborted.
update	required	Specifies code that will be executed periodically while the procedure is active [ string = Calculated(context) ]. If text returned will control the next active state. How often the code is executed is controlled by the update rate of the procedure.

Elements

Name	Use	Description
`<state>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SequentialProcedureState

Definition of a procedure state.

Attributes

Name	Use	Description
id	required	ID of the procedure state. Must be unique, and not one of the reserved keywords for state or procedure transitions. These keywoards are, *, abort, and complete.
name	optional	This optional attribute specifies a human readable name for the procedure state. If it is not specified the ID of the procedure state will be used instead.
experimental-setup-id	optional	This optional attribute, specifies the ID of the experimental setup that will be active will the procedure state is active. If none is specified the experimental setup for the procedure will be used instead.

AlgometryStimulusResponseProcedure

PDT: The Pain Detection Threshold,
PTL: The Pain Tolerance Limit, and
PTT: The Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
vas-pdt	optional	The VAS score is interpreted as the Pain Detection Threshold (PDT) [ double = Calculated(context) ]. This attribute should be set to at least 0.1cm to allow for a small deadband in the button on the VAS meter, which is required so as not to risk that noise will accidentally trigger an early determination of the PDT. It can be set to higher than 0.1cm to allow for non-painful stimulations to be rated by the participant.
stop-mode	required	Stop mode for the procedure (stop-on-maximal-rating or stop-when-button-pressed). This attribute determines whether the VAS scale has two (2) or three anchor points (3). When set to stop-on-maximal-rating the VAS scale has two anchor points (pain detection threshold (PDT), pain tolerance threshold (PTT)). When set to stop-when-button-pressed the VAS scale has three anchor points (pain detection threshold (PDT), pain tolerance limit (PTL), pain tolerance threshold (PTT)).
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryConditionedPainProcedure

From this stimulus-response curve, several psychophysical parameters can be determined:

Pain Detection Threshold (PDT),
Pain Tolerance Limit (PTL),
Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
conditional-pressure	required	This attribute is the pressure that will be applied with the conditioning cuff [ double = Calculated(context) ].
delta-conditional-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied conditioning pressure [ double = Calculated(context) ].
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ y = Calculated(context) ].
vas-pdt	optional	The VAS score is interpreted as the Pain Detection Threshold (PDT) [ double = Calculated(context) ]. This attribute should be set to at least 0.1cm to allow for a small deadband in the button on the VAS meter, which is required so as not to risk that noise will accidentally trigger an early determination of the PDT. It can be set to higher than 0.1cm to allow for non-painful stimulations to be rated by the participant.
stop-mode	required	Stop mode for the procedure (stop-on-maximal-rating or stop-when-button-pressed). This attribute determines whether the VAS scale has two (2) or three anchor points (3). When set to stop-on-maximal-rating the VAS scale has two anchor points (pain detection threshold (PDT), pain tolerance threshold (PTT)). When set to stop-when-button-pressed the VAS scale has three anchor points (pain detection threshold (PDT), pain tolerance limit (PTL), pain tolerance threshold (PTT)).
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ double = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryTemporalSummationProcedure

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
no-of-stimuli	optional	This attribute is the number of pressure stimuli applied during the procedure [ int = Calculated(context) ].
t-on	optional	This attribute is the duration of the rectangular stimuli [ double = Calculated(context) ].
t-off	optional	This attribute is the pause between the stimuli in the series [ double = Calculated(context) ].
pressure-stimulate	optional	This attribute is the pressure that will be applied during the rectangular pressure stimuli [ double = Calculated(context) ].
pressure-static	optional	This attribute is the pressure that will be applied in between the pressure stimuli [ double = Calculated(context) ]. This value is included as a slight static pressure between the stimuli can prevent the cuff from shifting during the procedure.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	optional	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryStaticTemporalSummationProcedure

The static temporal summation applies a constant pressure for a specified duration instead of a series of stimuli to determine the temporal summation of pressure stimulation.

During this pressure stimulation and for a period after the procedure, the participant's VAS score will be recorded as the result of the procedure.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
pressure-stimulate	optional	This attribute is the pressure that is applied during the static pressure stimulation [ double = Calculated(context) ].
stimulus-duration	optional	This attribute is the duration [s] of the constant pressure stimulation [ double = Calculated(context) ].
tail-duration	optional	This attribute is the duration after the cessation of the pressure stimulation in which the VAS score is recorded [ double = Calculated(context) ].
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	optional	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryStimulusRatingProcedure

The stimulus rating procedure provides a way to determine the Pain Detection Threshold (PDT), the Pain Tolerance Threshold (PTT), or both with an attached button.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
second-cuff	optional	Inflate the second cuff together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure [ double = Calculated(context) ]. The maximal pressure for the device is 100kPa.
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ int = Calculated(context) ].
measurement	required	Determine the Pain Detection Threshold (PDT), Pain Tolerance Threshold (PTT), or both. If the PDT or PTT is to be determined, the participant must press the button when the threshold is reached. If both the PDT and PTT are to be determined, the participant must press the button when the PDT is reached and release it when the PTT is reached.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryConditionedPainRatingProcedure

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
conditional-pressure	required	This attribute is the pressure that will be applied with the conditioning cuff [ double = Calculated(context) ].
delta-conditional-pressure	optional	This attribute is the rate of increase [kPa/s] of the conditioning pressure [ double = Calculated(context) ].
conditioning-time	optional	This attribute is the time from the procedure’s start until the pressure starts to increase linearly [ double = Calculated(context) ].
pressure-limit	optional	This attribute is the maximum pressure the device will deliver before it aborts the procedure. The maximal pressure for the device is 100kPa.
delta-pressure	optional	This attribute is the rate of increase [kPa/s] of the applied pressure [ double = Calculated(context) ].
primary-cuff	required	Determines which cuff (1 or 2) will be used for the pressure stimulation [ double = Calculated(context) ].
measurement	required	Determine the Pain Detection Threshold (PDT), Pain Tolerance Threshold (PTT), or both. If the PDT or PTT is to be determined, the participant must press the button when the threshold is reached. If both the PDT and PTT are to be determined, the participant must press the button when the PDT is reached and release it when the PTT is reached.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

AlgometryArbitraryTemporalSummationProcedure

The arbitrary temporal summation procedure applies a series of rectangular pressure stimuli to one or both cuffs.

The participant is asked to rate the pain sensation of these stimuli on the VAS meter as soon as possible after the cessation of a pressure stimulus.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
pressure-static	optional	This attribute is the pressure that will be applied in between the pressure stimuli [ double = Calculated(context) ]. This value is included as a slight static pressure between the stimuli can prevent the cuff from shifting during the procedure.
second-cuff	optional	Inflate together with the primary cuff [ bool ]. If this attribute is set to true, the value of the primary cuff parameter is irrelevant. Placing the two cuffs adjacent to each other can be used to study spatial summation.
primary-cuff	required	Determines which cuff [1 or 2] that will be used for the pressure stimulation [ int = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<stimuli>`	optional	The `<stimuli>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<stimulus>`

TemporalSummationStimulus

Specification of a pressure stimulus in the series of pressure stimuli.

Attributes

Name	Use	Description
pressure	required	Stimulation pressure [ double = Calculated(context) ].
t-on	required	Duration of the stimulus [ double = Calculated(context) ]
t-off	required	Pause between stimulations [ double = Calculated(context) ]

ThresholdEstimationProcedure

Stimulus modality: the type of stimulus, such as tactile, thermal, pressure, or electrical, presented to the participant and for which a threshold/psychometric function is estimated.
Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either true: the participant performed the task correctly, or false: the the participant failed to perform the task correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	required	Update rate for stimulus generation [ int = Calculated(context) ].
trigger-update-rate	optional	Update rate for trigger generation [ int = Calculated(context) ]. If not defined, the stimulus generation update rate will be used.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<update-rate-deterministic>` `<update-rate-random>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<manual-yes-no-task>` `<yes-no-task>` `<forced-yes-no-task>` `<manual-interval-rating-task>` `<interval-rating-task>` `<manual-categorical-rating-task>` `<categorical-rating-task>` `<ratio-rating-task>` `<interval-forced-choice-task>` `<alternative-forced-choice-task>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<stimulation-scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<channels>`	optional	The `<channels>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<channel>`

ManualYesNoResponse

Attributes

Name	Use	Description
instruction	optional	Question that the experimenter must ask the participant that the participant must answer with either a Yes or No response [ string ].

YesNoResponse

ForcedYesNoResponse

In the forced yes/no task, the stimulus is first presented to the participant, along with a cue that prompts the participant to attend to it.

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to the Yes/No question [ Image = Calculated(context) ].
cue	required	Image that will be used to cue the participant to pay attention to the stimulus [ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of the cue and the display of the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].
yes-button	required	Button that the participant will use to indicate a Yes answer to the question [ Button ].
no-button	required	Button that the participant will use to indicate a No answer to the question [ Button ].

ManualIntervalResponse

Attributes

Name	Use	Description
instruction	optional	Question that the experimenter must ask to prompt the participant to rate the sensation on the interval rating scale [ string ].
target	required	Target rating for the response task [ int = Calculated(context) ].
minimum	optional	Minimum rating on the interval rating scale [ int ]. Default is 0.
maximum	optional	Maximal rating on the interval rating scale [ int ]. Default is 10.

IntervalResponse

Attributes

Name	Use	Description
target	required	Target rating for the response task [ int = Calculated(context) ].

ManualCategoricalResponse

@Schema.Core.Procedures.Psychophysics.ThresholdEstimation.ResponseTasks.ManualCategoricalResponse.md

Attributes

Name	Use	Description
instruction	optional	Question that the experimenter must ask to prompt the participant to rate the sensation on the categorical rating scale [ string ].
target	required	Target rating for the response task [ int = Calculated(context) ].

Elements

Name	Use	Description
`<category>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

ManualCategory

Attributes

Name	Use	Description
text	required	Description of the category [ dynamic string ]

CategoricalResponse

Attributes

Name	Use	Description
target	required	Target rating for the response task [ int = Calculated(context) ].

RatioResponse

Attributes

Name	Use	Description
target	required	Target rating for the response task [ double = Calculated(context) ].

IntervalForcedChoiceResponse

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to which stimulus interval the stimulus was presented when the cue was shown[ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of cues or the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].

Elements

Name	Use	Description
`<interval>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AlternativeForcedChoiceResponse

Attributes

Name	Use	Description
probe	required	Image that will be used to probe the participant for an answer to which stimulus alternative was presented when the cue was shown[ Image = Calculated(context) ].
cue	required	Image that will be used to cue the participant to pay attention to the stimulus [ Image = Calculated(context) ].
display-duration	optional	The duration in milliseconds that the cue will be displayed to the participant [ int ].
display-interval	optional	The duration in milliseconds between the display of the cue and the display of the prompt [ int ]. The display-interval value must be greater than the display-duration value.
pause	optional	The delay in milliseconds between when the participant answered the question and the next stimulus is presented [ int ].

Elements

Name	Use	Description
`<alternative>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

StimulusAlternative

Attributes

Name	Use	Description
id	required	Unique ID of the stimulus alternative [ string ].
button	required	Button that the participant will use to indicate if they felt this specific stimulus alternative.

StimulusChannel

Once a threshold or psychometric function has been estimated, the result can be accessed by calculated parameters as [ProcedureID].[ChannelID].

Attributes

Name	Use	Description
id	required	Unique ID of the stimulus channel [ string ].
name	required	Name of the channel [ string ].
Imin	optional	Minimal stimulus intensity for the channel [ double = Calculated(context) ].
Imax	optional	Maximal stimulus intensity for the channel [ double = Calculated(context) ].
confidence-level	optional	Confidence level when plotting estimated parameters for psychometric functions (alpha, beta, etc) [ double = Calculated(context) ].

Elements

Name	Use	Description
`<catch-trials>`	optional	Catch trials are intermittent trials in which the stimulus is presented at an unequivocally subthreshold level, allowing the experimenter to verify attention. By comparing responses on these impossible trials to their known correct outcomes, catch trials provide direct empirical estimates of guess rates, helping distinguish genuine perceptual limits from non-sensory errors.
`<psi-method>` `<up-down-method>` `<discrete-up-down-method>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<triggers>`	optional	Specifies a set of triggers to be generated. These triggers will all be generated with a given duration (`duration`) and delay (`Tdelay`). The delay is relative to the start time of its parent trigger sequence; if it has no parent trigger sequence, it is relative to time zero. A trigger may generate a trigger on multiple digital outputs. Each output is specified with a nested `<code>` element.
`<stimulus>`	optional	Definition of a stimulus.

CatchTrials

Attributes

Name

Use

Description

order

required

Randomisation of the catch trial:

deterministic: Deterministic catch trials will occur with a fixed interval.
block-randomised: Block randomised will occur once within a block of interval number of stimuli.
randomised: Randomised catch trials will be generated with a probability of 1/interval.

interval

required

The interval, block-size, or probability with which the catch trial is generated [ int ].

PsiAlgorithm

Attributes

Name	Use	Description
number-of-trials	required	Number of trials that are performed with the algorithm [ int = Calculated(context) ].

Elements

Name	Use	Description
`<quick>`	required	The psychometric function that links stimulus intensity to the probability of a correct or “yes” response, providing a quantitative model of perceptual sensitivity.
`<beta>`	required	The beta range specifies the set of slope values considered in the posterior distribution, constraining the possible steepnesses of the psychometric function that the algorithm can infer.
`<alpha>`	required	The alpha range defines the set of threshold values over which the algorithm computes and updates its posterior, effectively bounding the possible thresholds it can estimate.
`<intensity>`	required	The intensity range defines the allowable stimulus levels the algorithm can choose from on each trial when selecting the next, most informative stimulus.

ArrayGenerator

Generation of arrays.

Attributes

Name	Use	Description
type	optional	Algorithm to use for the generation of values: linspace: the generated values are linearly spaced between the `x0` and `x1` values, both values included. A total of `n` values will be generated. logspace: the values are given as `x_n = base^xl_n`, where `xl_n` are the values of a `linspace` generated values. geomspace: the values are generated as a geometric progression between the `x0` and `x1` values, both values included. Consequently, each subsequent value `x_n + 1` is found as a common ratio `r` multiplied by the previous value `x_n`. The common ratio is calculated automatically, resulting in `n` values spaced geometrically between `x0` and `x1`. array: the values are generated from a calculated parameter [ double[] = Calculated(context) ].
n	optional	Number of samples to generate [ double = Calculated(context) ]. Value will be rounded down to nearest integer.
x0	optional	Starting value for the generated values [ double = Calculated(context) ].
x1	optional	End value for the generated values [ double = Calculated(context) ].
base	optional	Base value for logspace generated values [ double = Calculated(context) ].
value	optional	Value for array generated values [ double[] = Calculated(context) ].

UpDownAlgorithm

Attributes

Name	Use	Description
reversal-rule	optional	The number of times the participants must either succeed or fail for the intensity change to change direction [int = Calculated(context)]. This attribute is used for both upward and downward directions unless either the `up-rule` or the `down-rule` is defined, respectively. The default value for this attribute is one (1).
up-rule	optional	The number of times the participants must succeed when the intensity is increased upward for the intensity change to change direction [int = Calculated(context)]. The default value for this attribute is one (1).
down-rule	optional	The number of times the participants must fail when the intensity is decreased upward for the intensity change to change direction [int = Calculated(context)]. The default value for this attribute is one (1).
step-size	optional	Will be used as the initial step size in both the up and down directions, unless the step-size-up or step-size-down is defined [double = Calculated(context)]. Default value is 0.1.
step-size-up	optional	Will be used as the initial step size in the upward direction [double = Calculated(context)]. If it is undefined, the step-size attribute will be used instead as the initial step size for the up direction.
step-size-down	optional	Will be used as the initial step size in the downward direction [double = Calculated(context)]. If it is undefined, the step-size attribute will be used instead as the initial step size for the downward direction.
step-size-reduction	optional	Used to configure adaptive step sizes [ double = Calculated(context) ]. The step size after a reversal will be `new-step-size` = (1 - `step-size-reduction`) * `old-step-size`. The default value is 0.5.
max-step-size-reduction	optional	The maximum by which step sizes will be reduced when adaptive step sizes are enabled by setting the `step-size-reduction` attribute to a non-zero value [ double = Calculated(context) ].
step-size-type	optional	Type of step size: absolute, the step size is added or subtracted to the current intensity, or relative, the step size is relative to the current intensity.
stop-rule	optional	Number of reversals required before the algorithm is completed [ int = Calculated(context) ].
skip-rule	optional	The number of initial reversals that are skipped when calculating the threshold as the average of the intensity at the reversals [ int = Calculated(context) ]. Consequently, if this `skip-role` attribute is set to one (3) and the stop-rule is set to nine (9), the threshold will be calculated from the last six (6) reversals. The default value is zero (0).
start-intensity	required	Initial intensity for the algorithm [ double = Calculated(context) ].
initial-direction	optional	Initial direction for the intensity change.

Elements

Name	Use	Description
`<quick>`	optional	Psychometric function.

DiscreteUpDownAlgorithm

This pattern of increasing/decreasing the intensity until the participant either succeeds or fails the response task is repeated a set number of times. When complete, the algorithm finds the threshold as the average intensity at which the intensity change reverses, from failing (increasing threshold) to succeeding (decreasing threshold). The algorithm can be configured to either initially increase or decrease the intensity with the initial-direction attribute.

The index of the currently selected intensity is available to calculated parameters as the IntensityIndex variable.

Attributes

Name	Use	Description
stop-rule	required	Number of reversals required before the algorithm is completed [ int = Calculated(context) ].
initial-intensity	required	This attribute is used to select the initial intensity from the set of allowed intensities (‘intensities’) [ double = Calculated(context) ]. The initial intensity will be selected as the intensity in the set of allowed intensities closest to the value of this initial intensity attribute. If this attribute is not defined, the initial intensity will be set based on the initial direction. If the initial direction is upward, the smallest allowed intensity will be used; otherwise, the largest allowed intensity will be used.
intensities	required	The discrete set of allowed stimulus intensities in the form of an array of doubles [ double[] = Calculated(context) ]. These values must be ordered from the smallest to the largest and must be within the bounds of the Imin and Imax attributes for the stimulus channel.
initial-direction	optional	Initial direction for the intensity change.
initial-step-size	optional	Sets the initial step size [ int = Calculated(context) ]. The initial step size can be set to a value larger than one (1) to initially rapidly approach the threshold. Once a reversal has occurred, the step size will be set to one (1).
skip-rule	optional	The number of initial reversals that are skipped when calculating the threshold as the average of the intensity at the reversals [ int = Calculated(context) ]. Consequently, if this `skip-role` attribute is set to one (3) and the stop-rule is set to nine (9), the threshold will be calculated from the last six (6) reversals. The default value is zero (0).

ColdPressorProcedure

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
control	optional	Configuration of who marks the events with a press of a button: the operator or the participant.
measurement	required	This attribute controls how the procedure interprets button presses and can be used to determine the PDT, PTT, or both: `pdt`: Determination of a detection threshold. `ptt`: Determination of a tolerance threshold. `both`: Determination of both a detection and tolerance threshold. For all measurements the first button press markes the start of the task.
time-limit	required	Time limit for the procedure in seconds [ double = Calculated(context) ]. If the end event has been marked within this time limit, the procedure will end automatically, and the participant will be marked as a non-responder.
button	required	Configuration of the button used to mark events during the procedure.
ready-instruction	optional	Instructions to be used when the procedure is ready to run [ dynamic procedure ]. The default text for this instruction is "Procedure is ready to run".
completed-instruction	optional	The default text for this instruction is "Procedure is completed".
pending-instruction	optional	Instructions to be used when the procedure is running and waiting for the first event to be marked [ dynamic string ]. For the cold-pressor procedure, the first event is when the participant’s hand is placed in the water. The default text for this instruction is "Press the button when the hand is placed in the water".
pain-instruction	optional	Instructions to be used when determining the pain detection threshold (PDT) [ dynamic string ]. This instruction applies to PDT and BOTH measurements. The default text for this instruction is "Press the button when pain is felt".
completion-instruction	optional	Instructions to be used for the final event [ dynamic string ]. For the cold-pressor procedure, this event is the withdrawal of the hand from the water. The default text for this instruction is "Press the button when the hand is withdrawn from the water".
pdt-label	optional	Label to be used for the PDT measurement [ dynamic string ]. The default value is cold pain detection threshold (CPD).
ptt-label	optional	Label to be used for the PTT measurement [ dynamic string ]. The default value is cold pain tolerance threshold (CPT)
non-responder-label	optional	Description of non-responders [ dynamic string ].
responder-label	optional	Description of responders [ dynamic string ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

ManualThresholdEstimationProcedure

Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either correct: the participant perceived the stimulus correctly, or incorrect: the stimulus intensity was too low, and the participant failed to perceive the stimulus correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-unit	required	Stimulus unit [ string ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<intensity-transformation>`	optional	The procedure instructs the experimenter which stimulus intensity to apply to the participant for each iteration of the estimation. For specific mechanical stimulators, there can be an offset between the scale that the experimenter uses to set the stimulus intensity and the actual intensity given by the stimulator to the participant. For example, when a custom-made two-point discriminator is made from a caliper, there might be a constant offset between the distance indicated on the caliper scale and the distance between the tips of the custom-made prongs attached to the caliper. The intensity-transformation allows the intensity displayed to the experimenter to be linearly transformed before it is shown to the experimenter, meaning that the experimenter will not need to apply this transformation mentally while following the procedure’s instructions.
`<catch-trials>`	optional	A catch trial is a trial in which no stimulus or the equivalent of no stimulus is presented.It is included to estimate the participant’s baseline tendency to respond positively without a stimulus.
`<psi-algorithm>` `<up-down-algorithm>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.
`<yes-no-task>` `<two-interval-forced-choice-task>` `<one-interval-forced-choice-task>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

ManualCatchTrials

A catch trial is a trial in which no stimulus or the equivalent of no stimulus is presented.It is included to estimate the participant's baseline tendency to respond positively without a stimulus.

Attributes

Name	Use	Description
order	required	Randomisation of the catch trial: deterministic: Deterministic catch trials will occur with a fixed interval. block-randomised: Block randomised will occur once within a block of interval number of stimuli. randomised: Randomised catch trials will be generated with a probability of 1/interval.
interval	required	The interval, block-size, or probability with which the catch trial is generated [ int ].
image	optional	The image that is used to instruct the operator to perform a catch trial [ image = Calculated(context) ]
instruction	optional	The instruction used to inform the operator to perform a catch trial [ dynamic string ]

ManualPsiAlgorithm

At each trial, the method will:

The posterior probability distributions for correct and incorrect results are calculated based on Bayes's Theorem from the a priori probability distribution (the posterior probability distribution from the previous step in the algorithm).
Determine the optimal stimulus intensity that reveals the most information on the unknown parameters of the psychometric function. This optimal procedure intensity is determined by minimizing the entropy based on Shannon entropy (H) calculated from the posterior probability distributions that will result from both a correct and incorrect response.
The response task (Yes/No, One Interval Forced Choice, or Two Interval Forced Choice) procedures the optimal stimulus intensity.
Depending on the participant's response to the response task, the posterior probability distribution for either the correct or incorrect response is selected as the a priori probability distribution for the next step in the algorithm.

Attributes

Name	Use	Description
intensities	required	Stimulation intensities [ double[] = Calculated(context) ].
intensity-labels	optional	When specified, labels provided by this attribute will be displayed instead of intensities [ string[] = Calculated(context) ]. The list of labels specified must have the same length as the list of intensities.
number-of-trials	required	Number of stimuli that will be presented to the participant [ int = Calculated(context) ].

Elements

Name	Use	Description
`<quick>`	required	Psychometric function.
`<beta>`	required	Range of beta parameters.
`<alpha>`	required	Range of alpha parameters.

ManualUpDownAlgorithm

Attributes

Name	Use	Description
intensities	required	Stimulation intensities [ double[] = Calculated(context) ].
intensity-labels	optional	When specified, labels provided by this attribute will be displayed instead of intensities [ string[] = Calculated(context) ]. The list of labels specified must have the same length as the list of intensities.
stop-rule	required	Number of intensity revarsel that must occur before the algorithm terminated [ int = Calculated(context) ].
initial-direction	optional	Initial direction of the intensity change [ increasing or decreasing ]. If not specified it is set to increasing.
initial-step-size	optional	Initial step size [ int = Calculated(context) ]. Once a intensity reversal have occured the step size will be set to one (1).
skip-rule	optional	Number of initial intensity reversal that will be discarded in the threshold calculation [ int = Calculated(context) ]. If not specified this attribute is set to zero.

ManualYesNoTask

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
task-illustration-image	required	The image that is used to illustrate the stimulation task for the operator [ image = Calculated(context) ]
positive-answer	required	The expected answer for positive responses [ dynamic string ].
negative-answer	required	The expected answer for negative responses [ dynamic string ].

ManualTwoIntervalForcedChoiceTask

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
no-stimulus-image	required	Image used to illustrate an interval where no stimulus should be presented [ image = Calculated(context) ].
stimulus-image	required	Image used to illustrate an interval where a stimulus should be presented [ image = Calculated(context) ].
interval-a	required	Name of interval A [ dynamic string ].
interval-b	required	Name of interval B [ dynamic string ].

ManualOneIntervalForcedChoiceTask

Attributes

Name	Use	Description
question	required	The question about the stimulus that the participants is required to answer [ dynamic string ].
alternative-a-image	required	Image used to demonstrate alternative A to the operator [ byte[] = Calculated(context) ].
alternative-b-image	required	Image used to demonstrate alternative B to the operator [ byte[] = Calculated(context) ].
alternative-a	required	Expected response when the participant can perceive alternative A [ dynamic string ].
alternative-b	required	Expected response when the participant can perceive alternative B [ dynamic string ].

ResponseRecordingProcedure

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
duration	required	Sample duration for the response recoding [ double = Calculated(context) ].
sample-rate	required	Sample rate for the response recording [ double = Calculated (context) ]. This sample rate is used both for the psychophysical responses and the defined signals if any.
response-weight	optional	Weight given to the psychophysical ratings in the user interface [ int ]. Default value is 1.
signal-weight	optional	Weight given to the recorded signals in the user interface [ int ]. Default value is 0.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<events-makers>`	optional	Used to define the markers that an experimenter can use to mark events while the procedure is running. Events could be events such as a pain detection or a pain tolerance threshold. Events are organised into event groups, where only one event group can be active at any time. When the experimenter marks an event, then the marker can be configured to activate another event group. Consequently, this can be used to define the sequential logical flow of events, such as enforcing that a pain detection threshold is always before a pain tolerance threshold. When the procedure is started, the first defined event group will be active.
`<signals>`	optional	Defines the signals that will be sampled simultaneously with the collection of psychophysiological ratings and the script that will be called for each recording time to sample the signals.

EventMarkerCollection

Elements

Name	Use	Description
`<group>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

EventMarkerGroup

Defines a group of events that are active simultaneously.

Attributes

Name	Use	Description
id	required	Unique identifier for the event group [ string ]. This identifier is used by event markers to identity the next active event group.

Elements

Name	Use	Description
`<marker>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

EventMarker

Defines a marker for an event.

Attributes

Name	Use	Description
id	required	Unique identifier for the event marker [ string ].
name	optional	Name of the event [ string ]. If not specified the ID of the event will be used as its name.
complete	optional	Complete the procedure when the event is marked [ bool ]. Default value is false.
next-group	optional	Event group to activate when the event is marked [ string ]. This must be an ID of an event group, if no next-group is specified the currently active event group will remain active.

SignalGroupCollection

Defines the signals that will be sampled simultaneously with the collection of psychophysiological ratings and the script that will be called for each recording time to sample the signals.

Attributes

Name	Use	Description
sample	required	This attribute specifies the script that will be used to sample the signals [ [double] = Calculated(context) ]. The script must return a list of the same length as the number of defined signals and in the same order.
min	required	Global minimum value for the sampled signals [ double = Calculated(context) ].
max	required	Global maximum value for the sampled signals [ double = Calculated(context) ].

Elements

Name	Use	Description
`<signal>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SignalDeclaration

Attributes

Name	Use	Description
id	required	Identifier for the signal [ string ]. This identifier must be unique for all the defined signals.
name	optional	Name for the signal [ dynamic string ]. If no name is provided the ID of the signal will be used as its name.
type	optional	Type of signal that is sampled.
unit	optional	Unit of signal that is sampled [ string ].

StimulusPresentationProcedure

The Stimulus Presentation procedure allows a participant to become familiar with a stimulus and to rate its sensation on a psychophysical rating scale.

The procedure can also be used to manually find thresholds, as the last tested intensity is available in the calculated parameter [ProcedureID].Intensity upon completion.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
stimulus-update-rate	required	The update rate for the generated stimuli [ int = Calculated(context) ]. This update rate must be supported by the device that will deliver the stimuli.
trigger-update-rate	optional	The update rate for the generated triggers [ int = Calculated(context) ]. This update rate must be supported by the device that will deliver the stimuli, and if it is unspecified, the stimulus update rate will be used as the update rate for the trigger generation.

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<configuration>`	optional	Configuration of procedurecomponents, which includes configuration of the stimulation, trigger, and sampling components that are used by the procedure.
`<intensity>`	required	Specification of the intensities for the stimuli that the experimenter can choose during a session.
`<responses>`	optional	This element defines the response engine used by a procedure to collect behavioural or rating-based responses from the participant. The response engine supports multiple response modalities, including: Binary responses (yes/no, button presses) Numerical ratings (interval scales) Ratio ratings (continuous scales) Categorical ratings (ordinal scales) If no response collection mode is specified, the response engine is disabled and no response device is required for the procedure.
`<triggers>`	optional	Trigger generation.
`<stimulation>`	optional	Stimulation configuration that can either be delivered with a Stimulator instrument, or with any combination of instruments when the `´ element is defined.

ResponseEngine

This element defines the response engine used by a procedure to collect behavioural or rating-based responses from the participant.

The response engine supports multiple response modalities, including:

Binary responses (yes/no, button presses)
Numerical ratings (interval scales)
Ratio ratings (continuous scales)
Categorical ratings (ordinal scales)

If no response collection mode is specified, the response engine is disabled and no response device is required for the procedure.

Attributes

Name Use Description

response-collection

optional

Type of response collection that will be performed:

none: no responses are collected for this procedure.
yes-no: binary response collection using a button device. An Button instrument will need to be assigned to the procedure with a <device-assignment>.
ratio-rating: continuous ratio-scale rating using a ratio scale device. An RatioScale instrument will need to be assigned to the procedure with a <device-assignment>.
numerical-rating: numerical rating collection using an interval scale device. An IntervalScale instrument will need to be assigned to the procedure with a <device-assignment>.
categorical-rating: categorical response collection using an ordinal scale device. An OrdinalScale instrument will need to be assigned to the procedure with a <device-assignment>.

TriggerEngine

Trigger generation.

Attributes

Name Use Description

start-triggger

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<trigger>` `<repeated-trigger>` `<combined-triggers>`	1	This definition requires that exactly one item be provided and that it be chosen from a fixed set of mutually exclusive alternatives. Only one alternative may appear, and all other alternatives must be absent. No alternative is mandatory on its own, but the choice as a whole is required, meaning the container is invalid unless exactly one of the allowed options is specified.

StimulationEngine

Stimulation configuration that can either be delivered with a Stimulator instrument, or with any combination of instruments when the `´ element is defined.

Attributes

Name Use Description

start-trigger

optional

Timing or trigger source:

none: no source is configured.
internal: the source is an internal opration such as start of a stimulus.
external: a trigger event is received from external equipment.
button: a trigger event is received from a button press on a connected response device attached to any response port.
response-port01: a trigger is received on response port 1.
response-port02: a trigger is received on response port 2.
response-port03: a trigger is received on response port 3.
response-port04: a trigger is received on response port 4.

Elements

Name	Use	Description
`<scripts>`	optional	Custom stimulation where the stimulation is implemented with calculated parameters that can either be a single-line Python statement or, more commonly, by calling a Python function in a script.
`<stimulus>`	optional	Definition of a stimulus.

ThermalRatedStimulationProcedure

The Thermal Rated Stimulation procedure allows a thermal stimulus to be delivered to a participant while simultaneously recording the participant's psychophysical rating of the sensation.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
response-collection	optional	Type of response collection that will be performed: `none`: no responses are collected for this procedure. `yes-no`: binary response collection using a button device. An `Button` instrument will need to be assigned to the procedure with a `<device-assignment>`. `ratio-rating`: continuous ratio-scale rating using a ratio scale device. An `RatioScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `numerical-rating`: numerical rating collection using an interval scale device. An `IntervalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`. `categorical-rating`: categorical response collection using an ordinal scale device. An `OrdinalScale` instrument will need to be assigned to the procedure with a `<device-assignment>`.
sample-times	optional	Must return a list of the times the participant’s response should be sampled [ double[] = Calculated(context) ]. This attribute is only used if the `response-collection` is not set to `none`.
intensity	required	Intensity (`x`) that will be passed to the stimulus defined by the `<stimulus>` element [ double = Calculated(context) ].
minimal-display-temperature	optional	Used for displaying the thermal stimulus; it is the lower bound for the stimulation temperature [ double = Calculated(context) ].
maximal-display-temperature	optional	Used for displaying the thermal stimulus; it is the upper bound for the stimulation temperature [ double = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.
`<stimulus>`	optional	Definition of a stimulus.

ThermalThresholdEstimationProcedure

This procedure can be repeated a set number of times, and the threshold is taken as an average of the repeated threshold measurements.

Attributes

Name	Use	Description
id	required	Identifier for the procedure that must be unique within the protocol, and which must be a valid variable name.
name	required	Name of the procedure that is shown to the operator in LabBench Runner.
session	optional	ID of the session that the procedure belongs to. This parameter must only be used if sessions are defined for the protocol. If sessions are defined then the operator will choose the active session when the protocol is initialized by LabBench Runner. LabBench Runner will then only show procedures belonging to the current active session.
experimental-setup-id	optional	ID of the experimental setup configuration that will be selected when the procedure is performed.
threshold-type	required	Configuration of the thermal threshold to be determined.
stimulation-rate	required	The rate of temperature change for the determination of thresholds [ double = Calculated(context) ].
maximal-temperature	required	Maximal temperature for the thermal stimulus [ double = Calculated(context) ]. Please note that this temperature is higher than the `neutral-temperature` for heat thresholds and lower for cold thresholds. This temperature must be within the output temperature range (`minimal-temperature` to `maximal-temperature`) of the Thermal Stimulator assigned to the procedure.
return-rate	optional	Rate by which the temperature is returned to the neutral temperature once the threshold has been reached [ double = Calculated(context) ].
initial-stimulation-delay	required	Delay from start of the procedure in seconds to the start of the first threshold determination [ double = Calculated(context) ].
stimulation-interval	required	Interval between threshold determinations in seconds [ double = Calculated(context) ].
repetitions	required	Number of times the threshold is determined [ int = Calculated(context) ].

Elements

Name	Use	Description
`<procedure-events>`	optional	Defines the instruments involved in a procedure and specifies events that occur at the selection, start, completion, or abortion of the procedure. This element makes it possible to inject python code into a procedure that extends the base functionality that is provided by its LabBench implementation.
`<properties>`	optional	Procedure properties can modify the selection and execution of procedures, data collection, and provide instructions to the operator and participants.
`<dependencies>`	optional	The `<dependencies>` is an array element that can contain a sequence of elements. These elements can be of the following types: `<dependency>`
`<condition>`	optional	Place a condition on the inclusion of the procedure into a session.

QuestionnaireConstructor

The questionnaire procedure allows either the operator or the participant to answer a set of questions. The questionnaire can consist of the following types of questions:

Boolean Questions: questions that have mutually exclusive binary answer, which usually consists of answering a true or false statement, but can also consist of dichotomies such as child/adult.
Numerical Questions: are questions that can be answered with numerical answers.
Text Questions: are questions that can be answered with either free or validated text.
Likert Questions: A scale that captures how strongly someone agrees, disagrees, or feels about a statement using a fixed set of ordered response options.
List Questions: A set of binary statements that each can be either true or false.
Time Questions: a date and time provided by the participant, entered by the operator.
Map Questions: is answered by marking one or more regions, such as areas on a body map.
Categorical Rating Questions: rating of a sensation on a categorical scale.
Numerical Rating Questions: rating of a sensation on a numerical scale.
Visual Rating Questions: rating of a sensation on a visual analog rating scale.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

StimulationSequenceProcedureConstructor

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

SequentialProcedureConstructor

The states in the state machine are defined in the <states> element, which also makes it possible to define which Python functions are called for the enter, leave, and update state events.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryStimulusResponseProcedureConstructor

PDT: The Pain Detection Threshold,
PTL: The Pain Tolerance Limit, and
PTT: The Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryConditionedPainProcedureConstructor

From this stimulus-response curve, several psychophysical parameters can be determined:

Pain Detection Threshold (PDT),
Pain Tolerance Limit (PTL),
Pain Tolerance Threshold (PTT).

The determined parameters depend on the procedure configuration and the participant's instructions.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryTemporalSummationProcedureConstructor

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryStaticTemporalSummationProcedureConstructor

The static temporal summation applies a constant pressure for a specified duration instead of a series of stimuli to determine the temporal summation of pressure stimulation.

During this pressure stimulation and for a period after the procedure, the participant's VAS score will be recorded as the result of the procedure.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryStimulusRatingProcedureConstructor

The stimulus rating procedure provides a way to determine the Pain Detection Threshold (PDT), the Pain Tolerance Threshold (PTT), or both with an attached button.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryConditionedPainRatingProcedureConstructor

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

AlgometryArbitraryTemporalSummationProcedureConstructor

The arbitrary temporal summation procedure applies a series of rectangular pressure stimuli to one or both cuffs.

The participant is asked to rate the pain sensation of these stimuli on the VAS meter as soon as possible after the cessation of a pressure stimulus.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ThresholdEstimationProcedureConstructor

Stimulus modality: the type of stimulus, such as tactile, thermal, pressure, or electrical, presented to the participant and for which a threshold/psychometric function is estimated.
Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either true: the participant performed the task correctly, or false: the the participant failed to perform the task correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ColdPressorProcedureConstructor

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ManualThresholdEstimationProcedureConstructor

Response task: the perception task that the participant is asked to perform when the stimulus is presented. The outcome of this task is either correct: the participant perceived the stimulus correctly, or incorrect: the stimulus intensity was too low, and the participant failed to perceive the stimulus correctly.
Estimation algorithm: the adaptive algorithm by which the threshold/psychometric function is estimated. This algorithm uses the outcome of the response task (correct/incorrect) to update the estimate of the threshold or psychometric function for each stimulus presentation.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ResponseRecordingProcedureConstructor

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

StimulusPresentationProcedureConstructor

The Stimulus Presentation procedure allows a participant to become familiar with a stimulus and to rate its sensation on a psychophysical rating scale.

The procedure can also be used to manually find thresholds, as the last tested intensity is available in the calculated parameter [ProcedureID].Intensity upon completion.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ThermalRatedStimulationProcedureConstructor

The Thermal Rated Stimulation procedure allows a thermal stimulus to be delivered to a participant while simultaneously recording the participant's psychophysical rating of the sensation.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ThermalThresholdEstimationProcedureConstructor

This procedure can be repeated a set number of times, and the threshold is taken as an average of the repeated threshold measurements.

Attributes

Name	Use	Description
id	required	Identification of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
name	required	Name of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
session	optional	Session of the constructed procedure [ string ]. This can be a `var:` expression that constructs the ID from a formatted string with template variables.
template	required	Identifier (`id`) of the template to be used for constructing the procedure [ string ].

Elements

Name Use Description

<variables>

optional

An example of the generated of a procedure ID from a template variable:

id="var: f’B05{p}’"

<foreach variable="p" in="procedures">

ForeachConstructor

Loop through each element in a list template variable and generate procedures for each element in this list.

Attributes

Name	Use	Description
variable	required	Name of the variable used to hold the elements in the foreach loop [ string ].
in	required	Name of the list variable whose elements the foreach will loop through. This list variable must be defined in the variables element of the protocols templates element [ string ].
type	optional	The type of randomisation performed on the generated procedures: deterministic: no randomisation is performed. The procedures will appear in the protocol in the same order as generated by the foreach loop. random: the order of the procedures will be completely randomised. latin-squares: the order of the procedures will be based on a row of a N x N Latin-square, where N is the number of procedures generated by the foreach loop. generated: the procedures will be ordered by a sequence generated by a Python expression or Python backing script specified by the offset attribute.
offset	optional	This attribute is only used for Latin squares [ int = Calculated(context) ]. It is the offset/number of the row in the Latin square. If the offset is larger than the square, then the offset will be the modules with the square’s size. Typically, these offsets are calculated from the ParticipantNumber variable, which is the number of the participant in the data set. Basing the offset on the ParticipantNumber makes it possible to shift the latin-square row for each participant participating in the experiment.
generator	optional	This attribute is only used for generated randomisations [ int[] = Calculated(context) ]. It must return an int array of length N, where N is the number of procedures to be randomised.

Elements

Name	Use	Description
`<questionnaire-constructor>` `<sequential-constructor>` `<algometry-stimulus-response-constructor>` `<algometry-conditioned-pain-modulation-constructor>` `<algometry-temporal-summation-constructor>` `<algometry-static-temporal-summation-constructor>` `<algometry-stimulus-rating-constructor>` `<algometry-conditioned-pain-modulation-rating-constructor>` `<algometry-arbitrary-temporal-summation-constructor>` `<psychophysics-threshold-estimation-constructor>` `<psychophysics-cold-pressor-constructor>` `<psychophysics-manual-threshold-estimation-constructor>` `<psychophysics-response-recording-constructor>` `<psychophysics-stimulus-presentation-constructor>` `<stimulation-sequence-constructor>` `<thermal-rated-stimulation-constructor>` `<thermal-threshold-estimation-constructor>` `<foreach>` `<sequence>` `<if>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

SequenceConstructor

A sequence performs randomisation of the elements within the sequence.

Attributes

Name

Use

Description

type

required

The type of randomisation performed on the generated procedures:

deterministic: no randomisation is performed. The procedures will appear in the protocol in the same order as generated by the foreach loop.
random: the order of the procedures will be completely randomised.
latin-squares: the order of the procedures will be based on a row of a N x N Latin-square, where N is the number of procedures generated by the foreach loop.
generated: the procedures will be ordered by a sequence generated by a Python expression or Python backing script specified by the offset attribute.

offset

optional

This attribute is only used for Latin squares [ int = Calculated(context) ]. It is the offset/number of the row in the Latin square. If the offset is larger than the square, then the offset will be the modules with the square’s size. Typically, these offsets are calculated from the ParticipantNumber variable, which is the number of the participant in the data set. Basing the offset on the ParticipantNumber makes it possible to shift the latin-square row for each participant participating in the experiment.

generator

optional

This attribute is only used for generated randomisations [ int[] = Calculated(context) ]. It must return an int array of length N, where N is the number of procedures to be randomised.

Elements

Name	Use	Description
`<questionnaire-constructor>` `<sequential-contructor>` `<algometry-stimulus-response-constructor>` `<algometry-conditioned-pain-modulation-constructor>` `<algometry-temporal-summation-constructor>` `<algometry-static-temporal-summation-constructor>` `<algometry-stimulus-rating-constructor>` `<algometry-conditioned-pain-modulation-rating-constructor>` `<algometry-arbitrary-temporal-summation-constructor>` `<psychophysics-threshold-estimation-constructor>` `<psychophysics-cold-pressor-constructor>` `<psychophysics-manual-threshold-estimation-constructor>` `<psychophysics-response-recording-constructor>` `<psychophysics-stimulus-presentation-constructor>` `<stimulation-sequence-constructor>` `<thermal-rated-stimulation-constructor>` `<thermal-threshold-estimation-constructor>` `<foreach>` `<sequence>` `<if>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

IfConstructor

Enable conditional generation of procedures from procedure constructors.

Attributes

Name	Use	Description
condition	required	Condition for generating procedures [ bool = Calculated(context) ]. The enclosed procedure constructors are only executed if the condition is true.

Elements

Name	Use	Description
`<questionnaire-constructor>` `<sequential-constructor>` `<algometry-stimulus-response-constructor>` `<algometry-conditioned-pain-modulation-constructor>` `<algometry-temporal-summation-constructor>` `<algometry-static-temporal-summation-constructor>` `<algometry-stimulus-rating-constructor>` `<algometry-conditioned-pain-modulation-rating-constructor>` `<algometry-arbitrary-temporal-summation-constructor>` `<psychophysics-threshold-estimation-constructor>` `<psychophysics-cold-pressor-constructor>` `<psychophysics-manual-threshold-estimation-constructor>` `<psychophysics-response-recording-constructor>` `<psychophysics-stimulus-presentation-constructor>` `<stimulation-sequence-constructor>` `<thermal-rated-stimulation-constructor>` `<thermal-threshold-estimation-constructor>` `<foreach>` `<sequence>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

AssetManager

Files can be included in experiments in the form of assets within the <assets> element in the Experiment Definition File. This element consists of a set of <file-asset> that can be used in procedures and Python code.

The following assets can be included:

.py: Python code
.md: Markdown Files
.txt: Text Files
.rtf: Rich Text Format
.png: Portable Network Graphics
.zip: Zip files
.json: Data files
.wav: Sound files
.csv: Comma Separated Values
.svg: Scalable Vector Graphics
.ttf: True Type Fonts

Within calculated parameters, assets can be referred to by the id with the following notation: Asset.[AssetID]. Files within zip archives can be further addressed as Asset.[AssetID].[Name of file without extension]. Please note that paths and extensions within zip files are not considered. Consequently, in a zip file, there must be only one file with a given name, regardless of its extension or location within the zip file.

Elements

Name	Use	Description
`<file-asset>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

CSVAction

Export of data to csv files.

Attributes

Name	Use	Description
name	required	Name of the post-session action that will be used to identify the action in LabBench [ string ].
location	required	Location in the file system where the outputs of the post-session action will be saved [ string ].
filename	required	Name of the file [ string = Calculated(context) ].
header	optional	Include header in the file [ bool ].
separator	optional	Separator to use for the csv file [ string ].
culture	optional	Culture strings follow the format: languagecode2-regioncode2. For example: en-US: represents English (United States). fr-FR: represents French (France). zh-Hans: represents Simplified Chinese. The languagecode2 is based on ISO 639-1, while regioncode2 is based on ISO 3166-1. Use of regioncode2 is optional. The default value is "en".

Elements

Name	Use	Description
`<item>`	0 .. n	This definition describes a container that can hold an ordered list of zero or more items, where each item represents exactly one choice from a fixed set of allowed alternatives. Each item in the list is optional and independent, and the list itself has no upper limit on the number of items it may contain. For each position in the list, only one of the permitted alternatives may be present, and no other kinds of items are allowed. The container may also be empty, meaning none of the alternatives are specified.

CSVElement

Elements for the CSV file.

Attributes

Name	Use	Description
name	required	Name of the variable [ string ].
value	required	Value for the element [ object = Calculated(context) ].
default	optional	Value that will be inserted if the value calculation throws an error or if the element has been excluded with by its `condition` attribute [ string ].
condition	optional	Calculate the value or exclude this element [ bool = Calculated(context) ]. This attribute makes it possible to exclude calculation of the value when procedures are not completed.

ExportAction

Export of data to a single data file. Consequently, this post-session action enables the creation of a single data file for each participant participating in a study.

Attributes

Name	Use	Description
name	required	Name of the post-session action that will be used to identify the action in LabBench [ string ].
location	required	Location in the file system where the outputs of the post-session action will be saved [ string ].
filename	required	Name of the file [ string = Calculated(context) ].
format	optional	Specifies the format of the exported data: `json`: Javescript Object Notation `hdf5`: Hierarchical Data Format version 5 `matlab`: Matlab File Format (Level 5)

ScriptAction

Execution of a calculated parameter as a post-session action. As calculated parameters can execute Python functions with the `func: [Python Script Asset].Function Name allows you to use this post-session action to implement custom post-session actions.

Attributes

Name	Use	Description
name	required	Name of the post-session action that will be used to identify the action in LabBench [ string ].
location	required	Location in the file system where the outputs of the post-session action will be saved [ string ].
script	required	Calculated parameter to execute as a post-session action [ bool = Calculated(context) ]. Must return true if it completed successfully, otherwise false.

LogAction

Export of the experimental log for a participant to a pdf file.

Attributes

Name	Use	Description
name	required	Name of the post-session action that will be used to identify the action in LabBench [ string ].
location	required	Location in the file system where the outputs of the post-session action will be saved [ string ].
filename	required	Name of the file [ string = Calculated(context) ].
level	optional	Setting the log level, all log entries lower than this log level will be discarded.
id	optional	Identifier that will be embedded in the header of all pages of the generated experimental log [ dynamic text ].

CopyAction

Copy a file from one directory (source) to another directory (location). The filename cannot be changed.

Attributes

Name	Use	Description
name	required	Name of the post-session action that will be used to identify the action in LabBench [ string ].
location	required	Location in the file system where the outputs of the post-session action will be saved [ string ].
source	required	Source directory for the file to be copied [ string ].
filename	required	Name of the file [ string = Calculated(context) ].

Termonology

Element names:

participant-validator, experimental-setup, experimental-setup-variants, protocol, export-to-csv, export-data, export-script, export-log, copy, lio, cpar, cpar-plus, sound, joystick, tcs, display, evas, device-assignment, trigger-setup, stimulators, response-devices, ds5, noxistim, button, visual-analogue-scale, audio-trigger, visual-trigger, response-pad, map, button-assignment, anchors, modality, top-anchor, bottom-anchor, localized-text, typography, categorical-scale, numerical-scale, composite-scale, image-display, questionnaire, title, instruction, answer, likert-category, numerical-answer, text-answer, time-answer, scale-modality, crs-category, nrs-category, category, languages, sessions, properties, persistent-variables, variables, templates, procedures, assets, language, session, rerun-policy, incomplete-protocol-warning, allow-in-session-participant-creation, in-session-display-of-participants, integers, integer, strings, string, struct, variable, includes, template-variables, protocol-variables, procedure-templates, include, structs, sequential, stimulation-sequence, algometry-stimulus-response, algometry-conditioned-pain-modulation, algometry-temporal-summation, algometry-static-temporal-summation, algometry-stimulus-rating, algometry-conditioned-pain-modulation-rating, algometry-arbitrary-temporal-summation, psychophysics-threshold-estimation, psychophysics-cold-pressor, psychophysics-manual-threshold-estimation, psychophysics-response-recording, psychophysics-stimulus-presentation, thermal-rated-stimulation, thermal-threshold-estimation, procedure-events, dependency, condition, question-events, text, boolean, numeric, likert, dimensional-likert, list, time, map-constructor, text-constructor, boolean-constructor, numeric-constructor, likert-constructor, dimensional-likert-constructor, list-constructor, time-constructor, visual-analogue-scale-constructor, numerical-scale-constructor, categorical-scale-constructor, foreach, instrument, auto-start, auto-advance, time-constraint, instructions, participant-instructions, next, annotations, bool, bools, number, numbers, area, validation, choice, dimension, item, update-rate-deterministic, update-rate-random, states, state, configuration, stimulation-scripts, stimulation-pattern, stimuli, stimulation-generation, trigger-generation, sequence, uniformly-distributed-sequence, stimulus, triggers, trigger, repeated-trigger, combined-triggers, code, combined-trigger, pulse, ramp, sine, arbitrary, combined, repeated, window, multiple-outputs, linear-segments, output, segment, manual-yes-no-task, yes-no-task, forced-yes-no-task, manual-interval-rating-task, interval-rating-task, manual-categorical-rating-task, categorical-rating-task, ratio-rating-task, interval-forced-choice-task, alternative-forced-choice-task, stimulus-channel-template, channel, interval, alternative, catch-trials, psi-method, up-down-method, discrete-up-down-method, quick, beta, alpha, intensity, intensity-transformation, psi-algorithm, up-down-algorithm, two-interval-forced-choice-task, one-interval-forced-choice-task, gumbel, hyperbolic-secant, logistics, log-quick, normal, weibull, events-makers, signals, group, marker, signal, responses, stimulation, scripts, file-asset, localisation, aliases, alias, questionnaire-constructor, stimulation-sequence-constructor, sequential-constructor, algometry-stimulus-response-constructor, algometry-conditioned-pain-modulation-constructor, algometry-temporal-summation-constructor, algometry-static-temporal-summation-constructor, algometry-stimulus-rating-constructor, algometry-conditioned-pain-modulation-rating-constructor, algometry-arbitrary-temporal-summation-constructor, psychophysics-threshold-estimation-constructor, psychophysics-cold-pressor-constructor, psychophysics-manual-threshold-estimation-constructor, psychophysics-response-recording-constructor, psychophysics-stimulus-presentation-constructor, thermal-rated-stimulation-constructor, thermal-threshold-estimation-constructor, if, sequential-contructor

Attribute names:

regex, advice, id, name, default-analogue-output, logic-system, low-byte-voltage-level, high-byte-voltage-level, transconductance, timing-source, experimental-setup-id, code, button, label, sample-period, length, text, language, arming-period, type, compressor-mode, rating-scale, minimal-temperature, neutral-temperature, maximal-temperature, trigger-output, normative-distance, background-colour, foreground-colour, active-colour, inactive-colour, size, border-thickness, style, weight, colour, controller-device, maximum, minimum, initialize-rating-to-zero, device-id, procedure-id, instrument-name, default, message, require-reason, force-warning, value, protocol-id, progress-format, control, start, complete, abort, selected, selected-blocked, selected-ready, selected-completed, selected-excluded, interface, min, max, notification, time-reference, start-instruction, override-results, blocked, ready, excluded, completed, virtual, expression, help, changed, title, instruction, condition, image-map, overlay-image, selected-colour, active-selected-colour, deselected-colour, active-deselected-colour, selection-mode, initial-active-area, up, down, left, right, maximal-length, true-label, false-label, max-included, min-included, question, top-anchor, bottom-anchor, template, variable, in, enter, leave, update, stimulus-update-rate, trigger-update-rate, response-collection, trigger-source, initialize, stimulate, stimulus-description, stimulus-unit, time-base, iterations, pause, Tperiod, Toffset, maxTperiod, minTperiod, order, generator, count, intensity, Tdelay, duration, output, N, Is, Ts, Ioffset, Frequency, window, parameter, channel, baseline, second-cuff, pressure-limit, conditioning-time, delta-pressure, vas-pdt, stop-mode, primary-cuff, conditional-pressure, delta-conditional-pressure, no-of-stimuli, t-on, t-off, pressure-stimulate, pressure-static, stimulus-duration, tail-duration, measurement, pressure, probe, cue, display-duration, display-interval, yes-button, no-button, target, image, Imin, Imax, confidence-level, interval, number-of-trials, alpha, beta, lambda, gamma, n, x0, x1, base, reversal-rule, up-rule, down-rule, step-size, step-size-up, step-size-down, step-size-reduction, max-step-size-reduction, step-size-type, stop-rule, skip-rule, start-intensity, initial-direction, initial-intensity, intensities, initial-step-size, time-limit, ready-instruction, completed-instruction, pending-instruction, pain-instruction, completion-instruction, pdt-label, ptt-label, non-responder-label, responder-label, a, b, intensity-labels, task-illustration-image, positive-answer, negative-answer, no-stimulus-image, stimulus-image, interval-a, interval-b, alternative-a-image, alternative-b-image, alternative-a, alternative-b, sample-rate, response-weight, signal-weight, next-group, sample, unit, start-triggger, start-trigger, sample-times, minimal-display-temperature, maximal-display-temperature, threshold-type, stimulation-rate, return-rate, initial-stimulation-delay, stimulation-interval, repetitions, file, replace, with, session, offset, location, filename, header, separator, culture, format, script, level, source

Enums

AlgometerCompressorMode (auto,manual)
AlgometerStopCriterionSpecification (stop-on-maximal-rating,stop-when-button-pressed)
AreaSelectionMode (single,multiple,unspecified)
ArrayAlgorithm (linspace,logspace,geomspace,array)
ButtonID (button-none,button-01,button-02,button-03,button-04,button-05,button-06,button-07,button-08,up,down,left,right,decrease,increase,previous,next,clear)
CatchTrialMode (deterministic,block-randomised,randomised)
CPTControl (operator,participant)
CPTMeasurement (pdt,ptt,both)
DS5Transconductance (1mA_1V,2.5mA_1V,5mA_1V)
ElementStyle (normal,italic)
ElementWeight (thin,light,normal,medium,bold,extra-bold)
ExportFormat (json,hdf5,matlab)
InstrumentType (pressure-algometer,stimulator,image-display,button,ratio-scale,interval-scale,ordinal-scale,scales,sweep-sampler,trigger-generator,trigger-detector,sound-player,thermal-stimulator)
LogicSystem (positive,negative)
LogLevel (verbose,debug,information,warning,error,fatal)
NoxiStimTransconductance (1mA_1V,10mA_1V)
PainThresholdMeasurement (pdt,ptt,both)
QuestionnaireControllerMode (unspecified,operator,participant)
QuestionProgressFormat (none,percentage,index)
ResponseCollectionMode (none,yes-no,ratio-rating,numerical-rating,categorical-rating)
ResponsePadType (button-6-linear,button-4-linear,button-4-cross)
SequenceType (latin-squares,random,deterministic,generated)
Signal (voltage,current,temperature,force,impedance,applied-voltage,applied-current,distance,pressure,sound-itensity,generic)
StepType (absolute,relative)
StimulusSetOrder (round-robin,random,block-random,latin-squares,generated)
ThermalThresholdType (cold-detection-threshold,heat-detection-threshold,cold-pain-threshold,heat-pain-threshold,cold-pain-tolerance-threshold,heat-pain-tolerance-threshold)
TimeBase (microseconds,milliseconds,seconds)
TimeReference (start,end)
TriggerOutput (trigger-output,stimulator-trigger-output,trigger-interface)
TriggerSource (none,internal,external,button,response-port01,response-port02,response-port03,response-port04)
UpDownState (increasing,decreasing)
VoltageLevel (unconnected,3.3V,5.0V)
WindowType (bartlett,blackman,tukey)

Statistics

Number of elements: 666
Number of documented elements: 666
Number of undocumented elements: 0

Undocumented elements

None

Last modified May 21, 2026: Device server implementation (#1375) (5dd5648d)