Radio
', 'Towel
', 'Match
'], - is_html: true, - timing_response: 1500, - continue_after_response: false -} -``` +// create free-sort block for jspsych +var sort_block = { + type: 'free-sort', + stimuli: [sorting_stimuli], + prompt: "Click and drag the images below to sort them so that similar items are close together.
" +}; +``` \ No newline at end of file diff --git a/docs/markdown_docs/plugins/jspsych-html.md b/docs/markdown_docs/plugins/jspsych-html.md index f374b99a..36716420 100644 --- a/docs/markdown_docs/plugins/jspsych-html.md +++ b/docs/markdown_docs/plugins/jspsych-html.md @@ -1,8 +1,6 @@ -# jspsych-single-stim plugin +# jspsych-html plugin -This plugin displays an image or HTML-formatted content and allows the subject to respond by pressing a key on the keyboard. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the subject has failed to respond within a fixed length of time. - -Because this plugin can display any HTML content, it is quite versatile. It can be used for any situation in which the response generated by the subject is a single keystroke. +The HTML plugin displays an external HTML document (often a consent form). Either a keyboard response or a button press can be used to continue to the next trial. It allows the experimenter to check if conditions are met (such as indicating informed consent) before continuing. ## Parameters @@ -10,13 +8,20 @@ This table lists the parameters associated with this plugin. Parameters with a d Parameter | Type | Default Value | Description ----------|------|---------------|------------ -stimuli | array | *undefined* | Each element of the array is a stimulus. A stimulus can be either a path to an image file or a string containing valid HTML markup. Each stimulus will be presented in its own trial, and thus the length of this array determines the total number of trials. -is_html | boolean | false | If the elements of the `stimuli` array are strings containing HTML content, then this parameter must be set to true. -choices | array | [ ] | 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 an empty array means that all keys will be accepted as valid responses. -prompt | string | "" | 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). -timing_stim | numeric | -1 | How long to show the stimulus for in milliseconds. If the value is -1, then the stimulus will be shown until the subject makes a response. -timing_response | numeric | -1 | 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 the subject's response will be recorded as -1 for the trial and the trial will end. If the value of this parameter is -1, then the trial will wait for a response indefinitely. -continue_after_response | 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 `timing_response` parameter). If false, then the trial will continue until the value for `timing_response` 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. +pages | array | *undefined* | Array of objects representing the individual pages to be shown. See table below for details about the parameters of the objects. +cont_key | numeric | null | This setting is used for all pages that don't override the default value. See table below. +cont_btn | string | null | This setting is used for all pages that don't override the default value. See table below. +force_refresh | boolean | false | If `true`, then the plugin will avoid using the cached version of the HTML page to load if one exists. + +The `pages` array defines each individual trial in the block. Each object in the `pages` array can have the following parameters: + +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(){} | 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 adequetly filled out a form before continuing, for example. + ## Data Generated @@ -24,41 +29,52 @@ In addition to the [default data collected by all plugins](), this plugin collec 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. +url | string | The URL of the page. +rt | numeric | The response time in milliseconds for the subject to finish the trial. ## Examples -These examples show how to define a block using the single-stim plugin to achieve various goals. +#### Loading a consent form -#### Displaying images until subject gives a response - -```javascript -var block = { - type: 'single-stim', - stimuli: ['img/happy_face.png', 'img/sad_face.png'] -} +##### This content would be in a file called 'external_page.html' +```html ++ This is a demo experiment, with this minimal consent form being loaded + as an external html document. To continue, click the checkbox below + and hit "Start Experiment". +
++ + I agree to take part in this study. +
+ +Radio
', 'Towel
', 'Match
'], - is_html: true, - timing_response: 1500, - continue_after_response: false -} -``` + + diff --git a/docs/markdown_docs/plugins/jspsych-palmer.md b/docs/markdown_docs/plugins/jspsych-palmer.md index f374b99a..a1c421dc 100644 --- a/docs/markdown_docs/plugins/jspsych-palmer.md +++ b/docs/markdown_docs/plugins/jspsych-palmer.md @@ -1,8 +1,14 @@ -# jspsych-single-stim plugin +# jspsych-palmer -This plugin displays an image or HTML-formatted content and allows the subject to respond by pressing a key on the keyboard. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically if the subject has failed to respond within a fixed length of time. +The Palmer plugin displays a programmatically generated stimulus designed to mimic stimuli used by [Palmer (1977)](jspsych-palmer.md#references) and [Goldstone et al. (2005)](jspsych-palmer.md#references). -Because this plugin can display any HTML content, it is quite versatile. It can be used for any situation in which the response generated by the subject is a single keystroke. +The stimuli look like this (there are several options to configure the appearance of the stimuli below): + + + +Subjects can edit the stimuli by clicking on two adjacent circles to add or remove a line segment between them. The plugin also contains a function for generating non-editable versions of the stimuli that can be used in other plugins that accept HTML-formatted stimuli, like the single-stim and categorize plugins. + +**Dependency alert**: This plugin requires the Raphael-js library, available at [http://www.raphaeljs.com](http://www.raphaeljs.com). You must include the library in the `` section of your experiment page. ## Parameters @@ -10,13 +16,13 @@ This table lists the parameters associated with this plugin. Parameters with a d Parameter | Type | Default Value | Description ----------|------|---------------|------------ -stimuli | array | *undefined* | Each element of the array is a stimulus. A stimulus can be either a path to an image file or a string containing valid HTML markup. Each stimulus will be presented in its own trial, and thus the length of this array determines the total number of trials. -is_html | boolean | false | If the elements of the `stimuli` array are strings containing HTML content, then this parameter must be set to true. -choices | array | [ ] | 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 an empty array means that all keys will be accepted as valid responses. -prompt | string | "" | 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). -timing_stim | numeric | -1 | How long to show the stimulus for in milliseconds. If the value is -1, then the stimulus will be shown until the subject makes a response. -timing_response | numeric | -1 | 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 the subject's response will be recorded as -1 for the trial and the trial will end. If the value of this parameter is -1, then the trial will wait for a response indefinitely. -continue_after_response | 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 `timing_response` parameter). If false, then the trial will continue until the value for `timing_response` 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. +configurations | array | *undefined* | Array of stimulus configurations. Each configuration is an array of 1s and 0s. A 1 represents the presence of a line segment, and a 0 represents the absence of a line segment. The number of elements in a configuration array should be the number of possible line segments in the stimulus. For the default size of 3x3, this is 20 (6 horizontal + 6 vertical + 8 diagonal). The order of the lines in the array are horizontal, vertical, and then diagonal. The easiest way to see this is just to try different configurations. This represents the target configuration, as the stimulus will be blank initially. +show_feedback | boolean | false | Show corrective feedback after the subject submits a response. +grid_spacing | numeric | 75 | Distance in pixels between the rows and columns. +circle_radius | numeric | 20 | Radius in pixels of the circles. +square_size | numeric | 3 | Number of rows and columns in the stimulus. +timing_feedback | numeric | 1000 | How long to show the feedback for in milliseconds. +prompt | string | "" | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to ## Data Generated @@ -24,41 +30,64 @@ In addition to the [default data collected by all plugins](), this plugin collec 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. +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 produced exactly the right configuration. +configuration | JSON string | Configuration that the subject produced, in the same format as the configuration array parameter for the trial. +target_configuration | JSON string | The correct configuration (from configuration parameter). +num_wrong | numeric | The number of line segments that didn't match between what the subject produced and the target configuration. + +## Stimulus Creation + +The palmer plugin contains a stimulus generation method (`jsPsych.palmer.generate_stimulus`) that can be used independently of actually running trials with the plugin. You can use this method to generate stimuli (created as HTML strings) to embed in other plugins that can use HTML as input, such as jspsych-categorize. An example is provided here: + +```javascript +var square_size = 3; // number of rows and columns +var grid_spacing = 75; // pixels +var circle_size = 20; // radius in pixels +var configuration = [0,1,0,0,1,1,0,0,1,1,0,0,1,0,0,0,1,0,0,1]; // see definition above + +var stimulus = jsPsych.palmer.generate_stimulus(square_size, grid_spacing, circle_size, configuration); + +// stimulus now contains an HTML string that will generate the corresponding stimulus. +``` ## Examples These examples show how to define a block using the single-stim plugin to achieve various goals. -#### Displaying images until subject gives a response +#### Matching a previously seen stimulus ```javascript -var block = { + +// create a stimulus using the generate_stimulus method +var square_size = 3; // number of rows and columns +var grid_spacing = 75; // pixels +var circle_size = 20; // radius in pixels +var configuration = [0,1,0,0,1,1,0,0,1,1,0,0,1,0,0,0,1,0,0,1]; // see definition above + +var stimulus = jsPsych.palmer.generate_stimulus(square_size, grid_spacing, circle_size, configuration); + +// show stimulus using single-stim plugin +var stim_block = { type: 'single-stim', - stimuli: ['img/happy_face.png', 'img/sad_face.png'] -} -``` - -#### Restricting which keys the subject can use to respond - -```javascript -var block = { - type: 'single-stim', - stimuli: ['img/happy_face.png', 'img/sad_face.png'], - choices: ['h','s'] -} -``` - -#### Displaying HTML content for a fixed length of time - -```javascript -var block = { - type: 'single-stim', - stimuli: ['Radio
', 'Towel
', 'Match
'], + stimuli: [stimulus], is_html: true, - timing_response: 1500, + timing_response: 2000, continue_after_response: false } + +var test_block = { + type: 'palmer', + configurations: [[0,1,0,0,1,1,0,0,1,1,0,0,1,0,0,0,1,0,0,1]], + editable: true, + show_feedback: true, + timing_feedback: 2000, + prompt: 'Create the image you just saw. Click two circles to add or remove a line between them. Click submit when you are done.
' +}; ``` + +## References + +Goldstone, R. L., Rogosky, B. J., Pevtzow, R., & Blair, M. (2005). Perceptual and semantic reorganization during category learning. _In H. Cohen & C. Lefebvre (Eds.) Handbook of Categorization in Cognitive Science_. (pp. 651-678). Amsterdam: Elsevier. + +Palmer, S. (1977). Hierarchical Structure in Perceptual Representation. _Cognitive Psychology, 9_, 441. \ No newline at end of file