Current version: 1.7 ()
The following documentation is intended for more advanced users who wish to customize their reaction time (RT) script in more detail. For those looking to set up a basic RT script, please start here.
RTScript Object
A new RTScript object can be called as follows:
var rtScript = new RTScript(options);
You will also need to set up, in some way, an event handler for the keyPressed() function. For example:
function keyPress(event) {
rtScript.keyPressed(event);
}
if (window.addEventListener) {
window.addEventListener("keydown", keyPress, false);
} else if (window.attachEvent) {
document.attachEvent("onkeydown", keyPress);
} else {
document.onkeydown = function() { keyPress(event); };
}
Options for the RTScript object are set with an options object with the following possible properties:
| Property | Explanation |
|---|---|
| settings | object; more details below |
| instructions | array |
| labels | array of arrays |
| words | array of objects; more details below |
| primes | array of objects; more details below |
All array properties should start at 1 (by setting 0 to null). Each array item corresponds to a separate block in the RT task. Each of the “labels” array items should consist of a two-item array indicating the text to be displayed for the left and right labels for that block. For more examples of how to set up this task, you can look at the RT Task instructions, which includes a downloadable template.
The script outputs raw data for each trial in a series of hidden input elements, starting with the name “vv0001”. If you need access to the raw response data during the execution of the script, you may use the appropriate hook to attach a custom function that captures and uses the data.
Settings Object
The “settings” object takes the following properties:
| Property | Explanation |
|---|---|
| delay | delay between words/images, in milliseconds |
| keepRT | true: will output data for all reaction times; false: only averages, standard deviations, and error rates will be stored in output |
| randomOrder | true: words will be presented in random order; false: words will be presented sequentially |
| randomBlocks | true: blocks will be presented in random order; false: blocks will be presented sequentially |
| showLabels | true: left/right labels will be shown in the top corners of the screen during trials; false: labels will be hidden |
| showFixation | true: a + symbol will be displayed before each word to fixate attention; false: no fixation symbol will be shown |
| fixationTime | time to show fixation symbol, in milliseconds; only applicable if showFixation is set to true |
| fixationDelay | delay between fixation symbol and next word/image, in milliseconds; only applicable if showFixation is set to true |
Words Array
Each of “words” array items should consist of an array of objects that takes the following properties:
| Property | Explanation |
|---|---|
| word | string of the word to be used, or a URL of an image to be used |
| correct | string of a single letter, which is designated as the correct key to press for this word |
| display | optional; string that can include any HTML to be displayed |
| position | optional; indicates the position of the word, with acceptable values: "center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right" and "default" (center) |
| colour | optional; string of an HTML colour name or hex code, used as the colour of the word |
Primes Array
Each of “primes” array items should consist of an array of objects that takes the following properties:
| Property | Explanation |
|---|---|
| prime | string of the prime word to be used |
| word | number of the word with which the prime is associated; words are numbered starting at 1 from top to bottom |
| duration | time that prime is shown, in milliseconds |
| delay | time between prime and next word/prime, in milliseconds |
| display | optional; string that can include any HTML to be displayed |
| position | optional; indicates the position of the word, with acceptable values: "center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right" and "default" (center) |
| colour | optional; string of an HTML colour name or hex code, used as the colour of the word |
Hooks
In addition to the option properties listed above, the options object can also take hooks to attach custom functions to various points in the RT Task. Any function that is hooked to these properties will be triggered at the appropriate time. The names should be fairly self-explanatory as to when the hook is triggered:
| Property | Passed Arguments |
|---|---|
| beforeTask | function(settings) |
| afterTask | function(settings, responseTimes, finalSummaryValues) |
| beforeBlock | function(blockNum, blockObj) |
| afterBlock | function(blockNum, blockObj, responseTimes[blockNum]) |
| beforeFixation | function(blockNum, wordObj) |
| afterFixation | function(blockNum, wordObj) |
| beforePrime | function(blockNum, wordObj, primeObj) |
| afterPrime | function(blockNum, wordObj, primeObj) |
| beforeWord | function(blockNum, wordObj) |
| afterWord | function(blockNum, wordObj, [correctPressed, timeValue]) |
For example, to display whether the participant selected the correct response after each word, you can do something like this:
options.afterWord = function(index, word, response) {
var correct = (response[0] == 1) ? 'correct' : 'incorrect';
document.getElementById('instructions').innerHTML = word.wordName + ': '+ correct;
};
Block Object
Once the RTScript object has been initialized, it creates a Block object for each block in your script. Each Block contains the following properties:
| Property | Explanation |
|---|---|
| id | Block ID (e.g. “b1”) |
| left | label on the left side |
| right | label on the right side |
| instructions | text instructions displayed before the trials in the block |
| delay | delay between each word in the block, in milliseconds, unless overridden by the Word object |
| randomOrder | true: words will be presented in random order; false: words will be presented sequentially |
| fullWordList | array of all Word objects in the block |
| wordsRemaining | array of all Word objects in the block that have not yet been presented |
| currentWord | Word object currently being presented |
Word Object
Once the RTScript object has been initialized, it creates a Word object for each word in your script. Each Word contains the following properties:
| Property | Explanation |
|---|---|
| id | Word ID (e.g. “b1w5”) |
| wordName | text of word |
| correctKey | keyboard key designated as the “correct” response |
| delay | delay between current and next word, after response has been recorded |
| display | full HTML to be displayed for the word, including all positioning and colour information |
| imageURL | if the word is set as an image, the URL to the image |
| primes | array of all Prime objects associated with the Word |
Prime Object
Once the RTScript object has been initialized, it creates a Prime object for each prime in your script. Each Prime contains the following properties:
| Property | Explanation |
|---|---|
| id | Prime ID (e.g. “b1p5”) |
| primeName | text of prime |
| wordID | Word ID with which the prime is associated |
| duration | time in milliseconds to display prime |
| delay | delay time in milliseconds between current prime and next word/prime |
| display | full HTML to be displayed for the prime, including all positioning and colour information |
