HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-11 16:18:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

change all numeric key codes to key strings in docs #396

Browse Source
This commit is contained in:
Becky Gilbert 2021-02-02 12:25:11 -08:00
parent 662b6c0d2e
commit bc14216254
26 changed files with 485 additions and 486 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
docs/core_library/jspsych-core.md
View File

@ -8,10 +8,10 @@ jsPsych.addNodeToEndOfTimeline(node_parameters, callback)
### Parameters
Parameter | Type | Description
--------- | ---- | -----------
node_parameters | object | An object defining a timeline. It must have, at a minimum, a `timeline` parameter with a valid timeline array as the value for that parameter.
callback | function | An optional callback function. If adding the node to the timeline requires any preloading of media assets, this callback will be triggered after preloading is compelte.
| Parameter | Type | Description |
| --------------- | -------- | ---------------------------------------- |
| node_parameters | object | An object defining a timeline. It must have, at a minimum, a `timeline` parameter with a valid timeline array as the value for that parameter. |
| callback | function | An optional callback function. If adding the node to the timeline requires any preloading of media assets, this callback will be triggered after preloading is compelte. |
### Return value
@ -151,7 +151,7 @@ Ends the current timeline. If timelines are nested, then only the timeline that
### Example
#### Loop indefinitely until a particular key is pressed
#### End timeline if a particular key is pressed
```javascript
@ -170,10 +170,10 @@ for (var i = 0; i < images.length; i++) {
var block = {
type: 'image-keyboard-response',
choices: [89, 78], // Y or N
prompt: '<p>Press Y to Continue. Press N to end this node of the experiment.</p>',
choices: ['y', 'n'],
prompt: '<p>Press "y" to Continue. Press "n" to end this node of the experiment.</p>',
on_finish: function(data) {
if (data.key_press == 78) {
if (data.key_press == 'n') {
jsPsych.endCurrentTimeline();
}
},
@ -182,8 +182,7 @@ var block = {
var after_block = {
type: 'html-keyboard-response',
stimulus: '<p>The next node</p>',
is_html: true
stimulus: '<p>The next node</p>'
}
jsPsych.init({
@ -204,9 +203,9 @@ jsPsych.endExperiment(end_message)
### Parameters
Parameter | Type | Description
--------- | ---- | -----------
end_message | string | A message to display on the screen after the experiment is over.
| Parameter | Type | Description |
| ----------- | ------ | ---------------------------------------- |
| end_message | string | A message to display on the screen after the experiment is over. |
### Return value
@ -224,11 +223,11 @@ Ends the experiment, skipping all remaining trials.
var trial = {
type: 'image-keyboard-response',
stimulus: 'image1.jpg',
choices: [89,78], // Y or N
prompt: '<p>Press Y to Continue. Press N to end the experiment</p>',
choices: ['y', 'n']
prompt: '<p>Press "y" to Continue. Press "n" to end the experiment</p>',
on_finish: function(data){
if(data.key_press == 78){
jsPsych.endExperiment('The experiment was ended by pressing N.');
if(data.key_press == "n"){
jsPsych.endExperiment('The experiment was ended by pressing "n".');
}
}
}
@ -243,9 +242,9 @@ jsPsych.finishTrial(data)
### Parameters
Parameter | Type | Description
----------|------|------------
data | object | The data to store for the trial.
| Parameter | Type | Description |
| --------- | ------ | -------------------------------- |
| data | object | The data to store for the trial. |
### Return value
@ -333,45 +332,45 @@ jsPsych.init(settings)
### Parameters
Parameter | Type | Description
----------|------|------------
settings | object | The settings object for initializing jsPsych. See table below.
| Parameter | Type | Description |
| --------- | ------ | ---------------------------------------- |
| settings | object | The settings object for initializing jsPsych. See table below. |
The settings object can contain several parameters. The only *required* parameter is `timeline`.
Parameter | Type | Description
--------- | ---- | -----------
timeline | array | An array containing the objects that describe the experiment timeline. See [Creating an Experiment: The Timeline](../overview/timeline.md).
display_element | string | The ID of an HTML element to display the experiment in. If left blank, jsPsych will use the `<body>` element to display content. All keyboard event listeners are bound to this element. In order for a keyboard event to be detected, this element must have focus (be the last thing that the subject clicked on).
on_finish | function | Function to execute when the experiment ends.
on_trial_start | function | Function to execute when a new trial begins.
on_trial_finish | function | Function to execute when a trial ends.
on_data_update | function | Function to execute every time data is stored using the `jsPsych.data.write` method. All plugins use this method to save data (via a call to `jsPsych.finishTrial`, so this function runs every time a plugin stores new data.
on_interaction_data_update | function | Function to execute every time a new interaction event occurs. Interaction events include clicking on a different window (blur), returning to the experiment window (focus), entering full screen mode (fullscreenenter), and exiting full screen mode (fullscreenexit).
on_close | function | Function to execute when the user leaves the page. Can be used, for example, to save data before the page is closed.
exclusions | object | Specifies restrictions on the browser the subject can use to complete the experiment. See list of options below.
show_progress_bar | boolean | If true, then [a progress bar](../overview/progress-bar.md) is shown at the top of the page.
message_progress_bar | string | Message to display next to the progress bar. The default is 'Completion Progress'.
auto_update_progress_bar | boolean | If true, then the progress bar at the top of the page will automatically update as every top-level timeline or trial is completed.
show_preload_progress_bar | boolean | If true, then a progress bar is displayed while media files are automatically preloaded.
preload_audio | array | An array of audio files to preload before starting the experiment.
preload_images | array | An array of image files to preload before starting the experiment.
preload_video | array | An array of video files to preload before starting the experiment.
max_load_time | numeric | The maximum number of milliseconds to wait for content to preload. If the wait time is exceeded an error message is displayed and the experiment stops. The default value is 60 seconds.
max_preload_attempts | numeric | The maximum number of attempts to preload each file in case of an error. The default value is 10. There is a small delay of 200ms between each attempt.
use_webaudio | boolean | If false, then jsPsych will not attempt to use the WebAudio API for audio playback. Instead, HTML5 Audio objects will be used. The WebAudio API offers more precise control over the timing of audio events, and should be used when possible. The default value is true.
default_iti | numeric | The default inter-trial interval in ms. The default value if none is specified is 0ms.
experiment_width | numeric | The desired width of the jsPsych container in pixels. If left undefined, the width will be 100% of the display element. Usually this is the `<body>` element, and the width will be 100% of the screen size.
minimum_valid_rt | numeric | The minimum valid response time for key presses during the experiment. Any key press response time that is less than this value will be treated as invalid and ignored. Note that this parameter only applies to _keyboard responses_, and not to other response types such as buttons and sliders. The default value is 0.
override_safe_mode | boolean | Running a jsPsych experiment directly in a web browser (e.g., by double clicking on a local HTML file) will load the page using the `file://` protocol. Some features of jsPsych don't work with this protocol. By default, when jsPsych detects that it's running on a page loaded via the `file://` protocol, it runs in _safe mode_, which automatically disables features that don't work in this context. Specifically, the use of Web Audio is disabled (audio will be played using HTML5 audio instead, even if `use_webaudio` is `true`) and video preloading is disabled (both automatic preloading and manual preloading via `preload_video`). The `override_safe_mode` parameter defaults to `false`, but you can set it to `true` to force these features to operate under the `file://` protocol. In order for this to work, you will need to disable web security (CORS) features in your browser - this is safe to do if you know what you are doing. Note that this parameter has no effect when you are running the experiment on a web server, because the page will be loaded via the `http://` or `https://` protocol.
| Parameter | Type | Description |
| -------------------------- | -------- | ---------------------------------------- |
| timeline | array | An array containing the objects that describe the experiment timeline. See [Creating an Experiment: The Timeline](../overview/timeline.md). |
| display_element | string | The ID of an HTML element to display the experiment in. If left blank, jsPsych will use the `<body>` element to display content. All keyboard event listeners are bound to this element. In order for a keyboard event to be detected, this element must have focus (be the last thing that the subject clicked on). |
| on_finish | function | Function to execute when the experiment ends. |
| on_trial_start | function | Function to execute when a new trial begins. |
| on_trial_finish | function | Function to execute when a trial ends. |
| on_data_update | function | Function to execute every time data is stored using the `jsPsych.data.write` method. All plugins use this method to save data (via a call to `jsPsych.finishTrial`, so this function runs every time a plugin stores new data. |
| on_interaction_data_update | function | Function to execute every time a new interaction event occurs. Interaction events include clicking on a different window (blur), returning to the experiment window (focus), entering full screen mode (fullscreenenter), and exiting full screen mode (fullscreenexit). |
| on_close | function | Function to execute when the user leaves the page. Can be used, for example, to save data before the page is closed. |
| exclusions | object | Specifies restrictions on the browser the subject can use to complete the experiment. See list of options below. |
| show_progress_bar | boolean | If true, then [a progress bar](../overview/progress-bar.md) is shown at the top of the page. |
| message_progress_bar | string | Message to display next to the progress bar. The default is 'Completion Progress'. |
| auto_update_progress_bar | boolean | If true, then the progress bar at the top of the page will automatically update as every top-level timeline or trial is completed. |
| show_preload_progress_bar | boolean | If true, then a progress bar is displayed while media files are automatically preloaded. |
| preload_audio | array | An array of audio files to preload before starting the experiment. |
| preload_images | array | An array of image files to preload before starting the experiment. |
| preload_video | array | An array of video files to preload before starting the experiment. |
| max_load_time | numeric | The maximum number of milliseconds to wait for content to preload. If the wait time is exceeded an error message is displayed and the experiment stops. The default value is 60 seconds. |
| max_preload_attempts | numeric | The maximum number of attempts to preload each file in case of an error. The default value is 10. There is a small delay of 200ms between each attempt. |
| use_webaudio | boolean | If false, then jsPsych will not attempt to use the WebAudio API for audio playback. Instead, HTML5 Audio objects will be used. The WebAudio API offers more precise control over the timing of audio events, and should be used when possible. The default value is true. |
| default_iti | numeric | The default inter-trial interval in ms. The default value if none is specified is 0ms. |
| experiment_width | numeric | The desired width of the jsPsych container in pixels. If left undefined, the width will be 100% of the display element. Usually this is the `<body>` element, and the width will be 100% of the screen size. |
| minimum_valid_rt | numeric | The minimum valid response time for key presses during the experiment. Any key press response time that is less than this value will be treated as invalid and ignored. Note that this parameter only applies to _keyboard responses_, and not to other response types such as buttons and sliders. The default value is 0. |
| override_safe_mode | boolean | Running a jsPsych experiment directly in a web browser (e.g., by double clicking on a local HTML file) will load the page using the `file://` protocol. Some features of jsPsych don't work with this protocol. By default, when jsPsych detects that it's running on a page loaded via the `file://` protocol, it runs in _safe mode_, which automatically disables features that don't work in this context. Specifically, the use of Web Audio is disabled (audio will be played using HTML5 audio instead, even if `use_webaudio` is `true`) and video preloading is disabled (both automatic preloading and manual preloading via `preload_video`). The `override_safe_mode` parameter defaults to `false`, but you can set it to `true` to force these features to operate under the `file://` protocol. In order for this to work, you will need to disable web security (CORS) features in your browser - this is safe to do if you know what you are doing. Note that this parameter has no effect when you are running the experiment on a web server, because the page will be loaded via the `http://` or `https://` protocol. |
Possible values for the exclusions parameter above.
Parameter | Type | Description
--------- | ---- | -----------
min_width | numeric | The minimum width of the browser window. If the width is below this value, a message will be displayed to the subject asking them to maximize their browser window. The experiment will sit on this page until the browser window is large enough.
min_height | numeric | Same as above, but with height.
audio | boolean | Set to true to require support for the WebAudio API (used by plugins that play audio files).
| Parameter | Type | Description |
| ---------- | ------- | ---------------------------------------- |
| min_width | numeric | The minimum width of the browser window. If the width is below this value, a message will be displayed to the subject asking them to maximize their browser window. The experiment will sit on this page until the browser window is large enough. |
| min_height | numeric | Same as above, but with height. |
| audio | boolean | Set to true to require support for the WebAudio API (used by plugins that play audio files). |
### Return value
@ -439,7 +438,7 @@ var trial = {
stimulus: 'Press p to take a 30 second break. Otherwise, press c to continue immediately.',
choices: ['p','c'],
on_finish: function(data){
if(data.key_press == 80) { // 80 = p
if(data.key_press == "p") {
jsPsych.pauseExperiment();
setTimeout(jsPsych.resumeExperiment, 30000);
}
@ -462,11 +461,11 @@ None.
Returns an object with the following properties:
Property | Type | Description
----------|------|------------
total_trials | numeric | Indicates the number of trials in the experiment. Note that this does not count possible loops or skipped trials due to conditional statements.
current_trial_global | numeric | Returns the trial index of the current trial in a global scope. Every trial will increase this count by 1.
percent_complete | numeric | Estimates the percent of the experiment that is complete. Works as expected for experiments without conditional or looping timelines. For complex timelines, the percent is an approximation.
| Property | Type | Description |
| -------------------- | ------- | ---------------------------------------- |
| total_trials | numeric | Indicates the number of trials in the experiment. Note that this does not count possible loops or skipped trials due to conditional statements. |
| current_trial_global | numeric | Returns the trial index of the current trial in a global scope. Every trial will increase this count by 1. |
| percent_complete | numeric | Estimates the percent of the experiment that is complete. Works as expected for experiments without conditional or looping timelines. For complex timelines, the percent is an approximation. |
### Description
@ -508,7 +507,7 @@ var trial = {
stimulus: 'Press p to take a 30 second break. Otherwise, press c to continue immediately.',
choices: ['p','c'],
on_finish: function(data){
if(data.key_press == 80) { // 80 = p
if(data.key_press == "p") {
jsPsych.pauseExperiment();
setTimeout(jsPsych.resumeExperiment, 30000);
}
@ -525,9 +524,9 @@ jsPsych.setProgressBar(value)
### Parameters
Parameter | Type | Description
----------|------|------------
value | numeric | Proprotion (between 0 and 1) to fill the progress bar.
| Parameter | Type | Description |
| --------- | ------- | ---------------------------------------- |
| value | numeric | Proprotion (between 0 and 1) to fill the progress bar. |
### Return value
@ -578,10 +577,10 @@ jsPsych.timelineVariable(variable, call_immediate)
### Parameters
Parameter | Type | Description
----------|------|------------
variable | string | Name of the timeline variable
call_immediate | bool | Typically this parameter is `false`, or simply ommitted. When `false`, the return value is a function that returns the timeline variable. This makes `jsPsych.timelineVariable` suitable for dynamic parameters by default. If `true` the function returns the value of the timeline variable immediately.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------------------- |
| variable | string | Name of the timeline variable |
| call_immediate | bool | Typically this parameter is `false`, or simply ommitted. When `false`, the return value is a function that returns the timeline variable. This makes `jsPsych.timelineVariable` suitable for dynamic parameters by default. If `true` the function returns the value of the timeline variable immediately. |
### Return value
@ -631,7 +630,6 @@ var procedure = {
}
```
---
## jsPsych.totalTime

74
docs/core_library/jspsych-randomization.md
View File

@ -12,11 +12,11 @@ jsPsych.randomization.factorial(factors, repetitions, unpack)
### Parameters
Parameter | Type | Description
----------|------|------------
factors | object | The `factors` object should contain a property for each different factor. Each property-factor should have a value of an array, with each element of the array corresponding to a level of the factor.
repetitions | integer | The number of times to repeat each unique combination of the factors in the output sample.
unpack | boolean | If `true` then the output will be an object with a property for each factor in the original `factors` object. The value of each property-factor will be an array containing the levels of the factor in a random order. The order will be consistent across each property-factor (e.g., the first element of each property-factor will specify one unique combination of the factors). If `false`, then the return value will be an array of objects where each property-factor contains only a single value.
| Parameter | Type | Description |
| ----------- | ------- | ---------------------------------------- |
| factors | object | The `factors` object should contain a property for each different factor. Each property-factor should have a value of an array, with each element of the array corresponding to a level of the factor. |
| repetitions | integer | The number of times to repeat each unique combination of the factors in the output sample. |
| unpack | boolean | If `true` then the output will be an object with a property for each factor in the original `factors` object. The value of each property-factor will be an array containing the levels of the factor in a random order. The order will be consistent across each property-factor (e.g., the first element of each property-factor will specify one unique combination of the factors). If `false`, then the return value will be an array of objects where each property-factor contains only a single value. |
### Return value
@ -99,9 +99,9 @@ jsPsych.randomization.randomID(length)
### Parameters
Parameter | Type | Description
----------|------|------------
length | integer | The length of the randomly generated ID
| Parameter | Type | Description |
| --------- | ------- | --------------------------------------- |
| length | integer | The length of the randomly generated ID |
### Return value
@ -132,11 +132,11 @@ jsPsych.randomization.repeat(array, repetitions, unpack)
### Parameters
Parameter | Type | Description
----------|------|------------
array | array | The array of values to randomize & repeat.
repetitions | integer or array | The number of times to repeat each element of the `array` in the final sample. If this parameter is defined as an integer, then each element of `array` is repeated the same number of times. This parameter can also be an array of the same length as `array`, in which case each element of `array` will be repeated the number of times defined in the corresponding position of the `repetitions` array.
unpack | boolean | If each element of `array` is an object with an equivalent set of properties, then setting `unpack` to `true` will make the return value an object with a property for each of the unique properties among the elements of the `array`. Each property in the output object will be an array containing the values for that property in the randomized order. The order will be consistent across properties. If this is `false` then the output is just an array containing a randomized order of the original `array` elements.
| Parameter | Type | Description |
| ----------- | ---------------- | ---------------------------------------- |
| array | array | The array of values to randomize & repeat. |
| repetitions | integer or array | The number of times to repeat each element of the `array` in the final sample. If this parameter is defined as an integer, then each element of `array` is repeated the same number of times. This parameter can also be an array of the same length as `array`, in which case each element of `array` will be repeated the number of times defined in the corresponding position of the `repetitions` array. |
| unpack | boolean | If each element of `array` is an object with an equivalent set of properties, then setting `unpack` to `true` will make the return value an object with a property for each of the unique properties among the elements of the `array`. Each property in the output object will be an array containing the values for that property in the randomized order. The order will be consistent across properties. If this is `false` then the output is just an array containing a randomized order of the original `array` elements. |
### Return value
@ -176,19 +176,19 @@ var shuffledArray = jsPsych.randomization.repeat(myArray, 2);
var trial1 = {
stimulus: 'img/faceA.jpg',
correct_key: 80,
correct_key: 'p',
person_name: 'Joe'
}
var trial2 = {
stimulus: 'img/faceB.jpg',
correct_key: 80,
correct_key: 'p',
person_name: 'Fred'
}
var trial3 = {
stimulus: 'img/faceC.jpg',
correct_key: 81,
correct_key: 'q',
person_name: 'Mary'
}
@ -204,19 +204,19 @@ var shuffledArray = jsPsych.randomization.repeat(myArray, 2);
var trial1 = {
stimulus: 'img/faceA.jpg',
correct_key: 80,
correct_key: 'p',
person_name: 'Joe'
}
var trial2 = {
stimulus: 'img/faceB.jpg',
correct_key: 80,
correct_key: 'p',
person_name: 'Fred'
}
var trial3 = {
stimulus: 'img/faceC.jpg',
correct_key: 81,
correct_key: 'q',
person_name: 'Mary'
}
@ -226,8 +226,8 @@ var shuffledArray = jsPsych.randomization.repeat(myArray, 2, true);
/*
output: shuffledArray = {
stimulus: ['img/faceB.jpg','img/faceA.jpg','img/faceC.jpg','img/faceA.jpg','img/faceC.jpg','img/faceB.jpg'],
correct_key: [80, 80, 81, 80, 81, 80],
person_name: ['Fred','Joe', 'Mary', 'Joe', 'Mary', 'Fred']
correct_key: ['p', 'p', 'q', 'p', 'q', 'p'],
person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred']
}
*/
```
@ -240,11 +240,11 @@ jsPsych.randomization.sampleWithReplacement(array, sampleSize, weights)
### Parameters
Parameter | Type | Description
----------|------|------------
array | array | The array of values to sample from
sampleSize | numeric | The number of samples to draw
weights | array | The relative weight of each element in `array`. This array is normalized, so the values do not need to sum to 1. The length must match the length of `array`.
| Parameter | Type | Description |
| ---------- | ------- | ---------------------------------------- |
| array | array | The array of values to sample from |
| sampleSize | numeric | The number of samples to draw |
| weights | array | The relative weight of each element in `array`. This array is normalized, so the values do not need to sum to 1. The length must match the length of `array`. |
### Return value
@ -285,10 +285,10 @@ jsPsych.randomization.sampleWithoutReplacement(array, sampleSize)
### Parameters
Parameter | Type | Description
----------|------|------------
array | array | The array of values to sample from
sampleSize | numeric | The number of samples to draw
| Parameter | Type | Description |
| ---------- | ------- | ---------------------------------- |
| array | array | The array of values to sample from |
| sampleSize | numeric | The number of samples to draw |
### Return value
@ -319,9 +319,9 @@ jsPsych.randomization.shuffle(array)
### Parameters
Parameter | Type | Description
----------|------|------------
array | array | The array of values to shuffle
| Parameter | Type | Description |
| --------- | ----- | ------------------------------ |
| array | array | The array of values to shuffle |
### Return value
@ -352,10 +352,10 @@ jsPsych.randomization.shuffleNoRepeats(array, equalityTest)
### Parameters
Parameter | Type | Description
----------|------|------------
array | array | The array of values to shuffle
equalityTest | function | A function to use to evaluate the equality of neighbors in the array. The function should accept two parameters, which are the two elements to be tested. It should return `true` if they are equal and `false` if not. The default function, if none is specified, is to use the `===` operator. This will work for primitive values, but fail for Objects and Arrays. An example function is given below in the examples.
| Parameter | Type | Description |
| ------------ | -------- | ---------------------------------------- |
| array | array | The array of values to shuffle |
| equalityTest | function | A function to use to evaluate the equality of neighbors in the array. The function should accept two parameters, which are the two elements to be tested. It should return `true` if they are equal and `false` if not. The default function, if none is specified, is to use the `===` operator. This will work for primitive values, but fail for Objects and Arrays. An example function is given below in the examples. |
### Return value

2
docs/overview/callbacks.md
View File

@ -46,7 +46,7 @@ var trial = {
type: 'image-keyboard-response',
stimulus: 'imgA.png',
on_finish: function(data) {
if(data.key_press == 85){
if(data.key_press == 'j'){
data.correct = true;
} else {
data.correct = false;

2
docs/overview/data.md
View File

@ -61,7 +61,7 @@ var trial = {
type: 'image-keyboard-response',
stimulus: 'imgA.jpg',
on_finish: function(data){
if(data.key_press == 65){
if(data.key_press == 'j'){
data.correct = true;
} else {
data.correct = false;

4
docs/overview/trial.md
View File

@ -74,7 +74,7 @@ var trial = {
target_direction: 'left'
},
on_finish: function(data){
if(data.key_press == 70){// 70 is the numeric code for f
if(data.key_press == "f"){
data.correct = true; // can add property correct by modify data object directly
} else {
data.correct = false;
@ -117,7 +117,7 @@ var trial = {
target_direction: 'left'
},
on_finish: function(data){
if(data.key_press == 70){// 70 is the numeric code for f
if(data.key_press == "f"){
data.correct = true; // can add property correct by modify data object directly
} else {
data.correct = false;

2
docs/plugins/jspsych-animation.md
View File

@ -12,7 +12,7 @@ stimuli | array | *undefined* | Each element of the array is a path to an image
frame_time | numeric | 250 | How long to display each image (in milliseconds).
frame_isi | numeric | 0 | If greater than 0, then a gap will be shown between each image in the sequence. This parameter specifies the length of the gap.
sequence_reps | numeric | 1 | How many times to show the entire sequence. There will be no gap (other than the gap specified by `frame_isi`) between repetitions.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key(s) to press).
render_on_canvas | boolean | true | If true, the images will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive images in some browsers, like Firefox and Edge. If false, the image will be shown via an img element, as in previous versions of jsPsych.

32
docs/plugins/jspsych-audio-button-response.md
View File

@ -12,27 +12,27 @@ The trial can end when the subject responds, when the audio file has finished pl
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | audio file | *undefined* | Path to audio file to be played.
choices | array of strings | *undefined* | Labels for the buttons. Each different string in the array will generate a different button.
button_html | HTML string | `'<button class="jspsych-btn">%choice%</button>'` | A template of HTML for generating the button elements. You can override this to create customized buttons of various kinds. The string `%choice%` will be changed to the corresponding element of the `choices` array. You may also specify an array of strings, if you need different HTML to render for each button. If you do specify an array, the `choices` array and this array must have the same length. The HTML from position 0 in the `button_html` array will be used to create the button for element 0 in the `choices` array, and so on.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, the trial will wait for a response indefinitely.
margin_vertical | string | '0px' | Vertical margin of the button(s).
margin_horizontal | string | '8px' | Horizontal margin of the button(s).
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete.
trial_ends_after_audio | boolean | false | If true, then the trial will end as soon as the audio file finishes playing.
response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before the button choices are enabled and a response is accepted. Once the audio has played all the way through, the buttons are enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls).
| Parameter | Type | Default Value | Description |
| ------------------------------ | ---------------- | ---------------------------------------- | ---------------------------------------- |
| stimulus | audio file | *undefined* | Path to audio file to be played. |
| choices | array of strings | *undefined* | Labels for the buttons. Each different string in the array will generate a different button. |
| button_html | HTML string | `'<button class="jspsych-btn">%choice%</button>'` | A template of HTML for generating the button elements. You can override this to create customized buttons of various kinds. The string `%choice%` will be changed to the corresponding element of the `choices` array. You may also specify an array of strings, if you need different HTML to render for each button. If you do specify an array, the `choices` array and this array must have the same length. The HTML from position 0 in the `button_html` array will be used to create the button for element 0 in the `choices` array, and so on. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, the trial will wait for a response indefinitely. |
| margin_vertical | string | '0px' | Vertical margin of the button(s). |
| margin_horizontal | string | '8px' | Horizontal margin of the button(s). |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete. |
| trial_ends_after_audio | boolean | false | If true, then the trial will end as soon as the audio file finishes playing. |
| response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before the button choices are enabled and a response is accepted. Once the audio has played all the way through, the buttons are enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
button_pressed | numeric | Indicates which button the subject pressed. The first button in the `choices` array is 0, the second is 1, and so on.
| Name | Type | Value |
| -------------- | ------- | ---------------------------------------- |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first began playing until the subject's response. |
| button_pressed | numeric | Indicates which button the subject pressed. The first button in the `choices` array is 0, the second is 1, and so on. |
## Examples

30
docs/plugins/jspsych-audio-keyboard-response.md
View File

@ -12,25 +12,25 @@ The trial can end when the subject responds, when the audio file has finished pl
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | audio file | undefined | Path to audio file to be played.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete.
trial_ends_after_audio | boolean | false | If true, then the trial will end as soon as the audio file finishes playing.
response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before a keyboard response is accepted. Once the audio has played all the way through, a valid keyboard response is allowed (including while the audio is being re-played via on-screen playback controls).
| Parameter | Type | Default Value | Description |
| ------------------------------ | ---------------- | ------------------ | ---------------------------------------- |
| stimulus | audio file | undefined | Path to audio file to be played. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can use set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete. |
| trial_ends_after_audio | boolean | false | If true, then the trial will end as soon as the audio file finishes playing. |
| response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before a keyboard response is accepted. Once the audio has played all the way through, a valid keyboard response is allowed (including while the audio is being re-played via on-screen playback controls). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
stimulus | string | Path to the audio file that played during the trial.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| key_press | string | Indicates which key the subject pressed. If no key was pressed before the trial ended, then the value will be `null`. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first began playing until the subject made a key response. If no key was pressed before the trial ended, then the value will be `null`. |
| stimulus | string | Path to the audio file that played during the trial. |
## Examples
@ -42,7 +42,7 @@ var trial = {
stimulus: 'sound/tone.mp3',
choices: ['e', 'i'],
prompt: "<p>Is the pitch high or low? Press 'e' for low and 'i' for high.</p>",
response_ends_trial: false
response_ends_trial: false
};
```

42
docs/plugins/jspsych-audio-slider-response.md
View File

@ -12,32 +12,32 @@ The trial can end when the subject responds, or if the subject has failed to res
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | audio file | *undefined* | Audio file to be played
labels | array of strings | [] | Labels displayed at equidistant locations on the slider. For example, two labels will be placed at the ends of the slider. Three labels would place two at the ends and one in the middle. Four will place two at the ends, and the other two will be at 33% and 67% of the slider width.
button_label | string | 'Continue' | Label of the button to end the trial.
min | integer | 0 | Sets the minimum value of the slider
max | integer | 100 | Sets the maximum value of the slider
slider_start | integer | 50 | Sets the starting value of the slider
step | integer | 1 | Sets the step of the slider. This is the smallest amount by which the slider can change.
slider_width | integer | null | Set the width of the slider in pixels. If left null, then the width will be equal to the widest element in the display.
require_movement | boolean | false | If true, the subject must move the slider before clicking the continue button.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete.
response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before the slider is enabled and the trial can end via the next button click. Once the audio has played all the way through, the slider is enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls).
| Parameter | Type | Default Value | Description |
| ------------------------------ | ---------------- | ------------- | ---------------------------------------- |
| stimulus | audio file | *undefined* | Audio file to be played |
| labels | array of strings | [] | Labels displayed at equidistant locations on the slider. For example, two labels will be placed at the ends of the slider. Three labels would place two at the ends and one in the middle. Four will place two at the ends, and the other two will be at 33% and 67% of the slider width. |
| button_label | string | 'Continue' | Label of the button to end the trial. |
| min | integer | 0 | Sets the minimum value of the slider |
| max | integer | 100 | Sets the maximum value of the slider |
| slider_start | integer | 50 | Sets the starting value of the slider |
| step | integer | 1 | Sets the step of the slider. This is the smallest amount by which the slider can change. |
| slider_width | integer | null | Set the width of the slider in pixels. If left null, then the width will be equal to the widest element in the display. |
| require_movement | boolean | false | If true, the subject must move the slider before clicking the continue button. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete. |
| response_allowed_while_playing | boolean | true | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before the slider is enabled and the trial can end via the next button click. Once the audio has played all the way through, the slider is enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
response | numeric | The numeric value of the slider.
rt | numeric | The time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
stimulus | string | The path of the audio file that was played.
slider_start | numeric | The starting value of the slider.
| Name | Type | Value |
| ------------ | ------- | ---------------------------------------- |
| response | numeric | The numeric value of the slider. |
| rt | numeric | The time in milliseconds for the subject to make a response. The time is measured from when the stimulus first began playing until the subject's response. |
| stimulus | string | The path of the audio file that was played. |
| slider_start | numeric | The starting value of the slider. |
## Examples

26
docs/plugins/jspsych-canvas-keyboard-response.md
View File

@ -6,24 +6,24 @@ This plugin can be used to draw a stimulus on a [HTML canvas element](https://ww
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | function | *undefined* | The function to draw on the canvas. This function automatically takes a canvas element as its only argument, e.g. `function(c) {...}` or `function drawStim(c) {...}`, where `c` refers to the canvas element. Note that the stimulus function will still generally need to set the correct context itself, using a line like `let ctx = c.getContext("2d")`.
canvas_size | array | [500, 500] | Array that defines the size of the canvas element in pixels. First value is height, second value is width.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
stimulus_duration | numeric | null | How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends.
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can use this parameter to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
| Parameter | Type | Default Value | Description |
| ------------------- | ---------------- | ------------------ | ---------------------------------------- |
| stimulus | function | *undefined* | The function to draw on the canvas. This function automatically takes a canvas element as its only argument, e.g. `function(c) {...}` or `function drawStim(c) {...}`, where `c` refers to the canvas element. Note that the stimulus function will still generally need to set the correct context itself, using a line like `let ctx = c.getContext("2d")`. |
| canvas_size | array | [500, 500] | Array that defines the size of the canvas element in pixels. First value is height, second value is width. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| stimulus_duration | numeric | null | How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends. |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can use this parameter to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| key_press | string | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
Note: the canvas stimulus is *not* included in the trial data because it is a function. Any stimulus information that should be saved in the trial data can be added via the `data` parameter.

48
docs/plugins/jspsych-categorize-animation.md
View File

@ -6,31 +6,31 @@ The categorize animation plugin shows a sequence of images at a specified frame
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimuli | array | *undefined* | Each element of the array is a path to an image file.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
key_answer | numeric | *undefined* | A [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) indicating the correct response.
text_answer | string | "" | A text label that describes the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters.
correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below).
incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below).
frame_time | numeric | 500 | How long to display each image (in milliseconds).
sequence_reps | numeric | 1 | How many times to show the entire sequence.
allow_response_before_complete | boolean | false | If true, the subject can respond before the animation sequence finishes.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
feedback_duration | numeric | 2000 | How long to show the feedback (milliseconds).
render_on_canvas | boolean | true | If true, the images will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive images in some browsers, like Firefox and Edge. If false, the image will be shown via an img element, as in previous versions of jsPsych.
| Parameter | Type | Default Value | Description |
| ------------------------------ | ---------------- | ------------------ | ---------------------------------------- |
| stimuli | array | *undefined* | Each element of the array is a path to an image file. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| key_answer | string | *undefined* | The key character indicating the correct response. |
| text_answer | string | "" | A text label that describes the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters. |
| correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below). |
| incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below). |
| frame_time | numeric | 500 | How long to display each image (in milliseconds). |
| sequence_reps | numeric | 1 | How many times to show the entire sequence. |
| allow_response_before_complete | boolean | false | If true, the subject can respond before the animation sequence finishes. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| feedback_duration | numeric | 2000 | How long to show the feedback (milliseconds). |
| render_on_canvas | boolean | true | If true, the images will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive images in some browsers, like Firefox and Edge. If false, the image will be shown via an img element, as in previous versions of jsPsych. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | JSON | JSON encoded representation of the array of stimuli displayed in the trial.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject got the correct answer, `false` otherwise.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| stimulus | JSON | JSON encoded representation of the array of stimuli displayed in the trial. |
| key_press | string | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject got the correct answer, `false` otherwise. |
## Examples
@ -40,8 +40,8 @@ correct | boolean | `true` if the subject got the correct answer, `false` otherw
var animation_trial = {
type: 'categorize-animation',
stimuli: ["img/face_3.jpg", "img/face_2.jpg", "img/face_4.jpg", "img/face_1.jpg"],
choices: [80, 81], // 80 = 'p', 81 = 'q'
key_answer: 81, // correct answer is 'q' for both trials
choices: ['p', 'q'],
key_answer: 'q',
};
```
@ -51,8 +51,8 @@ var animation_trial = {
var animation_trial = {
type: 'categorize-animation',
stimuli: ["img/face_3.jpg", "img/face_2.jpg", "img/face_4.jpg", "img/face_1.jpg"],
choices: [80, 81], // 80 = 'p', 81 = 'q'
key_answer: 81, // correct answer is 'q' for both trials
choices: ['p', 'q'],
key_answer: 'q',
text_answer: 'Dax', // the label for the sequence is 'Dax'
correct_text: 'Correct! This was a %ANS%.',
incorrect_text: 'Incorrect. This was a %ANS%.'

51
docs/plugins/jspsych-categorize-html.md
View File

@ -6,33 +6,33 @@ The categorize html plugin shows an HTML object on the screen. The subject respo
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | html string | *undefined* | The HTML stimulus to display.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
key_answer | numeric | *undefined* | The [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) indicating the correct response.
text_answer | string | "" | A label that is associated with the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters.
correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the `%ANS%` string (see example below).
incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the `%ANS%` string (see example below).
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
force_correct_button_press | boolean | false | If set to true, then the subject must press the correct response key after feedback is given in order to advance to the next trial.
show_stim_with_feedback | boolean | true | If set to true, then the stimulus will be shown during feedback. If false, then only the text feedback will display during feedback.
show_feedback_on_timeout | boolean | false | If true, then category feedback will be displayed for an incorrect response after a timeout (trial_duration is exceeded). If false, then a timeout message will be shown.
timeout_message | string | "Please respond faster." | The message to show on a timeout non-response.
stimulus_duration | numeric | null | How long to show the stimulus for (milliseconds). If null, then the stimulus is shown until a response is given.
feedback_duration | numeric | 2000 | How long to show the feedback for (milliseconds).
trial_duration | numeric | null | The maximum time allowed for a response. If null, then the experiment will wait indefinitely for a response.
| Parameter | Type | Default Value | Description |
| -------------------------- | ---------------- | ------------------------ | ---------------------------------------- |
| stimulus | html string | *undefined* | The HTML stimulus to display. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| key_answer | string | *undefined* | The key character indicating the correct response. |
| text_answer | string | "" | A label that is associated with the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters. |
| correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the `%ANS%` string (see example below). |
| incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the `%ANS%` string (see example below). |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| force_correct_button_press | boolean | false | If set to true, then the subject must press the correct response key after feedback is given in order to advance to the next trial. |
| show_stim_with_feedback | boolean | true | If set to true, then the stimulus will be shown during feedback. If false, then only the text feedback will display during feedback. |
| show_feedback_on_timeout | boolean | false | If true, then category feedback will be displayed for an incorrect response after a timeout (trial_duration is exceeded). If false, then a timeout message will be shown. |
| timeout_message | string | "Please respond faster." | The message to show on a timeout non-response. |
| stimulus_duration | numeric | null | How long to show the stimulus for (milliseconds). If null, then the stimulus is shown until a response is given. |
| feedback_duration | numeric | 2000 | How long to show the feedback for (milliseconds). |
| trial_duration | numeric | null | The maximum time allowed for a response. If null, then the experiment will wait indefinitely for a response. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | string | Either the path to the image file or the string containing the HTML formatted content that the subject saw on this trial.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject got the correct answer, `false` otherwise.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| stimulus | string | Either the path to the image file or the string containing the HTML formatted content that the subject saw on this trial. |
| key_press | string | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject got the correct answer, `false` otherwise. |
## Examples
@ -42,11 +42,12 @@ correct | boolean | `true` if the subject got the correct answer, `false` otherw
var categorization_trial = {
type: 'categorize',
stimulus: '<p>B</p>',
key_answer: 80,
key_answer: 'p',
text_answer: 'letter',
choices: [80, 81],
choices: ['p', 'q'],
correct_text: "<p class='prompt'>Correct, this is a %ANS%.</p>",
incorrect_text: "<p class='prompt'>Incorrect, this is a %ANS%.</p>",
prompt: "<p>Press P for letter. Press Q for number.</p>"
prompt: "<p>Press p for letter. Press q for number.</p>"
};
```

48
docs/plugins/jspsych-categorize-image.md
View File

@ -6,34 +6,34 @@ The categorize image plugin shows an image object on the screen. The subject res
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | string | *undefined* | The path to the image file.
key_answer | numeric | *undefined* | The [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) indicating the correct response.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
text_answer | string | "" | A label that is associated with the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters.
correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below).
incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below).
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
force_correct_button_press | boolean | false | If set to true, then the subject must press the correct response key after feedback is given in order to advance to the next trial.
show_stim_with_feedback | boolean | true | If set to true, then the stimulus will be shown during feedback. If false, then only the text feedback will display during feedback.
show_feedback_on_timeout | boolean | false | If true, then category feedback will be displayed for an incorrect response after a timeout (trial_duration is exceeded). If false, then a timeout message will be shown.
timeout_message | string | "Please respond faster." | The message to show on a timeout non-response.
stimulus_duration | numeric | null | How long to show the stimulus for (milliseconds). If null, then the stimulus is shown until a response is given.
feedback_duration | numeric | 2000 | How long to show the feedback for (milliseconds).
trial_duration | numeric | null | The maximum time allowed for a response. If null, then the experiment will wait indefinitely for a response.
| Parameter | Type | Default Value | Description |
| -------------------------- | ---------------- | ------------------------ | ---------------------------------------- |
| stimulus | string | *undefined* | The path to the image file. |
| key_answer | string | *undefined* | The key character indicating the correct response. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| text_answer | string | "" | A label that is associated with the correct answer. Used in conjunction with the `correct_text` and `incorrect_text` parameters. |
| correct_text | string | "Correct." | String to show when the correct answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below). |
| incorrect_text | string | "Wrong." | String to show when the wrong answer is given. Can contain HTML formatting. The special string `%ANS%` can be used within the string. If present, the plugin will put the `text_answer` for the trial in place of the %ANS% string (see example below). |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| force_correct_button_press | boolean | false | If set to true, then the subject must press the correct response key after feedback is given in order to advance to the next trial. |
| show_stim_with_feedback | boolean | true | If set to true, then the stimulus will be shown during feedback. If false, then only the text feedback will display during feedback. |
| show_feedback_on_timeout | boolean | false | If true, then category feedback will be displayed for an incorrect response after a timeout (trial_duration is exceeded). If false, then a timeout message will be shown. |
| timeout_message | string | "Please respond faster." | The message to show on a timeout non-response. |
| stimulus_duration | numeric | null | How long to show the stimulus for (milliseconds). If null, then the stimulus is shown until a response is given. |
| feedback_duration | numeric | 2000 | How long to show the feedback for (milliseconds). |
| trial_duration | numeric | null | The maximum time allowed for a response. If null, then the experiment will wait indefinitely for a response. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | string | Either the path to the image file or the string containing the HTML formatted content that the subject saw on this trial.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject got the correct answer, `false` otherwise.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| stimulus | string | Either the path to the image file or the string containing the HTML formatted content that the subject saw on this trial. |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject got the correct answer, `false` otherwise. |
## Examples
@ -43,9 +43,9 @@ correct | boolean | `true` if the subject got the correct answer, `false` otherw
var categorization_trial = {
type: 'categorize-image',
stimulus: 'img/harrypotter.png',
key_answer: 71,
key_answer: 'g',
text_answer: 'Gryffindor',
choices: [71, 72, 82, 83],
choices: ['g', 'h', 'r', 's'],
correct_text: "<p class='prompt'>Correct! This person is a %ANS%.</p>",
incorrect_text: "<p class='prompt'>Incorrect. This person is a %ANS%.</p>",
prompt: "<p>Is this person a (G)ryffindor, (H)ufflepuff, (R)avenclaw, or (S)lytherin?</p>"

20
docs/plugins/jspsych-cloze.md
View File

@ -1,4 +1,4 @@
# jspsych-cloze
# *jspsych-cloze
This plugin displays a text with certain words removed. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Optionally, responses are evaluated and a function is called in case of differences, making it possible to inform participants about mistakes.
@ -6,20 +6,20 @@ This plugin displays a text with certain words removed. Participants are asked t
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
text | string | undefined | The cloze text to be displayed. Blanks are indicated by %% signs and automatically replaced by input fields. If there is a correct answer you want the system to check against, it must be typed between the two percentage signs (i.e. % correct solution %).
button_text | string | OK | Text of the button participants have to press for finishing the cloze test.
check_answers | boolean | false | Boolean value indicating if the answers given by participants should be compared against a correct solution given in the text (between % signs) after the button was clicked. If ```true```, answers are checked and in case of differences, the ```mistake_fn``` is called. In this case, the trial does not automatically finish. If ```false```, no checks are performed and the trial automatically ends when clicking the button.
mistake_fn | function | ```function(){}``` | Function called if ```check_answers``` is set to ```true``` and there is a difference between the participants answers and the correct solution provided in the text.
| Parameter | Type | Default Value | Description |
| ------------- | -------- | ------------------ | ---------------------------------------- |
| text | string | *undefined* | The cloze text to be displayed. Blanks are indicated by %% signs and automatically replaced by input fields. If there is a correct answer you want the system to check against, it must be typed between the two percentage signs (i.e. % correct solution %). |
| button_text | string | OK | Text of the button participants have to press for finishing the cloze test. |
| check_answers | boolean | false | Boolean value indicating if the answers given by participants should be compared against a correct solution given in the text (between % signs) after the button was clicked. If ```true```, answers are checked and in case of differences, the ```mistake_fn``` is called. In this case, the trial does not automatically finish. If ```false```, no checks are performed and the trial automatically ends when clicking the button. |
| mistake_fn | function | ```function(){}``` | Function called if ```check_answers``` is set to ```true``` and there is a difference between the participants answers and the correct solution provided in the text. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
answers | array of strings | Answers the partcipant gave
| Name | Type | Value |
| ------- | ---------------- | --------------------------- |
| answers | array of strings | Answers the partcipant gave |
## Examples

24
docs/plugins/jspsych-external-html.md
View File

@ -6,23 +6,23 @@ The HTML plugin displays an external HTML document (often a consent form). Eithe
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
url | string | *undefined* | The URL of the page to display.
cont_key | numeric | null | The key code a key to advance to the next trial. If left as null, then the subject will not be able to advance trials using the keyboard.
cont_btn | string | null | The ID of a clickable element on the page. When the element is clicked, the trial will advance.
check_fn | function | `function(){ return true; }` | This function is called with the jsPsych `display_element` as the only argument when the subject attempts to advance the trial. The trial will only advance if the function return `true`. This can be used to verify that the subject has correctly filled out a form before continuing, for example.
force_refresh | boolean | false | If `true`, then the plugin will avoid using the cached version of the HTML page to load if one exists.
execute_script | boolean | false | If `true`, then scripts on the remote page will be executed.
| Parameter | Type | Default Value | Description |
| -------------- | -------- | ---------------------------- | ---------------------------------------- |
| url | string | *undefined* | The URL of the page to display. |
| cont_key | string | null | The key character the subject can use to advance to the next trial. If left as null, then the subject will not be able to advance trials using the keyboard. |
| cont_btn | string | null | The ID of a clickable element on the page. When the element is clicked, the trial will advance. |
| check_fn | function | `function(){ return true; }` | This function is called with the jsPsych `display_element` as the only argument when the subject attempts to advance the trial. The trial will only advance if the function return `true`. This can be used to verify that the subject has correctly filled out a form before continuing, for example. |
| force_refresh | boolean | false | If `true`, then the plugin will avoid using the cached version of the HTML page to load if one exists. |
| execute_script | boolean | false | If `true`, then scripts on the remote page will be executed. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
url | string | The URL of the page.
rt | numeric | The response time in milliseconds for the subject to finish the trial.
| Name | Type | Value |
| ---- | ------- | ---------------------------------------- |
| url | string | The URL of the page. |
| rt | numeric | The response time in milliseconds for the subject to finish the trial. |
## Examples

26
docs/plugins/jspsych-html-keyboard-response.md
View File

@ -7,24 +7,24 @@ This plugin displays HTML content and records responses generated with the keybo
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | HTML string | *undefined* | The string to be displayed.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
stimulus_duration | numeric | null | How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends.
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
| Parameter | Type | Default Value | Description |
| ------------------- | ---------------- | ------------------ | ---------------------------------------- |
| stimulus | HTML string | *undefined* | The string to be displayed. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| stimulus_duration | numeric | null | How long to display the stimulus in milliseconds. The visibility CSS property of the stimulus will be set to `hidden` after this time has elapsed. If this is null, then the stimulus will remain visible until the trial ends. |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
stimulus | string | The HTML content that was displayed on the screen.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| stimulus | string | The HTML content that was displayed on the screen. |
## Examples

34
docs/plugins/jspsych-image-keyboard-response.md
View File

@ -7,28 +7,28 @@ This plugin displays and image and records responses generated with the keyboard
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | string | *undefined* | The path of the image file to be displayed.
stimulus_height | integer | null | Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height.
stimulus_width | integer | null | Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width.
maintain_aspect_ration | boolean | true | If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled to maintain the image's aspect ratio.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
stimulus_duration | numeric | null | How long to show the stimulus for in milliseconds. If the value is null, then the stimulus will be shown until the subject makes a response.
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
render_on_canvas | boolean | true | If true, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge. If false, the image will be shown via an img element, as in previous versions of jsPsych.
| Parameter | Type | Default Value | Description |
| --------------------- | ---------------- | ------------------ | ---------------------------------------- |
| stimulus | string | *undefined* | The path of the image file to be displayed. |
| stimulus_height | integer | null | Set the height of the image in pixels. If left null (no value specified), then the image will display at its natural height. |
| stimulus_width | integer | null | Set the width of the image in pixels. If left null (no value specified), then the image will display at its natural width. |
| maintain_aspect_ratio | boolean | true | If setting *only* the width or *only* the height and this parameter is true, then the other dimension will be scaled to maintain the image's aspect ratio. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| stimulus_duration | numeric | null | How long to show the stimulus for in milliseconds. If the value is `null`, then the stimulus will be shown until the subject makes a response. |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is `null`, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete. |
| render_on_canvas | boolean | true | If `true`, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge. If `false`, the image will be shown via an img element, as in previous versions of jsPsych. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
stimulus | string | The path of the image that was displayed.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| stimulus | string | The path of the image that was displayed. |
## Examples

32
docs/plugins/jspsych-instructions.md
View File

@ -6,27 +6,27 @@ This plugin is for showing instructions to the subject. It allows subjects to na
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
pages | array | *undefined* | Each element of the array is the content for a single page. Each page should be an HTML-formatted string.
key_forward | key code | 'rightarrow' | This is the key that the subject can press in order to advance to the next page. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`).
key_backward | key code | 'leftarrow' | This is the key that the subject can press to return to the previous page.
allow_backward | boolean | true | If true, the subject can return to previous pages of the instructions. If false, they may only advace to the next page.
allow_keys | boolean | true | If true, the subject can use keyboard keys to navigate the pages. If false, they may not.
show_clickable_nav | boolean | false | If true, then a `Previous` and `Next` button will be displayed beneath the instructions. Subjects can click the buttons to navigate.
button_label_previous | string | 'Previous' | The text that appears on the button to go backwards.
button_label_next | string | 'Next' | The text that appears on the button to go forwards.
show_page_number | boolean | false | If true, and clickable navigation is enabled, then Page x/y will be shown between the nav buttons.
page_label | string | 'Page' | The text that appears before x/y pages displayed when show_page_number is true.
| Parameter | Type | Default Value | Description |
| --------------------- | ------- | ------------- | ---------------------------------------- |
| pages | array | *undefined* | Each element of the array is the content for a single page. Each page should be an HTML-formatted string. |
| key_forward | string | 'ArrowRight' | This is the key that the subject can press in order to advance to the next page. This key should be specified as a string (e.g., `'a'`, `'ArrowLeft'`, `' '`, `'Enter'`). |
| key_backward | string | 'ArrowLeft' | This is the key that the subject can press to return to the previous page. This key should be specified as a string (e.g., `'a'`, `'ArrowLeft'`, `' '`, `'Enter'`). |
| allow_backward | boolean | true | If true, the subject can return to previous pages of the instructions. If false, they may only advace to the next page. |
| allow_keys | boolean | true | If `true`, the subject can use keyboard keys to navigate the pages. If `false`, they may not. |
| show_clickable_nav | boolean | false | If true, then a `Previous` and `Next` button will be displayed beneath the instructions. Subjects can click the buttons to navigate. |
| button_label_previous | string | 'Previous' | The text that appears on the button to go backwards. |
| button_label_next | string | 'Next' | The text that appears on the button to go forwards. |
| show_page_number | boolean | false | If true, and clickable navigation is enabled, then Page x/y will be shown between the nav buttons. |
| page_label | string | 'Page' | The text that appears before x/y pages displayed when show_page_number is true. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
view_history | JSON string | A JSON string containing the order of pages the subject viewed (including when the subject returned to previous pages) and the time spent viewing each page.
rt | numeric | The response time in milliseconds for the subject to view all of the pages.
| Name | Type | Value |
| ------------ | ----------- | ---------------------------------------- |
| view_history | JSON string | A JSON string containing the order of pages the subject viewed (including when the subject returned to previous pages) and the time spent viewing each page. |
| rt | numeric | The response time in milliseconds for the subject to view all of the pages. |
## Example

90
docs/plugins/jspsych-rdk.md
View File

@ -5,44 +5,44 @@ This plugin displays a Random Dot Kinematogram (RDK) and allows the subject to r
We would appreciate it if you cited this paper when you use the RDK:
<b>Rajananda, S., Lau, H. & Odegaard, B., (2018). A Random-Dot Kinematogram for Web-Based Vision Research. Journal of Open Research Software. 6(1), p.6. DOI: [http://doi.org/10.5334/jors.194]</b>
For optimal performance, fullscreen mode should be manually triggered by the user (e.g. F11 key in Chrome for Windows). Usage of the default Fullscreen trigger from the JsPsych API library with this plugin might result in the stimuli being displayed incorrectly.
For optimal performance, fullscreen mode should be manually triggered by the user (e.g. F11 key in Chrome for Windows). Usage of the default Fullscreen trigger from the jsPsych API library with this plugin might result in the stimuli being displayed incorrectly.
## Parameters
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Parameters can be left unspecified if the default value is acceptable.
|Parameter|Type|Default Value| Descripton|
|---------|----|-------------|-----------|
|choices|array|[]|The valid keys that the subject can press as a response. Must be an array of chars or numbers (corresponding to JavaScript character codes). If left unspecified, any key is a valid key.|
|correct_choice|array, char, or number|undefined|The keys that are considered the correct response for that particular trial. Can be a single char, a single number, an array of chars, or an array of numbers. Numbers here correspond to the JavaScript character codes. This needs to be linked with the `coherent_direction` parameter (See Examples section below for an illustration.) This is used to determine whether the subject chose the correct response. The boolean indicating whether or not the subject chose the correct response is returned in the `correct` key of the data object. |
|trial_duration|numeric|500|The amount of time that the stimulus is displayed on the screen in ms. If -1, the stimulus will be displayed until the subject keys in a valid response. (`choices` parameter must contain valid keys or else the stimuli will run indefinitely).|
|response_ends_trial|boolean|true|If true, then the subject's response will end the trial. If false, the stimuli will be presented for the full `trial_duration` (the response will be recorded as long as the subject responds within the trial duration).|
|number_of_apertures|numeric|1|The number of apertures or RDKs on the screen. If set to more than one, remember to set the location (i.e., aperture_center_x and aperture_center_y) parameters to separate them. <br>In addition, each aperture can be customized individually by passing in an array of values as the parameter (see example below). If a single value (not an array) is passed as the parameter, then all apertures will have the same parameter.|
|number_of_dots|numeric|300|Number of dots per set. Equivalent to number of dots per frame.|
|number_of_sets|numeric|1|Number of sets to cycle through. Each frame displays one set of dots. (E.g. If 2 sets of dots, frame 1 will display dots from set 1, frame 2 will display dots from set 2, frame 3 will display sets from set 1, etc.)|
|coherent_direction|numeric|0|The direction of movement for coherent dots in degrees. 0 degrees is in the 3 o'clock direction, and increasing this number moves counterclockwise. (E.g. 12 o'clock is 90, 9 o'clock is 180, etc.) Range is 0 - 360.|
|coherence|numeric|0.5|The proportion of dots that move together in the coherent direction. Range is 0 to 1.|
|opposite_coherence|numeric|0|The proportion of moving in the direction opposite of the coherent direction. Range is 0 to (1-coherence).|
|dot_radius|numeric|2|The radius of each individual dot in pixels.|
|dot_life|numeric|-1|The number of frames that pass before a dot disappears and reappears in a new frame. -1 denotes that the dot life is infinite (i.e., a dot will only disappear and reappear if it moves out of the aperture).|
|move_distance|numeric|1|The number of pixel lengths the dot will move in each frame (analogous to speed of dots).|
|aperture_width|numeric|600|The width of the aperture in pixels. For a square aperture, this will determine both the width and height. For circular aperture, this will determine the diameter.|
|aperture_height|numeric|400|The height of the aperture in pixels. For square and circle apertures, this will be ignored.|
|dot_color|string|"white"|The color of the dots.|
|background_color|string|"gray"|The color of the background.|
|RDK_type|numeric|3|The Signal Selection Rule (Same/Different) and Noise Type (Random Position/Walk/Direction):<br><br>1 - Same && Random Position<br>2 - Same && Random Walk<br>3 - Same && Random Direction<br>4 - Different && Random Position<br>5 - Different && Random Walk<br>6 - Different && Random Direction<br><br>(See 'RDK parameter' below for more detailed information)<br>|
|aperture_type|numeric|2|The shape of the aperture.<br><br>1 - Circle<br>2 - Ellipse<br>3 - Square<br>4 - Rectangle<br>|
|reinsert_type|numeric|2|The type of reinsertion of a dot that has gone out of bounds<br><br>1 - Randomly appear anywhere in the aperture<br>2 - Appear on the opposite edge of the aperture. For squares and rectangles, a random point on the opposite edge is chosen as the reinsertion point. For circles and ellipses, the exit point is reflected about center to become the reinsertion point.<br>|
|aperture_center_x|numeric|window.innerWidth/2|The x-coordinate of the center of the aperture, in pixels.<br>|
|aperture_center_y|numeric|window.innerHeight/2|The y-coordinate of the center of the aperture, in pixels.<br>|
|fixation_cross|boolean|false|Whether or not a fixation cross is presented in the middle of the screen.<br>|
|fixation_cross_width|numeric|20|The width of the fixation cross in pixels.<br>|
|fixation_cross_height|numeric|20|The height of the fixation cross in pixels.<br>|
|fixation_cross_color|string|"black"|The color of the fixation cross.<br>|
|fixation_cross_thickness|numeric|1|The thickness of the fixation cross in pixels.<br>|
|border|boolean|false|The presence of a border around the aperture.<br>|
|border_thickness|numeric|1|The thickness of the border in pixels.<br>|
|border_color|string|"black"|The color of the border.<br>|
| Parameter | Type | Default Value | Descripton |
| ------------------------ | ---------------- | -------------------- | ---------------------------------------- |
| choices | array of strings | jsPsych.ALL_KEYS | The valid keys that the subject can press as a response. Must be an array of strings. If left unspecified, any key is a valid key. |
| correct_choice | array or string | *undefined* | The keys that are considered the correct response for that particular trial. Can be a single string or an array of strings. This needs to be linked with the `coherent_direction` parameter (see Examples section below for an illustration). This is used to determine whether the subject chose the correct response. The boolean indicating whether or not the subject chose the correct response is returned in the `correct` key of the data object. |
| trial_duration | numeric | 500 | The amount of time that the stimulus is displayed on the screen in ms. If -1, the stimulus will be displayed until the subject keys in a valid response. (`choices` parameter must contain valid keys or else the stimuli will run indefinitely). |
| response_ends_trial | boolean | true | If `true`, then the subject's response will end the trial. If `false`, the stimuli will be presented for the full `trial_duration` (the response will be recorded as long as the subject responds within the trial duration). |
| number_of_apertures | numeric | 1 | The number of apertures or RDKs on the screen. If set to more than one, remember to set the location (i.e., aperture_center_x and aperture_center_y) parameters to separate them. <br>In addition, each aperture can be customized individually by passing in an array of values as the parameter (see example below). If a single value (not an array) is passed as the parameter, then all apertures will have the same parameter. |
| number_of_dots | numeric | 300 | Number of dots per set. Equivalent to number of dots per frame. |
| number_of_sets | numeric | 1 | Number of sets to cycle through. Each frame displays one set of dots. (E.g. If 2 sets of dots, frame 1 will display dots from set 1, frame 2 will display dots from set 2, frame 3 will display sets from set 1, etc.) |
| coherent_direction | numeric | 0 | The direction of movement for coherent dots in degrees. 0 degrees is in the 3 o'clock direction, and increasing this number moves counterclockwise. (E.g. 12 o'clock is 90, 9 o'clock is 180, etc.) Range is 0 - 360. |
| coherence | numeric | 0.5 | The proportion of dots that move together in the coherent direction. Range is 0 to 1. |
| opposite_coherence | numeric | 0 | The proportion of moving in the direction opposite of the coherent direction. Range is 0 to (1-coherence). |
| dot_radius | numeric | 2 | The radius of each individual dot in pixels. |
| dot_life | numeric | -1 | The number of frames that pass before a dot disappears and reappears in a new frame. -1 denotes that the dot life is infinite (i.e., a dot will only disappear and reappear if it moves out of the aperture). |
| move_distance | numeric | 1 | The number of pixel lengths the dot will move in each frame (analogous to speed of dots). |
| aperture_width | numeric | 600 | The width of the aperture in pixels. For a square aperture, this will determine both the width and height. For circular aperture, this will determine the diameter. |
| aperture_height | numeric | 400 | The height of the aperture in pixels. For square and circle apertures, this will be ignored. |
| dot_color | string | "white" | The color of the dots. |
| background_color | string | "gray" | The color of the background. |
| RDK_type | numeric | 3 | The Signal Selection Rule (Same/Different) and Noise Type (Random Position/Walk/Direction):<br><br>1 - Same && Random Position<br>2 - Same && Random Walk<br>3 - Same && Random Direction<br>4 - Different && Random Position<br>5 - Different && Random Walk<br>6 - Different && Random Direction<br><br>(See 'RDK parameter' below for more detailed information)<br> |
| aperture_type | numeric | 2 | The shape of the aperture.<br><br>1 - Circle<br>2 - Ellipse<br>3 - Square<br>4 - Rectangle<br> |
| reinsert_type | numeric | 2 | The type of reinsertion of a dot that has gone out of bounds<br><br>1 - Randomly appear anywhere in the aperture<br>2 - Appear on the opposite edge of the aperture. For squares and rectangles, a random point on the opposite edge is chosen as the reinsertion point. For circles and ellipses, the exit point is reflected about center to become the reinsertion point.<br> |
| aperture_center_x | numeric | window.innerWidth/2 | The x-coordinate of the center of the aperture, in pixels.<br> |
| aperture_center_y | numeric | window.innerHeight/2 | The y-coordinate of the center of the aperture, in pixels.<br> |
| fixation_cross | boolean | false | Whether or not a fixation cross is presented in the middle of the screen.<br> |
| fixation_cross_width | numeric | 20 | The width of the fixation cross in pixels.<br> |
| fixation_cross_height | numeric | 20 | The height of the fixation cross in pixels.<br> |
| fixation_cross_color | string | "black" | The color of the fixation cross.<br> |
| fixation_cross_thickness | numeric | 1 | The thickness of the fixation cross in pixels.<br> |
| border | boolean | false | The presence of a border around the aperture.<br> |
| border_thickness | numeric | 1 | The thickness of the border in pixels.<br> |
| border_color | string | "black" | The color of the border.<br> |
### RDK type parameter
** See Fig. 1 in Scase, Braddick, and Raymond (1996) for a visual depiction of these different signal selection rules and noise types.
@ -61,16 +61,16 @@ In addition to the [parameters available in all plugins](overview.md#parameters-
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects all parameter data described above and the following data for each trial.
|Name|Type|Value|
|----|----|-----|
|rt|numeric|The response time in ms for the subject to make a response.|
|key_press|numeric|The key that the subject pressed. The value corresponds to the Javascript Char Code (Key Code).|
|correct|boolean|Whether or not the subject's key press corresponded to those provided in correct_choice.|
|frame_rate|numeric|The average frame rate for the trial. 0 denotes that the subject responded before the appearance of the second frame.|
|number_of_frames|numeric|The number of frames that was shown in this trial.|
|frame_rate_array|JSON string|The array that holds the number of miliseconds for each frame in this trial.|
|canvas_width|numeric|The width of the canvas in pixels.|
|canvas_height|numeric|The height of the canvas in pixels.|
| Name | Type | Value |
| ---------------- | ----------- | ---------------------------------------- |
| rt | numeric | The response time in ms for the subject to make a response. |
| key_press | string | The key that the subject pressed. |
| correct | boolean | Whether or not the subject's key press corresponded to those provided in correct_choice. |
| frame_rate | numeric | The average frame rate for the trial. 0 denotes that the subject responded before the appearance of the second frame. |
| number_of_frames | numeric | The number of frames that was shown in this trial. |
| frame_rate_array | JSON string | The array that holds the number of miliseconds for each frame in this trial. |
| canvas_width | numeric | The width of the canvas in pixels. |
| canvas_height | numeric | The height of the canvas in pixels. |
## Example
@ -79,12 +79,12 @@ In addition to the [default data collected by all plugins](overview.md#data-coll
```javascript
var trial_right = {
coherent_direction: 0,
correct_choice: "P"
correct_choice: "p"
};
var trial_left = {
coherent_direction: 180,
correct_choice: "Q"
correct_choice: "q"
};
```

4
docs/plugins/jspsych-reconstruction.md
View File

@ -13,8 +13,8 @@ Parameter | Type | Default Value | Description
stim_function | function | *undefined* | A function with a single parameter that returns an HTML-formatted string representing the stimulus.
starting_value | numeric | 0.5 | The starting value of the stimulus parameter.
step_size | numeric | 0.05 | The change in the stimulus parameter caused by pressing one of the modification keys.
key_increase | key code | 'h' | The key to press for increasing the parameter value.
key_decrease | key code | 'g' | The key to press for decreasing the parameter value.
key_increase | string | 'h' | The key to press for increasing the parameter value.
key_decrease | string | 'g' | The key to press for decreasing the parameter value.
button_label | string | 'Continue' | The text that appears on the button to finish the trial.
## Data Generated

48
docs/plugins/jspsych-same-different-html.md
View File

@ -6,36 +6,36 @@ The same-different-html plugin displays two stimuli sequentially. Stimuli are HT
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimuli | array | *undefined* | A pair of stimuli, represented as an array with two entries, one for each stimulus. A stimulus is a string containing valid HTML markup. Stimuli will be shown in the order that they are defined in the array.
answer | string | *undefined* | Either `'same'` or `'different'`.
same_key | numeric or string | 'Q' | The key that subjects should press to indicate that the two stimuli are the same.
different_key | numeric or string | 'P' | The key that subjects should press to indicate that the two stimuli are different.
first_stim_duration | numeric | 1000 | How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject presses any key.
gap_duration | numeric | 500 | How long to show a blank screen in between the two stimuli.
second_stim_duration | numeric | 1000 | How long to show the second stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject responds.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
| Parameter | Type | Default Value | Description |
| -------------------- | ------- | ------------- | ---------------------------------------- |
| stimuli | array | *undefined* | A pair of stimuli, represented as an array with two entries, one for each stimulus. A stimulus is a string containing valid HTML markup. Stimuli will be shown in the order that they are defined in the array. |
| answer | string | *undefined* | Either `'same'` or `'different'`. |
| same_key | string | 'q' | The key that subjects should press to indicate that the two stimuli are the same. |
| different_key | string | 'p' | The key that subjects should press to indicate that the two stimuli are different. |
| first_stim_duration | numeric | 1000 | How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject presses any key. |
| gap_duration | numeric | 500 | How long to show a blank screen in between the two stimuli. |
| second_stim_duration | numeric | 1000 | How long to show the second stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject responds. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | string | An JSON-encoded array of length 2 containing either the path to the image file or the string containing the HTML formatted content that the subject saw for each trial.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject's response matched the `answer` for this trial.
answer | string | The correct answer to the trial, either `'same'` or `'different'`.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| stimulus | string | An JSON-encoded array of length 2 containing the HTML-formatted content that the subject saw for each trial. |
| key_press | string | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject's response matched the `answer` for this trial. |
| answer | string | The correct answer to the trial, either `'same'` or `'different'`. |
Additionally, if `first_stim_duration` is null, then the following data is also collected:
Name | Type | Value
-----|------|------
rt_stim1 | numeric | The response time in milliseconds for the subject to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the subject's response.
key_press_stim1 | numeric | Indicates which key the subject pressed to continue. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
| Name | Type | Value |
| --------------- | ------- | ---------------------------------------- |
| rt_stim1 | numeric | The response time in milliseconds for the subject to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the subject's response. |
| key_press_stim1 | string | Indicates which key the subject pressed to continue. |
## Examples
@ -45,9 +45,9 @@ key_press_stim1 | numeric | Indicates which key the subject pressed to continue.
var trial = {
type: 'same-different-html',
stimuli: ['<p>Climbing</p>', '<p>Walking</p>'],
prompt: "<p>Press S if the texts imply the same amount of physical exertion. Press D if the texts imply different amount of physical exertion.</p>",
same_key: 'S',
different_key: 'D',
prompt: "<p>Press 's' if the texts imply the same amount of physical exertion. Press 'd' if the texts imply different amount of physical exertion.</p>",
same_key: 's',
different_key: 'd',
answer: 'different'
}
```

42
docs/plugins/jspsych-same-different-image.md
View File

@ -6,36 +6,36 @@ The same-different plugin displays two stimuli sequentially. Stimuli are image o
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimuli | array | *undefined* | A pair of stimuli, represented as an array with two entries, one for each stimulus. The stimulus is a path to an image file. Stimuli will be shown in the order that they are defined in the array.
answer | string | *undefined* | Either `'same'` or `'different'`.
same_key | numeric or string | 'Q' | The key that subjects should press to indicate that the two stimuli are the same.
different_key | numeric or string | 'P' | The key that subjects should press to indicate that the two stimuli are different.
first_stim_duration | numeric | 1000 | How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject presses any key.
gap_duration | numeric | 500 | How long to show a blank screen in between the two stimuli.
second_stim_duration | numeric | 1000 | How long to show the second stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject responds.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
| Parameter | Type | Default Value | Description |
| -------------------- | ------- | ------------- | ---------------------------------------- |
| stimuli | array | *undefined* | A pair of stimuli, represented as an array with two entries, one for each stimulus. The stimulus is a path to an image file. Stimuli will be shown in the order that they are defined in the array. |
| answer | string | *undefined* | Either `'same'` or `'different'`. |
| same_key | string | 'q' | The key that subjects should press to indicate that the two stimuli are the same. |
| different_key | string | 'p' | The key that subjects should press to indicate that the two stimuli are different. |
| first_stim_duration | numeric | 1000 | How long to show the first stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject presses any key. |
| gap_duration | numeric | 500 | How long to show a blank screen in between the two stimuli. |
| second_stim_duration | numeric | 1000 | How long to show the second stimulus for in milliseconds. If the value of this parameter is null then the stimulus will be shown until the subject responds. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | string | An JSON-encoded array of length 2 containing either the path to the image file or the string containing the HTML formatted content that the subject saw for each trial.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject's response matched the `answer` for this trial.
answer | string | The correct answer to the trial, either `'same'` or `'different'`.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| stimulus | string | An JSON-encoded array of length 2 containing the paths to the image files that the subject saw for each trial. |
| key_press | string | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject's response matched the `answer` for this trial. |
| answer | string | The correct answer to the trial, either `'same'` or `'different'`. |
Additionally, if `first_stim_duration` is null, then the following data is also collected:
Name | Type | Value
-----|------|------
rt_stim1 | numeric | The response time in milliseconds for the subject to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the subject's response.
key_press_stim1 | numeric | Indicates which key the subject pressed to continue. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
| Name | Type | Value |
| --------------- | ------- | ---------------------------------------- |
| rt_stim1 | numeric | The response time in milliseconds for the subject to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the subject's response. |
| key_press_stim1 | string | Indicates which key the subject pressed to continue. |
## Examples

42
docs/plugins/jspsych-serial-reaction-time.md
View File

@ -6,32 +6,32 @@ The serial reaction time plugin implements a generalized version of the SRT task
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
target | array | *undefined* | The location of the target. The array should be the `[row, column]` of the target.
grid | array | `[[1,1,1,1]]` | This array represents the grid of boxes shown on the screen. Each inner array represents a single row. The entries in the inner arrays represent the columns. If an entry is `1` then a square will be drawn at that location on the grid. If an entry is `0` then the corresponding location on the grid will be empty. Thus, by mixing `1`s and `0`s it is possible to create many different grid-based arrangements.
choices | array | `[['3','5','7','9']]` | The dimensions of this array must match the dimensions of `grid`. Each entry in this array is the key that should be pressed for that corresponding location in the grid. Entries can be left blank if there is no key associated with that location of the grid.
grid_square_size | numeric | 100 | The width and height in pixels of each square in the grid.
target_color | hex color code | `#999` | The color of the target square.
response_ends_trial | boolean | `true` | If true, the trial ends after a key press. Feedback is displayed if `show_response_feedback` is true.
pre_target_duration | numeric | 0 | The number of milliseconds to display the grid *before* the target changes color.
trial_duration | numeric | null | The maximum length of time of the trial, not including feedback.
show_response_feedback | boolean | false | If true, show feedback indicating where the user responded and whether it was correct.
feedback_duration | numeric | 200 |The length of time in milliseconds to show the feedback.
fade_duration | numeric | null | If a positive number, the target will progressively change color at the start of the trial, with the transition lasting this many milliseconds.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which keys to press).
| Parameter | Type | Default Value | Description |
| ---------------------- | ---------------- | --------------------- | ---------------------------------------- |
| target | array | *undefined* | The location of the target. The array should be the `[row, column]` of the target. |
| grid | array | `[[1,1,1,1]]` | This array represents the grid of boxes shown on the screen. Each inner array represents a single row. The entries in the inner arrays represent the columns. If an entry is `1` then a square will be drawn at that location on the grid. If an entry is `0` then the corresponding location on the grid will be empty. Thus, by mixing `1`s and `0`s it is possible to create many different grid-based arrangements. |
| choices | array of strings | `[['3','5','7','9']]` | The dimensions of this array must match the dimensions of `grid`. Each entry in this array is the key that should be pressed for that corresponding location in the grid. Entries can be left blank if there is no key associated with that location of the grid. |
| grid_square_size | numeric | 100 | The width and height in pixels of each square in the grid. |
| target_color | hex color code | `#999` | The color of the target square. |
| response_ends_trial | boolean | `true` | If true, the trial ends after a key press. Feedback is displayed if `show_response_feedback` is true. |
| pre_target_duration | numeric | 0 | The number of milliseconds to display the grid *before* the target changes color. |
| trial_duration | numeric | null | The maximum length of time of the trial, not including feedback. |
| show_response_feedback | boolean | false | If true, show feedback indicating where the user responded and whether it was correct. |
| feedback_duration | numeric | 200 | The length of time in milliseconds to show the feedback. |
| fade_duration | numeric | null | If a positive number, the target will progressively change color at the start of the trial, with the transition lasting this many milliseconds. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which keys to press). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
grid | JSON | A JSON-encoded representation of the grid.
target | JSON | A JSON-encoded representation of the target on the grid.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response.
correct | boolean | `true` if the subject's response matched the target.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| grid | JSON | A JSON-encoded representation of the grid. |
| target | JSON | A JSON-encoded representation of the target on the grid. |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the second stimulus first appears on the screen until the subject's response. |
| correct | boolean | `true` if the subject's response matched the target. |
## Examples

42
docs/plugins/jspsych-video-keyboard-response.md
View File

@ -6,32 +6,32 @@ This plugin plays a video file and records a keyboard response. The stimulus can
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimulus | array | *undefined* | An array of file paths to the video. You can specify multiple formats of the same video (e.g., .mp4, .ogg, .webm) to maximize the [cross-browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats). Usually .mp4 is a safe cross-browser option. The plugin does not reliably support .mov files. The player will use the first source file in the array that is compatible with the browser, so specify the files in order of preference.
prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press).
width | numeric | width of the video file | The width of the video display in pixels.
height | numeric | heigh of the video file | The height of the video display in pixels.
autoplay | boolean | true | If true, the video will begin playing as soon as it has loaded.
controls | boolean | false | If true, controls for the video player will be available to the subject. They will be able to pause the video or move the playback to any point in the video.
start | numeric | null | If given a value, the video will start at this time point in seconds.
stop| numeric | null | If given a value, the video will stop at this time point in seconds.
rate | numeric | null | The playback rate of the video. 1 is normal, <1 is slower, >1 is faster.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
trial_ends_after_video | bool | false | If true, then the trial will end as soon as the video file finishes playing.
trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely.
response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete.
response_allowed_while_playing | boolean | true | If true, then responses are allowed while the video is playing. If false, then the video must finish playing before a keyboard response is accepted. Once the video has played all the way through, a valid keyboard response is allowed (including while the video is being re-played via on-screen playback controls).
| Parameter | Type | Default Value | Description |
| ------------------------------ | ---------------- | ----------------------- | ---------------------------------------- |
| stimulus | array | *undefined* | An array of file paths to the video. You can specify multiple formats of the same video (e.g., .mp4, .ogg, .webm) to maximize the [cross-browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats). Usually .mp4 is a safe cross-browser option. The plugin does not reliably support .mov files. The player will use the first source file in the array that is compatible with the browser, so specify the files in order of preference. |
| prompt | string | null | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the subject is supposed to take (e.g., which key to press). |
| width | numeric | width of the video file | The width of the video display in pixels. |
| height | numeric | heigh of the video file | The height of the video display in pixels. |
| autoplay | boolean | true | If true, the video will begin playing as soon as it has loaded. |
| controls | boolean | false | If true, controls for the video player will be available to the subject. They will be able to pause the video or move the playback to any point in the video. |
| start | numeric | null | If given a value, the video will start at this time point in seconds. |
| stop | numeric | null | If given a value, the video will stop at this time point in seconds. |
| rate | numeric | null | The playback rate of the video. 1 is normal, <1 is slower, >1 is faster. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| trial_ends_after_video | bool | false | If true, then the trial will end as soon as the video file finishes playing. |
| trial_duration | numeric | null | How long to wait for the subject to make a response before ending the trial in milliseconds. If the subject fails to make a response before this timer is reached, the subject's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
| response_ends_trial | boolean | true | If true, then the trial will end whenever the subject makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the subject to view a stimulus for a fixed amount of time, even if they respond before the time is complete. |
| response_allowed_while_playing | boolean | true | If true, then responses are allowed while the video is playing. If false, then the video must finish playing before a keyboard response is accepted. Once the video has played all the way through, a valid keyboard response is allowed (including while the video is being re-played via on-screen playback controls). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
stimulus | string | JSON encoding of the `stimulus` array.
| Name | Type | Value |
| --------- | ------- | ---------------------------------------- |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| stimulus | string | JSON encoding of the `stimulus` array. |
## Example

44
docs/plugins/jspsych-visual-search-circle.md
View File

@ -8,33 +8,33 @@ This plugin presents a customizable visual-search task modelled after [Wang, Cav
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
target_present | boolean | *undefined* | Is the target present?
set_size | numeric | *undefined* | How many items should be displayed?
target | string | *undefined* | Path to image file that is the search target.
foil | string or array | *undefined* | Path to image file that is the foil/distractor. Can specify an array of distractors if the distractors are all different images.
fixation_image | string | *undefined* | Path to image file that is a fixation target.
target_size | array | `[50, 50]` | Two element array indicating the height and width of the search array element images.
fixation_size | array | `[16, 16]` | Two element array indicating the height and width of the fixation image.
circle_diameter | numeric | 250 | The diameter of the search array circle in pixels.
target_present_key | numeric | 74 | The key to press if the target is present in the search array.
target_absent_key | numeric | 70 | The key to press if the target is not present in the search array.
trial_duration | numeric | null | The maximum amount of time the subject is allowed to search before the trial will continue. A value of null will allow the subject to search indefinitely.
fixation_duration | numeric | 1000 | How long to show the fixation image for before the search array (in milliseconds).
| Parameter | Type | Default Value | Description |
| ------------------ | --------------- | ------------- | ---------------------------------------- |
| target_present | boolean | *undefined* | Is the target present? |
| set_size | numeric | *undefined* | How many items should be displayed? |
| target | string | *undefined* | Path to image file that is the search target. |
| foil | string or array | *undefined* | Path to image file that is the foil/distractor. Can specify an array of distractors if the distractors are all different images. |
| fixation_image | string | *undefined* | Path to image file that is a fixation target. |
| target_size | array | `[50, 50]` | Two element array indicating the height and width of the search array element images. |
| fixation_size | array | `[16, 16]` | Two element array indicating the height and width of the fixation image. |
| circle_diameter | numeric | 250 | The diameter of the search array circle in pixels. |
| target_present_key | string | 'j' | The key to press if the target is present in the search array. |
| target_absent_key | string | 'f' | The key to press if the target is not present in the search array. |
| trial_duration | numeric | null | The maximum amount of time the subject is allowed to search before the trial will continue. A value of null will allow the subject to search indefinitely. |
| fixation_duration | numeric | 1000 | How long to show the fixation image for before the search array (in milliseconds). |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
correct | boolean | True if the subject gave the correct response.
key_press | numeric | Indicates which key the subject pressed. The value is the [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) corresponding to the subject's response.
rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response.
set_size | numeric | The number of items in the search array
target_present | boolean | True if the target is present in the search array
locations | JSON string | JSON-encoded array where each element of the array is the pixel value of the center of an image in the search array. If the target is present, then the first element will represent the location of the target.
| Name | Type | Value |
| -------------- | ----------- | ---------------------------------------- |
| correct | boolean | True if the subject gave the correct response. |
| key_press | numeric | Indicates which key the subject pressed. |
| rt | numeric | The response time in milliseconds for the subject to make a response. The time is measured from when the stimulus first appears on the screen until the subject's response. |
| set_size | numeric | The number of items in the search array |
| target_present | boolean | True if the target is present in the search array |
| locations | JSON string | JSON-encoded array where each element of the array is the pixel value of the center of an image in the search array. If the target is present, then the first element will represent the location of the target. |
## Example

28
docs/plugins/jspsych-vsl-animate-occlusion.md
View File

@ -12,25 +12,25 @@ This plugin requires the Snap.svg library, available at [http://www.snapsvg.io](
In addition to the [parameters available in all plugins](overview.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
stimuli | array | *undefined* | Each element of the array is a stimulus. A stimulus is a path to an image file. The order of stimuli in the array determines the order of the animation sequence.
canvas_size | array | `[400, 400]` | Array specifying the width and height of the area that the animation will display in. Stimuli will move to the edges of this area, so increasing the width without increasing the `timing_cycle` parameter will speed up the images.
image_size | array | `[100, 100]` | Array specifying the width and height of the images to show. The occluding rectangle will have a width equal to the width of image_size.
initial_direction | string | "left" | Which direction the stimulus should move first (subsequent directions will alternate). Choices are "left" or "right".
occlude_center | boolean | true | If true, display a rectangle in the center of the screen that is just wide enough to occlude the image completely as it passes behind.
choices | array of keycodes | `jsPsych.ALL_KEYS` | This array contains the keys that the subject is allowed to press in order to respond to the stimulus. Keys can be specified as their [numeric key code](http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes) or as characters (e.g., `'a'`, `'q'`). The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed.
cycle_duration | numeric | 1000 | How long it takes for a stimulus in the sequence to make a complete cycle (move to the edge and back to the center) in milliseconds.
pre_movement_duration | numeric | 500 | How long to wait before the stimuli starts moving from behind the center rectangle.
| Parameter | Type | Default Value | Description |
| --------------------- | ---------------- | ------------------ | ---------------------------------------- |
| stimuli | array | *undefined* | Each element of the array is a stimulus. A stimulus is a path to an image file. The order of stimuli in the array determines the order of the animation sequence. |
| canvas_size | array | `[400, 400]` | Array specifying the width and height of the area that the animation will display in. Stimuli will move to the edges of this area, so increasing the width without increasing the `timing_cycle` parameter will speed up the images. |
| image_size | array | `[100, 100]` | Array specifying the width and height of the images to show. The occluding rectangle will have a width equal to the width of image_size. |
| initial_direction | string | "left" | Which direction the stimulus should move first (subsequent directions will alternate). Choices are "left" or "right". |
| occlude_center | boolean | true | If true, display a rectangle in the center of the screen that is just wide enough to occlude the image completely as it passes behind. |
| choices | array of strings | `jsPsych.ALL_KEYS` | This array contains the key(s) that the subject is allowed to press in order to respond to the stimulus. Keys should be specified as characters (e.g., `'a'`, `'q'`, `' '`, `'Enter'`, `'ArrowDown'`) - see [this page](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) and [this page (event.key column)](https://www.freecodecamp.org/news/javascript-keycode-list-keypress-event-key-codes/) for more examples. Any key presses that are not listed in the array will be ignored. The default value of `jsPsych.ALL_KEYS` means that all keys will be accepted as valid responses. Specifying `jsPsych.NO_KEYS` will mean that no responses are allowed. |
| cycle_duration | numeric | 1000 | How long it takes for a stimulus in the sequence to make a complete cycle (move to the edge and back to the center) in milliseconds. |
| pre_movement_duration | numeric | 500 | How long to wait before the stimuli starts moving from behind the center rectangle. |
## Data Generated
In addition to the [default data collected by all plugins](overview.md#data-collected-by-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
stimulus | JSON string | A JSON encoded array where each element of the array is a stimulus from the sequence, in the order that they were shown.
responses | JSON string | A JSON encoded array containing all response information. The encoded object is an array containing one element for each valid response. Each response item has three properties: `key` the key code of the response key, `stimulus` the index of the stimulus that was displayed when the response was made, and `rt` the response time measured since the start of the sequence.
| Name | Type | Value |
| --------- | ----------- | ---------------------------------------- |
| stimulus | JSON string | A JSON encoded array where each element of the array is a stimulus from the sequence, in the order that they were shown. |
| responses | JSON string | A JSON encoded array containing all response information. The encoded object is an array containing one element for each valid response. Each response item has three properties: `key` the key that was pressed, `stimulus` the index of the stimulus that was displayed when the response was made, and `rt` the response time measured since the start of the sequence. |
## Examples