Conditional Stimuli

Displaying performance-related feedback to a participant is a staple of behavioral experimentation. The QRTEngine implements a powerful method of doing such ‘conditional’ stimuli (stimuli that are displayed based on certain conditions having been satisfied). Although Qualtrics allows for ‘conditional’ branches inside their Surveys and the display of questions based on some conditions, these types of conditional display of blocks/questions are impossible to use within-trial performance related feedback. Ie, showing a participant whether they correctly or incorrectly pressed a key, whether they responded too late, etc. This is due to the QRTEngine handling the presentation of stimuli (questions) within a trial, and Qualtrics’ SurveyEngine only handling things on a block-level.

The way one would handle performance related feedback in the QRTEngine is through so-called ‘conditionals’. Basically, these are little statements (or rather, functions) that decide whether or not a specific stimulus should be shown. We have created an example task that shows the possibilities inherent to this method of giving feedback. Please download it here and import it into your Qualtrics account, as we will occasionally refer to examples in this task to help explain the different ways in which performance feedback can be given.


Let’s look at a simple example of a stimulus with a conditional component.

The marked lines indicate a new option , the conditional, has been added to this stimulus, next to the options we have seen before in the basic tutorial. The conditional, in javascript terms, is a function that the QRTEngine expects to return a boolean that will indicate whether the current stimulus should be displayed, or not. In other words, this means that the QRTEngine gets to know about whatever is behind the ‘return’ seen on line 6, which has to (indirectly) either be ‘true’ or ‘false’. IF true, the stimulus is displayed, if false, it is skipped over in this trial. The example above seems sort of redundant, because it always is true. Likewise, the example below, when added to a stimulus in Qualtrics, is redundant because it always returns false, and thus is always skipped.

However, the ‘true’ and ‘false’ in the conditional does not necessarily have to be explicitly typed out like this. So called conditional, or boolean logic, also allows us to generate these boolean values, trues and falses, but in a more dynamic way.

The example above shows the way in which this works, if we look at the example task we can see a Stimulus named ‘PressKey’, which asks us to press a key. Any letter is a valid, or allowable key, but only the ‘a’ and ‘l’ keys are correct responses. This stimulus will only be shown when either A or L is pressed. ACC, short for Accuracy, is a field that is stored in relation to any Stimulus that requires a key press, and will be 1 or 0 depending on whether the correct key was pressed or not.  QRTE.getTrialData("PressKey[ACC]") then gets this information, and compares it to 1 (or, whether it was accurate). ‘===’ is the JavaScript way of comparing variables with eachother, where ‘===’ stands for equals, which will resolve into a boolean, which will either be true or false and thus indirectly result in one of the ‘redundant’ examples that were shown above. (For a bit more explanation on Javascript conditional statements, see: http://webcheatsheet.com/javascript/if_else_switch.php)

More examples

Now the fun begins! ‘ACC’ is not the only field stored in relation to a key being pressed. The fields have been mentioned in our paper before, but for completeness sake, we include them here:

  • RT – The time it took to press the key, in milliseconds
  • RTTime – the timestamp at which the key press was registered (based on UNIX time)
  • ACC – The accuracy of the key response
  • RESP – The identity of the key response, which key was actually pressed?

Speed based feedback

Say you want to display a certain stimulus that tells the participant they were too slow in responding, or that they were really quick. You can use the example below. RT contains the speed of the key press, and if this is below (or equal to) 2 seconds, or 2000 milliseconds, the stimulus is shown. Similarly, one could use ‘>’ to check whether it is above 2000.

Key identity based feedback

In our example task, both A and L were considered correct responses, but what if you wanted to display different stimuli depending on whether A or L was pressed. The example below shows how to do just that. We use the RESP field to retrieve which key was actually pressed, and check whether that key is ‘a’ (always use lower-case letters here). Thus, this stimulus will be displayed only if ‘a’ was pressed.

 Show stimuli at random

Moving away from the respondent performance based conditionals, we can also choose to display, or not display, stimuli with for example a 50% chance of either happening. ‘chance’ is a variable that is created just for this purpose (and is thrown away after the return statement is handled). It is set to .5, which stands for a 50% chance of either happening. Math.random() generates a random uniformly distributed number between 0 and 1 (meaning each value between 0 and 1 is generated at equal chance). This randomly drawn number is then compared to our ‘chance’, and the generated number is lower, the stimulus is displayed.

 Combining examples

We can also combine several of the examples given earlier. In Boolean Logic there are so called AND, OR and NOT operators.  These operators are able to combine different booleans into one value through a specified operation, which resembles the way in which AND, OR and NOT are used in natural language. For an explanation on this, see http://www.columbia.edu/cu/lweb/help/clio/boolean_operators.html.

In JavaScript, AND is coded as ‘&&’, OR is coded as ‘||’ (two pipes) and not as ‘!’ (an exclamation mark). So, say we want to display stimulus with a 50% chance, but ONLY if the participant’s key response was quicker than 2 seconds. Basically this means – My randomly generated number is small than .5 AND my RT is below 2000. Which turns into the code in the example below:

You can combine anything you want, but learning how boolean operators behave will be very important. For example, combining even more operators can be tricky: How would you create a stimulus that is displayed either – At a 50% chance when a Correct response was given, or when the reaction time was below 1.5 seconds? The answer can be found in the example task.

Note to advanced users

As the conditional argument is a function, any computation that results in a boolean will be acceptable (although, for obvious reasons, these computations shouldn’t take too much time, as it will result in a slowing down of the experiment as a whole). For example, using Block Data, one can keep track of the rolling average of RT’s, and display a warning stimulus when this average becomes too high (Please wake up!!). Or you could calculate pi to any random precision and base your decision off of that. The possibilities are only limited by what can be calculated in a reasonable amount of time.


Hopefully this guide helps illuminate an important aspect of the QRTEngine, and behavioural experimentation as a whole. If you have any remaining questions, or want to show off the cool conditionals you’ve created, please feel free to shoot us a line at support@qrtengine.com, or post on our forums. Thanks for reading!