Scripting Language – Features
Stimulus Material and Presentation
The scripting language allows you to define individual pictures and tones as atomic building blocks that can be presented at trial time in any combination on any screen location. This results in a very efficient definition of stimulus material because you do not have to define all permutations of stimulus locations to support all potential screen constellations.
Visual Stimulus Material
Visual stimuli are defined in form of PICTURES which can be positioned and combined with other pictures to create dynamic screen content within trials at runtime
Internal picture definition within script
- Multi-line text
- Raster graphics defined as 0,0 pixel block
- Vector graphics defined as drawing commands
- Gabor patch
- Screen image area saved at runtime
External graphics files referenced via URL
- Image files (PNG, GIF, JPG)
- Video files (MP4, OGC, WEBM)
- Rotate on X,Y,Z axis
- Concatenate multiple pictures into one image
- Add to current screen image
- Set text color and font
- Active single word presentation mode
Pictures are displayed on screen positions which are defined in the script as X/Y milimeter coordinates with the center at (0,0). One position definition may consist of multiple points references as index 1..N
Computer monitors can be calibrated so that the mm coordinates exactly match the physical dimensions of the screen.
- Single point defined as one X/Y coordinate
- Multiple point defined as a series of X/Y coordinate
- Circle with n equally spaced points
- Matrix with equally spaced row and column points
- Line with multiple points along one vector
Manipulation of one position at runtime
- Drawing a random point
- Rotating point indices
- Randomly mixing point indices
- Reserving a point as already loaded with a picture
- Filling all empty points with pictures
Screen Switching and Rendering
The script language shields you from technical details of graphics rendering, but for advanced user you can choose between different image rendering and switching modes:
Direct Rendering (default)
- All pictures are directly rendered to the screen buffer without considering vertical refresh of the graphics card. Good for not too complex screen content which renders fast within one refresh cycle.
Synchronized Direct Rendering
- All visual presentation commands are queued and executed in sync with the vertical refresh of the card. This is the same as the direct rendering but the onset time for response registration is corrected by the vertical refresh of the card derived from the requestAnimationFrame API.
Back Buffer Rendering
- Rendering of pictures can be redirected to an off-screen back buffer which is not visible until it is transferred to the screen. This method allows you to prepare complex screen content apriori, and then transfer the entire image from back buffer to visible front buffer using efficient block-copy methods of modern graphics engine.
Auditory Stimulus Material
Auditory stimuli are defined in form of TONES which can be played and combined with other tones and pictures at runtime during trials
Internal tone definition within script
- Sine wave tones
External audio files referenced via URL
- Audio file (WAV, MP3, MPEG)
Single Word Presentation Mode
To study text comprehension, the script language offers a very simple method to present a text phrase word by word or split into any user-defined tokens.
- Define all text phrases as Text Pictures
- Configure the trial to display these text pictures token-by-token in one of the following modes
- Tokens are displayed one by one at their original location of the phrase
- All token appears on the same location
- Hide all tokens which are not displayed
- Mask all tokens which are not displayed to give the subject some indication of the length and structure of the entire phrase
- Define a trial which captures the response for each token
- e.g. define a self-paced trial structure which continuous not before the subject submits a response
- e.g. define a trial with fixed presentation time to present tokens with a constant speed
The scripting language supports a variety of input devices including speech recognition, subjective rating scales, and free text input feels. This allows you to define custom scales and questionnaires and combine them with other cognitive tasks into one test battery.
With speech recognition, you can voice enable any reaction time task or Likert scale by mapping voice input to response keys. Use this feature to enable patients with motoric disabilities to submit their answers or force subject to submit verbal responses (e.g. in a Stroop paradigm)
Keyboard and Mouse Keys
Response keys are defined with the KEY command. You can activate one or multiple keys which should be considered when waiting for a key press.
Any key name of keyboard and mouse
- Key press
- Key release
Touch or Mouse Click
The script language allows you to declare screen positions as sensitive and map locations to keys. For example, a left and right screen location could be mapped to the keys ‘L’ and ‘R’ respectively.
You can event define dynamic mapping where the names of pictures that are loaded on random locations are recorded as a the touch response. Let’s say you randomly load pictures left or right, the touch on the left side will be recorded using the name displayed on the left.
The script language allows you to define a vocabulary of words which you can map to response keys. Let’s say you want to allow subjects to say YES or NO, you can define a vocabulary ‘Yes’ and ‘No’ and map these words to the keys ‘Y’ and ‘N’.
You can map multiple phrases to the same key to increase the hit rate of recognizing the verbal response. E.g. ‘Yes’ and ‘Yeah’ could be both mapped to the key ‘Y’.
This feature is based on the Google SpeechAPI available in Google Chrome and provided on an as-is base, because it is not part of industry standard.
Subjective Rating Scales
Two types of rating scales are supported to collect subjective ratings of mood, emotional state, opinions, etc.
VAS Scale: Visual analogue scale (typically 0-100 mm) where subjects set a slider to a position which reflects their subjective rating
Likert Scale: Multiple options (typically 5 or 7 alternatives) subjects can select depending on which option best describe their subjective feeling or opinion.
Free Text Input
The scripting language allows you to define text input fields to capture free text input. This feature can be used to create simple linear questions or capture free text input as part of an experiment (e.g. free recall in memory tasks).
To define the sequence of events of your experiment, the scripting language provides three procedural language constructs:
- A TRIAL define the low level atomic events and timing of presenting instructions and the reaction time task. Trials may have variable parameters to repeat them with different settings.
- A BLOCK defines the factorial design of on block of trials by listing all trials together with their parameter settings.
- A SESSION is the main structure of the experimental session and specifies the to be executed order of trials and blocks.
A TRIAL defines the individual events and timing of one trial. Trials are typically repeated many times within blocks to present the same reaction time task with different treatment conditions. The script language allows you to define variable parameters to execute the same trial with different stimuli, screen positions, and timing.
Examples of trial events are
Visual Presentation: Show Picture, Clear Screen
Auditory Presentation: Start Tone, Clear Tone
Rating Scales: Show Scale, Get Scale Rating
Response Registration: Wait for Key, Record Keys
Response-dependent Actions: Feedback, On-Key Actions
Random Processes: Draw Random Element, Fill Positions, Mix Positions
A Block definition is a listing all trial specifications which should be executed. The same trial can be executed with different values e.g. the name of the picture to be shown, name of screen position where the picture should be displayed, the time to wait between cue and stimulus, the correct key name, etc.
A block definition may also include multiple trial definitions to run structurally different trial definitions within the same block. For example, if you want to presents a picture in on trial, and an auditory stimulus in another trial, then you will need two different trial definitions, one with a show picture command and one with a play tone command.
Blocks are called from a SESSION. You can specify if trials should be executed in a fixed order as define, or in a random order. You also define how many times the core factorial design of a block should be repeated and optionally set a max time limit.
A session definition is a fixed list of Trial names and Block names which specifies the sequence of events at the highest level. For example, you may want to execute one or multiple trials to show instructions, followed by one or multiple blocks which present all trial specifications define in this block in random order.
While many treatment conditions are controlled and explicitly defined as factorial design of blocks, some aspects of an experiment should just be randomized. The scripting language provides multiple mechanisms to randomize stimulus material, screen positions, timing, and order of trials.
Random Draw from Set
The script language allows to group data objects such as PICTURE, POSITION, TONE, etc. into a SET. A set is collection of such objects which can be used to realize random processes by drawing set elements with or without replacement from a set.
Let’s say you have a set of distractor pictures and want to display a random distractor in each trial to a specific target which you control. While the picture name for the target would be explicitly specified in a BLOCK definition, you want the distractor to be chosen randomly. For this, you draw a random picture from the set of distractors at each trial level and display it next to the target.
Random elements drawn from a set are logged and included in the result file.
Random Screen Locations
In many task paradigms, not only the pictures, but also the screen location of visual stimuli should be randomized. This can be easily achieved using the POSITION construct of the script language.
A POSITION may consist of multiple points indexed from 1..N. For example, to load a picture on one of eight equi-distant points of a circle, you just define a POSITION of type circle and then load a picture on one of the eight points.
The script language allows you choose a random point out of these eight, or to randomize the order of points so that the index is random.
There is also the option to load a random collection of pictures defined as a SET on random screen locations defined as POSITION. This is very convenient in visual search paradigms where random distractors are loaded on random locations.
Random Time Interval
Random time can be realized by defining the same trial with different time values and put all variants into the block definition and execute them in random order. But sometimes, you really just want to have one random interval between fixation point and stimulus, or between trials. The script language supports the definition or two types of random time intervals:
Exponential time interval with an estimated mean and max value
Equi-distant random time interval with n-values between a min and max time value
Random Trial Order
A BLOCK definition typically contains your factorial design of independent variables in form of a list of trial specifications. By executing this list of trials in random order, a treatment condition is not predictable for the subject.
If you repeat a factorial design within one block execution, you can choose between two randomization modes:
- Randomize each factorial design individually, so that all treatment conditions are about equally placed within a longer BLOCK,
- Randomize trials across the total length of the block
You can also set a flag to avoid direct repetition of the same block.
The script language does provide embedded mathematical and logical expressions to compute dynamic content and event flow. In addition, it offers several built-in mechanisms to realize response-dependent actions and branching.
- Response-dependent insertions
- Response-dependent branching
- Response-dependent adaptive staircase process
A response-dependent insertion inserts one or multiple trial events into the event flow depending on the subject’s response.
- Present Feedback: For each trial specification you can define which key and number of responses are correct. During execution, the actual response is compared with these settings and different events can be executed depending on correct/false key and correct/false number of keys. This 2×2 schema can be used to insert feedback for simple reaction, choice-reaction, and Go/No-Go tasks.
- On-Key Actions: with this option, you define individual events for each key independently of the correctness. This mode gives you more control about how to react to a response. On-key actions are typically used to display some feedback on an individual key press, or update position or images depending on which key has been pressed.
Unlike insertions, which insert events, but then continue with the normal trial event sequence, branching will interrupt event flows or jump to specific trials depending on a subject’s response.
Branching is triggered by including one of the following commands into the response-dependent feedback or on-key actions
- End current trial
- End current block
- Repeat current trial
- Jump to another trial with specific index in the block definition
- Jump to another trial relative to the current trial
Adaptive staircases are rule-sets which define when to increase or decrease a task difficulty depending on the correctness of a response. The goal of an staircase process is to determine what task difficulty leads to a certain percentage of correct responses. For example, if you increase difficulty if the response is correct, and decrease if the response is incorrect, you will end up with 50% correct responses in the long run.
The script language allows you to activate different rule sets to achieve different percentage levels by specifying step sizes and number of consecutive correct or wrong responses until a task level is increased or decreased.
There are two modes a staircase can operate
Changing variable parameter of a trial specification: for example, you could vary a variable time parameter influencing the SOA between stimulus and mask, to estimate the time needed for 75% correct responses
Walking up and down a block definition: In this mode, the staircase process is selecting specific trials from the block definition by increasing or decreasing the trial index. The block definition must list trials specification in ascending order of the treatment condition you are interested in. For example, you could vary the inter-stimulus-interval between an auditory stimulus and visual stimulus from -200ms to +200ms and then let the staircase walk up and down until subjects perceive the bimodal stimuli to be presented simultaneous.
The script language offers the definition of mathematical and logical expressions that can be used to define response dependent content or event flow at runtime.
The eval()-like expressions use session statistics and variables as input, for example:
- Last Response
- Descriptive statistics of recent responses
- Block statistics
- Session statistics
- Any user-defined variable
The result of the expressions can be used to update content or influence the events flow:
- A logical condition that can be used for conditional branching (On Expression)
- A text that can be displayed as dynamic text picture
- Update a variable that can be used within the trial definitions as a dynamic parameter