On QRTEngine JavaScript, part 2: Stimuli

Stimuli are the core of any behavioural experiment. For that reason, the QRTEngine allows for a lot of user control over these stimuli, with the user being the experimenter. In fact, the core of QRTE is basically a loop that displays and removes stimuli from display at the right time, in the correct order. Everything else is just ways to interact with that loop, but having easy ways of interacting with the core is just as important as having a working core loop. This tutorial will hopefully enlighten the ways in which the core loop can be interacted with, or how the behaviour of stimuli (those tagged as ‘Stimulus’ in the JavaScript) can be changed.

Stimulus States

In general, any Stimulus goes through four distinct stages which can be hooked into in several ways. The core loop, as mentioned before, runs through all stimuli in a trial and display and then hides them in order. This means that for a single stimulus, the following stages exist (in order)

  1. pre-display (inactive)
  2. activated(active)
  3. displayed (active)
  4. post-display (inactive)

Pre-display is the state the stimulus is in while other stimuli (in front of it in the queue) are worked through. Post-display is the state it goes into after it has been displayed, and will stay in as long as the trial goes on. In both these states, the stimulus doesn’t respond to key presses (as it should), nor is it visible (as it should be as well). In the Activated and Displayed state, the Stimulus is ‘active’ and thus will respond to key-presses. However, the difference is that the Stimulus is displayed in the latter state, but not the former. This allows for a delay in presentation of the stimulus, controlled by the delay ‘configuration’ which will be touched on later.

Changing Stimulus Behaviour

Among the things that QRTEngine allows is hooking into the state changes of the Stimulus, which will be explained upon further down in this tutorial. Basically, it allows you to do your own thing when the stimulus is ‘activated’, when it is ‘displayed’ and when it is ‘hidden’.  These are just three of the ways in which the behaviour of a stimulus can be altered, there are many more and it is generally done by changing the stimulus’ attributes in various ways. These attributes can be split into two categories, each with their own way of setting them. The first one, configurations, can be set through a method (QRTE.config) and will generally be set  inside the Init question, but this isn’t absolutely required. The second category of attributes is set as attributes to the object being passed into the Stimulus method in the JavaScript associated with the question in Qualtrics. At the point of writing this, I don’t remember why I made the distinction in the first place, future versions might see these configurations and ‘attributes’ being merged into one (without losing backwards compatibility in this regard). Anyhow, first off, the configurations!


In total there are 5 configurations that can be set for a Stimulus. Generally these configurations optional and default to a certain value and thus certain behaviour. The existing configurations are the following, in no particular order:

  • Duration – default: infinite – The duration the stimulus should stay on screen for in milliseconds (alternatively this value can be set to Infinity for infinite duration )
  • Delay – default: 0 – The time, in milliseconds, that the QRTEngine should wait between this question becoming active and actually displaying it. Time of question being active = duration + delay.
  • Allowable – default: none – A ‘string’ of characters depicting keys which are allowed to be pressed while this stimulus is active, or rather, which the
  • CResp – default: none – A ‘string’ of characters depicting keys which will be considered as a correct response when pressed. Each character must appear in the ‘allowable’ string as well, although the other way around is obviously not required.
  • EndAction – default: ‘none’ – A string with certain values that tell the Engine what to do when key is pressed, see possible values below:
    • TERMINATE – QRTEngine will hide the stimulus and progress to the next one upon pressing an allowable key, storing accuracy, RT, RTTime
    • NONE – QRTEngine will store accuracy, RT, RTTime, but won’t advance to the next stimulus untill either the duration runs out, or it is told to do so expressly.

Having these types of ‘attributes’ be configurations allows you to configure, on a basic but most of the time sufficient level, each stimulus in the JavaScript for the Init question. General note: It is advisable to defer as many computationally heavy actions  to the Init question, as there is a built in ‘padding’ that ensures at least a certain Inter-Trial Interval (ITI) is reached, meaning that most of the time the Engine is idle while waiting for the ITI to finish. A Perfect time to do some heavy calculations! Refer to Part three of this series for more information on that!

Stimulus Method Parameters

The Method parameters allow for an even finer control of the specifics of the Stimulus. Whereas configurations mostly concern parameters that have to do with length and responsiveness of the stimulus, the method parameters have to do with initialisation of the stimulus and ‘events’.

First off, there are two parameters that are required for the Stimulus to work correctly. These are the following:

  • id – String – unique identifier used by QRTEngine for the specific Stimulus. This is used to properly  parse the data file received from Qualtrics. Simply put, without a unique id, the data file will contain inconsistencies.
  • onShowFn – Function – The function to be called upon activating the Stimulus.  Does not necessarily have to do anything, but is required as a parameter. (Might change this in future versions)

Next to the above required ones, there are quite a few optional parameters that allow for very fine control over the stimulus.

  • conditionalFunction – Function that is called before displaying the Stimulus, if it returns true, the Stimulus is displayed, if false it is not displayed.
  • stimContinue Boolean – If set to true, QRTEngine will continue searching for new Stimuli to display on the same page.
  • onKeyPress – Function – Function that is called upon the Stimulus receiving *any* keypress. 
    • Examples: none yet
  • onAllowableKey – Function -Function that is called upon the Stimulus receiving an Allowable keypress.
    • Examples: none yet
  • onCorrectKey – Function – Function that is called upon the Stimulus receiving an Allowable keypress that is also marked Correct. 
    • Examples: none yet
  • onIncorrectKey – Function – Function that is called upon the Stimulus receiving an Allowable keypress that is not marked is Correct, but correct responses possible.
    • Examples: none yet
  • proceedOnHide Boolean – If true, the QRTEngine proceeds to the next page of stimuli, if false, does nothing upon hiding.  This is aimed to be used when displaying multiple stimuli on screen at the same time, but when one stimulus has to be removed early without causing the next set of stimuli to be displayed.
    • Examples: none yet
  • onHideFn Function – Function that is called upon hiding a Stimulus.
    • Examples: none yet
  • duringDisplayFn – Function – Function that is called every frame (usually every 16 ms, depending on refresh rate of the screen) that the stimulus is displayed for.
    • Examples: none yet

Fun fact:  duringDisplayFn is used to estimate the refresh rate the screen is running during the first fixation period of a block.


I will keep updating this list as more examples on how to use these important parameters get made. A website explaining the API using YUIDOC should also become available soon, so please check back often!