From 2e8a37f36fd9ebde490ac7edb4dbcbde43d6fbcf Mon Sep 17 00:00:00 2001
From: Becky Gilbert <beckyannegilbert@gmail.com>
Date: Fri, 7 Oct 2022 15:54:00 -0800
Subject: [PATCH] Deployed 2a081607 to 7.3 with MkDocs 1.3.0 and mike 1.1.2

---
 7.3/developers/documentation/index.html |   2 +-
 7.3/search/search_index.json            |   2 +-
 7.3/sitemap.xml.gz                      | Bin 988 -> 988 bytes
 3 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/7.3/developers/documentation/index.html b/7.3/developers/documentation/index.html
index 2db8c4d1..169fa302 100644
--- a/7.3/developers/documentation/index.html
+++ b/7.3/developers/documentation/index.html
@@ -2000,7 +2000,7 @@
 <div class="admonition warning">
 <p class="admonition-title">For core maintainers only</p>
 </div>
-<p>After the documentation has been built locally (and therefore committed to your local <code>gh-pages</code> branch), you can update the live documentation site by switching to your <code>gh-pages</code> branch and pushing to the remote branch.</p>
+<p>After the documentation has been built locally (and therefore committed to your local <code>gh-pages</code> branch), you can update the live documentation site by switching to your <code>gh-pages</code> branch and pushing to the remote <code>gh-pages</code> branch.</p>
 
               
             </article>
diff --git a/7.3/search/search_index.json b/7.3/search/search_index.json
index 5dadb350..8505976c 100644
--- a/7.3/search/search_index.json
+++ b/7.3/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"\u00b6 jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. Experiments in jsPsych are created using plugins . Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. You can use the plugins that are included with jsPsych , use plugins that are developed by community members in the contrib repository , or create your own plugins . By assembling different plugins together into a timeline , it is possible to create a wide range of experiments. The page on timelines is a good place to start learning about jsPsych. From there, you might want to complete the hello world tutorial to learn how to set up a jsPsych experiment and the reaction time experiment tutorial to learn the core features of the framework.","title":"Introduction"},{"location":"#_1","text":"jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. Experiments in jsPsych are created using plugins . Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. You can use the plugins that are included with jsPsych , use plugins that are developed by community members in the contrib repository , or create your own plugins . By assembling different plugins together into a timeline , it is possible to create a wide range of experiments. The page on timelines is a good place to start learning about jsPsych. From there, you might want to complete the hello world tutorial to learn how to set up a jsPsych experiment and the reaction time experiment tutorial to learn the core features of the framework.","title":""},{"location":"about/about/","text":"About jsPsych \u00b6 jsPsych is open source project with numerous contributors . The project is currently managed by the core team of Josh de Leeuw ( @jodeleeuw ), Becky Gilbert ( @becky-gilbert ), and Bj\u00f6rn Luchterhandt ( @bjoluc ). jsPsych was created by Josh de Leeuw . Citation \u00b6 If you use jsPsych please cite the following paper. de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. Behavior Research Methods , 47 (1), 1-12. doi:10.3758/s13428-014-0458-y .","title":"About jsPsych"},{"location":"about/about/#about-jspsych","text":"jsPsych is open source project with numerous contributors . The project is currently managed by the core team of Josh de Leeuw ( @jodeleeuw ), Becky Gilbert ( @becky-gilbert ), and Bj\u00f6rn Luchterhandt ( @bjoluc ). jsPsych was created by Josh de Leeuw .","title":"About jsPsych"},{"location":"about/about/#citation","text":"If you use jsPsych please cite the following paper. de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. Behavior Research Methods , 47 (1), 1-12. doi:10.3758/s13428-014-0458-y .","title":"Citation"},{"location":"about/license/","text":"License \u00b6 jsPsych is licensed under the MIT license. The MIT License (MIT) Copyright (c) 2014-2022 Joshua R. de Leeuw Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","title":"License"},{"location":"about/license/#license","text":"jsPsych is licensed under the MIT license. The MIT License (MIT) Copyright (c) 2014-2022 Joshua R. de Leeuw Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","title":"License"},{"location":"developers/configuration/","text":"Configuring the jsPsych development environment \u00b6 Setup \u00b6 JsPsych is written using TypeScript , a superset of JavaScript that adds static typing, but compiles to plain JavaScript. The TypeScript compiler itself is written in JavaScript and can be run by Node.js , a runtime to execute JavaScript code without a web browser. Node.js comes with a package manager called NPM (Node Package Manager) that can install JavaScript libraries to run on your machine, such as TypeScript and other build tools for jsPsych. In order to work on code in the jsPsych or the jspsych-contrib repository, it is recommended that you follow the steps below to set up your development environment. Install Node.js \u00b6 The jsPsych development setup requires Node.js >= v14 to be installed on your machine. We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use). If you are bound to Node.js v14, make sure to install NPM v7 manually (via npm install -g npm@7 ). Clone the repository and install the dependencies \u00b6 Clone either the jsPsych repository or the jspsych-contrib repository by running git clone https://github.com/jspsych/jsPsych.git && cd jsPsych or git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib in a terminal. Then run npm install . This will create a node_modules directory and install all the dependencies into it that are required to build and test jsPsych. Attention It is important that npm install is only run in the root directory of the repository (due to the NPM workspaces feature). If you accidentally ran npm install anywhere else, remove the node_modules directory and the package-lock.json file that were created at that location and run npm install in the root directory again. Info If you are running npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository. This step may take a few minutes. If you would like to use that time efficiently, consider reading the following two sections to know what's happening. Repository structure \u00b6 A Node.js package is a directory that contains a package.json file describing it. Most importantly, a package.json file lists other packages that the package depends on. The jsPsych and jspsych-contrib repositories use NPM workspaces . That means, running npm install in the repository root will install the dependencies for all packages in the packages directory. The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package. These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg ). Build chain and build artifacts \u00b6 JsPsych comes with a build chain (specified in the @jspsych/config package) that can be executed by running npm run build in a package's directory. The build chain will read the package (starting at its src/index.ts file) and create the following build artifacts in the package's dist directory: index.js This file contains everything from index.ts , but as plain JavaScript and bundled in a single file (i.e. without import ing files from the same package). It is used by bundlers like webpack . index.cjs Like index.js , but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework. index.browser.js This file, like index.js , contains the entire package as plain JavaScript, but this time wrapped in a function so that it can be included directly by browsers using the <script> tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after export default in the index.ts file) is assigned to a global variable. The name of this global variable is specified in the package's rollup.config.mjs file, as a parameter to the makeRollupConfig() function. Hence, for instance, including the index.browser.js file from the plugin-html-keyboard-response package would assign the HtmlKeyboardResponsePlugin class to the global jsPsychHtmlKeyboardResponse variable. Because the code in index.browser.js looks very similar to the index.ts code but is fully supported by modern web browsers, all examples in the examples directory reference the index.browser.js files so users can also modify the source code directly without running the build chain. index.browser.min.js There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features. That's why the jsPsych build chain uses Babel to translate the source files into code that a majority of web browsers can understand. The result of this operation is index.browser.min.js . It behaves just like index.browser.js , but adds support for older browsers by substituting new JavaScript features using older ones. Because this is the recommended build artifact for production usage (and is automatically served by unpkg), the code in index.browser.min.js is also processed by Terser to reduce its size and speed up experiment loading times. *.js.map When debugging code in a browser (especially index.browser.min.js , which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a .map file which contains a mapping of the generated code to the original source code. Browsers automatically read these .map files and display the original code in their debuggers instead of the generated one. *.d.ts The .d.ts files contain the TypeScript type definitions that would otherwise be lost during compilation to plain JavaScript. They are read by Typescript and editors when a package is imported into another TypeScript project. Testing \u00b6 Automated code testing for jsPsych is implemented with Jest . To run the tests, install Node and npm. Run npm install in the root jsPsych directory. Then run npm test . You can also run npm test in the directory of the package that you would like to test. For example, if you are developing tests for the html-keyboard-response plugin you can run npm test in /packages/plugin-html-keyboard-response . If you want to run one file from the root directory, using the aforementioned example, you can run npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts . Tests for the core jsPsych library are located in /packages/jspsych/tests . Tests for plugins and extensions are located in the /src folder of the corresponding package. Test files for plugins and extensions are named index.spec.ts . There are helper functions for testing in /packages/jspsych/tests/utils.ts . We recommend looking at other test files to observe conventions for testing.","title":"Configuration"},{"location":"developers/configuration/#configuring-the-jspsych-development-environment","text":"","title":"Configuring the jsPsych development environment"},{"location":"developers/configuration/#setup","text":"JsPsych is written using TypeScript , a superset of JavaScript that adds static typing, but compiles to plain JavaScript. The TypeScript compiler itself is written in JavaScript and can be run by Node.js , a runtime to execute JavaScript code without a web browser. Node.js comes with a package manager called NPM (Node Package Manager) that can install JavaScript libraries to run on your machine, such as TypeScript and other build tools for jsPsych. In order to work on code in the jsPsych or the jspsych-contrib repository, it is recommended that you follow the steps below to set up your development environment.","title":"Setup"},{"location":"developers/configuration/#install-nodejs","text":"The jsPsych development setup requires Node.js >= v14 to be installed on your machine. We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use). If you are bound to Node.js v14, make sure to install NPM v7 manually (via npm install -g npm@7 ).","title":"Install Node.js"},{"location":"developers/configuration/#clone-the-repository-and-install-the-dependencies","text":"Clone either the jsPsych repository or the jspsych-contrib repository by running git clone https://github.com/jspsych/jsPsych.git && cd jsPsych or git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib in a terminal. Then run npm install . This will create a node_modules directory and install all the dependencies into it that are required to build and test jsPsych. Attention It is important that npm install is only run in the root directory of the repository (due to the NPM workspaces feature). If you accidentally ran npm install anywhere else, remove the node_modules directory and the package-lock.json file that were created at that location and run npm install in the root directory again. Info If you are running npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository. This step may take a few minutes. If you would like to use that time efficiently, consider reading the following two sections to know what's happening.","title":"Clone the repository and install the dependencies"},{"location":"developers/configuration/#repository-structure","text":"A Node.js package is a directory that contains a package.json file describing it. Most importantly, a package.json file lists other packages that the package depends on. The jsPsych and jspsych-contrib repositories use NPM workspaces . That means, running npm install in the repository root will install the dependencies for all packages in the packages directory. The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package. These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg ).","title":"Repository structure"},{"location":"developers/configuration/#build-chain-and-build-artifacts","text":"JsPsych comes with a build chain (specified in the @jspsych/config package) that can be executed by running npm run build in a package's directory. The build chain will read the package (starting at its src/index.ts file) and create the following build artifacts in the package's dist directory: index.js This file contains everything from index.ts , but as plain JavaScript and bundled in a single file (i.e. without import ing files from the same package). It is used by bundlers like webpack . index.cjs Like index.js , but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework. index.browser.js This file, like index.js , contains the entire package as plain JavaScript, but this time wrapped in a function so that it can be included directly by browsers using the <script> tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after export default in the index.ts file) is assigned to a global variable. The name of this global variable is specified in the package's rollup.config.mjs file, as a parameter to the makeRollupConfig() function. Hence, for instance, including the index.browser.js file from the plugin-html-keyboard-response package would assign the HtmlKeyboardResponsePlugin class to the global jsPsychHtmlKeyboardResponse variable. Because the code in index.browser.js looks very similar to the index.ts code but is fully supported by modern web browsers, all examples in the examples directory reference the index.browser.js files so users can also modify the source code directly without running the build chain. index.browser.min.js There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features. That's why the jsPsych build chain uses Babel to translate the source files into code that a majority of web browsers can understand. The result of this operation is index.browser.min.js . It behaves just like index.browser.js , but adds support for older browsers by substituting new JavaScript features using older ones. Because this is the recommended build artifact for production usage (and is automatically served by unpkg), the code in index.browser.min.js is also processed by Terser to reduce its size and speed up experiment loading times. *.js.map When debugging code in a browser (especially index.browser.min.js , which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a .map file which contains a mapping of the generated code to the original source code. Browsers automatically read these .map files and display the original code in their debuggers instead of the generated one. *.d.ts The .d.ts files contain the TypeScript type definitions that would otherwise be lost during compilation to plain JavaScript. They are read by Typescript and editors when a package is imported into another TypeScript project.","title":"Build chain and build artifacts"},{"location":"developers/configuration/#testing","text":"Automated code testing for jsPsych is implemented with Jest . To run the tests, install Node and npm. Run npm install in the root jsPsych directory. Then run npm test . You can also run npm test in the directory of the package that you would like to test. For example, if you are developing tests for the html-keyboard-response plugin you can run npm test in /packages/plugin-html-keyboard-response . If you want to run one file from the root directory, using the aforementioned example, you can run npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts . Tests for the core jsPsych library are located in /packages/jspsych/tests . Tests for plugins and extensions are located in the /src folder of the corresponding package. Test files for plugins and extensions are named index.spec.ts . There are helper functions for testing in /packages/jspsych/tests/utils.ts . We recommend looking at other test files to observe conventions for testing.","title":"Testing"},{"location":"developers/contributing/","text":"Contributing to jsPsych \u00b6 We welcome contributions of all kinds, including changes to the core codebase, the development of new plugins and extensions, and improvements to the documentation. The project is managed entirely through the GitHub repository . There you can: Use discussions to propose ideas for development and seek feedback on contributions, such as a new plugin. Use issues to identify anything with an actionable next step. For example, a page in the documentation that needs to be fixed, a bug in the code, or a specific feature that has a clear scope. Submit a pull request with modifications to the codebase. Pull requests will be reviewed by one or more members of the core team. Guidelines for contibuting \u00b6 Contributing to the codebase \u00b6 We welcome contributions of any scope. Before we can merge changes into the main codebase, we generally require a few things. Note that you are welcome to contribute code without these things in place, but it will help us get to your contribution faster if you take care of whatever components you are comfortable doing. The code must be tested through our automated testing system. We use Jest as the testing framework. If you are fixing a bug, consider adding a test case that shows the bug has been resolved. If you are contributing new features, like a new plugin, a test suite for the plugin is very helpful. See testing jsPsych for more information about configuring the test tools and writing tests. Relevant documentation must be updated. Any pages in /docs that are affected by the contribution should be updated, and if new pages are needed they should be created. For example, if you are contributing a plugin then adding documentation for the plugin and updating the list of available plugins as well as the mkdocs configuration file is very helpful! An example file should be included if applicable. If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the /examples folder in the repository. A changeset must be included in the pull request . We use changesets to generate new releases and their corresponding release notes. This is a good overview of changesets that explains how to add one to your pull request. Feel free to ask for help with this! Update the contributors.md file . If you are a first time contributor to jsPsych please add your name to our contributors file . And thanks! Contributing to the documentation \u00b6 We are very appreciative of both small and large contributions to the documentation, from fixing a typo to adding a whole new tutorial. All of the documentation that appears on this site is contained in the /docs folder of the repository. The documentation is built using MkDocs and themed using Material for MkDocs . You can edit any of the markdown files and submit a pull request to modify documentation. If you'd like to test your changes to the documentation locally you'll need to install MkDocs and Material for MkDocs . Then you can run the command mike serve in the root folder of the repository to launch a local webserver and view the documentation. Contributing to jspsych vs. jspsych-contrib \u00b6 If you are developing a new plugin or extension there are two different repositories that you can contribute to: jspsych or jspsych-contrib . The main jspsych repository is open to new plugins and extensions that are likely to be widely used. We require that contributions to main repository are well documented and tested before they are merged. Contributions to the main repository must use TypeScript. We limit contributions to this repository because once a plugin or extension is in the main codebase we are generally committed to providing updates as we develop new versions of jsPsych. Each new plugin and extension potentially increases the amount of development work that we will need to do in the future, so we are somewhat selective about what we will merge. If you have an idea that you'd like to discuss please open a discussion thread and we'd love to chat about it! The jspsych-contrib repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our TypeScript template or using our JavaScript template . Contributions to jspsych-contrib are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from jspsych-contrib based on their popularity and completeness (documentation and testing).","title":"Contributing to jsPsych"},{"location":"developers/contributing/#contributing-to-jspsych","text":"We welcome contributions of all kinds, including changes to the core codebase, the development of new plugins and extensions, and improvements to the documentation. The project is managed entirely through the GitHub repository . There you can: Use discussions to propose ideas for development and seek feedback on contributions, such as a new plugin. Use issues to identify anything with an actionable next step. For example, a page in the documentation that needs to be fixed, a bug in the code, or a specific feature that has a clear scope. Submit a pull request with modifications to the codebase. Pull requests will be reviewed by one or more members of the core team.","title":"Contributing to jsPsych"},{"location":"developers/contributing/#guidelines-for-contibuting","text":"","title":"Guidelines for contibuting"},{"location":"developers/contributing/#contributing-to-the-codebase","text":"We welcome contributions of any scope. Before we can merge changes into the main codebase, we generally require a few things. Note that you are welcome to contribute code without these things in place, but it will help us get to your contribution faster if you take care of whatever components you are comfortable doing. The code must be tested through our automated testing system. We use Jest as the testing framework. If you are fixing a bug, consider adding a test case that shows the bug has been resolved. If you are contributing new features, like a new plugin, a test suite for the plugin is very helpful. See testing jsPsych for more information about configuring the test tools and writing tests. Relevant documentation must be updated. Any pages in /docs that are affected by the contribution should be updated, and if new pages are needed they should be created. For example, if you are contributing a plugin then adding documentation for the plugin and updating the list of available plugins as well as the mkdocs configuration file is very helpful! An example file should be included if applicable. If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the /examples folder in the repository. A changeset must be included in the pull request . We use changesets to generate new releases and their corresponding release notes. This is a good overview of changesets that explains how to add one to your pull request. Feel free to ask for help with this! Update the contributors.md file . If you are a first time contributor to jsPsych please add your name to our contributors file . And thanks!","title":"Contributing to the codebase"},{"location":"developers/contributing/#contributing-to-the-documentation","text":"We are very appreciative of both small and large contributions to the documentation, from fixing a typo to adding a whole new tutorial. All of the documentation that appears on this site is contained in the /docs folder of the repository. The documentation is built using MkDocs and themed using Material for MkDocs . You can edit any of the markdown files and submit a pull request to modify documentation. If you'd like to test your changes to the documentation locally you'll need to install MkDocs and Material for MkDocs . Then you can run the command mike serve in the root folder of the repository to launch a local webserver and view the documentation.","title":"Contributing to the documentation"},{"location":"developers/contributing/#contributing-to-jspsych-vs-jspsych-contrib","text":"If you are developing a new plugin or extension there are two different repositories that you can contribute to: jspsych or jspsych-contrib . The main jspsych repository is open to new plugins and extensions that are likely to be widely used. We require that contributions to main repository are well documented and tested before they are merged. Contributions to the main repository must use TypeScript. We limit contributions to this repository because once a plugin or extension is in the main codebase we are generally committed to providing updates as we develop new versions of jsPsych. Each new plugin and extension potentially increases the amount of development work that we will need to do in the future, so we are somewhat selective about what we will merge. If you have an idea that you'd like to discuss please open a discussion thread and we'd love to chat about it! The jspsych-contrib repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our TypeScript template or using our JavaScript template . Contributions to jspsych-contrib are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from jspsych-contrib based on their popularity and completeness (documentation and testing).","title":"Contributing to jspsych vs. jspsych-contrib"},{"location":"developers/documentation/","text":"Building the jsPsych documentation \u00b6 The documentation hosted at https://www.jspsych.org is generated using mkdocs and the mkdocs-material theme . The documentation files are located in the /docs directory of the GitHub repository . The documentation is written using markdown. To build a local copy of the docs, you will need to install mkdocs , mkdocs-material , and mike using poetry . Install poetry \u00b6 Poetry is a package manager for python. Follow the install instructions on the poetry website to get it running. Install dev dependencies \u00b6 Run the command poetry install in the root directory of jsPsych to install mkdocs , mkdocs-material , and their dependencies. Building a local copy of the docs \u00b6 Run poetry run mike deploy [version] -u to build a new version of the documentation or to override an existing version. For example, if you are testing an edit to version 7.2 of the documentation, run poetry run mike deploy 7.2 -u . You can also use jsPsych's custom npm command: npm run docs:deploy [version] , e.g. npm run docs:deploy 7.2 . This will build the documentation and commit it directly to the gh-pages branch. We use mike instead of mkdocs for the build step to support versioning of the documentation. mike runs the mkdocs command under the hood. Viewing the local docs \u00b6 To launch a local webserver, run poetry run mike serve , or use jsPsych's custom npm command: npm run docs:serve . The docs will be viewable at http://localhost:8000 . Updating the public docs site \u00b6 For core maintainers only After the documentation has been built locally (and therefore committed to your local gh-pages branch), you can update the live documentation site by switching to your gh-pages branch and pushing to the remote branch.","title":"Building the Documentation"},{"location":"developers/documentation/#building-the-jspsych-documentation","text":"The documentation hosted at https://www.jspsych.org is generated using mkdocs and the mkdocs-material theme . The documentation files are located in the /docs directory of the GitHub repository . The documentation is written using markdown. To build a local copy of the docs, you will need to install mkdocs , mkdocs-material , and mike using poetry .","title":"Building the jsPsych documentation"},{"location":"developers/documentation/#install-poetry","text":"Poetry is a package manager for python. Follow the install instructions on the poetry website to get it running.","title":"Install poetry"},{"location":"developers/documentation/#install-dev-dependencies","text":"Run the command poetry install in the root directory of jsPsych to install mkdocs , mkdocs-material , and their dependencies.","title":"Install dev dependencies"},{"location":"developers/documentation/#building-a-local-copy-of-the-docs","text":"Run poetry run mike deploy [version] -u to build a new version of the documentation or to override an existing version. For example, if you are testing an edit to version 7.2 of the documentation, run poetry run mike deploy 7.2 -u . You can also use jsPsych's custom npm command: npm run docs:deploy [version] , e.g. npm run docs:deploy 7.2 . This will build the documentation and commit it directly to the gh-pages branch. We use mike instead of mkdocs for the build step to support versioning of the documentation. mike runs the mkdocs command under the hood.","title":"Building a local copy of the docs"},{"location":"developers/documentation/#viewing-the-local-docs","text":"To launch a local webserver, run poetry run mike serve , or use jsPsych's custom npm command: npm run docs:serve . The docs will be viewable at http://localhost:8000 .","title":"Viewing the local docs"},{"location":"developers/documentation/#updating-the-public-docs-site","text":"For core maintainers only After the documentation has been built locally (and therefore committed to your local gh-pages branch), you can update the live documentation site by switching to your gh-pages branch and pushing to the remote branch.","title":"Updating the public docs site"},{"location":"developers/extension-development/","text":"Extension development \u00b6 Requirements for an extension \u00b6 As of version 7.0, extensions are JavaScript Classes . An extension must implement: A constructor() that accepts an instance of jsPsych. An initialize() function to handle the initialize event of the extension. An on_start() function to handle the on_start event of the extension. An on_load() function to handle the on_load event of the extension. An on_finish() function to handle the on_finish event of the extension and store data that the extension collects. A static info property containing a unique name for the extension. Templates \u00b6 Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository . Extension components \u00b6 constructor() \u00b6 The extension's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. class MyAwesomeExtension { constructor ( jsPsych ){ this . jsPsych = jsPsych ; } } initialize() \u00b6 The initialize() function is called when an instance of jsPsych is first initialized, either through initJsPsych() or new JsPsych() . This is where setup code for the extension should be run. This event will happen once per experiment, unlike the other events which occur with each trial. The params object can include whatever parameters are necessary to configure the extension. The params object is passed from the call to initJsPsych() to initialize() method. initialize() must return a Promise that resolves when the extension is finished initializing. //... experiment code ...// let jsPsych = initJsPsych ({ extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ return new Promise (( resolve , reject )=>{ console . log ( params . demo ); // will output 'value' resolve (); // finish initialzing }) } } on_start() \u00b6 on_start() is called at the start of the plugin execution, prior to calling plugin.trial . This is where trial-specific initialization can happen, such as creating empty containers to hold data or resetting internal state. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ console . log ( params . demo ); // outputs 'value' before the trial begins. } } on_load() \u00b6 on_load() is called after the on_load event for the plugin has completed, which is typically when the plugin has finished executing initial DOM-modifying code and has set up various event listeners. This is where the extension can begin actively interacting with the DOM and recording data. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ // replaces the contents of the display with 'value'; this . jsPsych . getDisplayElement (). innerHTML = params . demo ; } } on_finish() \u00b6 on_finish() is called after the plugin invokes jsPsych.finishTrial() . This can be used for any teardown at the end of the trial. This method should return an object of data to append to the plugin's data. Note that this event fires before the on_finish event for the plugin, so data added by the extension is accessible in any trial on_finish event handlers. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ], on_finish : ( data ) => { console . log ( data . awesome ); // will output 'value'. } }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ ... } on_finish ( params ){ return { awesome : params . value } } } static .info \u00b6 The info property for the class must contain an object with a name property that has a unique name for the extension. class MyAwesomeExtension { } MyAwesomeExtension . info = { name : 'awesome' } Optional methods \u00b6 The extension can also include any additional methods that are necessary for interacting with it. See the webgazer extension for an example. Advice for writing extensions \u00b6 If you are developing an extension with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . In general, extensions should be able to work with any plugin. They should make very few assumptions about what the DOM will contain beyond the container elements generated by jsPsych. If you are making an extension targeted at one or a small number of specific plugins, consider modifying the plugin code instead.","title":"Extension Development"},{"location":"developers/extension-development/#extension-development","text":"","title":"Extension development"},{"location":"developers/extension-development/#requirements-for-an-extension","text":"As of version 7.0, extensions are JavaScript Classes . An extension must implement: A constructor() that accepts an instance of jsPsych. An initialize() function to handle the initialize event of the extension. An on_start() function to handle the on_start event of the extension. An on_load() function to handle the on_load event of the extension. An on_finish() function to handle the on_finish event of the extension and store data that the extension collects. A static info property containing a unique name for the extension.","title":"Requirements for an extension"},{"location":"developers/extension-development/#templates","text":"Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository .","title":"Templates"},{"location":"developers/extension-development/#extension-components","text":"","title":"Extension components"},{"location":"developers/extension-development/#constructor","text":"The extension's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. class MyAwesomeExtension { constructor ( jsPsych ){ this . jsPsych = jsPsych ; } }","title":"constructor()"},{"location":"developers/extension-development/#initialize","text":"The initialize() function is called when an instance of jsPsych is first initialized, either through initJsPsych() or new JsPsych() . This is where setup code for the extension should be run. This event will happen once per experiment, unlike the other events which occur with each trial. The params object can include whatever parameters are necessary to configure the extension. The params object is passed from the call to initJsPsych() to initialize() method. initialize() must return a Promise that resolves when the extension is finished initializing. //... experiment code ...// let jsPsych = initJsPsych ({ extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ return new Promise (( resolve , reject )=>{ console . log ( params . demo ); // will output 'value' resolve (); // finish initialzing }) } }","title":"initialize()"},{"location":"developers/extension-development/#on_start","text":"on_start() is called at the start of the plugin execution, prior to calling plugin.trial . This is where trial-specific initialization can happen, such as creating empty containers to hold data or resetting internal state. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ console . log ( params . demo ); // outputs 'value' before the trial begins. } }","title":"on_start()"},{"location":"developers/extension-development/#on_load","text":"on_load() is called after the on_load event for the plugin has completed, which is typically when the plugin has finished executing initial DOM-modifying code and has set up various event listeners. This is where the extension can begin actively interacting with the DOM and recording data. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ // replaces the contents of the display with 'value'; this . jsPsych . getDisplayElement (). innerHTML = params . demo ; } }","title":"on_load()"},{"location":"developers/extension-development/#on_finish","text":"on_finish() is called after the plugin invokes jsPsych.finishTrial() . This can be used for any teardown at the end of the trial. This method should return an object of data to append to the plugin's data. Note that this event fires before the on_finish event for the plugin, so data added by the extension is accessible in any trial on_finish event handlers. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ], on_finish : ( data ) => { console . log ( data . awesome ); // will output 'value'. } }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ ... } on_finish ( params ){ return { awesome : params . value } } }","title":"on_finish()"},{"location":"developers/extension-development/#static-info","text":"The info property for the class must contain an object with a name property that has a unique name for the extension. class MyAwesomeExtension { } MyAwesomeExtension . info = { name : 'awesome' }","title":"static .info"},{"location":"developers/extension-development/#optional-methods","text":"The extension can also include any additional methods that are necessary for interacting with it. See the webgazer extension for an example.","title":"Optional methods"},{"location":"developers/extension-development/#advice-for-writing-extensions","text":"If you are developing an extension with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . In general, extensions should be able to work with any plugin. They should make very few assumptions about what the DOM will contain beyond the container elements generated by jsPsych. If you are making an extension targeted at one or a small number of specific plugins, consider modifying the plugin code instead.","title":"Advice for writing extensions"},{"location":"developers/plugin-development/","text":"Plugin development \u00b6 Requirements for a plugin \u00b6 As of version 7.0, plugins are JavaScript Classes . A plugin must implement: A constructor() that accepts an instance of jsPsych. A trial() method that accepts an HTMLElement as its first argument and an object of trial parameters as its second argument. There is an optional third argument to handle the on_load event in certain cirumstances. The trial() method should invoke jsPsych.finishTrial() to end the trial and save data at the appropriate moment. A static info property on the class that contains an object describing the plugin's parameters. Templates \u00b6 Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository . Plugin components \u00b6 constructor() \u00b6 The plugin's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial() \u00b6 The plugin's trial() method is responsible for running a single trial. When the jsPsych timeline reaches a trial using the plugin it will invoke the trial() method for the plugin. There are three parameters that are passed into the trial method. display_element is the DOM element where jsPsych content is being rendered. This parameter will be an HTMLElement , and you can use it to modify the portion of the document that jsPsych controls. trial is an object containing all of the parameters specified in the corresponding TimelineNode . on_load is an optional parameter that contains a callback function to invoke when trial() has completed its initial loading. See handling the on_load event . The only requirement for the trial method is that it calls jsPsych.finishTrial() when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point. static info \u00b6 The plugin's info property is an object with a name and parameters property. const info = { name : 'my-awesome-plugin' , parameters : { } } The parameters property is an object containing all of the parameters for the plugin. Each parameter has a type and default property. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } If the default value is undefined then a user must specify a value for this parameter when creating a trial using the plugin on the timeline. If they do not, then an error will be generated and shown in the console. If a default value is specified in info then that value will be used by the plugin unless the user overrides it by specifying that property. jsPsych allows most plugin parameters to be dynamic , which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that shouldn't be evaluated before the trial starts, then you should make sure that the parameter type is 'FUNCTION' . This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the canvas-* plugins for examples. The info object should be a static member of the class, as shown below. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } class MyAwesomePlugin { constructor (...) trial (...) } MyAwesomePlugin . info = info ; Plugin functionality \u00b6 Inside the .trial() method you can do pretty much anything that you want, including modifying the DOM, setting up event listeners, and making asynchronous requests. In this section we'll highlight a few common things that you might want to do as examples. Changing the content of the display \u00b6 There are a few ways to change the content of the display. The display_element parameter of the trial method contains the HTMLElement for displaying jsPsych content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the innerHTML . Here's an example of using innerHTML to display an image specified in the trial parameters. trial ( display_element , trial ){ let html_content = `<img src=\" ${ trial . image } \"></img>` ; display_element . innerHTML = html_content ; } jsPsych doesn't clear the display before or after each trial, so it is usually appropriate to use innerHTML to clear the display at the end of a trial. display_element . innerHTML = '' ; Waiting for specified durations \u00b6 If you need to delay code execution for a fixed amount of time, we recommend using jsPsych's wrapper of the setTimeout() function, jsPsych.pluginAPI.setTimeout() . In 7.0 the only advantage of using this method is that it registers the timeout handler so that it can be easily cleared at the end of the trial using jsPsych.pluginAPI.clearAllTimeouts() . In future versions we may replace the implementation of jsPsych.pluginAPI.setTimeout() with improved timing functionality based on requestAnimationFrame . trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; // hide image after trial.image_duration milliseconds this . jsPsych . pluginAPI . setTimeout (()=>{ display_element . innerHTML = '' ; }, trial . image_duration ); } Responding to keyboard events \u00b6 While the plugin framework allows you to set up any events that you would like to, including normal handling of keyup or keydown events, the jsPsych.pluginAPI module contains the getKeyboardResponse function , which implements some additional helpful functionality for key responses in an experiment. Here's a basic example. See the getKeyboardResponse docs for additional examples. trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; const after_key_response = ( info ) => { // hide the image display_element . innerHTML = '' ; // record the response time as data let data = { rt : info . rt } // end the trial this . jsPsych . finishTrial ( data ); } // set up a keyboard event to respond only to the spacebar this . jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_key_response , valid_responses : [ ' ' ], persist : false }); } Asynchronous loading \u00b6 One of the trial events is on_load , which is normally triggered automatically when the .trial() method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the audio-keyboard-response plugin, in which the check to see if the audio file is loaded is asynchronous and the .trial() method returns before the audio file has been initialized and the display updated. If you would like to manually trigger the on_load event for a plugin, the .trial() method accepts an optional third parameter that is a callback function to invoke when loading is complete. In order to tell jsPsych to not invoke the regular callback when the .trial() method returns, you need to explicitly return a Promise . As of version 7.0 this Promise only serves as a flag to tell jsPsych that the on_load event should not be triggered. In future versions we may make the Promise functional so that the trial operation can be an async function. Here's a sketch of how the on_load event can be utilized in a plugin. Note that this example is only a sketch and leaves out all the stuff that happens between loading and finishing the trial. See the source for the audio-keyboard-response plugin for a complete exampe. trial ( display_element , trial , on_load ){ let trial_complete ; do_something_asynchronous (). then (()=>{ on_load (); }); const end_trial = () => { this . jsPsych . finishTrial ({...}) trial_complete (); // not strictly necessary, but doesn't hurt. } return new Promise (( resolve )=>{ trial_complete = resolve ; }) } Save data \u00b6 To write data to jsPsych's data collection pass an object of data as the parameter to jsPsych.finishTrial() . constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial ( display_element , trial ){ let data = { correct : true , rt : 350 } this . jsPsych . finishTrial ( data ); } The data recorded will be that correct is true and that rt is 350 . Additional data for the trial will also be collected automatically. Simulation mode \u00b6 Plugins can optionally support simulation modes . To add simulation support, a plugin needs a simulate() function that accepts four arguments simulate(trial, simulation_mode, simulation_options, load_callback) trial : This is the same as the trial parameter passed to the plugin's trial() method. It contains an object of the parameters for the trial. simulation_mode : A string, either \"data-only\" or \"visual\" . This specifies which simulation mode is being requested. Plugins can optionally support \"visual\" mode. If \"visual\" mode is not supported, the plugin should default to \"data-only\" mode when \"visual\" mode is requested. simulation_options : An object of simulation-specific options. load_callback : A function handle to invoke when the simulation is ready to trigger the on_load event for the trial. It is important to invoke this at the correct time during the simulation so that any on_load events in the experiment execute as expected. Typically the flow for supporting simulation mode involves: Generating artificial data that is consistent with the trial parameters. Merging that data with any data specified by the user in simulation_options . Verifying that the final data object is still consistent with the trial parameters. For example, checking that RTs are not longer than the duration of the trial. In data-only mode, call jsPsych.finishTrial() with the artificial data. In visual mode, invoke the trial() method of the plugin and then use the artificial data to trigger the appropriate events. There are a variety of methods in the Plugin API module to assist with things like simulating key presses and mouse clicks. We plan to add a longer guide about simulation development in the future. For now, we recommend browsing the source code of plugins that support simulation mode to see how the flow described above is implemented. Advice for writing plugins \u00b6 If you are developing a plugin with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . We also recommend that you make your plugin as general as possible . Consider using parameters to give the user of the plugin as many options for customization as possible. For example, if you have any text that displays in the plugin including things like button labels, implement the text as a parameter. This allows users running experiments in other languages to replace text values as needed.","title":"Plugin Development"},{"location":"developers/plugin-development/#plugin-development","text":"","title":"Plugin development"},{"location":"developers/plugin-development/#requirements-for-a-plugin","text":"As of version 7.0, plugins are JavaScript Classes . A plugin must implement: A constructor() that accepts an instance of jsPsych. A trial() method that accepts an HTMLElement as its first argument and an object of trial parameters as its second argument. There is an optional third argument to handle the on_load event in certain cirumstances. The trial() method should invoke jsPsych.finishTrial() to end the trial and save data at the appropriate moment. A static info property on the class that contains an object describing the plugin's parameters.","title":"Requirements for a plugin"},{"location":"developers/plugin-development/#templates","text":"Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository .","title":"Templates"},{"location":"developers/plugin-development/#plugin-components","text":"","title":"Plugin components"},{"location":"developers/plugin-development/#constructor","text":"The plugin's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. constructor ( jsPsych ){ this . jsPsych = jsPsych ; }","title":"constructor()"},{"location":"developers/plugin-development/#trial","text":"The plugin's trial() method is responsible for running a single trial. When the jsPsych timeline reaches a trial using the plugin it will invoke the trial() method for the plugin. There are three parameters that are passed into the trial method. display_element is the DOM element where jsPsych content is being rendered. This parameter will be an HTMLElement , and you can use it to modify the portion of the document that jsPsych controls. trial is an object containing all of the parameters specified in the corresponding TimelineNode . on_load is an optional parameter that contains a callback function to invoke when trial() has completed its initial loading. See handling the on_load event . The only requirement for the trial method is that it calls jsPsych.finishTrial() when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point.","title":"trial()"},{"location":"developers/plugin-development/#static-info","text":"The plugin's info property is an object with a name and parameters property. const info = { name : 'my-awesome-plugin' , parameters : { } } The parameters property is an object containing all of the parameters for the plugin. Each parameter has a type and default property. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } If the default value is undefined then a user must specify a value for this parameter when creating a trial using the plugin on the timeline. If they do not, then an error will be generated and shown in the console. If a default value is specified in info then that value will be used by the plugin unless the user overrides it by specifying that property. jsPsych allows most plugin parameters to be dynamic , which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that shouldn't be evaluated before the trial starts, then you should make sure that the parameter type is 'FUNCTION' . This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the canvas-* plugins for examples. The info object should be a static member of the class, as shown below. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } class MyAwesomePlugin { constructor (...) trial (...) } MyAwesomePlugin . info = info ;","title":"static info"},{"location":"developers/plugin-development/#plugin-functionality","text":"Inside the .trial() method you can do pretty much anything that you want, including modifying the DOM, setting up event listeners, and making asynchronous requests. In this section we'll highlight a few common things that you might want to do as examples.","title":"Plugin functionality"},{"location":"developers/plugin-development/#changing-the-content-of-the-display","text":"There are a few ways to change the content of the display. The display_element parameter of the trial method contains the HTMLElement for displaying jsPsych content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the innerHTML . Here's an example of using innerHTML to display an image specified in the trial parameters. trial ( display_element , trial ){ let html_content = `<img src=\" ${ trial . image } \"></img>` ; display_element . innerHTML = html_content ; } jsPsych doesn't clear the display before or after each trial, so it is usually appropriate to use innerHTML to clear the display at the end of a trial. display_element . innerHTML = '' ;","title":"Changing the content of the display"},{"location":"developers/plugin-development/#waiting-for-specified-durations","text":"If you need to delay code execution for a fixed amount of time, we recommend using jsPsych's wrapper of the setTimeout() function, jsPsych.pluginAPI.setTimeout() . In 7.0 the only advantage of using this method is that it registers the timeout handler so that it can be easily cleared at the end of the trial using jsPsych.pluginAPI.clearAllTimeouts() . In future versions we may replace the implementation of jsPsych.pluginAPI.setTimeout() with improved timing functionality based on requestAnimationFrame . trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; // hide image after trial.image_duration milliseconds this . jsPsych . pluginAPI . setTimeout (()=>{ display_element . innerHTML = '' ; }, trial . image_duration ); }","title":"Waiting for specified durations"},{"location":"developers/plugin-development/#responding-to-keyboard-events","text":"While the plugin framework allows you to set up any events that you would like to, including normal handling of keyup or keydown events, the jsPsych.pluginAPI module contains the getKeyboardResponse function , which implements some additional helpful functionality for key responses in an experiment. Here's a basic example. See the getKeyboardResponse docs for additional examples. trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; const after_key_response = ( info ) => { // hide the image display_element . innerHTML = '' ; // record the response time as data let data = { rt : info . rt } // end the trial this . jsPsych . finishTrial ( data ); } // set up a keyboard event to respond only to the spacebar this . jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_key_response , valid_responses : [ ' ' ], persist : false }); }","title":"Responding to keyboard events"},{"location":"developers/plugin-development/#asynchronous-loading","text":"One of the trial events is on_load , which is normally triggered automatically when the .trial() method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the audio-keyboard-response plugin, in which the check to see if the audio file is loaded is asynchronous and the .trial() method returns before the audio file has been initialized and the display updated. If you would like to manually trigger the on_load event for a plugin, the .trial() method accepts an optional third parameter that is a callback function to invoke when loading is complete. In order to tell jsPsych to not invoke the regular callback when the .trial() method returns, you need to explicitly return a Promise . As of version 7.0 this Promise only serves as a flag to tell jsPsych that the on_load event should not be triggered. In future versions we may make the Promise functional so that the trial operation can be an async function. Here's a sketch of how the on_load event can be utilized in a plugin. Note that this example is only a sketch and leaves out all the stuff that happens between loading and finishing the trial. See the source for the audio-keyboard-response plugin for a complete exampe. trial ( display_element , trial , on_load ){ let trial_complete ; do_something_asynchronous (). then (()=>{ on_load (); }); const end_trial = () => { this . jsPsych . finishTrial ({...}) trial_complete (); // not strictly necessary, but doesn't hurt. } return new Promise (( resolve )=>{ trial_complete = resolve ; }) }","title":"Asynchronous loading"},{"location":"developers/plugin-development/#save-data","text":"To write data to jsPsych's data collection pass an object of data as the parameter to jsPsych.finishTrial() . constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial ( display_element , trial ){ let data = { correct : true , rt : 350 } this . jsPsych . finishTrial ( data ); } The data recorded will be that correct is true and that rt is 350 . Additional data for the trial will also be collected automatically.","title":"Save data"},{"location":"developers/plugin-development/#simulation-mode","text":"Plugins can optionally support simulation modes . To add simulation support, a plugin needs a simulate() function that accepts four arguments simulate(trial, simulation_mode, simulation_options, load_callback) trial : This is the same as the trial parameter passed to the plugin's trial() method. It contains an object of the parameters for the trial. simulation_mode : A string, either \"data-only\" or \"visual\" . This specifies which simulation mode is being requested. Plugins can optionally support \"visual\" mode. If \"visual\" mode is not supported, the plugin should default to \"data-only\" mode when \"visual\" mode is requested. simulation_options : An object of simulation-specific options. load_callback : A function handle to invoke when the simulation is ready to trigger the on_load event for the trial. It is important to invoke this at the correct time during the simulation so that any on_load events in the experiment execute as expected. Typically the flow for supporting simulation mode involves: Generating artificial data that is consistent with the trial parameters. Merging that data with any data specified by the user in simulation_options . Verifying that the final data object is still consistent with the trial parameters. For example, checking that RTs are not longer than the duration of the trial. In data-only mode, call jsPsych.finishTrial() with the artificial data. In visual mode, invoke the trial() method of the plugin and then use the artificial data to trigger the appropriate events. There are a variety of methods in the Plugin API module to assist with things like simulating key presses and mouse clicks. We plan to add a longer guide about simulation development in the future. For now, we recommend browsing the source code of plugins that support simulation mode to see how the flow described above is implemented.","title":"Simulation mode"},{"location":"developers/plugin-development/#advice-for-writing-plugins","text":"If you are developing a plugin with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . We also recommend that you make your plugin as general as possible . Consider using parameters to give the user of the plugin as many options for customization as possible. For example, if you have any text that displays in the plugin including things like button labels, implement the text as a parameter. This allows users running experiments in other languages to replace text values as needed.","title":"Advice for writing plugins"},{"location":"extensions/list-of-extensions/","text":"List of Plugins \u00b6 These are the extensions that are included in the jsPsych release. Additional extensions may be available in the community contributions repository . For an overview of what extensions are and how they work, see our extensions overview . Extension Description mouse\u2011tracking Enables tracking of mouse events and recording location of objects on screen. record\u2011video Record video data from the participant's webcam during a trial. webgazer Enables eye tracking using the WebGazer library.","title":"List of Extensions"},{"location":"extensions/list-of-extensions/#list-of-plugins","text":"These are the extensions that are included in the jsPsych release. Additional extensions may be available in the community contributions repository . For an overview of what extensions are and how they work, see our extensions overview . Extension Description mouse\u2011tracking Enables tracking of mouse events and recording location of objects on screen. record\u2011video Record video data from the participant's webcam during a trial. webgazer Enables eye tracking using the WebGazer library.","title":"List of Plugins"},{"location":"extensions/mouse-tracking/","text":"mouse-tracking \u00b6 This extension supports mouse tracking. Specifically, it can record the x and y coordinates, along with the time of mousemove events , mousedown events , and mouseup events . It also allows recording of the bounding rectangle of elements on the screen to support the calculation of mouse events relative to different elements. Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] }) Parameter Type Default Value Description minimum_sample_time number 0 The minimum time between samples for mousemove events in milliseconds. If mousemove events occur more rapidly than this limit, they will not be recorded. Use this if you want to keep the data files smaller and don't need high resolution tracking data. The default value of 0 means that all events will be recorded. Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the mouse tracking data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. events array ['mousemove'] A list of events to track. Can include 'mousemove', 'mousedown', and 'mouseup'. Data Generated \u00b6 Name Type Value mouse_tracking_data array An array of objects containing mouse movement data for the trial. Each object has an x , a y , a t , and an event property. The x and y properties specify the mouse coordinates in pixels relative to the top left corner of the viewport and t specifies the time in milliseconds since the start of the trial. The event will be either 'mousemove', 'mousedown', or 'mouseup' depending on which event was generated. mouse_tracking_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element. Examples \u00b6 Record mouse movement data and play it back Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Move your mouse around inside the square.</p>\" , extensions : [ { type : jsPsychExtensionMouseTracking , params : { targets : [ '#target' ]}} ], data : { task : 'draw' } }; var replay = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto; position: relative;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Here's the recording of your mouse movements</p>\" , on_load : function (){ var mouseMovements = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_data ; var targetRect = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_targets [ '#target' ]; var startTime = performance . now (); function draw_frame () { var timeElapsed = performance . now () - startTime ; var points = mouseMovements . filter (( x ) => x . t <= timeElapsed ); var html = `` ; for ( var p of points ){ html += `<div style=\"width: 3px; height: 3px; background-color: blue; position: absolute; top: ${ p . y - 1 - targetRect . top } px; left: ${ p . x - 1 - targetRect . left } px;\"></div>` } document . querySelector ( '#target' ). innerHTML = html ; if ( points . length < mouseMovements . length ) { requestAnimationFrame ( draw_frame ); } } requestAnimationFrame ( draw_frame ); }, data : { task : 'replay' } } Open demo in new tab","title":"mouse-tracking"},{"location":"extensions/mouse-tracking/#mouse-tracking","text":"This extension supports mouse tracking. Specifically, it can record the x and y coordinates, along with the time of mousemove events , mousedown events , and mouseup events . It also allows recording of the bounding rectangle of elements on the screen to support the calculation of mouse events relative to different elements.","title":"mouse-tracking"},{"location":"extensions/mouse-tracking/#parameters","text":"","title":"Parameters"},{"location":"extensions/mouse-tracking/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] }) Parameter Type Default Value Description minimum_sample_time number 0 The minimum time between samples for mousemove events in milliseconds. If mousemove events occur more rapidly than this limit, they will not be recorded. Use this if you want to keep the data files smaller and don't need high resolution tracking data. The default value of 0 means that all events will be recorded.","title":"Initialization Parameters"},{"location":"extensions/mouse-tracking/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the mouse tracking data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. events array ['mousemove'] A list of events to track. Can include 'mousemove', 'mousedown', and 'mouseup'.","title":"Trial Parameters"},{"location":"extensions/mouse-tracking/#data-generated","text":"Name Type Value mouse_tracking_data array An array of objects containing mouse movement data for the trial. Each object has an x , a y , a t , and an event property. The x and y properties specify the mouse coordinates in pixels relative to the top left corner of the viewport and t specifies the time in milliseconds since the start of the trial. The event will be either 'mousemove', 'mousedown', or 'mouseup' depending on which event was generated. mouse_tracking_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element.","title":"Data Generated"},{"location":"extensions/mouse-tracking/#examples","text":"Record mouse movement data and play it back Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Move your mouse around inside the square.</p>\" , extensions : [ { type : jsPsychExtensionMouseTracking , params : { targets : [ '#target' ]}} ], data : { task : 'draw' } }; var replay = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto; position: relative;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Here's the recording of your mouse movements</p>\" , on_load : function (){ var mouseMovements = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_data ; var targetRect = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_targets [ '#target' ]; var startTime = performance . now (); function draw_frame () { var timeElapsed = performance . now () - startTime ; var points = mouseMovements . filter (( x ) => x . t <= timeElapsed ); var html = `` ; for ( var p of points ){ html += `<div style=\"width: 3px; height: 3px; background-color: blue; position: absolute; top: ${ p . y - 1 - targetRect . top } px; left: ${ p . x - 1 - targetRect . left } px;\"></div>` } document . querySelector ( '#target' ). innerHTML = html ; if ( points . length < mouseMovements . length ) { requestAnimationFrame ( draw_frame ); } } requestAnimationFrame ( draw_frame ); }, data : { task : 'replay' } } Open demo in new tab","title":"Examples"},{"location":"extensions/record-video/","text":"record-video \u00b6 This extension records video from the participant's webcam during a trial. This extension encodes the video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] }) Parameter Type Default Value Description None Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] } Parameter Type Default Value Description None Data Generated \u00b6 Name Type Value record_video_data base64 string Base 64 encoded representation of the video data. Examples \u00b6 Record video data during a trial Code Demo const init_camera = { type : jsPsychInitializeCamera }; const trial = { type : jsPsychHtmlButtonResponse , stimulus : `<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; position: relative; margin: 2em auto;\"> <div class=\"orbit\" style=\"width:25px; height:25px; border-radius:25px;background-color: #f00; position: absolute; top:calc(50% - 12px); left:calc(50% - 12px);\"></div> </div> <style> .orbit { transform: translateX(100px); animation: orbit 4s infinite; } @keyframes orbit { 0% { transform: rotate(0deg) translateX(100px); } 100% { transform: rotate(360deg) translateX(100px); } } </style>` , choices : [ 'Done' ], prompt : \"<p>Video is recording. Click done after a few seconds.</p>\" , extensions : [ { type : jsPsychExtensionRecordVideo } ] }; Open demo in new tab","title":"record-video"},{"location":"extensions/record-video/#record-video","text":"This extension records video from the participant's webcam during a trial. This extension encodes the video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R.","title":"record-video"},{"location":"extensions/record-video/#parameters","text":"","title":"Parameters"},{"location":"extensions/record-video/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] }) Parameter Type Default Value Description None","title":"Initialization Parameters"},{"location":"extensions/record-video/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] } Parameter Type Default Value Description None","title":"Trial Parameters"},{"location":"extensions/record-video/#data-generated","text":"Name Type Value record_video_data base64 string Base 64 encoded representation of the video data.","title":"Data Generated"},{"location":"extensions/record-video/#examples","text":"Record video data during a trial Code Demo const init_camera = { type : jsPsychInitializeCamera }; const trial = { type : jsPsychHtmlButtonResponse , stimulus : `<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; position: relative; margin: 2em auto;\"> <div class=\"orbit\" style=\"width:25px; height:25px; border-radius:25px;background-color: #f00; position: absolute; top:calc(50% - 12px); left:calc(50% - 12px);\"></div> </div> <style> .orbit { transform: translateX(100px); animation: orbit 4s infinite; } @keyframes orbit { 0% { transform: rotate(0deg) translateX(100px); } 100% { transform: rotate(360deg) translateX(100px); } } </style>` , choices : [ 'Done' ], prompt : \"<p>Video is recording. Click done after a few seconds.</p>\" , extensions : [ { type : jsPsychExtensionRecordVideo } ] }; Open demo in new tab","title":"Examples"},{"location":"extensions/webgazer/","text":"webgazer \u00b6 This extension supports eye tracking through the WebGazer library. For a narrative description of how to use this extension see the eye tracking overview . Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] }) Parameter Type Default Value Description webgazer object undefined You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global webgazer object. If you are loading webgazer.js via a <script> tag you do not need to set this parameter in most circumstances. auto_initialize bool false Whether to automatically initialize webgazer when the experiment begins. If set to true then the experiment will attempt to access the user's webcam immediately upon page load. The default value is false because it is probably a good idea to explain to the user why camera permission will be needed before asking for it. The webgazer-init-camera plugin can be used to initialize the camera during the experiment. round_predictions bool true Whether to round the x , y coordinates predicted by WebGazer to the nearest whole number. This greatly reduces the size of the data, as WebGazer records data to 15 decimal places by default. Given the noise of the system, there's really no need to record data to this level of precision. sampling_interval numeric 34 Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second. Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the WebGazer data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. Data Generated \u00b6 Name Type Value webgazer_data array An array of objects containing gaze data for the trial. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. webgazer_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element. Functions \u00b6 In addition to the jsPsych webgazer-* plugins, the jsPsych webgazer extension provides a set of functions that allow the researcher to interact more directly with WebGazer. These functions can be called at any point during an experiment, and are crucial for building trial plugins that interact with WebGazer. All of the functions below must be prefixed with jsPsych.extensions.webgazer (e.g. jsPsych.extensions.webgazer.faceDetected() ). start() \u00b6 Performs initialization of webgazer, including requesting permissions from the user to access the camera. Returns a Promise that resolves when the camera is initialized and fails if the camera cannot be accessed, e.g., because the user denies permission. This is handled automatically if using the webgazer-init-camera plugin or setting auto_initialize to true in the extension parameters. isInitialized() \u00b6 Returns true if start() has been successfully called at some point, and false otherwise. faceDetected() \u00b6 Returns true if WebGazer is ready to make predictions ( webgazer.getTracker().predictionReady is true ). showPredictions() \u00b6 Turns on WebGazer's real-time visualization of predicted gaze location. hidePredictions() \u00b6 Turns off WebGazer's real-time visualization of predicted gaze location. showVideo() \u00b6 Turns on a display of the webcam image, guiding box for positioning the face, and WebGazer's estimate of the location of facial landmarks. hideVideo() \u00b6 Turns off the camera display. resume() \u00b6 Turns on gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer. pause() \u00b6 Turns off gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer. resetCalibration() \u00b6 Clears all calibration data. startMouseCalibration() \u00b6 Turns on mouse movement and mouse clicks as calibration events. While the webgazer-calibration plugin can also be used to run a parmeterized calibration routine, this calibration function call allows you to continuously calibrate WebGazer to any mouse movements or clicks throughout the experiment. For example, any *-button-response trial would also function as a WebGazer calibration event. stopMouseCalibration() \u00b6 Stops WebGazer from using mouse movements and mouse clicks as calibration events. calibratePoint(x, y) \u00b6 Instructs WebGazer to register the location x , y (in screen pixel coordinates) as a calibration event. Can be used for passive viewing calibration, i.e., instructing participants to fixate at a particular location. setRegressionType(regression_type) \u00b6 Change the method that WebGazer is using to perform feature -> location regression. Valid options are ridge , weightedRidge , and threadedRidge . See the WebGazer docs for more information about these options. The extension uses the default mode specified by WebGazer (currently ridge ). getCurrentPrediction() \u00b6 Get the current predicted gaze location from WebGazer. This returns a Promise that resolves once WebGazer has finished computing the gaze prediction. The Promise has a single parameter with an object with x , y , and, t parameters. t will be the value of performance.now() at approximately the time that the video frame was recorded. startSampleInterval(interval) \u00b6 Starts sampling gaze predictions every interval milliseconds. If interval is left undefined then the default value at extension initialization is used. Every sample will trigger an onGazeUpdate callback, as well as side effects that result in data storage within the extension. stopSampleInterval() \u00b6 Stops the sampling started by startSampleInterval() . onGazeUpdate(callback) \u00b6 Subscribe to gaze updates. The callback will be invoked every time a new gaze prediction is generated. The first argument of the callback will be an object with x , y , and, if currently in a trial with the extension turned on, the time t in ms since the start of the trial. t will be the value of performance.now() at approximately the time that the video frame was recorded. If currently in an active trial then t will be relative to the start of the trial. This function returns a close handler. When you no longer need to subscribe to gaze updates, call the close handler. Example: var cancelGazeUpdateHandler = jsPsych . extensions . webgazer . onGazeUpdate ( function ( prediction ){ console . log ( `Currently looking at ${ prediction . x } , ${ prediction . y } ` ); }); cancelGazeUpdateHandler (); You can add multiple handlers. Handlers are not closed automatically, so be sure to cancel them when no longer needed.","title":"webgazer"},{"location":"extensions/webgazer/#webgazer","text":"This extension supports eye tracking through the WebGazer library. For a narrative description of how to use this extension see the eye tracking overview .","title":"webgazer"},{"location":"extensions/webgazer/#parameters","text":"","title":"Parameters"},{"location":"extensions/webgazer/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] }) Parameter Type Default Value Description webgazer object undefined You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global webgazer object. If you are loading webgazer.js via a <script> tag you do not need to set this parameter in most circumstances. auto_initialize bool false Whether to automatically initialize webgazer when the experiment begins. If set to true then the experiment will attempt to access the user's webcam immediately upon page load. The default value is false because it is probably a good idea to explain to the user why camera permission will be needed before asking for it. The webgazer-init-camera plugin can be used to initialize the camera during the experiment. round_predictions bool true Whether to round the x , y coordinates predicted by WebGazer to the nearest whole number. This greatly reduces the size of the data, as WebGazer records data to 15 decimal places by default. Given the noise of the system, there's really no need to record data to this level of precision. sampling_interval numeric 34 Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second.","title":"Initialization Parameters"},{"location":"extensions/webgazer/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the WebGazer data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded.","title":"Trial Parameters"},{"location":"extensions/webgazer/#data-generated","text":"Name Type Value webgazer_data array An array of objects containing gaze data for the trial. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. webgazer_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element.","title":"Data Generated"},{"location":"extensions/webgazer/#functions","text":"In addition to the jsPsych webgazer-* plugins, the jsPsych webgazer extension provides a set of functions that allow the researcher to interact more directly with WebGazer. These functions can be called at any point during an experiment, and are crucial for building trial plugins that interact with WebGazer. All of the functions below must be prefixed with jsPsych.extensions.webgazer (e.g. jsPsych.extensions.webgazer.faceDetected() ).","title":"Functions"},{"location":"extensions/webgazer/#start","text":"Performs initialization of webgazer, including requesting permissions from the user to access the camera. Returns a Promise that resolves when the camera is initialized and fails if the camera cannot be accessed, e.g., because the user denies permission. This is handled automatically if using the webgazer-init-camera plugin or setting auto_initialize to true in the extension parameters.","title":"start()"},{"location":"extensions/webgazer/#isinitialized","text":"Returns true if start() has been successfully called at some point, and false otherwise.","title":"isInitialized()"},{"location":"extensions/webgazer/#facedetected","text":"Returns true if WebGazer is ready to make predictions ( webgazer.getTracker().predictionReady is true ).","title":"faceDetected()"},{"location":"extensions/webgazer/#showpredictions","text":"Turns on WebGazer's real-time visualization of predicted gaze location.","title":"showPredictions()"},{"location":"extensions/webgazer/#hidepredictions","text":"Turns off WebGazer's real-time visualization of predicted gaze location.","title":"hidePredictions()"},{"location":"extensions/webgazer/#showvideo","text":"Turns on a display of the webcam image, guiding box for positioning the face, and WebGazer's estimate of the location of facial landmarks.","title":"showVideo()"},{"location":"extensions/webgazer/#hidevideo","text":"Turns off the camera display.","title":"hideVideo()"},{"location":"extensions/webgazer/#resume","text":"Turns on gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer.","title":"resume()"},{"location":"extensions/webgazer/#pause","text":"Turns off gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer.","title":"pause()"},{"location":"extensions/webgazer/#resetcalibration","text":"Clears all calibration data.","title":"resetCalibration()"},{"location":"extensions/webgazer/#startmousecalibration","text":"Turns on mouse movement and mouse clicks as calibration events. While the webgazer-calibration plugin can also be used to run a parmeterized calibration routine, this calibration function call allows you to continuously calibrate WebGazer to any mouse movements or clicks throughout the experiment. For example, any *-button-response trial would also function as a WebGazer calibration event.","title":"startMouseCalibration()"},{"location":"extensions/webgazer/#stopmousecalibration","text":"Stops WebGazer from using mouse movements and mouse clicks as calibration events.","title":"stopMouseCalibration()"},{"location":"extensions/webgazer/#calibratepointx-y","text":"Instructs WebGazer to register the location x , y (in screen pixel coordinates) as a calibration event. Can be used for passive viewing calibration, i.e., instructing participants to fixate at a particular location.","title":"calibratePoint(x, y)"},{"location":"extensions/webgazer/#setregressiontyperegression_type","text":"Change the method that WebGazer is using to perform feature -> location regression. Valid options are ridge , weightedRidge , and threadedRidge . See the WebGazer docs for more information about these options. The extension uses the default mode specified by WebGazer (currently ridge ).","title":"setRegressionType(regression_type)"},{"location":"extensions/webgazer/#getcurrentprediction","text":"Get the current predicted gaze location from WebGazer. This returns a Promise that resolves once WebGazer has finished computing the gaze prediction. The Promise has a single parameter with an object with x , y , and, t parameters. t will be the value of performance.now() at approximately the time that the video frame was recorded.","title":"getCurrentPrediction()"},{"location":"extensions/webgazer/#startsampleintervalinterval","text":"Starts sampling gaze predictions every interval milliseconds. If interval is left undefined then the default value at extension initialization is used. Every sample will trigger an onGazeUpdate callback, as well as side effects that result in data storage within the extension.","title":"startSampleInterval(interval)"},{"location":"extensions/webgazer/#stopsampleinterval","text":"Stops the sampling started by startSampleInterval() .","title":"stopSampleInterval()"},{"location":"extensions/webgazer/#ongazeupdatecallback","text":"Subscribe to gaze updates. The callback will be invoked every time a new gaze prediction is generated. The first argument of the callback will be an object with x , y , and, if currently in a trial with the extension turned on, the time t in ms since the start of the trial. t will be the value of performance.now() at approximately the time that the video frame was recorded. If currently in an active trial then t will be relative to the start of the trial. This function returns a close handler. When you no longer need to subscribe to gaze updates, call the close handler. Example: var cancelGazeUpdateHandler = jsPsych . extensions . webgazer . onGazeUpdate ( function ( prediction ){ console . log ( `Currently looking at ${ prediction . x } , ${ prediction . y } ` ); }); cancelGazeUpdateHandler (); You can add multiple handlers. Handlers are not closed automatically, so be sure to cancel them when no longer needed.","title":"onGazeUpdate(callback)"},{"location":"overview/browser-device-support/","text":"Browser and Device Support \u00b6 Desktop and Laptop Browsers \u00b6 Supported jsPsych supports recent versions of the four most commonly-used web browsers: Chrome Firefox Safari Edge This means that jsPsych should work on these browsers. If something doesn't work as you expect on one of the browsers above, it might be a bug that should be fixed. You can search for and report bugs on the jsPsych GitHub Issues page . We're very grateful for anyone who takes the time to report bugs - it helps improve the library for everyone! Unsupported There are many other web browsers that are available, but that are not commonly used. The most well-known of these are Internet Explorer and Opera. jsPsych is not tested on these and other browsers not listed in the Supported section above. jsPsych experiments might work in these browsers, but they might not . If you want to give participants the option to use unsupported browsers, then we recommend carefully testing your experiment to make sure that everything works as expected. Otherwise, we suggest asking your participants to only use a supported browser, or incorporating browser, device, and/or feature checks at the start of your experiment. jsPsych offers built-in methods for exclusion based on minimum browser size and WebAudio API compatibility . You can incorporate other browser/device/feature checks into your experiment by adding custom JavaScript code. Mobile Devices \u00b6 In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen. If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that: * Font sizes are readable on smaller screens * Stimuli sizes are large enough and appropriate for the task * Page is laid out as intended (e.g. elements are centered and do not overlap) * Response options are touchscreen-friendly (e.g. buttons rather than key presses) * Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap It's possible to use your browser's developer tools to emulate mobile devices ( this page shows how to do it in Chrome ), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate. Mobile Browsers \u00b6 The browser options for mobile phones and tablets are slightly different than those for desktop and laptop computers. In addition to mobile versions of Chrome, Firefox, Safari, and Edge, other notable mobile browsers include Opera Mobile, Samsung Internet, UC Browser, and Dolphin. Because of the greater diversity of mobile browsers and volatility in their usage statistics, jsPsych does not officially support any particular set of mobile browsers. However, we do anticipate that most experiments should work in most mobile browsers, especially the mobile versions of browsers that we do support in Desktop mode. If you run into a problem using jsPsych in mobile browsers, please report it on the jsPsych GitHub Issues page ! We do our best to fix browser incompatibilities that are not specific to a single experiment.","title":"Browser and Device Support"},{"location":"overview/browser-device-support/#browser-and-device-support","text":"","title":"Browser and Device Support"},{"location":"overview/browser-device-support/#desktop-and-laptop-browsers","text":"Supported jsPsych supports recent versions of the four most commonly-used web browsers: Chrome Firefox Safari Edge This means that jsPsych should work on these browsers. If something doesn't work as you expect on one of the browsers above, it might be a bug that should be fixed. You can search for and report bugs on the jsPsych GitHub Issues page . We're very grateful for anyone who takes the time to report bugs - it helps improve the library for everyone! Unsupported There are many other web browsers that are available, but that are not commonly used. The most well-known of these are Internet Explorer and Opera. jsPsych is not tested on these and other browsers not listed in the Supported section above. jsPsych experiments might work in these browsers, but they might not . If you want to give participants the option to use unsupported browsers, then we recommend carefully testing your experiment to make sure that everything works as expected. Otherwise, we suggest asking your participants to only use a supported browser, or incorporating browser, device, and/or feature checks at the start of your experiment. jsPsych offers built-in methods for exclusion based on minimum browser size and WebAudio API compatibility . You can incorporate other browser/device/feature checks into your experiment by adding custom JavaScript code.","title":"Desktop and Laptop Browsers"},{"location":"overview/browser-device-support/#mobile-devices","text":"In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen. If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that: * Font sizes are readable on smaller screens * Stimuli sizes are large enough and appropriate for the task * Page is laid out as intended (e.g. elements are centered and do not overlap) * Response options are touchscreen-friendly (e.g. buttons rather than key presses) * Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap It's possible to use your browser's developer tools to emulate mobile devices ( this page shows how to do it in Chrome ), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate.","title":"Mobile Devices"},{"location":"overview/browser-device-support/#mobile-browsers","text":"The browser options for mobile phones and tablets are slightly different than those for desktop and laptop computers. In addition to mobile versions of Chrome, Firefox, Safari, and Edge, other notable mobile browsers include Opera Mobile, Samsung Internet, UC Browser, and Dolphin. Because of the greater diversity of mobile browsers and volatility in their usage statistics, jsPsych does not officially support any particular set of mobile browsers. However, we do anticipate that most experiments should work in most mobile browsers, especially the mobile versions of browsers that we do support in Desktop mode. If you run into a problem using jsPsych in mobile browsers, please report it on the jsPsych GitHub Issues page ! We do our best to fix browser incompatibilities that are not specific to a single experiment.","title":"Mobile Browsers"},{"location":"overview/data/","text":"Data in jsPsych: permanent and non-permanent data. \u00b6 There are two very different kinds of data storage: data stored in memory and data stored permanently . Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a server. Data stored in memory exists only as long the browser window running jsPsych is open. jsPsych has many features for interacting with data stored in memory, but few for permanent data storage. This is a deliberate choice, as there are dozens of ways that data could be stored permanently. jsPsych does not lock you into one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and the second half of this page contains a few suggestions on how to accomplish permanent data storage. Storing data in jsPsych's data structure \u00b6 jsPsych has a centralized collection of data that is built as the experiment runs. Each trial adds to the collection, and you can access the data with various functions, including jsPsych.data.get() , which returns the entire set of data. In most cases, data collection will be automatic and hidden. Plugins save data on their own so it is not uncommon to have the only interaction with the data be at the end of the experiment when it is time to save it in a permanent manner (see sections below about how to do this). However, there are some situations in which you may want to interact with the data; in particular, you may want to store additional data that the plugins are not recording, like a subject identifier or condition assignment. You may also want to add data on a trial by trial basis. For example, in a Stroop paradigm you would want to label which trials are congruent and which are incongruent. These scenarios are explored below. Adding data to all trials \u00b6 Often it is useful to add a piece of data to all of the trials in the experiment. For example, appending the subject ID to each trial. This can be done with the jsPsych.data.addProperties() function. Here is an example: // generate a random subject ID with 15 characters var subject_id = jsPsych . randomization . randomID ( 15 ); // pick a random condition for the subject at the start of the experiment var condition_assignment = jsPsych . randomization . sampleWithoutReplacement ([ 'conditionA' , 'conditionB' , 'conditionC' ], 1 )[ 0 ]; // record the condition assignment in the jsPsych data // this adds a property called 'subject' and a property called 'condition' to every trial jsPsych . data . addProperties ({ subject : subject_id , condition : condition_assignment }); Adding data to a particular trial or set of trials \u00b6 Data can be added to a particular trial by setting the data parameter for the trial. The data parameter is an object of key-value pairs, and each pair is added to the data for that trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , data : { image_type : 'A' } } Data declared in this way is also saved in the trials on any nested timelines: var block = { type : jsPsychImageKeyboardResponse , data : { image_type : 'A' }, timeline : [ { stimulus : 'imgA1.jpg' }, { stimulus : 'imgA2.jpg' } ] } The data object for a trial can also be updated in the on_finish event handler. You can override properties or add new ones. This is particularly useful for cases where the value depends on something that happened during the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } } Aggregating and manipulating jsPsych data \u00b6 When accessing the data with jsPsych.data.get() the returned object is a special data collection object that exposes a number of methods for aggregating and manipulating the data. The full list of methods is detailed in the data module documentation . Here are some examples of data collection manipulation. All data generated by the image-keyboard-response plugin: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }); All data generated by the categorize-image plugin with a correct response: var data = jsPsych . data . get (). filter ({ trial_type : 'categorize-image' , correct : true }); All data with a response time between 100 and 500ms: var data = jsPsych . data . get (). filterCustom ( function ( x ){ return x . rt >= 100 && x . rt <= 500 }); Applying filters consecutively to get all trials from a particular plugin with a response time above 100ms: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }). filterCustom ( function ( x ){ return x . rt > 100 ; }); Getting the data from the last n trials: var n = 3 ; var data = jsPsych . data . get (). last ( n ); Getting the data from the last n trials with a correct response: var n = 3 ; var data = jsPsych . data . get (). filter ({ correct : true }). last ( n ); Getting the data from the first n trials: var n = 3 ; var data = jsPsych . data . get (). first ( n ); Counting the number of trials with a correct response in a data collection: var count = jsPsych . data . get (). filter ({ correct : true }). count (); Selecting all of the response times from a data collection: var response_times = jsPsych . data . get (). select ( 'rt' ); Calculating various descriptive statistics on the response times in a data collection: jsPsych . data . get (). select ( 'rt' ). mean (); jsPsych . data . get (). select ( 'rt' ). sum (); jsPsych . data . get (). select ( 'rt' ). min (); jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). variance (); jsPsych . data . get (). select ( 'rt' ). sd (); jsPsych . data . get (). select ( 'rt' ). median (); jsPsych . data . get (). select ( 'rt' ). count (); Storing data permanently as a file \u00b6 This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server. This method will only work if you are running on a web server with PHP installed, or a local server with PHP (e.g., XAMPP ). This method uses a short PHP script to write files to the server: <?php // get the data from the POST message $post_data = json_decode ( file_get_contents ( 'php://input' ), true ); $data = $post_data [ 'filedata' ]; // generate a unique ID for the file, e.g., session-6feu833950202 $file = uniqid ( \"session-\" ); // the directory \"data\" must be writable by the server $name = \"data/ { $file } .csv\" ; // write the file to disk file_put_contents ( $name , $data ); ?> The file_put_contents($name, $data) method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission to that directory. In the above example, the directory data/ is used to store files. To use the PHP script, the JavaScript that runs jsPsych needs to send the filedata information. This is done through an AJAX call. function saveData ( name , data ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // 'write_data.php' is the path to the php file described above. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . send ( JSON . stringify ({ filedata : data })); } // call the saveData function after the experiment is over initJsPsych ({ on_finish : function (){ saveData ( jsPsych . data . get (). csv ()); } }); Danger The example above has minimal security and should probably not be used without additional security measures put in place. The risk is that someone can write arbitrary data using the saveData() function and store it to a file on your webserver. If they can guess the file name generated by the PHP script, or access a directory listing containing all of the filenames, then they can potentially write executable code to your server and run it. One fix is to store the CSV files outside the web directory on the server. This requires changing the path in the PHP script above from /data to a folder that is not accessible on the web. You should only use this solution if you have access to more than just the web directory on your server. You can also configure your web server to block access to the folder you are storing data in . The MySQL option below is more secure. Storing data permanently in a MySQL database \u00b6 Another solution for storing data generated by jsPsych is to write it to a database. There are dozens of database options. MySQL is one of the most popular relational databases , is free to use, and relatively easy to install . This code will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code. If you are trying to run on a local machine, you'll need to install a local server environment like XAMPP . You'll need two PHP scripts. The first is a configuration file for your database. Save it as database_config.php on your server. Within this file are configuration options for the database. You'll need to change these according to how you have configured your MySQL installation. <?php $servername = \"localhost\" ; $port = 3306 ; $username = \"username\" ; $password = \"password\" ; $dbname = \"database\" ; $table = \"tablename\" ; ?> The second PHP file will write data to the database. This script reads the database to discover what columns are in the table, and then only allows data to be entered in that matches those columns. This is a security feature. Save this file as write_data.php on your server. <?php // this path should point to your configuration file. include ( 'database_config.php' ); $data_array = json_decode ( file_get_contents ( 'php://input' ), true ); try { $conn = new PDO ( \"mysql:host= $servername ;port= $port ;dbname= $dbname \" , $username , $password ); $conn -> setAttribute ( PDO :: ATTR_ERRMODE , PDO :: ERRMODE_EXCEPTION ); // First stage is to get all column names from the table and store // them in $col_names array. $stmt = $conn -> prepare ( \"SHOW COLUMNS FROM ` $table `\" ); $stmt -> execute (); $col_names = array (); while ( $row = $stmt -> fetchColumn ()) { $col_names [] = $row ; } // Second stage is to create prepared SQL statement using the column // names as a guide to what values might be in the JSON. // If a value is missing from a particular trial, then NULL is inserted $sql = \"INSERT INTO $table VALUES(\" ; for ( $i = 0 ; $i < count ( $col_names ); $i ++ ){ $name = $col_names [ $i ]; $sql .= \": $name \" ; if ( $i != count ( $col_names ) - 1 ){ $sql .= \", \" ; } } $sql .= \");\" ; $insertstmt = $conn -> prepare ( $sql ); for ( $i = 0 ; $i < count ( $data_array ); $i ++ ){ for ( $j = 0 ; $j < count ( $col_names ); $j ++ ){ $colname = $col_names [ $j ]; if ( ! isset ( $data_array [ $i ][ $colname ])){ $insertstmt -> bindValue ( \": $colname \" , null , PDO :: PARAM_NULL ); } else { $insertstmt -> bindValue ( \": $colname \" , $data_array [ $i ][ $colname ]); } } $insertstmt -> execute (); } echo '{\"success\": true}' ; } catch ( PDOException $e ) { echo '{\"success\": false, \"message\": ' . $e -> getMessage (); } $conn = null ; ?> To send the data, we use an XMLHttpRequest request in JavaScript. function saveData () { var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // change 'write_data.php' to point to php script. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } }; xhr . send ( jsPsych . data . get (). json ()); } It's important that the XMLHttpRequest is able to complete before the experiment is closed. If you invoke the saveData() function at the end of your experiment and the participant closes the window before all of the data has been transferred you will lose that data. To mitigate this risk, you can use the call-function plugin's async option to prevent the experiment from progressing until the request is complete. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } done (); // invoking done() causes experiment to progress to next trial. }; xhr . send ( jsPsych . data . get (). json ()); } }","title":"Data Storage, Aggregation, and Manipulation"},{"location":"overview/data/#data-in-jspsych-permanent-and-non-permanent-data","text":"There are two very different kinds of data storage: data stored in memory and data stored permanently . Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a server. Data stored in memory exists only as long the browser window running jsPsych is open. jsPsych has many features for interacting with data stored in memory, but few for permanent data storage. This is a deliberate choice, as there are dozens of ways that data could be stored permanently. jsPsych does not lock you into one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and the second half of this page contains a few suggestions on how to accomplish permanent data storage.","title":"Data in jsPsych: permanent and non-permanent data."},{"location":"overview/data/#storing-data-in-jspsychs-data-structure","text":"jsPsych has a centralized collection of data that is built as the experiment runs. Each trial adds to the collection, and you can access the data with various functions, including jsPsych.data.get() , which returns the entire set of data. In most cases, data collection will be automatic and hidden. Plugins save data on their own so it is not uncommon to have the only interaction with the data be at the end of the experiment when it is time to save it in a permanent manner (see sections below about how to do this). However, there are some situations in which you may want to interact with the data; in particular, you may want to store additional data that the plugins are not recording, like a subject identifier or condition assignment. You may also want to add data on a trial by trial basis. For example, in a Stroop paradigm you would want to label which trials are congruent and which are incongruent. These scenarios are explored below.","title":"Storing data in jsPsych's data structure"},{"location":"overview/data/#adding-data-to-all-trials","text":"Often it is useful to add a piece of data to all of the trials in the experiment. For example, appending the subject ID to each trial. This can be done with the jsPsych.data.addProperties() function. Here is an example: // generate a random subject ID with 15 characters var subject_id = jsPsych . randomization . randomID ( 15 ); // pick a random condition for the subject at the start of the experiment var condition_assignment = jsPsych . randomization . sampleWithoutReplacement ([ 'conditionA' , 'conditionB' , 'conditionC' ], 1 )[ 0 ]; // record the condition assignment in the jsPsych data // this adds a property called 'subject' and a property called 'condition' to every trial jsPsych . data . addProperties ({ subject : subject_id , condition : condition_assignment });","title":"Adding data to all trials"},{"location":"overview/data/#adding-data-to-a-particular-trial-or-set-of-trials","text":"Data can be added to a particular trial by setting the data parameter for the trial. The data parameter is an object of key-value pairs, and each pair is added to the data for that trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , data : { image_type : 'A' } } Data declared in this way is also saved in the trials on any nested timelines: var block = { type : jsPsychImageKeyboardResponse , data : { image_type : 'A' }, timeline : [ { stimulus : 'imgA1.jpg' }, { stimulus : 'imgA2.jpg' } ] } The data object for a trial can also be updated in the on_finish event handler. You can override properties or add new ones. This is particularly useful for cases where the value depends on something that happened during the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } }","title":"Adding data to a particular trial or set of trials"},{"location":"overview/data/#aggregating-and-manipulating-jspsych-data","text":"When accessing the data with jsPsych.data.get() the returned object is a special data collection object that exposes a number of methods for aggregating and manipulating the data. The full list of methods is detailed in the data module documentation . Here are some examples of data collection manipulation. All data generated by the image-keyboard-response plugin: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }); All data generated by the categorize-image plugin with a correct response: var data = jsPsych . data . get (). filter ({ trial_type : 'categorize-image' , correct : true }); All data with a response time between 100 and 500ms: var data = jsPsych . data . get (). filterCustom ( function ( x ){ return x . rt >= 100 && x . rt <= 500 }); Applying filters consecutively to get all trials from a particular plugin with a response time above 100ms: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }). filterCustom ( function ( x ){ return x . rt > 100 ; }); Getting the data from the last n trials: var n = 3 ; var data = jsPsych . data . get (). last ( n ); Getting the data from the last n trials with a correct response: var n = 3 ; var data = jsPsych . data . get (). filter ({ correct : true }). last ( n ); Getting the data from the first n trials: var n = 3 ; var data = jsPsych . data . get (). first ( n ); Counting the number of trials with a correct response in a data collection: var count = jsPsych . data . get (). filter ({ correct : true }). count (); Selecting all of the response times from a data collection: var response_times = jsPsych . data . get (). select ( 'rt' ); Calculating various descriptive statistics on the response times in a data collection: jsPsych . data . get (). select ( 'rt' ). mean (); jsPsych . data . get (). select ( 'rt' ). sum (); jsPsych . data . get (). select ( 'rt' ). min (); jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). variance (); jsPsych . data . get (). select ( 'rt' ). sd (); jsPsych . data . get (). select ( 'rt' ). median (); jsPsych . data . get (). select ( 'rt' ). count ();","title":"Aggregating and manipulating jsPsych data"},{"location":"overview/data/#storing-data-permanently-as-a-file","text":"This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server. This method will only work if you are running on a web server with PHP installed, or a local server with PHP (e.g., XAMPP ). This method uses a short PHP script to write files to the server: <?php // get the data from the POST message $post_data = json_decode ( file_get_contents ( 'php://input' ), true ); $data = $post_data [ 'filedata' ]; // generate a unique ID for the file, e.g., session-6feu833950202 $file = uniqid ( \"session-\" ); // the directory \"data\" must be writable by the server $name = \"data/ { $file } .csv\" ; // write the file to disk file_put_contents ( $name , $data ); ?> The file_put_contents($name, $data) method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission to that directory. In the above example, the directory data/ is used to store files. To use the PHP script, the JavaScript that runs jsPsych needs to send the filedata information. This is done through an AJAX call. function saveData ( name , data ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // 'write_data.php' is the path to the php file described above. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . send ( JSON . stringify ({ filedata : data })); } // call the saveData function after the experiment is over initJsPsych ({ on_finish : function (){ saveData ( jsPsych . data . get (). csv ()); } }); Danger The example above has minimal security and should probably not be used without additional security measures put in place. The risk is that someone can write arbitrary data using the saveData() function and store it to a file on your webserver. If they can guess the file name generated by the PHP script, or access a directory listing containing all of the filenames, then they can potentially write executable code to your server and run it. One fix is to store the CSV files outside the web directory on the server. This requires changing the path in the PHP script above from /data to a folder that is not accessible on the web. You should only use this solution if you have access to more than just the web directory on your server. You can also configure your web server to block access to the folder you are storing data in . The MySQL option below is more secure.","title":"Storing data permanently as a file"},{"location":"overview/data/#storing-data-permanently-in-a-mysql-database","text":"Another solution for storing data generated by jsPsych is to write it to a database. There are dozens of database options. MySQL is one of the most popular relational databases , is free to use, and relatively easy to install . This code will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code. If you are trying to run on a local machine, you'll need to install a local server environment like XAMPP . You'll need two PHP scripts. The first is a configuration file for your database. Save it as database_config.php on your server. Within this file are configuration options for the database. You'll need to change these according to how you have configured your MySQL installation. <?php $servername = \"localhost\" ; $port = 3306 ; $username = \"username\" ; $password = \"password\" ; $dbname = \"database\" ; $table = \"tablename\" ; ?> The second PHP file will write data to the database. This script reads the database to discover what columns are in the table, and then only allows data to be entered in that matches those columns. This is a security feature. Save this file as write_data.php on your server. <?php // this path should point to your configuration file. include ( 'database_config.php' ); $data_array = json_decode ( file_get_contents ( 'php://input' ), true ); try { $conn = new PDO ( \"mysql:host= $servername ;port= $port ;dbname= $dbname \" , $username , $password ); $conn -> setAttribute ( PDO :: ATTR_ERRMODE , PDO :: ERRMODE_EXCEPTION ); // First stage is to get all column names from the table and store // them in $col_names array. $stmt = $conn -> prepare ( \"SHOW COLUMNS FROM ` $table `\" ); $stmt -> execute (); $col_names = array (); while ( $row = $stmt -> fetchColumn ()) { $col_names [] = $row ; } // Second stage is to create prepared SQL statement using the column // names as a guide to what values might be in the JSON. // If a value is missing from a particular trial, then NULL is inserted $sql = \"INSERT INTO $table VALUES(\" ; for ( $i = 0 ; $i < count ( $col_names ); $i ++ ){ $name = $col_names [ $i ]; $sql .= \": $name \" ; if ( $i != count ( $col_names ) - 1 ){ $sql .= \", \" ; } } $sql .= \");\" ; $insertstmt = $conn -> prepare ( $sql ); for ( $i = 0 ; $i < count ( $data_array ); $i ++ ){ for ( $j = 0 ; $j < count ( $col_names ); $j ++ ){ $colname = $col_names [ $j ]; if ( ! isset ( $data_array [ $i ][ $colname ])){ $insertstmt -> bindValue ( \": $colname \" , null , PDO :: PARAM_NULL ); } else { $insertstmt -> bindValue ( \": $colname \" , $data_array [ $i ][ $colname ]); } } $insertstmt -> execute (); } echo '{\"success\": true}' ; } catch ( PDOException $e ) { echo '{\"success\": false, \"message\": ' . $e -> getMessage (); } $conn = null ; ?> To send the data, we use an XMLHttpRequest request in JavaScript. function saveData () { var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // change 'write_data.php' to point to php script. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } }; xhr . send ( jsPsych . data . get (). json ()); } It's important that the XMLHttpRequest is able to complete before the experiment is closed. If you invoke the saveData() function at the end of your experiment and the participant closes the window before all of the data has been transferred you will lose that data. To mitigate this risk, you can use the call-function plugin's async option to prevent the experiment from progressing until the request is complete. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } done (); // invoking done() causes experiment to progress to next trial. }; xhr . send ( jsPsych . data . get (). json ()); } }","title":"Storing data permanently in a MySQL database"},{"location":"overview/dynamic-parameters/","text":"Dynamic parameters \u00b6 Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial . This enables dynamic updating of the parameter based on data that a participant has generated or any other information that you do not know in advance. Examples \u00b6 Providing Feedback \u00b6 Here is a sketch of how this functionality could be used to display feedback to a participant in the Flanker Task. var timeline = []; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_finish : function ( data ){ // Score the keyboard response as correct or incorrect. if ( jsPsych . pluginAPI . compareKeys ( data . response , \"f\" )){ data . correct = true ; } else { data . correct = false ; } } } var feedback = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ // The feedback stimulus is a dynamic parameter because we can't know in advance whether // the stimulus should be 'correct' or 'incorrect'. // Instead, this function will check the accuracy of the last response and use that information to set // the stimulus value on each trial. var last_trial_correct = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. correct ; if ( last_trial_correct ){ return \"<p>Correct!</p>\" ; // the parameter value has to be returned from the function } else { return \"<p>Wrong.</p>\" ; // the parameter value has to be returned from the function } } } timeline . push ( trial , feedback ); Note When scoring a participant's response, the jsPsych.pluginAPI.compareKeys function is only needed to compare keyboard responses. For other kinds of response types, such as button presses, you can compare the participant's response and correct response values directly, e.g. if ( data . response == 0 )){ data . correct = true ; } else { data . correct = false ; } Or: data . correct = data . response === data . correct_response ; Randomizing a parameter value \u00b6 Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function. var random_duration = function () { var rand_dur = jsPsych . randomization . sampleWithoutReplacement ([ 500 , 600 , 700 , 800 ], 1 )[ 0 ]; return rand_dur ; } var trial = { type : jsPsychHtmlKeyboardResponse stimulus : '+' , post_trial_gap : random_duration // if you use a named function for a dynamic parameter, then just use the function name (without parentheses after it) } Storing changing variables in the data \u00b6 The trial's data parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called current_difficulty that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this: var current_difficulty ; // value changes during the experiment var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : function () { return { difficulty : current_difficulty }; } } It's also possible to use a function for any of the individual properties in the trial's data object, for instance if you want to combine static and dynamic information in the data: var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : { difficulty : function () { return current_difficulty ; // the difficulty value changes during the experiment }, task_part : 'recall' , // this part of the data is always the same block_number : 1 } } Nested Parameters \u00b6 Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a questions parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the questions parameter dynamic, you can use a function that returns the array with all of the parameters for each question: var subject_id ; // value is set during the experiment var trial = { type : jsPsychSurveyText , questions : function (){ var questions_array = [ { prompt : \"Hi \" + subject_id + \"! What's your favorite city?\" , required : true , name : 'fav_city' }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' }, ]; return questions_array ; } } You can also use a function for any of the individual parameters inside of a nested parameter. var trial = { type : jsPsychSurveyText , questions : [ { prompt : function () { // this question prompt is dynamic - the text that is shown // will change based on the participant's earlier response var favorite_city = jsPsych . data . getLastTrialData (). values ()[ 0 ]. response . fav_city ; var text = \"Earlier you said your favorite city is \" + favorite_city + \". What do you like most about \" + favorite_city + \"?\" return text ; }, required : true , rows : 40 , columns : 10 }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' } ] } When dynamic parameters can't be used \u00b6 Note that if the plugin expects the value of a given parameter to be a function, then this function will not be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the stimulus parameter in the canvas-* plugins, the mistake_fn parameter in the cloze plugin, and the stim_function parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's type in the plugin.info section of the plugin file. If the parameter type is ParameterType.FUNCTION , then this parameter must be a function and it will not be executed before the trial starts. Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.","title":"Dynamic Parameters"},{"location":"overview/dynamic-parameters/#dynamic-parameters","text":"Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial . This enables dynamic updating of the parameter based on data that a participant has generated or any other information that you do not know in advance.","title":"Dynamic parameters"},{"location":"overview/dynamic-parameters/#examples","text":"","title":"Examples"},{"location":"overview/dynamic-parameters/#providing-feedback","text":"Here is a sketch of how this functionality could be used to display feedback to a participant in the Flanker Task. var timeline = []; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_finish : function ( data ){ // Score the keyboard response as correct or incorrect. if ( jsPsych . pluginAPI . compareKeys ( data . response , \"f\" )){ data . correct = true ; } else { data . correct = false ; } } } var feedback = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ // The feedback stimulus is a dynamic parameter because we can't know in advance whether // the stimulus should be 'correct' or 'incorrect'. // Instead, this function will check the accuracy of the last response and use that information to set // the stimulus value on each trial. var last_trial_correct = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. correct ; if ( last_trial_correct ){ return \"<p>Correct!</p>\" ; // the parameter value has to be returned from the function } else { return \"<p>Wrong.</p>\" ; // the parameter value has to be returned from the function } } } timeline . push ( trial , feedback ); Note When scoring a participant's response, the jsPsych.pluginAPI.compareKeys function is only needed to compare keyboard responses. For other kinds of response types, such as button presses, you can compare the participant's response and correct response values directly, e.g. if ( data . response == 0 )){ data . correct = true ; } else { data . correct = false ; } Or: data . correct = data . response === data . correct_response ;","title":"Providing Feedback"},{"location":"overview/dynamic-parameters/#randomizing-a-parameter-value","text":"Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function. var random_duration = function () { var rand_dur = jsPsych . randomization . sampleWithoutReplacement ([ 500 , 600 , 700 , 800 ], 1 )[ 0 ]; return rand_dur ; } var trial = { type : jsPsychHtmlKeyboardResponse stimulus : '+' , post_trial_gap : random_duration // if you use a named function for a dynamic parameter, then just use the function name (without parentheses after it) }","title":"Randomizing a parameter value"},{"location":"overview/dynamic-parameters/#storing-changing-variables-in-the-data","text":"The trial's data parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called current_difficulty that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this: var current_difficulty ; // value changes during the experiment var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : function () { return { difficulty : current_difficulty }; } } It's also possible to use a function for any of the individual properties in the trial's data object, for instance if you want to combine static and dynamic information in the data: var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : { difficulty : function () { return current_difficulty ; // the difficulty value changes during the experiment }, task_part : 'recall' , // this part of the data is always the same block_number : 1 } }","title":"Storing changing variables in the data"},{"location":"overview/dynamic-parameters/#nested-parameters","text":"Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a questions parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the questions parameter dynamic, you can use a function that returns the array with all of the parameters for each question: var subject_id ; // value is set during the experiment var trial = { type : jsPsychSurveyText , questions : function (){ var questions_array = [ { prompt : \"Hi \" + subject_id + \"! What's your favorite city?\" , required : true , name : 'fav_city' }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' }, ]; return questions_array ; } } You can also use a function for any of the individual parameters inside of a nested parameter. var trial = { type : jsPsychSurveyText , questions : [ { prompt : function () { // this question prompt is dynamic - the text that is shown // will change based on the participant's earlier response var favorite_city = jsPsych . data . getLastTrialData (). values ()[ 0 ]. response . fav_city ; var text = \"Earlier you said your favorite city is \" + favorite_city + \". What do you like most about \" + favorite_city + \"?\" return text ; }, required : true , rows : 40 , columns : 10 }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' } ] }","title":"Nested Parameters"},{"location":"overview/dynamic-parameters/#when-dynamic-parameters-cant-be-used","text":"Note that if the plugin expects the value of a given parameter to be a function, then this function will not be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the stimulus parameter in the canvas-* plugins, the mistake_fn parameter in the cloze plugin, and the stim_function parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's type in the plugin.info section of the plugin file. If the parameter type is ParameterType.FUNCTION , then this parameter must be a function and it will not be executed before the trial starts. Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.","title":"When dynamic parameters can't be used"},{"location":"overview/events/","text":"Event-related callback functions \u00b6 jsPsych offers the ability to call arbitrary functions in response to certain events occurring, like the end of a trial or when new data is saved. This page summarizes the different opportunities for callback functions and how to specify them. on_close \u00b6 The on_close callback can be declared in the initJsPsych method. The callback triggers when the user leaves the page, but before any content on the page is removed from the browser's memory. This can be used, for example, to save data as the user is leaving the page. initJsPsych ({ on_close : function (){ var data = jsPsych . data . get (). json (); save_data_to_server ( data ); } }); on_data_update \u00b6 The on_data_update callback can be declared in the initJsPsych method. The callback triggers at the end of a data update cycle. This happens after every trial, after the on_finish (trial) and on_trial_finish events execute, allowing you to modify the data in those callbacks, and then use this callback to store the data. The function will be passed a single argument, which contains the data that was written. initJsPsych ({ on_data_update : function ( data ) { console . log ( 'Just added new data. The contents of the data are: ' + JSON . stringify ( data )); } }); on_finish (trial) \u00b6 The on_finish callback can be added to any trial. The callback will trigger whenever the trial ends. The callback function will be passed a single argument, containing the data object from the trial. This data object is editable . Any changes made in the on_finish function will be stored in the internal data collection. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } }; on_finish (experiment) \u00b6 The on_finish callback can be declared in the initJsPsych method. The callback will trigger once all trials in the experiment have been run. The method will be passed a single argument, containing all of the data generated in the experiment. initJsPsych ({ on_finish : function ( data ) { console . log ( 'The experiment is over! Here is all the data: ' + JSON . stringify ( data )); } }); on_load \u00b6 The on_load callback can be added to any trial. The callback will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { console . log ( 'The trial just finished loading.' ); } }; on_start (trial) \u00b6 The on_start callback can be added to any trial. The callback will trigger right before the trial begins. The callback function will be passed a single argument, containing the trial object. If any of the parameters of the trial are functions or timeline variables, these will be evaluated before on_start is called, and the trial object will contain the evaluated value. The trial object is modifiable, and any changes made will affect the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_start : function ( trial ) { console . log ( 'The trial is about to start.' ); trial . stimulus = 'imgB.png' ; // this will change what stimulus is displayed in the trial } }; on_timeline_finish \u00b6 The on_timeline_finish callback can be declared in a timeline node. The callback will be triggered when the timeline ends during the experiment. If timeline_variables , conditional_function , loop_function , or sample options are used, this function will execute when all trials have finished. If a loop_function is used, then this on_timeline_finish function will be triggered before the loop function. If the repetitions option is used, this function will be triggered at the end of every repetition. var procedure = { timeline : [ trial1 , trial2 ], timeline_variables : [ { stimulus : 'person-1.jpg' }, { stimulus : 'person-2.jpg' }, { stimulus : 'person-3.jpg' }, { stimulus : 'person-4.jpg' } ], on_timeline_finish : function () { console . log ( 'This timeline has finished.' ); }, loop_function : function () { console . log ( 'This loop function will execute after on_timeline_finish.' ); return false ; } } on_timeline_start \u00b6 The on_timeline_start callback can be declared in a timeline node. The callback will be triggered when the timeline starts during the experiment, including when timeline_variables , loop_function , or sample options are used. If a conditional_function is used, then the conditional function will execute first, and the on_timeline_start function will only execute if the conditional function returns true . If the repetitions option is used, this function will be triggered at the start of every repetition. var procedure = { timeline : [ trial1 , trial2 ], conditional_function : function () { console . log ( 'This conditional function will execute first.' ) return true ; }, on_timeline_start : function () { console . log ( 'This timeline has started' ); } } on_trial_finish \u00b6 The on_trial_finish callback can be declared in the initJsPsych method. The callback will trigger at the end of every trial in the experiment. If you want a callback to trigger only for the end of certain trials, use the on_finish callback on the trial object. The callback function will be passed a single argument, containing the data object from the trial. initJsPsych ({ on_trial_finish : function ( data ) { console . log ( 'A trial just ended.' ); console . log ( JSON . stringify ( data )); } }); on_trial_start \u00b6 The on_trial_start callback can be declared in the initJsPsych method. The callback will trigger at the start of every trial in the experiment. The function receives a single argument: a modifiable copy of the trial object that will be used to run the next trial. Changes can be made to this object to alter the parameters of the upcoming trial. var current_score = 0 ; // a variable that is updated throughout the experiment to keep track of the current score. initJsPsych ({ on_trial_start : function ( trial ) { trial . data . score_at_start_of_trial = current_score ; console . log ( 'A trial just started.' ); } });","title":"Events"},{"location":"overview/events/#event-related-callback-functions","text":"jsPsych offers the ability to call arbitrary functions in response to certain events occurring, like the end of a trial or when new data is saved. This page summarizes the different opportunities for callback functions and how to specify them.","title":"Event-related callback functions"},{"location":"overview/events/#on_close","text":"The on_close callback can be declared in the initJsPsych method. The callback triggers when the user leaves the page, but before any content on the page is removed from the browser's memory. This can be used, for example, to save data as the user is leaving the page. initJsPsych ({ on_close : function (){ var data = jsPsych . data . get (). json (); save_data_to_server ( data ); } });","title":"on_close"},{"location":"overview/events/#on_data_update","text":"The on_data_update callback can be declared in the initJsPsych method. The callback triggers at the end of a data update cycle. This happens after every trial, after the on_finish (trial) and on_trial_finish events execute, allowing you to modify the data in those callbacks, and then use this callback to store the data. The function will be passed a single argument, which contains the data that was written. initJsPsych ({ on_data_update : function ( data ) { console . log ( 'Just added new data. The contents of the data are: ' + JSON . stringify ( data )); } });","title":"on_data_update"},{"location":"overview/events/#on_finish-trial","text":"The on_finish callback can be added to any trial. The callback will trigger whenever the trial ends. The callback function will be passed a single argument, containing the data object from the trial. This data object is editable . Any changes made in the on_finish function will be stored in the internal data collection. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } };","title":"on_finish (trial)"},{"location":"overview/events/#on_finish-experiment","text":"The on_finish callback can be declared in the initJsPsych method. The callback will trigger once all trials in the experiment have been run. The method will be passed a single argument, containing all of the data generated in the experiment. initJsPsych ({ on_finish : function ( data ) { console . log ( 'The experiment is over! Here is all the data: ' + JSON . stringify ( data )); } });","title":"on_finish (experiment)"},{"location":"overview/events/#on_load","text":"The on_load callback can be added to any trial. The callback will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { console . log ( 'The trial just finished loading.' ); } };","title":"on_load"},{"location":"overview/events/#on_start-trial","text":"The on_start callback can be added to any trial. The callback will trigger right before the trial begins. The callback function will be passed a single argument, containing the trial object. If any of the parameters of the trial are functions or timeline variables, these will be evaluated before on_start is called, and the trial object will contain the evaluated value. The trial object is modifiable, and any changes made will affect the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_start : function ( trial ) { console . log ( 'The trial is about to start.' ); trial . stimulus = 'imgB.png' ; // this will change what stimulus is displayed in the trial } };","title":"on_start (trial)"},{"location":"overview/events/#on_timeline_finish","text":"The on_timeline_finish callback can be declared in a timeline node. The callback will be triggered when the timeline ends during the experiment. If timeline_variables , conditional_function , loop_function , or sample options are used, this function will execute when all trials have finished. If a loop_function is used, then this on_timeline_finish function will be triggered before the loop function. If the repetitions option is used, this function will be triggered at the end of every repetition. var procedure = { timeline : [ trial1 , trial2 ], timeline_variables : [ { stimulus : 'person-1.jpg' }, { stimulus : 'person-2.jpg' }, { stimulus : 'person-3.jpg' }, { stimulus : 'person-4.jpg' } ], on_timeline_finish : function () { console . log ( 'This timeline has finished.' ); }, loop_function : function () { console . log ( 'This loop function will execute after on_timeline_finish.' ); return false ; } }","title":"on_timeline_finish"},{"location":"overview/events/#on_timeline_start","text":"The on_timeline_start callback can be declared in a timeline node. The callback will be triggered when the timeline starts during the experiment, including when timeline_variables , loop_function , or sample options are used. If a conditional_function is used, then the conditional function will execute first, and the on_timeline_start function will only execute if the conditional function returns true . If the repetitions option is used, this function will be triggered at the start of every repetition. var procedure = { timeline : [ trial1 , trial2 ], conditional_function : function () { console . log ( 'This conditional function will execute first.' ) return true ; }, on_timeline_start : function () { console . log ( 'This timeline has started' ); } }","title":"on_timeline_start"},{"location":"overview/events/#on_trial_finish","text":"The on_trial_finish callback can be declared in the initJsPsych method. The callback will trigger at the end of every trial in the experiment. If you want a callback to trigger only for the end of certain trials, use the on_finish callback on the trial object. The callback function will be passed a single argument, containing the data object from the trial. initJsPsych ({ on_trial_finish : function ( data ) { console . log ( 'A trial just ended.' ); console . log ( JSON . stringify ( data )); } });","title":"on_trial_finish"},{"location":"overview/events/#on_trial_start","text":"The on_trial_start callback can be declared in the initJsPsych method. The callback will trigger at the start of every trial in the experiment. The function receives a single argument: a modifiable copy of the trial object that will be used to run the next trial. Changes can be made to this object to alter the parameters of the upcoming trial. var current_score = 0 ; // a variable that is updated throughout the experiment to keep track of the current score. initJsPsych ({ on_trial_start : function ( trial ) { trial . data . score_at_start_of_trial = current_score ; console . log ( 'A trial just started.' ); } });","title":"on_trial_start"},{"location":"overview/exclude-browser/","text":"Exclude Participants Based on Browser Features \u00b6 Changed in 7.1 Online participants will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. As of v7.1 of jsPsych, the recommended way to do this is using the browser-check plugin . This plugin can record many features of the participant's browser and exclude participants who do not meet a defined set of inclusion criteria. Please see the browser-check plugin documentation for more details. The prior approach of using the exclusions parameter in initJsPsych() is deprecated and will be removed in v8.0 . You can find the documentation for it in the 7.0 docs .","title":"Exclude Participants Based on Browser Features"},{"location":"overview/exclude-browser/#exclude-participants-based-on-browser-features","text":"Changed in 7.1 Online participants will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. As of v7.1 of jsPsych, the recommended way to do this is using the browser-check plugin . This plugin can record many features of the participant's browser and exclude participants who do not meet a defined set of inclusion criteria. Please see the browser-check plugin documentation for more details. The prior approach of using the exclusions parameter in initJsPsych() is deprecated and will be removed in v8.0 . You can find the documentation for it in the 7.0 docs .","title":"Exclude Participants Based on Browser Features"},{"location":"overview/experiment-options/","text":"Experiment-wide settings \u00b6 There are several options that can be set when calling initJsPsych() to initialize the jsPsych experiment. Options are specified in the object passed to initJsPsych . For example, to specify a default inter-trial interval, a minimum valid response time duration, and a maximum width for all of the experiment's page content, the object would contain: initJsPsych ({ default_iti : 250 , minimum_valid_rt : 100 , experiment_width : 800 }); Controlling where jsPsych renders on the page \u00b6 By default, jsPsych will render the experiment in the <body> element of a page. It is possible to display the experiment in a different element (e.g., a <div> ) by specifying the display_element parameter. < body > < div id = \"jspsych-target\" ></ div > </ body > < script > initJsPsych ({ display_element : 'jspsych-target' }); </ script > This option is useful if the experiment needs to be rendered on a page with other content (e.g., a demo version of the experiment with annotation text), or if additional control over the display element is desired. Custom CSS rules can be applied to position, size, scale, etc. the display element. Experiment events \u00b6 Several experiment-wide events can trigger functions. This is documented in more detail on the event-related callback functions page . The events that trigger functions are: on_finish : Called at the end of the experiment. on_trial_start : Called at the beginning of every trial. on_trial_finish : Called at the end of every trial. on_data_update : Called whenever new data is added to the jsPsych data object. on_interaction_data_update : Called whenever new interaction data (e.g., the participant enters or exits fullscreen mode) is added. on_close : Called right before the page closes, such as when a participant closes the experiment early. Specify exclusion criteria \u00b6 Exclusion criteria can be specified based on features of the user's web browser, such as the display size and whether certain features are reported. See the page on excluding participants based on browser features . Display a progress bar \u00b6 An automatic or manually updated progress bar can be displayed at the top of the screen. By default, the text next to the progress bar is \"Completion Progress\", but this text can be changed with the message_progress_bar parameter in initJsPsych . See the progress bar page for more details. Choose the method for playing audio files \u00b6 Specifying the use_webaudio parameter in initJsPsych() allows you to choose whether to use the WebAudio API or HTML5 audio for playing audio files during your experiment. By default, jsPsych uses the WebAudio API to play audio files. Among other features, the WebAudio API allows for more precise measurement of response times relative to the onset of the audio. However, loading files through the WebAudio API causes errors when running an experiment offline (i.e., by double-clicking on the HTML file, rather than hosting it on a web server). This is due to the cross-origin security policy implemented by web browsers. For this reason, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline, and automatically uses HTML5 audio to prevent errors, even when use_webaudio has been explicitly set to true . For more information, see the section Cross-origin requests (CORS) and safe mode on the Running Experiments page. initJsPsych ({ use_webaudio : false }); Set the default intertrial interval \u00b6 By default the next trial in a timeline will begin immediately after the conclusion of the previous trial. An experiment-wide delay can be specified using the default_iti parameter to initJsPsych() . initJsPsych ({ default_iti : 500 }); This parameter is specified in milliseconds. A blank screen will display between each trial for the duration of the ITI. Specify the maximum width of the experiment \u00b6 The experiment will, by default, take up 100% of the display element. Usually the display element is the <body> , and the experiment is the full width of the screen. (This can be overridden by specifying the display_element parameter described above). Specifying the experiment_width parameter will set a maximum width for the display. The parameter is specified in pixels. initJsPsych ({ experiment_width : 750 }); Specify a minimum valid response time \u00b6 By default, jsPsych will treat any keyboard response time as valid. However, it's possible to specify a minimum valid response time (in ms) for key presses. Any key press 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. // ignore any keyboard responses that are less than 100 ms initJsPsych ({ minimum_valid_rt : 100 }); Choose whether you want keyboard choices/responses to be case-sensitive \u00b6 JavaScript keyboard events make a distinction between uppercase and lowercase key responses (e.g. 'a' and 'A'). Often the researcher just cares about which physical key was pressed, and not whether the key press would result in an uppercase letter (for instance, if CapsLock is on or if the Shift key is held down). For this reason, jsPsych converts all key choice parameters and key responses as lowercase by default. This makes it easier to specify key choices (e.g. choices: ['a'] , instead of choices: ['a','A'] ), and it makes it easier to check and score a participant's response. There may be situations when you want key choices and responses to be case-sensitive. You can change this by setting the case_sensitive_responses parameter to true in initJsPsych . // use case-sensitive key choices and responses, // i.e. uppercase and lower case letters ('a' and 'A') will be treated as different key choices, // and will be recorded this way in the data initJsPsych ({ case_sensitive_responses : true }); Note that this setting only applies to key choices and responses that use jsPsych's keyboard response listener, such as in the * -keyboard-response plugins. This does NOT apply to responses that are made by typing into a text box, such as in the survey-text and cloze plugins. Override 'safe mode' when running experiments offline \u00b6 By default, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline (via the file:// protocol) in order to prevent certain errors. Specifically, in safe mode, HTML5 audio is used to play audio files (even when use_webaudio has been explicitly set to true ) and video preloading is disabled (both automatic and manual preloading). For more information, see the Cross-origin requests (CORS) and safe mode section on the Running Experiments page. It's possible to override this safe mode feature by setting the override_safe_mode parameter to true in initJsPsych . This is something you might do if you've disabled certain security settings in your browser for testing purposes. This parameter has no effect when your experiment is running online (on a server), because it will be using the http:// or https:// protocol, which does not trigger safe mode. initJsPsych ({ override_safe_mode : true }); Add extensions \u00b6 Extensions are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with initJsPsych . The extensions parameter in initJsPsych is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] });","title":"Experiment Settings"},{"location":"overview/experiment-options/#experiment-wide-settings","text":"There are several options that can be set when calling initJsPsych() to initialize the jsPsych experiment. Options are specified in the object passed to initJsPsych . For example, to specify a default inter-trial interval, a minimum valid response time duration, and a maximum width for all of the experiment's page content, the object would contain: initJsPsych ({ default_iti : 250 , minimum_valid_rt : 100 , experiment_width : 800 });","title":"Experiment-wide settings"},{"location":"overview/experiment-options/#controlling-where-jspsych-renders-on-the-page","text":"By default, jsPsych will render the experiment in the <body> element of a page. It is possible to display the experiment in a different element (e.g., a <div> ) by specifying the display_element parameter. < body > < div id = \"jspsych-target\" ></ div > </ body > < script > initJsPsych ({ display_element : 'jspsych-target' }); </ script > This option is useful if the experiment needs to be rendered on a page with other content (e.g., a demo version of the experiment with annotation text), or if additional control over the display element is desired. Custom CSS rules can be applied to position, size, scale, etc. the display element.","title":"Controlling where jsPsych renders on the page"},{"location":"overview/experiment-options/#experiment-events","text":"Several experiment-wide events can trigger functions. This is documented in more detail on the event-related callback functions page . The events that trigger functions are: on_finish : Called at the end of the experiment. on_trial_start : Called at the beginning of every trial. on_trial_finish : Called at the end of every trial. on_data_update : Called whenever new data is added to the jsPsych data object. on_interaction_data_update : Called whenever new interaction data (e.g., the participant enters or exits fullscreen mode) is added. on_close : Called right before the page closes, such as when a participant closes the experiment early.","title":"Experiment events"},{"location":"overview/experiment-options/#specify-exclusion-criteria","text":"Exclusion criteria can be specified based on features of the user's web browser, such as the display size and whether certain features are reported. See the page on excluding participants based on browser features .","title":"Specify exclusion criteria"},{"location":"overview/experiment-options/#display-a-progress-bar","text":"An automatic or manually updated progress bar can be displayed at the top of the screen. By default, the text next to the progress bar is \"Completion Progress\", but this text can be changed with the message_progress_bar parameter in initJsPsych . See the progress bar page for more details.","title":"Display a progress bar"},{"location":"overview/experiment-options/#choose-the-method-for-playing-audio-files","text":"Specifying the use_webaudio parameter in initJsPsych() allows you to choose whether to use the WebAudio API or HTML5 audio for playing audio files during your experiment. By default, jsPsych uses the WebAudio API to play audio files. Among other features, the WebAudio API allows for more precise measurement of response times relative to the onset of the audio. However, loading files through the WebAudio API causes errors when running an experiment offline (i.e., by double-clicking on the HTML file, rather than hosting it on a web server). This is due to the cross-origin security policy implemented by web browsers. For this reason, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline, and automatically uses HTML5 audio to prevent errors, even when use_webaudio has been explicitly set to true . For more information, see the section Cross-origin requests (CORS) and safe mode on the Running Experiments page. initJsPsych ({ use_webaudio : false });","title":"Choose the method for playing audio files"},{"location":"overview/experiment-options/#set-the-default-intertrial-interval","text":"By default the next trial in a timeline will begin immediately after the conclusion of the previous trial. An experiment-wide delay can be specified using the default_iti parameter to initJsPsych() . initJsPsych ({ default_iti : 500 }); This parameter is specified in milliseconds. A blank screen will display between each trial for the duration of the ITI.","title":"Set the default intertrial interval"},{"location":"overview/experiment-options/#specify-the-maximum-width-of-the-experiment","text":"The experiment will, by default, take up 100% of the display element. Usually the display element is the <body> , and the experiment is the full width of the screen. (This can be overridden by specifying the display_element parameter described above). Specifying the experiment_width parameter will set a maximum width for the display. The parameter is specified in pixels. initJsPsych ({ experiment_width : 750 });","title":"Specify the maximum width of the experiment"},{"location":"overview/experiment-options/#specify-a-minimum-valid-response-time","text":"By default, jsPsych will treat any keyboard response time as valid. However, it's possible to specify a minimum valid response time (in ms) for key presses. Any key press 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. // ignore any keyboard responses that are less than 100 ms initJsPsych ({ minimum_valid_rt : 100 });","title":"Specify a minimum valid response time"},{"location":"overview/experiment-options/#choose-whether-you-want-keyboard-choicesresponses-to-be-case-sensitive","text":"JavaScript keyboard events make a distinction between uppercase and lowercase key responses (e.g. 'a' and 'A'). Often the researcher just cares about which physical key was pressed, and not whether the key press would result in an uppercase letter (for instance, if CapsLock is on or if the Shift key is held down). For this reason, jsPsych converts all key choice parameters and key responses as lowercase by default. This makes it easier to specify key choices (e.g. choices: ['a'] , instead of choices: ['a','A'] ), and it makes it easier to check and score a participant's response. There may be situations when you want key choices and responses to be case-sensitive. You can change this by setting the case_sensitive_responses parameter to true in initJsPsych . // use case-sensitive key choices and responses, // i.e. uppercase and lower case letters ('a' and 'A') will be treated as different key choices, // and will be recorded this way in the data initJsPsych ({ case_sensitive_responses : true }); Note that this setting only applies to key choices and responses that use jsPsych's keyboard response listener, such as in the * -keyboard-response plugins. This does NOT apply to responses that are made by typing into a text box, such as in the survey-text and cloze plugins.","title":"Choose whether you want keyboard choices/responses to be case-sensitive"},{"location":"overview/experiment-options/#override-safe-mode-when-running-experiments-offline","text":"By default, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline (via the file:// protocol) in order to prevent certain errors. Specifically, in safe mode, HTML5 audio is used to play audio files (even when use_webaudio has been explicitly set to true ) and video preloading is disabled (both automatic and manual preloading). For more information, see the Cross-origin requests (CORS) and safe mode section on the Running Experiments page. It's possible to override this safe mode feature by setting the override_safe_mode parameter to true in initJsPsych . This is something you might do if you've disabled certain security settings in your browser for testing purposes. This parameter has no effect when your experiment is running online (on a server), because it will be using the http:// or https:// protocol, which does not trigger safe mode. initJsPsych ({ override_safe_mode : true });","title":"Override 'safe mode' when running experiments offline"},{"location":"overview/experiment-options/#add-extensions","text":"Extensions are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with initJsPsych . The extensions parameter in initJsPsych is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] });","title":"Add extensions"},{"location":"overview/extensions/","text":"Extensions \u00b6 Extensions are jsPsych modules that can interface with any plugin to extend the functionality of the plugin. A canonical example of an extension is eye tracking. An eye tracking extension allows a plugin to gather gaze data and add it to the plugin's data object. Using an Extension \u00b6 To use an extension in an experiment, you'll load the extension file via a <script> tag (just like adding a plugin) and then initialize the extension in the parameters of initJsPsych() . < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-example@1.0.0\" ></ script > </ head > initJsPsych ({ extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }) To enable an extension during a trial, add the extension to the extensions list for the trial. Some extensions may also support or require an object of parameters to configure the extension: var trial = { extensions : [ { type : jsPsychExtensionExample , params : {...} } ] } List of Extensions \u00b6 Extension Description jspsych\u2011ext\u2011webgazer.js Enables eye tracking using the WebGazer library. Writing an Extension \u00b6 See our developer's guide for extensions for information about how to create a new extension.","title":"Extensions"},{"location":"overview/extensions/#extensions","text":"Extensions are jsPsych modules that can interface with any plugin to extend the functionality of the plugin. A canonical example of an extension is eye tracking. An eye tracking extension allows a plugin to gather gaze data and add it to the plugin's data object.","title":"Extensions"},{"location":"overview/extensions/#using-an-extension","text":"To use an extension in an experiment, you'll load the extension file via a <script> tag (just like adding a plugin) and then initialize the extension in the parameters of initJsPsych() . < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-example@1.0.0\" ></ script > </ head > initJsPsych ({ extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }) To enable an extension during a trial, add the extension to the extensions list for the trial. Some extensions may also support or require an object of parameters to configure the extension: var trial = { extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }","title":"Using an Extension"},{"location":"overview/extensions/#list-of-extensions","text":"Extension Description jspsych\u2011ext\u2011webgazer.js Enables eye tracking using the WebGazer library.","title":"List of Extensions"},{"location":"overview/extensions/#writing-an-extension","text":"See our developer's guide for extensions for information about how to create a new extension.","title":"Writing an Extension"},{"location":"overview/eye-tracking/","text":"Eye Tracking \u00b6 jsPsych supports eye tracking through the WebGazer library. WebGazer uses computer vision techniques to identify features of the participant's eyes via a webcam and predicts gaze location. The system is calibrated by having the participant click on or look at known locations on the screen. These locations are linked to eye features. Gaze location is predicted using regression. Getting Started \u00b6 Load webgazer.js \u00b6 The official version of WebGazer is currently not supported by jsPsych. Our fork of the library contains some minor improvements aimed at the kind of experiments that jsPsych is typically used for, e.g., situations in which the timing of display screens needs to be accurate. You must include the webgazer.js file in your experiment via a <script> tag. However, the webgazer.js file is not part of any of the jsPsych NPM packages and is therefore not available via the unpkg.com CDN. Instead, it can be found on the jsdelivr.net CDN at: \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > </ head > Note A copy of our forked webgazer.js file is also included in the jsPsych release, in the /examples/js/webgazer folder. So if you prefer to download and host all of your jsPsych files (i.e. set-up option 2 in the Hello World tutorial), then another option is to load that file rather than using the jsdelivr link above. Assuming you downloaded the release and copied the webgazer.js file into a folder called js/webgazer in your root project directory, then you would load the file like this: < script src = \"js/webgazer/webgazer.js\" ></ script > Load the jsPsych webgazer extension \u00b6 The webgazer extension adds functionality to jsPsych for interacting with webgazer. Load it like you would a plugin file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > </ head > To use the WebGazer extension in an experiment, include it in the list of extensions passed to initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) Initialize the camera \u00b6 To help the participant position their face correctly for eye tracking you can use the webgazer-init-camera plugin . This will show the participant what the camera sees, including facial feature landmarks, and prevent the participant from continuing until their face is in good position for eye tracking. This plugin will also trigger the experiment to request permission to access the user's webcam if it hasn't already been granted. var init_camera_trial = { type : jsPsychWebgazerInitCamera } Calibration \u00b6 To calibrate WebGazer, you can use the webgazer-calibrate plugin . This plugin allows you to specify a set of points on the screen for calibration and to choose the method for calibrating -- either clicking on each point or simply fixating on each point. The location of calibration points is specified in percentages, e.g., [25,50] will result in a point that is 25% of the width of the screen from the left edge and 50% of the height of the screen from the top edge. Options for controlling other details of the calibration are explained in the documentation for the plugin . Note that instructions are not included in the calibration plugin, so you'll likely want to use a different plugin (e.g., html-button-response ) to display instructions prior to running the calibration. var calibration_trial = { type : jsPsychWebgazerCalibrate , calibration_points : [[ 25 , 50 ], [ 50 , 50 ], [ 75 , 50 ], [ 50 , 25 ], [ 50 , 75 ]], calibration_mode : 'click' } Validation \u00b6 To measure the accuracy and precision of the calibration, you can use the webgazer-vaidate plugin . Like the calibration plugin, you can specify a list of points to perform validation on. Here you can specify the points as either percentages or in terms of the distance from the center of the screen in pixels. Which mode you use will probably depend on how you are defining your stimuli throughout the experiment. You can also specify the radius of tolerance around each point, and the plugin will calculate the percentage of measured gaze samples within that radius. This is a potentially useful heuristic for deciding whether or not to calibrate again. Options for controlling other details of the validation are explained in the documentation for the plugin . var validation_trial = { type : jsPsychWebgazerValidate , validation_points : [[ - 200 , 200 ], [ 200 , 200 ],[ - 200 , - 200 ],[ 200 , - 200 ]], validation_point_coordinates : 'center-offset-pixels' , roi_radius : 100 } The validation procedure stores the raw gaze data for each validation point, the computed average offset from each validation point, the percentage of samples within the roi_radius for each validation point, and the number of samples collected per second. { raw_gaze : [...], percent_in_roi : [...], average_offset : [...], samples_per_sec : ... } We recommend performing calibration and validation periodically throughout your experiment. Adding eye tracking to a trial \u00b6 To enable eye tracking for a trial in your experiment, you can simply add the WebGazer extension to the trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img id=\"scene\" src=\"my-scene.png\"></img>' , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#scene' ] } } ] } This will turn on WebGazer at the start of the trial. The params property in the extensions declaration allows you to pass in a list of CSS selector strings . The bounding rectangle of the DOM element that matches each selector will be recorded in the data for that trial. This allows for easy alignment of the gaze data and objects on the screen. webgazer_targets : { 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} } Gaze data will be added to the trial's data under the property webgazer_data . The gaze data is an array of objects. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. Note that establishing the precision and accuracy of these measurements across the variety of web browsers and systems that your experiment participants might be using is quite difficult. For example, different browsers may cause small systematic shifts in the accuracy of t values. webgazer_data : [ { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...} ] Tips for Improving Data Quality \u00b6 These are some anecdotal observations about factors that improve data quality. The quality of the camera feed is essential. Good lighting makes a big difference. You may want to encourage participants to perform any eye tracking experiments in a well-lit room. Participants need to keep their head relatively still during and after calibration. The calibration is not robust to head movements. WebGazer's click-based calibration can be used throughout the experiment. You can turn this on by calling jsPsych.extensions.webgazer.startMouseCalibration() at any point in the experiment. If you use a continue button to advance through the experiment and move the location of the continue button around you can be making small adjustments to the calibration throughout. Computing the gaze predictions consumes more computational resources than most other things that jsPsych is typically used for. The sampling rate that WebGazer is able to achieve will depend on the computing power of the participant's device. You may want to ask the participant to close any non-essential software and browser windows prior to completing the experiment. You may also want to check that the sampling rate is sufficiently high as part of validation. If you have tips based on your own experience please consider sharing them on our discussion forum and we'll add to this list! Example \u00b6 Tip Additional example experiments using WebGazer are available in the /examples folder of the jsPsych release. See webgazer.html , webgazer_image.html , and webgazer_audio.html . Example Here's an example of putting all of the pieces above together. This example also shows how to use data from the validation to decide whether or not to recalibrate. You can try this experiment here (opens in new tab) . <!DOCTYPE html> < html > < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jsPsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" /> < style > . jspsych-btn { margin-bottom : 10 px ; } </ style > </ head > < body ></ body > < script > var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }); var preload = { type : jsPsychPreload , images : [ 'img/blue.png' ] } var camera_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>In order to participate you must allow the experiment to use your camera.</p> <p>You will be prompted to do this on the next screen.</p> <p>If you do not wish to allow use of your camera, you cannot participate in this experiment.<p> <p>It may take up to 30 seconds for the camera to initialize after you give permission.</p> ` , choices : [ 'Got it' ], } var init_camera = { type : jsPsychWebgazerInitCamera } var calibration_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now you'll calibrate the eye tracking, so that the software can use the image of your eyes to predict where you are looking.</p> <p>You'll see a series of dots appear on the screen. Look at each dot and click on it.</p> ` , choices : [ 'Got it' ], } var calibration = { type : jsPsychWebgazerCalibrate , calibration_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], repetitions_per_point : 2 , randomize_calibration_order : true } var validation_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now we'll measure the accuracy of the calibration.</p> <p>Look at each dot as it appears on the screen.</p> <p style=\"font-weight: bold;\">You do not need to click on the dots this time.</p> ` , choices : [ 'Got it' ], post_trial_gap : 1000 } var validation = { type : jsPsychWebgazerValidate , validation_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], roi_radius : 200 , time_to_saccade : 1000 , validation_duration : 2000 , data : { task : 'validate' } } var recalibrate_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>The accuracy of the calibration is a little lower than we'd like.</p> <p>Let's try calibrating one more time.</p> <p>On the next screen, look at the dots and click on them.<p> ` , choices : [ 'OK' ], } var recalibrate = { timeline : [ recalibrate_instructions , calibration , validation_instructions , validation ], conditional_function : function (){ var validation_data = jsPsych . data . get (). filter ({ task : 'validate' }). values ()[ 0 ]; return validation_data . percent_in_roi . some ( function ( x ){ var minimum_percent_acceptable = 50 ; return x < minimum_percent_acceptable ; }); }, data : { phase : 'recalibration' } } var calibration_done = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Great, we're done with calibration!</p> ` , choices : [ 'OK' ] } var begin = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>The next screen will show an image to demonstrate adding the webgazer extension to a trial.</p> <p>Just look at the image while eye tracking data is collected. The trial will end automatically.</p> <p>Press any key to start.</p> ` } var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : \"NO_KEYS\" , trial_duration : 2000 , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#jspsych-image-keyboard-response-stimulus' ]} } ] } var show_data = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trial_data = jsPsych . data . getLastTrialData (). values (); var trial_json = JSON . stringify ( trial_data , null , 2 ); return `<p style=\"margin-bottom:0px;\"><strong>Trial data:</strong></p> <pre style=\"margin-top:0px;text-align:left;\"> ${ trial_json } </pre>` ; }, choices : \"NO_KEYS\" }; jsPsych . run ([ preload , camera_instructions , init_camera , calibration_instructions , calibration , validation_instructions , validation , recalibrate , calibration_done , begin , trial , show_data ]); </ script > </ html > Below is example data from the image-keyboard-response trial taken from the experiment above. In addition to the standard data that is collected for this plugin, you can see the additional webgazer_data and webgazer_targets arrays. The webgazer_data shows 21 gaze location estimates during the 1-second image presentation. The webgazer_targets array shows that there was one target, the image-keyboard-response stimulus, and tells you the x- and y-coordinate boundaries for the target (image) rectangle. By comparing each of the x/y locations from the webgazer_data locations array with the target boundaries in webgazer_targets , you can determine if/when the estimated gaze location was inside the target area. { \"rt\" : null , \"stimulus\" : \"img/blue.png\" , \"response\" : null , \"trial_type\" : \"image-keyboard-response\" , \"trial_index\" : 4 , \"time_elapsed\" : 30701 , \"internal_node_id\" : \"0.0-4.0\" , \"webgazer_data\" : [ { \"x\" : 1065 , \"y\" : 437 , \"t\" : 39 }, { \"x\" : 943 , \"y\" : 377 , \"t\" : 79 }, { \"x\" : 835 , \"y\" : 332 , \"t\" : 110 }, { \"x\" : 731 , \"y\" : 299 , \"t\" : 146 }, { \"x\" : 660 , \"y\" : 271 , \"t\" : 189 }, { \"x\" : 606 , \"y\" : 251 , \"t\" : 238 }, { \"x\" : 582 , \"y\" : 213 , \"t\" : 288 }, { \"x\" : 551 , \"y\" : 200 , \"t\" : 335 }, { \"x\" : 538 , \"y\" : 183 , \"t\" : 394 }, { \"x\" : 514 , \"y\" : 177 , \"t\" : 436 }, { \"x\" : 500 , \"y\" : 171 , \"t\" : 493 }, { \"x\" : 525 , \"y\" : 178 , \"t\" : 542 }, { \"x\" : 537 , \"y\" : 182 , \"t\" : 592 }, { \"x\" : 543 , \"y\" : 178 , \"t\" : 633 }, { \"x\" : 547 , \"y\" : 177 , \"t\" : 691 }, { \"x\" : 558 , \"y\" : 174 , \"t\" : 739 }, { \"x\" : 574 , \"y\" : 183 , \"t\" : 789 }, { \"x\" : 577 , \"y\" : 197 , \"t\" : 838 }, { \"x\" : 584 , \"y\" : 214 , \"t\" : 889 }, { \"x\" : 603 , \"y\" : 218 , \"t\" : 937 }, { \"x\" : 606 , \"y\" : 221 , \"t\" : 987 } ], \"webgazer_targets\" : [ \"#jspsych-image-keyboard-response-stimulus\" : { \"x\" : 490 , \"y\" : 135 , \"height\" : 300 , \"width\" : 300 , \"top\" : 135 , \"bottom\" : 435 , \"left\" : 490 , \"right\" : 790 } ] }","title":"Eye Tracking"},{"location":"overview/eye-tracking/#eye-tracking","text":"jsPsych supports eye tracking through the WebGazer library. WebGazer uses computer vision techniques to identify features of the participant's eyes via a webcam and predicts gaze location. The system is calibrated by having the participant click on or look at known locations on the screen. These locations are linked to eye features. Gaze location is predicted using regression.","title":"Eye Tracking"},{"location":"overview/eye-tracking/#getting-started","text":"","title":"Getting Started"},{"location":"overview/eye-tracking/#load-webgazerjs","text":"The official version of WebGazer is currently not supported by jsPsych. Our fork of the library contains some minor improvements aimed at the kind of experiments that jsPsych is typically used for, e.g., situations in which the timing of display screens needs to be accurate. You must include the webgazer.js file in your experiment via a <script> tag. However, the webgazer.js file is not part of any of the jsPsych NPM packages and is therefore not available via the unpkg.com CDN. Instead, it can be found on the jsdelivr.net CDN at: \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > </ head > Note A copy of our forked webgazer.js file is also included in the jsPsych release, in the /examples/js/webgazer folder. So if you prefer to download and host all of your jsPsych files (i.e. set-up option 2 in the Hello World tutorial), then another option is to load that file rather than using the jsdelivr link above. Assuming you downloaded the release and copied the webgazer.js file into a folder called js/webgazer in your root project directory, then you would load the file like this: < script src = \"js/webgazer/webgazer.js\" ></ script >","title":"Load webgazer.js"},{"location":"overview/eye-tracking/#load-the-jspsych-webgazer-extension","text":"The webgazer extension adds functionality to jsPsych for interacting with webgazer. Load it like you would a plugin file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > </ head > To use the WebGazer extension in an experiment, include it in the list of extensions passed to initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] })","title":"Load the jsPsych webgazer extension"},{"location":"overview/eye-tracking/#initialize-the-camera","text":"To help the participant position their face correctly for eye tracking you can use the webgazer-init-camera plugin . This will show the participant what the camera sees, including facial feature landmarks, and prevent the participant from continuing until their face is in good position for eye tracking. This plugin will also trigger the experiment to request permission to access the user's webcam if it hasn't already been granted. var init_camera_trial = { type : jsPsychWebgazerInitCamera }","title":"Initialize the camera"},{"location":"overview/eye-tracking/#calibration","text":"To calibrate WebGazer, you can use the webgazer-calibrate plugin . This plugin allows you to specify a set of points on the screen for calibration and to choose the method for calibrating -- either clicking on each point or simply fixating on each point. The location of calibration points is specified in percentages, e.g., [25,50] will result in a point that is 25% of the width of the screen from the left edge and 50% of the height of the screen from the top edge. Options for controlling other details of the calibration are explained in the documentation for the plugin . Note that instructions are not included in the calibration plugin, so you'll likely want to use a different plugin (e.g., html-button-response ) to display instructions prior to running the calibration. var calibration_trial = { type : jsPsychWebgazerCalibrate , calibration_points : [[ 25 , 50 ], [ 50 , 50 ], [ 75 , 50 ], [ 50 , 25 ], [ 50 , 75 ]], calibration_mode : 'click' }","title":"Calibration"},{"location":"overview/eye-tracking/#validation","text":"To measure the accuracy and precision of the calibration, you can use the webgazer-vaidate plugin . Like the calibration plugin, you can specify a list of points to perform validation on. Here you can specify the points as either percentages or in terms of the distance from the center of the screen in pixels. Which mode you use will probably depend on how you are defining your stimuli throughout the experiment. You can also specify the radius of tolerance around each point, and the plugin will calculate the percentage of measured gaze samples within that radius. This is a potentially useful heuristic for deciding whether or not to calibrate again. Options for controlling other details of the validation are explained in the documentation for the plugin . var validation_trial = { type : jsPsychWebgazerValidate , validation_points : [[ - 200 , 200 ], [ 200 , 200 ],[ - 200 , - 200 ],[ 200 , - 200 ]], validation_point_coordinates : 'center-offset-pixels' , roi_radius : 100 } The validation procedure stores the raw gaze data for each validation point, the computed average offset from each validation point, the percentage of samples within the roi_radius for each validation point, and the number of samples collected per second. { raw_gaze : [...], percent_in_roi : [...], average_offset : [...], samples_per_sec : ... } We recommend performing calibration and validation periodically throughout your experiment.","title":"Validation"},{"location":"overview/eye-tracking/#adding-eye-tracking-to-a-trial","text":"To enable eye tracking for a trial in your experiment, you can simply add the WebGazer extension to the trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img id=\"scene\" src=\"my-scene.png\"></img>' , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#scene' ] } } ] } This will turn on WebGazer at the start of the trial. The params property in the extensions declaration allows you to pass in a list of CSS selector strings . The bounding rectangle of the DOM element that matches each selector will be recorded in the data for that trial. This allows for easy alignment of the gaze data and objects on the screen. webgazer_targets : { 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} } Gaze data will be added to the trial's data under the property webgazer_data . The gaze data is an array of objects. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. Note that establishing the precision and accuracy of these measurements across the variety of web browsers and systems that your experiment participants might be using is quite difficult. For example, different browsers may cause small systematic shifts in the accuracy of t values. webgazer_data : [ { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...} ]","title":"Adding eye tracking to a trial"},{"location":"overview/eye-tracking/#tips-for-improving-data-quality","text":"These are some anecdotal observations about factors that improve data quality. The quality of the camera feed is essential. Good lighting makes a big difference. You may want to encourage participants to perform any eye tracking experiments in a well-lit room. Participants need to keep their head relatively still during and after calibration. The calibration is not robust to head movements. WebGazer's click-based calibration can be used throughout the experiment. You can turn this on by calling jsPsych.extensions.webgazer.startMouseCalibration() at any point in the experiment. If you use a continue button to advance through the experiment and move the location of the continue button around you can be making small adjustments to the calibration throughout. Computing the gaze predictions consumes more computational resources than most other things that jsPsych is typically used for. The sampling rate that WebGazer is able to achieve will depend on the computing power of the participant's device. You may want to ask the participant to close any non-essential software and browser windows prior to completing the experiment. You may also want to check that the sampling rate is sufficiently high as part of validation. If you have tips based on your own experience please consider sharing them on our discussion forum and we'll add to this list!","title":"Tips for Improving Data Quality"},{"location":"overview/eye-tracking/#example","text":"Tip Additional example experiments using WebGazer are available in the /examples folder of the jsPsych release. See webgazer.html , webgazer_image.html , and webgazer_audio.html . Example Here's an example of putting all of the pieces above together. This example also shows how to use data from the validation to decide whether or not to recalibrate. You can try this experiment here (opens in new tab) . <!DOCTYPE html> < html > < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jsPsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" /> < style > . jspsych-btn { margin-bottom : 10 px ; } </ style > </ head > < body ></ body > < script > var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }); var preload = { type : jsPsychPreload , images : [ 'img/blue.png' ] } var camera_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>In order to participate you must allow the experiment to use your camera.</p> <p>You will be prompted to do this on the next screen.</p> <p>If you do not wish to allow use of your camera, you cannot participate in this experiment.<p> <p>It may take up to 30 seconds for the camera to initialize after you give permission.</p> ` , choices : [ 'Got it' ], } var init_camera = { type : jsPsychWebgazerInitCamera } var calibration_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now you'll calibrate the eye tracking, so that the software can use the image of your eyes to predict where you are looking.</p> <p>You'll see a series of dots appear on the screen. Look at each dot and click on it.</p> ` , choices : [ 'Got it' ], } var calibration = { type : jsPsychWebgazerCalibrate , calibration_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], repetitions_per_point : 2 , randomize_calibration_order : true } var validation_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now we'll measure the accuracy of the calibration.</p> <p>Look at each dot as it appears on the screen.</p> <p style=\"font-weight: bold;\">You do not need to click on the dots this time.</p> ` , choices : [ 'Got it' ], post_trial_gap : 1000 } var validation = { type : jsPsychWebgazerValidate , validation_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], roi_radius : 200 , time_to_saccade : 1000 , validation_duration : 2000 , data : { task : 'validate' } } var recalibrate_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>The accuracy of the calibration is a little lower than we'd like.</p> <p>Let's try calibrating one more time.</p> <p>On the next screen, look at the dots and click on them.<p> ` , choices : [ 'OK' ], } var recalibrate = { timeline : [ recalibrate_instructions , calibration , validation_instructions , validation ], conditional_function : function (){ var validation_data = jsPsych . data . get (). filter ({ task : 'validate' }). values ()[ 0 ]; return validation_data . percent_in_roi . some ( function ( x ){ var minimum_percent_acceptable = 50 ; return x < minimum_percent_acceptable ; }); }, data : { phase : 'recalibration' } } var calibration_done = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Great, we're done with calibration!</p> ` , choices : [ 'OK' ] } var begin = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>The next screen will show an image to demonstrate adding the webgazer extension to a trial.</p> <p>Just look at the image while eye tracking data is collected. The trial will end automatically.</p> <p>Press any key to start.</p> ` } var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : \"NO_KEYS\" , trial_duration : 2000 , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#jspsych-image-keyboard-response-stimulus' ]} } ] } var show_data = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trial_data = jsPsych . data . getLastTrialData (). values (); var trial_json = JSON . stringify ( trial_data , null , 2 ); return `<p style=\"margin-bottom:0px;\"><strong>Trial data:</strong></p> <pre style=\"margin-top:0px;text-align:left;\"> ${ trial_json } </pre>` ; }, choices : \"NO_KEYS\" }; jsPsych . run ([ preload , camera_instructions , init_camera , calibration_instructions , calibration , validation_instructions , validation , recalibrate , calibration_done , begin , trial , show_data ]); </ script > </ html > Below is example data from the image-keyboard-response trial taken from the experiment above. In addition to the standard data that is collected for this plugin, you can see the additional webgazer_data and webgazer_targets arrays. The webgazer_data shows 21 gaze location estimates during the 1-second image presentation. The webgazer_targets array shows that there was one target, the image-keyboard-response stimulus, and tells you the x- and y-coordinate boundaries for the target (image) rectangle. By comparing each of the x/y locations from the webgazer_data locations array with the target boundaries in webgazer_targets , you can determine if/when the estimated gaze location was inside the target area. { \"rt\" : null , \"stimulus\" : \"img/blue.png\" , \"response\" : null , \"trial_type\" : \"image-keyboard-response\" , \"trial_index\" : 4 , \"time_elapsed\" : 30701 , \"internal_node_id\" : \"0.0-4.0\" , \"webgazer_data\" : [ { \"x\" : 1065 , \"y\" : 437 , \"t\" : 39 }, { \"x\" : 943 , \"y\" : 377 , \"t\" : 79 }, { \"x\" : 835 , \"y\" : 332 , \"t\" : 110 }, { \"x\" : 731 , \"y\" : 299 , \"t\" : 146 }, { \"x\" : 660 , \"y\" : 271 , \"t\" : 189 }, { \"x\" : 606 , \"y\" : 251 , \"t\" : 238 }, { \"x\" : 582 , \"y\" : 213 , \"t\" : 288 }, { \"x\" : 551 , \"y\" : 200 , \"t\" : 335 }, { \"x\" : 538 , \"y\" : 183 , \"t\" : 394 }, { \"x\" : 514 , \"y\" : 177 , \"t\" : 436 }, { \"x\" : 500 , \"y\" : 171 , \"t\" : 493 }, { \"x\" : 525 , \"y\" : 178 , \"t\" : 542 }, { \"x\" : 537 , \"y\" : 182 , \"t\" : 592 }, { \"x\" : 543 , \"y\" : 178 , \"t\" : 633 }, { \"x\" : 547 , \"y\" : 177 , \"t\" : 691 }, { \"x\" : 558 , \"y\" : 174 , \"t\" : 739 }, { \"x\" : 574 , \"y\" : 183 , \"t\" : 789 }, { \"x\" : 577 , \"y\" : 197 , \"t\" : 838 }, { \"x\" : 584 , \"y\" : 214 , \"t\" : 889 }, { \"x\" : 603 , \"y\" : 218 , \"t\" : 937 }, { \"x\" : 606 , \"y\" : 221 , \"t\" : 987 } ], \"webgazer_targets\" : [ \"#jspsych-image-keyboard-response-stimulus\" : { \"x\" : 490 , \"y\" : 135 , \"height\" : 300 , \"width\" : 300 , \"top\" : 135 , \"bottom\" : 435 , \"left\" : 490 , \"right\" : 790 } ] }","title":"Example"},{"location":"overview/fullscreen/","text":"Fullscreen Experiments \u00b6 You can run your experiment in fullscreen mode by using the jspsych-fullscreen plugin. var jsPsych = initJsPsych (); var timeline = []; timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : true }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be in fullscreen mode.' }); // exit fullscreen mode timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : false }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will NOT be in fullscreen mode.' }); jsPsych . run ( timeline ); For security reasons, web browsers require that users initiate an action to launch fullscreen mode. The fullscreen plugin displays a button that the user must click to change the display to fullscreen. Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"Fullscreen Experiments"},{"location":"overview/fullscreen/#fullscreen-experiments","text":"You can run your experiment in fullscreen mode by using the jspsych-fullscreen plugin. var jsPsych = initJsPsych (); var timeline = []; timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : true }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be in fullscreen mode.' }); // exit fullscreen mode timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : false }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will NOT be in fullscreen mode.' }); jsPsych . run ( timeline ); For security reasons, web browsers require that users initiate an action to launch fullscreen mode. The fullscreen plugin displays a button that the user must click to change the display to fullscreen. Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"Fullscreen Experiments"},{"location":"overview/media-preloading/","text":"Media Preloading \u00b6 If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the jsPsych preload plugin . Preloading files means that the participant's browser will download the files and store them in local memory on the participant's computer. This is important because displaying or playing a media file is much faster if it is already in memory on the participant's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a participant's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment. Warning Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The Cross-origin requests (CORS) and safe mode section on the Running Experiments page contains more information about this. Automatic Preloading \u00b6 jsPsych can automatically preload audio, video, and image files that are used as parameters for the standard set of plugins, based on the timeline that is passed to jsPsych.run . You must initiate this preloading using a preload trial. You should add this preload trial into your timeline when you want the preloading to occur, and set the auto_preload parameter to true . // the \"auto_preload: true\" setting tells the plugin to automatically find // stimuli to preload based the main experiment timeline (used in jsPsych.run) var preload = { type : jsPsychPreload , auto_preload : true } // this image file can be automatically preloaded var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // the sound file can be automatically preloaded var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // the video file can be automatically preloaded (as long as the experiment // is running on a server) var video_trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/sample_video.mp4' ] } jsPsych . run ([ preload , image_trial , sound_trial , video_trial ]); Manual preloading \u00b6 If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the media files, you are using timeline variables, or you are embedding the media files in an HTML string), then these files will not be detected when you use the auto_preload option, so you must manually specify them. The preload plugin allows you to add these files using the images , audio and video parameters. // this image file cannot be automatically preloaded because it is embedded in // an HTML string var image_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img src=\"img/file1.png\"></img>' , } // this audio file cannot be automatically preloaded because it is returned // from a function var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : function () { return 'audio/sound1.mp3' } } // these video files cannot be automatically preloaded because they are passed // into a trial using the jsPsych.timelineVariable function var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } // to manually preload media files, create an array of file paths for each // media type var images = [ 'img/file1.png' ]; var audio = [ 'audio/sound1.mp3' ]; var video = [ 'video/1.mp4' , 'video/2.mp4' ]; // these array can be passed into the preload plugin using the images, audio // and video parameters var preload = { type : jsPsychPreload , images : images , audio : audio , video : video } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]); Combining automatic and manual preloading \u00b6 It's possible to combine automatic and manual preloading. For instance, you may want to automatically preload all of the media files based on your experiment timeline, while also manually preloading any files that can't be automatically preloaded. Any duplicate file names across all preloading methods will be removed before preloading starts, so including the same file names in multiple preload parameters will not affect the preloading duration. // this file can be preloaded automatically var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // this file can be preloaded automatically var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // these files must be preloaded manually var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } var video = [ 'video/1.mp4' , 'video/2.mp4' ]; var preload = { type : jsPsychPreload , auto_preload : true , // automatically preload the image and audio files video : video // manually preload the videos used with timeline variables } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]); Preloading in batches \u00b6 Some experiments use many and/or large media files. This can cause problems when participants have slow and/or unreliable internet connections, because it increases the chances of loading errors during preloading. This can also cause problems with file caching, i.e. ensuring that the preloaded files remain in the browser's memory, because loading all stimuli at once may exceed the browser's cache limits. One option for mitigating these problems is to load the media files in smaller batches throughout the experiment. Files should be preloaded as close as possible to when they will be needed. For instance, if you have several blocks of trials, then right before each block, you can preload the stimuli that are needed for that block. Here is an example with trials where the stimuli files can be preloaded automatically. In this case, the trials parameter is used to tell the preload plugin to preload the stimuli from a specific part of the timeline. // these image files in these trial blocks can be automatically preloaded var block_1 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file2.png' } ] } var block_2 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file3.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file4.png' } ] } var preload_1 = { type : jsPsychPreload , trials : block_1 // automatically preload just the images from block_1 trials } var preload_2 = { type : jsPsychPreload , trials : block_2 // automatically preload just the images from block_2 trials } jsPsych . run ( // add each preload trial onto the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Below is an example with trials where the stimuli files cannot be preloaded automatically, because the stimuli files are passed to the trials via jsPsych.timelineVariable . In this case, we create separate arrays for each batch of files, and then pass those arrays to the each preload trial. // these trial blocks cannot be automatically preloaded because // the media files are passed to the trial parameters with timeline variables var block_1 = { timeline : [...], timeline_variables : [ { stim : 'file1.png' }, { stim : 'file1.png' } ] } var block_2 = { timeline : [...], timeline_variables : [ { stim : 'file3.png' }, { stim : 'file4.png' } ] } var images_block_1 = [ 'file1.png' , 'file2.png' ]; var images_block_2 = [ 'file3.png' , 'file4.png' ]; // preload trial for preloading the block 1 stimuli var preload_1 = { type : jsPsychPreload , images : images_block_1 } // preload trial for preloading the block 2 stimuli var preload_2 = { type : jsPsychPreload , images : images_block_2 } jsPsych . run ( // add each preload trial to the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Preloading progress bar \u00b6 By default, the preload plugin will display a progress bar while files are being preloaded. This progress bar represents all files that are being preloaded during the trial, regardless of whether the file is being preloaded automatically via the auto_preload or trials parameters, or manually via the audio , images , and video parameters. You may wish to turn the preload progress bar off if you are only loading a small number of files, as it will appear and disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the show_progress_bar parameter in the preload trial. var preload_trial = { type : jsPsychPreload , auto_preload : true show_progress_bar : false // hide progress bar } Loading time limits \u00b6 It's usually a good idea to set a time limit for file loading, to ensure that participants aren't waiting for an unreasonable amount of time. Time limits can be specified in milliseconds using the max_load_time parameter. If you set a loading time limit and all files haven't finished loading before this time, then the preload trial will either stop an error (if continue_after_error is false, the default) or the trial will end and the experiment will continue (if continue_after_error is true ). If max_load_time is null (the default), then there is no time limit. var preload_trial = { type : jsPsychPreload , auto_preload : true max_load_time : 60000 // 1 minute } Loading and error messages \u00b6 It's possible to specify custom messages to be shown on the page while the media files are loading, and in case of one or more file loading errors. The message parameter allows you to customize the loading message using an HML-formatted string. If show_progress_bar is true , then this message will be shown above the progress bar. var preload_trial = { type : jsPsychPreload , auto_preload : true message : 'Please wait while the experiment loads. This may take a few minutes.' , } A preloading error will occur when either (a) one or more files produces a loading error, and/or (b) all files have not finished loading before the max_load_time duration. The error_message parameter allows you to customize the messsage that's shown on the page in these cases. This message will only be shown if continue_after_error is false (the default). var preload_trial = { type : jsPsychPreload , auto_preload : true , error_message : 'The experiment failed to load. Please contact the researcher.' } In addition to the error_message parameter, it's also possible to show more detailed error messages on the page about any files that failed to load. You can control this with the show_detailed_errors parameter. Detailed error messages will appear below the general error message. This only applies if continue_after_error is false (the default). Detailed error messages can be useful when testing and debugging your experiment. If show_detailed_errors is true , then if one or more loading errors occurs before the max_load_time is reached, then the error page will also contian a list of the file(s) that produced an error, along with error information (if there is any). Note that this may not be a complete list, because it will only report any errors that occurred before the max_load_time was reached. If there are no file loading errors but preloading hasn't finished before the max_load_time , then detailed error message will just tell you that loading timed out. var preload_trial = { type : jsPsychPreload , auto_preload : true , // show details of any file loading errors and/or loading time out show_detailed_errors : true } Options for handling errors \u00b6 If continue_after_error is true , then the experiment will not stop if one or more files fails to load. Instead, the trial will end and the experiment will continue. However, the preload trial data will contain a property called success , which is whether or not all files were loaded successfully, timeout , which is whether or not the files loaded successfully before the max_load_time . The preload trial data will also contain lists of any image , audio , and video files that failed to load. This gives you the option to continue the experiment after preloading fails and use the preload trial data decide what to do next. For instance, you may decide to skip the trials that use the stimuli files that failed to load, or try loading the failed files again. Another option is to simply end the experiment when preloading fails, but send the data back to your server so that you have more information about the loading failure. var preload_trial = { type : jsPsychPreload , auto_preload : true , message : 'Please wait while the experiment loads...' , // don't stop the experiment if there are file loading errors or if loading times out continue_after_error : true } var save_data = { type : jsPsychCallFunction , async : true , func : function ( done ){ var data = jsPsych . data . get (). json (); save_data ( data , function () { done ()}) } } // the experiment will stop here, since there are no valid key choices or trial duration var fail_message = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The experiment failed to load. Please contact the researcher.' , choices : \"NO_KEYS\" , trial_duration : null } var if_loading_fails = { timeline : [ save_data , fail_message ], conditional_function : function () { if ( jsPsych . data . getLastTrialData ()[ 0 ]. values (). success ) { // preloading was successful, so skip this conditional timeline // and move on with the experiment return false ; } else { // preloading failed, so run this conditional timeline: // save the data to the server and show the fail message return true ; } } } // ... rest of experiment jsPsych . run ([ preload_trial , if_loading_fails , ... ]) The preload plugin's on_success and on_error callback functions provide another way of tracking preloading progress and handling file loading errors. These functions are called after any file either loads successfully or produces an error, respectively. These functions receive a single argument, which is the path of the file (string) that loaded or produced an error. var file_load_count = 0 ; var file_error_count = 0 ; var preload_trial = { type : jsPsychPreload , auto_preload : true , on_error : function ( file ) { file_error_count ++ ; console . log ( 'Error: ' , file ); }, on_success : function ( file ) { file_load_count ++ ; console . log ( 'Loaded: ' , file ); } }; Note that there's no guarantee that any/all files will trigger one of these two callback functions, because they are cancelled after the preload trial ends. For instance, if a file takes longer to load then the max_load_time , then the preload trial will end due to timing out, and the on_success and on_error callbacks for any in-progress files will be cancelled.","title":"Media Preloading"},{"location":"overview/media-preloading/#media-preloading","text":"If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the jsPsych preload plugin . Preloading files means that the participant's browser will download the files and store them in local memory on the participant's computer. This is important because displaying or playing a media file is much faster if it is already in memory on the participant's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a participant's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment. Warning Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The Cross-origin requests (CORS) and safe mode section on the Running Experiments page contains more information about this.","title":"Media Preloading"},{"location":"overview/media-preloading/#automatic-preloading","text":"jsPsych can automatically preload audio, video, and image files that are used as parameters for the standard set of plugins, based on the timeline that is passed to jsPsych.run . You must initiate this preloading using a preload trial. You should add this preload trial into your timeline when you want the preloading to occur, and set the auto_preload parameter to true . // the \"auto_preload: true\" setting tells the plugin to automatically find // stimuli to preload based the main experiment timeline (used in jsPsych.run) var preload = { type : jsPsychPreload , auto_preload : true } // this image file can be automatically preloaded var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // the sound file can be automatically preloaded var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // the video file can be automatically preloaded (as long as the experiment // is running on a server) var video_trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/sample_video.mp4' ] } jsPsych . run ([ preload , image_trial , sound_trial , video_trial ]);","title":"Automatic Preloading"},{"location":"overview/media-preloading/#manual-preloading","text":"If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the media files, you are using timeline variables, or you are embedding the media files in an HTML string), then these files will not be detected when you use the auto_preload option, so you must manually specify them. The preload plugin allows you to add these files using the images , audio and video parameters. // this image file cannot be automatically preloaded because it is embedded in // an HTML string var image_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img src=\"img/file1.png\"></img>' , } // this audio file cannot be automatically preloaded because it is returned // from a function var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : function () { return 'audio/sound1.mp3' } } // these video files cannot be automatically preloaded because they are passed // into a trial using the jsPsych.timelineVariable function var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } // to manually preload media files, create an array of file paths for each // media type var images = [ 'img/file1.png' ]; var audio = [ 'audio/sound1.mp3' ]; var video = [ 'video/1.mp4' , 'video/2.mp4' ]; // these array can be passed into the preload plugin using the images, audio // and video parameters var preload = { type : jsPsychPreload , images : images , audio : audio , video : video } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]);","title":"Manual preloading"},{"location":"overview/media-preloading/#combining-automatic-and-manual-preloading","text":"It's possible to combine automatic and manual preloading. For instance, you may want to automatically preload all of the media files based on your experiment timeline, while also manually preloading any files that can't be automatically preloaded. Any duplicate file names across all preloading methods will be removed before preloading starts, so including the same file names in multiple preload parameters will not affect the preloading duration. // this file can be preloaded automatically var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // this file can be preloaded automatically var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // these files must be preloaded manually var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } var video = [ 'video/1.mp4' , 'video/2.mp4' ]; var preload = { type : jsPsychPreload , auto_preload : true , // automatically preload the image and audio files video : video // manually preload the videos used with timeline variables } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]);","title":"Combining automatic and manual preloading"},{"location":"overview/media-preloading/#preloading-in-batches","text":"Some experiments use many and/or large media files. This can cause problems when participants have slow and/or unreliable internet connections, because it increases the chances of loading errors during preloading. This can also cause problems with file caching, i.e. ensuring that the preloaded files remain in the browser's memory, because loading all stimuli at once may exceed the browser's cache limits. One option for mitigating these problems is to load the media files in smaller batches throughout the experiment. Files should be preloaded as close as possible to when they will be needed. For instance, if you have several blocks of trials, then right before each block, you can preload the stimuli that are needed for that block. Here is an example with trials where the stimuli files can be preloaded automatically. In this case, the trials parameter is used to tell the preload plugin to preload the stimuli from a specific part of the timeline. // these image files in these trial blocks can be automatically preloaded var block_1 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file2.png' } ] } var block_2 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file3.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file4.png' } ] } var preload_1 = { type : jsPsychPreload , trials : block_1 // automatically preload just the images from block_1 trials } var preload_2 = { type : jsPsychPreload , trials : block_2 // automatically preload just the images from block_2 trials } jsPsych . run ( // add each preload trial onto the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Below is an example with trials where the stimuli files cannot be preloaded automatically, because the stimuli files are passed to the trials via jsPsych.timelineVariable . In this case, we create separate arrays for each batch of files, and then pass those arrays to the each preload trial. // these trial blocks cannot be automatically preloaded because // the media files are passed to the trial parameters with timeline variables var block_1 = { timeline : [...], timeline_variables : [ { stim : 'file1.png' }, { stim : 'file1.png' } ] } var block_2 = { timeline : [...], timeline_variables : [ { stim : 'file3.png' }, { stim : 'file4.png' } ] } var images_block_1 = [ 'file1.png' , 'file2.png' ]; var images_block_2 = [ 'file3.png' , 'file4.png' ]; // preload trial for preloading the block 1 stimuli var preload_1 = { type : jsPsychPreload , images : images_block_1 } // preload trial for preloading the block 2 stimuli var preload_2 = { type : jsPsychPreload , images : images_block_2 } jsPsych . run ( // add each preload trial to the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] );","title":"Preloading in batches"},{"location":"overview/media-preloading/#preloading-progress-bar","text":"By default, the preload plugin will display a progress bar while files are being preloaded. This progress bar represents all files that are being preloaded during the trial, regardless of whether the file is being preloaded automatically via the auto_preload or trials parameters, or manually via the audio , images , and video parameters. You may wish to turn the preload progress bar off if you are only loading a small number of files, as it will appear and disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the show_progress_bar parameter in the preload trial. var preload_trial = { type : jsPsychPreload , auto_preload : true show_progress_bar : false // hide progress bar }","title":"Preloading progress bar"},{"location":"overview/media-preloading/#loading-time-limits","text":"It's usually a good idea to set a time limit for file loading, to ensure that participants aren't waiting for an unreasonable amount of time. Time limits can be specified in milliseconds using the max_load_time parameter. If you set a loading time limit and all files haven't finished loading before this time, then the preload trial will either stop an error (if continue_after_error is false, the default) or the trial will end and the experiment will continue (if continue_after_error is true ). If max_load_time is null (the default), then there is no time limit. var preload_trial = { type : jsPsychPreload , auto_preload : true max_load_time : 60000 // 1 minute }","title":"Loading time limits"},{"location":"overview/media-preloading/#loading-and-error-messages","text":"It's possible to specify custom messages to be shown on the page while the media files are loading, and in case of one or more file loading errors. The message parameter allows you to customize the loading message using an HML-formatted string. If show_progress_bar is true , then this message will be shown above the progress bar. var preload_trial = { type : jsPsychPreload , auto_preload : true message : 'Please wait while the experiment loads. This may take a few minutes.' , } A preloading error will occur when either (a) one or more files produces a loading error, and/or (b) all files have not finished loading before the max_load_time duration. The error_message parameter allows you to customize the messsage that's shown on the page in these cases. This message will only be shown if continue_after_error is false (the default). var preload_trial = { type : jsPsychPreload , auto_preload : true , error_message : 'The experiment failed to load. Please contact the researcher.' } In addition to the error_message parameter, it's also possible to show more detailed error messages on the page about any files that failed to load. You can control this with the show_detailed_errors parameter. Detailed error messages will appear below the general error message. This only applies if continue_after_error is false (the default). Detailed error messages can be useful when testing and debugging your experiment. If show_detailed_errors is true , then if one or more loading errors occurs before the max_load_time is reached, then the error page will also contian a list of the file(s) that produced an error, along with error information (if there is any). Note that this may not be a complete list, because it will only report any errors that occurred before the max_load_time was reached. If there are no file loading errors but preloading hasn't finished before the max_load_time , then detailed error message will just tell you that loading timed out. var preload_trial = { type : jsPsychPreload , auto_preload : true , // show details of any file loading errors and/or loading time out show_detailed_errors : true }","title":"Loading and error messages"},{"location":"overview/media-preloading/#options-for-handling-errors","text":"If continue_after_error is true , then the experiment will not stop if one or more files fails to load. Instead, the trial will end and the experiment will continue. However, the preload trial data will contain a property called success , which is whether or not all files were loaded successfully, timeout , which is whether or not the files loaded successfully before the max_load_time . The preload trial data will also contain lists of any image , audio , and video files that failed to load. This gives you the option to continue the experiment after preloading fails and use the preload trial data decide what to do next. For instance, you may decide to skip the trials that use the stimuli files that failed to load, or try loading the failed files again. Another option is to simply end the experiment when preloading fails, but send the data back to your server so that you have more information about the loading failure. var preload_trial = { type : jsPsychPreload , auto_preload : true , message : 'Please wait while the experiment loads...' , // don't stop the experiment if there are file loading errors or if loading times out continue_after_error : true } var save_data = { type : jsPsychCallFunction , async : true , func : function ( done ){ var data = jsPsych . data . get (). json (); save_data ( data , function () { done ()}) } } // the experiment will stop here, since there are no valid key choices or trial duration var fail_message = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The experiment failed to load. Please contact the researcher.' , choices : \"NO_KEYS\" , trial_duration : null } var if_loading_fails = { timeline : [ save_data , fail_message ], conditional_function : function () { if ( jsPsych . data . getLastTrialData ()[ 0 ]. values (). success ) { // preloading was successful, so skip this conditional timeline // and move on with the experiment return false ; } else { // preloading failed, so run this conditional timeline: // save the data to the server and show the fail message return true ; } } } // ... rest of experiment jsPsych . run ([ preload_trial , if_loading_fails , ... ]) The preload plugin's on_success and on_error callback functions provide another way of tracking preloading progress and handling file loading errors. These functions are called after any file either loads successfully or produces an error, respectively. These functions receive a single argument, which is the path of the file (string) that loaded or produced an error. var file_load_count = 0 ; var file_error_count = 0 ; var preload_trial = { type : jsPsychPreload , auto_preload : true , on_error : function ( file ) { file_error_count ++ ; console . log ( 'Error: ' , file ); }, on_success : function ( file ) { file_load_count ++ ; console . log ( 'Loaded: ' , file ); } }; Note that there's no guarantee that any/all files will trigger one of these two callback functions, because they are cancelled after the preload trial ends. For instance, if a file takes longer to load then the max_load_time , then the preload trial will end due to timing out, and the on_success and on_error callbacks for any in-progress files will be cancelled.","title":"Options for handling errors"},{"location":"overview/mturk/","text":"Integrating with Mechanical Turk \u00b6 A common use of jsPsych is to build an online experiment and find participants using Mechanical Turk . Once an experiment is available through a web server and data is being saved on the server , connecting the experiment with Mechanical Turk takes only a few additional steps. jsPsych has some built-in functionality to assist with this process. The jsPsych.turk module \u00b6 The jsPsych.turk module contains functions that are relevant for experiments running on Mechanical Turk. Creating an advertisement page \u00b6 When potential participants view your experiment on Mechanical Turk, they will be able to see a single webpage before deciding whether or not to accept the HIT (start the experiment). This first page is often used as an advertisement for the experiment, similar to posting a flier in a department hallway. The important thing to remember about this page is that potential participants will be able to interact with it even if they haven't accepted the HIT. Therefore, it can be useful to change the content of the page depending on whether the HIT has been accepted or not. This is relatively easy to do: < div id = \"experiment_link\" > You must accept the HIT to begin the experiment </ div > . < script > // jsPsych has a method turkInfo() which can determine whether or not the // HIT has been accepted. var turkInfo = jsPsych . turkInfo (); // turkInfo.previewMode is true in two cases: when the HIT has not been // accepted yet OR when the page is viewed outside of mechanical turk. // The second property, outsideTurk, is true when the page is viewed // outside of mechanical turk, so together, the statement will be true // only when in Turk and when the HIT is not accepted yet. if ( ! turkInfo . previewMode && ! turkInfo . outsideTurk ) { document . querySelector ( '#experiment_link' ). innerHMTL = '<a href=\"link_to_experiment.html\" target=\"_blank\">Click Here to Start Experiment</a>' ; } </ script > One important issue with advertisement pages is that they must be served using the https protocol, which requires having an SSL certificate on the web server hosting the page. Instructions for how to do this vary depending on what kind of server you are using, so the best advice is to simply Google for instructions on how to acquire and install an SSL certificate on your particular server. Getting the worker ID \u00b6 Every account on Mechanical Turk is given a unique identification string. Recording this ID is a useful way to keep track of who is doing your experiment. In particular, while Turk has built in tools for preventing the same person from doing a HIT more than once, there may be cases where you don't want participants to complete related experiments. If you store the worker ID of every person who starts an experiment in a database, then you can exclude people by running a query on the database to check for the ID. jsPsych can get the workerID, assignmentID, and hitID with the turkInfo method. var turkInfo = jsPsych . turk . turkInfo (); // workerID turkInfo . workerId // hitID turkInfo . hitId // assignmentID turkInfo . assignmentId Recording the workerId at the start of the experiment is also a good way to track dropouts. Submitting results to Mechanical Turk \u00b6 If you are running a HIT on Mechanical Turk using the ExternalQuestion template, then you'll need to provide a way for participants to indicate that they have completed the HIT. (If you are using another template, then the template will provide this code for you). jsPSych makes this a relatively easy task. A common strategy for external HITs is to display an HTML page on the Mechanical Turk website that links to your HIT. Participants click the link, which opens the actual experiment content in a new browser window or tab, allowing the experiment to take up the whole browser window instead of just the iframe that displays content on Mechanical Turk. On this page, you might include a submit button for workers to indicate that they have finished the experiment. The page would look something like this: < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > When workers click the button, the contents of the code text field will be sent to Mechanical Turk, and you'll be able to view the participants and the codes that they entered in the Mechanical Turk GUI. You can then approve or reject work using the Mechanical Turk website. Limitations \u00b6 jsPsych is not designed to communicate with the Mechanical Turk API in a comprehensive manner. If you are looking for software to help you post and manage HITs, then you may want to look at PsiTurk . jsPsych and PsiTurk complement each other nicely, and there is an example of combining the two platforms on PsiTurk's experiment exchange.","title":"Integrating with Mechanical Turk"},{"location":"overview/mturk/#integrating-with-mechanical-turk","text":"A common use of jsPsych is to build an online experiment and find participants using Mechanical Turk . Once an experiment is available through a web server and data is being saved on the server , connecting the experiment with Mechanical Turk takes only a few additional steps. jsPsych has some built-in functionality to assist with this process.","title":"Integrating with Mechanical Turk"},{"location":"overview/mturk/#the-jspsychturk-module","text":"The jsPsych.turk module contains functions that are relevant for experiments running on Mechanical Turk.","title":"The jsPsych.turk module"},{"location":"overview/mturk/#creating-an-advertisement-page","text":"When potential participants view your experiment on Mechanical Turk, they will be able to see a single webpage before deciding whether or not to accept the HIT (start the experiment). This first page is often used as an advertisement for the experiment, similar to posting a flier in a department hallway. The important thing to remember about this page is that potential participants will be able to interact with it even if they haven't accepted the HIT. Therefore, it can be useful to change the content of the page depending on whether the HIT has been accepted or not. This is relatively easy to do: < div id = \"experiment_link\" > You must accept the HIT to begin the experiment </ div > . < script > // jsPsych has a method turkInfo() which can determine whether or not the // HIT has been accepted. var turkInfo = jsPsych . turkInfo (); // turkInfo.previewMode is true in two cases: when the HIT has not been // accepted yet OR when the page is viewed outside of mechanical turk. // The second property, outsideTurk, is true when the page is viewed // outside of mechanical turk, so together, the statement will be true // only when in Turk and when the HIT is not accepted yet. if ( ! turkInfo . previewMode && ! turkInfo . outsideTurk ) { document . querySelector ( '#experiment_link' ). innerHMTL = '<a href=\"link_to_experiment.html\" target=\"_blank\">Click Here to Start Experiment</a>' ; } </ script > One important issue with advertisement pages is that they must be served using the https protocol, which requires having an SSL certificate on the web server hosting the page. Instructions for how to do this vary depending on what kind of server you are using, so the best advice is to simply Google for instructions on how to acquire and install an SSL certificate on your particular server.","title":"Creating an advertisement page"},{"location":"overview/mturk/#getting-the-worker-id","text":"Every account on Mechanical Turk is given a unique identification string. Recording this ID is a useful way to keep track of who is doing your experiment. In particular, while Turk has built in tools for preventing the same person from doing a HIT more than once, there may be cases where you don't want participants to complete related experiments. If you store the worker ID of every person who starts an experiment in a database, then you can exclude people by running a query on the database to check for the ID. jsPsych can get the workerID, assignmentID, and hitID with the turkInfo method. var turkInfo = jsPsych . turk . turkInfo (); // workerID turkInfo . workerId // hitID turkInfo . hitId // assignmentID turkInfo . assignmentId Recording the workerId at the start of the experiment is also a good way to track dropouts.","title":"Getting the worker ID"},{"location":"overview/mturk/#submitting-results-to-mechanical-turk","text":"If you are running a HIT on Mechanical Turk using the ExternalQuestion template, then you'll need to provide a way for participants to indicate that they have completed the HIT. (If you are using another template, then the template will provide this code for you). jsPSych makes this a relatively easy task. A common strategy for external HITs is to display an HTML page on the Mechanical Turk website that links to your HIT. Participants click the link, which opens the actual experiment content in a new browser window or tab, allowing the experiment to take up the whole browser window instead of just the iframe that displays content on Mechanical Turk. On this page, you might include a submit button for workers to indicate that they have finished the experiment. The page would look something like this: < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > When workers click the button, the contents of the code text field will be sent to Mechanical Turk, and you'll be able to view the participants and the codes that they entered in the Mechanical Turk GUI. You can then approve or reject work using the Mechanical Turk website.","title":"Submitting results to Mechanical Turk"},{"location":"overview/mturk/#limitations","text":"jsPsych is not designed to communicate with the Mechanical Turk API in a comprehensive manner. If you are looking for software to help you post and manage HITs, then you may want to look at PsiTurk . jsPsych and PsiTurk complement each other nicely, and there is an example of combining the two platforms on PsiTurk's experiment exchange.","title":"Limitations"},{"location":"overview/plugins/","text":"Plugins \u00b6 In jsPsych, plugins define the kinds of trials or events that should occur during the experiment. Some plugins define very general events, like displaying a set of instructions pages , displaying an image and recording a keyboard response , or playing a sound file and recording a button response . Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a circular visual search array ), or run a specific version of particular kind of task (e.g., the Implicit Association Test ). Part of creating an experiment with jsPsych involves figuring out which plugins are needed to create the tasks you want your participants to perform. Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the image-keyboard-response plugin defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only need to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects. Using a plugin \u00b6 To use a plugin, you'll need to load the plugin's JavaScript file in your experiment's HTML page. All jsPsych experiments also need to load the \"jsPsych.js\" file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" type = \"text/javascript\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" type = \"text/javascript\" ></ script > </ head > Once a plugin is loaded, you can use JavaScript to define a trial that uses that plugin. All jsPsych trials need a type parameter, which tells jsPsych what plugin to use to run the trial. The trial's type is similar to the plugin name, but it always starts with \"jsPsych\" and is written in camel case rather than with dashes between the words. The trial's type parameter should NOT be a string (i.e., no quotes around the type value). Here are some examples of plugin names and types: Plugin name Type image-keyboard-response jsPsychImageKeyboardResponse fullscreen jsPsychFullscreen webgazer-init-camera jsPsychWebgazerInitCamera The following JavaScript code defines a trial using the image-keyboard-response plugin to display an image file. This trial uses the default values for valid keys, stimulus duration, trial duration, and other parameters. var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' } You can override any default parameter values by adding them into your trial object. Here's an example of overriding the default values for trial_duration and post_trial_gap : var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' , trial_duration : 3000 , post_trial_gap : 2000 } Parameters available in all plugins \u00b6 Each plugin specifies its own set of parameters. Check the documentation for a plugin to see what parameters are available and what they do. There is also a set of parameters that can be specified for any plugin: Parameter Type Default Value Description data object undefined An object containing additional data to store for the trial. See the Data page for more details. post_trial_gap numeric null Sets the time, in milliseconds, between the current trial and the next trial. If null, there will be no gap. on_start function function(){ return; } A callback function to execute when the trial begins, before any loading has occurred. See the Event-Related Callbacks page for more details. on_finish function function(){ return; } A callback function to execute when the trial finishes, and before the next trial begins. See the Event-Related Callbacks page for more details. on_load function function(){ return; } A callback function to execute when the trial has loaded, which typically happens after the initial display of the plugin has loaded. See the Event-Related Callbacks page for more details. css_classes string null A list of CSS classes to add to the jsPsych display element for the duration of this trial. This allows you to create custom formatting rules (CSS classes) that are only applied to specific trials. For more information and examples, see the Controlling Visual Appearance page and the \"css-classes-parameter.html\" file in the jsPsych examples folder. save_trial_parameters object {} An object containing any trial parameters that should or should not be saved to the trial data. Each key is the name of a trial parameter, and its value should be true or false , depending on whether or not its value should be saved to the data. If the parameter is a function that returns the parameter value, then the value that is returned will be saved to the data. If the parameter is always expected to be a function (e.g., an event-related callback function), then the function itself will be saved as a string. For more examples, see the \"save-trial-parameters.html\" file in the jsPsych examples folder. The data parameter \u00b6 The data parameter allows you to add additional properties to the trial data. This can be useful for storing properties of the trial that are not directly apparent from the values that the plugin records. The data parameter value must be an object that contains key-value pairs. A simple example is the Flanker Task . In this experiment, participants respond to the direction of a central arrow by pressing a key to the left for a left-pointing arrow (<) and a key to the right for a right-pointing arrow (>). The arrow appears in the center of flankers , or arrows that the participant should ignore. Those flankers can be congruent (>>>>>) or incongruent (<<><<). A trial for the Flanker Task written with jsPsych might look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' } } Note the use of the data parameter to add a property stimulus_type with the value congruent and a property target_direction with the value left . Having these properties recorded directly in the data simplifies data analysis, making it easy to aggregate data by stimulus_type and/or target_direction . The post_trial_gap (ITI) parameter \u00b6 The default inter-trial interval (ITI) in jsPsych is 0 ms. This can be adjusted at the experiment-wide level by changing the default_iti parameter in initJsPsych() . The ITI can also be controlled at the trial level through the post_trial_gap parameter. Setting this parameter to a positive integer x will cause a blank screen to display after the trial for x milliseconds. Setting this parameter for a trial will override the default_iti value set in initJsPsych . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'There will be a 1.5 second blank screen after this trial.' , post_trial_gap : 1500 } The on_start parameter \u00b6 Immediately before a trial runs, there is an opportunity to run an arbitrary function through the on_start event handler. This event handler is passed a single argument containing an editable copy of the trial parameters. This function can therefore be used to alter the trial based on the state of the experiment, among other uses. // when this trial runs, the on_start function will change the trial's stimulus and data parameters, // so the trial will display an incongruent Flanker stimulus with a right-facing central arrow var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_start : function ( trial ){ trial . stimulus = '<<><<' ; trial . data . stimulus_type = 'incongruent' ; trial . data . target_direction = 'right' ; } } The on_finish parameter \u00b6 After a trial is completed, there is an opportunity to run an arbitrary function through the on_finish event handler. This function is passed a single argument containing an editable copy of the data recorded for that trial. This function can therefore be used to update the state of the experiment based on the data collected, or modify the data collected. The on_finish function can be useful to calculate new data properties that were unknowable at the start of the trial. For example, with the Flanker Task example above, the on_finish function could check the response and use to this information to add a new property to the data called correct , which is either true or false . // in addition to all of the standard data collected for this trial, // this on_finish function adds a property called 'correct' // which is either 'true' or 'false' // depending on the response that was made var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' , correct_response : 'f' }, on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response )){ data . correct = true ; } else { data . correct = false ; } } } The on_load parameter \u00b6 The on_load callback function will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. This can be useful for changing various aspects of the page elements and their properties that would otherwise require modifying the plugin file. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { // this will change the src attribute of the image after 500ms setTimeout ( function (){ document . querySelector ( 'img' ). src = 'imgB.png' }, 500 ); } }; The css_classes parameter \u00b6 The css_classes parameter allows you to add an array of CSS class names to the jsPsych display element on that specific trial. This allows you to create custom style and formatting rules that are only applied to specific trials. If you want CSS rules that only apply to specific elements during a trial, you can use additional CSS selectors. < style > . flanker-stimulus { font-size : 500 % ; } . flanker-stimulus # prompt { font-size : 18 px ; } . fixation { font-size : 80 px ; } </ style > < script > var fixation_trial = { type : jsPsychHtmlKeyboardResponse , choices : \"NO_KEYS\" , stimulus : '+' , css_classes : [ 'fixation' ] }; var flanker_trial = { type : jsPsychHtmlKeyboardResponse , choices : [ \"ArrowLeft\" , \"ArrowRight\" ], stimulus : '>>>>>' , prompt : '<span id=\"prompt\">Press the left or right arrow key.</span>' , css_classes : [ 'flanker-stimulus' ] }; </ script > The save_trial_parameters parameter \u00b6 The save_trial_parameters parameter allows you to tell jsPsych what parameters you want to be saved to the data. This can be used to override the parameter values that the plugin saves by default. You can add more parameter values to the data that are not normally saved, or remove parameter values that normally are saved. This can be especially useful when the parameter value is dynamic (i.e. a function) and you want to record the value that was used during the trial. var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"color: orange; font-size: 48px; font-weight: bold;\">BLUE</p>' , choices : function () { return jsPsych . randomization . shuffle ([ 'Yes' , 'No' ]); }, post_trial_gap : function () { return jsPsych . randomization . sampleWithoutReplacement ([ 200 , 300 , 400 , 500 ], 1 )[ 0 ]; }, save_trial_parameters : { // save the randomly-selected button order and post trial gap duration to the trial data choices : true , post_trial_gap : true , // don't save the stimulus stimulus : false } } Note You cannot remove the internal_node_id and trial_index values from the trial data, because these are used internally by jsPsych. Data collected by all plugins \u00b6 Each plugin defines what data is collected on the trial. The documentation for each plugin specifies what information will be stored in the trial data. In addition to the data collected by a plugin, there is a default set of data that is collected on every trial. Name Type Value trial_type string The name of the plugin used to run the trial. trial_index numeric The index of the current trial across the whole experiment. time_elapsed numeric The number of milliseconds between the start of the experiment and when the trial ended. internal_node_id string A string identifier for the current TimelineNode. Creating a new plugin \u00b6 See our developer's guide for plugins for information about how to create a new plugin.","title":"Plugins"},{"location":"overview/plugins/#plugins","text":"In jsPsych, plugins define the kinds of trials or events that should occur during the experiment. Some plugins define very general events, like displaying a set of instructions pages , displaying an image and recording a keyboard response , or playing a sound file and recording a button response . Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a circular visual search array ), or run a specific version of particular kind of task (e.g., the Implicit Association Test ). Part of creating an experiment with jsPsych involves figuring out which plugins are needed to create the tasks you want your participants to perform. Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the image-keyboard-response plugin defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only need to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects.","title":"Plugins"},{"location":"overview/plugins/#using-a-plugin","text":"To use a plugin, you'll need to load the plugin's JavaScript file in your experiment's HTML page. All jsPsych experiments also need to load the \"jsPsych.js\" file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" type = \"text/javascript\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" type = \"text/javascript\" ></ script > </ head > Once a plugin is loaded, you can use JavaScript to define a trial that uses that plugin. All jsPsych trials need a type parameter, which tells jsPsych what plugin to use to run the trial. The trial's type is similar to the plugin name, but it always starts with \"jsPsych\" and is written in camel case rather than with dashes between the words. The trial's type parameter should NOT be a string (i.e., no quotes around the type value). Here are some examples of plugin names and types: Plugin name Type image-keyboard-response jsPsychImageKeyboardResponse fullscreen jsPsychFullscreen webgazer-init-camera jsPsychWebgazerInitCamera The following JavaScript code defines a trial using the image-keyboard-response plugin to display an image file. This trial uses the default values for valid keys, stimulus duration, trial duration, and other parameters. var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' } You can override any default parameter values by adding them into your trial object. Here's an example of overriding the default values for trial_duration and post_trial_gap : var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' , trial_duration : 3000 , post_trial_gap : 2000 }","title":"Using a plugin"},{"location":"overview/plugins/#parameters-available-in-all-plugins","text":"Each plugin specifies its own set of parameters. Check the documentation for a plugin to see what parameters are available and what they do. There is also a set of parameters that can be specified for any plugin: Parameter Type Default Value Description data object undefined An object containing additional data to store for the trial. See the Data page for more details. post_trial_gap numeric null Sets the time, in milliseconds, between the current trial and the next trial. If null, there will be no gap. on_start function function(){ return; } A callback function to execute when the trial begins, before any loading has occurred. See the Event-Related Callbacks page for more details. on_finish function function(){ return; } A callback function to execute when the trial finishes, and before the next trial begins. See the Event-Related Callbacks page for more details. on_load function function(){ return; } A callback function to execute when the trial has loaded, which typically happens after the initial display of the plugin has loaded. See the Event-Related Callbacks page for more details. css_classes string null A list of CSS classes to add to the jsPsych display element for the duration of this trial. This allows you to create custom formatting rules (CSS classes) that are only applied to specific trials. For more information and examples, see the Controlling Visual Appearance page and the \"css-classes-parameter.html\" file in the jsPsych examples folder. save_trial_parameters object {} An object containing any trial parameters that should or should not be saved to the trial data. Each key is the name of a trial parameter, and its value should be true or false , depending on whether or not its value should be saved to the data. If the parameter is a function that returns the parameter value, then the value that is returned will be saved to the data. If the parameter is always expected to be a function (e.g., an event-related callback function), then the function itself will be saved as a string. For more examples, see the \"save-trial-parameters.html\" file in the jsPsych examples folder.","title":"Parameters available in all plugins"},{"location":"overview/plugins/#the-data-parameter","text":"The data parameter allows you to add additional properties to the trial data. This can be useful for storing properties of the trial that are not directly apparent from the values that the plugin records. The data parameter value must be an object that contains key-value pairs. A simple example is the Flanker Task . In this experiment, participants respond to the direction of a central arrow by pressing a key to the left for a left-pointing arrow (<) and a key to the right for a right-pointing arrow (>). The arrow appears in the center of flankers , or arrows that the participant should ignore. Those flankers can be congruent (>>>>>) or incongruent (<<><<). A trial for the Flanker Task written with jsPsych might look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' } } Note the use of the data parameter to add a property stimulus_type with the value congruent and a property target_direction with the value left . Having these properties recorded directly in the data simplifies data analysis, making it easy to aggregate data by stimulus_type and/or target_direction .","title":"The data parameter"},{"location":"overview/plugins/#the-post_trial_gap-iti-parameter","text":"The default inter-trial interval (ITI) in jsPsych is 0 ms. This can be adjusted at the experiment-wide level by changing the default_iti parameter in initJsPsych() . The ITI can also be controlled at the trial level through the post_trial_gap parameter. Setting this parameter to a positive integer x will cause a blank screen to display after the trial for x milliseconds. Setting this parameter for a trial will override the default_iti value set in initJsPsych . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'There will be a 1.5 second blank screen after this trial.' , post_trial_gap : 1500 }","title":"The post_trial_gap (ITI) parameter"},{"location":"overview/plugins/#the-on_start-parameter","text":"Immediately before a trial runs, there is an opportunity to run an arbitrary function through the on_start event handler. This event handler is passed a single argument containing an editable copy of the trial parameters. This function can therefore be used to alter the trial based on the state of the experiment, among other uses. // when this trial runs, the on_start function will change the trial's stimulus and data parameters, // so the trial will display an incongruent Flanker stimulus with a right-facing central arrow var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_start : function ( trial ){ trial . stimulus = '<<><<' ; trial . data . stimulus_type = 'incongruent' ; trial . data . target_direction = 'right' ; } }","title":"The on_start parameter"},{"location":"overview/plugins/#the-on_finish-parameter","text":"After a trial is completed, there is an opportunity to run an arbitrary function through the on_finish event handler. This function is passed a single argument containing an editable copy of the data recorded for that trial. This function can therefore be used to update the state of the experiment based on the data collected, or modify the data collected. The on_finish function can be useful to calculate new data properties that were unknowable at the start of the trial. For example, with the Flanker Task example above, the on_finish function could check the response and use to this information to add a new property to the data called correct , which is either true or false . // in addition to all of the standard data collected for this trial, // this on_finish function adds a property called 'correct' // which is either 'true' or 'false' // depending on the response that was made var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' , correct_response : 'f' }, on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response )){ data . correct = true ; } else { data . correct = false ; } } }","title":"The on_finish parameter"},{"location":"overview/plugins/#the-on_load-parameter","text":"The on_load callback function will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. This can be useful for changing various aspects of the page elements and their properties that would otherwise require modifying the plugin file. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { // this will change the src attribute of the image after 500ms setTimeout ( function (){ document . querySelector ( 'img' ). src = 'imgB.png' }, 500 ); } };","title":"The on_load parameter"},{"location":"overview/plugins/#the-css_classes-parameter","text":"The css_classes parameter allows you to add an array of CSS class names to the jsPsych display element on that specific trial. This allows you to create custom style and formatting rules that are only applied to specific trials. If you want CSS rules that only apply to specific elements during a trial, you can use additional CSS selectors. < style > . flanker-stimulus { font-size : 500 % ; } . flanker-stimulus # prompt { font-size : 18 px ; } . fixation { font-size : 80 px ; } </ style > < script > var fixation_trial = { type : jsPsychHtmlKeyboardResponse , choices : \"NO_KEYS\" , stimulus : '+' , css_classes : [ 'fixation' ] }; var flanker_trial = { type : jsPsychHtmlKeyboardResponse , choices : [ \"ArrowLeft\" , \"ArrowRight\" ], stimulus : '>>>>>' , prompt : '<span id=\"prompt\">Press the left or right arrow key.</span>' , css_classes : [ 'flanker-stimulus' ] }; </ script >","title":"The css_classes parameter"},{"location":"overview/plugins/#the-save_trial_parameters-parameter","text":"The save_trial_parameters parameter allows you to tell jsPsych what parameters you want to be saved to the data. This can be used to override the parameter values that the plugin saves by default. You can add more parameter values to the data that are not normally saved, or remove parameter values that normally are saved. This can be especially useful when the parameter value is dynamic (i.e. a function) and you want to record the value that was used during the trial. var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"color: orange; font-size: 48px; font-weight: bold;\">BLUE</p>' , choices : function () { return jsPsych . randomization . shuffle ([ 'Yes' , 'No' ]); }, post_trial_gap : function () { return jsPsych . randomization . sampleWithoutReplacement ([ 200 , 300 , 400 , 500 ], 1 )[ 0 ]; }, save_trial_parameters : { // save the randomly-selected button order and post trial gap duration to the trial data choices : true , post_trial_gap : true , // don't save the stimulus stimulus : false } } Note You cannot remove the internal_node_id and trial_index values from the trial data, because these are used internally by jsPsych.","title":"The save_trial_parameters parameter"},{"location":"overview/plugins/#data-collected-by-all-plugins","text":"Each plugin defines what data is collected on the trial. The documentation for each plugin specifies what information will be stored in the trial data. In addition to the data collected by a plugin, there is a default set of data that is collected on every trial. Name Type Value trial_type string The name of the plugin used to run the trial. trial_index numeric The index of the current trial across the whole experiment. time_elapsed numeric The number of milliseconds between the start of the experiment and when the trial ended. internal_node_id string A string identifier for the current TimelineNode.","title":"Data collected by all plugins"},{"location":"overview/plugins/#creating-a-new-plugin","text":"See our developer's guide for plugins for information about how to create a new plugin.","title":"Creating a new plugin"},{"location":"overview/progress-bar/","text":"Automatic Progress Bar \u00b6 jsPsych can show a progress bar at the top of the experiment page indicating the participant's overall completion progress. The progress bar is rendered outside the jsPsych display element, and it requires the jspsych.css file to be loaded on the page. As of version 6.0, the progress bar looks like this: To show the progress bar, set the show_progress_bar option in initJsPsych to true : var jsPsych = initJsPsych ({ show_progress_bar : true }); The progress bar updates after every node on the top-level timeline updates. This avoids distracting updates in the middle of trials that are composed of multiple plugins, or confusing updates due to looping or conditional structures that may or may not execute depending on the actions of the participant. This also allows some flexibility for the programmer; by nesting timelines in a deliberate manner, the timing of progress bar updates can be controlled. Manual Control \u00b6 The progress bar can also be manually controlled using the function jsPsych.setProgressBar() . This function takes a numeric value between 0 and 1, representing the proportion of the progress bar to fill. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Almost done...' , on_finish : function (){ jsPsych . setProgressBar ( 0.85 ); // set progress bar to 85% full. } } You can also get the current value of the progress bar with jsPsych.getProgressBarCompleted() . var proportion_complete = jsPsych . getProgressBarCompleted (); If you are going to use manual progress bar control, you may want to disable the automatic progress bar updates by setting the auto_update_progress_bar property in initJsPsych() to false . var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); Here's a complete example showing how to use these functions and initJsPsych() settings to manually update the progress bar: var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); var n_trials = 5 ; var start = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press any key to start!' , on_start : function () { // set progress bar to 0 at the start of experiment jsPsych . setProgressBar ( 0 ); } }; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a trial!' , on_finish : function () { // at the end of each trial, update the progress bar // based on the current value and the proportion to update for each trial var curr_progress_bar_value = jsPsych . getProgressBarCompleted (); jsPsych . setProgressBar ( curr_progress_bar_value + ( 1 / n_trials )); } }; var trials = { timeline : [ trial ], repetitions : n_trials }; var done = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Done!' }; jsPsych . run ([ start , trials , done ]); Custom Text \u00b6 By default, jsPsych adds the text \"Completion Progress\" to the left of the progress bar. You can specify custom text using the message_progress_bar parameter in initJsPsych . // support for different spoken languages var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : 'Porcentaje completo' }); // no message var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : '' });","title":"Automatic Progress Bar"},{"location":"overview/progress-bar/#automatic-progress-bar","text":"jsPsych can show a progress bar at the top of the experiment page indicating the participant's overall completion progress. The progress bar is rendered outside the jsPsych display element, and it requires the jspsych.css file to be loaded on the page. As of version 6.0, the progress bar looks like this: To show the progress bar, set the show_progress_bar option in initJsPsych to true : var jsPsych = initJsPsych ({ show_progress_bar : true }); The progress bar updates after every node on the top-level timeline updates. This avoids distracting updates in the middle of trials that are composed of multiple plugins, or confusing updates due to looping or conditional structures that may or may not execute depending on the actions of the participant. This also allows some flexibility for the programmer; by nesting timelines in a deliberate manner, the timing of progress bar updates can be controlled.","title":"Automatic Progress Bar"},{"location":"overview/progress-bar/#manual-control","text":"The progress bar can also be manually controlled using the function jsPsych.setProgressBar() . This function takes a numeric value between 0 and 1, representing the proportion of the progress bar to fill. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Almost done...' , on_finish : function (){ jsPsych . setProgressBar ( 0.85 ); // set progress bar to 85% full. } } You can also get the current value of the progress bar with jsPsych.getProgressBarCompleted() . var proportion_complete = jsPsych . getProgressBarCompleted (); If you are going to use manual progress bar control, you may want to disable the automatic progress bar updates by setting the auto_update_progress_bar property in initJsPsych() to false . var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); Here's a complete example showing how to use these functions and initJsPsych() settings to manually update the progress bar: var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); var n_trials = 5 ; var start = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press any key to start!' , on_start : function () { // set progress bar to 0 at the start of experiment jsPsych . setProgressBar ( 0 ); } }; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a trial!' , on_finish : function () { // at the end of each trial, update the progress bar // based on the current value and the proportion to update for each trial var curr_progress_bar_value = jsPsych . getProgressBarCompleted (); jsPsych . setProgressBar ( curr_progress_bar_value + ( 1 / n_trials )); } }; var trials = { timeline : [ trial ], repetitions : n_trials }; var done = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Done!' }; jsPsych . run ([ start , trials , done ]);","title":"Manual Control"},{"location":"overview/progress-bar/#custom-text","text":"By default, jsPsych adds the text \"Completion Progress\" to the left of the progress bar. You can specify custom text using the message_progress_bar parameter in initJsPsych . // support for different spoken languages var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : 'Porcentaje completo' }); // no message var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : '' });","title":"Custom Text"},{"location":"overview/prolific/","text":"Integrating with Prolific \u00b6 Prolific is a participant recruitment service aimed at research. Integrating a jsPsych experiment with Prolific requires capturing the participant's ID and sending the participant to a completion URL at the end of the experiment. Capturing the Participant ID, Study ID, and Session ID \u00b6 When creating a study on Prolific you must provide the URL to your study. You can host your jsPsych experiment however you'd like - some options are discussed in the Running Experiments documentation page. Once you've got a URL to your experiment, you can enter that in the study link section of Prolific. Then, click the option to record Prolific IDs via URL parameters. This will append information about the participant's prolific ID ( PROLIFIC_PID ), the study's ID ( STUDY_ID ), and the session ID ( SESSION_ID ) to the URL that participants use to access your experiment. We can capture these variables with jsPsych, and add them to jsPsych's data. This can be done anywhere in your code. This code does not need to run as part of your experiment timeline. < script > var jsPsych = initJsPsych (); // capture info from Prolific var subject_id = jsPsych . data . getURLVariable ( 'PROLIFIC_PID' ); var study_id = jsPsych . data . getURLVariable ( 'STUDY_ID' ); var session_id = jsPsych . data . getURLVariable ( 'SESSION_ID' ); jsPsych . data . addProperties ({ subject_id : subject_id , study_id : study_id , session_id : session_id }); // create the rest of the experiment var timeline = [...] jsPsych . run ( timeline ) </ script > Completing the Experiment \u00b6 When the experiment is complete, Prolific requires that you send the participant to a specific URL that marks the session as complete on Prolific's server. The link is provided to you by Prolific in the study completion section of the setup. You can accomplish this in a couple different ways. Warning It's important that you've saved all the data from your experiment before the participant returns to Prolific. Make sure that any server communication has completed prior to redirecting the participant. One way to do this is by using the async features of the call-function plugin ( example ). Participant clicks a link \u00b6 One option is to create a trial that contains a link that the participant clicks to end the experiment and return to Prolific. For example, the html-keyboard-response plugin can be used to display text that includes a link. This could go on a debriefing page. Here's an example trial that could be used. Note that choices is set to \"NO_KEYS\" , which will prevent the participant from continuing past this point in the experiment. var final_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>You've finished the last task. Thanks for participating!</p> <p><a href=\"https://app.prolific.co/submissions/complete?cc=XXXXXXX\">Click here to return to Prolific and complete the study</a>.</p>` , choices : \"NO_KEYS\" } Automatically redirect \u00b6 A second option is to automatically redirect the participant to the completion URL when the experiment is finished. You could do this in a number of places in the jsPsych timeline. Here's an example using the on_finish event for the entire experiment. var jsPsych = initJsPsych ({ on_finish : function (){ window . location = \"https://app.prolific.co/submissions/complete?cc=XXXXXXX\" } });","title":"Integrating with Prolific"},{"location":"overview/prolific/#integrating-with-prolific","text":"Prolific is a participant recruitment service aimed at research. Integrating a jsPsych experiment with Prolific requires capturing the participant's ID and sending the participant to a completion URL at the end of the experiment.","title":"Integrating with Prolific"},{"location":"overview/prolific/#capturing-the-participant-id-study-id-and-session-id","text":"When creating a study on Prolific you must provide the URL to your study. You can host your jsPsych experiment however you'd like - some options are discussed in the Running Experiments documentation page. Once you've got a URL to your experiment, you can enter that in the study link section of Prolific. Then, click the option to record Prolific IDs via URL parameters. This will append information about the participant's prolific ID ( PROLIFIC_PID ), the study's ID ( STUDY_ID ), and the session ID ( SESSION_ID ) to the URL that participants use to access your experiment. We can capture these variables with jsPsych, and add them to jsPsych's data. This can be done anywhere in your code. This code does not need to run as part of your experiment timeline. < script > var jsPsych = initJsPsych (); // capture info from Prolific var subject_id = jsPsych . data . getURLVariable ( 'PROLIFIC_PID' ); var study_id = jsPsych . data . getURLVariable ( 'STUDY_ID' ); var session_id = jsPsych . data . getURLVariable ( 'SESSION_ID' ); jsPsych . data . addProperties ({ subject_id : subject_id , study_id : study_id , session_id : session_id }); // create the rest of the experiment var timeline = [...] jsPsych . run ( timeline ) </ script >","title":"Capturing the Participant ID, Study ID, and Session ID"},{"location":"overview/prolific/#completing-the-experiment","text":"When the experiment is complete, Prolific requires that you send the participant to a specific URL that marks the session as complete on Prolific's server. The link is provided to you by Prolific in the study completion section of the setup. You can accomplish this in a couple different ways. Warning It's important that you've saved all the data from your experiment before the participant returns to Prolific. Make sure that any server communication has completed prior to redirecting the participant. One way to do this is by using the async features of the call-function plugin ( example ).","title":"Completing the Experiment"},{"location":"overview/prolific/#participant-clicks-a-link","text":"One option is to create a trial that contains a link that the participant clicks to end the experiment and return to Prolific. For example, the html-keyboard-response plugin can be used to display text that includes a link. This could go on a debriefing page. Here's an example trial that could be used. Note that choices is set to \"NO_KEYS\" , which will prevent the participant from continuing past this point in the experiment. var final_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>You've finished the last task. Thanks for participating!</p> <p><a href=\"https://app.prolific.co/submissions/complete?cc=XXXXXXX\">Click here to return to Prolific and complete the study</a>.</p>` , choices : \"NO_KEYS\" }","title":"Participant clicks a link"},{"location":"overview/prolific/#automatically-redirect","text":"A second option is to automatically redirect the participant to the completion URL when the experiment is finished. You could do this in a number of places in the jsPsych timeline. Here's an example using the on_finish event for the entire experiment. var jsPsych = initJsPsych ({ on_finish : function (){ window . location = \"https://app.prolific.co/submissions/complete?cc=XXXXXXX\" } });","title":"Automatically redirect"},{"location":"overview/record-browser-interactions/","text":"Record browser interactions \u00b6 Participants in an online experiment have the freedom to multitask while performing an experiment. jsPsych automatically records information about when the user clicks on a window that is not the experiment, and about when the user exits full screen mode if the experiment is running in full screen mode. This data is stored separately from the main experiment data, and can be accessed with jsPsych.data.getInteractionData() . Each time the user leaves the experiment window, returns to the experiment window, exits full screen mode, or enters full screen mode, the event is recorded in the interaction data. Each event has the following structure. { event : 'focus' , // 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' trial : 12 , // the index of the active trial when the event happened time : 1240543 // time in ms since the start of the experiment } You can specify a custom function, in the initJsPsych() method, that is called whenever one of these events occurs initJsPsych ({ on_interaction_data_update : function ( data ) { console . log ( JSON . stringify ( data )) } });","title":"Record Browser Interactions"},{"location":"overview/record-browser-interactions/#record-browser-interactions","text":"Participants in an online experiment have the freedom to multitask while performing an experiment. jsPsych automatically records information about when the user clicks on a window that is not the experiment, and about when the user exits full screen mode if the experiment is running in full screen mode. This data is stored separately from the main experiment data, and can be accessed with jsPsych.data.getInteractionData() . Each time the user leaves the experiment window, returns to the experiment window, exits full screen mode, or enters full screen mode, the event is recorded in the interaction data. Each event has the following structure. { event : 'focus' , // 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' trial : 12 , // the index of the active trial when the event happened time : 1240543 // time in ms since the start of the experiment } You can specify a custom function, in the initJsPsych() method, that is called whenever one of these events occurs initJsPsych ({ on_interaction_data_update : function ( data ) { console . log ( JSON . stringify ( data )) } });","title":"Record browser interactions"},{"location":"overview/running-experiments/","text":"Running Experiments \u00b6 You can run your jsPsych experiment: Offline , by opening the HTML file directly in the browser using the file:// protocol. Online , by hosting the files on a web server using the http:// or https:// protocol. The way that you run your experiment will have consequences for certain aspects about how the experiment works, and what your experiment will be able to do. This page explains what you need to know about both of these options. Info If you are looking for a tool to automate deployment-related tasks, check out the jsPsych Builder CLI utility. It automatically bundles scripts and style sheets, configures media preloading, and yields a zip file that contains all files for deployment (online or offline). jsPsych Builder can also directly build JATOS experiment files (.jzip) that you can upload to a JATOS server (see this section below for more info about JATOS and other server options). Offline \u00b6 You can run your jsPsych experiment offline by opening the HTML file directly in a web browser, for instance by double-clicking on it. This uses the file:// protocol. It's usually the fastest and easiest way to run through an experiment, and is very useful while writing and testing the code. At some point you will need to move your experiment files onto a server and send the data to a database, since this is how you will ultimately collect the data (unless you're planning to collect data on your local computer). There are some important differences between the way the experiment runs offline compared to online via a web server. Note that, unless noted, here we're using the word \"server\" to mean either a local server (which runs on your computer and only makes the experiment files available from within that computer, and is often used during development), or a remote server (which does not run on your computer and does share your experiment files over the internet). Cross-origin requests (CORS) and safe mode \u00b6 Web browsers have a security policy called cross-origin resource sharing (CORS) that determines whether the webpage can request files that come from a different origin (i.e. protocol, host/domain, and port). This isn't a problem when your study runs online , because in that case your experiment files all have the same origin. However, when you run your experiment offline , the CORS policy blocks some jsPsych features that require loading local files . If your experiment uses these features, then CORS errors will prevent the experiment from running. To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTML page is running via the file:// protocol, and if so, automatically disables the features that don't work in that context. Specifically, when a jsPsych experiment runs offline: Web Audio is disabled (even if use_webaudio is set to true in initJsPsych ). The WebAudio API option is used by default because it allows more precise measurement of response times relative to the onset of the audio. But because WebAudio doesn't work offline, audio will be played using HTML5 audio instead. This is equivalent to setting use_webaudio to false in initJsPsych . Video preloading is disabled (both automatic and manual preloading via the preload plugin). Videos will still play when you run your experiment offline, but they will load during the experiment, which might cause noticeable delays before video playback starts. This safe mode feature is controlled by the override_safe_mode parameter in initJsPsych , which defaults to false . If you leave this setting as the default, then you won't need to worry about CORS errors while running your experiment offline, or remembering to change your initJsPsych settings when you move the experiment online. It's possible to override jsPsych's safe mode by setting override_safe_mode to true in initJsPsych . One reason you might do this is if you've disabled web security features in your browser (see here and here for instructions in Chrome), which is safe to do if you know what you're doing. If your experiment does not use Web Audio or preloaded videos, then jsPsych's safe mode feature will not have any effect. The override_safe_mode parameter also has no effect when your experiment is running online a web server, because the page will be loaded via the http:// or https:// protocol. Media loading \u00b6 While running your experiment offline, any media files are likely to load very quickly because they are stored on your own computer's disk. Therefore you may not notice problems with file loading delays while running your experiment locally (either offline or on a local server) because the files will load fast enough that they never cause disruption. However, when your experiment is hosted on a remote server, the files will need to be transferred over the internet, which means they will take longer to load - in some cases much longer. Loading delays are most noticeable with media files: images, audio, and video. As explained on the Media Preloading page, loading delays during your experiment can cause problems for stimulus display and response times. It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see here for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the max_load_time parameter in the preload plugin so that participants with slow/unreliable internet connections will be able to take part in your experiment. Permanent data storage \u00b6 As explained in the Data Storage, Aggregation, and Manipulation page, jsPsych stores information in the participant's browser. While running an experiment offline, you won't be able to send the data to a database. However you can still see the data that jsPsych collects by saving it as a local file (using jsPsych.data.get().localSave ), displaying it in the webpage at the end of the experiment (using jsPsych.data.displayData ), or printing it to the browser's console (using console.log ). Permanent data storage is also necessary when the code that runs the experiment depends on information that can't be known in advance, and that changes throughout data collection. Some common examples of this in cognitive behavioral research are version counterbalancing , where the experiment code needs to access and update the history of version assignment in order to determine which version should be assigned, and multi-session/training studies , where the experiment might need to access and update information about each participant like their current session number, task difficulty level, etc. Doing these things in an automated way requires the use of a server. While developing and testing your experiment offline, you might choose to simulate some of these things and then implement them properly once you move your experiment online. For instance, you could randomize instead of counterbalancing version assignment: var versions = [ 1 , 2 ]; var random_version = jsPsych . randomization . sampleWithoutReplacement ( versions , 1 )[ 0 ]; And use URL query parameters to pass in variables like session number and difficulty level: // add the variables onto the end of the URL that appears in the browser when you open the file // e.g., file:///C:/my_experiment.html?id=1&sess=2&diff=3 var participant_id = jsPsych . data . getURLVariable ( 'id' ); var session = jsPsych . data . getURLVariable ( 'sess' ); var difficulty = jsPsych . data . getURLVariable ( 'diff' ); Online \u00b6 Hosting the Experiment and Saving the Data \u00b6 jsPsych is a front-end JavaScript library that runs entirely on the participant's computer. To run a jsPsych experiment over the internet, the files need to be hosted on a public web server so that participants can access the experiment using a web browser. When the participant completes the experiment in the browser, all of the data that jsPsych collects is stored on the participant's computer in the browser's memory. To get access to this data, it needs to be sent from the participant's browser back to the web server and stored in a database or a file. To be maximally flexible, jsPsych doesn't provide a single built-in solution for the web server component of your experiment. This makes jsPsych compatible with a wide range of hosting services and tools, allowing researchers to choose the web server option that best suit their needs. Some options for running your jsPsych experiment online include: Cognition.run - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. JATOS - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers. Pavlovia - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia. PsiTurk - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option. Pushkin - A set of tools to help you set up your own virtual laboratory for online experiments. This option differs from the others in that it helps you set up a complete website that may contain many different experiments, information about the laboratory, participant logins, and other features that are targeted at hosting large-scale data collection efforts. Full DIY - You can setup your own web server and database and handle the communication yourself. Traditional web server 'stacks' include LAMP / LEMP (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include Flask (Python) and Node.js (JavaScript). Recruiting Participants \u00b6 Once your experiment is running online, you could recruit participants in the same way that you would for lab-based studies. For instance, if your institution uses SONA, you can advertise your web-based study link on SONA. SONA allows you to automactically embed a unique ID in online study URLs, which you can then save in your data using jsPsych's URL query parameters function . SONA will also generate a completion URL that you can redirect participants to at the end of the study, and this will mark them as having completed the study in SONA. To take full advantage of hosting an experiment online, many researchers advertise their experiments more widely. Social media and other media outlets provide one option for reaching a large number of potential participants. There are also some commercial platforms that you can use to advertise your study and pay anonymous online participants. These recruitment platforms charge a fee for use. The advantages of these platforms are that they handle the participant payments and allow you to specify pre-screening criteria. The most commonly used recruitment platforms in online behavioral research are: Prolific : An online labor market designed specifically for web-based research. Amazon Mechanical Turk (MTurk) : An online labor market designed for advertising paid 'human intelligence tasks'. This service was designed for use by commercial businesses but has been used by behavioral researchers for many years. Like SONA, Prolific and MTurk use URL query parameters to get participant information, and redirection to specific URLs to mark participants as having finished the study. jsPsych includes convenience functions for interacting with MTurk participants . Information about integrating with Prolific can be found in the researcher support section of their website.","title":"Running Experiments"},{"location":"overview/running-experiments/#running-experiments","text":"You can run your jsPsych experiment: Offline , by opening the HTML file directly in the browser using the file:// protocol. Online , by hosting the files on a web server using the http:// or https:// protocol. The way that you run your experiment will have consequences for certain aspects about how the experiment works, and what your experiment will be able to do. This page explains what you need to know about both of these options. Info If you are looking for a tool to automate deployment-related tasks, check out the jsPsych Builder CLI utility. It automatically bundles scripts and style sheets, configures media preloading, and yields a zip file that contains all files for deployment (online or offline). jsPsych Builder can also directly build JATOS experiment files (.jzip) that you can upload to a JATOS server (see this section below for more info about JATOS and other server options).","title":"Running Experiments"},{"location":"overview/running-experiments/#offline","text":"You can run your jsPsych experiment offline by opening the HTML file directly in a web browser, for instance by double-clicking on it. This uses the file:// protocol. It's usually the fastest and easiest way to run through an experiment, and is very useful while writing and testing the code. At some point you will need to move your experiment files onto a server and send the data to a database, since this is how you will ultimately collect the data (unless you're planning to collect data on your local computer). There are some important differences between the way the experiment runs offline compared to online via a web server. Note that, unless noted, here we're using the word \"server\" to mean either a local server (which runs on your computer and only makes the experiment files available from within that computer, and is often used during development), or a remote server (which does not run on your computer and does share your experiment files over the internet).","title":"Offline"},{"location":"overview/running-experiments/#cross-origin-requests-cors-and-safe-mode","text":"Web browsers have a security policy called cross-origin resource sharing (CORS) that determines whether the webpage can request files that come from a different origin (i.e. protocol, host/domain, and port). This isn't a problem when your study runs online , because in that case your experiment files all have the same origin. However, when you run your experiment offline , the CORS policy blocks some jsPsych features that require loading local files . If your experiment uses these features, then CORS errors will prevent the experiment from running. To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTML page is running via the file:// protocol, and if so, automatically disables the features that don't work in that context. Specifically, when a jsPsych experiment runs offline: Web Audio is disabled (even if use_webaudio is set to true in initJsPsych ). The WebAudio API option is used by default because it allows more precise measurement of response times relative to the onset of the audio. But because WebAudio doesn't work offline, audio will be played using HTML5 audio instead. This is equivalent to setting use_webaudio to false in initJsPsych . Video preloading is disabled (both automatic and manual preloading via the preload plugin). Videos will still play when you run your experiment offline, but they will load during the experiment, which might cause noticeable delays before video playback starts. This safe mode feature is controlled by the override_safe_mode parameter in initJsPsych , which defaults to false . If you leave this setting as the default, then you won't need to worry about CORS errors while running your experiment offline, or remembering to change your initJsPsych settings when you move the experiment online. It's possible to override jsPsych's safe mode by setting override_safe_mode to true in initJsPsych . One reason you might do this is if you've disabled web security features in your browser (see here and here for instructions in Chrome), which is safe to do if you know what you're doing. If your experiment does not use Web Audio or preloaded videos, then jsPsych's safe mode feature will not have any effect. The override_safe_mode parameter also has no effect when your experiment is running online a web server, because the page will be loaded via the http:// or https:// protocol.","title":"Cross-origin requests (CORS) and safe mode"},{"location":"overview/running-experiments/#media-loading","text":"While running your experiment offline, any media files are likely to load very quickly because they are stored on your own computer's disk. Therefore you may not notice problems with file loading delays while running your experiment locally (either offline or on a local server) because the files will load fast enough that they never cause disruption. However, when your experiment is hosted on a remote server, the files will need to be transferred over the internet, which means they will take longer to load - in some cases much longer. Loading delays are most noticeable with media files: images, audio, and video. As explained on the Media Preloading page, loading delays during your experiment can cause problems for stimulus display and response times. It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see here for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the max_load_time parameter in the preload plugin so that participants with slow/unreliable internet connections will be able to take part in your experiment.","title":"Media loading"},{"location":"overview/running-experiments/#permanent-data-storage","text":"As explained in the Data Storage, Aggregation, and Manipulation page, jsPsych stores information in the participant's browser. While running an experiment offline, you won't be able to send the data to a database. However you can still see the data that jsPsych collects by saving it as a local file (using jsPsych.data.get().localSave ), displaying it in the webpage at the end of the experiment (using jsPsych.data.displayData ), or printing it to the browser's console (using console.log ). Permanent data storage is also necessary when the code that runs the experiment depends on information that can't be known in advance, and that changes throughout data collection. Some common examples of this in cognitive behavioral research are version counterbalancing , where the experiment code needs to access and update the history of version assignment in order to determine which version should be assigned, and multi-session/training studies , where the experiment might need to access and update information about each participant like their current session number, task difficulty level, etc. Doing these things in an automated way requires the use of a server. While developing and testing your experiment offline, you might choose to simulate some of these things and then implement them properly once you move your experiment online. For instance, you could randomize instead of counterbalancing version assignment: var versions = [ 1 , 2 ]; var random_version = jsPsych . randomization . sampleWithoutReplacement ( versions , 1 )[ 0 ]; And use URL query parameters to pass in variables like session number and difficulty level: // add the variables onto the end of the URL that appears in the browser when you open the file // e.g., file:///C:/my_experiment.html?id=1&sess=2&diff=3 var participant_id = jsPsych . data . getURLVariable ( 'id' ); var session = jsPsych . data . getURLVariable ( 'sess' ); var difficulty = jsPsych . data . getURLVariable ( 'diff' );","title":"Permanent data storage"},{"location":"overview/running-experiments/#online","text":"","title":"Online"},{"location":"overview/running-experiments/#hosting-the-experiment-and-saving-the-data","text":"jsPsych is a front-end JavaScript library that runs entirely on the participant's computer. To run a jsPsych experiment over the internet, the files need to be hosted on a public web server so that participants can access the experiment using a web browser. When the participant completes the experiment in the browser, all of the data that jsPsych collects is stored on the participant's computer in the browser's memory. To get access to this data, it needs to be sent from the participant's browser back to the web server and stored in a database or a file. To be maximally flexible, jsPsych doesn't provide a single built-in solution for the web server component of your experiment. This makes jsPsych compatible with a wide range of hosting services and tools, allowing researchers to choose the web server option that best suit their needs. Some options for running your jsPsych experiment online include: Cognition.run - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. JATOS - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers. Pavlovia - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia. PsiTurk - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option. Pushkin - A set of tools to help you set up your own virtual laboratory for online experiments. This option differs from the others in that it helps you set up a complete website that may contain many different experiments, information about the laboratory, participant logins, and other features that are targeted at hosting large-scale data collection efforts. Full DIY - You can setup your own web server and database and handle the communication yourself. Traditional web server 'stacks' include LAMP / LEMP (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include Flask (Python) and Node.js (JavaScript).","title":"Hosting the Experiment and Saving the Data"},{"location":"overview/running-experiments/#recruiting-participants","text":"Once your experiment is running online, you could recruit participants in the same way that you would for lab-based studies. For instance, if your institution uses SONA, you can advertise your web-based study link on SONA. SONA allows you to automactically embed a unique ID in online study URLs, which you can then save in your data using jsPsych's URL query parameters function . SONA will also generate a completion URL that you can redirect participants to at the end of the study, and this will mark them as having completed the study in SONA. To take full advantage of hosting an experiment online, many researchers advertise their experiments more widely. Social media and other media outlets provide one option for reaching a large number of potential participants. There are also some commercial platforms that you can use to advertise your study and pay anonymous online participants. These recruitment platforms charge a fee for use. The advantages of these platforms are that they handle the participant payments and allow you to specify pre-screening criteria. The most commonly used recruitment platforms in online behavioral research are: Prolific : An online labor market designed specifically for web-based research. Amazon Mechanical Turk (MTurk) : An online labor market designed for advertising paid 'human intelligence tasks'. This service was designed for use by commercial businesses but has been used by behavioral researchers for many years. Like SONA, Prolific and MTurk use URL query parameters to get participant information, and redirection to specific URLs to mark participants as having finished the study. jsPsych includes convenience functions for interacting with MTurk participants . Information about integrating with Prolific can be found in the researcher support section of their website.","title":"Recruiting Participants"},{"location":"overview/simulation/","text":"Simulation Modes \u00b6 Added in 7.1 Simulation mode allows you run your experiment automatically and generate artificial data. Info For a detailed description of the motivation behind simulation mode and a discussion of different use cases of simulation mode, see de Leeuw, J.R., Gilbert, R.A., Petrov, N.B., & Luchterhandt, B. (2022). Simulation behavior to help researchers build experiments. Behavior Research Methods , https://doi.org/10.3758/s13428-022-01899-0 . A pre-print version is available on PsyArXiv . Getting Started \u00b6 To use simulation mode, replace jsPsych.run() with jsPsych.simulate() . jsPsych . simulate ( timeline ); This will run jsPsych in the default data-only simulation mode. To use the visual simulation mode you can specify the second parameter. jsPsych . simulate ( timeline , \"data-only\" ); jsPsych . simulate ( timeline , \"visual\" ); What happens in simulation mode \u00b6 In simulation mode, plugins call their simulate() method instead of calling their trial() method. If a plugin doesn't implement a simulate() method, then the trial will run as usual (using the trial() method) and any interaction that is needed to advance to the next trial will be required. If a plugin doesn't support visual mode, then it will run in data-only mode. data-only mode \u00b6 In data-only mode plugins typically generate resonable artificial data given the parameters specified for the trial. For example, if the trial_duration parameter is set to 2,000 ms, then any response times generated will be capped at this value. Generally the default data generated by the plugin randomly selects any available options (e.g., buttons to click) with equal probability. Response times are usually generated by sampling from an exponentially-modified Gaussian distribution truncated to positive values using jsPsych.randomization.sampleExGaussian() . In data-only mode, the plugin's trial() method usually does not run. The data are simply calculated based on trial parameters and the finishTrial() method is called immediately with the simulated data. visual mode \u00b6 In visual mode a plugin will typically generate simulated data for the trial and then use that data to mimic the kinds of actions that a participant would do. The plugin's trial() method is called by the simulation, and you'll see the experiment progress in real time. Mouse, keyboard, and touch events are simulated to control the experiment. In visual mode each plugin will generate simulated data in the same manner as data-only mode, but this data will instead be used to generate actions in the experiment and the plugin's trial() method will ultimately be responsible for generating the data. This can create some subtle differences in data between the two modes. For example, if the simulated data generates a response time of 500 ms, the data.rt value will be exactly 500 in data-only mode, but may be 501 or another slightly larger value in visual mode. This is because the simulated response is triggered at 500 ms and small delays due to JavaScript's event loop might add a few ms to the measure. Controlling simulation mode with simulation_options \u00b6 The parameters for simulation mode can be set using the simulation_options parameter in both jsPsych.simulate() and at the level of individual trials. Trial-level options \u00b6 You can specify simulation options for an individual trial by setting the simulation_options parameter. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : 500 } } } Currently the three options that are available are data , mode , and simulate . data \u00b6 Setting the data option will replace the default data generated by the plugin with whatever data you specify. You can specify some or all of the data parameters. Any parameters you do not specify will be generated by the plugin. In most cases plugins will try to ensure that the data generated is consistent with the trial parameters. For example, if a trial has a trial_duration parameter of 2000 but the simulation_options specify a rt of 2500 , this creates an impossible situation because the trial would have ended before the response at 2,500ms. In most cases, the plugin will act as if a response was attempted at 2500 , which will mean that no response is generated for the trial. As you might imagine, there are a lot of parameter combinations that can generate peculiar cases where data may be inconsistent with trial parameters. We recommend double checking the simulation output, and please alert us if you discover a situation where the simulation produces inconsistent data. mode \u00b6 You can override the simulation mode specified in jsPsych.simulate() for any trial. Setting mode: 'data-only' will run the trial in data-only mode and setting mode: 'visual' will run the trial in visual mode. simulate \u00b6 If you want to turn off simulation mode for a trial, set simulate: false . Functions and timeline variables \u00b6 The simulation_options parameter is compatible with both dynamic parameters and timeline variables . Dynamic parameters can be especially useful if you want to randomize the data for each run of the simulation. For example, you can specify the rt as a sample from an ExGaussian distribution. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : ()=>{ return jsPsych . randomization . sampleExGaussian ( 500 , 50 , 1 / 100 , true ) } } } } Experiment-level options \u00b6 You can also control the parameters for simulation by passing in an object to the simulation_options argument of jsPsych.simulate() . const simulation_options = { default : { data : { rt : 200 } } } jsPsych . simulate ( timeline , \"visual\" , simulation_options ) The above example will set the rt for any trial that doesn't have its own simulation_options specified to 200 . This could be useful, for example, to create a very fast preview of the experiment to verify that everything is displaying correctly without having to wait through longer trials. You can also specify sets of parameters by name using the experiment-level simulation options. const simulation_options = { default : { data : { rt : 200 } }, long_response : { data : { rt : () => { return jsPsych . randomization . sampleExGaussian ( 5000 , 500 , 1 / 500 , true ) } } } } const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>This is gonna take a bit.</p>' , simulation_options : 'long_response' } timeline . push ( trial ); jsPsych . simulate ( timeline , \"visual\" , simulation_options ) In the example above, we specified the simulation_options for trial using a string ( 'long_response' ). This will look up the corresponding set of options in the experiment-level simulation_options . We had a few use cases in mind with this approach: You could group together trials with similar behavior without needing to specify unique options for each trial. You could easily swap out different simulation options to test different kinds of behavior. For example, if you want to test that a timeline with a conditional_function is working as expected, you could have one set of simulation options where the data will cause the conditional_function to evaluate to true and another to false . By using string-based identifiers, you don't need to change the timeline code at all. You can just change the object being passed to jsPsych.simulate() . In an extreme case of the previous example, every trial on the timeline could have its own unique identifier and you could have multiple sets of simulation options to have very precise control over the data output. Current Limitations \u00b6 Simulation mode is not yet as comprehensively tested as the rest of jsPsych. While we are confident that the simulation is accurate enough for many use cases, it's very likely that there are circumstances where the simulated behavior will be inconsistent with what is actually possible in the experiment. If you come across any such circumstances, please let us know ! Currently extensions are not supported in simulation mode. Some plugins are also not supported. This will be noted on their documentation page.","title":"Simulation Modes"},{"location":"overview/simulation/#simulation-modes","text":"Added in 7.1 Simulation mode allows you run your experiment automatically and generate artificial data. Info For a detailed description of the motivation behind simulation mode and a discussion of different use cases of simulation mode, see de Leeuw, J.R., Gilbert, R.A., Petrov, N.B., & Luchterhandt, B. (2022). Simulation behavior to help researchers build experiments. Behavior Research Methods , https://doi.org/10.3758/s13428-022-01899-0 . A pre-print version is available on PsyArXiv .","title":"Simulation Modes"},{"location":"overview/simulation/#getting-started","text":"To use simulation mode, replace jsPsych.run() with jsPsych.simulate() . jsPsych . simulate ( timeline ); This will run jsPsych in the default data-only simulation mode. To use the visual simulation mode you can specify the second parameter. jsPsych . simulate ( timeline , \"data-only\" ); jsPsych . simulate ( timeline , \"visual\" );","title":"Getting Started"},{"location":"overview/simulation/#what-happens-in-simulation-mode","text":"In simulation mode, plugins call their simulate() method instead of calling their trial() method. If a plugin doesn't implement a simulate() method, then the trial will run as usual (using the trial() method) and any interaction that is needed to advance to the next trial will be required. If a plugin doesn't support visual mode, then it will run in data-only mode.","title":"What happens in simulation mode"},{"location":"overview/simulation/#data-only-mode","text":"In data-only mode plugins typically generate resonable artificial data given the parameters specified for the trial. For example, if the trial_duration parameter is set to 2,000 ms, then any response times generated will be capped at this value. Generally the default data generated by the plugin randomly selects any available options (e.g., buttons to click) with equal probability. Response times are usually generated by sampling from an exponentially-modified Gaussian distribution truncated to positive values using jsPsych.randomization.sampleExGaussian() . In data-only mode, the plugin's trial() method usually does not run. The data are simply calculated based on trial parameters and the finishTrial() method is called immediately with the simulated data.","title":"data-only mode"},{"location":"overview/simulation/#visual-mode","text":"In visual mode a plugin will typically generate simulated data for the trial and then use that data to mimic the kinds of actions that a participant would do. The plugin's trial() method is called by the simulation, and you'll see the experiment progress in real time. Mouse, keyboard, and touch events are simulated to control the experiment. In visual mode each plugin will generate simulated data in the same manner as data-only mode, but this data will instead be used to generate actions in the experiment and the plugin's trial() method will ultimately be responsible for generating the data. This can create some subtle differences in data between the two modes. For example, if the simulated data generates a response time of 500 ms, the data.rt value will be exactly 500 in data-only mode, but may be 501 or another slightly larger value in visual mode. This is because the simulated response is triggered at 500 ms and small delays due to JavaScript's event loop might add a few ms to the measure.","title":"visual mode"},{"location":"overview/simulation/#controlling-simulation-mode-with-simulation_options","text":"The parameters for simulation mode can be set using the simulation_options parameter in both jsPsych.simulate() and at the level of individual trials.","title":"Controlling simulation mode with simulation_options"},{"location":"overview/simulation/#trial-level-options","text":"You can specify simulation options for an individual trial by setting the simulation_options parameter. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : 500 } } } Currently the three options that are available are data , mode , and simulate .","title":"Trial-level options"},{"location":"overview/simulation/#data","text":"Setting the data option will replace the default data generated by the plugin with whatever data you specify. You can specify some or all of the data parameters. Any parameters you do not specify will be generated by the plugin. In most cases plugins will try to ensure that the data generated is consistent with the trial parameters. For example, if a trial has a trial_duration parameter of 2000 but the simulation_options specify a rt of 2500 , this creates an impossible situation because the trial would have ended before the response at 2,500ms. In most cases, the plugin will act as if a response was attempted at 2500 , which will mean that no response is generated for the trial. As you might imagine, there are a lot of parameter combinations that can generate peculiar cases where data may be inconsistent with trial parameters. We recommend double checking the simulation output, and please alert us if you discover a situation where the simulation produces inconsistent data.","title":"data"},{"location":"overview/simulation/#mode","text":"You can override the simulation mode specified in jsPsych.simulate() for any trial. Setting mode: 'data-only' will run the trial in data-only mode and setting mode: 'visual' will run the trial in visual mode.","title":"mode"},{"location":"overview/simulation/#simulate","text":"If you want to turn off simulation mode for a trial, set simulate: false .","title":"simulate"},{"location":"overview/simulation/#functions-and-timeline-variables","text":"The simulation_options parameter is compatible with both dynamic parameters and timeline variables . Dynamic parameters can be especially useful if you want to randomize the data for each run of the simulation. For example, you can specify the rt as a sample from an ExGaussian distribution. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : ()=>{ return jsPsych . randomization . sampleExGaussian ( 500 , 50 , 1 / 100 , true ) } } } }","title":"Functions and timeline variables"},{"location":"overview/simulation/#experiment-level-options","text":"You can also control the parameters for simulation by passing in an object to the simulation_options argument of jsPsych.simulate() . const simulation_options = { default : { data : { rt : 200 } } } jsPsych . simulate ( timeline , \"visual\" , simulation_options ) The above example will set the rt for any trial that doesn't have its own simulation_options specified to 200 . This could be useful, for example, to create a very fast preview of the experiment to verify that everything is displaying correctly without having to wait through longer trials. You can also specify sets of parameters by name using the experiment-level simulation options. const simulation_options = { default : { data : { rt : 200 } }, long_response : { data : { rt : () => { return jsPsych . randomization . sampleExGaussian ( 5000 , 500 , 1 / 500 , true ) } } } } const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>This is gonna take a bit.</p>' , simulation_options : 'long_response' } timeline . push ( trial ); jsPsych . simulate ( timeline , \"visual\" , simulation_options ) In the example above, we specified the simulation_options for trial using a string ( 'long_response' ). This will look up the corresponding set of options in the experiment-level simulation_options . We had a few use cases in mind with this approach: You could group together trials with similar behavior without needing to specify unique options for each trial. You could easily swap out different simulation options to test different kinds of behavior. For example, if you want to test that a timeline with a conditional_function is working as expected, you could have one set of simulation options where the data will cause the conditional_function to evaluate to true and another to false . By using string-based identifiers, you don't need to change the timeline code at all. You can just change the object being passed to jsPsych.simulate() . In an extreme case of the previous example, every trial on the timeline could have its own unique identifier and you could have multiple sets of simulation options to have very precise control over the data output.","title":"Experiment-level options"},{"location":"overview/simulation/#current-limitations","text":"Simulation mode is not yet as comprehensively tested as the rest of jsPsych. While we are confident that the simulation is accurate enough for many use cases, it's very likely that there are circumstances where the simulated behavior will be inconsistent with what is actually possible in the experiment. If you come across any such circumstances, please let us know ! Currently extensions are not supported in simulation mode. Some plugins are also not supported. This will be noted on their documentation page.","title":"Current Limitations"},{"location":"overview/style/","text":"Controlling Visual Appearance \u00b6 Your experiment's style and formatting comes from the CSS (cascading style sheet) rules that are stored in the jspsych.css file, and the browser's defaults. There are a few ways to change the style and formatting in your experiment. The method that you choose is partly a matter of personal preference. It might also depend on whether you want the style/formatting change(s) to apply to specific trials , to the whole experiment (HTML page), or across different experiments . This section discusses the different ways of incorporating CSS into your jsPsych experiment. You can also see this page about adding CSS to web pages to learn more. Inline CSS \u00b6 Whenever you're using a parameter that accepts an HTML-formatted string, you have the option to include inline CSS. Inline CSS is a way of adding style and formatting directly into a specific HTML element using its \"style\" attribute . This is a good option for when you want to make few and/or simple style changes to an HTML trial parameter. To change an element's style using inline CSS, you can set the element's \"style\" attribute to a string that contains the CSS parameters that you want to change, along with the values that you want to use. The syntax is \" <parameter-name> : <parameter-value> ;\". In the example below, the stimulus font size is set to 30px and the text color is set to red. These changes will only be applied to this stimulus text in this specific trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:30px;color:red;\">hello world!</p>' } You can also use a dynamic parameter to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and timeline variables : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var stim = '<p style=\"font-size:30px;font-weight:bold;\">' + jsPsych . timelineVariable ( 'text' ) + '</p>' ; return stim ; } } var trial_procedure = { timeline : [ trial ], timeline_variables : [ { text : 'Welcome' }, { text : 'to' }, { text : 'the' }, { text : 'experiment!' } ] } Adding CSS rules \u00b6 You may want to add a lot of different CSS changes to your experiment, re-use the same change(s) across lots of different trials, and/or separate the style/formatting from the HTML string. In these cases, you might find it useful to create CSS rules rather than using inline CSS. Creating CSS rules is a lot like using inline CSS, except that you also need to use a CSS selector . This is because your CSS rules aren't attached to any specific HTML element (unlike inline CSS), so you need to tell the browser which element(s) the style rules should apply to. The syntax is \"css-selector { <parameter-name> : <parameter-value> ; }\". In the example below, the CSS selector \"p\" tells the browser to apply the font size change to any text that is inside of a <p> element. p { font-size : 30 px ; } You can make more specific changes using CSS rules. The specificity will depend on the CSS selectors that are used. In addition to using the tag name (e.g. \"p\"), other common CSS selectors include the element's ID or class . If you are selecting an element using it's ID, then the CSS selector needs to have a # in front of the ID, e.g. \"#stimulus\". If you are selecting elements based on their class, then you need to include a . in front of the class, e.g. \".large-text\". In the example below, the \"#stimulus\" CSS selector means that the width change will only affect elements with the \"stimulus\" ID, and the \".large-text\" CSS selector means that the font size change will only affect elements that have the \"large-text\" class. # stimulus width : 300px ; } . large-text { font-size : 200 % ; } It is possible to create even more specific CSS selectors, for instance by combining tags, IDs, and/or classes. For example, let's say that you are showing feedback text to participants, and that this text is inside of a <p> tag. You could add the ID \"correct\" to the <p> element for correct response feedback, and the ID \"incorrect\" to the <p> element for incorrect response feedback. Then you can define separate styles for correct and incorrect feedback text like this: p # incorrect { color : red ; } p # correct { color : green ; } See this page about CSS selectors for a complete reference of CSS selector patterns and their meanings. With style tags \u00b6 You can add CSS rules to your HTML page by putting them inside of <style> tags. These rules will be applied to your whole experiment . This method can be useful for making general changes to the way that your experiment looks. In the example below, the default font size is set to 25px throughout the experiment. This will overrule the default font size of 18px that is set in the jspsych.css file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . jspsych-display-element { font-size : 25 px ; } </ style > </ head > With a stylesheet \u00b6 CSS rules can also be applied to your experiment with a link to an external CSS file. This is the same method that is usually used to apply the style from jspsych.css to an experiment. These rules will be applied to your whole experiment . You may find it useful to use a custom stylesheet when you want to re-use the same CSS rules across multiple experiments (HTML files). This example shows how to add a custom CSS file in addition to the styles provided in jspsych.css. In this example, the custom CSS file is called \"my_experiment_style.css\" and it is located in the same directory as your HTML file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < link rel = \"stylesheet\" href = \"my_experiment_style.css\" > </ head > Below are the some example contents of an external CSS file, like the \"my_experiment_style.css\" from the example above. This CSS will (1) change the page background color to black, (2) change the default font to 25px and white, and (3) limit the width of the page content so that it can only take up to 80% of its normal width. body { background-color : black ; } . jspsych-display-element { font-size : 25 px ; color : white ; } . jspsych-content { max-width : 80 % ; } Note <style> tags are not used inside of an external CSS file. Using the css_classes trial parameter \u00b6 CSS rules can also be applied in a trial-specific way using the css_classes parameter. This parameter will apply one or more class to the <div> element that holds all of the jsPsych page content during that specific trial. This way you can treat CSS styles just like any other trial parameter. You can use a static css_classes parameter value if you always want to apply the same CSS rules to the trial. In the 'fixation' example below, separating the style rules from the stimulus string makes the code a little bit 'cleaner', and this makes it easier to re-use the same style rules in other parts of the experiment. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . fixation { font-size : 90 px ; font-weight : bold ; color : gray ;} </ style > </ head > < script > var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 , css_classes : [ 'fixation' ] } // ... </ script > You may want the css_classes parameter to vary across trials. If so, you can turn it into a dynamic parameter or use timeline variables (see examples below). One thing to note about the css_classes parameter is that it only adds the class(es) to the jspsych-content <div> element, which is the \"parent\" element that contains all of the experiment content. Often you'll want your CSS rules to be applied to other elements inside of this jspsych-content div. Sometimes your CSS rules will be \"inherited\" by all of the other jsPsych content inside of this parent <div>. For instance, in the fixation example above, the CSS rules that change the font size, weight and color are applied to the parent <div> and automatically passed on to the stimulus text through inheritance. There are two reasons why a CSS rule like the one above for fixation may not work the way you expect: Not all CSS properties are inherited from the parent element. When a CSS property is inherited from the parent element, it will affect all elements in a given trial. In these cases, you can change your CSS selector to make it more specific: add a space after class name, then add more CSS selectors to select the specific element(s) that you want to change. Tip To find out this more specific CSS selector, you can right-click on the element and select Inspect . In the inspector window, right-click on the property corresponding to the element and copy the selector. You might need to increase the trial's trial_duration to give yourself enough time to inspect the elements on the page. See more tips for working with CSS below. In the example below, the CSS selector .left-align #stimulus selects the element with the ID \"stimulus\" that is inside of an element with the class \"left-align\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ) }], timeline_variables : [ { css_classes : [ 'left-align' ]}, { css_classes : [ 'right-align' ]} ] } // ... </ script > It's also possible to pass multiple class names to the css_classes parameter. This can be useful for creating conditions that involve crossing different style-related factors. This example shows you to combine two text alignment and two text color factors to produce four different stimulus conditions: < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} . teal # stimulus { color : teal ;} . purple # stimulus { color : purple ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ), data : { condition : jsPsych . timelineVariable ( 'condition' )} }], timeline_variables : [ { css_classes : [ 'left-align' , 'teal' ], condition : 'left-teal' }, { css_classes : [ 'right-align' , 'teal' ], condition : 'right-teal' }, { css_classes : [ 'left-align' , 'purple' ], condition : 'left-purple' }, { css_classes : [ 'right-align' , 'purple' ], condition : 'right-purple' } ] } // ... </ script > See the \"css-classes-parameter.html\" file in jsPsych's examples subfolder for more explanation and examples. Tips for working with CSS \u00b6 Your browser's developer tools contain very useful features for exploring and debugging your experiment's style and formatting. Open your browser's developer tools and click on the Element Inspector button or go to the Elements tab. Once you have selected an element on the page, you can see all of the information that can be used to select it, including: tag name, e.g., \"div\", \"p\", \"img\", \"button\" ID, if it has one class(es), if it has any You can then use this information to create a CSS selector to modify that element's style. As you can see, jsPsych adds its own IDs and classes to many elements. You can use the developer tools to determine what IDs and classes already exist for the elements that you want to modify, as you may can often just use these instead of adding your own. For instance, in the \"html-keyboard-response\" plugin, the stimulus will always be shown in a <div> with the ID \"jspsych-html-keyboard-response-stimulus\". So you can create a CSS rule that is applied to all \"html-keyboard-response\" stimuli like this: # jspsych-html-keyboard-response-stimulus { color : white ; background-color : blue ; width : 100 px ; border : 4 px solid black ; } As another example, most jsPsych buttons have the class \"jspsych-btn\", so you can use this class to change the default button styling: . jspsych-btn { padding : 20 px 20 px ; font-size : 25 px ; border-color : black ; } You can also use the developer tools to change an element's CSS and immediately see the effect that the changes will have on the page. These changes are just temporary, so you will still need to use one of methods described above to add the CSS changes to your experiment. However, making changes in the developer tools is very useful for figuring out which CSS properties to change and which values to use. This area of the developer tools also shows what styles are currently applied to the element and where those style rules are coming from. There are a few things to be aware of while debugging problems with CSS. When there are conflicting CSS rules, some CSS rules will take precedence over others . For instance, inline CSS usually takes precedence over other CSS rules, and more specific CSS selectors usually take precedence over less specific ones. When there are conflicting CSS rules that have the same level of precedence, the last rule will override any earlier rules . For that reason it's important to add your own custom stylesheet after the default jspsych.css stylesheet. See this page about CSS precedence for more information. If one CSS style rule is overridden by another one, the rule that is overridden will appear in strikethrough text in the element's \"Styles\" section. Also, if you are using an incorrect CSS property name or an invalid value, then that will show up here as an error, indicated by both strikethrough text and a little yellow warning symbol.","title":"Controlling Visual Appearance"},{"location":"overview/style/#controlling-visual-appearance","text":"Your experiment's style and formatting comes from the CSS (cascading style sheet) rules that are stored in the jspsych.css file, and the browser's defaults. There are a few ways to change the style and formatting in your experiment. The method that you choose is partly a matter of personal preference. It might also depend on whether you want the style/formatting change(s) to apply to specific trials , to the whole experiment (HTML page), or across different experiments . This section discusses the different ways of incorporating CSS into your jsPsych experiment. You can also see this page about adding CSS to web pages to learn more.","title":"Controlling Visual Appearance"},{"location":"overview/style/#inline-css","text":"Whenever you're using a parameter that accepts an HTML-formatted string, you have the option to include inline CSS. Inline CSS is a way of adding style and formatting directly into a specific HTML element using its \"style\" attribute . This is a good option for when you want to make few and/or simple style changes to an HTML trial parameter. To change an element's style using inline CSS, you can set the element's \"style\" attribute to a string that contains the CSS parameters that you want to change, along with the values that you want to use. The syntax is \" <parameter-name> : <parameter-value> ;\". In the example below, the stimulus font size is set to 30px and the text color is set to red. These changes will only be applied to this stimulus text in this specific trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:30px;color:red;\">hello world!</p>' } You can also use a dynamic parameter to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and timeline variables : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var stim = '<p style=\"font-size:30px;font-weight:bold;\">' + jsPsych . timelineVariable ( 'text' ) + '</p>' ; return stim ; } } var trial_procedure = { timeline : [ trial ], timeline_variables : [ { text : 'Welcome' }, { text : 'to' }, { text : 'the' }, { text : 'experiment!' } ] }","title":"Inline CSS"},{"location":"overview/style/#adding-css-rules","text":"You may want to add a lot of different CSS changes to your experiment, re-use the same change(s) across lots of different trials, and/or separate the style/formatting from the HTML string. In these cases, you might find it useful to create CSS rules rather than using inline CSS. Creating CSS rules is a lot like using inline CSS, except that you also need to use a CSS selector . This is because your CSS rules aren't attached to any specific HTML element (unlike inline CSS), so you need to tell the browser which element(s) the style rules should apply to. The syntax is \"css-selector { <parameter-name> : <parameter-value> ; }\". In the example below, the CSS selector \"p\" tells the browser to apply the font size change to any text that is inside of a <p> element. p { font-size : 30 px ; } You can make more specific changes using CSS rules. The specificity will depend on the CSS selectors that are used. In addition to using the tag name (e.g. \"p\"), other common CSS selectors include the element's ID or class . If you are selecting an element using it's ID, then the CSS selector needs to have a # in front of the ID, e.g. \"#stimulus\". If you are selecting elements based on their class, then you need to include a . in front of the class, e.g. \".large-text\". In the example below, the \"#stimulus\" CSS selector means that the width change will only affect elements with the \"stimulus\" ID, and the \".large-text\" CSS selector means that the font size change will only affect elements that have the \"large-text\" class. # stimulus width : 300px ; } . large-text { font-size : 200 % ; } It is possible to create even more specific CSS selectors, for instance by combining tags, IDs, and/or classes. For example, let's say that you are showing feedback text to participants, and that this text is inside of a <p> tag. You could add the ID \"correct\" to the <p> element for correct response feedback, and the ID \"incorrect\" to the <p> element for incorrect response feedback. Then you can define separate styles for correct and incorrect feedback text like this: p # incorrect { color : red ; } p # correct { color : green ; } See this page about CSS selectors for a complete reference of CSS selector patterns and their meanings.","title":"Adding CSS rules"},{"location":"overview/style/#with-style-tags","text":"You can add CSS rules to your HTML page by putting them inside of <style> tags. These rules will be applied to your whole experiment . This method can be useful for making general changes to the way that your experiment looks. In the example below, the default font size is set to 25px throughout the experiment. This will overrule the default font size of 18px that is set in the jspsych.css file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . jspsych-display-element { font-size : 25 px ; } </ style > </ head >","title":"With style tags"},{"location":"overview/style/#with-a-stylesheet","text":"CSS rules can also be applied to your experiment with a link to an external CSS file. This is the same method that is usually used to apply the style from jspsych.css to an experiment. These rules will be applied to your whole experiment . You may find it useful to use a custom stylesheet when you want to re-use the same CSS rules across multiple experiments (HTML files). This example shows how to add a custom CSS file in addition to the styles provided in jspsych.css. In this example, the custom CSS file is called \"my_experiment_style.css\" and it is located in the same directory as your HTML file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < link rel = \"stylesheet\" href = \"my_experiment_style.css\" > </ head > Below are the some example contents of an external CSS file, like the \"my_experiment_style.css\" from the example above. This CSS will (1) change the page background color to black, (2) change the default font to 25px and white, and (3) limit the width of the page content so that it can only take up to 80% of its normal width. body { background-color : black ; } . jspsych-display-element { font-size : 25 px ; color : white ; } . jspsych-content { max-width : 80 % ; } Note <style> tags are not used inside of an external CSS file.","title":"With a stylesheet"},{"location":"overview/style/#using-the-css_classes-trial-parameter","text":"CSS rules can also be applied in a trial-specific way using the css_classes parameter. This parameter will apply one or more class to the <div> element that holds all of the jsPsych page content during that specific trial. This way you can treat CSS styles just like any other trial parameter. You can use a static css_classes parameter value if you always want to apply the same CSS rules to the trial. In the 'fixation' example below, separating the style rules from the stimulus string makes the code a little bit 'cleaner', and this makes it easier to re-use the same style rules in other parts of the experiment. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . fixation { font-size : 90 px ; font-weight : bold ; color : gray ;} </ style > </ head > < script > var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 , css_classes : [ 'fixation' ] } // ... </ script > You may want the css_classes parameter to vary across trials. If so, you can turn it into a dynamic parameter or use timeline variables (see examples below). One thing to note about the css_classes parameter is that it only adds the class(es) to the jspsych-content <div> element, which is the \"parent\" element that contains all of the experiment content. Often you'll want your CSS rules to be applied to other elements inside of this jspsych-content div. Sometimes your CSS rules will be \"inherited\" by all of the other jsPsych content inside of this parent <div>. For instance, in the fixation example above, the CSS rules that change the font size, weight and color are applied to the parent <div> and automatically passed on to the stimulus text through inheritance. There are two reasons why a CSS rule like the one above for fixation may not work the way you expect: Not all CSS properties are inherited from the parent element. When a CSS property is inherited from the parent element, it will affect all elements in a given trial. In these cases, you can change your CSS selector to make it more specific: add a space after class name, then add more CSS selectors to select the specific element(s) that you want to change. Tip To find out this more specific CSS selector, you can right-click on the element and select Inspect . In the inspector window, right-click on the property corresponding to the element and copy the selector. You might need to increase the trial's trial_duration to give yourself enough time to inspect the elements on the page. See more tips for working with CSS below. In the example below, the CSS selector .left-align #stimulus selects the element with the ID \"stimulus\" that is inside of an element with the class \"left-align\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ) }], timeline_variables : [ { css_classes : [ 'left-align' ]}, { css_classes : [ 'right-align' ]} ] } // ... </ script > It's also possible to pass multiple class names to the css_classes parameter. This can be useful for creating conditions that involve crossing different style-related factors. This example shows you to combine two text alignment and two text color factors to produce four different stimulus conditions: < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} . teal # stimulus { color : teal ;} . purple # stimulus { color : purple ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ), data : { condition : jsPsych . timelineVariable ( 'condition' )} }], timeline_variables : [ { css_classes : [ 'left-align' , 'teal' ], condition : 'left-teal' }, { css_classes : [ 'right-align' , 'teal' ], condition : 'right-teal' }, { css_classes : [ 'left-align' , 'purple' ], condition : 'left-purple' }, { css_classes : [ 'right-align' , 'purple' ], condition : 'right-purple' } ] } // ... </ script > See the \"css-classes-parameter.html\" file in jsPsych's examples subfolder for more explanation and examples.","title":"Using the css_classes trial parameter"},{"location":"overview/style/#tips-for-working-with-css","text":"Your browser's developer tools contain very useful features for exploring and debugging your experiment's style and formatting. Open your browser's developer tools and click on the Element Inspector button or go to the Elements tab. Once you have selected an element on the page, you can see all of the information that can be used to select it, including: tag name, e.g., \"div\", \"p\", \"img\", \"button\" ID, if it has one class(es), if it has any You can then use this information to create a CSS selector to modify that element's style. As you can see, jsPsych adds its own IDs and classes to many elements. You can use the developer tools to determine what IDs and classes already exist for the elements that you want to modify, as you may can often just use these instead of adding your own. For instance, in the \"html-keyboard-response\" plugin, the stimulus will always be shown in a <div> with the ID \"jspsych-html-keyboard-response-stimulus\". So you can create a CSS rule that is applied to all \"html-keyboard-response\" stimuli like this: # jspsych-html-keyboard-response-stimulus { color : white ; background-color : blue ; width : 100 px ; border : 4 px solid black ; } As another example, most jsPsych buttons have the class \"jspsych-btn\", so you can use this class to change the default button styling: . jspsych-btn { padding : 20 px 20 px ; font-size : 25 px ; border-color : black ; } You can also use the developer tools to change an element's CSS and immediately see the effect that the changes will have on the page. These changes are just temporary, so you will still need to use one of methods described above to add the CSS changes to your experiment. However, making changes in the developer tools is very useful for figuring out which CSS properties to change and which values to use. This area of the developer tools also shows what styles are currently applied to the element and where those style rules are coming from. There are a few things to be aware of while debugging problems with CSS. When there are conflicting CSS rules, some CSS rules will take precedence over others . For instance, inline CSS usually takes precedence over other CSS rules, and more specific CSS selectors usually take precedence over less specific ones. When there are conflicting CSS rules that have the same level of precedence, the last rule will override any earlier rules . For that reason it's important to add your own custom stylesheet after the default jspsych.css stylesheet. See this page about CSS precedence for more information. If one CSS style rule is overridden by another one, the rule that is overridden will appear in strikethrough text in the element's \"Styles\" section. Also, if you are using an incorrect CSS property name or an invalid value, then that will show up here as an error, indicated by both strikethrough text and a little yellow warning symbol.","title":"Tips for working with CSS"},{"location":"overview/timeline/","text":"Creating an Experiment: The Timeline \u00b6 To create an experiment using jsPsych, you need to specify a timeline that describes the structure of the experiment. The timeline is an ordered set of trials. You must create the timeline before launching the experiment. Most of the code you will write for an experiment will be code to create the timeline. This page walks through the creation of timelines, including very basic examples and more advanced features. A single trial \u00b6 To create a trial, you need to create an object that describes the trial. The most important feature of this object is the type parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the html-keyboard-response plugin to display a short message, the trial object would look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Welcome to the experiment.' } The parameters for this object (e.g., stimulus ) will depend on the plugin that you choose. Each plugin defines the set of parameters that are needed to run a trial with that plugin. Visit the documentation for a plugin to learn about the parameters that you can use with that plugin. To create a timeline with the single trial and run the experiment, just embed the trial object in an array. A timeline can simply be an array of trials. var timeline = [ trial ]; jsPsych . run ( timeline ); To create and run a simple experiment like this complete the hello world tutorial . Multiple trials \u00b6 Scaling up to multiple trials is straightforward. Create an object for each trial, and add each object to the timeline array. // with lots of trials, it might be easier to add the trials // to the timeline array as they are defined. var timeline = []; var trial_1 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 1.' } timeline . push ( trial_1 ); var trial_2 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 2.' } timeline . push ( trial_2 ); var trial_3 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 3.' } timeline . push ( trial_3 ); Nested timelines \u00b6 Each object on the timeline can also have it's own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the image-keyboard-response plugin , where the only thing that changes from trial-to-trial is the image file being displayed on the screen. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' }, { stimulus : 'image3.png' } ] } In the above code, the type , prompt , and choices parameters are automatically applied to all of the objects in the timeline array. This creates three trials with the same type , prompt , and choices parameters, but different values for the stimulus parameter. You can also override the values by declaring a new value in the timeline array. In the example below, the second trial will display a different prompt message. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' , prompt : '<p>Press 1 for this trial.</p>' }, { stimulus : 'image3.png' } ] } Timelines can be nested any number of times. Timeline variables \u00b6 A common pattern in behavioral experiments is to repeat the same procedure/task many times with slightly different parameters. A procedure might be a single trial, but it also might be a series of trials. For example, a task might involve a fixation cross appearing, followed by a blank screen, followed by an image for a short duration, followed by a prompt and a text box to report on some aspect of the image. One shortcut to implement this pattern is with the nested timeline approach described in the previous section, but this only works if all the trials use the same plugin type. Timeline variables are a more general solution. With timeline variables you define the procedure once (as a timeline) and specify a set of parameters and their values for each iteration through the timeline. What follows is an example of how to use timeline variables. The simple reaction time tutorial also explains how to use timeline variables. Suppose we want to create an experiment where people see a set of faces. Perhaps this is a memory experiment and this is the phase of the experiment where the faces are being presented for the first time. In between each face, a fixation cross is displayed on the screen. Without timeline variables, we would need to add many trials to the timeline, alternating between trials showing the fixation cross and trials showing the face and name. This could be done efficiently using a loop or function to create the timeline, but timeline variables make it even easier - as well as adding extra features like sampling and randomization. Here's a basic version of the task with timeline variables. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' }, { face : 'person-2.jpg' }, { face : 'person-3.jpg' }, { face : 'person-4.jpg' } ] } In the above version, there are four separate trials defined in the timeline_variables parameter. Each trial has a variable face and a variable name . The timeline defines a procedure of showing a fixation cross for 500ms followed by the face and name for 2500ms. This procedure will repeat four times, with the first trial showing 'person-1.jpg' , the second 'person-2.jpg' , and so on. The variables are referenced within the procedure by calling the jsPsych.timelineVariable() method and passing in the name of the variable. What if we wanted to add an additional step to the task where the name is displayed prior to the face appearing? (Maybe this is one condition of an experiment investigating whether the order of name-face or face-name affects retention.) We can add another variable to our list that gives the name associated with each image. Then we can add another trial to our timeline to show the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 1000 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] } Using in a function \u00b6 Continung the example from the previous section, what if we wanted to show the name with the face, combining the two variables together? To do this, we can use a dynamic parameter (a function) to create an HTML-string that uses both variables in a single parameter. The value of the stimulus parameter will be a function that returns an HTML string that contains both the image and the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ var html = ` <img src=\" ${ jsPsych . timelineVariable ( 'face' ) } \"> <p> ${ jsPsych . timelineVariable ( 'name' ) } </p>` ; return html ; }, choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] } Random orders of trials \u00b6 If we want to randomize the order of the trials, we can set randomize_order to true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true } Sampling methods \u00b6 There are also sampling methods that can be used to select a set of trials from the timeline_variables. Sampling is declared by creating a sample parameter. The sample parameter is given an object of arguments. The type parameter in this object controls the type of sampling that is done. Valid values for type are \"with-replacement\" : Sample size items from the timeline variables with the possibility of choosing the same item multiple time. \"without-replacement\" : Sample size items from timeline variables, with each item being selected a maximum of 1 time. \"fixed-repetitons\" : Repeat each item in the timeline variables size times, in a random order. Unlike using the repetitons parameter, this method allows for consecutive trials to use the same timeline variable set. \"alternate-groups\" : Sample in an alternating order based on a declared group membership. Groups are defined by the groups parameter. This parameter takes an array of arrays, where each inner array is a group and the items in the inner array are the indices of the timeline variables in the timeline_variables array that belong to that group. \"custom\" : Write a function that returns a custom order of the timeline variables. Sampling with replacement \u00b6 This sample parameter will create 10 repetitions, sampling with replacement. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 } } Sampling with replacement, unequal probabilities \u00b6 This sample parameter will make the \"Alex\" trial three times as likely to be sampled as the others. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 , weights : [ 3 , 1 , 1 , 1 ] } } Sampling without replacement \u00b6 This sample parameter will pick three of the four possible trials to run at random. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'without-replacement' , size : 3 } } Repeating each trial a fixed number of times in a random order \u00b6 This sample parameter will create 3 repetitions of each trial, for a total of 12 trials, with a random order. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'fixed-repetitions' , size : 3 } } Alternating groups \u00b6 This sample parameter puts the \"Alex\" and \"Chad\" trials in group 1 and the \"Beth\" and \"Dave\" trials in group 2. The resulting sample of trials will follow the pattern group 1 -> group 2 -> group 1 -> group 2 . Each trial will be selected only one time. If you wanted group 2 to sometimes be first, you could set randomize_group_order: true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'alternate-groups' , groups : [[ 0 , 2 ],[ 1 , 3 ]], randomize_group_order : false } } Custom sampling function \u00b6 Any sampling method can be implemented using the custom type sampler. The order of trials will be determined by running the function supplied as fn . The function has a single parameter, t , which is an array of integers from 0 to n-1 , where n is the number of trials in the timeline_variables array. The function must return an array that specifies the order of the trials, e.g., returning [3,3,2,2,1,1,0,0] would result in the order Dave -> Dave -> Chad -> Chad -> Beth -> Beth -> Alex -> Alex . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'custom' , fn : function ( t ){ return t . reverse (); // show the trials in the reverse order } } } Repeating a set of trials \u00b6 To repeat a timeline multiple times, you can create an object (node) that contains a timeline , which is the timeline array to repeat, and repetitions , which is the number of times to repeat that timeline. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be repeated twice.' } var node = { timeline : [ trial ], repetitions : 2 } The repetitions parameter can be used alongside other node parameters, such as timeline variables, loop functions, and/or conditional functions. If you are using timeline_variables and randomize_order is true , then the order of the timeline variables will re-randomize before every repetition. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , repetitions : 3 } Looping timelines \u00b6 Any timeline can be looped using the loop_function option. The loop function must be a function that evaluates to true if the timeline should repeat, and false if the timeline should end. It receives a single parameter, named data by convention. This parameter will be the DataCollection object with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial is in a loop. Press R to repeat this trial, or C to continue.' } var loop_node = { timeline : [ trial ], loop_function : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . values ()[ 0 ]. response , 'r' )){ return true ; } else { return false ; } } } Conditional timelines \u00b6 A timeline can be skipped or not based on the evaluation of the conditional_function option. If the conditional function evaluates to true , the timeline will execute normally. If the conditional function evaluates to false then the timeline will be skipped. The conditional function is evaluated whenever jsPsych is about to run the first trial on the timeline. var jsPsych = initJsPsych (); var pre_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The next trial is in a conditional statement. Press S to skip it, or V to view it.' } var if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'You chose to view the trial. Press any key to continue.' } var if_node = { timeline : [ if_trial ], conditional_function : function (){ // get the data from the previous trial, // and check which key was pressed var data = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]; if ( jsPsych . pluginAPI . compareKeys ( data . response , 's' )){ return false ; } else { return true ; } } } var after_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is the trial after the conditional.' } jsPsych . run ([ pre_if_trial , if_node , after_if_trial ]); Timeline start and finish functions \u00b6 You can run a custom function at the start and end of a timeline node using the on_timeline_start and on_timeline_finish callback function parameters. These are functions that will run when the timeline starts and ends, respectively. var procedure = { timeline : [ trial_1 , trial_2 ], on_timeline_start : function () { console . log ( 'The trial procedure just started.' ) }, on_timeline_finish : function () { console . log ( 'The trial procedure just finished.' ) } } This works the same way with timeline variables. The on_timeline_start and on_timeline_finish functions will run when timeline variables trials start and end, respectively. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , on_timeline_start : function () { console . log ( 'First trial is starting.' ) }, on_timeline_finish : function () { console . log ( 'Last trial just finished.' ) } } When the repetititons option is used (and is greater than 1), these functions will run once per repetition of the timeline. var repetition_count = 0 ; var procedure = { timeline : [ trial_1 , trial_2 ], repetitions : 3 , on_timeline_start : function () { repetition_count ++ ; console . log ( 'Repetition number ' , repetition_count , ' has just started.' ); }, on_timeline_finish : function () { console . log ( 'Repetition number ' , repetition_count , ' has just finished.' ) } }","title":"Creating an Experiment: The Timeline"},{"location":"overview/timeline/#creating-an-experiment-the-timeline","text":"To create an experiment using jsPsych, you need to specify a timeline that describes the structure of the experiment. The timeline is an ordered set of trials. You must create the timeline before launching the experiment. Most of the code you will write for an experiment will be code to create the timeline. This page walks through the creation of timelines, including very basic examples and more advanced features.","title":"Creating an Experiment: The Timeline"},{"location":"overview/timeline/#a-single-trial","text":"To create a trial, you need to create an object that describes the trial. The most important feature of this object is the type parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the html-keyboard-response plugin to display a short message, the trial object would look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Welcome to the experiment.' } The parameters for this object (e.g., stimulus ) will depend on the plugin that you choose. Each plugin defines the set of parameters that are needed to run a trial with that plugin. Visit the documentation for a plugin to learn about the parameters that you can use with that plugin. To create a timeline with the single trial and run the experiment, just embed the trial object in an array. A timeline can simply be an array of trials. var timeline = [ trial ]; jsPsych . run ( timeline ); To create and run a simple experiment like this complete the hello world tutorial .","title":"A single trial"},{"location":"overview/timeline/#multiple-trials","text":"Scaling up to multiple trials is straightforward. Create an object for each trial, and add each object to the timeline array. // with lots of trials, it might be easier to add the trials // to the timeline array as they are defined. var timeline = []; var trial_1 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 1.' } timeline . push ( trial_1 ); var trial_2 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 2.' } timeline . push ( trial_2 ); var trial_3 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 3.' } timeline . push ( trial_3 );","title":"Multiple trials"},{"location":"overview/timeline/#nested-timelines","text":"Each object on the timeline can also have it's own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the image-keyboard-response plugin , where the only thing that changes from trial-to-trial is the image file being displayed on the screen. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' }, { stimulus : 'image3.png' } ] } In the above code, the type , prompt , and choices parameters are automatically applied to all of the objects in the timeline array. This creates three trials with the same type , prompt , and choices parameters, but different values for the stimulus parameter. You can also override the values by declaring a new value in the timeline array. In the example below, the second trial will display a different prompt message. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' , prompt : '<p>Press 1 for this trial.</p>' }, { stimulus : 'image3.png' } ] } Timelines can be nested any number of times.","title":"Nested timelines"},{"location":"overview/timeline/#timeline-variables","text":"A common pattern in behavioral experiments is to repeat the same procedure/task many times with slightly different parameters. A procedure might be a single trial, but it also might be a series of trials. For example, a task might involve a fixation cross appearing, followed by a blank screen, followed by an image for a short duration, followed by a prompt and a text box to report on some aspect of the image. One shortcut to implement this pattern is with the nested timeline approach described in the previous section, but this only works if all the trials use the same plugin type. Timeline variables are a more general solution. With timeline variables you define the procedure once (as a timeline) and specify a set of parameters and their values for each iteration through the timeline. What follows is an example of how to use timeline variables. The simple reaction time tutorial also explains how to use timeline variables. Suppose we want to create an experiment where people see a set of faces. Perhaps this is a memory experiment and this is the phase of the experiment where the faces are being presented for the first time. In between each face, a fixation cross is displayed on the screen. Without timeline variables, we would need to add many trials to the timeline, alternating between trials showing the fixation cross and trials showing the face and name. This could be done efficiently using a loop or function to create the timeline, but timeline variables make it even easier - as well as adding extra features like sampling and randomization. Here's a basic version of the task with timeline variables. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' }, { face : 'person-2.jpg' }, { face : 'person-3.jpg' }, { face : 'person-4.jpg' } ] } In the above version, there are four separate trials defined in the timeline_variables parameter. Each trial has a variable face and a variable name . The timeline defines a procedure of showing a fixation cross for 500ms followed by the face and name for 2500ms. This procedure will repeat four times, with the first trial showing 'person-1.jpg' , the second 'person-2.jpg' , and so on. The variables are referenced within the procedure by calling the jsPsych.timelineVariable() method and passing in the name of the variable. What if we wanted to add an additional step to the task where the name is displayed prior to the face appearing? (Maybe this is one condition of an experiment investigating whether the order of name-face or face-name affects retention.) We can add another variable to our list that gives the name associated with each image. Then we can add another trial to our timeline to show the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 1000 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] }","title":"Timeline variables"},{"location":"overview/timeline/#using-in-a-function","text":"Continung the example from the previous section, what if we wanted to show the name with the face, combining the two variables together? To do this, we can use a dynamic parameter (a function) to create an HTML-string that uses both variables in a single parameter. The value of the stimulus parameter will be a function that returns an HTML string that contains both the image and the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ var html = ` <img src=\" ${ jsPsych . timelineVariable ( 'face' ) } \"> <p> ${ jsPsych . timelineVariable ( 'name' ) } </p>` ; return html ; }, choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] }","title":"Using in a function"},{"location":"overview/timeline/#random-orders-of-trials","text":"If we want to randomize the order of the trials, we can set randomize_order to true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true }","title":"Random orders of trials"},{"location":"overview/timeline/#sampling-methods","text":"There are also sampling methods that can be used to select a set of trials from the timeline_variables. Sampling is declared by creating a sample parameter. The sample parameter is given an object of arguments. The type parameter in this object controls the type of sampling that is done. Valid values for type are \"with-replacement\" : Sample size items from the timeline variables with the possibility of choosing the same item multiple time. \"without-replacement\" : Sample size items from timeline variables, with each item being selected a maximum of 1 time. \"fixed-repetitons\" : Repeat each item in the timeline variables size times, in a random order. Unlike using the repetitons parameter, this method allows for consecutive trials to use the same timeline variable set. \"alternate-groups\" : Sample in an alternating order based on a declared group membership. Groups are defined by the groups parameter. This parameter takes an array of arrays, where each inner array is a group and the items in the inner array are the indices of the timeline variables in the timeline_variables array that belong to that group. \"custom\" : Write a function that returns a custom order of the timeline variables.","title":"Sampling methods"},{"location":"overview/timeline/#sampling-with-replacement","text":"This sample parameter will create 10 repetitions, sampling with replacement. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 } }","title":"Sampling with replacement"},{"location":"overview/timeline/#sampling-with-replacement-unequal-probabilities","text":"This sample parameter will make the \"Alex\" trial three times as likely to be sampled as the others. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 , weights : [ 3 , 1 , 1 , 1 ] } }","title":"Sampling with replacement, unequal probabilities"},{"location":"overview/timeline/#sampling-without-replacement","text":"This sample parameter will pick three of the four possible trials to run at random. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'without-replacement' , size : 3 } }","title":"Sampling without replacement"},{"location":"overview/timeline/#repeating-each-trial-a-fixed-number-of-times-in-a-random-order","text":"This sample parameter will create 3 repetitions of each trial, for a total of 12 trials, with a random order. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'fixed-repetitions' , size : 3 } }","title":"Repeating each trial a fixed number of times in a random order"},{"location":"overview/timeline/#alternating-groups","text":"This sample parameter puts the \"Alex\" and \"Chad\" trials in group 1 and the \"Beth\" and \"Dave\" trials in group 2. The resulting sample of trials will follow the pattern group 1 -> group 2 -> group 1 -> group 2 . Each trial will be selected only one time. If you wanted group 2 to sometimes be first, you could set randomize_group_order: true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'alternate-groups' , groups : [[ 0 , 2 ],[ 1 , 3 ]], randomize_group_order : false } }","title":"Alternating groups"},{"location":"overview/timeline/#custom-sampling-function","text":"Any sampling method can be implemented using the custom type sampler. The order of trials will be determined by running the function supplied as fn . The function has a single parameter, t , which is an array of integers from 0 to n-1 , where n is the number of trials in the timeline_variables array. The function must return an array that specifies the order of the trials, e.g., returning [3,3,2,2,1,1,0,0] would result in the order Dave -> Dave -> Chad -> Chad -> Beth -> Beth -> Alex -> Alex . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'custom' , fn : function ( t ){ return t . reverse (); // show the trials in the reverse order } } }","title":"Custom sampling function"},{"location":"overview/timeline/#repeating-a-set-of-trials","text":"To repeat a timeline multiple times, you can create an object (node) that contains a timeline , which is the timeline array to repeat, and repetitions , which is the number of times to repeat that timeline. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be repeated twice.' } var node = { timeline : [ trial ], repetitions : 2 } The repetitions parameter can be used alongside other node parameters, such as timeline variables, loop functions, and/or conditional functions. If you are using timeline_variables and randomize_order is true , then the order of the timeline variables will re-randomize before every repetition. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , repetitions : 3 }","title":"Repeating a set of trials"},{"location":"overview/timeline/#looping-timelines","text":"Any timeline can be looped using the loop_function option. The loop function must be a function that evaluates to true if the timeline should repeat, and false if the timeline should end. It receives a single parameter, named data by convention. This parameter will be the DataCollection object with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial is in a loop. Press R to repeat this trial, or C to continue.' } var loop_node = { timeline : [ trial ], loop_function : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . values ()[ 0 ]. response , 'r' )){ return true ; } else { return false ; } } }","title":"Looping timelines"},{"location":"overview/timeline/#conditional-timelines","text":"A timeline can be skipped or not based on the evaluation of the conditional_function option. If the conditional function evaluates to true , the timeline will execute normally. If the conditional function evaluates to false then the timeline will be skipped. The conditional function is evaluated whenever jsPsych is about to run the first trial on the timeline. var jsPsych = initJsPsych (); var pre_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The next trial is in a conditional statement. Press S to skip it, or V to view it.' } var if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'You chose to view the trial. Press any key to continue.' } var if_node = { timeline : [ if_trial ], conditional_function : function (){ // get the data from the previous trial, // and check which key was pressed var data = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]; if ( jsPsych . pluginAPI . compareKeys ( data . response , 's' )){ return false ; } else { return true ; } } } var after_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is the trial after the conditional.' } jsPsych . run ([ pre_if_trial , if_node , after_if_trial ]);","title":"Conditional timelines"},{"location":"overview/timeline/#timeline-start-and-finish-functions","text":"You can run a custom function at the start and end of a timeline node using the on_timeline_start and on_timeline_finish callback function parameters. These are functions that will run when the timeline starts and ends, respectively. var procedure = { timeline : [ trial_1 , trial_2 ], on_timeline_start : function () { console . log ( 'The trial procedure just started.' ) }, on_timeline_finish : function () { console . log ( 'The trial procedure just finished.' ) } } This works the same way with timeline variables. The on_timeline_start and on_timeline_finish functions will run when timeline variables trials start and end, respectively. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , on_timeline_start : function () { console . log ( 'First trial is starting.' ) }, on_timeline_finish : function () { console . log ( 'Last trial just finished.' ) } } When the repetititons option is used (and is greater than 1), these functions will run once per repetition of the timeline. var repetition_count = 0 ; var procedure = { timeline : [ trial_1 , trial_2 ], repetitions : 3 , on_timeline_start : function () { repetition_count ++ ; console . log ( 'Repetition number ' , repetition_count , ' has just started.' ); }, on_timeline_finish : function () { console . log ( 'Repetition number ' , repetition_count , ' has just finished.' ) } }","title":"Timeline start and finish functions"},{"location":"overview/timing-accuracy/","text":"Timing accuracy \u00b6 Wondering if jsPsych can be used for research that depends on accurate display times or response time measurement? For most purposes, the answer is yes. Display timing is somewhat less accurate in JavaScript than in standard experimental software that runs on a desktop. Desktop software can have closer integration with the graphics devices of the machine than JavaScript currently permits. If a one or two frame (17-33ms) difference in display timing matters for your experiment, then you'll want to be careful with JavaScript-based experiments. It is possible to achieve this level of control in JavaScript, but it often requires code that is more tailored to your experiment and some restrictions about which browsers can be used to run the experiment. Tip If you are hoping to run an experiment with the best timing that jsPsych can offer, we currently recommend using the jspsych-psychophysics plugin developed by Daiichiro Kuroki . Kuroki, D. (2021). A new jsPsych plugin for psychophysics, providing accurate display duration and stimulus onset asynchrony. Behavior Research Methods , 53 , 301\u2013310. https://doi.org/10.3758/s13428-020-01445-w Response time measurements in jsPsych (and JavaScript in general) are comparable to those taken in standard lab software like Psychophysics Toolbox and E-Prime. Response times measured in JavaScript tend to be a little bit longer (10-40ms), but have similar variance. References \u00b6 See the following papers for extensive work on display and response timing in browser-based experiments. Note that browsers are updating frequently and the JavaScript language specification is also changing. It's possible that the results from these papers do not apply to current versions of web browsers. Future updates to JavaScript APIs will likely improve the ability of online experiments to provide more accurate display timing and response time measurement. Bridges, D., Pitiot, A., MacAskill, M. R., & Peirce, J. W. (2020). The timing mega-study: Comparing a range of experiment generators, both lab-based and online. PeerJ, 8 , e9414. Anwyl-Irvine, A., Dalmaijer, E. S., Hodges, N., & Evershed, J. K. (2020). Realistic precision and accuracy of online experiment platforms, web browsers, and devices. Behavior Research Methods, 53, 1-19. Pronk, T., Wiers, R. W., Molenkamp, B., & Murre, J. (2020). Mental chronometry in the pocket? Timing accuracy of web applications on touchscreen and keyboard devices. Behavior Research Methods, 52 (3), 1371-1382. Pinet, S., Zielinski, C., Math\u00f4t, S. et al. (2017). Measuring sequences of keystrokes with jsPsych: Reliability of response times and interkeystroke intervals. Behavior Research Methods , 49 (3), 1177-1178. de Leeuw, J. R., & Motz, B. A. (2016). Psychophysics in a Web browser? Comparing response times collected with JavaScript and Psychophysics Toolbox in a visual search task. Behavior Research Methods , 48 (1), 1-12. Hilbig, B. E. (2016). Reaction time effects in lab- versus web-based research: Experimental evidence. Behavior Research Methods , 48 (4), 1718-1724. Reimers, S., & Stewart, N. (2015). Presentation and response time accuracy in Adobe Flash and HTML5/JavaScript Web experiments. Behavior Research Methods , 47 (2), 309-327.","title":"Timing Accuracy"},{"location":"overview/timing-accuracy/#timing-accuracy","text":"Wondering if jsPsych can be used for research that depends on accurate display times or response time measurement? For most purposes, the answer is yes. Display timing is somewhat less accurate in JavaScript than in standard experimental software that runs on a desktop. Desktop software can have closer integration with the graphics devices of the machine than JavaScript currently permits. If a one or two frame (17-33ms) difference in display timing matters for your experiment, then you'll want to be careful with JavaScript-based experiments. It is possible to achieve this level of control in JavaScript, but it often requires code that is more tailored to your experiment and some restrictions about which browsers can be used to run the experiment. Tip If you are hoping to run an experiment with the best timing that jsPsych can offer, we currently recommend using the jspsych-psychophysics plugin developed by Daiichiro Kuroki . Kuroki, D. (2021). A new jsPsych plugin for psychophysics, providing accurate display duration and stimulus onset asynchrony. Behavior Research Methods , 53 , 301\u2013310. https://doi.org/10.3758/s13428-020-01445-w Response time measurements in jsPsych (and JavaScript in general) are comparable to those taken in standard lab software like Psychophysics Toolbox and E-Prime. Response times measured in JavaScript tend to be a little bit longer (10-40ms), but have similar variance.","title":"Timing accuracy"},{"location":"overview/timing-accuracy/#references","text":"See the following papers for extensive work on display and response timing in browser-based experiments. Note that browsers are updating frequently and the JavaScript language specification is also changing. It's possible that the results from these papers do not apply to current versions of web browsers. Future updates to JavaScript APIs will likely improve the ability of online experiments to provide more accurate display timing and response time measurement. Bridges, D., Pitiot, A., MacAskill, M. R., & Peirce, J. W. (2020). The timing mega-study: Comparing a range of experiment generators, both lab-based and online. PeerJ, 8 , e9414. Anwyl-Irvine, A., Dalmaijer, E. S., Hodges, N., & Evershed, J. K. (2020). Realistic precision and accuracy of online experiment platforms, web browsers, and devices. Behavior Research Methods, 53, 1-19. Pronk, T., Wiers, R. W., Molenkamp, B., & Murre, J. (2020). Mental chronometry in the pocket? Timing accuracy of web applications on touchscreen and keyboard devices. Behavior Research Methods, 52 (3), 1371-1382. Pinet, S., Zielinski, C., Math\u00f4t, S. et al. (2017). Measuring sequences of keystrokes with jsPsych: Reliability of response times and interkeystroke intervals. Behavior Research Methods , 49 (3), 1177-1178. de Leeuw, J. R., & Motz, B. A. (2016). Psychophysics in a Web browser? Comparing response times collected with JavaScript and Psychophysics Toolbox in a visual search task. Behavior Research Methods , 48 (1), 1-12. Hilbig, B. E. (2016). Reaction time effects in lab- versus web-based research: Experimental evidence. Behavior Research Methods , 48 (4), 1718-1724. Reimers, S., & Stewart, N. (2015). Presentation and response time accuracy in Adobe Flash and HTML5/JavaScript Web experiments. Behavior Research Methods , 47 (2), 309-327.","title":"References"},{"location":"plugins/animation/","text":"animation \u00b6 Current version: 1.1.2. See version history . This plugin displays a sequence of images at a fixed frame rate. The sequence can be looped a specified number of times. The participant is free to respond at any point during the animation, and the time of the response is recorded. Parameters \u00b6 In addition to the 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. 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 in milliseconds. 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value animation_sequence array An array, where each element is an object that represents a stimulus in the animation sequence. Each object has a stimulus property, which is the image that was displayed, and a time property, which is the time in ms, measured from when the sequence began, that the stimulus was displayed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. response array An array, where each element is an object representing a response given by the participant. Each object has a stimulus property, indicating which image was displayed when the key was pressed, an rt property, indicating the time of the key press relative to the start of the animation, and a key_press property, indicating which key was pressed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-animation import animation from '@jspsych/plugin-animation' ; Examples \u00b6 Displaying a single sequence multiple times Code Demo var animation_sequence = [ \"img/happy_face_1.jpg\" , \"img/happy_face_2.jpg\" , \"img/happy_face_3.jpg\" , \"img/happy_face_4.jpg\" ]; var animation_trial = { type : jsPsychAnimation , stimuli : animation_sequence , sequence_reps : 3 , frame_time : 300 , prompt : '<p>Watch the faces.</p>' , }; Open demo in new tab","title":"animation"},{"location":"plugins/animation/#animation","text":"Current version: 1.1.2. See version history . This plugin displays a sequence of images at a fixed frame rate. The sequence can be looped a specified number of times. The participant is free to respond at any point during the animation, and the time of the response is recorded.","title":"animation"},{"location":"plugins/animation/#parameters","text":"In addition to the 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. 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 in milliseconds. 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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.","title":"Parameters"},{"location":"plugins/animation/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value animation_sequence array An array, where each element is an object that represents a stimulus in the animation sequence. Each object has a stimulus property, which is the image that was displayed, and a time property, which is the time in ms, measured from when the sequence began, that the stimulus was displayed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. response array An array, where each element is an object representing a response given by the participant. Each object has a stimulus property, indicating which image was displayed when the key was pressed, an rt property, indicating the time of the key press relative to the start of the animation, and a key_press property, indicating which key was pressed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/animation/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-animation import animation from '@jspsych/plugin-animation' ;","title":"Install"},{"location":"plugins/animation/#examples","text":"Displaying a single sequence multiple times Code Demo var animation_sequence = [ \"img/happy_face_1.jpg\" , \"img/happy_face_2.jpg\" , \"img/happy_face_3.jpg\" , \"img/happy_face_4.jpg\" ]; var animation_trial = { type : jsPsychAnimation , stimuli : animation_sequence , sequence_reps : 3 , frame_time : 300 , prompt : '<p>Watch the faces.</p>' , }; Open demo in new tab","title":"Examples"},{"location":"plugins/audio-button-response/","text":"audio-button-response \u00b6 Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with a button click. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the audio has finished playing. Parameters \u00b6 In addition to the 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-button-response import audioButtonResponse from '@jspsych/plugin-audio-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/tone.mp3' , choices : [ 'Low' , 'High' ], prompt : \"<p>Is the pitch high or low?</p>\" }; Open demo in new tab Using custom button HTML to use images as buttons Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/roar.mp3' , choices : [ 'lion.png' , 'elephant.png' , 'monkey.png' ], prompt : \"<p>Which animal made the sound?</p>\" , button_html : '<img src=\"%choice%\" />' }; Open demo in new tab Note : if you want the images to look more like jsPsych buttons, i.e. with borders and different styles for hover/active/disabled states, then you can also embed the image element inside the default button_html string: button_html : '<button class=\"jspsych-btn\"><img src=\"%choice%\" /></button>'","title":"audio-button-response"},{"location":"plugins/audio-button-response/#audio-button-response","text":"Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with a button click. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the audio has finished playing.","title":"audio-button-response"},{"location":"plugins/audio-button-response/#parameters","text":"In addition to the 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on.","title":"Data Generated"},{"location":"plugins/audio-button-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-button-response import audioButtonResponse from '@jspsych/plugin-audio-button-response' ;","title":"Install"},{"location":"plugins/audio-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/tone.mp3' , choices : [ 'Low' , 'High' ], prompt : \"<p>Is the pitch high or low?</p>\" }; Open demo in new tab Using custom button HTML to use images as buttons Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/roar.mp3' , choices : [ 'lion.png' , 'elephant.png' , 'monkey.png' ], prompt : \"<p>Which animal made the sound?</p>\" , button_html : '<img src=\"%choice%\" />' }; Open demo in new tab Note : if you want the images to look more like jsPsych buttons, i.e. with borders and different styles for hover/active/disabled states, then you can also embed the image element inside the default button_html string: button_html : '<button class=\"jspsych-btn\"><img src=\"%choice%\" /></button>'","title":"Examples"},{"location":"plugins/audio-keyboard-response/","text":"audio-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with the keyboard. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the audio has finished playing. Parameters \u00b6 In addition to the 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant 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. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-keyboard-response import audioKeyboardResponse from '@jspsych/plugin-audio-keyboard-response' ; Examples \u00b6 Trial continues until participant gives a response Code Demo var trial = { type : jsPsychAudioKeyboardResponse , 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 : true }; Open demo in new tab Play a sound with no user response; trial ends after sound plays Code Demo var trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'sound/tone.mp3' , choices : \"NO_KEYS\" , trial_ends_after_audio : true }; Open demo in new tab","title":"audio-keyboard-response"},{"location":"plugins/audio-keyboard-response/#audio-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with the keyboard. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the audio has finished playing.","title":"audio-keyboard-response"},{"location":"plugins/audio-keyboard-response/#parameters","text":"In addition to the 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant 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.","title":"Data Generated"},{"location":"plugins/audio-keyboard-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-keyboard-response import audioKeyboardResponse from '@jspsych/plugin-audio-keyboard-response' ;","title":"Install"},{"location":"plugins/audio-keyboard-response/#examples","text":"Trial continues until participant gives a response Code Demo var trial = { type : jsPsychAudioKeyboardResponse , 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 : true }; Open demo in new tab Play a sound with no user response; trial ends after sound plays Code Demo var trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'sound/tone.mp3' , choices : \"NO_KEYS\" , trial_ends_after_audio : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/audio-slider-response/","text":"audio-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin plays an audio file and allows the participant to respond by dragging a slider. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the audio has finished playing. Parameters \u00b6 In addition to the 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 participant 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. stimulus string The path of the audio file that was played. slider_start numeric The starting value of the slider. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-slider-response import audioSliderResponse from '@jspsych/plugin-audio-slider-response' ; Examples \u00b6 A simple rating scale Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' } Open demo in new tab No response allowed until audio finishes; participant must interact with slider to continue Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' , response_allowed_while_playing : false , require_movement : true } Open demo in new tab","title":"audio-slider-response"},{"location":"plugins/audio-slider-response/#audio-slider-response","text":"Current version: 1.1.2. See version history . This plugin plays an audio file and allows the participant to respond by dragging a slider. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the audio has finished playing.","title":"audio-slider-response"},{"location":"plugins/audio-slider-response/#parameters","text":"In addition to the 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 participant 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. stimulus string The path of the audio file that was played. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/audio-slider-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-slider-response import audioSliderResponse from '@jspsych/plugin-audio-slider-response' ;","title":"Install"},{"location":"plugins/audio-slider-response/#examples","text":"A simple rating scale Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' } Open demo in new tab No response allowed until audio finishes; participant must interact with slider to continue Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' , response_allowed_while_playing : false , require_movement : true } Open demo in new tab","title":"Examples"},{"location":"plugins/browser-check/","text":"browser-check \u00b6 Current version: 1.0.2. See version history . This plugin measures and records various features of the participant's browser and can end the experiment if defined inclusion criteria are not met. The plugin currently can record the following features: The width and height of the browser window in pixels. The type of browser used (e.g., Chrome, Firefox, Edge, etc.) and the version number of the browser.* Whether the participant is using a mobile device.* The operating system.* Support for the WebAudio API. Support for the Fullscreen API, e.g., through the fullscreen plugin . The display refresh rate in frames per second. Whether the device has a webcam and microphone. Note that this only reveals whether a webcam/microphone exists. The participant still needs to grant permission in order for the experiment to use these devices. Warning Features with an * are recorded by parsing the user agent string . This method is accurate most of the time, but is not guaranteed to be correct. The plugin uses the detect-browser package to perform user agent parsing. You can find a list of supported browsers and OSes in the source file . The plugin begins by measuring the set of features requested. An inclusion function is evaluated to see if the paricipant passes the inclusion criteria. If they do, then the trial ends and the experiment continues. If they do not, then the experiment ends immediately. If a minimum width and/or minimum height is desired, the plugin will optionally display a message to participants whose browser windows are too small to give them an opportunity to make the window larger if possible. See the examples below for more guidance. Parameters \u00b6 In addition to the 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 features array of strings [\"width\", \"height\", \"webaudio\", \"browser\", \"browser_version\", \"mobile\", \"os\", \"fullscreen\", \"vsync_rate\", \"webcam\", \"microphone\"] The list of browser features to record. The default value includes all of the available options. skip_features array of strings [] Any features listed here will be skipped, even if they appear in features . Use this when you want to run most of the defaults. vsync_frame_count int 60 The number of frames to sample when measuring the display refresh rate ( \"vsync_rate\" ). Increasing the number will potenially improve the stability of the estimate at the cost of increasing the amount of time the plugin takes during this test. On most devices, 60 frames takes about 1 second to measure. allow_window_resize bool true Whether to allow the participant to resize the browser window if the window is smaller than minimum_width and/or minimum_height . If false , then the minimum_width and minimum_height parameters are ignored and you can validate the size in the inclusion_function . minimum_height int 0 If allow_window_resize is true , then this is the minimum height of the window (in pixels) that must be met before continuing. minimum_width int 0 If allow_window_resize is true , then this is the minimum width of the window (in pixels) that must be met before continuing. window_resize_message string see description The message that will be displayed during the interactive resize when allow_window_resize is true and the window is too small. If the message contains HTML elements with the special IDs browser-check-min-width , browser-check-min-height , browser-check-actual-height , and/or browser-check-actual-width , then the contents of those elements will be dynamically updated to reflect the minimum_width , minimum_height and measured width and height of the browser. The default message is: <p>Your browser window is too small to complete this experiment. Please maximize the size of your browser window. If your browser window is already maximized, you will not be able to complete this experiment.</p><p>The minimum window width is <span id=\"browser-check-min-width\"></span> px.</p><p>Your current window width is <span id=\"browser-check-actual-width\"></span> px.</p><p>The minimum window height is <span id=\"browser-check-min-height\"></span> px.</p><p>Your current window height is <span id=\"browser-check-actual-height\"></span> px.</p> . resize_fail_button_text string \"I cannot make the window any larger\" During the interactive resize, a button with this text will be displayed below the window_resize_message for the participant to click if the window cannot meet the minimum size needed. When the button is clicked, the experiment will end and exclusion_message will be displayed. inclusion_function function () => { return true; } A function that evaluates to true if the browser meets all of the inclusion criteria for the experiment, and false otherwise. The first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. exclusion_message function () => { return <p>Your browser does not meet the requirements to participate in this experiment.</p> } A function that returns the message to display if inclusion_function evaluates to false or if the participant clicks on the resize fail button during the interactive resize. In order to allow customization of the message, the first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value width int The width of the browser window in pixels. If interactive resizing happens, this is the width after resizing. height int The height of the browser window in pixels. If interactive resizing happens, this is the height after resizing. browser string The browser used. browser_version string The version number of the browser. os string The operating system used. mobile bool Whether the browser is a mobile device. webaudio bool Whether the browser supports the WebAudio API. fullscreen bool Whether the browser supports the Fullscreen API. vsync_rate number An estimate of the refresh rate of the screen, in frames per second. webcam bool Whether there is a webcam device available. Note that the participant still must grant permission to access the device before it can be used. microphone bool Whether there is an audio input device available. Note that the participant still must grant permission to access the device before it can be used. Note that all of these values are only recorded when the corresponding key is included in the features parameter for the trial. Simulation Mode \u00b6 In simulation mode the plugin will report the actual features of the browser, with the exception of vsync_rate , which is always 60. In data-only mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the reported width and height will be equal to minimum_width and minimum_height , as if the participant resized the browser to meet the specifications. In visual mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the experiment will wait for 3 seconds before clicking the resize fail button. During this time, you can adjust the window if you would like to. As with all simulated plugins, you can override the default (actual) data with fake data using simulation_options . This allows you to test your exclusion criteria by simulating other configurations. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-browser-check@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-browser-check.js\" >< /script> Using NPM: npm install @jspsych/plugin-browser-check import browserCheck from '@jspsych/plugin-browser-check' ; Examples \u00b6 Recording all of the available features, no exclusions Code Demo var trial = { type : jsPsychBrowserCheck }; Open demo in new tab Using the inclusion function to mandate the use of Chrome or Firefox as the browser Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return [ 'chrome' , 'firefox' ]. includes ( data . browser ); }, exclusion_message : `<p>You must use Chrome or Firefox to complete this experiment.</p>` }; Open demo in new tab Setting a minimum window height & width, with the option to resize the window Code Demo var trial = { type : jsPsychBrowserCheck , minimum_width : 1000 , minimum_height : 600 }; This demo only works in a resizable window. Please open it in new tab Open demo in new tab Custom exclusion message based on measured features Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return data . browser == 'chrome' && data . mobile === false }, exclusion_message : ( data ) => { if ( data . mobile ){ return '<p>You must use a desktop/laptop computer to participate in this experiment.</p>' ; } else if ( data . browser !== 'chrome' ){ return '<p>You must use Chrome as your browser to complete this experiment.</p>' } } }; Open demo in new tab","title":"browser-check"},{"location":"plugins/browser-check/#browser-check","text":"Current version: 1.0.2. See version history . This plugin measures and records various features of the participant's browser and can end the experiment if defined inclusion criteria are not met. The plugin currently can record the following features: The width and height of the browser window in pixels. The type of browser used (e.g., Chrome, Firefox, Edge, etc.) and the version number of the browser.* Whether the participant is using a mobile device.* The operating system.* Support for the WebAudio API. Support for the Fullscreen API, e.g., through the fullscreen plugin . The display refresh rate in frames per second. Whether the device has a webcam and microphone. Note that this only reveals whether a webcam/microphone exists. The participant still needs to grant permission in order for the experiment to use these devices. Warning Features with an * are recorded by parsing the user agent string . This method is accurate most of the time, but is not guaranteed to be correct. The plugin uses the detect-browser package to perform user agent parsing. You can find a list of supported browsers and OSes in the source file . The plugin begins by measuring the set of features requested. An inclusion function is evaluated to see if the paricipant passes the inclusion criteria. If they do, then the trial ends and the experiment continues. If they do not, then the experiment ends immediately. If a minimum width and/or minimum height is desired, the plugin will optionally display a message to participants whose browser windows are too small to give them an opportunity to make the window larger if possible. See the examples below for more guidance.","title":"browser-check"},{"location":"plugins/browser-check/#parameters","text":"In addition to the 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 features array of strings [\"width\", \"height\", \"webaudio\", \"browser\", \"browser_version\", \"mobile\", \"os\", \"fullscreen\", \"vsync_rate\", \"webcam\", \"microphone\"] The list of browser features to record. The default value includes all of the available options. skip_features array of strings [] Any features listed here will be skipped, even if they appear in features . Use this when you want to run most of the defaults. vsync_frame_count int 60 The number of frames to sample when measuring the display refresh rate ( \"vsync_rate\" ). Increasing the number will potenially improve the stability of the estimate at the cost of increasing the amount of time the plugin takes during this test. On most devices, 60 frames takes about 1 second to measure. allow_window_resize bool true Whether to allow the participant to resize the browser window if the window is smaller than minimum_width and/or minimum_height . If false , then the minimum_width and minimum_height parameters are ignored and you can validate the size in the inclusion_function . minimum_height int 0 If allow_window_resize is true , then this is the minimum height of the window (in pixels) that must be met before continuing. minimum_width int 0 If allow_window_resize is true , then this is the minimum width of the window (in pixels) that must be met before continuing. window_resize_message string see description The message that will be displayed during the interactive resize when allow_window_resize is true and the window is too small. If the message contains HTML elements with the special IDs browser-check-min-width , browser-check-min-height , browser-check-actual-height , and/or browser-check-actual-width , then the contents of those elements will be dynamically updated to reflect the minimum_width , minimum_height and measured width and height of the browser. The default message is: <p>Your browser window is too small to complete this experiment. Please maximize the size of your browser window. If your browser window is already maximized, you will not be able to complete this experiment.</p><p>The minimum window width is <span id=\"browser-check-min-width\"></span> px.</p><p>Your current window width is <span id=\"browser-check-actual-width\"></span> px.</p><p>The minimum window height is <span id=\"browser-check-min-height\"></span> px.</p><p>Your current window height is <span id=\"browser-check-actual-height\"></span> px.</p> . resize_fail_button_text string \"I cannot make the window any larger\" During the interactive resize, a button with this text will be displayed below the window_resize_message for the participant to click if the window cannot meet the minimum size needed. When the button is clicked, the experiment will end and exclusion_message will be displayed. inclusion_function function () => { return true; } A function that evaluates to true if the browser meets all of the inclusion criteria for the experiment, and false otherwise. The first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. exclusion_message function () => { return <p>Your browser does not meet the requirements to participate in this experiment.</p> } A function that returns the message to display if inclusion_function evaluates to false or if the participant clicks on the resize fail button during the interactive resize. In order to allow customization of the message, the first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below.","title":"Parameters"},{"location":"plugins/browser-check/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value width int The width of the browser window in pixels. If interactive resizing happens, this is the width after resizing. height int The height of the browser window in pixels. If interactive resizing happens, this is the height after resizing. browser string The browser used. browser_version string The version number of the browser. os string The operating system used. mobile bool Whether the browser is a mobile device. webaudio bool Whether the browser supports the WebAudio API. fullscreen bool Whether the browser supports the Fullscreen API. vsync_rate number An estimate of the refresh rate of the screen, in frames per second. webcam bool Whether there is a webcam device available. Note that the participant still must grant permission to access the device before it can be used. microphone bool Whether there is an audio input device available. Note that the participant still must grant permission to access the device before it can be used. Note that all of these values are only recorded when the corresponding key is included in the features parameter for the trial.","title":"Data Generated"},{"location":"plugins/browser-check/#simulation-mode","text":"In simulation mode the plugin will report the actual features of the browser, with the exception of vsync_rate , which is always 60. In data-only mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the reported width and height will be equal to minimum_width and minimum_height , as if the participant resized the browser to meet the specifications. In visual mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the experiment will wait for 3 seconds before clicking the resize fail button. During this time, you can adjust the window if you would like to. As with all simulated plugins, you can override the default (actual) data with fake data using simulation_options . This allows you to test your exclusion criteria by simulating other configurations.","title":"Simulation Mode"},{"location":"plugins/browser-check/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-browser-check@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-browser-check.js\" >< /script> Using NPM: npm install @jspsych/plugin-browser-check import browserCheck from '@jspsych/plugin-browser-check' ;","title":"Install"},{"location":"plugins/browser-check/#examples","text":"Recording all of the available features, no exclusions Code Demo var trial = { type : jsPsychBrowserCheck }; Open demo in new tab Using the inclusion function to mandate the use of Chrome or Firefox as the browser Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return [ 'chrome' , 'firefox' ]. includes ( data . browser ); }, exclusion_message : `<p>You must use Chrome or Firefox to complete this experiment.</p>` }; Open demo in new tab Setting a minimum window height & width, with the option to resize the window Code Demo var trial = { type : jsPsychBrowserCheck , minimum_width : 1000 , minimum_height : 600 }; This demo only works in a resizable window. Please open it in new tab Open demo in new tab Custom exclusion message based on measured features Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return data . browser == 'chrome' && data . mobile === false }, exclusion_message : ( data ) => { if ( data . mobile ){ return '<p>You must use a desktop/laptop computer to participate in this experiment.</p>' ; } else if ( data . browser !== 'chrome' ){ return '<p>You must use Chrome as your browser to complete this experiment.</p>' } } }; Open demo in new tab","title":"Examples"},{"location":"plugins/call-function/","text":"call-function \u00b6 Current version: 1.1.2. See version history . This plugin executes a specified function. This allows the experimenter to run arbitrary code at any point during the experiment. The function cannot take any arguments. If arguments are needed, then an anonymous function should be used to wrap the function call (see examples below). Parameters \u00b6 In addition to the 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 func function undefined The function to call. async boolean false Set to true if func is an asynchoronous function. If this is true, then the first argument passed to func will be a callback that you should call when the async operation is complete. You can pass data to the callback. See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value value any The return value of the called function. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-call-function@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-call-function.js\" >< /script> Using NPM: npm install @jspsych/plugin-call-function import callFunction from '@jspsych/plugin-call-function' ; Examples \u00b6 Calling a simple function Code Demo var myfunc = function () { return 'you called?' ; } var trial = { type : jsPsychCallFunction , func : myfunc } Open demo in new tab Using an anonymous function to pass variables Code Demo var myfunc = function ( data ){ // data contains all the experiment data so far, // so this function could implement code to write // the data to a database. console . log ( data . values ()) } var trial = { type : jsPsychCallFunction , func : function (){ myfunc ( jsPsych . data . get ()) } } Open demo in new tab Async function call: wait for data to be saved to a server Code There's no demo for this code, because it requires a server to communicate with. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // can perform async operations here like // creating an XMLHttpRequest to communicate // with a server var xhttp = new XMLHttpRequest (); xhttp . onreadystatechange = function () { if ( this . readyState == 4 && this . status == 200 ) { var response_data = xhttp . responseText ; // line below is what causes jsPsych to // continue to next trial. response_data // will be stored in jsPsych data object. done ( response_data ); } }; xhttp . open ( \"GET\" , \"path_to_server_script.php\" , true ); xhttp . send (); } } Async function call: simulate waiting for an event to finish Code Demo var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // generate a delay between 1500 and 3000 milliseconds to simulate // waiting for an event to finish after an unknown duration, // then move on with the experiment var rand_delay = ( Math . floor ( Math . random () * ( 3000 - 1500 + 1 ) + 1500 )); jsPsych . pluginAPI . setTimeout ( function () { // end the trial and save the delay duration to the data done ( rand_delay . toString () + \"ms\" ); }, rand_delay ) } }; Open demo in new tab","title":"call-function"},{"location":"plugins/call-function/#call-function","text":"Current version: 1.1.2. See version history . This plugin executes a specified function. This allows the experimenter to run arbitrary code at any point during the experiment. The function cannot take any arguments. If arguments are needed, then an anonymous function should be used to wrap the function call (see examples below).","title":"call-function"},{"location":"plugins/call-function/#parameters","text":"In addition to the 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 func function undefined The function to call. async boolean false Set to true if func is an asynchoronous function. If this is true, then the first argument passed to func will be a callback that you should call when the async operation is complete. You can pass data to the callback. See example below.","title":"Parameters"},{"location":"plugins/call-function/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value value any The return value of the called function.","title":"Data Generated"},{"location":"plugins/call-function/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-call-function@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-call-function.js\" >< /script> Using NPM: npm install @jspsych/plugin-call-function import callFunction from '@jspsych/plugin-call-function' ;","title":"Install"},{"location":"plugins/call-function/#examples","text":"Calling a simple function Code Demo var myfunc = function () { return 'you called?' ; } var trial = { type : jsPsychCallFunction , func : myfunc } Open demo in new tab Using an anonymous function to pass variables Code Demo var myfunc = function ( data ){ // data contains all the experiment data so far, // so this function could implement code to write // the data to a database. console . log ( data . values ()) } var trial = { type : jsPsychCallFunction , func : function (){ myfunc ( jsPsych . data . get ()) } } Open demo in new tab Async function call: wait for data to be saved to a server Code There's no demo for this code, because it requires a server to communicate with. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // can perform async operations here like // creating an XMLHttpRequest to communicate // with a server var xhttp = new XMLHttpRequest (); xhttp . onreadystatechange = function () { if ( this . readyState == 4 && this . status == 200 ) { var response_data = xhttp . responseText ; // line below is what causes jsPsych to // continue to next trial. response_data // will be stored in jsPsych data object. done ( response_data ); } }; xhttp . open ( \"GET\" , \"path_to_server_script.php\" , true ); xhttp . send (); } } Async function call: simulate waiting for an event to finish Code Demo var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // generate a delay between 1500 and 3000 milliseconds to simulate // waiting for an event to finish after an unknown duration, // then move on with the experiment var rand_delay = ( Math . floor ( Math . random () * ( 3000 - 1500 + 1 ) + 1500 )); jsPsych . pluginAPI . setTimeout ( function () { // end the trial and save the delay duration to the data done ( rand_delay . toString () + \"ms\" ); }, rand_delay ) } }; Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-button-response/","text":"canvas-button-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element , and record a button click response and response time. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. One or more button choices will be displayed under the canvas, and the button style can be customized using HTML formatting. Parameters \u00b6 In addition to the 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 strings [] 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 participant is supposed to take (e.g., what question to answer). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. 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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-button-response import canvasButtonResponse from '@jspsych/plugin-canvas-button-response' ; Examples \u00b6 Drawing circles based on parameters Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_1 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 100 , 'blue' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { color : 'blue' , radius : 100 } }; var circle_2 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 150 , 'green' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Larger' , 'Smaller' ], stimulus_duration : 1000 , prompt : '<p>Is this circle larger or smaller than the last one?</p>' + '<p>Stimulus will be hidden after 1 second.</p>' , data : { color : 'green' , radius : 150 } }; Open demo in new tab Using an anonymous stimulus function Code Demo var lines = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { var ctx = c . getContext ( \"2d\" ); // first line ctx . beginPath (); ctx . moveTo ( 200 , 10 ); ctx . lineTo ( 200 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumBlue' ; ctx . stroke (); // second line ctx . beginPath (); ctx . moveTo ( 20 , 100 ); ctx . lineTo ( 100 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumPurple' ; ctx . stroke (); }, canvas_size : [ 300 , 300 ], choices : [ 'Blue line' , 'Purple line' ], prompt : '<p>Which line is longer?</p>' , data : { line1_color : 'blue' , line1_length : 290 , line2_color : \"purple\" , line2_length : 170 } }; Open demo in new tab Using the canvas stimulus function with timeline variables, and recording the correctness of responses Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_procedure = { timeline : [ { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , jsPsych . timelineVariable ( 'radius' ), jsPsych . timelineVariable ( 'color' )); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { radius : jsPsych . timelineVariable ( 'radius' ), color : jsPsych . timelineVariable ( 'color' ), correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = data . response == data . correct_response ; } } ], timeline_variables : [ { radius : 80 , color : 'red' , correct_response : 0 }, { radius : 100 , color : 'green' , correct_response : 1 }, { radius : 50 , color : 'blue' , correct_response : 2 } ], randomize_order : true }; Open demo in new tab","title":"canvas-button-response"},{"location":"plugins/canvas-button-response/#canvas-button-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element , and record a button click response and response time. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. One or more button choices will be displayed under the canvas, and the button style can be customized using HTML formatting.","title":"canvas-button-response"},{"location":"plugins/canvas-button-response/#parameters","text":"In addition to the 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 strings [] 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 participant is supposed to take (e.g., what question to answer). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. 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.","title":"Data Generated"},{"location":"plugins/canvas-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-button-response import canvasButtonResponse from '@jspsych/plugin-canvas-button-response' ;","title":"Install"},{"location":"plugins/canvas-button-response/#examples","text":"Drawing circles based on parameters Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_1 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 100 , 'blue' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { color : 'blue' , radius : 100 } }; var circle_2 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 150 , 'green' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Larger' , 'Smaller' ], stimulus_duration : 1000 , prompt : '<p>Is this circle larger or smaller than the last one?</p>' + '<p>Stimulus will be hidden after 1 second.</p>' , data : { color : 'green' , radius : 150 } }; Open demo in new tab Using an anonymous stimulus function Code Demo var lines = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { var ctx = c . getContext ( \"2d\" ); // first line ctx . beginPath (); ctx . moveTo ( 200 , 10 ); ctx . lineTo ( 200 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumBlue' ; ctx . stroke (); // second line ctx . beginPath (); ctx . moveTo ( 20 , 100 ); ctx . lineTo ( 100 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumPurple' ; ctx . stroke (); }, canvas_size : [ 300 , 300 ], choices : [ 'Blue line' , 'Purple line' ], prompt : '<p>Which line is longer?</p>' , data : { line1_color : 'blue' , line1_length : 290 , line2_color : \"purple\" , line2_length : 170 } }; Open demo in new tab Using the canvas stimulus function with timeline variables, and recording the correctness of responses Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_procedure = { timeline : [ { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , jsPsych . timelineVariable ( 'radius' ), jsPsych . timelineVariable ( 'color' )); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { radius : jsPsych . timelineVariable ( 'radius' ), color : jsPsych . timelineVariable ( 'color' ), correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = data . response == data . correct_response ; } } ], timeline_variables : [ { radius : 80 , color : 'red' , correct_response : 0 }, { radius : 100 , color : 'green' , correct_response : 1 }, { radius : 50 , color : 'blue' , correct_response : 2 } ], randomize_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-keyboard-response/","text":"canvas-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and record a keyboard response. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-keyboard-response import canvasKeyboardResponse from '@jspsych/plugin-canvas-keyboard-response' ; Examples \u00b6 Draw rectangle and wait for response Code Demo function drawRect ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . rect ( 30 , 30 , 200 , 50 ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawRect , choices : [ 'e' , 'i' ], prompt : '<p>Is this a circle or a rectangle? Press \"e\" for circle and \"i\" for rectangle.</p>' , data : { shape : 'rectangle' } } Open demo in new tab Draw circle, no response allowed Code Demo function drawCirc ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . arc ( 100 , 75 , 50 , 0 , 2 * Math . PI ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawCirc , prompt : '<p>No key response is allowed.</p><p>The stimulus disappears after 3 seconds.</p>' , choices : \"NO_KEYS\" , trial_duration : 3000 , data : { shape : 'circle' , radius : 50 } } Open demo in new tab","title":"canvas-keyboard-response"},{"location":"plugins/canvas-keyboard-response/#canvas-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and record a keyboard response. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time.","title":"canvas-keyboard-response"},{"location":"plugins/canvas-keyboard-response/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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.","title":"Data Generated"},{"location":"plugins/canvas-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-keyboard-response import canvasKeyboardResponse from '@jspsych/plugin-canvas-keyboard-response' ;","title":"Install"},{"location":"plugins/canvas-keyboard-response/#examples","text":"Draw rectangle and wait for response Code Demo function drawRect ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . rect ( 30 , 30 , 200 , 50 ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawRect , choices : [ 'e' , 'i' ], prompt : '<p>Is this a circle or a rectangle? Press \"e\" for circle and \"i\" for rectangle.</p>' , data : { shape : 'rectangle' } } Open demo in new tab Draw circle, no response allowed Code Demo function drawCirc ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . arc ( 100 , 75 , 50 , 0 , 2 * Math . PI ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawCirc , prompt : '<p>No key response is allowed.</p><p>The stimulus disappears after 3 seconds.</p>' , choices : \"NO_KEYS\" , trial_duration : 3000 , data : { shape : 'circle' , radius : 50 } } Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-slider-response/","text":"canvas-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and collect a response within a range of values, which is made by dragging a slider. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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. 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 participant must click 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 participant is supposed to take (e.g., what question to answer). 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-slider-response import canvasSliderResponse from '@jspsych/plugin-canvas-slider-response' ; Examples \u00b6 Draw two squares Code Demo var colors = [ '#FF3333' , '#FF6A33' ]; function twoSquares ( c ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : twoSquares , labels : [ '0' , '10' ], canvas_size : [ 150 , 500 ], prompt : '<p>How different would you say the colors of these two squares are on a scale from 0 (the same) to 10 (completely different)</p>' , data : { color1 : colors [ 0 ], color2 : colors [ 1 ]} } Open demo in new tab Draw two squares with additional parameters Code Demo var colors ; function twoSquares ( c , colors ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : function ( c ) { colors = [ 'darkred' , 'cyan' ]; twoSquares ( c , colors ); }, labels : [ 'Exactly<br>the same' , 'Totally<br>different' ], canvas_size : [ 200 , 500 ], prompt : '<p>How different would you say the colors of these two squares are?</p>' , on_finish : function ( data ) { data . color1 = colors [ 0 ]; data . color2 = colors [ 1 ]; } }; Open demo in new tab","title":"canvas-slider-response"},{"location":"plugins/canvas-slider-response/#canvas-slider-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and collect a response within a range of values, which is made by dragging a slider. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time.","title":"canvas-slider-response"},{"location":"plugins/canvas-slider-response/#parameters","text":"In addition to the 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. 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 participant must click 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 participant is supposed to take (e.g., what question to answer). 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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.","title":"Data Generated"},{"location":"plugins/canvas-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-slider-response import canvasSliderResponse from '@jspsych/plugin-canvas-slider-response' ;","title":"Install"},{"location":"plugins/canvas-slider-response/#examples","text":"Draw two squares Code Demo var colors = [ '#FF3333' , '#FF6A33' ]; function twoSquares ( c ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : twoSquares , labels : [ '0' , '10' ], canvas_size : [ 150 , 500 ], prompt : '<p>How different would you say the colors of these two squares are on a scale from 0 (the same) to 10 (completely different)</p>' , data : { color1 : colors [ 0 ], color2 : colors [ 1 ]} } Open demo in new tab Draw two squares with additional parameters Code Demo var colors ; function twoSquares ( c , colors ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : function ( c ) { colors = [ 'darkred' , 'cyan' ]; twoSquares ( c , colors ); }, labels : [ 'Exactly<br>the same' , 'Totally<br>different' ], canvas_size : [ 200 , 500 ], prompt : '<p>How different would you say the colors of these two squares are?</p>' , on_finish : function ( data ) { data . color1 = colors [ 0 ]; data . color2 = colors [ 1 ]; } }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-animation/","text":"categorize-animation \u00b6 Current version: 1.1.2. See version history . The categorize animation plugin shows a sequence of images at a specified frame rate. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 or the end of the animation depending on the allow_response_before_complete parameter. The intention is that it can be used to provide a reminder about the action the participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array Array of stimuli displayed in the trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-animation import categorizeAnimation from '@jspsych/plugin-categorize-animation' ; Examples \u00b6 Basic example Code Demo var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ], prompt : `Press the P or Q key.` , choices : [ 'p' , 'q' ], key_answer : 'q' , }; Open demo in new tab Giving feedback with %ANS% string Code Demo var images = [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ]; var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : images , choices : [ 'p' , 'q' ], prompt : `Press the P or Q key.` , 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%.' }; Open demo in new tab","title":"categorize-animation"},{"location":"plugins/categorize-animation/#categorize-animation","text":"Current version: 1.1.2. See version history . The categorize animation plugin shows a sequence of images at a specified frame rate. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-animation"},{"location":"plugins/categorize-animation/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 or the end of the animation depending on the allow_response_before_complete parameter. The intention is that it can be used to provide a reminder about the action the participant 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.","title":"Parameters"},{"location":"plugins/categorize-animation/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array Array of stimuli displayed in the trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-animation/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-animation import categorizeAnimation from '@jspsych/plugin-categorize-animation' ;","title":"Install"},{"location":"plugins/categorize-animation/#examples","text":"Basic example Code Demo var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ], prompt : `Press the P or Q key.` , choices : [ 'p' , 'q' ], key_answer : 'q' , }; Open demo in new tab Giving feedback with %ANS% string Code Demo var images = [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ]; var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : images , choices : [ 'p' , 'q' ], prompt : `Press the P or Q key.` , 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%.' }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-html/","text":"categorize-html \u00b6 Current version: 1.1.2. See version history . The categorize html plugin shows an HTML object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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 \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-html import categorizeHtml from '@jspsych/plugin-categorize-html' ; Examples \u00b6 Categorizing HTML content Code Demo var categorization_trial = { type : jsPsychCategorizeHtml , stimulus : '<p>B</p>' , key_answer : 'p' , text_answer : 'letter' , 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>\" }; Open demo in new tab","title":"categorize-html"},{"location":"plugins/categorize-html/#categorize-html","text":"Current version: 1.1.2. See version history . The categorize html plugin shows an HTML object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-html"},{"location":"plugins/categorize-html/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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.","title":"Parameters"},{"location":"plugins/categorize-html/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-html import categorizeHtml from '@jspsych/plugin-categorize-html' ;","title":"Install"},{"location":"plugins/categorize-html/#examples","text":"Categorizing HTML content Code Demo var categorization_trial = { type : jsPsychCategorizeHtml , stimulus : '<p>B</p>' , key_answer : 'p' , text_answer : 'letter' , 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>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-image/","text":"categorize-image \u00b6 Current version: 1.1.2. See version history . The categorize image plugin shows an image object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 string undefined The key character indicating the correct response. choices array of strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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 \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-image import categorizeImage from '@jspsych/plugin-categorize-image' ; Examples \u00b6 Categorizing an image Code Demo var categorization_trial = { type : jsPsychCategorizeImage , stimulus : 'img/blue.png' , key_answer : 'b' , text_answer : 'Blue' , choices : [ 'r' , 'g' , 'b' ], correct_text : \"<p class='prompt'>Correct! The color is %ANS%.</p>\" , incorrect_text : \"<p class='prompt'>Incorrect. The color is %ANS%.</p>\" , prompt : \"<p>Is the color of this circle (R)ed, (G)reen, or (B)lue?</p>\" }; Open demo in new tab","title":"categorize-image"},{"location":"plugins/categorize-image/#categorize-image","text":"Current version: 1.1.2. See version history . The categorize image plugin shows an image object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-image"},{"location":"plugins/categorize-image/#parameters","text":"In addition to the 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 string undefined The key character indicating the correct response. choices array of strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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.","title":"Parameters"},{"location":"plugins/categorize-image/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-image import categorizeImage from '@jspsych/plugin-categorize-image' ;","title":"Install"},{"location":"plugins/categorize-image/#examples","text":"Categorizing an image Code Demo var categorization_trial = { type : jsPsychCategorizeImage , stimulus : 'img/blue.png' , key_answer : 'b' , text_answer : 'Blue' , choices : [ 'r' , 'g' , 'b' ], correct_text : \"<p class='prompt'>Correct! The color is %ANS%.</p>\" , incorrect_text : \"<p class='prompt'>Incorrect. The color is %ANS%.</p>\" , prompt : \"<p>Is the color of this circle (R)ed, (G)reen, or (B)lue?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/cloze/","text":"cloze \u00b6 Current version: 1.2.0. See version history . This plugin displays a text with certain words omitted. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding. Parameters \u00b6 In addition to the 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. allow_blanks boolean true Boolean value indicating if the answers given by participants should be checked for completion after the button was clicked. If true , answers are not checked for completion and blank answers are allowed. The trial will then automatically finish upon the clicking the button. If false , answers are checked for completion, and in case there are some fields with missing answers, the mistake_fn is called. In this case, the trial does not automatically finish. mistake_fn function function(){} Function called if check_answers is set to true and there is a difference between the participant's answers and the correct solution provided in the text, or if allow_blanks is set to false and there is at least one field with a blank answer. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response array of strings Answers the partcipant gave Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-cloze@1.2.0\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-cloze.js\" >< /script> Using NPM: npm install @jspsych/plugin-cloze import cloze from '@jspsych/plugin-cloze' ; Examples \u00b6 Simple cloze using default settings (no check against correct solution, no custom button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'The %% is the largest terrestrial mammal. It lives in both %% and %%.' }; Open demo in new tab Cloze example using default settings with completion checking and custom error handling Code Demo var cloze_trial = { type : jsPsychCloze , text : 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.' , allow_blanks : false , mistake_fn : function () { alert ( 'Please fill in all blanks.' ); } }; Open demo in new tab More elaborate example (with check against correct solution, custom error handling and modified button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'A rectangle has % 4 % corners and a triangle has % 3 %.' , check_answers : true , button_text : 'Next' , mistake_fn : function (){ alert ( \"Wrong answer. Please check again.\" ) } }; Open demo in new tab","title":"cloze"},{"location":"plugins/cloze/#cloze","text":"Current version: 1.2.0. See version history . This plugin displays a text with certain words omitted. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding.","title":"cloze"},{"location":"plugins/cloze/#parameters","text":"In addition to the 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. allow_blanks boolean true Boolean value indicating if the answers given by participants should be checked for completion after the button was clicked. If true , answers are not checked for completion and blank answers are allowed. The trial will then automatically finish upon the clicking the button. If false , answers are checked for completion, and in case there are some fields with missing answers, the mistake_fn is called. In this case, the trial does not automatically finish. mistake_fn function function(){} Function called if check_answers is set to true and there is a difference between the participant's answers and the correct solution provided in the text, or if allow_blanks is set to false and there is at least one field with a blank answer.","title":"Parameters"},{"location":"plugins/cloze/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response array of strings Answers the partcipant gave","title":"Data Generated"},{"location":"plugins/cloze/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-cloze@1.2.0\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-cloze.js\" >< /script> Using NPM: npm install @jspsych/plugin-cloze import cloze from '@jspsych/plugin-cloze' ;","title":"Install"},{"location":"plugins/cloze/#examples","text":"Simple cloze using default settings (no check against correct solution, no custom button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'The %% is the largest terrestrial mammal. It lives in both %% and %%.' }; Open demo in new tab Cloze example using default settings with completion checking and custom error handling Code Demo var cloze_trial = { type : jsPsychCloze , text : 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.' , allow_blanks : false , mistake_fn : function () { alert ( 'Please fill in all blanks.' ); } }; Open demo in new tab More elaborate example (with check against correct solution, custom error handling and modified button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'A rectangle has % 4 % corners and a triangle has % 3 %.' , check_answers : true , button_text : 'Next' , mistake_fn : function (){ alert ( \"Wrong answer. Please check again.\" ) } }; Open demo in new tab","title":"Examples"},{"location":"plugins/external-html/","text":"external-html \u00b6 Current version: 1.1.2. See version history . 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 \u00b6 In addition to the 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 string null The key character the participant can use to advance to the next trial. If left as null, then the participant 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 participant attempts to advance the trial. The trial will only advance if the function return true . This can be used to verify that the participant 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 \u00b6 In addition to the default data collected by all 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 participant to finish the trial. Simulation Mode \u00b6 In visual simulation mode, the plugin cannot interact with any form elements on the screen other than the cont_btn specified in the trial parameters. If your check_fn requires other user interaction, for example, clicking a checkbox, then you'll need to disable simulation for the trial and complete the interaction manually. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-external-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-external-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-external-html import externalHtml from '@jspsych/plugin-external-html' ; Examples \u00b6 Loading a consent form \u00b6 This content would be in a file called 'external_page.html' \u00b6 < div id = \"consent\" > < p > 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\". </ p > < p > < input type = \"checkbox\" id = \"consent_checkbox\" /> I agree to take part in this study. </ p > < button type = \"button\" id = \"start\" > Start Experiment </ button > </ div > jsPsych code to load above page. Code Demo // sample function that might be used to check if a participant has given // consent to participate. var check_consent = function ( elem ) { if ( document . getElementById ( 'consent_checkbox' ). checked ) { return true ; } else { alert ( \"If you wish to participate, you must check the box next to the statement 'I agree to participate in this study.'\" ); return false ; } return false ; }; // declare the block. var trial = { type : jsPsychExternalHtml , url : \"external_page.html\" , cont_btn : \"start\" , check_fn : check_consent }; Open demo in new tab","title":"external-html"},{"location":"plugins/external-html/#external-html","text":"Current version: 1.1.2. See version history . 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.","title":"external-html"},{"location":"plugins/external-html/#parameters","text":"In addition to the 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 string null The key character the participant can use to advance to the next trial. If left as null, then the participant 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 participant attempts to advance the trial. The trial will only advance if the function return true . This can be used to verify that the participant 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.","title":"Parameters"},{"location":"plugins/external-html/#data-generated","text":"In addition to the default data collected by all 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 participant to finish the trial.","title":"Data Generated"},{"location":"plugins/external-html/#simulation-mode","text":"In visual simulation mode, the plugin cannot interact with any form elements on the screen other than the cont_btn specified in the trial parameters. If your check_fn requires other user interaction, for example, clicking a checkbox, then you'll need to disable simulation for the trial and complete the interaction manually.","title":"Simulation Mode"},{"location":"plugins/external-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-external-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-external-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-external-html import externalHtml from '@jspsych/plugin-external-html' ;","title":"Install"},{"location":"plugins/external-html/#examples","text":"","title":"Examples"},{"location":"plugins/external-html/#loading-a-consent-form","text":"","title":"Loading a consent form"},{"location":"plugins/external-html/#this-content-would-be-in-a-file-called-external_pagehtml","text":"< div id = \"consent\" > < p > 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\". </ p > < p > < input type = \"checkbox\" id = \"consent_checkbox\" /> I agree to take part in this study. </ p > < button type = \"button\" id = \"start\" > Start Experiment </ button > </ div > jsPsych code to load above page. Code Demo // sample function that might be used to check if a participant has given // consent to participate. var check_consent = function ( elem ) { if ( document . getElementById ( 'consent_checkbox' ). checked ) { return true ; } else { alert ( \"If you wish to participate, you must check the box next to the statement 'I agree to participate in this study.'\" ); return false ; } return false ; }; // declare the block. var trial = { type : jsPsychExternalHtml , url : \"external_page.html\" , cont_btn : \"start\" , check_fn : check_consent }; Open demo in new tab","title":"This content would be in a file called 'external_page.html'"},{"location":"plugins/free-sort/","text":"free-sort \u00b6 Current version: 1.0.2. See version history . The free-sort plugin displays one or more images on the screen that the participant can interact with by clicking and dragging with a mouse, or touching and dragging with a touchscreen device. When the trial starts, the images can be positioned outside or inside the sort area. All images must be moved into the sorting area before the participant can click a button to end the trial. All of the moves that the participant performs are recorded, as well as the final positions of all images. This plugin could be useful when asking participants to position images based on similarity to one another, or to recall image spatial locations. Parameters \u00b6 In addition to the 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 this array is an image path. stim_height numeric 100 The height of the images in pixels. stim_width numeric 100 The width of the images in pixels. scale_factor numeric 1.5 How much larger to make the stimulus while moving (1 = no scaling). sort_area_height numeric 800 The height of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_width numeric 800 The width of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_shape string \"ellipse\" The shape of the sorting area, can be \"ellipse\" or \"square\". prompt string null This string can contain HTML markup. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). prompt_location string \"above\" Indicates whether to show the prompt \"above\" or \"below\" the sorting area. button_label string 'Continue' The text that appears on the button to continue to the next trial. change_border_background_color boolean true If true , the sort area border color will change while items are being moved in and out of the sort area, and the background color will change once all items have been moved into the sort area. If false , the border will remain black and the background will remain white throughout the trial. border_color_in string '#a1d99b' If change_border_background_color is true , the sort area border will change to this color when an item is being moved into the sort area, and the background will change to this color when all of the items have been moved into the sort area. border_color_out string '#fc9272' If change_border_background_color is true , this will be the color of the sort area border when there are one or more items that still need to be moved into the sort area. border_width numeric null The width in pixels of the border around the sort area. If null , the border width will be 3% of the sort_area_height . counter_text_unfinished string You still need to place %n% item%s% inside the sort area. Text to display when there are one or more items that still need to be placed in the sort area. If \"%n%\" is included in the string, it will be replaced with the number of items that still need to be moved inside. If \"%s%\" is included in the string, a \"s\" will be included when the number of items remaining is greater than one. counter_text_finished string All items placed. Feel free to reposition items if necessary. Text that will take the place of the counter_text_unfinished text when all items have been moved inside the sort area. stim_starts_inside boolean false If false , the images will be positioned to the left and right of the sort area when the trial loads. If true , the images will be positioned at random locations inside the sort area when the trial loads. column_spread_factor numeric 1 When the images appear outside the sort area, this determines the x-axis spread of the image columns. Default value is 1. Values less than 1 will compress the image columns along the x-axis, and values greater than 1 will spread them farther apart. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value init_locations array An array containing objects representing the initial locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. moves array An array containing objects representing all of the moves the participant made when sorting. Each object represents a move. Each element in the array has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location after the move. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. final_locations array An array containing objects representing the final locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to finish all sorting. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-free-sort@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-free-sort.js\" >< /script> Using NPM: npm install @jspsych/plugin-free-sort import freeSort from '@jspsych/plugin-free-sort' ; Examples \u00b6 Basic example Code Demo var sort_trial = { type : jsPsychFreeSort , stimuli : sorting_stimuli , stim_width : 80 , stim_height : 60 , sort_area_width : 500 , sort_area_height : 500 , prompt : \"<p>Click and drag the images below to sort them so that similar items are close together.</p>\" }; Open demo in new tab","title":"free-sort"},{"location":"plugins/free-sort/#free-sort","text":"Current version: 1.0.2. See version history . The free-sort plugin displays one or more images on the screen that the participant can interact with by clicking and dragging with a mouse, or touching and dragging with a touchscreen device. When the trial starts, the images can be positioned outside or inside the sort area. All images must be moved into the sorting area before the participant can click a button to end the trial. All of the moves that the participant performs are recorded, as well as the final positions of all images. This plugin could be useful when asking participants to position images based on similarity to one another, or to recall image spatial locations.","title":"free-sort"},{"location":"plugins/free-sort/#parameters","text":"In addition to the 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 this array is an image path. stim_height numeric 100 The height of the images in pixels. stim_width numeric 100 The width of the images in pixels. scale_factor numeric 1.5 How much larger to make the stimulus while moving (1 = no scaling). sort_area_height numeric 800 The height of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_width numeric 800 The width of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_shape string \"ellipse\" The shape of the sorting area, can be \"ellipse\" or \"square\". prompt string null This string can contain HTML markup. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). prompt_location string \"above\" Indicates whether to show the prompt \"above\" or \"below\" the sorting area. button_label string 'Continue' The text that appears on the button to continue to the next trial. change_border_background_color boolean true If true , the sort area border color will change while items are being moved in and out of the sort area, and the background color will change once all items have been moved into the sort area. If false , the border will remain black and the background will remain white throughout the trial. border_color_in string '#a1d99b' If change_border_background_color is true , the sort area border will change to this color when an item is being moved into the sort area, and the background will change to this color when all of the items have been moved into the sort area. border_color_out string '#fc9272' If change_border_background_color is true , this will be the color of the sort area border when there are one or more items that still need to be moved into the sort area. border_width numeric null The width in pixels of the border around the sort area. If null , the border width will be 3% of the sort_area_height . counter_text_unfinished string You still need to place %n% item%s% inside the sort area. Text to display when there are one or more items that still need to be placed in the sort area. If \"%n%\" is included in the string, it will be replaced with the number of items that still need to be moved inside. If \"%s%\" is included in the string, a \"s\" will be included when the number of items remaining is greater than one. counter_text_finished string All items placed. Feel free to reposition items if necessary. Text that will take the place of the counter_text_unfinished text when all items have been moved inside the sort area. stim_starts_inside boolean false If false , the images will be positioned to the left and right of the sort area when the trial loads. If true , the images will be positioned at random locations inside the sort area when the trial loads. column_spread_factor numeric 1 When the images appear outside the sort area, this determines the x-axis spread of the image columns. Default value is 1. Values less than 1 will compress the image columns along the x-axis, and values greater than 1 will spread them farther apart.","title":"Parameters"},{"location":"plugins/free-sort/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value init_locations array An array containing objects representing the initial locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. moves array An array containing objects representing all of the moves the participant made when sorting. Each object represents a move. Each element in the array has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location after the move. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. final_locations array An array containing objects representing the final locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to finish all sorting.","title":"Data Generated"},{"location":"plugins/free-sort/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/free-sort/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-free-sort@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-free-sort.js\" >< /script> Using NPM: npm install @jspsych/plugin-free-sort import freeSort from '@jspsych/plugin-free-sort' ;","title":"Install"},{"location":"plugins/free-sort/#examples","text":"Basic example Code Demo var sort_trial = { type : jsPsychFreeSort , stimuli : sorting_stimuli , stim_width : 80 , stim_height : 60 , sort_area_width : 500 , sort_area_height : 500 , prompt : \"<p>Click and drag the images below to sort them so that similar items are close together.</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/fullscreen/","text":"fullscreen \u00b6 Current version: 1.1.2. See version history . The fullscreen plugin allows the experiment to enter or exit fullscreen mode. For security reasons, all browsers require that entry into fullscreen mode is triggered by a user action. To enter fullscreen mode, this plugin has the user click a button. Exiting fullscreen mode can be done without user input. Warning Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari. Parameters \u00b6 In addition to the 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 fullscreen_mode boolean true A value of true causes the experiment to enter fullscreen mode. A value of false causes the browser to exit fullscreen mode. message string <p>The experiment will switch to full screen mode when you press the button below</p> The HTML content to display above the button to enter fullscreen mode. button_label string 'Continue' The text that appears on the button to enter fullscreen mode. delay_after numeric 1000 The length of time to delay after entering fullscreen mode before ending the trial. This can be useful because entering fullscreen is jarring and most browsers display some kind of message that the browser has entered fullscreen mode. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean true if the browser supports fullscreen mode (i.e., is not Safari) Simulation Mode \u00b6 Web browsers do not allow fullscreen mode to be triggered by a script to avoid malicious usage of fullscreen behavior when the user is not wanting it. In visual simulation mode, the trial will run normally and the button will get a simulated click, but the display will not change. If you want the display to actually enter fullscreen mode during the simulation, you should disable simulation for the fullscreen trial and manually click the button. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-fullscreen@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-fullscreen.js\" >< /script> Using NPM: npm install @jspsych/plugin-fullscreen import fullscreen from '@jspsych/plugin-fullscreen' ; Examples \u00b6 Entering and exiting fullscreen Code Demo var enter_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : true } var trial_in_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will be in fullscreen mode.' , choices : [ 'Continue' ] } var exit_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : false , delay_after : 0 } var trial_after_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will NOT be in fullscreen mode.' , choices : [ 'Continue' ] } Open demo in new tab","title":"fullscreen"},{"location":"plugins/fullscreen/#fullscreen","text":"Current version: 1.1.2. See version history . The fullscreen plugin allows the experiment to enter or exit fullscreen mode. For security reasons, all browsers require that entry into fullscreen mode is triggered by a user action. To enter fullscreen mode, this plugin has the user click a button. Exiting fullscreen mode can be done without user input. Warning Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"fullscreen"},{"location":"plugins/fullscreen/#parameters","text":"In addition to the 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 fullscreen_mode boolean true A value of true causes the experiment to enter fullscreen mode. A value of false causes the browser to exit fullscreen mode. message string <p>The experiment will switch to full screen mode when you press the button below</p> The HTML content to display above the button to enter fullscreen mode. button_label string 'Continue' The text that appears on the button to enter fullscreen mode. delay_after numeric 1000 The length of time to delay after entering fullscreen mode before ending the trial. This can be useful because entering fullscreen is jarring and most browsers display some kind of message that the browser has entered fullscreen mode.","title":"Parameters"},{"location":"plugins/fullscreen/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean true if the browser supports fullscreen mode (i.e., is not Safari)","title":"Data Generated"},{"location":"plugins/fullscreen/#simulation-mode","text":"Web browsers do not allow fullscreen mode to be triggered by a script to avoid malicious usage of fullscreen behavior when the user is not wanting it. In visual simulation mode, the trial will run normally and the button will get a simulated click, but the display will not change. If you want the display to actually enter fullscreen mode during the simulation, you should disable simulation for the fullscreen trial and manually click the button.","title":"Simulation Mode"},{"location":"plugins/fullscreen/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-fullscreen@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-fullscreen.js\" >< /script> Using NPM: npm install @jspsych/plugin-fullscreen import fullscreen from '@jspsych/plugin-fullscreen' ;","title":"Install"},{"location":"plugins/fullscreen/#examples","text":"Entering and exiting fullscreen Code Demo var enter_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : true } var trial_in_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will be in fullscreen mode.' , choices : [ 'Continue' ] } var exit_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : false , delay_after : 0 } var trial_after_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will NOT be in fullscreen mode.' , choices : [ 'Continue' ] } Open demo in new tab","title":"Examples"},{"location":"plugins/html-audio-response/","text":"html-audio-response \u00b6 Current version: 1.0.2. See version history . This plugin displays HTML content and records audio from the participant via a microphone. In order to get access to the microphone, you need to use the initialize-microphone plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records audio data in base 64 format . This is a text-based representation of the audio which can be coverted to various audio formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of audio recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of audio, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded audio files as Object URLs via save_audio_url: true . This will generate a URL that is storing a copy of the recorded audio, which can be used for subsequent playback. See below for an example where the recorded audio is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of audio snippets, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded audio and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_audio_url bool false If true , then an Object URL will be generated and stored for the recorded audio. Only set this to true if you plan to reuse the recorded audio later in the experiment, as it is a potentially memory-intensive feature. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded audio data. stimulus string The HTML content that was displayed on the screen. estimated_stimulus_onset number This is an estimate of when the stimulus appeared relative to the start of the audio recording. The plugin is configured so that the recording should start prior to the display of the stimulus. We have not yet been able to verify the accuracy of this estimate with external measurement devices. audio_url string A URL to a copy of the audio data. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-audio-response@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-audio-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-audio-response import htmlAudioResponse from '@jspsych/plugin-html-audio-response' ; Examples \u00b6 Simple spoken response to a stimulus Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p style=\"font-size:48px; color:red;\">GREEN</p> <p>Speak the color of the ink.</p>` , recording_duration : 3500 }; Open demo in new tab Allow playback and rerecording; save data to server immediately Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p>Please sing the first few seconds of a song and click the button when you are done.</p> ` , recording_duration : 15000 , allow_playback : true , on_finish : function ( data ){ fetch ( '/save-my-data.php' , { audio_base64 : data . response }) . then (( audio_id ){ data . response = audio_id ; }); } }; This example assumes that there is a script on your experiment server that accepts the data called save-my-data.php . It also assumes that the script will generate a response with an ID for the stored audio file ( audio_id ). In the example, we replace the very long base64 representation of the audio file with the generated ID, which could be just a handful of characters. This would let you link files to responses in data analysis, without having to store long audio files in memory during the experiment. Open demo in new tab Use recorded audio as a subsequent stimulus Code Demo var instruction = { type : jsPsychHtmlButtonResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Make up a name for this shape. When you have one in mind, click the button and then say the name aloud.</p> ` , choices : [ 'I am ready.' ] } var record = { type : jsPsychHtmlAudioResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Recording...</p> ` , recording_duration : 1500 , save_audio_url : true }; var playback = { type : jsPsychAudioButtonResponse , stimulus : ()=>{ return jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. audio_url ; }, prompt : '<p>Click the object the matches the spoken name.</p>' , choices : [ 'img/9.gif' , 'img/10.gif' , 'img/11.gif' , 'img/12.gif' ], button_html : '<img src=\"%choice%\" style=\"width:100px; padding: 20px;\"></img>' } Open demo in new tab","title":"html-audio-response"},{"location":"plugins/html-audio-response/#html-audio-response","text":"Current version: 1.0.2. See version history . This plugin displays HTML content and records audio from the participant via a microphone. In order to get access to the microphone, you need to use the initialize-microphone plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records audio data in base 64 format . This is a text-based representation of the audio which can be coverted to various audio formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of audio recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of audio, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded audio files as Object URLs via save_audio_url: true . This will generate a URL that is storing a copy of the recorded audio, which can be used for subsequent playback. See below for an example where the recorded audio is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of audio snippets, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"html-audio-response"},{"location":"plugins/html-audio-response/#parameters","text":"In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded audio and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_audio_url bool false If true , then an Object URL will be generated and stored for the recorded audio. Only set this to true if you plan to reuse the recorded audio later in the experiment, as it is a potentially memory-intensive feature.","title":"Parameters"},{"location":"plugins/html-audio-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded audio data. stimulus string The HTML content that was displayed on the screen. estimated_stimulus_onset number This is an estimate of when the stimulus appeared relative to the start of the audio recording. The plugin is configured so that the recording should start prior to the display of the stimulus. We have not yet been able to verify the accuracy of this estimate with external measurement devices. audio_url string A URL to a copy of the audio data.","title":"Data Generated"},{"location":"plugins/html-audio-response/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/html-audio-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-audio-response@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-audio-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-audio-response import htmlAudioResponse from '@jspsych/plugin-html-audio-response' ;","title":"Install"},{"location":"plugins/html-audio-response/#examples","text":"Simple spoken response to a stimulus Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p style=\"font-size:48px; color:red;\">GREEN</p> <p>Speak the color of the ink.</p>` , recording_duration : 3500 }; Open demo in new tab Allow playback and rerecording; save data to server immediately Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p>Please sing the first few seconds of a song and click the button when you are done.</p> ` , recording_duration : 15000 , allow_playback : true , on_finish : function ( data ){ fetch ( '/save-my-data.php' , { audio_base64 : data . response }) . then (( audio_id ){ data . response = audio_id ; }); } }; This example assumes that there is a script on your experiment server that accepts the data called save-my-data.php . It also assumes that the script will generate a response with an ID for the stored audio file ( audio_id ). In the example, we replace the very long base64 representation of the audio file with the generated ID, which could be just a handful of characters. This would let you link files to responses in data analysis, without having to store long audio files in memory during the experiment. Open demo in new tab Use recorded audio as a subsequent stimulus Code Demo var instruction = { type : jsPsychHtmlButtonResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Make up a name for this shape. When you have one in mind, click the button and then say the name aloud.</p> ` , choices : [ 'I am ready.' ] } var record = { type : jsPsychHtmlAudioResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Recording...</p> ` , recording_duration : 1500 , save_audio_url : true }; var playback = { type : jsPsychAudioButtonResponse , stimulus : ()=>{ return jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. audio_url ; }, prompt : '<p>Click the object the matches the spoken name.</p>' , choices : [ 'img/9.gif' , 'img/10.gif' , 'img/11.gif' , 'img/12.gif' ], button_html : '<img src=\"%choice%\" style=\"width:100px; padding: 20px;\"></img>' } Open demo in new tab","title":"Examples"},{"location":"plugins/html-button-response/","text":"html-button-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated by button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Parameters \u00b6 In addition to the 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 content to be displayed. choices array of strings [] 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The HTML content that was displayed on the screen. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-button-response import htmlButtonResponse from '@jspsych/plugin-html-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"font-size:48px; color:red;\">GREEN</p>' , choices : [ 'Red' , 'Green' , 'Blue' ], prompt : \"<p>What color is the ink?</p>\" }; Open demo in new tab","title":"html-button-response"},{"location":"plugins/html-button-response/#html-button-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated by button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting.","title":"html-button-response"},{"location":"plugins/html-button-response/#parameters","text":"In addition to the 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 content to be displayed. choices array of strings [] 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The HTML content that was displayed on the screen.","title":"Data Generated"},{"location":"plugins/html-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-button-response import htmlButtonResponse from '@jspsych/plugin-html-button-response' ;","title":"Install"},{"location":"plugins/html-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"font-size:48px; color:red;\">GREEN</p>' , choices : [ 'Red' , 'Green' , 'Blue' ], prompt : \"<p>What color is the ink?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-keyboard-response/","text":"html-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated with 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-keyboard-response import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:48px; color:green;\">BLUE</p>' , choices : [ 'r' , 'g' , 'b' ], prompt : \"<p>Is the ink color (r)ed, (g)reen, or (b)lue?</p>\" }; Open demo in new tab Showing a 1 second fixation cross; no response allowed Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size: 48px;\">+</p>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; Open demo in new tab","title":"html-keyboard-response"},{"location":"plugins/html-keyboard-response/#html-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated with 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 participant has failed to respond within a fixed length of time.","title":"html-keyboard-response"},{"location":"plugins/html-keyboard-response/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen.","title":"Data Generated"},{"location":"plugins/html-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-keyboard-response import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ;","title":"Install"},{"location":"plugins/html-keyboard-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:48px; color:green;\">BLUE</p>' , choices : [ 'r' , 'g' , 'b' ], prompt : \"<p>Is the ink color (r)ed, (g)reen, or (b)lue?</p>\" }; Open demo in new tab Showing a 1 second fixation cross; no response allowed Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size: 48px;\">+</p>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-slider-response/","text":"html-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and allows the participant to respond by dragging a slider. Parameters \u00b6 In addition to the 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 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 participant 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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. slider_start numeric The starting value of the slider. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-slider-response import htmlSliderResponse from '@jspsych/plugin-html-slider-response' ; Examples \u00b6 Displaying question until participant moves the slider Code Demo var trial = { type : jsPsychHtmlSliderResponse , stimulus : `<div style=\"width:500px;\"> <p>How likely is it that team A will win this match?</p> <div style=\"width:240px; float: left;\"> <p>TEAM A</p> <p>10 wins, 5 losses, 6 draws</p> </div> <div style=\"width:240px; float: right;\"> <p>TEAM B</p> <p>6 wins, 4 losses, 11 draws</p> </div> </div>` , require_movement : true , labels : [ '100% chance' , '50% chance' , '0% chance' ] }; Open demo in new tab","title":"html-slider-response"},{"location":"plugins/html-slider-response/#html-slider-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and allows the participant to respond by dragging a slider.","title":"html-slider-response"},{"location":"plugins/html-slider-response/#parameters","text":"In addition to the 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 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 participant 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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/html-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-slider-response import htmlSliderResponse from '@jspsych/plugin-html-slider-response' ;","title":"Install"},{"location":"plugins/html-slider-response/#examples","text":"Displaying question until participant moves the slider Code Demo var trial = { type : jsPsychHtmlSliderResponse , stimulus : `<div style=\"width:500px;\"> <p>How likely is it that team A will win this match?</p> <div style=\"width:240px; float: left;\"> <p>TEAM A</p> <p>10 wins, 5 losses, 6 draws</p> </div> <div style=\"width:240px; float: right;\"> <p>TEAM B</p> <p>6 wins, 4 losses, 11 draws</p> </div> </div>` , require_movement : true , labels : [ '100% chance' , '50% chance' , '0% chance' ] }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-video-response/","text":"html-video-response \u00b6 Current version: 1.0.1. See version history . This plugin displays HTML content and records video from the participant via a webcam. In order to get access to the camera, you need to use the initialize-camera plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of video recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of video, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded video files as Object URLs via save_video_url: true . This will generate a URL that stores a copy of the recorded video, which can be used for subsequent playback during the experiment. See below for an example where the recorded video is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of video clips, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems . Parameters \u00b6 In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded video and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_video_url bool false If true , then an Object URL will be generated and stored for the recorded video. Only set this to true if you plan to reuse the recorded video later in the experiment, as it is a potentially memory-intensive feature. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded video data. stimulus string The HTML content that was displayed on the screen. video_url string A URL to a copy of the video data. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-video-response@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-video-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-video-response import htmlVideoResponse from '@jspsych/plugin-html-video-response' ; Examples \u00b6 Simple recorded response to a stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : ` <p style=\"font-size:48px; color:red;\"> <-- </p> <p>Turn your head in the direction of the arrow</p>` , recording_duration : 3500 , show_done_button : false , }; Open demo in new tab Allow playback and rerecording Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face</p>` , recording_duration : 3500 , show_done_button : false , allow_playback : true }; Open demo in new tab Use recorded video as a subsequent stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var record = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face.</p>` , recording_duration : 1500 , show_done_button : false , save_video_url : true }; var classify = { type : jsPsychVideoButtonResponse , stimulus : () => { return [ jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. video_url ]; }, choices : [ \"Happy\" , \"Sad\" , \"Angry\" , \"Surprised\" ], prompt : \"<p>What emotion is this?</p>\" , } Open demo in new tab","title":"html-video-response"},{"location":"plugins/html-video-response/#html-video-response","text":"Current version: 1.0.1. See version history . This plugin displays HTML content and records video from the participant via a webcam. In order to get access to the camera, you need to use the initialize-camera plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of video recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of video, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded video files as Object URLs via save_video_url: true . This will generate a URL that stores a copy of the recorded video, which can be used for subsequent playback during the experiment. See below for an example where the recorded video is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of video clips, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems .","title":"html-video-response"},{"location":"plugins/html-video-response/#parameters","text":"In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded video and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_video_url bool false If true , then an Object URL will be generated and stored for the recorded video. Only set this to true if you plan to reuse the recorded video later in the experiment, as it is a potentially memory-intensive feature.","title":"Parameters"},{"location":"plugins/html-video-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded video data. stimulus string The HTML content that was displayed on the screen. video_url string A URL to a copy of the video data.","title":"Data Generated"},{"location":"plugins/html-video-response/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/html-video-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-video-response@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-video-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-video-response import htmlVideoResponse from '@jspsych/plugin-html-video-response' ;","title":"Install"},{"location":"plugins/html-video-response/#examples","text":"Simple recorded response to a stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : ` <p style=\"font-size:48px; color:red;\"> <-- </p> <p>Turn your head in the direction of the arrow</p>` , recording_duration : 3500 , show_done_button : false , }; Open demo in new tab Allow playback and rerecording Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face</p>` , recording_duration : 3500 , show_done_button : false , allow_playback : true }; Open demo in new tab Use recorded video as a subsequent stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var record = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face.</p>` , recording_duration : 1500 , show_done_button : false , save_video_url : true }; var classify = { type : jsPsychVideoButtonResponse , stimulus : () => { return [ jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. video_url ]; }, choices : [ \"Happy\" , \"Sad\" , \"Angry\" , \"Surprised\" ], prompt : \"<p>What emotion is this?</p>\" , } Open demo in new tab","title":"Examples"},{"location":"plugins/iat-html/","text":"iat-html \u00b6 Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using HTML content as the stimulus. Parameters \u00b6 In addition to the 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 HTML-formatted stimulus to display. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The content to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then html_when_wrong and wrong_image_name is required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string undefined Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of strings \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given stimulus. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-html import iatHtml from '@jspsych/plugin-iat-html' ; Examples \u00b6 Displaying IAT question using html Code Demo var trial = { type : jsPsychIatHtml , stimulus : 'Joyous' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"iat-html"},{"location":"plugins/iat-html/#iat-html","text":"Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using HTML content as the stimulus.","title":"iat-html"},{"location":"plugins/iat-html/#parameters","text":"In addition to the 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 HTML-formatted stimulus to display. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The content to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then html_when_wrong and wrong_image_name is required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string undefined Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of strings \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/iat-html/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given stimulus.","title":"Data Generated"},{"location":"plugins/iat-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-html import iatHtml from '@jspsych/plugin-iat-html' ;","title":"Install"},{"location":"plugins/iat-html/#examples","text":"Displaying IAT question using html Code Demo var trial = { type : jsPsychIatHtml , stimulus : 'Joyous' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"Examples"},{"location":"plugins/iat-image/","text":"iat-image \u00b6 Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using an image as the stimulus. Parameters \u00b6 In addition to the 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 stimulus to display. The path to an image. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The HTML to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then image_when_wrong and wrong_image_name are required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string 'undefined' Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of characters \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given image. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-image import iatImage from '@jspsych/plugin-iat-image' ; Examples \u00b6 Displaying IAT question using image files Code Demo var trial_block = { type : jsPsychIatImage , stimulus : 'img/iat_old_face.jpg' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"iat-image"},{"location":"plugins/iat-image/#iat-image","text":"Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using an image as the stimulus.","title":"iat-image"},{"location":"plugins/iat-image/#parameters","text":"In addition to the 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 stimulus to display. The path to an image. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The HTML to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then image_when_wrong and wrong_image_name are required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string 'undefined' Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of characters \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/iat-image/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given image.","title":"Data Generated"},{"location":"plugins/iat-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-image import iatImage from '@jspsych/plugin-iat-image' ;","title":"Install"},{"location":"plugins/iat-image/#examples","text":"Displaying IAT question using image files Code Demo var trial_block = { type : jsPsychIatImage , stimulus : 'img/iat_old_face.jpg' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"Examples"},{"location":"plugins/image-button-response/","text":"image-button-response \u00b6 Current version: 1.1.2. See version history . This plugin displays an image and records responses generated with a button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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_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 [] 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The path of the image that was displayed. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-button-response import imageButtonResponse from '@jspsych/plugin-image-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'Happy' , 'Sad' ], prompt : \"<p>Is this person happy or sad?</p>\" }; Open demo in new tab","title":"image-button-response"},{"location":"plugins/image-button-response/#image-button-response","text":"Current version: 1.1.2. See version history . This plugin displays an image and records responses generated with a button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-button-response"},{"location":"plugins/image-button-response/#parameters","text":"In addition to the 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_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 [] 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The path of the image that was displayed.","title":"Data Generated"},{"location":"plugins/image-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-button-response import imageButtonResponse from '@jspsych/plugin-image-button-response' ;","title":"Install"},{"location":"plugins/image-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'Happy' , 'Sad' ], prompt : \"<p>Is this person happy or sad?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/image-keyboard-response/","text":"image-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin displays and image and records responses generated with 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 participant has failed to respond within a fixed length of time. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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_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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-keyboard-response import imageKeyboardResponse from '@jspsych/plugin-image-keyboard-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'e' , 'i' ], prompt : \"<p>Is this person happy or sad? Press 'e' for happy and 'i' for sad.</p>\" , }; Open demo in new tab Displaying image for a fixed duration; no response allowed Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : \"NO_KEYS\" , prompt : \"<p>Study this face for 5 seconds.</p>\" , trial_duration : 5000 }; Open demo in new tab","title":"image-keyboard-response"},{"location":"plugins/image-keyboard-response/#image-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin displays and image and records responses generated with 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 participant has failed to respond within a fixed length of time. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-keyboard-response"},{"location":"plugins/image-keyboard-response/#parameters","text":"In addition to the 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_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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed.","title":"Data Generated"},{"location":"plugins/image-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-keyboard-response import imageKeyboardResponse from '@jspsych/plugin-image-keyboard-response' ;","title":"Install"},{"location":"plugins/image-keyboard-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'e' , 'i' ], prompt : \"<p>Is this person happy or sad? Press 'e' for happy and 'i' for sad.</p>\" , }; Open demo in new tab Displaying image for a fixed duration; no response allowed Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : \"NO_KEYS\" , prompt : \"<p>Study this face for 5 seconds.</p>\" , trial_duration : 5000 }; Open demo in new tab","title":"Examples"},{"location":"plugins/image-slider-response/","text":"image-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin displays and image and allows the participant to respond by dragging a slider. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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 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. 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 advance/submit 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 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 participant 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. slider_start numeric The starting value of the slider. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-slider-response import imageSliderResponse from '@jspsych/plugin-image-slider-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageSliderResponse , stimulus : 'img/happy_face_1.png' , labels : [ 'happy' , 'sad' ], prompt : \"<p>How happy/sad is this person?</p>\" , }; Open demo in new tab","title":"image-slider-response"},{"location":"plugins/image-slider-response/#image-slider-response","text":"Current version: 1.1.2. See version history . This plugin displays and image and allows the participant to respond by dragging a slider. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-slider-response"},{"location":"plugins/image-slider-response/#parameters","text":"In addition to the 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 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. 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 advance/submit 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 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 participant 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/image-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-slider-response import imageSliderResponse from '@jspsych/plugin-image-slider-response' ;","title":"Install"},{"location":"plugins/image-slider-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageSliderResponse , stimulus : 'img/happy_face_1.png' , labels : [ 'happy' , 'sad' ], prompt : \"<p>How happy/sad is this person?</p>\" , }; Open demo in new tab","title":"Examples"},{"location":"plugins/initialize-camera/","text":"initialize-camera \u00b6 Current version: 1.0.0 See version history . This plugin asks the participant to grant permission to access a camera. If multiple cameras are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the camera is selected with this plugin it can be accessed with jsPsych.pluginAPI.getCameraRecorder() . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 device_select_message html string <p>Please select the camera you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this camera.' The label for the select button. include_audio bool false Set to true to include an audio track in the recordings. width int null Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . height int null Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . mime_type string null Set this to use a specific MIME type for the recording. Set the entire type, e.g., 'video/mp4; codecs=\"avc1.424028, mp4a.40.2\"' . Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected camera. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-camera import initializeCamera from '@jspsych/plugin-initialize-camera' ; Examples \u00b6 Ask for camera permission Code Demo var trial = { type : jsPsychInitializeCamera }; Open demo in new tab","title":"initialize-camera"},{"location":"plugins/initialize-camera/#initialize-camera","text":"Current version: 1.0.0 See version history . This plugin asks the participant to grant permission to access a camera. If multiple cameras are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the camera is selected with this plugin it can be accessed with jsPsych.pluginAPI.getCameraRecorder() . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"initialize-camera"},{"location":"plugins/initialize-camera/#parameters","text":"In addition to the 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 device_select_message html string <p>Please select the camera you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this camera.' The label for the select button. include_audio bool false Set to true to include an audio track in the recordings. width int null Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . height int null Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . mime_type string null Set this to use a specific MIME type for the recording. Set the entire type, e.g., 'video/mp4; codecs=\"avc1.424028, mp4a.40.2\"' .","title":"Parameters"},{"location":"plugins/initialize-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected camera.","title":"Data Generated"},{"location":"plugins/initialize-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/initialize-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-camera import initializeCamera from '@jspsych/plugin-initialize-camera' ;","title":"Install"},{"location":"plugins/initialize-camera/#examples","text":"Ask for camera permission Code Demo var trial = { type : jsPsychInitializeCamera }; Open demo in new tab","title":"Examples"},{"location":"plugins/initialize-microphone/","text":"initialize-microphone \u00b6 Current version: 1.0.2. See version history . This plugin asks the participant to grant permission to access a microphone. If multiple microphones are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the microphone is selected with this plugin it can be accessed with jsPsych.pluginAPI.getMicrophoneRecorder() . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 device_select_message html string <p>Please select the microphone you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this microphone.' The label for the select button. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected microphone. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-microphone@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-microphone.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-microphone import initializeMicrophone from '@jspsych/plugin-initialize-microphone' ; Examples \u00b6 Ask for microphone permission Code Demo var trial = { type : jsPsychInitializeMicrophone }; Open demo in new tab","title":"initialize-microphone"},{"location":"plugins/initialize-microphone/#initialize-microphone","text":"Current version: 1.0.2. See version history . This plugin asks the participant to grant permission to access a microphone. If multiple microphones are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the microphone is selected with this plugin it can be accessed with jsPsych.pluginAPI.getMicrophoneRecorder() . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"initialize-microphone"},{"location":"plugins/initialize-microphone/#parameters","text":"In addition to the 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 device_select_message html string <p>Please select the microphone you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this microphone.' The label for the select button.","title":"Parameters"},{"location":"plugins/initialize-microphone/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected microphone.","title":"Data Generated"},{"location":"plugins/initialize-microphone/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/initialize-microphone/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-microphone@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-microphone.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-microphone import initializeMicrophone from '@jspsych/plugin-initialize-microphone' ;","title":"Install"},{"location":"plugins/initialize-microphone/#examples","text":"Ask for microphone permission Code Demo var trial = { type : jsPsychInitializeMicrophone }; Open demo in new tab","title":"Examples"},{"location":"plugins/instructions/","text":"instructions \u00b6 Current version: 1.1.2. See version history . This plugin is for showing instructions to the participant. It allows participants to navigate through multiple pages of instructions at their own pace, recording how long the participant spends on each page. Navigation can be done using the mouse or keyboard. participants can be allowed to navigate forwards and backwards through pages, if desired. Parameters \u00b6 In addition to the 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 string 'ArrowRight' This is the key that the participant 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 participant 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 participant 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 participant 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. Participants 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value view_history array An array containing the order of pages the participant viewed (including when the participant returned to previous pages) and the time spent viewing each page. Each object in the array represents a single page view, and contains keys called page_index (the page number, starting with 0) and viewing_time (duration of the page view). This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to view all of the pages. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-instructions@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-instructions.js\" >< /script> Using NPM: npm install @jspsych/plugin-instructions import instructions from '@jspsych/plugin-instructions' ; Examples \u00b6 Showing simple text instructions \u00b6 Showing simple text instructions Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], show_clickable_nav : true } Open demo in new tab Including images \u00b6 Including Images Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'You will be looking at images of arrows: ' + '<br>' + '<img src=\"con2.png\"></img>' ], show_clickable_nav : true } Open demo in new tab Changing Button Text \u00b6 Changing Button Text Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], button_label_next : \"Continue\" , button_label_previous : \"Return to the dark side\" , show_clickable_nav : true } Open demo in new tab","title":"instructions"},{"location":"plugins/instructions/#instructions","text":"Current version: 1.1.2. See version history . This plugin is for showing instructions to the participant. It allows participants to navigate through multiple pages of instructions at their own pace, recording how long the participant spends on each page. Navigation can be done using the mouse or keyboard. participants can be allowed to navigate forwards and backwards through pages, if desired.","title":"instructions"},{"location":"plugins/instructions/#parameters","text":"In addition to the 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 string 'ArrowRight' This is the key that the participant 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 participant 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 participant 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 participant 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. Participants 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.","title":"Parameters"},{"location":"plugins/instructions/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value view_history array An array containing the order of pages the participant viewed (including when the participant returned to previous pages) and the time spent viewing each page. Each object in the array represents a single page view, and contains keys called page_index (the page number, starting with 0) and viewing_time (duration of the page view). This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to view all of the pages.","title":"Data Generated"},{"location":"plugins/instructions/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-instructions@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-instructions.js\" >< /script> Using NPM: npm install @jspsych/plugin-instructions import instructions from '@jspsych/plugin-instructions' ;","title":"Install"},{"location":"plugins/instructions/#examples","text":"","title":"Examples"},{"location":"plugins/instructions/#showing-simple-text-instructions","text":"Showing simple text instructions Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], show_clickable_nav : true } Open demo in new tab","title":"Showing simple text instructions"},{"location":"plugins/instructions/#including-images","text":"Including Images Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'You will be looking at images of arrows: ' + '<br>' + '<img src=\"con2.png\"></img>' ], show_clickable_nav : true } Open demo in new tab","title":"Including images"},{"location":"plugins/instructions/#changing-button-text","text":"Changing Button Text Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], button_label_next : \"Continue\" , button_label_previous : \"Return to the dark side\" , show_clickable_nav : true } Open demo in new tab","title":"Changing Button Text"},{"location":"plugins/list-of-plugins/","text":"List of Plugins \u00b6 These are the plugins that are included in the jsPsych release. Additional plugins may be available in the community contributions repository . For an overview of what plugins are and how they work, see our plugins overview . Plugin Description animation Shows a sequence of images at a specified frame rate. Records key presses (including timing information) made by the participant while they are viewing the animation. audio\u2011button\u2011response Play an audio file and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. audio\u2011keyboard\u2011response Play an audio file and allow the participant to respond by pressing a key. audio\u2011slider\u2011response Play an audio file and allow the participant to respond by moving a slider to indicate a value. browser\u2011check Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. call\u2011function Executes an arbitrary function call. Doesn't display anything to the participant, and the participant is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. canvas\u2011button\u2011response Draw a stimulus on a HTML canvas element , and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011keyboard\u2011response Draw a stimulus on a HTML canvas element , and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011slider\u2011response Draw a stimulus on a HTML canvas element , and ask the participant to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). categorize\u2011animation The participant responds to an animation and can be given feedback about their response. categorize\u2011html The participant responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response. categorize\u2011image The participant responds to an image using the keyboard and can be given feedback about the correctness of their response. cloze Plugin for displaying a cloze test and checking participants answers against a correct solution. external\u2011html Displays an external HTML page (such as a consent form) and lets the participant respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a participant has granted consent before starting the experiment. free\u2011sort Displays a set of images on the screen in random locations. Participants can click and drag the images to move them around the screen. Records all the moves made by the participant, so the sequence of moves can be recovered from the data. fullscreen Toggles the experiment in and out of fullscreen mode. html\u2011audio\u2011response Display an HTML-formatted stimulus and records an audio response via a microphone. html\u2011button\u2011response Display an HTML-formatted stimulus and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. html\u2011keyboard\u2011response Display an HTML-formatted stimulus and allow the participant to respond by pressing a key. html\u2011slider\u2011response Display an HTML-formatted stimulus and allow the participant to respond by moving a slider to indicate a value. html\u2011video\u2011response Display an HTML-formatted stimulus and records video data via a webcam. iat\u2011html The implicit association task, using HTML-formatted stimuli. iat\u2011image The implicit association task, using images as stimuli. image\u2011button\u2011response Display an image and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. image\u2011keyboard\u2011response Display an image and allow the participant to respond by pressing a key. image\u2011slider\u2011response Display an image and allow the participant to respond by moving a slider to indicate a value. initialize\u2011camera Request permission to use the participant's camera to record video and allows the participant to choose which camera to use if multiple devices are enabled. Also allows setting the mime type of the recorded video. initialize\u2011microphone Request permission to use the participant's microphone to record audio and allows the participant to choose which microphone to use if multiple devices are enabled. instructions For displaying instructions to the participant. Allows the participant to navigate between pages of instructions using keys or buttons. maxdiff Displays rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. mirror\u2011camera Shows a live feed of the participant's camera on the screen. preload This plugin loads images, audio, and video files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and to avoid disrupting the flow of the experiment. reconstruction The participant interacts with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. resize Calibrate the display so that materials display with a known physical size. same\u2011different\u2011html A same-different judgment task. An HTML-formatted stimulus is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. same\u2011different\u2011image A same-different judgment task. An image is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. serial\u2011reaction\u2011time A set of boxes are displayed on the screen and one of them changes color. The participant presses a key that corresponds to the different color box as fast as possible. serial\u2011reaction\u2011time\u2011mouse A set of boxes are displayed on the screen and one of them changes color. The participants clicks the box that changed color as fast as possible. sketchpad Creates an interactive canvas that the participant can draw on using their mouse or touchscreen. survey\u2011html\u2011form Renders a custom HTML form. Allows for mixing multiple kinds of form input. survey\u2011likert Displays likert-style questions. survey\u2011multi\u2011choice Displays multiple choice questions with one answer allowed per question. survey\u2011multi\u2011select Displays multiple choice questions with multiple answes allowed per question. survey\u2011text Shows a prompt with a text box. The participant writes a response and then submits by clicking a button. video\u2011button\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a button. video\u2011keyboard\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a key. video\u2011slider\u2011response Displays a video file with many options for customizing playback. participant responds to the video by moving a slider. virtual\u2011chinrest An implementation of the \"virutal chinrest\" procedure developed by Li, Joo, Yeatman, and Reinecke (2020) . Calibrates the monitor to display items at a known physical size by having participants scale an image to be the same size as a physical credit card. Then uses a blind spot task to estimate the distance between the participant and the display. visual\u2011search\u2011circle A customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. webgazer\u2011calibrate Calibrates the WebGazer extension for eye tracking. webgazer\u2011init\u2011camera Initializes the camera and helps the participant center their face for eye tracking. webgazer\u2011validate Performs validation to measure precision and accuracy of WebGazer eye tracking predictions.","title":"List of Plugins"},{"location":"plugins/list-of-plugins/#list-of-plugins","text":"These are the plugins that are included in the jsPsych release. Additional plugins may be available in the community contributions repository . For an overview of what plugins are and how they work, see our plugins overview . Plugin Description animation Shows a sequence of images at a specified frame rate. Records key presses (including timing information) made by the participant while they are viewing the animation. audio\u2011button\u2011response Play an audio file and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. audio\u2011keyboard\u2011response Play an audio file and allow the participant to respond by pressing a key. audio\u2011slider\u2011response Play an audio file and allow the participant to respond by moving a slider to indicate a value. browser\u2011check Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. call\u2011function Executes an arbitrary function call. Doesn't display anything to the participant, and the participant is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. canvas\u2011button\u2011response Draw a stimulus on a HTML canvas element , and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011keyboard\u2011response Draw a stimulus on a HTML canvas element , and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011slider\u2011response Draw a stimulus on a HTML canvas element , and ask the participant to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). categorize\u2011animation The participant responds to an animation and can be given feedback about their response. categorize\u2011html The participant responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response. categorize\u2011image The participant responds to an image using the keyboard and can be given feedback about the correctness of their response. cloze Plugin for displaying a cloze test and checking participants answers against a correct solution. external\u2011html Displays an external HTML page (such as a consent form) and lets the participant respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a participant has granted consent before starting the experiment. free\u2011sort Displays a set of images on the screen in random locations. Participants can click and drag the images to move them around the screen. Records all the moves made by the participant, so the sequence of moves can be recovered from the data. fullscreen Toggles the experiment in and out of fullscreen mode. html\u2011audio\u2011response Display an HTML-formatted stimulus and records an audio response via a microphone. html\u2011button\u2011response Display an HTML-formatted stimulus and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. html\u2011keyboard\u2011response Display an HTML-formatted stimulus and allow the participant to respond by pressing a key. html\u2011slider\u2011response Display an HTML-formatted stimulus and allow the participant to respond by moving a slider to indicate a value. html\u2011video\u2011response Display an HTML-formatted stimulus and records video data via a webcam. iat\u2011html The implicit association task, using HTML-formatted stimuli. iat\u2011image The implicit association task, using images as stimuli. image\u2011button\u2011response Display an image and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. image\u2011keyboard\u2011response Display an image and allow the participant to respond by pressing a key. image\u2011slider\u2011response Display an image and allow the participant to respond by moving a slider to indicate a value. initialize\u2011camera Request permission to use the participant's camera to record video and allows the participant to choose which camera to use if multiple devices are enabled. Also allows setting the mime type of the recorded video. initialize\u2011microphone Request permission to use the participant's microphone to record audio and allows the participant to choose which microphone to use if multiple devices are enabled. instructions For displaying instructions to the participant. Allows the participant to navigate between pages of instructions using keys or buttons. maxdiff Displays rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. mirror\u2011camera Shows a live feed of the participant's camera on the screen. preload This plugin loads images, audio, and video files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and to avoid disrupting the flow of the experiment. reconstruction The participant interacts with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. resize Calibrate the display so that materials display with a known physical size. same\u2011different\u2011html A same-different judgment task. An HTML-formatted stimulus is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. same\u2011different\u2011image A same-different judgment task. An image is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. serial\u2011reaction\u2011time A set of boxes are displayed on the screen and one of them changes color. The participant presses a key that corresponds to the different color box as fast as possible. serial\u2011reaction\u2011time\u2011mouse A set of boxes are displayed on the screen and one of them changes color. The participants clicks the box that changed color as fast as possible. sketchpad Creates an interactive canvas that the participant can draw on using their mouse or touchscreen. survey\u2011html\u2011form Renders a custom HTML form. Allows for mixing multiple kinds of form input. survey\u2011likert Displays likert-style questions. survey\u2011multi\u2011choice Displays multiple choice questions with one answer allowed per question. survey\u2011multi\u2011select Displays multiple choice questions with multiple answes allowed per question. survey\u2011text Shows a prompt with a text box. The participant writes a response and then submits by clicking a button. video\u2011button\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a button. video\u2011keyboard\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a key. video\u2011slider\u2011response Displays a video file with many options for customizing playback. participant responds to the video by moving a slider. virtual\u2011chinrest An implementation of the \"virutal chinrest\" procedure developed by Li, Joo, Yeatman, and Reinecke (2020) . Calibrates the monitor to display items at a known physical size by having participants scale an image to be the same size as a physical credit card. Then uses a blind spot task to estimate the distance between the participant and the display. visual\u2011search\u2011circle A customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. webgazer\u2011calibrate Calibrates the WebGazer extension for eye tracking. webgazer\u2011init\u2011camera Initializes the camera and helps the participant center their face for eye tracking. webgazer\u2011validate Performs validation to measure precision and accuracy of WebGazer eye tracking predictions.","title":"List of Plugins"},{"location":"plugins/maxdiff/","text":"maxdiff \u00b6 Current version: 1.1.2. See version history . The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously. Parameters \u00b6 In addition to the 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 alternatives array undefined An array of one or more alternatives of string type to fill the rows of the maxdiff table. If required is true, then the array must contain two or more alternatives, so that at least one can be selected for both the left and right columns. labels array undefined An array with exactly two labels of string type to display as column headings (to the left and right of the alternatives) for responses on the criteria of interest. randomize_alternative_order boolean false If true, the display order of alternatives is randomly determined at the start of the trial. preamble string empty string HTML formatted string to display at the top of the page above the maxdiff table. required boolean false If true, prevents the user from submitting the response and proceeding until a radio button in both the left and right response columns has been selected. button_label string 'Continue' Label of the button. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the maxdiff table first appears on the screen until the participant's response. labels object An object with two keys, left and right , containing the labels (strings) corresponding to the left and right response columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response object An object with two keys, left and right , containing the alternatives selected on the left and right columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-maxdiff@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-maxdiff.js\" >< /script> Using NPM: npm install @jspsych/plugin-maxdiff import maxdiff from '@jspsych/plugin-maxdiff' ; Examples \u00b6 Basic example Code Demo var maxdiff_page = { type : jsPsychMaxdiff , alternatives : [ 'apple' , 'orange' , 'pear' , 'banana' ], labels : [ 'Most Preferred' , 'Least Preferred' ], preamble : '<p> Please select your <b>most preferred</b> and <b>least preferred</b> fruits. </p>' }; Open demo in new tab","title":"maxdiff"},{"location":"plugins/maxdiff/#maxdiff","text":"Current version: 1.1.2. See version history . The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously.","title":"maxdiff"},{"location":"plugins/maxdiff/#parameters","text":"In addition to the 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 alternatives array undefined An array of one or more alternatives of string type to fill the rows of the maxdiff table. If required is true, then the array must contain two or more alternatives, so that at least one can be selected for both the left and right columns. labels array undefined An array with exactly two labels of string type to display as column headings (to the left and right of the alternatives) for responses on the criteria of interest. randomize_alternative_order boolean false If true, the display order of alternatives is randomly determined at the start of the trial. preamble string empty string HTML formatted string to display at the top of the page above the maxdiff table. required boolean false If true, prevents the user from submitting the response and proceeding until a radio button in both the left and right response columns has been selected. button_label string 'Continue' Label of the button.","title":"Parameters"},{"location":"plugins/maxdiff/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the maxdiff table first appears on the screen until the participant's response. labels object An object with two keys, left and right , containing the labels (strings) corresponding to the left and right response columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response object An object with two keys, left and right , containing the alternatives selected on the left and right columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/maxdiff/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-maxdiff@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-maxdiff.js\" >< /script> Using NPM: npm install @jspsych/plugin-maxdiff import maxdiff from '@jspsych/plugin-maxdiff' ;","title":"Install"},{"location":"plugins/maxdiff/#examples","text":"Basic example Code Demo var maxdiff_page = { type : jsPsychMaxdiff , alternatives : [ 'apple' , 'orange' , 'pear' , 'banana' ], labels : [ 'Most Preferred' , 'Least Preferred' ], preamble : '<p> Please select your <b>most preferred</b> and <b>least preferred</b> fruits. </p>' }; Open demo in new tab","title":"Examples"},{"location":"plugins/mirror-camera/","text":"mirror-camera \u00b6 Current version: 1.0.0 See version history . This plugin shows a live feed of the participant's camera. It can be useful in experiments that need to record video in order to give the participant a chance to see what is in the view of the camera. You must initialize the camera using the initialize-camera plugin prior to running this plugin. Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems . Parameters \u00b6 In addition to the 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 prompt html string null HTML-formatted content to display below the camera feed. width int null The width of the video playback element. If left null then it will match the size of the recording. height int null The height of the video playback element. If left null then it will match the size of the recording. button_label string \"Continue\" The label of the button to advance to the next trial. mirror_camera bool true Whether to mirror the video image. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time the participant viewed the video playback. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-mirror-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-mirror-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-mirror-camera import mirrorCamera from '@jspsych/plugin-mirror-camera' ; Examples \u00b6 Show the camera feed Code Demo const init_camera = { type : jsPsychInitializeCamera , } const mirror_camera = { type : jsPsychMirrorCamera , } Open demo in new tab","title":"mirror-camera"},{"location":"plugins/mirror-camera/#mirror-camera","text":"Current version: 1.0.0 See version history . This plugin shows a live feed of the participant's camera. It can be useful in experiments that need to record video in order to give the participant a chance to see what is in the view of the camera. You must initialize the camera using the initialize-camera plugin prior to running this plugin. Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems .","title":"mirror-camera"},{"location":"plugins/mirror-camera/#parameters","text":"In addition to the 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 prompt html string null HTML-formatted content to display below the camera feed. width int null The width of the video playback element. If left null then it will match the size of the recording. height int null The height of the video playback element. If left null then it will match the size of the recording. button_label string \"Continue\" The label of the button to advance to the next trial. mirror_camera bool true Whether to mirror the video image.","title":"Parameters"},{"location":"plugins/mirror-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time the participant viewed the video playback.","title":"Data Generated"},{"location":"plugins/mirror-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/mirror-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-mirror-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-mirror-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-mirror-camera import mirrorCamera from '@jspsych/plugin-mirror-camera' ;","title":"Install"},{"location":"plugins/mirror-camera/#examples","text":"Show the camera feed Code Demo const init_camera = { type : jsPsychInitializeCamera , } const mirror_camera = { type : jsPsychMirrorCamera , } Open demo in new tab","title":"Examples"},{"location":"plugins/preload/","text":"preload \u00b6 Current version: 1.1.2. See version history . This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the Media Preloading page for more information. The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the max_load_time duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The continue_after_error parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful. Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. While there are no specific parameters that are required, the plugin expects to be given a set of files to load through one or more of the following parameters: auto_preload or trials (for automatic loading), and/or images , audio , video (for manual loading). To automatically load files based on a timeline of trials, either set the auto_preload parameter is true (to load files based on the main timeline passed to jsPsych.run ) or use the trials parameter to load files based on a specific subset of trials. To manually load a set of files, use the images , audio , and video parameters. You can combine automatic and manual loading methods in a single preload trial. All other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description auto_preload boolean false If true , the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to jsPsych.run . If false , any file(s) to be preloaded should be specified by passing a timeline array to the trials parameter and/or an array of file paths to the images , audio , and/or video parameters. Setting this parameter to false is useful when you plan to preload your files in smaller batches throughout the experiment. trials timeline array [] An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See Creating an Experiment: The Timeline for information on constructing timelines. images array [] Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. audio array [] Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. video array [] Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. message HTML string null HTML-formatted message to show above the progress bar while the files are loading. If null , then no message is shown. show_progress_bar boolean true If true , a progress bar will be shown while the files are loading. If false , no progress bar is shown. continue_after_error boolean false If false , then the experiment will stop during this trial if either (a) one or more of the files fails to load, and/or (b) all files do not finish loading before the max_load_time duration is reached. The trial will display the error_message , as well as the detailed error messages if show_detailed_errors is true . If true , the experiment will continue even if loading fails or times out, and information about loading success/failure will be stored in the trial data (see \"Data Generated\" below). error_message HTML string 'The experiment failed to load.' HTML-formatted message to be shown on the page after loading fails or times out. Only applies when continue_after_error is false . show_detailed_errors boolean false If true , and if continue_after_error is false , then a list of detailed errors will be shown below the error_message . This list will contain the file paths for any files that produced a loading failure, as well as a message indicating that loading timed out, if that was the case. This setting is intended to help the researcher with testing/debugging. If false , and if continue_after_error is false , then only the error_message will be shown if loading fails or times out. max_load_time numeric null Duration to wait, in milliseconds, for all files to load before loading times out. If one or more files has not finished loading within this time limit, then the trial will stop with an error (if continue_after_error is false ), or the trial will end with information about the loading time-out in the trial data (see \"Data Generated\" below). If null , the trial will wait indefinitely for all files to either load or produce an error. on_error function null Function to be called immediately after a file loading request has returned an error. The function receives a single argument, which is the file path that produced the error. This callback is cancelled as soon as the trial ends. See example below. on_success function null Function to be called immediately after a file has successfully loaded. The function receives a single argument, which is the file path that finished loading. This callback is cancelled as soon as the trial ends. See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean If true , then all files loaded successfully within the max_load_time . If false , then one or more file requests returned a failure and/or the file loading did not complete within the max_load_time duration. timeout boolean If true , then the files did not finish loading within the max_load_time duration. If false , then the file loading did not timeout. Note that when the preload trial does not timeout ( timeout: false ), it is still possible for loading to fail ( success: false ). This happens if one or more files fails to load and all file requests trigger either a success or failure event before the max_load_time duration. failed_images array One or more image file paths that produced a loading failure before the trial ended. failed_audio array One or more audio file paths that produced a loading failure before the trial ended. failed_video array One or more video file paths that produced a loading failure before the trial ended. Simulation Mode \u00b6 In visual simulation mode, the plugin will run the trial as if the experiment was running normally. Specifying simulation_options.data will not work in visual mode. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-preload.js\" >< /script> Using NPM: npm install @jspsych/plugin-preload import preload from '@jspsych/plugin-preload' ; Examples \u00b6 Automatically preloading based on other trials Code Demo var preload = { type : jsPsychPreload , auto_preload : true } var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } The stimulus parameter from the image-button-response trials will be automatically preloaded. Open demo in new tab Manually preloading an image Code Demo var preload = { type : jsPsychPreload , images : [ 'img/sad_face_1.jpg' ] } var trial_1 = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Study this face</p> <img src=\"img/sad_face_1.jpg\"></img> ` , choices : [ 'Next' ] } Because the image is embedded inside HTML from the html-button-response plugin, it will not be automatically preloaded. Instead we can preload manually. Open demo in new tab Loading files in batches Code Demo var jsPsych = initJsPsych (); var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } var block_1 = { timeline : [ trial_1 , trial_2 , trial_3 ] } var trial_4 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_1.jpg' , choices : [ 'Next' ] } var trial_5 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_2.jpg' , choices : [ 'Next' ] } var trial_6 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_3.jpg' , choices : [ 'Next' ] } var block_2 = { timeline : [ trial_4 , trial_5 , trial_6 ] } var preload_block_1 = { type : jsPsychPreload , trials : [ block_1 ] } var preload_block_2 = { type : jsPsychPreload , trials : [ block_2 ] } jsPsych . run ([ preload_block_1 , block_1 , preload_block_2 , block_2 ]) You can put trials using the preload plugin throughout your experiment to distribute when files are loaded. In the example above, there are two blocks of trials and the images for each are preloaded just before the corresponding block. Open demo in new tab Showing a detailed error message for debugging loading issues Code Demo var preload = { type : jsPsychPreload , images : [ 'img/bad_file_path.png' ], show_detailed_errors : true } Open demo in new tab For more examples, see the jspsych-preload.html file in the /examples folder of the release and the Media Preloading documentation page.","title":"preload"},{"location":"plugins/preload/#preload","text":"Current version: 1.1.2. See version history . This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the Media Preloading page for more information. The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the max_load_time duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The continue_after_error parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful.","title":"preload"},{"location":"plugins/preload/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. While there are no specific parameters that are required, the plugin expects to be given a set of files to load through one or more of the following parameters: auto_preload or trials (for automatic loading), and/or images , audio , video (for manual loading). To automatically load files based on a timeline of trials, either set the auto_preload parameter is true (to load files based on the main timeline passed to jsPsych.run ) or use the trials parameter to load files based on a specific subset of trials. To manually load a set of files, use the images , audio , and video parameters. You can combine automatic and manual loading methods in a single preload trial. All other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description auto_preload boolean false If true , the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to jsPsych.run . If false , any file(s) to be preloaded should be specified by passing a timeline array to the trials parameter and/or an array of file paths to the images , audio , and/or video parameters. Setting this parameter to false is useful when you plan to preload your files in smaller batches throughout the experiment. trials timeline array [] An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See Creating an Experiment: The Timeline for information on constructing timelines. images array [] Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. audio array [] Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. video array [] Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. message HTML string null HTML-formatted message to show above the progress bar while the files are loading. If null , then no message is shown. show_progress_bar boolean true If true , a progress bar will be shown while the files are loading. If false , no progress bar is shown. continue_after_error boolean false If false , then the experiment will stop during this trial if either (a) one or more of the files fails to load, and/or (b) all files do not finish loading before the max_load_time duration is reached. The trial will display the error_message , as well as the detailed error messages if show_detailed_errors is true . If true , the experiment will continue even if loading fails or times out, and information about loading success/failure will be stored in the trial data (see \"Data Generated\" below). error_message HTML string 'The experiment failed to load.' HTML-formatted message to be shown on the page after loading fails or times out. Only applies when continue_after_error is false . show_detailed_errors boolean false If true , and if continue_after_error is false , then a list of detailed errors will be shown below the error_message . This list will contain the file paths for any files that produced a loading failure, as well as a message indicating that loading timed out, if that was the case. This setting is intended to help the researcher with testing/debugging. If false , and if continue_after_error is false , then only the error_message will be shown if loading fails or times out. max_load_time numeric null Duration to wait, in milliseconds, for all files to load before loading times out. If one or more files has not finished loading within this time limit, then the trial will stop with an error (if continue_after_error is false ), or the trial will end with information about the loading time-out in the trial data (see \"Data Generated\" below). If null , the trial will wait indefinitely for all files to either load or produce an error. on_error function null Function to be called immediately after a file loading request has returned an error. The function receives a single argument, which is the file path that produced the error. This callback is cancelled as soon as the trial ends. See example below. on_success function null Function to be called immediately after a file has successfully loaded. The function receives a single argument, which is the file path that finished loading. This callback is cancelled as soon as the trial ends. See example below.","title":"Parameters"},{"location":"plugins/preload/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean If true , then all files loaded successfully within the max_load_time . If false , then one or more file requests returned a failure and/or the file loading did not complete within the max_load_time duration. timeout boolean If true , then the files did not finish loading within the max_load_time duration. If false , then the file loading did not timeout. Note that when the preload trial does not timeout ( timeout: false ), it is still possible for loading to fail ( success: false ). This happens if one or more files fails to load and all file requests trigger either a success or failure event before the max_load_time duration. failed_images array One or more image file paths that produced a loading failure before the trial ended. failed_audio array One or more audio file paths that produced a loading failure before the trial ended. failed_video array One or more video file paths that produced a loading failure before the trial ended.","title":"Data Generated"},{"location":"plugins/preload/#simulation-mode","text":"In visual simulation mode, the plugin will run the trial as if the experiment was running normally. Specifying simulation_options.data will not work in visual mode.","title":"Simulation Mode"},{"location":"plugins/preload/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-preload.js\" >< /script> Using NPM: npm install @jspsych/plugin-preload import preload from '@jspsych/plugin-preload' ;","title":"Install"},{"location":"plugins/preload/#examples","text":"Automatically preloading based on other trials Code Demo var preload = { type : jsPsychPreload , auto_preload : true } var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } The stimulus parameter from the image-button-response trials will be automatically preloaded. Open demo in new tab Manually preloading an image Code Demo var preload = { type : jsPsychPreload , images : [ 'img/sad_face_1.jpg' ] } var trial_1 = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Study this face</p> <img src=\"img/sad_face_1.jpg\"></img> ` , choices : [ 'Next' ] } Because the image is embedded inside HTML from the html-button-response plugin, it will not be automatically preloaded. Instead we can preload manually. Open demo in new tab Loading files in batches Code Demo var jsPsych = initJsPsych (); var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } var block_1 = { timeline : [ trial_1 , trial_2 , trial_3 ] } var trial_4 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_1.jpg' , choices : [ 'Next' ] } var trial_5 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_2.jpg' , choices : [ 'Next' ] } var trial_6 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_3.jpg' , choices : [ 'Next' ] } var block_2 = { timeline : [ trial_4 , trial_5 , trial_6 ] } var preload_block_1 = { type : jsPsychPreload , trials : [ block_1 ] } var preload_block_2 = { type : jsPsychPreload , trials : [ block_2 ] } jsPsych . run ([ preload_block_1 , block_1 , preload_block_2 , block_2 ]) You can put trials using the preload plugin throughout your experiment to distribute when files are loaded. In the example above, there are two blocks of trials and the images for each are preloaded just before the corresponding block. Open demo in new tab Showing a detailed error message for debugging loading issues Code Demo var preload = { type : jsPsychPreload , images : [ 'img/bad_file_path.png' ], show_detailed_errors : true } Open demo in new tab For more examples, see the jspsych-preload.html file in the /examples folder of the release and the Media Preloading documentation page.","title":"Examples"},{"location":"plugins/reconstruction/","text":"reconstruction \u00b6 Current version: 1.1.2. See version history . This plugin allows a participant to interact with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a single value, which is the parameter that can be modified by the participant. The value can only range from 0 to 1. See the example at the bottom of the page for a sample function. Parameters \u00b6 In addition to the 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 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 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value start_value numeric The starting value of the stimulus parameter. final_value numeric The final value of the stimulus parameter. rt numeric The length of time, in milliseconds, that the trial lasted. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-reconstruction@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-reconstruction.js\" >< /script> Using NPM: npm install @jspsych/plugin-reconstruction import reconstruction from '@jspsych/plugin-reconstruction' ; Examples \u00b6 Make a block larger and smaller Code Demo var sample_function = function ( param ){ var size = 50 + Math . floor ( param * 250 ); var html = '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - size / 2 ) + 'px; left:' + ( 150 - size / 2 ) + 'px; background-color: #000000; ' + 'width: ' + size + 'px; height: ' + size + 'px;\"></div></div><p>Press \"h\" to make the square larger. Press \"g\" to make the square smaller.</p>' + '<p>When the square is the same size as the previous one, click Continue.</p>' ; return html ; } var match_item = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - 210 / 2 ) + 'px; left:' + ( 150 - 210 / 2 ) + 'px; background-color: #000000; ' + 'width: 210px; height: 210px;\"></div></div>' , choices : [ 'c' ], post_trial_gap : 1250 , prompt : '<p>Study the size of this square carefully. On the next screen you will have to recreate it. When you are ready, press \"c\".</p>' } var reconstruction = { type : jsPsychReconstruction , stim_function : sample_function , starting_value : 0.5 , } Open demo in new tab","title":"reconstruction"},{"location":"plugins/reconstruction/#reconstruction","text":"Current version: 1.1.2. See version history . This plugin allows a participant to interact with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a single value, which is the parameter that can be modified by the participant. The value can only range from 0 to 1. See the example at the bottom of the page for a sample function.","title":"reconstruction"},{"location":"plugins/reconstruction/#parameters","text":"In addition to the 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 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 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.","title":"Parameters"},{"location":"plugins/reconstruction/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value start_value numeric The starting value of the stimulus parameter. final_value numeric The final value of the stimulus parameter. rt numeric The length of time, in milliseconds, that the trial lasted.","title":"Data Generated"},{"location":"plugins/reconstruction/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-reconstruction@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-reconstruction.js\" >< /script> Using NPM: npm install @jspsych/plugin-reconstruction import reconstruction from '@jspsych/plugin-reconstruction' ;","title":"Install"},{"location":"plugins/reconstruction/#examples","text":"Make a block larger and smaller Code Demo var sample_function = function ( param ){ var size = 50 + Math . floor ( param * 250 ); var html = '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - size / 2 ) + 'px; left:' + ( 150 - size / 2 ) + 'px; background-color: #000000; ' + 'width: ' + size + 'px; height: ' + size + 'px;\"></div></div><p>Press \"h\" to make the square larger. Press \"g\" to make the square smaller.</p>' + '<p>When the square is the same size as the previous one, click Continue.</p>' ; return html ; } var match_item = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - 210 / 2 ) + 'px; left:' + ( 150 - 210 / 2 ) + 'px; background-color: #000000; ' + 'width: 210px; height: 210px;\"></div></div>' , choices : [ 'c' ], post_trial_gap : 1250 , prompt : '<p>Study the size of this square carefully. On the next screen you will have to recreate it. When you are ready, press \"c\".</p>' } var reconstruction = { type : jsPsychReconstruction , stim_function : sample_function , starting_value : 0.5 , } Open demo in new tab","title":"Examples"},{"location":"plugins/resize/","text":"resize \u00b6 Current version: 1.0.2. See version history . This plugin displays a resizable div container that allows the user to drag until the container is the same size as the item being measured. Once the user measures the item as close as possible, clicking the button sets a scaling factor for the div containing jsPsych content. This causes the stimuli that follow to have a known size, independent of monitor resolution. Parameters \u00b6 In addition to the 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 item_height numeric 1 The height of the item to be measured. Any units can be used as long as you are consistent with using the same units for all parameters. item_width numeric 1 The width of the item to be measured. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement. prompt string '' HTML content to display below the resizable box, and above the button. button_label string 'Continue' Label to display on the button to complete calibration. starting_size numeric 100 The initial size of the box, in pixels, along the largest dimension. The aspect ratio will be set automatically to match the item width and height. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value final_width_px numeric Final width of the resizable div container, in pixels. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-resize@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-resize.js\" >< /script> Using NPM: npm install @jspsych/plugin-resize import resize from '@jspsych/plugin-resize' ; Examples \u00b6 Measuring a credit card and resizing the display to have 150 pixels equal an inch. Code Demo var inputs = { type : jsPsychResize , item_width : 3 + 3 / 8 , item_height : 2 + 1 / 8 , prompt : \"<p>Click and drag the lower right corner of the box until the box is the same size as a credit card held up to the screen.</p>\" , pixels_per_unit : 150 }; Open demo in new tab","title":"resize"},{"location":"plugins/resize/#resize","text":"Current version: 1.0.2. See version history . This plugin displays a resizable div container that allows the user to drag until the container is the same size as the item being measured. Once the user measures the item as close as possible, clicking the button sets a scaling factor for the div containing jsPsych content. This causes the stimuli that follow to have a known size, independent of monitor resolution.","title":"resize"},{"location":"plugins/resize/#parameters","text":"In addition to the 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 item_height numeric 1 The height of the item to be measured. Any units can be used as long as you are consistent with using the same units for all parameters. item_width numeric 1 The width of the item to be measured. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement. prompt string '' HTML content to display below the resizable box, and above the button. button_label string 'Continue' Label to display on the button to complete calibration. starting_size numeric 100 The initial size of the box, in pixels, along the largest dimension. The aspect ratio will be set automatically to match the item width and height.","title":"Parameters"},{"location":"plugins/resize/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value final_width_px numeric Final width of the resizable div container, in pixels. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content.","title":"Data Generated"},{"location":"plugins/resize/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/resize/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-resize@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-resize.js\" >< /script> Using NPM: npm install @jspsych/plugin-resize import resize from '@jspsych/plugin-resize' ;","title":"Install"},{"location":"plugins/resize/#examples","text":"Measuring a credit card and resizing the display to have 150 pixels equal an inch. Code Demo var inputs = { type : jsPsychResize , item_width : 3 + 3 / 8 , item_height : 2 + 1 / 8 , prompt : \"<p>Click and drag the lower right corner of the box until the box is the same size as a credit card held up to the screen.</p>\" , pixels_per_unit : 150 }; Open demo in new tab","title":"Examples"},{"location":"plugins/same-different-html/","text":"same-different-html \u00b6 Current version: 1.1.2. See version history . The same-different-html plugin displays two stimuli sequentially. Stimuli are HTML objects. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example. Parameters \u00b6 In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the HTML-formatted content that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-html import sameDifferentHtml from '@jspsych/plugin-same-different-html' ; Examples \u00b6 Two text choices Code Demo var trial = { type : jsPsychSameDifferentHtml , stimuli : [ '<p style=\"font-size:30px;\">Climbing</p>' , '<p style=\"font-size:30px;\">Walking</p>' ], prompt : `<p>Press 's' if the activities require the same amount of physical exertion.</p> <p>Press 'd' if the activities require different amount of physical exertion.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"same-different-html"},{"location":"plugins/same-different-html/#same-different-html","text":"Current version: 1.1.2. See version history . The same-different-html plugin displays two stimuli sequentially. Stimuli are HTML objects. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example.","title":"same-different-html"},{"location":"plugins/same-different-html/#parameters","text":"In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press).","title":"Parameters"},{"location":"plugins/same-different-html/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the HTML-formatted content that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue.","title":"Data Generated"},{"location":"plugins/same-different-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-html import sameDifferentHtml from '@jspsych/plugin-same-different-html' ;","title":"Install"},{"location":"plugins/same-different-html/#examples","text":"Two text choices Code Demo var trial = { type : jsPsychSameDifferentHtml , stimuli : [ '<p style=\"font-size:30px;\">Climbing</p>' , '<p style=\"font-size:30px;\">Walking</p>' ], prompt : `<p>Press 's' if the activities require the same amount of physical exertion.</p> <p>Press 'd' if the activities require different amount of physical exertion.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"Examples"},{"location":"plugins/same-different-image/","text":"same-different-image \u00b6 Current version: 1.1.2. See version history . The same-different-image plugin displays two stimuli sequentially. Stimuli are images. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example. Parameters \u00b6 In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the paths to the image files that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-image import sameDifferentImage from '@jspsych/plugin-same-different-image' ; Examples \u00b6 Identifying emotional expressions Code Demo var trial = { type : jsPsychSameDifferentImage , stimuli : [ 'img/happy_face_1.jpg' , 'img/sad_face_3.jpg' ], prompt : `<p>Press s if the faces had the same emotional expression.</p> <p>Press d if the faces had different emotional expressions.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"same-different-image"},{"location":"plugins/same-different-image/#same-different-image","text":"Current version: 1.1.2. See version history . The same-different-image plugin displays two stimuli sequentially. Stimuli are images. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example.","title":"same-different-image"},{"location":"plugins/same-different-image/#parameters","text":"In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press).","title":"Parameters"},{"location":"plugins/same-different-image/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the paths to the image files that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue.","title":"Data Generated"},{"location":"plugins/same-different-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-image import sameDifferentImage from '@jspsych/plugin-same-different-image' ;","title":"Install"},{"location":"plugins/same-different-image/#examples","text":"Identifying emotional expressions Code Demo var trial = { type : jsPsychSameDifferentImage , stimuli : [ 'img/happy_face_1.jpg' , 'img/sad_face_3.jpg' ], prompt : `<p>Press s if the faces had the same emotional expression.</p> <p>Press d if the faces had different emotional expressions.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"Examples"},{"location":"plugins/serial-reaction-time-mouse/","text":"serial-reaction-time-mouse \u00b6 Current version: 1.1.2. See version history . The serial reaction time mouse plugin implements a generalized version of the SRT task (Nissen & Bullmer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant must click on the square that changes color. Parameters \u00b6 In addition to the 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. 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 mouse click. 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. 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. allow_nontarget_responses boolean false If true, the user can make nontarget response. 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 participant is supposed to take (e.g., which keys to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The grid representation. Each inner array represents a single row. The entries in the inner arrays represent the columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The [row, column] target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. response array The [row, column] response location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. correct boolean Whether the response location matches the target location ( true ) or not ( false ). Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time-mouse@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time-mouse.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time-mouse import serialReactionTimeMouse from '@jspsych/plugin-serial-reaction-time-mouse' ; Examples \u00b6 A classic version of the SRT Code Demo var grid = [ [ 1 , 1 , 1 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 3 ] } Open demo in new tab A 2x2 grid with extra space and different colors Code Demo var grid = [ [ 1 , 0 , 1 ], [ 0 , 0 , 0 ], [ 1 , 0 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ], target_color : '#006738' } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ], target_color : '#F78F1E' } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 2 ], target_color : '#13B24B' } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 0 ], target_color : '#E74921' } Open demo in new tab","title":"serial-reaction-time-mouse"},{"location":"plugins/serial-reaction-time-mouse/#serial-reaction-time-mouse","text":"Current version: 1.1.2. See version history . The serial reaction time mouse plugin implements a generalized version of the SRT task (Nissen & Bullmer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant must click on the square that changes color.","title":"serial-reaction-time-mouse"},{"location":"plugins/serial-reaction-time-mouse/#parameters","text":"In addition to the 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. 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 mouse click. 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. 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. allow_nontarget_responses boolean false If true, the user can make nontarget response. 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 participant is supposed to take (e.g., which keys to press).","title":"Parameters"},{"location":"plugins/serial-reaction-time-mouse/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The grid representation. Each inner array represents a single row. The entries in the inner arrays represent the columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The [row, column] target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. response array The [row, column] response location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. correct boolean Whether the response location matches the target location ( true ) or not ( false ).","title":"Data Generated"},{"location":"plugins/serial-reaction-time-mouse/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time-mouse@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time-mouse.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time-mouse import serialReactionTimeMouse from '@jspsych/plugin-serial-reaction-time-mouse' ;","title":"Install"},{"location":"plugins/serial-reaction-time-mouse/#examples","text":"A classic version of the SRT Code Demo var grid = [ [ 1 , 1 , 1 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 3 ] } Open demo in new tab A 2x2 grid with extra space and different colors Code Demo var grid = [ [ 1 , 0 , 1 ], [ 0 , 0 , 0 ], [ 1 , 0 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ], target_color : '#006738' } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ], target_color : '#F78F1E' } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 2 ], target_color : '#13B24B' } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 0 ], target_color : '#E74921' } Open demo in new tab","title":"Examples"},{"location":"plugins/serial-reaction-time/","text":"serial-reaction-time \u00b6 Current version: 1.1.2. See version history . The serial reaction time plugin implements a generalized version of the SRT task (Nissen & Bullemer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant presses a key that corresponds to the darkened key. Feedback is optionally displayed, showing the participant which square the key they pressed matches. Parameters \u00b6 In addition to the 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 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 participant is supposed to take (e.g., which keys to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The representation of the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The representation of the target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant's response matched the target. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time import serialReactionTime from '@jspsych/plugin-serial-reaction-time' ; Examples \u00b6 A classic SRT Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the S, F, H, and K keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 , 1 , 1 ] ] var response_map = [ [ 's' , 'f' , 'h' , 'k' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 3 ] } Open demo in new tab 2x2 grid with feedback Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the R, I, V, and M keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 ], [ 1 , 1 ] ] var response_map = [ [ 'r' , 'i' ], [ 'v' , 'm' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ], show_response_feedback : true , feedback_duration : 500 } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 0 ], show_response_feedback : true , feedback_duration : 500 } Open demo in new tab","title":"serial-reaction-time"},{"location":"plugins/serial-reaction-time/#serial-reaction-time","text":"Current version: 1.1.2. See version history . The serial reaction time plugin implements a generalized version of the SRT task (Nissen & Bullemer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant presses a key that corresponds to the darkened key. Feedback is optionally displayed, showing the participant which square the key they pressed matches.","title":"serial-reaction-time"},{"location":"plugins/serial-reaction-time/#parameters","text":"In addition to the 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 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 participant is supposed to take (e.g., which keys to press).","title":"Parameters"},{"location":"plugins/serial-reaction-time/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The representation of the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The representation of the target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant's response matched the target.","title":"Data Generated"},{"location":"plugins/serial-reaction-time/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time import serialReactionTime from '@jspsych/plugin-serial-reaction-time' ;","title":"Install"},{"location":"plugins/serial-reaction-time/#examples","text":"A classic SRT Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the S, F, H, and K keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 , 1 , 1 ] ] var response_map = [ [ 's' , 'f' , 'h' , 'k' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 3 ] } Open demo in new tab 2x2 grid with feedback Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the R, I, V, and M keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 ], [ 1 , 1 ] ] var response_map = [ [ 'r' , 'i' ], [ 'v' , 'm' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ], show_response_feedback : true , feedback_duration : 500 } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 0 ], show_response_feedback : true , feedback_duration : 500 } Open demo in new tab","title":"Examples"},{"location":"plugins/sketchpad/","text":"sketchpad \u00b6 Current version: 1.0.3. See version history . This plugin creates an interactive canvas that the participant can draw on using their mouse or touchscreen. It can be used for sketching tasks, like asking the participant to draw a particular object. It can also be used for some image segmentation or annotation tasks by setting the background_image parameter to render an image on the canvas. The plugin stores a base 64 data URL representation of the final image. This can be converted to an image file using online tools or short programs in R , python , or another language of your choice. It also records all of the individual strokes that the participant made during the trial. Warning This plugin generates a lot of data. Each trial can easily add 500kb+ of data to a final JSON output. You can reduce the amount of data generated by turning off storage of the individual stroke data ( save_strokes: false ) or storage of the final image ( save_final_image: false ) if your use case doesn't require that information. If you are going to be collecting a lot of data with this plugin you may want to save your data to your server after each trial and not wait until the end of the experiment to perform a single bulk upload. You can do this by putting data saving code inside the on_data_update event handler . Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. Parameter Type Default Value Description canvas_shape \"rectangle\" or \"circle\" \"rectangle\" The shape of the canvas element. canvas_width int 500 Width of the canvas in pixels when canvas_shape is \"rectangle\" canvas_height int 500 Height of the canvas in pixels when canvas_shape is \"rectangle\" canvas_diameter int 500 Diameter of the canvas in pixels when canvas_shape is \"circle\" canvas_border_width int 0 Width of the canvas border canvas_border_color string \"#000\" Color of the canvas border background_image image path null Path to an image to render as the background of the canvas background_color string \"#fff\" Color of the canvas background. Note that a background_image will render on top of the color. stroke_width int 2 Width of the stroke on the canvas stroke_color string \"#000\" Color of the stroke on the canvas stroke_color_palette array of strings [] Array of colors to render as a palette of choices for stroke color. Clicking on the corresponding color button will change the stroke color. prompt string null HTML content to render on the screen. prompt_location \"abovecanvas\" or \"belowcanvas\" or \"belowbutton\" \"abovecanvas\" The location to render the prompt content. save_final_image bool true Whether to save the final image in the data as a base64 encoded data URL. save_strokes bool true Whether to save the individual stroke data that generated the final image. key_to_draw key string null If this key is held down then it is like the mouse button being held down. The \"ink\" will flow when the button is held and stop when it is lifted. Pass in the string representation of the key, e.g., 'a' for the A key or ' ' for the spacebar. show_finished_button bool true Whether to show the button that ends the trial. finished_button_label string \"Finished\" The label for the button that ends the trial. show_clear_button bool true Whether to show the button that clears the entire drawing. clear_button_label string \"Clear\" The label for the button that clears the entire drawing. show_undo_button bool true Whether to show the button that enables an undo action. undo_button_label string \"Undo\" The label for the button that enables an undo action. show_redo_button bool true Whether to show the button that enables a redo action. Note that show_undo_button must be true for the redo button to show up. redo_button_label string \"Redo\" The label for the button that enables a redo action. choices array of keys \"NO_KEYS\" This array contains the key(s) that the participant is allowed to press in order to end the trial. Keys should be specified as characters (e.g., 'a' , 'q' , ' ' , 'Enter' , 'ArrowDown' ) - see this page and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"NO_KEYS\" means that no keys will be accepted as valid responses. Specifying \"ALL_KEYS\" will mean that all responses are allowed. trial_duration int null Length of time before the trial ends. If null the trial will continue indefinitely (until another way of ending the trial occurs). show_countdown_trial_duration bool false Whether to show a timer that counts down until the end of the trial when trial_duration is not null . countdown_timer_html string '<span id=\"sketchpad-timer\"></span> remaining' The HTML to use for rendering the countdown timer. The element with id=\"sketchpad-timer\" will have its content replaced by a countdown timer in the format MM:SS . Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time from the start of the trial to the end of the trial. response string If the trial was ended by clicking the finished button, then \"button\" . If the trial was ended by pressing a key, then the key that was pressed. If the trial timed out, then null . png base64 data URL string If save_image is true, then this will contain the base64 encoded data URL for the image, in png format. strokes array of stroke objects If save_strokes is true, then this will contain an array of stroke objects. Objects have an action property that is either \"start\" , \"move\" , or \"end\" . If action is \"start\" or \"move\" it will have an x and y property that report the coordinates of the action relative to the upper-left corner of the canvas. If action is \"start\" then the object will also have a t and color property, specifying the time of the action relative to the onset of the trial (ms) and the color of the stroke. If action is \"end\" then it will only have a t property. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-sketchpad@1.0.3\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-sketchpad.js\" >< /script> Using NPM: npm install @jspsych/plugin-sketchpad import sketchpad from '@jspsych/plugin-sketchpad' ; Examples \u00b6 Basic sketchpad with a prompt Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p>Draw an apple!</p>' , prompt_location : 'abovecanvas' , canvas_width : 300 , canvas_height : 300 , canvas_border_width : 2 } Open demo in new tab Image segmentation with different colors Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p style=\"width:380px\">Circle the mouth using red. Circle the eyes using blue.</p>' , prompt_location : 'abovecanvas' , stroke_color_palette : [ 'red' , 'blue' ], stroke_color : 'red' , background_image : 'img/sad_face_4.jpg' , canvas_width : 380 , canvas_height : 252 } Open demo in new tab Draw an image in a time limit, then display the image and ask for a label. Code Demo var draw = { type : jsPsychSketchpad , prompt : '<p>Draw the first animal that comes to mind. You have 30 seconds!</p>' , prompt_location : 'belowcanvas' , trial_duration : 30000 , show_countdown_trial_duration : true , } var label = { type : jsPsychSurveyText , preamble : () => { var imageData = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. png ; return `<img src=\" ${ imageData } \"></img>` ; }, questions : [ { prompt : 'What animal did you draw?' } ] } Open demo in new tab","title":"sketchpad"},{"location":"plugins/sketchpad/#sketchpad","text":"Current version: 1.0.3. See version history . This plugin creates an interactive canvas that the participant can draw on using their mouse or touchscreen. It can be used for sketching tasks, like asking the participant to draw a particular object. It can also be used for some image segmentation or annotation tasks by setting the background_image parameter to render an image on the canvas. The plugin stores a base 64 data URL representation of the final image. This can be converted to an image file using online tools or short programs in R , python , or another language of your choice. It also records all of the individual strokes that the participant made during the trial. Warning This plugin generates a lot of data. Each trial can easily add 500kb+ of data to a final JSON output. You can reduce the amount of data generated by turning off storage of the individual stroke data ( save_strokes: false ) or storage of the final image ( save_final_image: false ) if your use case doesn't require that information. If you are going to be collecting a lot of data with this plugin you may want to save your data to your server after each trial and not wait until the end of the experiment to perform a single bulk upload. You can do this by putting data saving code inside the on_data_update event handler .","title":"sketchpad"},{"location":"plugins/sketchpad/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. Parameter Type Default Value Description canvas_shape \"rectangle\" or \"circle\" \"rectangle\" The shape of the canvas element. canvas_width int 500 Width of the canvas in pixels when canvas_shape is \"rectangle\" canvas_height int 500 Height of the canvas in pixels when canvas_shape is \"rectangle\" canvas_diameter int 500 Diameter of the canvas in pixels when canvas_shape is \"circle\" canvas_border_width int 0 Width of the canvas border canvas_border_color string \"#000\" Color of the canvas border background_image image path null Path to an image to render as the background of the canvas background_color string \"#fff\" Color of the canvas background. Note that a background_image will render on top of the color. stroke_width int 2 Width of the stroke on the canvas stroke_color string \"#000\" Color of the stroke on the canvas stroke_color_palette array of strings [] Array of colors to render as a palette of choices for stroke color. Clicking on the corresponding color button will change the stroke color. prompt string null HTML content to render on the screen. prompt_location \"abovecanvas\" or \"belowcanvas\" or \"belowbutton\" \"abovecanvas\" The location to render the prompt content. save_final_image bool true Whether to save the final image in the data as a base64 encoded data URL. save_strokes bool true Whether to save the individual stroke data that generated the final image. key_to_draw key string null If this key is held down then it is like the mouse button being held down. The \"ink\" will flow when the button is held and stop when it is lifted. Pass in the string representation of the key, e.g., 'a' for the A key or ' ' for the spacebar. show_finished_button bool true Whether to show the button that ends the trial. finished_button_label string \"Finished\" The label for the button that ends the trial. show_clear_button bool true Whether to show the button that clears the entire drawing. clear_button_label string \"Clear\" The label for the button that clears the entire drawing. show_undo_button bool true Whether to show the button that enables an undo action. undo_button_label string \"Undo\" The label for the button that enables an undo action. show_redo_button bool true Whether to show the button that enables a redo action. Note that show_undo_button must be true for the redo button to show up. redo_button_label string \"Redo\" The label for the button that enables a redo action. choices array of keys \"NO_KEYS\" This array contains the key(s) that the participant is allowed to press in order to end the trial. Keys should be specified as characters (e.g., 'a' , 'q' , ' ' , 'Enter' , 'ArrowDown' ) - see this page and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"NO_KEYS\" means that no keys will be accepted as valid responses. Specifying \"ALL_KEYS\" will mean that all responses are allowed. trial_duration int null Length of time before the trial ends. If null the trial will continue indefinitely (until another way of ending the trial occurs). show_countdown_trial_duration bool false Whether to show a timer that counts down until the end of the trial when trial_duration is not null . countdown_timer_html string '<span id=\"sketchpad-timer\"></span> remaining' The HTML to use for rendering the countdown timer. The element with id=\"sketchpad-timer\" will have its content replaced by a countdown timer in the format MM:SS .","title":"Parameters"},{"location":"plugins/sketchpad/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time from the start of the trial to the end of the trial. response string If the trial was ended by clicking the finished button, then \"button\" . If the trial was ended by pressing a key, then the key that was pressed. If the trial timed out, then null . png base64 data URL string If save_image is true, then this will contain the base64 encoded data URL for the image, in png format. strokes array of stroke objects If save_strokes is true, then this will contain an array of stroke objects. Objects have an action property that is either \"start\" , \"move\" , or \"end\" . If action is \"start\" or \"move\" it will have an x and y property that report the coordinates of the action relative to the upper-left corner of the canvas. If action is \"start\" then the object will also have a t and color property, specifying the time of the action relative to the onset of the trial (ms) and the color of the stroke. If action is \"end\" then it will only have a t property.","title":"Data Generated"},{"location":"plugins/sketchpad/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/sketchpad/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-sketchpad@1.0.3\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-sketchpad.js\" >< /script> Using NPM: npm install @jspsych/plugin-sketchpad import sketchpad from '@jspsych/plugin-sketchpad' ;","title":"Install"},{"location":"plugins/sketchpad/#examples","text":"Basic sketchpad with a prompt Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p>Draw an apple!</p>' , prompt_location : 'abovecanvas' , canvas_width : 300 , canvas_height : 300 , canvas_border_width : 2 } Open demo in new tab Image segmentation with different colors Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p style=\"width:380px\">Circle the mouth using red. Circle the eyes using blue.</p>' , prompt_location : 'abovecanvas' , stroke_color_palette : [ 'red' , 'blue' ], stroke_color : 'red' , background_image : 'img/sad_face_4.jpg' , canvas_width : 380 , canvas_height : 252 } Open demo in new tab Draw an image in a time limit, then display the image and ask for a label. Code Demo var draw = { type : jsPsychSketchpad , prompt : '<p>Draw the first animal that comes to mind. You have 30 seconds!</p>' , prompt_location : 'belowcanvas' , trial_duration : 30000 , show_countdown_trial_duration : true , } var label = { type : jsPsychSurveyText , preamble : () => { var imageData = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. png ; return `<img src=\" ${ imageData } \"></img>` ; }, questions : [ { prompt : 'What animal did you draw?' } ] } Open demo in new tab","title":"Examples"},{"location":"plugins/survey-html-form/","text":"survey-html-form \u00b6 Current version: 1.0.2. See version history . The survey-html-form plugin displays a set of <inputs> from a HTML string. The type of input can be freely chosen, for a list of possible input types see the MDN page on inputs . The participant provides answers to the input fields. Parameters \u00b6 In addition to the 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 html string undefined HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The <form> tag must not be included and is generated by the plugin. This string can contain other HTML elements besides the input fields. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. dataAsArray boolean false Retrieve the data as an array e.g. [{name: \"INPUT_NAME\", value: \"INPUT_VALUE\"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. This might be useful if you omit naming your inputs. autofocus string empty string The HTML element ID of a form field to autofocus on. The focused element is the element that will receive keyboard events. For elements like <input type=\"text\"> or <textbox> , autofocus means that the cursor will appear in the text input area when the trial loads. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-html-form@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-html-form.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-html-form import surveyHtmlForm from '@jspsych/plugin-survey-html-form' ; Examples \u00b6 Fill in the blanks Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>How are you feeling <b>right now?</b></p>' , html : '<p> I am feeling <input name=\"first\" type=\"text\" />, <input name=\"second\" type=\"text\" />, and <input name=\"third\" type=\"text\" />.</p>' }; Open demo in new tab Using the autofocus parameter Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>What is your favorite bird?</p>' , html : '<p>My favorite bird is <input type=\"text\" id=\"test-resp-box\" name=\"response\" size=\"10\" /></p>' , autofocus : 'test-resp-box' }; In this example, the browser will focus on the element with the ID test-resp-box when the trial loads. For <input type=\"text\"> elements, this means that the cursor will appear inside the text box. Open demo in new tab","title":"survey-html-form"},{"location":"plugins/survey-html-form/#survey-html-form","text":"Current version: 1.0.2. See version history . The survey-html-form plugin displays a set of <inputs> from a HTML string. The type of input can be freely chosen, for a list of possible input types see the MDN page on inputs . The participant provides answers to the input fields.","title":"survey-html-form"},{"location":"plugins/survey-html-form/#parameters","text":"In addition to the 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 html string undefined HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The <form> tag must not be included and is generated by the plugin. This string can contain other HTML elements besides the input fields. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. dataAsArray boolean false Retrieve the data as an array e.g. [{name: \"INPUT_NAME\", value: \"INPUT_VALUE\"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. This might be useful if you omit naming your inputs. autofocus string empty string The HTML element ID of a form field to autofocus on. The focused element is the element that will receive keyboard events. For elements like <input type=\"text\"> or <textbox> , autofocus means that the cursor will appear in the text input area when the trial loads. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-html-form/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response.","title":"Data Generated"},{"location":"plugins/survey-html-form/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/survey-html-form/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-html-form@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-html-form.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-html-form import surveyHtmlForm from '@jspsych/plugin-survey-html-form' ;","title":"Install"},{"location":"plugins/survey-html-form/#examples","text":"Fill in the blanks Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>How are you feeling <b>right now?</b></p>' , html : '<p> I am feeling <input name=\"first\" type=\"text\" />, <input name=\"second\" type=\"text\" />, and <input name=\"third\" type=\"text\" />.</p>' }; Open demo in new tab Using the autofocus parameter Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>What is your favorite bird?</p>' , html : '<p>My favorite bird is <input type=\"text\" id=\"test-resp-box\" name=\"response\" size=\"10\" /></p>' , autofocus : 'test-resp-box' }; In this example, the browser will focus on the element with the ID test-resp-box when the trial loads. For <input type=\"text\"> elements, this means that the cursor will appear inside the text box. Open demo in new tab","title":"Examples"},{"location":"plugins/survey-likert/","text":"survey-likert \u00b6 Current version: 1.1.2. See version history . The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds by selecting a radio button. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, labels and required parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The strings are the question that will be associated with a slider. labels : Type array, default value is undefined . Each array element is an array of strings. The innermost arrays contain a set of labels to display for an individual question. If you want to use blank responses and only label the end points or some subset of the options, just insert a blank string for the unlabeled responses. required : Type boolean, default value is false. Makes answering questions required. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. scale_width numeric null The width of the likert scale in pixels. If left null , then the width of the scale will be equal to the width of the widest content on the page. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-likert@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-likert.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-likert import surveyLikert from '@jspsych/plugin-survey-likert' ; Examples \u00b6 Single Question Code Demo var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , labels : [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ] } ] }; Open demo in new tab Multiple questions in a random order Code Demo var likert_scale = [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ]; var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , name : 'Vegetables' , labels : likert_scale }, { prompt : \"I like fruit.\" , name : 'Fruit' , labels : likert_scale }, { prompt : \"I like meat.\" , name : 'Meat' , labels : likert_scale }, ], randomize_question_order : true }; Open demo in new tab","title":"survey-likert"},{"location":"plugins/survey-likert/#survey-likert","text":"Current version: 1.1.2. See version history . The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds by selecting a radio button.","title":"survey-likert"},{"location":"plugins/survey-likert/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, labels and required parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The strings are the question that will be associated with a slider. labels : Type array, default value is undefined . Each array element is an array of strings. The innermost arrays contain a set of labels to display for an individual question. If you want to use blank responses and only label the end points or some subset of the options, just insert a blank string for the unlabeled responses. required : Type boolean, default value is false. Makes answering questions required. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. scale_width numeric null The width of the likert scale in pixels. If left null , then the width of the scale will be equal to the width of the widest content on the page. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-likert/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-likert/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-likert@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-likert.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-likert import surveyLikert from '@jspsych/plugin-survey-likert' ;","title":"Install"},{"location":"plugins/survey-likert/#examples","text":"Single Question Code Demo var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , labels : [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ] } ] }; Open demo in new tab Multiple questions in a random order Code Demo var likert_scale = [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ]; var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , name : 'Vegetables' , labels : likert_scale }, { prompt : \"I like fruit.\" , name : 'Fruit' , labels : likert_scale }, { prompt : \"I like meat.\" , name : 'Meat' , labels : likert_scale }, ], randomize_question_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-multi-choice/","text":"survey-multi-choice \u00b6 Current version: 1.1.2. See version history . The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options, required, and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The string is prompt/question that will be associated with a group of options (radio buttons). All questions will get presented on the same page (trial). options : Type array, defualt value is undefined . An array of strings. The array contains a set of options to display for an individual question. required : Type boolean, default value is null. The boolean value indicates if a question is required('true') or not ('false'), using the HTML5 required attribute. If this parameter is undefined, the question will be optional. horizontal :Type boolean, default value is false. If true, then the question is centered and the options are displayed horizontally. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as the name of the option label selected (string). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-choice@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-choice.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-choice import surveyMultiChoice from '@jspsych/plugin-survey-multi-choice' ; Examples \u00b6 Vertical Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false } ], }; Open demo in new tab Horizontal Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true , horizontal : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , horizontal : true } ], }; Open demo in new tab","title":"survey-multi-choice"},{"location":"plugins/survey-multi-choice/#survey-multi-choice","text":"Current version: 1.1.2. See version history . The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer.","title":"survey-multi-choice"},{"location":"plugins/survey-multi-choice/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options, required, and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The string is prompt/question that will be associated with a group of options (radio buttons). All questions will get presented on the same page (trial). options : Type array, defualt value is undefined . An array of strings. The array contains a set of options to display for an individual question. required : Type boolean, default value is null. The boolean value indicates if a question is required('true') or not ('false'), using the HTML5 required attribute. If this parameter is undefined, the question will be optional. horizontal :Type boolean, default value is false. If true, then the question is centered and the options are displayed horizontally. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-multi-choice/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as the name of the option label selected (string). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-multi-choice/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-choice@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-choice.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-choice import surveyMultiChoice from '@jspsych/plugin-survey-multi-choice' ;","title":"Install"},{"location":"plugins/survey-multi-choice/#examples","text":"Vertical Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false } ], }; Open demo in new tab Horizontal Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true , horizontal : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , horizontal : true } ], }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-multi-select/","text":"survey-multi-select \u00b6 Current version: 1.1.2. See version history . The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can select multiple answers. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt/question that will be associated with a group of options (check boxes). All questions will get presented on the same page (trial). options : Type array, default value of undefined . The array contains a set of options to display for an individual question. horizontal : Type boolean, default value of false. If true, the questions are centered and options are displayed horizontally. required : Type boolean, default value of true. If true, then at least one option must be selected. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. required_message string 'You must choose at least one response for this question' Message to display if required response is not given. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the responses are recorded as arrays containing any response options that were selected (strings). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-select@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-select.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-select import surveyMultiSelect from '@jspsych/plugin-survey-multi-select' ; Examples \u00b6 Multiple Questions on a Page Code Demo var trial = { type : jsPsychSurveyMultiSelect , questions : [ { prompt : \"Which of these colors do you like?\" , options : [ \"Red\" , \"Yellow\" , \"Green\" , \"Blue\" , \"Black\" ], horizontal : true , required : true , name : 'Colors' }, { prompt : \"Which of these foods do you like?\" , options : [ \"Apples\" , \"Bananas\" , \"Carrots\" , \"Donuts\" , \"Eggplant\" ], horizontal : true , required : true , name : 'Foods' } ], randomize_question_order : true }; Open demo in new tab","title":"survey-multi-select"},{"location":"plugins/survey-multi-select/#survey-multi-select","text":"Current version: 1.1.2. See version history . The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can select multiple answers.","title":"survey-multi-select"},{"location":"plugins/survey-multi-select/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt/question that will be associated with a group of options (check boxes). All questions will get presented on the same page (trial). options : Type array, default value of undefined . The array contains a set of options to display for an individual question. horizontal : Type boolean, default value of false. If true, the questions are centered and options are displayed horizontally. required : Type boolean, default value of true. If true, then at least one option must be selected. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. required_message string 'You must choose at least one response for this question' Message to display if required response is not given. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-multi-select/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the responses are recorded as arrays containing any response options that were selected (strings). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-multi-select/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-select@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-select.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-select import surveyMultiSelect from '@jspsych/plugin-survey-multi-select' ;","title":"Install"},{"location":"plugins/survey-multi-select/#examples","text":"Multiple Questions on a Page Code Demo var trial = { type : jsPsychSurveyMultiSelect , questions : [ { prompt : \"Which of these colors do you like?\" , options : [ \"Red\" , \"Yellow\" , \"Green\" , \"Blue\" , \"Black\" ], horizontal : true , required : true , name : 'Colors' }, { prompt : \"Which of these foods do you like?\" , options : [ \"Apples\" , \"Bananas\" , \"Carrots\" , \"Donuts\" , \"Eggplant\" ], horizontal : true , required : true , name : 'Foods' } ], randomize_question_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-text/","text":"survey-text \u00b6 Current version: 1.1.2. See version history . The survey-text plugin displays a set of questions with free response text fields. The participant types in answers. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, placeholder, required, rows, and columns parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt for the participant to respond to. Each question gets its own response field. placeholder : Type string, default value of \"\" . The string will create placeholder text in the text field. required : Boolean; if true then the user must enter a response to submit. rows : Type integer, default value of 1. The number of rows for the response text box. columns : Type integer, default value of 40. The number of columns for the response text box. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the response is a string containing whatever text was in the response box when the responses were submitted. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-text@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-text.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-text import surveyText from '@jspsych/plugin-survey-text' ; Examples \u00b6 Single question and response Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'How old are you?' } ] } Open demo in new tab Multiple questions, with an optional placeholder and a required question Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What is your date of birth?' , placeholder : 'mm/dd/yyyy' , required : true }, { prompt : 'What country do you currently live in?' } ] } Open demo in new tab Naming questions to improve readability of the stored data Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What did you eat for breakfast?' , name : 'Breakfast' }, { prompt : 'What did you eat for lunch?' , name : 'Lunch' } ] } Open demo in new tab Using the preamble and a longer textbox response Code Demo var trial = { type : jsPsychSurveyText , preamble : `<img src=\"img/navarro_burst_03.jpg\" style=\"width:400px;\"></img>` , questions : [ { prompt : 'Describe your reaction to the image above' , rows : 5 } ] } The artwork in this demo is by Danielle Navarro Open demo in new tab","title":"survey-text"},{"location":"plugins/survey-text/#survey-text","text":"Current version: 1.1.2. See version history . The survey-text plugin displays a set of questions with free response text fields. The participant types in answers.","title":"survey-text"},{"location":"plugins/survey-text/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, placeholder, required, rows, and columns parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt for the participant to respond to. Each question gets its own response field. placeholder : Type string, default value of \"\" . The string will create placeholder text in the text field. required : Boolean; if true then the user must enter a response to submit. rows : Type integer, default value of 1. The number of rows for the response text box. columns : Type integer, default value of 40. The number of columns for the response text box. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-text/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the response is a string containing whatever text was in the response box when the responses were submitted. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-text/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-text@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-text.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-text import surveyText from '@jspsych/plugin-survey-text' ;","title":"Install"},{"location":"plugins/survey-text/#examples","text":"Single question and response Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'How old are you?' } ] } Open demo in new tab Multiple questions, with an optional placeholder and a required question Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What is your date of birth?' , placeholder : 'mm/dd/yyyy' , required : true }, { prompt : 'What country do you currently live in?' } ] } Open demo in new tab Naming questions to improve readability of the stored data Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What did you eat for breakfast?' , name : 'Breakfast' }, { prompt : 'What did you eat for lunch?' , name : 'Lunch' } ] } Open demo in new tab Using the preamble and a longer textbox response Code Demo var trial = { type : jsPsychSurveyText , preamble : `<img src=\"img/navarro_burst_03.jpg\" style=\"width:400px;\"></img>` , questions : [ { prompt : 'Describe your reaction to the image above' , rows : 5 } ] } The artwork in this demo is by Danielle Navarro Open demo in new tab","title":"Examples"},{"location":"plugins/survey/","text":"survey \u00b6 Current version: 0.2.1. See version history . The survey plugin displays one or more questions of different types, on one or more pages that the participant can navigate. This plugin is built on top of the SurveyJS library. The supported question types are: \"drop-down\" for presenting a question with a limited set of options in a drop-down menu. The participant can only select one option. \"likert\" for presenting a prompt along with a discrete rating scale. \"likert-table\" for presenting a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). \"multi-choice\" for presenting a question with a limited set of options. The participant can only select one option. \"multi-select\" for presenting a question with a limited set of options. The participant can select multiple options. \"ranking\" for presenting a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. \"text\" for presenting a question with a free response text field in which the participant can type in an answer. There is also an \"html\" type for adding arbitrary HTML-formatted content (without any associated response field) in the question set. Warning Development on this plugin is ongoing and we plan to incorporate more of the features that SurveyJS provides. Prior to release of version 1.0 of the plugin, we expect the parameters and implementation of this plugin to change. We recommend performing a little bit of extra testing with any experiments that utilize this plugin. CSS \u00b6 This plugin uses an additional stylesheet called survey.css . You can load it via: < link rel = \"stylesheet\" href = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1/css/survey.css\" > If you are using a bundler such as webpack , you can also import it in JavaScript as follows, depending on your bundler configuration: import '@jspsych/plugin-survey/css/survey.css' Parameters \u00b6 In addition to the 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. Survey parameters \u00b6 Parameter Type Default Value Description pages array undefined An array of arrays. Each inner array contains the content for a single page, which is made up of one or more question objects. button_label_next string 'Continue' Label of the button to move forward to the next page, or finish the survey. button_label_previous string 'Back' Label of the button to move to a previous page in the survey. button_label_finish string 'Finish' Label of the button to submit responses. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. show_question_numbers string \"off\" One of: \"on\", \"onPage\", \"off\". If \"on\", questions will be labelled starting with \"1.\" on the first page, and numbering will continue across pages. If \"onPage\", questions will be labelled starting with \"1.\", with separate numbering on each page. If \"off\", no numbers will be added before the question prompts. Note: HTML question types are ignored in automatic numbering. title string null If specified, this text will be shown at the top of the survey pages. required_error string \"Please answer the question.\" Text to display if a required question is not responeded to. required_question_label string \"*\" String to display at the end of required questions. Use an empty string (\"\") if you do not want to add a label to the end of required questions. Question types and parameters \u00b6 Parameters for all question types \u00b6 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 type string undefined The question type. Options are: \"drop-down\", \"html\", \"likert\", \"likert-table\", \"multi-choice\", \"multi-select\", \"ranking\", \"rating\", \"text\". prompt string undefined The prompt/question that will be associated with the question's response field. If the question type is \"html\", then this string is the HTML-formatted string to be displayed. If the question type is \"likert-table\", the prompt is a general question or title presented above the table. required boolean false Whether a response to the question is required ( true ) or not ( false ), using the HTML5 required attribute. name string null Name of the question to be used for storing data. If this parameter is not provided, then default names will be used to identify the questions in the data: P0_Q0 , P0_Q1 , P1_Q0 etc. Question names must be unique across all pages within the trial. Drop-down \u00b6 Present a question with a limited set of options in a drop-down menu. The participant can only select one option. In addition to the parameters for all question types, the drop-down question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). HTML \u00b6 Present arbitrary HTML-formatted content embedded in the list of questions, including text, images, and sounds. There are no response options. The only available parameters are those listed for all question types with a default value of undefined ( type and prompt ) and name . The name parameter is optional and used to identify the question in the data, with a response value of null . The required parameter will be ignored. Likert \u00b6 Present a prompt along with a discrete rating scale. The scale values are presented as buttons that can be selected and de-selected. The scale is specified by the likert_scale_values parameter, which is an array of text labels and associated values, or it is generated using the likert_rating_min / max / stepsize parameters (along with optional maximum/minimum descriptions). In addition to the parameters for all question types, the likert question type also offers 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 likert_scale_values array of objects null Array of objects that defines the rating scale labels and associated values to be stored in the data. Each object defines a single rating option. The objects must have a value property, which is an integer or string value that will be stored as the response in the data. The objects can optionally have a text property, which is a string that will be displayed for that rating option (example: [{value: 1, text: \"A lot\"},{value: 2, text: \"Somewhat\"},{value: 3, text: \"Not much\"}] ). If no text property is specified then the value will be displayed (examples: [{value: 1},{value: 2},{value: 3}] , [{value: \"Yes\"},{value: \"Maybe\"},{value: \"No\"}] ). If provided, this parameter will override the likert_rating_min / max / stepsize parameters. likert_scale_min integer 1 If the likert_scale_values array is not specified, then this parameter will define the minimum scale value. likert_scale_max integer 5 If the likert_scale_values array is not specified, then this parameter will define the maximum scale value. likert_scale_stepsize integer 1 If the likert_scale_values array is not specified, then this parameter will define the step size that should be used for generating rating options between the minimum and maximum values. likert_scale_min_label string null Description for the minimum (first) rating option. If provided, this text will be shown inside the first rating button, before the rating text/value. This parameter is meant for defining the scale's minimum when integer values are used for the rating scale buttons. likert_scale_max_label string null Description for the maximum (last) rating option. If provided, this text will be shown inside the first rating button, after the rating text/value. This parameter is meant for defining the scale's maximum when integer values are used for the rating scale buttons. Likert-table \u00b6 Present a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). In addition to the parameters for all question types, the likert-table question type also offers 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 statements array of objects undefined This array contains one or more objects representing the statements/questions to be presented in the table rows. Each object must have a prompt , which is the statement/question text. The objects can optionally include a name , which is how the statement should be identified in the data. If no name is provided, then the default values of \"S0\", \"S1\" etc. will be used. options array of strings undefined This array contains the set of multiple choice options to be presented in the table columns. randomize_statement_order boolean false If true , the order of statements/questions in the statements array will be randomized. Multi-choice \u00b6 Present a question with a limited set of options. The participant can only select one option. In addition to the parameters for all question types, the multi-choice question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Multi-select \u00b6 Present a question with a limited set of options. The participant can select multiple options. In addition to the parameters for all question types, the multi-select question type also offers 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 options array of strings undefined This array contains the set of options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response array of strings null Array of one or more strings from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Ranking \u00b6 Present a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. It is ideally used with a short list of options (up to about 7 items). It supports mouse responses, touch responses (mobile devices), and keyboard responses (Tab and Shift-Tab to select, and Up/Down arrow keys to re-order). In addition to the parameters for all question types, the ranking question type also offers 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 options array of strings undefined This array contains the set of to-be-ranked options for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response array of strings null The same array of strings used for the options array, but listed in the order that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Text \u00b6 Present a question with a free response text field in which the participant can type in an answer. In addition to the parameters for all question types, the text question also offers 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 placeholder string \"\" Placeholder text in the text response field. textbox_rows integer 1 The number of rows (height) for the response text box. textbox_columns integer 40 The number of columns (width) for the response text box. validation string \"\" A regular expression used to validate the response. input_type string \"text\" Type for the HTML <input> element. The input_type parameter must be one of \"color\", \"date\", \"datetime-local\", \"email\", \"month\", \"number\", \"password\", \"range\", \"tel\", \"text\", \"time\", \"url\", \"week\". If the textbox_rows parameter is larger than 1, the input_type parameter will be ignored. The textbox_columns parameter only affects questions with input_type \"email\", \"password\", \"tel\", \"url\", or \"text\". Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response to each question. The object will have a separate key (variable) for each question, with the first question on the first page being recorded in P0_Q0 , the second question on the first page in P0_Q1 , and so on. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. The response type will depend on the question type. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Note that, if any questions use the other option ( add_other_option: true ), then the response value will be the other_option_text (e.g. \"Other\") and any text written in the textbox will be saved as \"(question name)-Comment\". rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey import survey from '@jspsych/plugin-survey' ; Examples \u00b6 Basic single page Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'html' , prompt : 'Please answer the following questions:' , }, { type : 'multi-choice' , prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { type : 'multi-select' , prompt : \"Which of the following do you like?\" , name : 'FruitLike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , } ] ], }; Open demo in new tab Multiple pages, more customization Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'text' , prompt : \"Where were you born?\" , placeholder : 'City, State, Country' , name : 'birthplace' , required : true , }, { type : 'text' , prompt : \"How old are you?\" , name : 'age' , textbox_columns : 5 , required : false , } ], [ { type : 'multi-choice' , prompt : \"What&#39;s your favorite color?\" , options : [ 'blue' , 'yellow' , 'pink' , 'teal' , 'orange' , 'lime green' , 'other' , 'none of these' ], name : 'FavColor' , }, { type : 'multi-select' , prompt : \"Which of these animals do you like? Select all that apply.\" , options : [ 'lion' , 'squirrel' , 'badger' , 'whale' ], option_reorder : 'random' , columns : 0 , name : 'AnimalLike' , } ] ], title : 'My questionnaire' , button_label_next : 'Continue' , button_label_back : 'Previous' , button_label_finish : 'Submit' , show_question_numbers : 'onPage' }; Open demo in new tab Single and multiple item Likert-style scales Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'likert' , prompt : 'I like to eat vegetables.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat fruit.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat meat.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, ], [ { type : 'likert-table' , prompt : ' ' , statements : [ { prompt : 'I like to eat vegetables' , name : 'VeggiesTable' }, { prompt : 'I like to eat fruit' , name : 'FruitTable' }, { prompt : 'I like to eat meat' , name : 'MeatTable' }, ], options : [ 'Strongly Disagree' , 'Disagree' , 'Neutral' , 'Agree' , 'Strongly Agree' ], } ] ], }; Open demo in new tab Response scoring Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : 'During the experiment, are allowed to write things down on paper to help you?' , options : [ \"Yes\" , \"No\" ], correct_response : \"No\" , required : true }, ] ], }; Open demo in new tab Adding data to trial When adding any data to a Survey trial, you should add it via the data parameter at the whole-trial level (not inside the question objects), even if it only relates to one question out of multiple questions/pages contained wihtin the trial. Code Demo const question_info = [ { 'fruit' : 'apples' , 'Q1_prompt' : 'Do you like apples?' , 'Q1_type' : 'regular' }, { 'fruit' : 'bananas' , 'Q1_prompt' : 'Do you NOT like bananas?' , 'Q1_type' : 'reverse' }, ]; const survey = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : jsPsych . timelineVariable ( 'Q1_prompt' ), options : [ 'Yes' , 'No' ], name : 'Q1' }, { type : 'text' , prompt : function () { return `What's your favorite thing about ${ jsPsych . timelineVariable ( 'fruit' ) } ?` ; }, name : 'Q2' } ] ], // Add data at the whole-trial level here data : { 'Q1_prompt' : jsPsych . timelineVariable ( 'Q1_prompt' ), 'Q1_type' : jsPsych . timelineVariable ( 'Q1_type' ), 'fruit' : jsPsych . timelineVariable ( 'fruit' ) }, button_label_finish : 'Continue' }; const survey_procedure = { timeline : [ survey ], timeline_variables : question_info , randomize_order : true }; Open demo in new tab","title":"survey"},{"location":"plugins/survey/#survey","text":"Current version: 0.2.1. See version history . The survey plugin displays one or more questions of different types, on one or more pages that the participant can navigate. This plugin is built on top of the SurveyJS library. The supported question types are: \"drop-down\" for presenting a question with a limited set of options in a drop-down menu. The participant can only select one option. \"likert\" for presenting a prompt along with a discrete rating scale. \"likert-table\" for presenting a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). \"multi-choice\" for presenting a question with a limited set of options. The participant can only select one option. \"multi-select\" for presenting a question with a limited set of options. The participant can select multiple options. \"ranking\" for presenting a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. \"text\" for presenting a question with a free response text field in which the participant can type in an answer. There is also an \"html\" type for adding arbitrary HTML-formatted content (without any associated response field) in the question set. Warning Development on this plugin is ongoing and we plan to incorporate more of the features that SurveyJS provides. Prior to release of version 1.0 of the plugin, we expect the parameters and implementation of this plugin to change. We recommend performing a little bit of extra testing with any experiments that utilize this plugin.","title":"survey"},{"location":"plugins/survey/#css","text":"This plugin uses an additional stylesheet called survey.css . You can load it via: < link rel = \"stylesheet\" href = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1/css/survey.css\" > If you are using a bundler such as webpack , you can also import it in JavaScript as follows, depending on your bundler configuration: import '@jspsych/plugin-survey/css/survey.css'","title":"CSS"},{"location":"plugins/survey/#parameters","text":"In addition to the 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.","title":"Parameters"},{"location":"plugins/survey/#survey-parameters","text":"Parameter Type Default Value Description pages array undefined An array of arrays. Each inner array contains the content for a single page, which is made up of one or more question objects. button_label_next string 'Continue' Label of the button to move forward to the next page, or finish the survey. button_label_previous string 'Back' Label of the button to move to a previous page in the survey. button_label_finish string 'Finish' Label of the button to submit responses. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. show_question_numbers string \"off\" One of: \"on\", \"onPage\", \"off\". If \"on\", questions will be labelled starting with \"1.\" on the first page, and numbering will continue across pages. If \"onPage\", questions will be labelled starting with \"1.\", with separate numbering on each page. If \"off\", no numbers will be added before the question prompts. Note: HTML question types are ignored in automatic numbering. title string null If specified, this text will be shown at the top of the survey pages. required_error string \"Please answer the question.\" Text to display if a required question is not responeded to. required_question_label string \"*\" String to display at the end of required questions. Use an empty string (\"\") if you do not want to add a label to the end of required questions.","title":"Survey parameters"},{"location":"plugins/survey/#question-types-and-parameters","text":"","title":"Question types and parameters"},{"location":"plugins/survey/#parameters-for-all-question-types","text":"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 type string undefined The question type. Options are: \"drop-down\", \"html\", \"likert\", \"likert-table\", \"multi-choice\", \"multi-select\", \"ranking\", \"rating\", \"text\". prompt string undefined The prompt/question that will be associated with the question's response field. If the question type is \"html\", then this string is the HTML-formatted string to be displayed. If the question type is \"likert-table\", the prompt is a general question or title presented above the table. required boolean false Whether a response to the question is required ( true ) or not ( false ), using the HTML5 required attribute. name string null Name of the question to be used for storing data. If this parameter is not provided, then default names will be used to identify the questions in the data: P0_Q0 , P0_Q1 , P1_Q0 etc. Question names must be unique across all pages within the trial.","title":"Parameters for all question types"},{"location":"plugins/survey/#drop-down","text":"Present a question with a limited set of options in a drop-down menu. The participant can only select one option. In addition to the parameters for all question types, the drop-down question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Drop-down"},{"location":"plugins/survey/#html","text":"Present arbitrary HTML-formatted content embedded in the list of questions, including text, images, and sounds. There are no response options. The only available parameters are those listed for all question types with a default value of undefined ( type and prompt ) and name . The name parameter is optional and used to identify the question in the data, with a response value of null . The required parameter will be ignored.","title":"HTML"},{"location":"plugins/survey/#likert","text":"Present a prompt along with a discrete rating scale. The scale values are presented as buttons that can be selected and de-selected. The scale is specified by the likert_scale_values parameter, which is an array of text labels and associated values, or it is generated using the likert_rating_min / max / stepsize parameters (along with optional maximum/minimum descriptions). In addition to the parameters for all question types, the likert question type also offers 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 likert_scale_values array of objects null Array of objects that defines the rating scale labels and associated values to be stored in the data. Each object defines a single rating option. The objects must have a value property, which is an integer or string value that will be stored as the response in the data. The objects can optionally have a text property, which is a string that will be displayed for that rating option (example: [{value: 1, text: \"A lot\"},{value: 2, text: \"Somewhat\"},{value: 3, text: \"Not much\"}] ). If no text property is specified then the value will be displayed (examples: [{value: 1},{value: 2},{value: 3}] , [{value: \"Yes\"},{value: \"Maybe\"},{value: \"No\"}] ). If provided, this parameter will override the likert_rating_min / max / stepsize parameters. likert_scale_min integer 1 If the likert_scale_values array is not specified, then this parameter will define the minimum scale value. likert_scale_max integer 5 If the likert_scale_values array is not specified, then this parameter will define the maximum scale value. likert_scale_stepsize integer 1 If the likert_scale_values array is not specified, then this parameter will define the step size that should be used for generating rating options between the minimum and maximum values. likert_scale_min_label string null Description for the minimum (first) rating option. If provided, this text will be shown inside the first rating button, before the rating text/value. This parameter is meant for defining the scale's minimum when integer values are used for the rating scale buttons. likert_scale_max_label string null Description for the maximum (last) rating option. If provided, this text will be shown inside the first rating button, after the rating text/value. This parameter is meant for defining the scale's maximum when integer values are used for the rating scale buttons.","title":"Likert"},{"location":"plugins/survey/#likert-table","text":"Present a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). In addition to the parameters for all question types, the likert-table question type also offers 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 statements array of objects undefined This array contains one or more objects representing the statements/questions to be presented in the table rows. Each object must have a prompt , which is the statement/question text. The objects can optionally include a name , which is how the statement should be identified in the data. If no name is provided, then the default values of \"S0\", \"S1\" etc. will be used. options array of strings undefined This array contains the set of multiple choice options to be presented in the table columns. randomize_statement_order boolean false If true , the order of statements/questions in the statements array will be randomized.","title":"Likert-table"},{"location":"plugins/survey/#multi-choice","text":"Present a question with a limited set of options. The participant can only select one option. In addition to the parameters for all question types, the multi-choice question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Multi-choice"},{"location":"plugins/survey/#multi-select","text":"Present a question with a limited set of options. The participant can select multiple options. In addition to the parameters for all question types, the multi-select question type also offers 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 options array of strings undefined This array contains the set of options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response array of strings null Array of one or more strings from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Multi-select"},{"location":"plugins/survey/#ranking","text":"Present a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. It is ideally used with a short list of options (up to about 7 items). It supports mouse responses, touch responses (mobile devices), and keyboard responses (Tab and Shift-Tab to select, and Up/Down arrow keys to re-order). In addition to the parameters for all question types, the ranking question type also offers 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 options array of strings undefined This array contains the set of to-be-ranked options for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response array of strings null The same array of strings used for the options array, but listed in the order that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Ranking"},{"location":"plugins/survey/#text","text":"Present a question with a free response text field in which the participant can type in an answer. In addition to the parameters for all question types, the text question also offers 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 placeholder string \"\" Placeholder text in the text response field. textbox_rows integer 1 The number of rows (height) for the response text box. textbox_columns integer 40 The number of columns (width) for the response text box. validation string \"\" A regular expression used to validate the response. input_type string \"text\" Type for the HTML <input> element. The input_type parameter must be one of \"color\", \"date\", \"datetime-local\", \"email\", \"month\", \"number\", \"password\", \"range\", \"tel\", \"text\", \"time\", \"url\", \"week\". If the textbox_rows parameter is larger than 1, the input_type parameter will be ignored. The textbox_columns parameter only affects questions with input_type \"email\", \"password\", \"tel\", \"url\", or \"text\".","title":"Text"},{"location":"plugins/survey/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response to each question. The object will have a separate key (variable) for each question, with the first question on the first page being recorded in P0_Q0 , the second question on the first page in P0_Q1 , and so on. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. The response type will depend on the question type. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Note that, if any questions use the other option ( add_other_option: true ), then the response value will be the other_option_text (e.g. \"Other\") and any text written in the textbox will be saved as \"(question name)-Comment\". rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted.","title":"Data Generated"},{"location":"plugins/survey/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/survey/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey import survey from '@jspsych/plugin-survey' ;","title":"Install"},{"location":"plugins/survey/#examples","text":"Basic single page Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'html' , prompt : 'Please answer the following questions:' , }, { type : 'multi-choice' , prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { type : 'multi-select' , prompt : \"Which of the following do you like?\" , name : 'FruitLike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , } ] ], }; Open demo in new tab Multiple pages, more customization Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'text' , prompt : \"Where were you born?\" , placeholder : 'City, State, Country' , name : 'birthplace' , required : true , }, { type : 'text' , prompt : \"How old are you?\" , name : 'age' , textbox_columns : 5 , required : false , } ], [ { type : 'multi-choice' , prompt : \"What&#39;s your favorite color?\" , options : [ 'blue' , 'yellow' , 'pink' , 'teal' , 'orange' , 'lime green' , 'other' , 'none of these' ], name : 'FavColor' , }, { type : 'multi-select' , prompt : \"Which of these animals do you like? Select all that apply.\" , options : [ 'lion' , 'squirrel' , 'badger' , 'whale' ], option_reorder : 'random' , columns : 0 , name : 'AnimalLike' , } ] ], title : 'My questionnaire' , button_label_next : 'Continue' , button_label_back : 'Previous' , button_label_finish : 'Submit' , show_question_numbers : 'onPage' }; Open demo in new tab Single and multiple item Likert-style scales Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'likert' , prompt : 'I like to eat vegetables.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat fruit.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat meat.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, ], [ { type : 'likert-table' , prompt : ' ' , statements : [ { prompt : 'I like to eat vegetables' , name : 'VeggiesTable' }, { prompt : 'I like to eat fruit' , name : 'FruitTable' }, { prompt : 'I like to eat meat' , name : 'MeatTable' }, ], options : [ 'Strongly Disagree' , 'Disagree' , 'Neutral' , 'Agree' , 'Strongly Agree' ], } ] ], }; Open demo in new tab Response scoring Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : 'During the experiment, are allowed to write things down on paper to help you?' , options : [ \"Yes\" , \"No\" ], correct_response : \"No\" , required : true }, ] ], }; Open demo in new tab Adding data to trial When adding any data to a Survey trial, you should add it via the data parameter at the whole-trial level (not inside the question objects), even if it only relates to one question out of multiple questions/pages contained wihtin the trial. Code Demo const question_info = [ { 'fruit' : 'apples' , 'Q1_prompt' : 'Do you like apples?' , 'Q1_type' : 'regular' }, { 'fruit' : 'bananas' , 'Q1_prompt' : 'Do you NOT like bananas?' , 'Q1_type' : 'reverse' }, ]; const survey = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : jsPsych . timelineVariable ( 'Q1_prompt' ), options : [ 'Yes' , 'No' ], name : 'Q1' }, { type : 'text' , prompt : function () { return `What's your favorite thing about ${ jsPsych . timelineVariable ( 'fruit' ) } ?` ; }, name : 'Q2' } ] ], // Add data at the whole-trial level here data : { 'Q1_prompt' : jsPsych . timelineVariable ( 'Q1_prompt' ), 'Q1_type' : jsPsych . timelineVariable ( 'Q1_type' ), 'fruit' : jsPsych . timelineVariable ( 'fruit' ) }, button_label_finish : 'Continue' }; const survey_procedure = { timeline : [ survey ], timeline_variables : question_info , randomize_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/video-button-response/","text":"video-button-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video and records responses generated by button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the video has finished playing. The button itself can be customized using HTML formatting. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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. 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. margin_vertical string '0px' Vertical margin of the button(s). margin_horizontal string '8px' Horizontal margin of the button(s). 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 participant 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 participant. 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. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the button choices are enabled and a response is accepted. Once the video has played all the way through, the buttons are enabled and a response is allowed (including while the video is being re-played via on-screen playback controls). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-button-response import videoButtonResponse from '@jspsych/plugin-video-button-response' ; Example \u00b6 Responses disabled until the video is complete Code Demo var trial = { type : jsPsychVideoButtonResponse , stimulus : [ 'video/fish.mp4' ], choices : [ '0-5' , '6-10' , '11-15' , '16-20' , '21-25' , '25+' ], prompt : \"<p>How many different fish are shown in the video?</p>\" , response_allowed_while_playing : false }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-button-response"},{"location":"plugins/video-button-response/#video-button-response","text":"Current version: 1.1.2. See version history . This plugin plays a video and records responses generated by button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the video has finished playing. The button itself can be customized using HTML formatting. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-button-response"},{"location":"plugins/video-button-response/#parameters","text":"In addition to the 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 . 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. 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. margin_vertical string '0px' Vertical margin of the button(s). margin_horizontal string '8px' Horizontal margin of the button(s). 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 participant 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 participant. 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. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the button choices are enabled and a response is accepted. Once the video has played all the way through, the buttons are enabled and a response is allowed (including while the video is being re-played via on-screen playback controls).","title":"Parameters"},{"location":"plugins/video-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/video-button-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-button-response import videoButtonResponse from '@jspsych/plugin-video-button-response' ;","title":"Install"},{"location":"plugins/video-button-response/#example","text":"Responses disabled until the video is complete Code Demo var trial = { type : jsPsychVideoButtonResponse , stimulus : [ 'video/fish.mp4' ], choices : [ '0-5' , '6-10' , '11-15' , '16-20' , '21-25' , '25+' ], prompt : \"<p>How many different fish are shown in the video?</p>\" , response_allowed_while_playing : false }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Example"},{"location":"plugins/video-keyboard-response/","text":"video-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video file and records a keyboard response. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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 participant 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 participant. 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-keyboard-response import videoKeyboardResponse from '@jspsych/plugin-video-keyboard-response' ; Examples \u00b6 Show a video and advance to next trial automatically Code Demo var trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/fish.mp4' ], choices : \"NO_KEYS\" , trial_ends_after_video : true }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-keyboard-response"},{"location":"plugins/video-keyboard-response/#video-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin plays a video file and records a keyboard response. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-keyboard-response"},{"location":"plugins/video-keyboard-response/#parameters","text":"In addition to the 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 . 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 participant 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 participant. 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/video-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/video-keyboard-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-keyboard-response import videoKeyboardResponse from '@jspsych/plugin-video-keyboard-response' ;","title":"Install"},{"location":"plugins/video-keyboard-response/#examples","text":"Show a video and advance to next trial automatically Code Demo var trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/fish.mp4' ], choices : \"NO_KEYS\" , trial_ends_after_video : true }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Examples"},{"location":"plugins/video-slider-response/","text":"video-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video and allows the participant to respond by dragging a slider. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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 participant 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 participant. 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. 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. 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. 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 participant must move the slider before clicking the continue button. button_label string 'Continue' Label of the button to end the trial. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the slider is enabled and the trial can end via the next button click. Once the video has played all the way through, the slider is enabled and a response is allowed (including while the video is being re-played via on-screen playback controls). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric The numeric value of the slider. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. slider_start numeric The starting value of the slider. start numeric The start time of the video clip. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-slider-response import videoSliderResponse from '@jspsych/plugin-video-slider-response' ; Example \u00b6 Rate enjoyment of a video clip Code Demo var trial = { type : jsPsychVideoSliderResponse , stimulus : [ 'video/fish.mp4' ], labels : [ \"Hated it\" , \"Loved it\" ], prompt : '<p>Please rate your enjoyment of the video clip.</p>' }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-slider-response"},{"location":"plugins/video-slider-response/#video-slider-response","text":"Current version: 1.1.2. See version history . This plugin plays a video and allows the participant to respond by dragging a slider. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-slider-response"},{"location":"plugins/video-slider-response/#parameters","text":"In addition to the 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 . 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 participant 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 participant. 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. 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. 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. 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 participant must move the slider before clicking the continue button. button_label string 'Continue' Label of the button to end the trial. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the slider is enabled and the trial can end via the next button click. Once the video has played all the way through, the slider is enabled and a response is allowed (including while the video is being re-played via on-screen playback controls).","title":"Parameters"},{"location":"plugins/video-slider-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric The numeric value of the slider. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. slider_start numeric The starting value of the slider. start numeric The start time of the video clip.","title":"Data Generated"},{"location":"plugins/video-slider-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-slider-response import videoSliderResponse from '@jspsych/plugin-video-slider-response' ;","title":"Install"},{"location":"plugins/video-slider-response/#example","text":"Rate enjoyment of a video clip Code Demo var trial = { type : jsPsychVideoSliderResponse , stimulus : [ 'video/fish.mp4' ], labels : [ \"Hated it\" , \"Loved it\" ], prompt : '<p>Please rate your enjoyment of the video clip.</p>' }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Example"},{"location":"plugins/virtual-chinrest/","text":"virtual-chinrest \u00b6 Current version: 2.0.2. See version history . This plugin provides a \"virtual chinrest\" that can measure the distance between the participant and the screen. It can also standardize the jsPsych page content to a known physical dimension (e.g., ensuring that a 200px wide stimulus is 2.2cm wide on the participant's monitor). This is based on the work of Li, Joo, Yeatman, and Reinecke (2020) , and the plugin code is a modified version of their implementation . We recommend citing their work in any paper that makes use of this plugin. Citation Li, Q., Joo, S. J., Yeatman, J. D., & Reinecke, K. (2020). Controlling for Participants\u2019 Viewing Distance in Large-Scale, Psychophysical Online Experiments Using a Virtual Chinrest. Scientific Reports, 10 (1), 1-11. doi: 10.1038/s41598-019-57204-1 The plugin works in two phases. Phase 1 . To calculate the pixel-to-cm conversion rate for a participant\u2019s display, participants are asked to place a credit card or other item of the same size on the screen and resize an image until it is the same size as the credit card. Since we know the physical dimensions of the card, we can find the conversion rate for the participant's display. Phase 2 . To measure the participant's viewing distance from their screen we use a blind spot task. Participants are asked to focus on a black square on the screen with their right eye closed, while a red dot repeatedly sweeps from right to left. They press the spacebar on their keyboard whenever they perceive that the red dot has disappeared. This part allows the plugin to use the distance between the black square and the red dot when it disappears from eyesight to estimate how far the participant is from the monitor. This estimation assumes that the blind spot is located at 13.5\u00b0 temporally. Parameters \u00b6 Parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Descripton resize_units string \"none\" Units to resize the jsPsych content to after the trial is over: \"none\" \"cm\" \"inch\" or \"deg\" . If \"none\" , no resizing will be done to the jsPsych content after the virtual-chinrest trial ends. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement, where the units are indicated by resize_units . This is only used when resizing is done after the trial ends (i.e. the resize_units parameter is not \"none\"). adjustment_prompt HTML string \"Click and drag the lower right corner of the image until it is the same size as a credit card held up to the screen. You can use any card that is the same size as a credit card, like a membership card or driver's license. If you do not have access to a real card you can use a ruler to measure the image width to 3.37 inches or 85.6 mm.\" This string can contain HTML markup. Any content here will be displayed below the card stimulus during the resizing phase. adjustment_button_prompt HTML string \"Click here when the image is the correct size\" Content of the button displayed below the card stimulus during the resizing phase. item_path string null Path of the item to be presented in the card stimulus during the resizing phase. If null then no image is shown, and a solid color background is used instead. An example image is available in /examples/img/card.png item_height_mm numeric 53.98 The known height of the physical item (e.g. credit card) to be measured, in mm. item_width_mm numeric 85.6 The known width of the physical item (e.g. credit card) to be measured, in mm. item_init_size numeric 250 The initial size of the card stimulus, in pixels, along its largest dimension. blindspot_reps numeric 5 How many times to measure the blindspot location. If 0 , blindspot will not be detected, and viewing distance and degree data will not be computed. blindspot_prompt HTML string \"Now we will quickly measure how far away you are sitting. Put your left hand on the space bar. Cover your right eye with your right hand. Using your left eye, focus on the black square. Keep your focus on the black square. The red ball will disappear as it moves from right to left. Press the space bar as soon as the ball disappears. Press the space bar when you are ready to begin. This string can contain HTML markup. Any content here will be displayed above the blindspot task . redo_measurement_button_label HTML string 'No, that is not close. Try again' Text for the button on the viewing distance report page to re-do the viewing distance estimate. If the participant click this button, the blindspot task starts again. blindspot_done_prompt HTML string \"Yes\" Text for the button on the viewing distance report page that can be clicked to accept the viewing distance estimate. blindspot_measurements_prompt HTML string 'Remaining measurements: ' Text accompanying the remaining measurements counter that appears below the blindspot task. viewing_distance_report HTML string \"Based on your responses, you are sitting about <span id='distance-estimate' style='font-weight: bold;'></span> from the screen. Does that seem about right?\" Estimated viewing distance data displayed after blindspot task. If \"none\" is given, viewing distance will not be reported to the participant. The HTML span element with id = distance-estimate returns the distance. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Note: The deg data are only returned if viewing distance is estimated with the blindspot method (px2deg, win_height_deg, win_width_deg, item_width_deg). Name Type Value rt numeric The response time in milliseconds. item_height_mm numeric The height in millimeters of the item to be measured. item_width_mm numeric The width in millimeters of the item to be measured item_height_deg numeric Final height of the resizable div container, in degrees. item_width_deg numeric Final width of the resizable div container, in degrees. item_width_px numeric Final width of the resizable div container, in pixels. px2deg numeric Pixels to degrees conversion factor. px2mm numeric Pixels to millimeters conversion factor. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. win_width_deg numeric The interior width of the window in degrees. win_height_deg numeric The interior height of the window in degrees. view_dist_mm numeric Estimated distance to the screen in millimeters. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-virtual-chinrest@2.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-virtual-chinrest.js\" >< /script> Using NPM: npm install @jspsych/plugin-virtual-chinrest import virtualChinrest from '@jspsych/plugin-virtual-chinrest' ; Example \u00b6 Measure distance to screen and pixel ratio; no resizing Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"none\" }; This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on centimeters per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"cm\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should be 10 cm x 10 cm.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on degrees of visual angle per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"deg\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should take up about 10 degrees of visual angle.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab","title":"virtual-chinrest"},{"location":"plugins/virtual-chinrest/#virtual-chinrest","text":"Current version: 2.0.2. See version history . This plugin provides a \"virtual chinrest\" that can measure the distance between the participant and the screen. It can also standardize the jsPsych page content to a known physical dimension (e.g., ensuring that a 200px wide stimulus is 2.2cm wide on the participant's monitor). This is based on the work of Li, Joo, Yeatman, and Reinecke (2020) , and the plugin code is a modified version of their implementation . We recommend citing their work in any paper that makes use of this plugin. Citation Li, Q., Joo, S. J., Yeatman, J. D., & Reinecke, K. (2020). Controlling for Participants\u2019 Viewing Distance in Large-Scale, Psychophysical Online Experiments Using a Virtual Chinrest. Scientific Reports, 10 (1), 1-11. doi: 10.1038/s41598-019-57204-1 The plugin works in two phases. Phase 1 . To calculate the pixel-to-cm conversion rate for a participant\u2019s display, participants are asked to place a credit card or other item of the same size on the screen and resize an image until it is the same size as the credit card. Since we know the physical dimensions of the card, we can find the conversion rate for the participant's display. Phase 2 . To measure the participant's viewing distance from their screen we use a blind spot task. Participants are asked to focus on a black square on the screen with their right eye closed, while a red dot repeatedly sweeps from right to left. They press the spacebar on their keyboard whenever they perceive that the red dot has disappeared. This part allows the plugin to use the distance between the black square and the red dot when it disappears from eyesight to estimate how far the participant is from the monitor. This estimation assumes that the blind spot is located at 13.5\u00b0 temporally.","title":"virtual-chinrest"},{"location":"plugins/virtual-chinrest/#parameters","text":"Parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Descripton resize_units string \"none\" Units to resize the jsPsych content to after the trial is over: \"none\" \"cm\" \"inch\" or \"deg\" . If \"none\" , no resizing will be done to the jsPsych content after the virtual-chinrest trial ends. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement, where the units are indicated by resize_units . This is only used when resizing is done after the trial ends (i.e. the resize_units parameter is not \"none\"). adjustment_prompt HTML string \"Click and drag the lower right corner of the image until it is the same size as a credit card held up to the screen. You can use any card that is the same size as a credit card, like a membership card or driver's license. If you do not have access to a real card you can use a ruler to measure the image width to 3.37 inches or 85.6 mm.\" This string can contain HTML markup. Any content here will be displayed below the card stimulus during the resizing phase. adjustment_button_prompt HTML string \"Click here when the image is the correct size\" Content of the button displayed below the card stimulus during the resizing phase. item_path string null Path of the item to be presented in the card stimulus during the resizing phase. If null then no image is shown, and a solid color background is used instead. An example image is available in /examples/img/card.png item_height_mm numeric 53.98 The known height of the physical item (e.g. credit card) to be measured, in mm. item_width_mm numeric 85.6 The known width of the physical item (e.g. credit card) to be measured, in mm. item_init_size numeric 250 The initial size of the card stimulus, in pixels, along its largest dimension. blindspot_reps numeric 5 How many times to measure the blindspot location. If 0 , blindspot will not be detected, and viewing distance and degree data will not be computed. blindspot_prompt HTML string \"Now we will quickly measure how far away you are sitting. Put your left hand on the space bar. Cover your right eye with your right hand. Using your left eye, focus on the black square. Keep your focus on the black square. The red ball will disappear as it moves from right to left. Press the space bar as soon as the ball disappears. Press the space bar when you are ready to begin. This string can contain HTML markup. Any content here will be displayed above the blindspot task . redo_measurement_button_label HTML string 'No, that is not close. Try again' Text for the button on the viewing distance report page to re-do the viewing distance estimate. If the participant click this button, the blindspot task starts again. blindspot_done_prompt HTML string \"Yes\" Text for the button on the viewing distance report page that can be clicked to accept the viewing distance estimate. blindspot_measurements_prompt HTML string 'Remaining measurements: ' Text accompanying the remaining measurements counter that appears below the blindspot task. viewing_distance_report HTML string \"Based on your responses, you are sitting about <span id='distance-estimate' style='font-weight: bold;'></span> from the screen. Does that seem about right?\" Estimated viewing distance data displayed after blindspot task. If \"none\" is given, viewing distance will not be reported to the participant. The HTML span element with id = distance-estimate returns the distance.","title":"Parameters"},{"location":"plugins/virtual-chinrest/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Note: The deg data are only returned if viewing distance is estimated with the blindspot method (px2deg, win_height_deg, win_width_deg, item_width_deg). Name Type Value rt numeric The response time in milliseconds. item_height_mm numeric The height in millimeters of the item to be measured. item_width_mm numeric The width in millimeters of the item to be measured item_height_deg numeric Final height of the resizable div container, in degrees. item_width_deg numeric Final width of the resizable div container, in degrees. item_width_px numeric Final width of the resizable div container, in pixels. px2deg numeric Pixels to degrees conversion factor. px2mm numeric Pixels to millimeters conversion factor. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. win_width_deg numeric The interior width of the window in degrees. win_height_deg numeric The interior height of the window in degrees. view_dist_mm numeric Estimated distance to the screen in millimeters.","title":"Data Generated"},{"location":"plugins/virtual-chinrest/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/virtual-chinrest/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-virtual-chinrest@2.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-virtual-chinrest.js\" >< /script> Using NPM: npm install @jspsych/plugin-virtual-chinrest import virtualChinrest from '@jspsych/plugin-virtual-chinrest' ;","title":"Install"},{"location":"plugins/virtual-chinrest/#example","text":"Measure distance to screen and pixel ratio; no resizing Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"none\" }; This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on centimeters per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"cm\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should be 10 cm x 10 cm.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on degrees of visual angle per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"deg\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should take up about 10 degrees of visual angle.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab","title":"Example"},{"location":"plugins/visual-search-circle/","text":"visual-search-circle \u00b6 Current version: 1.1.2. See version history . This plugin presents a customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. Here is an example using normal and backward Ns: Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. The set of images to display must be defined in one of two ways: The target , foil and set_size parameters: the combination of these parameters can be used to construct a 'classic' visual search task, where there is a single foil/distractor image that makes up all of the images in the set, with the exception of the target image if it is present. OR The stimuli parameter: this array that can be used to present any arbitrary set of image files, with or without the target image, with any number of different foils/distractors, and with any number of repeated images. The target_present and fixation_image parameters must always be specified. Other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description target string null Path to image file that is the search target. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. foil string null Path to image file that is the foil/distractor. This image will be repeated for all distractors up to the set_size value. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. set_size numeric null How many items should be displayed, including the target when target_present is true . The foil image will be repeated up to this value when target_present is false , or up to set_size - 1 when target_present is true . This parameter must specified when using the target , foil and set_size parameters to define the stimuli set, but should NOT be specified when using the stimuli parameter. stimuli array of images null Array containing all of the image files to be displayed. This parameter must be specified when NOT using the target , foil , and set_size parameters to define the stimuli set. target_present boolean undefined Is the target present? This parameter must always be specified. When using the target , foil and set_size parameters, false means that the foil image will be repeated up to the set_size, and true means that the target will be presented along with the foil image repeated up to set_size - 1. When using the stimuli parameter, this parameter is only used to determine the response accuracy. fixation_image string undefined Path to image file that is a fixation target. This parameter must always be specified. 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 participant is allowed to search before the trial will continue. A value of null will allow the participant to search indefinitely. fixation_duration numeric 1000 How long to show the fixation image for before the search array (in milliseconds). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value correct boolean True if the participant gave the correct response. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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 array Array where each element 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. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-visual-search-circle@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-visual-search-circle.js\" >< /script> Using NPM: npm install @jspsych/plugin-visual-search-circle import visualSearchCircle from '@jspsych/plugin-visual-search-circle' ; Examples \u00b6 Identical distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press J if there is a backwards N.</p> <p>Press F if all the Ns are in the normal orientation.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , target : 'img/backwardN.gif' , foil : 'img/normalN.gif' , fixation_image : 'img/fixation.gif' , target_present : true , set_size : 4 } Open demo in new tab Variety of different distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press E if there is an elephant in the group.</p> <p>Press N if there is no elephant in the group.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , stimuli : [ 'img/elephant.png' , 'img/lion.png' , 'img/monkey.png' ], fixation_image : 'img/fixation.gif' , target_present_key : 'e' , target_absent_key : 'n' , target_present : true } Open demo in new tab","title":"visual-search-circle"},{"location":"plugins/visual-search-circle/#visual-search-circle","text":"Current version: 1.1.2. See version history . This plugin presents a customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. Here is an example using normal and backward Ns:","title":"visual-search-circle"},{"location":"plugins/visual-search-circle/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. The set of images to display must be defined in one of two ways: The target , foil and set_size parameters: the combination of these parameters can be used to construct a 'classic' visual search task, where there is a single foil/distractor image that makes up all of the images in the set, with the exception of the target image if it is present. OR The stimuli parameter: this array that can be used to present any arbitrary set of image files, with or without the target image, with any number of different foils/distractors, and with any number of repeated images. The target_present and fixation_image parameters must always be specified. Other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description target string null Path to image file that is the search target. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. foil string null Path to image file that is the foil/distractor. This image will be repeated for all distractors up to the set_size value. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. set_size numeric null How many items should be displayed, including the target when target_present is true . The foil image will be repeated up to this value when target_present is false , or up to set_size - 1 when target_present is true . This parameter must specified when using the target , foil and set_size parameters to define the stimuli set, but should NOT be specified when using the stimuli parameter. stimuli array of images null Array containing all of the image files to be displayed. This parameter must be specified when NOT using the target , foil , and set_size parameters to define the stimuli set. target_present boolean undefined Is the target present? This parameter must always be specified. When using the target , foil and set_size parameters, false means that the foil image will be repeated up to the set_size, and true means that the target will be presented along with the foil image repeated up to set_size - 1. When using the stimuli parameter, this parameter is only used to determine the response accuracy. fixation_image string undefined Path to image file that is a fixation target. This parameter must always be specified. 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 participant is allowed to search before the trial will continue. A value of null will allow the participant to search indefinitely. fixation_duration numeric 1000 How long to show the fixation image for before the search array (in milliseconds).","title":"Parameters"},{"location":"plugins/visual-search-circle/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value correct boolean True if the participant gave the correct response. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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 array Array where each element 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. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/visual-search-circle/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-visual-search-circle@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-visual-search-circle.js\" >< /script> Using NPM: npm install @jspsych/plugin-visual-search-circle import visualSearchCircle from '@jspsych/plugin-visual-search-circle' ;","title":"Install"},{"location":"plugins/visual-search-circle/#examples","text":"Identical distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press J if there is a backwards N.</p> <p>Press F if all the Ns are in the normal orientation.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , target : 'img/backwardN.gif' , foil : 'img/normalN.gif' , fixation_image : 'img/fixation.gif' , target_present : true , set_size : 4 } Open demo in new tab Variety of different distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press E if there is an elephant in the group.</p> <p>Press N if there is no elephant in the group.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , stimuli : [ 'img/elephant.png' , 'img/lion.png' , 'img/monkey.png' ], fixation_image : 'img/fixation.gif' , target_present_key : 'e' , target_absent_key : 'n' , target_present : true } Open demo in new tab","title":"Examples"},{"location":"plugins/webgazer-calibrate/","text":"webgazer-calibrate \u00b6 Current version: 1.0.2. See version history . This plugin can be used to calibrate the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 calibration_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. Specified as a percentage of the screen width and height, from the left and top edge. The default grid is 9 points. calibration_mode string 'click' Can specify click to have participants click on calibration points or view to have participants passively watch calibration points. repetitions_per_point numeric 1 The number of times to repeat the sequence of calibration points. point_size numeric 20 Diameter of the calibration points in pixels. randomize_calibration_order bool false Whether to randomize the order of the calibration points. time_to_saccade numeric 1000 If calibration_mode is set to view , then this is the delay before calibrating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. time_per_point numeric 1000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value No data currently added by this plugin. Use the webgazer-validate plugin to measure the precision and accuracy of calibration. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-calibrate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-calibrate import webgazerCalibrate from '@jspsych/plugin-webgazer-calibrate' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-calibrate"},{"location":"plugins/webgazer-calibrate/#webgazer-calibrate","text":"Current version: 1.0.2. See version history . This plugin can be used to calibrate the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-calibrate"},{"location":"plugins/webgazer-calibrate/#parameters","text":"In addition to the 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 calibration_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. Specified as a percentage of the screen width and height, from the left and top edge. The default grid is 9 points. calibration_mode string 'click' Can specify click to have participants click on calibration points or view to have participants passively watch calibration points. repetitions_per_point numeric 1 The number of times to repeat the sequence of calibration points. point_size numeric 20 Diameter of the calibration points in pixels. randomize_calibration_order bool false Whether to randomize the order of the calibration points. time_to_saccade numeric 1000 If calibration_mode is set to view , then this is the delay before calibrating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. time_per_point numeric 1000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked.","title":"Parameters"},{"location":"plugins/webgazer-calibrate/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value No data currently added by this plugin. Use the webgazer-validate plugin to measure the precision and accuracy of calibration.","title":"Data Generated"},{"location":"plugins/webgazer-calibrate/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-calibrate/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-calibrate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-calibrate import webgazerCalibrate from '@jspsych/plugin-webgazer-calibrate' ;","title":"Install"},{"location":"plugins/webgazer-calibrate/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"plugins/webgazer-init-camera/","text":"webgazer-init-camera \u00b6 Current version: 1.0.2. See version history . This plugin initializes the camera and helps the participant center their face in the camera view for using the the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 instructions string too long to put here Instructions for the participant to follow. button_text string Continue The text for the button that participants click to end the trial. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value load_time numeric The time it took for webgazer to initialize. This can be a long time in some situations, so this value is recorded for troubleshooting when participants are reporting difficulty. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-init-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-init-camera import webgazerInitCamera from '@jspsych/plugin-webgazer-init-camera' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-init-camera"},{"location":"plugins/webgazer-init-camera/#webgazer-init-camera","text":"Current version: 1.0.2. See version history . This plugin initializes the camera and helps the participant center their face in the camera view for using the the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-init-camera"},{"location":"plugins/webgazer-init-camera/#parameters","text":"In addition to the 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 instructions string too long to put here Instructions for the participant to follow. button_text string Continue The text for the button that participants click to end the trial.","title":"Parameters"},{"location":"plugins/webgazer-init-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value load_time numeric The time it took for webgazer to initialize. This can be a long time in some situations, so this value is recorded for troubleshooting when participants are reporting difficulty.","title":"Data Generated"},{"location":"plugins/webgazer-init-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-init-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-init-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-init-camera import webgazerInitCamera from '@jspsych/plugin-webgazer-init-camera' ;","title":"Install"},{"location":"plugins/webgazer-init-camera/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"plugins/webgazer-validate/","text":"webgazer-validate \u00b6 Current version: 1.0.2. See version history . This plugin can be used to measure the accuracy and precision of gaze predictions made by the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 validation_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. The default grid is 9 points. Meaning of coordinates controlled by validation_point_coordinates parameter. validation_point_coordinates string 'percent' Can specify percent to have validation point coordinates specified in percentage of screen width and height, or center-offset-pixels to specify each point as the distance in pixels from the center of the screen. roi_radius numeric 200 Tolerance around the validation point in pixels when calculating the percent of gaze measurements within the acceptable range. randomize_validation_order bool false Whether to randomize the order of the validation points. time_to_saccade numeric 1000 The delay before validating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. validation_duration numeric 2000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. point_size numeric 20 Diameter of the validation points in pixels. show_validation_data bool false If true then a visualization of the validation data will be shown on the screen after the validation is complete. This will show each measured gaze location color coded by whether it is within the roi_radius of the target point. This is mainly intended for testing and debugging. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value raw_gaze array Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of {x,y,dx,dy} values specifying the absolute x and y pixels, as well as the distance from the target for that gaze point. percent_in_roi array The percentage of samples within the roi_radius for each validation point. average_offset array The average x and y distance from each validation point, plus the median distance r of the points from this average offset. samples_per_sec numeric The average number of samples per second. Calculated by finding samples per second for each point and then averaging these estimates together. validation_points array The list of validation points, in the order that they appeared. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-validate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-validate import webgazerValidate from '@jspsych/plugin-webgazer-validate' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-validate"},{"location":"plugins/webgazer-validate/#webgazer-validate","text":"Current version: 1.0.2. See version history . This plugin can be used to measure the accuracy and precision of gaze predictions made by the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-validate"},{"location":"plugins/webgazer-validate/#parameters","text":"In addition to the 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 validation_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. The default grid is 9 points. Meaning of coordinates controlled by validation_point_coordinates parameter. validation_point_coordinates string 'percent' Can specify percent to have validation point coordinates specified in percentage of screen width and height, or center-offset-pixels to specify each point as the distance in pixels from the center of the screen. roi_radius numeric 200 Tolerance around the validation point in pixels when calculating the percent of gaze measurements within the acceptable range. randomize_validation_order bool false Whether to randomize the order of the validation points. time_to_saccade numeric 1000 The delay before validating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. validation_duration numeric 2000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. point_size numeric 20 Diameter of the validation points in pixels. show_validation_data bool false If true then a visualization of the validation data will be shown on the screen after the validation is complete. This will show each measured gaze location color coded by whether it is within the roi_radius of the target point. This is mainly intended for testing and debugging.","title":"Parameters"},{"location":"plugins/webgazer-validate/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value raw_gaze array Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of {x,y,dx,dy} values specifying the absolute x and y pixels, as well as the distance from the target for that gaze point. percent_in_roi array The percentage of samples within the roi_radius for each validation point. average_offset array The average x and y distance from each validation point, plus the median distance r of the points from this average offset. samples_per_sec numeric The average number of samples per second. Calculated by finding samples per second for each point and then averaging these estimates together. validation_points array The list of validation points, in the order that they appeared.","title":"Data Generated"},{"location":"plugins/webgazer-validate/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-validate/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-validate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-validate import webgazerValidate from '@jspsych/plugin-webgazer-validate' ;","title":"Install"},{"location":"plugins/webgazer-validate/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"reference/jspsych-data/","text":"jsPsych.data \u00b6 The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins. jsPsych.data.addProperties \u00b6 jsPsych . data . addProperties ( properties ) Parameters \u00b6 Parameter Type Description properties object Object of key: value pairs to add to the data. Return value \u00b6 Returns nothing. Description \u00b6 This method appends a set of properties to every trial in the data object, including trials that have already occurred and trials that have yet to occur. You can use this to record things like the subject ID or condition assignment. Examples \u00b6 Assigning a subject ID and condition code \u00b6 jsPsych . data . addProperties ({ subject : 1 , condition : 'control' }); jsPsych.data.displayData \u00b6 jsPsych . data . displayData ( format ) Parameters \u00b6 Parameter Type Description format string Specifies whether to display the data in 'csv' or 'json' format. Return value \u00b6 Returns nothing. Description \u00b6 Outputs all of the data collected in the experiment to the screen in either JSON or CSV format. This is a useful method for quick debugging when developing an experiment. Examples \u00b6 Using the on_finish callback function to show data at the end of the experiment \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData ( 'csv' ); } }) jsPsych.data.get \u00b6 jsPsych.data.get() Parameters \u00b6 None. Return value \u00b6 Returns the data collection of all data generated by the experiment. Description \u00b6 This function is the standard starting point for accessing the data generated by the experiment. It returns a DataCollection object, which has several methods that can be used to further filter, aggregate, and view the data. These methods are described under the DataCollection section on this page. Example \u00b6 // select all trials var all_data = jsPsych . data . get (); // get csv representation of data and log to console console . log ( all_data . csv ()); jsPsych.data.getDataByTimelineNode \u00b6 jsPsych . data . getDataByTimelineNode ( node_id ) Parameters \u00b6 Parameter Type Description node_id string The id of the TimelineNodes to get data from. Return value \u00b6 Returns a DataCollection of all of the data generated in a specified TimelineNode. Description \u00b6 Get all the data generated by a specified Timeline. Example \u00b6 var current_node_id = jsPsych . getCurrentTimelineNodeID (); var data_from_current_node = jsPsych . data . getDataByTimelineNode ( current_node_id ); jsPsych.data.getInteractionData \u00b6 jsPsych . data . getInteractionData () Parameters \u00b6 None. Return value \u00b6 Returns a DataCollection object with all of the interaction events. Description \u00b6 jsPsych automatically records a few different kinds of user interaction events. blur events occur when the user clicks on another window or tab during the experiment, indicating that they are no longer interacting with the experiment. focus events occur when the user clicks on the experiment window after having clicked somewhere else first (i.e., generated a blur event). fullscreenenter and fullscreenexit events are triggered by the browser entering and exiting fullscreen mode. However, fullscreenenter events only occur when the script switches the browser to fullscreen mode, e.g., with the fullscreen plugin . Manually entering fullscreen mode does not trigger this event. fullscreenexit events occur whether the user manually exits fullscreen mode or the script exits fullscreen mode. This method returns the DataCollection containing all interaction events. This is useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form: { type : 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' , trial : 10 , // the trial number when the event happened time : 13042 // total time elapsed since the start of the experiment } Example \u00b6 var interaction_data = jsPsych . data . getInteractionData (); // log data to console in json format console . log ( interaction_data . json ()); jsPsych.data.getLastTimelineData \u00b6 jsPsych . data . getLastTimelineData () Return value \u00b6 Returns a DataCollection. Description \u00b6 Gets all of the data generated in the same timeline as the last trial. Example \u00b6 var lasttimelinedata = jsPsych . data . getLastTimelineData (); jsPsych.data.getLastTrialData \u00b6 jsPsych . data . getLastTrialData () Return value \u00b6 Returns a DataCollection. Description \u00b6 Gets the data collection containing all data generated by the last trial. Example \u00b6 var lasttrialdata = jsPsych . data . getLastTrialData (); jsPsych.data.getURLVariable \u00b6 jsPsych . data . getURLVariable ( var_name ) Parameters \u00b6 Parameter Type Description var_name string Which variable to get the value of. Return value \u00b6 Returns the value of a variable passed in through the query string. Description \u00b6 For extracting a particular variable passed in through a URL query string. Example \u00b6 // if the URL of the page is: experiment.html?subject=1234&condition=test console . log ( jsPsych . data . getURLVariable ( 'subject' )) // logs \"1234\" console . log ( jsPsych . data . getURLVariable ( 'condition' )) // logs \"test\" jsPsych.data.urlVariables \u00b6 jsPsych . data . urlVariables () Return value \u00b6 Returns an object (associative array) of the variables in the URL query string. Description \u00b6 For extracting variables passed in through a URL query string. Example \u00b6 // if the URL of the page is: experiment.html?subject=1234&condition=test var urlvar = jsPsych . data . urlVariables (); console . log ( urlvar . subject ) // logs \"1234\" console . log ( urlvar . condition ) // logs \"test\" jsPsych.data.write \u00b6 jsPsych . data . write ( data_object ) Parameters \u00b6 Parameter Type Description data_object object Object of key: value pairs to store in jsPsych's data storage as a trial. Return value \u00b6 Returns nothing. Description \u00b6 This method is used by jsPsych.finishTrial for writing data. You should probably not use it to add data. Instead use jsPsych.data.addProperties . Example \u00b6 // don't use this! data should only be written once per trial. use jsPsych.finishTrial to save data. var trial_data = { correct : true , rt : 487 } jsPsych . data . write ( trial_data ); DataCollection \u00b6 All data is stored in the DataCollection object. Using methods like jsPsych.data.get() and jsPsych.data.getLastTrialData() return DataCollections containing the experiment data. This is a list of all of the methods that are available to call on a DataCollection object. .addToAll() \u00b6 Adds a set of properties to all items in the DataCollection. Similar to jsPsych.data.addProperties() , except that it can be applied to a subset of the whole DataCollection by filtering down to a smaller DataCollection first. jsPsych . data . get (). addToAll ({ subject_id : 123 , condition : 'control' }); .addToLast() \u00b6 Adds a set of properties to the last trial in the DataCollection. jsPsych . data . get (). addToLast ({ success : true }); .count() \u00b6 Counts the number of trials in the DataCollection. jsPsych . data . get (). count () .csv() \u00b6 Generates a CSV string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). csv ()); .filter() \u00b6 Returns a subset of the DataCollection based on the filter. The filter is an object, and trials are only kept in the returned DataCollection if they contain the key: value pair(s) in the filter object. For example, the code below selects all of the trials with a correct response. var correct_trials = jsPsych . data . get (). filter ({ correct : true }); The object can have multiple key: value pairs, and the trials must match all of them in order to be included in the returned collection. // keep only correct trials from the practice phase var correct_practice_trials = jsPsych . data . get (). filter ({ correct : true , phase : 'practice' }); The filter can also be an array of objects. In this case each object in the array acts as an OR filter. As long as the trial has all the key: value pairs of one of the objects in the array, it will appear in the returned collection. // select trials from block 1 and block 5. var trials = jsPsych . data . get (). filter ([{ block : 1 }, { block : 5 }]); The filter method returns a DataCollection object, so methods can be chained onto a single statement. // count the number of correct trials in block 1 var block_1_correct = jsPsych . data . get (). filter ({ block : 1 , correct : true }). count (); .filterColumns() \u00b6 Selects the set of columns listed in the array. This is the opposite of the .ignore() method. // Get only the subject, rt, and condition entries for each trial. const subset_of_data = jsPsych . data . get (). filterColumns ([ 'subject' , 'rt' , 'condition' ]) .filterCustom() \u00b6 This method is similar to the .filter() method, except that it accepts a function as the filter. The function is passed a single argument, containing the data for a trial. If the function returns true the trial is included in the returned DataCollection. // count the number of trials with a response time greater than 2000ms. var too_long = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 2000 ; }). count () .first() / .last() \u00b6 Returns a DataCollection containing the first/last n trials. If n is greater than the number of trials in the DataCollection, then these functions will return an array of length equal to the number of trials. If there are no trials in the DataCollection, then these functions will return an empty array. If the n argument is omitted, then the functions will use the default value of 1. If n is zero or a negative number, then these functions will throw an error. var first_trial = jsPsych . data . get (). first ( 1 ); var last_trial_with_correct_response = jsPsych . data . get (). filter ({ correct : true }). last ( 1 ); var last_10_trials = jsPsych . data . get (). last ( 10 ); .ignore() \u00b6 Returns a DataCollection with all instances of a particular key removed from the dataset. // log a csv file that does not contain the internal_node_id values for each trial console . log ( jsPsych . data . get (). ignore ( 'internal_node_id' ). csv ()); .join() \u00b6 Appends one DataCollection onto another and returns the combined collection. // get a DataCollection with all trials that are either correct or // have a response time greater than 200ms. var dc1 = jsPsych . data . get (). filter ({ correct : true }); var dc2 = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 200 }); var data = dc1 . join ( dc2 ); .json() \u00b6 Generates a JSON string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). json ()); .localSave() \u00b6 Saves a CSV or JSON file on the computer running the experiment. If conducting an online experiment, this will download the file onto the subject's computer, and is therefore not a recommended data storage solution for online data collection. Warning: This function may not behave correctly in older browsers. Upgrading to the latest version of any major web browser should solve the problem. // first argument is the format, second is the filename. // the format can be either 'csv' or 'json'. jsPsych . data . get (). localSave ( 'csv' , 'mydata.csv' ); .push() \u00b6 Add a new entry to the DataCollection. This method is mostly used internally, and you shouldn't need to call it under normal circumstances. var data = { correct : true , rt : 500 } jsPsych . data . get (). push ( data ); .readOnly() \u00b6 Creates a copy of the DataCollection so that any modification of the values in the DataCollection will not affect the original. // this line edits the rt property of the first trial jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt = 100 ; // readOnly creates a copy that can be modified without affecting the original jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // outputs 100 jsPsych . data . get (). readOnly (). first ( 1 ). values ()[ 0 ]. rt = 200 jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // still outputs 100 .select() \u00b6 Returns a DataColumn object (see documentation below) of a single property from a DataCollection object. var rt_data = jsPsych . data . get (). select ( 'rt' ); rt_data . mean () .uniqueNames() \u00b6 Generates an array of all the unique key names in the set of trials contained in the DataCollection. This is especially useful when setting up a relational database (e.g., MySQL) where the column names need to be specified in advance. console . log ( jsPsych . data . get (). uniqueNames ()); .values() \u00b6 Returns the raw data array associated with the DataCollection. This array is modifiable, so changes to the array and values of objects in the array will change the DataCollection. var raw_data = jsPsych . data . get (). values (); // was response in first trial correct? if ( raw_data [ 0 ]. correct ){ console . log ( 'correct!' ); } else { console . log ( 'incorrect.' ); } DataColumn \u00b6 DataColumn objects represent all the values of a single property in a DataCollection. They are generated by using the .select() method on a DataCollection. Once a DataColumn is generated, the following methods can be used. .all() \u00b6 Checks if all values in the DataColumn return true when passed to a function. The function takes a single argument, which represents one value from the DataColumn. // check if all the response times in the practice phase were under 1000ms jsPsych . data . get (). filter ({ phase : 'practice' }). select ( 'correct' ). all ( function ( x ) { return x < 1000 ; }); .count() \u00b6 Counts the number of values in the DataColumn. // count how many response times there are jsPsych . data . get (). select ( 'rt' ). count (); .frequencies() \u00b6 Counts the number of occurrences of each unique value in the DataColumn. Returns this value as an object, where each key is a unique value and the value of each key is the number of occurrences of that key. // get frequencies of correct and incorrect responses jsPsych . data . get (). select ( 'correct' ). frequencies (); .max() / .min() \u00b6 Returns the maximum or minimum value in a DataColumn. jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). min (); .mean() \u00b6 Returns the average of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). mean (); .median() \u00b6 Returns the median of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). median (); .sd() \u00b6 Returns the standard deviation of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sd (); .subset() \u00b6 Filters the DataColumn to include only values that return true when passed through the specified function. // below results will be less than 200. jsPsych . data . get (). select ( 'rt' ). subset ( function ( x ){ return x < 200 ; }). max (); .sum() \u00b6 Returns the sum of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sum (); .values \u00b6 The raw array of values in the DataColumn. // note that this is not a function call. jsPsych . data . get (). select ( 'rt' ). values ; .variance() \u00b6 Returns the variance of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). variance ();","title":"jsPsych.data"},{"location":"reference/jspsych-data/#jspsychdata","text":"The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins.","title":"jsPsych.data"},{"location":"reference/jspsych-data/#jspsychdataaddproperties","text":"jsPsych . data . addProperties ( properties )","title":"jsPsych.data.addProperties"},{"location":"reference/jspsych-data/#parameters","text":"Parameter Type Description properties object Object of key: value pairs to add to the data.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description","text":"This method appends a set of properties to every trial in the data object, including trials that have already occurred and trials that have yet to occur. You can use this to record things like the subject ID or condition assignment.","title":"Description"},{"location":"reference/jspsych-data/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-data/#assigning-a-subject-id-and-condition-code","text":"jsPsych . data . addProperties ({ subject : 1 , condition : 'control' });","title":"Assigning a subject ID and condition code"},{"location":"reference/jspsych-data/#jspsychdatadisplaydata","text":"jsPsych . data . displayData ( format )","title":"jsPsych.data.displayData"},{"location":"reference/jspsych-data/#parameters_1","text":"Parameter Type Description format string Specifies whether to display the data in 'csv' or 'json' format.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_1","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description_1","text":"Outputs all of the data collected in the experiment to the screen in either JSON or CSV format. This is a useful method for quick debugging when developing an experiment.","title":"Description"},{"location":"reference/jspsych-data/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-data/#using-the-on_finish-callback-function-to-show-data-at-the-end-of-the-experiment","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData ( 'csv' ); } })","title":"Using the on_finish callback function to show data at the end of the experiment"},{"location":"reference/jspsych-data/#jspsychdataget","text":"jsPsych.data.get()","title":"jsPsych.data.get"},{"location":"reference/jspsych-data/#parameters_2","text":"None.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_2","text":"Returns the data collection of all data generated by the experiment.","title":"Return value"},{"location":"reference/jspsych-data/#description_2","text":"This function is the standard starting point for accessing the data generated by the experiment. It returns a DataCollection object, which has several methods that can be used to further filter, aggregate, and view the data. These methods are described under the DataCollection section on this page.","title":"Description"},{"location":"reference/jspsych-data/#example","text":"// select all trials var all_data = jsPsych . data . get (); // get csv representation of data and log to console console . log ( all_data . csv ());","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetdatabytimelinenode","text":"jsPsych . data . getDataByTimelineNode ( node_id )","title":"jsPsych.data.getDataByTimelineNode"},{"location":"reference/jspsych-data/#parameters_3","text":"Parameter Type Description node_id string The id of the TimelineNodes to get data from.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_3","text":"Returns a DataCollection of all of the data generated in a specified TimelineNode.","title":"Return value"},{"location":"reference/jspsych-data/#description_3","text":"Get all the data generated by a specified Timeline.","title":"Description"},{"location":"reference/jspsych-data/#example_1","text":"var current_node_id = jsPsych . getCurrentTimelineNodeID (); var data_from_current_node = jsPsych . data . getDataByTimelineNode ( current_node_id );","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetinteractiondata","text":"jsPsych . data . getInteractionData ()","title":"jsPsych.data.getInteractionData"},{"location":"reference/jspsych-data/#parameters_4","text":"None.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_4","text":"Returns a DataCollection object with all of the interaction events.","title":"Return value"},{"location":"reference/jspsych-data/#description_4","text":"jsPsych automatically records a few different kinds of user interaction events. blur events occur when the user clicks on another window or tab during the experiment, indicating that they are no longer interacting with the experiment. focus events occur when the user clicks on the experiment window after having clicked somewhere else first (i.e., generated a blur event). fullscreenenter and fullscreenexit events are triggered by the browser entering and exiting fullscreen mode. However, fullscreenenter events only occur when the script switches the browser to fullscreen mode, e.g., with the fullscreen plugin . Manually entering fullscreen mode does not trigger this event. fullscreenexit events occur whether the user manually exits fullscreen mode or the script exits fullscreen mode. This method returns the DataCollection containing all interaction events. This is useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form: { type : 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' , trial : 10 , // the trial number when the event happened time : 13042 // total time elapsed since the start of the experiment }","title":"Description"},{"location":"reference/jspsych-data/#example_2","text":"var interaction_data = jsPsych . data . getInteractionData (); // log data to console in json format console . log ( interaction_data . json ());","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetlasttimelinedata","text":"jsPsych . data . getLastTimelineData ()","title":"jsPsych.data.getLastTimelineData"},{"location":"reference/jspsych-data/#return-value_5","text":"Returns a DataCollection.","title":"Return value"},{"location":"reference/jspsych-data/#description_5","text":"Gets all of the data generated in the same timeline as the last trial.","title":"Description"},{"location":"reference/jspsych-data/#example_3","text":"var lasttimelinedata = jsPsych . data . getLastTimelineData ();","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetlasttrialdata","text":"jsPsych . data . getLastTrialData ()","title":"jsPsych.data.getLastTrialData"},{"location":"reference/jspsych-data/#return-value_6","text":"Returns a DataCollection.","title":"Return value"},{"location":"reference/jspsych-data/#description_6","text":"Gets the data collection containing all data generated by the last trial.","title":"Description"},{"location":"reference/jspsych-data/#example_4","text":"var lasttrialdata = jsPsych . data . getLastTrialData ();","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatageturlvariable","text":"jsPsych . data . getURLVariable ( var_name )","title":"jsPsych.data.getURLVariable"},{"location":"reference/jspsych-data/#parameters_5","text":"Parameter Type Description var_name string Which variable to get the value of.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_7","text":"Returns the value of a variable passed in through the query string.","title":"Return value"},{"location":"reference/jspsych-data/#description_7","text":"For extracting a particular variable passed in through a URL query string.","title":"Description"},{"location":"reference/jspsych-data/#example_5","text":"// if the URL of the page is: experiment.html?subject=1234&condition=test console . log ( jsPsych . data . getURLVariable ( 'subject' )) // logs \"1234\" console . log ( jsPsych . data . getURLVariable ( 'condition' )) // logs \"test\"","title":"Example"},{"location":"reference/jspsych-data/#jspsychdataurlvariables","text":"jsPsych . data . urlVariables ()","title":"jsPsych.data.urlVariables"},{"location":"reference/jspsych-data/#return-value_8","text":"Returns an object (associative array) of the variables in the URL query string.","title":"Return value"},{"location":"reference/jspsych-data/#description_8","text":"For extracting variables passed in through a URL query string.","title":"Description"},{"location":"reference/jspsych-data/#example_6","text":"// if the URL of the page is: experiment.html?subject=1234&condition=test var urlvar = jsPsych . data . urlVariables (); console . log ( urlvar . subject ) // logs \"1234\" console . log ( urlvar . condition ) // logs \"test\"","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatawrite","text":"jsPsych . data . write ( data_object )","title":"jsPsych.data.write"},{"location":"reference/jspsych-data/#parameters_6","text":"Parameter Type Description data_object object Object of key: value pairs to store in jsPsych's data storage as a trial.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_9","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description_9","text":"This method is used by jsPsych.finishTrial for writing data. You should probably not use it to add data. Instead use jsPsych.data.addProperties .","title":"Description"},{"location":"reference/jspsych-data/#example_7","text":"// don't use this! data should only be written once per trial. use jsPsych.finishTrial to save data. var trial_data = { correct : true , rt : 487 } jsPsych . data . write ( trial_data );","title":"Example"},{"location":"reference/jspsych-data/#datacollection","text":"All data is stored in the DataCollection object. Using methods like jsPsych.data.get() and jsPsych.data.getLastTrialData() return DataCollections containing the experiment data. This is a list of all of the methods that are available to call on a DataCollection object.","title":"DataCollection"},{"location":"reference/jspsych-data/#addtoall","text":"Adds a set of properties to all items in the DataCollection. Similar to jsPsych.data.addProperties() , except that it can be applied to a subset of the whole DataCollection by filtering down to a smaller DataCollection first. jsPsych . data . get (). addToAll ({ subject_id : 123 , condition : 'control' });","title":".addToAll()"},{"location":"reference/jspsych-data/#addtolast","text":"Adds a set of properties to the last trial in the DataCollection. jsPsych . data . get (). addToLast ({ success : true });","title":".addToLast()"},{"location":"reference/jspsych-data/#count","text":"Counts the number of trials in the DataCollection. jsPsych . data . get (). count ()","title":".count()"},{"location":"reference/jspsych-data/#csv","text":"Generates a CSV string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). csv ());","title":".csv()"},{"location":"reference/jspsych-data/#filter","text":"Returns a subset of the DataCollection based on the filter. The filter is an object, and trials are only kept in the returned DataCollection if they contain the key: value pair(s) in the filter object. For example, the code below selects all of the trials with a correct response. var correct_trials = jsPsych . data . get (). filter ({ correct : true }); The object can have multiple key: value pairs, and the trials must match all of them in order to be included in the returned collection. // keep only correct trials from the practice phase var correct_practice_trials = jsPsych . data . get (). filter ({ correct : true , phase : 'practice' }); The filter can also be an array of objects. In this case each object in the array acts as an OR filter. As long as the trial has all the key: value pairs of one of the objects in the array, it will appear in the returned collection. // select trials from block 1 and block 5. var trials = jsPsych . data . get (). filter ([{ block : 1 }, { block : 5 }]); The filter method returns a DataCollection object, so methods can be chained onto a single statement. // count the number of correct trials in block 1 var block_1_correct = jsPsych . data . get (). filter ({ block : 1 , correct : true }). count ();","title":".filter()"},{"location":"reference/jspsych-data/#filtercolumns","text":"Selects the set of columns listed in the array. This is the opposite of the .ignore() method. // Get only the subject, rt, and condition entries for each trial. const subset_of_data = jsPsych . data . get (). filterColumns ([ 'subject' , 'rt' , 'condition' ])","title":".filterColumns()"},{"location":"reference/jspsych-data/#filtercustom","text":"This method is similar to the .filter() method, except that it accepts a function as the filter. The function is passed a single argument, containing the data for a trial. If the function returns true the trial is included in the returned DataCollection. // count the number of trials with a response time greater than 2000ms. var too_long = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 2000 ; }). count ()","title":".filterCustom()"},{"location":"reference/jspsych-data/#first-last","text":"Returns a DataCollection containing the first/last n trials. If n is greater than the number of trials in the DataCollection, then these functions will return an array of length equal to the number of trials. If there are no trials in the DataCollection, then these functions will return an empty array. If the n argument is omitted, then the functions will use the default value of 1. If n is zero or a negative number, then these functions will throw an error. var first_trial = jsPsych . data . get (). first ( 1 ); var last_trial_with_correct_response = jsPsych . data . get (). filter ({ correct : true }). last ( 1 ); var last_10_trials = jsPsych . data . get (). last ( 10 );","title":".first() / .last()"},{"location":"reference/jspsych-data/#ignore","text":"Returns a DataCollection with all instances of a particular key removed from the dataset. // log a csv file that does not contain the internal_node_id values for each trial console . log ( jsPsych . data . get (). ignore ( 'internal_node_id' ). csv ());","title":".ignore()"},{"location":"reference/jspsych-data/#join","text":"Appends one DataCollection onto another and returns the combined collection. // get a DataCollection with all trials that are either correct or // have a response time greater than 200ms. var dc1 = jsPsych . data . get (). filter ({ correct : true }); var dc2 = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 200 }); var data = dc1 . join ( dc2 );","title":".join()"},{"location":"reference/jspsych-data/#json","text":"Generates a JSON string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). json ());","title":".json()"},{"location":"reference/jspsych-data/#localsave","text":"Saves a CSV or JSON file on the computer running the experiment. If conducting an online experiment, this will download the file onto the subject's computer, and is therefore not a recommended data storage solution for online data collection. Warning: This function may not behave correctly in older browsers. Upgrading to the latest version of any major web browser should solve the problem. // first argument is the format, second is the filename. // the format can be either 'csv' or 'json'. jsPsych . data . get (). localSave ( 'csv' , 'mydata.csv' );","title":".localSave()"},{"location":"reference/jspsych-data/#push","text":"Add a new entry to the DataCollection. This method is mostly used internally, and you shouldn't need to call it under normal circumstances. var data = { correct : true , rt : 500 } jsPsych . data . get (). push ( data );","title":".push()"},{"location":"reference/jspsych-data/#readonly","text":"Creates a copy of the DataCollection so that any modification of the values in the DataCollection will not affect the original. // this line edits the rt property of the first trial jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt = 100 ; // readOnly creates a copy that can be modified without affecting the original jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // outputs 100 jsPsych . data . get (). readOnly (). first ( 1 ). values ()[ 0 ]. rt = 200 jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // still outputs 100","title":".readOnly()"},{"location":"reference/jspsych-data/#select","text":"Returns a DataColumn object (see documentation below) of a single property from a DataCollection object. var rt_data = jsPsych . data . get (). select ( 'rt' ); rt_data . mean ()","title":".select()"},{"location":"reference/jspsych-data/#uniquenames","text":"Generates an array of all the unique key names in the set of trials contained in the DataCollection. This is especially useful when setting up a relational database (e.g., MySQL) where the column names need to be specified in advance. console . log ( jsPsych . data . get (). uniqueNames ());","title":".uniqueNames()"},{"location":"reference/jspsych-data/#values","text":"Returns the raw data array associated with the DataCollection. This array is modifiable, so changes to the array and values of objects in the array will change the DataCollection. var raw_data = jsPsych . data . get (). values (); // was response in first trial correct? if ( raw_data [ 0 ]. correct ){ console . log ( 'correct!' ); } else { console . log ( 'incorrect.' ); }","title":".values()"},{"location":"reference/jspsych-data/#datacolumn","text":"DataColumn objects represent all the values of a single property in a DataCollection. They are generated by using the .select() method on a DataCollection. Once a DataColumn is generated, the following methods can be used.","title":"DataColumn"},{"location":"reference/jspsych-data/#all","text":"Checks if all values in the DataColumn return true when passed to a function. The function takes a single argument, which represents one value from the DataColumn. // check if all the response times in the practice phase were under 1000ms jsPsych . data . get (). filter ({ phase : 'practice' }). select ( 'correct' ). all ( function ( x ) { return x < 1000 ; });","title":".all()"},{"location":"reference/jspsych-data/#count_1","text":"Counts the number of values in the DataColumn. // count how many response times there are jsPsych . data . get (). select ( 'rt' ). count ();","title":".count()"},{"location":"reference/jspsych-data/#frequencies","text":"Counts the number of occurrences of each unique value in the DataColumn. Returns this value as an object, where each key is a unique value and the value of each key is the number of occurrences of that key. // get frequencies of correct and incorrect responses jsPsych . data . get (). select ( 'correct' ). frequencies ();","title":".frequencies()"},{"location":"reference/jspsych-data/#max-min","text":"Returns the maximum or minimum value in a DataColumn. jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). min ();","title":".max() / .min()"},{"location":"reference/jspsych-data/#mean","text":"Returns the average of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). mean ();","title":".mean()"},{"location":"reference/jspsych-data/#median","text":"Returns the median of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). median ();","title":".median()"},{"location":"reference/jspsych-data/#sd","text":"Returns the standard deviation of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sd ();","title":".sd()"},{"location":"reference/jspsych-data/#subset","text":"Filters the DataColumn to include only values that return true when passed through the specified function. // below results will be less than 200. jsPsych . data . get (). select ( 'rt' ). subset ( function ( x ){ return x < 200 ; }). max ();","title":".subset()"},{"location":"reference/jspsych-data/#sum","text":"Returns the sum of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sum ();","title":".sum()"},{"location":"reference/jspsych-data/#values_1","text":"The raw array of values in the DataColumn. // note that this is not a function call. jsPsych . data . get (). select ( 'rt' ). values ;","title":".values"},{"location":"reference/jspsych-data/#variance","text":"Returns the variance of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). variance ();","title":".variance()"},{"location":"reference/jspsych-pluginAPI/","text":"jsPsych.pluginAPI \u00b6 The pluginAPI module contains functions that are useful when developing plugins. All of the functions are accessible through the pluginAPI object. In this documentation we've divided them up based on different kinds of functionality. Keyboard Input \u00b6 cancelAllKeyboardResponses \u00b6 jsPsych . pluginAPI . cancelAllKeyboardResponses () Parameters \u00b6 None. Return value \u00b6 Returns nothing. Description \u00b6 Cancels all currently active keyboard listeners created by jsPsych.pluginAPI.getKeyboardResponse . Example \u00b6 jsPsych . pluginAPI . cancelAllKeyboardResponses (); cancelKeyboardResponse \u00b6 jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id ) Parameters \u00b6 Parameter Type Description listener_id object The listener_id object generated by the call to jsPsych.pluginAPI.getKeyboardResponse . Return value \u00b6 Returns nothing. Description \u00b6 Cancels a specific keyboard listener created by jsPsych.pluginAPI.getKeyboardResponse . Example \u00b6 // create a persistent keyboard listener var listener_id = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : [ 'p' , 'q' ], rt_method : 'performance' , persist : true , allow_held_key : false }); // cancel keyboard listener jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id ); compareKeys \u00b6 jsPsych . pluginAPI . compareKeys ( key1 , key2 ) Parameters \u00b6 Parameter Type Description key1 string or numeric The representation of a key, either string or keycode key2 string or numeric The representation of a key, either string or keycode Return value \u00b6 Returns true if keycodes or strings refer to the same key, regardless of type. Returns false if the keycodes or strings do not match. Description \u00b6 Compares two keys to see if they are the same, ignoring differences in representational type, and using the appropriate case sensitivity based on the experiment's settings. If case_sensitive_responses is set to false in initJsPsych (the default), then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will match, and this function will return true . If case_sensitive_responses is set to true in initJsPsych , then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will not match, and this function will return false . We recommend using this function to compare keys in all plugin and experiment code, rather than using something like if (response == 'j')... . This is because the response key returned by the jsPsych.pluginAPI.getKeyboardResponse function will be converted to lowercase when case_sensitive_responses is false , and it will match the exact key press representation when case_sensitive_responses is true . Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting, and that you do not need to remember to check key responses against different case versions of the comparison key (e.g. if (response == 'ArrowLeft' || response == 'arrowleft')... ). Examples \u00b6 Basic examples \u00b6 jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns true when case_sensitive_responses is false in initJsPsych jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns false when case_sensitive_responses is true in initJsPsych // also works with numeric key codes (but note that numeric keyCode values are now deprecated) jsPsych . pluginAPI . compareKeys ( 'a' , 65 ); // returns true jsPsych . pluginAPI . compareKeys ( 'space' , 31 ); // returns false Comparing a key response and key parameter value in plugins \u00b6 // this is the callback_function passed to jsPsych.pluginAPI.getKeyboardResponse var after_response = function ( info ) { // score the response by comparing the key that was pressed against the trial's key_answer parameter var correct = jsPsych . pluginAPI . compareKeys ( trial . key_answer , info . key ); //... } Scoring a key response in experiment code \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], prompt : 'Press f for left. Press j for right.' , on_finish : function ( data ){ // score the response by comparing the key that was pressed (data.response) against the // correct response for this trial ('f'), and store reponse accuracy in the trial data if ( jsPsych . pluginAPI . compareKeys ( data . response , 'f' )){ data . correct = true ; } else { data . correct = false ; } } } getKeyboardResponse \u00b6 jsPsych . pluginAPI . getKeyboardResponse ( parameters ) Parameters \u00b6 The method accepts an object of parameter values (see example below). The valid keys for this object are listed in the table below. Parameter Type Description callback_function function The function to execute whenever a valid keyboard response is generated. valid_responses array An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable. rt_method string Indicates which method of recording time to use. The 'performance' method uses calls to performance.now() , which is the standard way of measuring timing in jsPsych. It is supported by up-to-date versions of all the major browsers . The audio method is used in conjuction with an audio_context (set as an additional parameter). This uses the clock time of the audio_context when audio stimuli are being played. audio_context AudioContext object The AudioContext of the audio file that is being played. audio_context_start_time numeric The scheduled time of the sound file in the AudioContext. This will be used as the start time. allow_held_key boolean If true , then responses will be registered from keys that are being held down. If false , then a held key can only register a response the first time that getKeyboardResponse is called for that key. For example, if a participant holds down the A key before the experiment starts, then the first time getKeyboardResponse is called, the A will register as a key press. However, any future calls to getKeyboardResponse will not register the A until the participant releases the key and presses it again. persist boolean If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by jsPsych.pluginAPI.cancelKeyboardResponse or jsPsych.pluginAPI.cancelAllKeyboardResponses . Return value \u00b6 Return an object that uniquely identifies the keyboard listener. This object can be passed to jsPsych.pluginAPI.cancelKeyboardResponse to cancel the keyboard listener. Description \u00b6 Gets a keyboard response from the participant, recording the response time from when the function is first called until a valid response is generated. The keyboard event listener will be bound to the display_element declared in initJsPsych() (or the <body> element if no display_element is specified). This allows jsPsych experiments to be embedded in websites with other content without disrupting the functionality of other UI elements. A valid response triggers the callback_function specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties key and rt . key contains the string representation of the response key, and rt contains the response time. This function uses the .key value of the keyboard event, which is case sensitive . When case_sensitive_responses is false in initJsPsych (the default), this function will convert both the valid_responses strings and the response key to lowercase before comparing them, and it will pass the lowercase version of the response key to the callback_function . For example, if valid_responses is ['a'] , then both 'A' and 'a' will be considered valid key presses, and 'a' will be returned as the response key. When case_sensitive_responses is true in initJsPsych , this function will not convert the case when comparing the valid_responses and response key, and it will not convert the case of the response key that is passed to the callback_function . For example, if valid_responses is ['a'] , then 'a' will be the only valid key press, and 'A' (i.e. 'a' with CapsLock on or Shift held down) will not be accepted. Also, if valid_responses includes multiple letter case options (e.g. \"ALL_KEYS\" ), then you may need to check the response key against both letter cases when scoring etc., e.g. if (response == 'ArrowLeft' || response =='arrowleft') ... . Examples \u00b6 Get a single response from any key \u00b6 var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); } jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : false }); Get a responses from a key until the letter q is pressed \u00b6 var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); if ( jsPsych . pluginAPI . compareKeys ( info . key , 'q' )){ / jsPsych . pluginAPI . cancelKeyboardResponse ( listener ); } } var listener = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : true }); Media \u00b6 getAudioBuffer \u00b6 jsPsych . pluginAPI . getAudioBuffer ( filepath ) Parameters \u00b6 Parameter Type Description filepath string The path to the audio file that was preloaded. Return value \u00b6 Returns a Promise that resolves when the audio file loads. Success handler's parameter will be the audio buffer. If the experiment is running using the WebAudio API it will be an AudioBuffer object. Otherwise, it will be an HTML5 Audio object. The failure handler's parameter is the error generated by preloadAudio . Description \u00b6 Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. It is strongly recommended that you preload audio files before calling this method. This method will load the files if they are not preloaded, but this may result in delays during the experiment as audio is downloaded. Examples \u00b6 HTML 5 Audio \u00b6 jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( audio ){ audio . play (); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) WebAudio API \u00b6 var context = jsPsych . pluginAPI . audioContext (); jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( buffer ){ audio = context . createBufferSource (); audio . buffer = buffer ; audio . connect ( context . destination ); audio . start ( context . currentTime ); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) See the audio-keyboard-response plugin for an example in a fuller context. getAutoPreloadList \u00b6 jsPsych . pluginAPI . getAutoPreloadList ( timeline ) Parameters \u00b6 Parameter Type Description timeline array An array containing the trial object(s) from which a list of media files should be automatically generated. This array can contain the entire experiment timeline, or any individual parts of a larger timeline, such as specific timeline nodes and trial objects. Return value \u00b6 An object with properties for each media type: images , audio , and video . Each property contains an array of the unique files of that media type that were automatically extracted from the timeline. If no files are found in the timeline for a particular media type, then the array will be empty for that type. Description \u00b6 This method is used to automatically generate lists of unique image, audio, and video files from a timeline. It is used by the preload plugin to generate a list of to-be-preloaded files based on the trials passed to the trials parameter and/or the experiment timeline passed to jsPsych.run (when auto_preload is true). It can be used in custom plugins and experiment code to generate a list of audio/image/video files, based on a timeline. This function will only return files from plugin parameters that are marked as parameter type AUDIO / IMAGE / VIDEO , and only when the preload flag of the corresponding parameter definition has not been set to false , and the trial's parameter value is not a function. When a file path is returned to the trial parameter from a function (including the jsPsych.timelineVariable function), or when the file path is embedded in an HTML string, that file will not be detected by the getAutoPreloadList method. In these cases, the file should be preloaded manually. See Media Preloading for more information. Example \u00b6 var audio_trial = { type : jsPsychAudioKeyboardResponse stimulus : 'file.mp3' } var image_trial = { type : jsPsychImageKeyboardResponse stimulus : 'file.png' } var video_trial = { type : jsPsychVideoKeyboardResponse stimulus : 'file.mp4' } var timeline = [ audio_trial , image_trial , video_trial ]; jsPsych . pluginAPI . getAutoPreloadList ( timeline ); getMicrophoneRecorder \u00b6 jsPsych . pluginAPI . getMicrophoneRecorder () Parameters \u00b6 None Return value \u00b6 A MediaRecorder object connected to the MediaStream for the active microphone. Description \u00b6 Provides access to the MediaRecorder created by initializeMicrophoneRecorder() . If no microphone recorder exists, it returns null . Example \u00b6 const recorder = jsPsych . pluginAPI . getMicrophoneRecorder (); initializeMicrophoneRecorder \u00b6 jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream ) Parameters \u00b6 Parameter Type Description stream MediaStream The MediaStream object from an active microphone device. Return value \u00b6 None. Description \u00b6 Generates a MediaRecorder object from provided MediaStream and stores this for access via getMicrophoneRecorder() . Example \u00b6 const stream = await navigator . mediaDevices . getUserMedia ({ audio : { deviceId : mic_id } }); jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream ); preloadAudio \u00b6 jsPsych . pluginAPI . preloadAudio ( files , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description files array An array of audio file paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the files have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload audio files. It is used by the preload plugin, and could be called directly to preload audio files in custom plugins or experiment. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the files are loaded. Thus, it is possible that an audio file would be required for playing before it is done preloading. The callback_complete function will only execute after all the audio files are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / sounds . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of audio files' ); } function startExperiment (){ jsPsych . run ( exp ); } preloadImages \u00b6 jsPsych . pluginAPI . preloadImages ( images , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description images array An array of image paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the images have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload image files. It is used by the preload plugin, and could be called directly to preload image files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the images are loaded. Thus, it is possible that an image would be required for display before it is done preloading. The callback_complete function will only execute after all the images are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / images . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of images' ); } function startExperiment (){ jsPsych . run ( exp ); } preloadVideo \u00b6 jsPsych . pluginAPI . preloadVideo ( video , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description video array An array of video paths to load. The array can be nested (e.g., if videos are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the videos have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload video files. It is used by the preload plugin, and could be called directly to preload video files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the videos are loaded. Thus, it is possible that a video would be requested before it is done preloading. The callback_complete function will only execute after all the videos are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / videos . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of videos' ); } function startExperiment (){ jsPsych . run ( exp ); } Simulation \u00b6 clickTarget \u00b6 jsPsych . pluginAPI . clickTarget ( target , delay ) Parameters \u00b6 Parameter Type Description target Element The DOM element to simulate clicking on. delay number Time to wait in milliseconds. The click will be executed after the delay. Return value \u00b6 None Description \u00b6 Simulates clicking on a DOM element by dispatching three MouseEvents on the target : 'mousedown' , then 'mouseup' , then 'click' . If delay is positive, then the events are scheduled to execute after the delay via setTimeout . Example \u00b6 const target = document . querySelector ( '.jspsych-btn' ); jsPsych . pluginAPI . clickTarget ( target , 500 ); ensureSimulationDataConsistency \u00b6 jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data ) Parameters \u00b6 Parameter Type Description trial object Parameters for the trial, e.g., those passed to the plugin's trial() method. data object An object containing data for the trial. Return value \u00b6 None. The data object is modified in place by this method. Description \u00b6 Performs some basic consistency checks on the data based on the parameters specified in trial . For example, if trial.choices is \"NO_KEYS\" but data.response is a key string then data.response and data.rt are set to null . Example \u00b6 jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data ); fillTextInput \u00b6 jsPsych . pluginAPI . fillTextInput ( target , text , delay ) Parameters \u00b6 Parameter Type Description target HTMLInputElement The input element to fill in with text. text string The text to input. delay number Time to wait in milliseconds. The text will be inserted after the delay. Return value \u00b6 None Description \u00b6 Sets the value of the target HTMLInputElement to equal text . Example \u00b6 const target = document . querySelector ( 'input[type=\"text\"]' ); jsPsych . pluginAPI . fillTextInput ( target , \"hello!\" , 500 ); getValidKey \u00b6 jsPsych . pluginAPI . getValidKey ( choices ) Parameters \u00b6 Parameter Type Description choices \"NO_KEYS\" or \"ALL_KEYS\" or array of strings Representation of the valid keys allowed for a keyboard response used by the getKeyboardResponse method. Return value \u00b6 A valid key given the choices parameter, chosen at random from the possible keys. Description \u00b6 Picks a random key given a set of options. Currently it only picks letters and numbers when choices is \"ALL_KEYS\" . Example \u00b6 const random_key = jsPsych . pluginAPI . getValidKey ( trial . choices ); keyDown \u00b6 jsPsych . pluginAPI . keyDown ( key ) Parameters \u00b6 Parameter Type Description key string The .key property of the corresponding key on the keyboard. Return value \u00b6 None. Description \u00b6 Dispatches a 'keydown' event for the specified key . Example \u00b6 jsPsych . pluginAPI . keyDown ( 'a' ); keyUp \u00b6 jsPsych . pluginAPI . keyUp ( key ) Parameters \u00b6 Parameter Type Description key string The .key property of the corresponding key on the keyboard. Return value \u00b6 None. Description \u00b6 Dispatches a 'keyup' event for the specified key . Example \u00b6 jsPsych . pluginAPI . keyUp ( 'a' ); mergeSimulationData \u00b6 jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ) Parameters \u00b6 Parameter Type Description default_data object An object containing data values for the simulated trial. simulation_options object The simulation_options specified for the trial. Return value \u00b6 An object of data. Description \u00b6 This method merges the default_data with any data specified in simulation_options.data , giving priority to values specified in simulation_options.data . It returns the merged data. Example \u00b6 const default_data = { rt : 500 , response : 'a' } const simulation_options = { data : { rt : 200 } } const data = jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ); data . rt === 200 ; // true Timeouts \u00b6 clearAllTimeouts \u00b6 jsPsych . pluginAPI . clearAllTimeouts () Parameters \u00b6 None. Return value \u00b6 Returns nothing. Description \u00b6 Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout(). setTimeout \u00b6 jsPsych . pluginAPI . setTimeout ( callback , delay ) Parameters \u00b6 Parameter Type Description callback function A function to execute after waiting for delay. delay integer Time to wait in milliseconds. Return value \u00b6 Returns the ID of the setTimeout handle. Description \u00b6 This is simply a call to the standard setTimeout function in JavaScript with the added benefit of registering the setTimeout call in a central list. This is useful for scenarios where some other event (the trial ending, aborting the experiment) should stop the execution of queued timeouts. Example \u00b6 // print the time console . log ( Date . now ()) // print the time 1s later jsPsych . pluginAPI . setTimeout ( function (){ console . log ( Date . now ()) }, 1000 );","title":"jsPsych.pluginAPI"},{"location":"reference/jspsych-pluginAPI/#jspsychpluginapi","text":"The pluginAPI module contains functions that are useful when developing plugins. All of the functions are accessible through the pluginAPI object. In this documentation we've divided them up based on different kinds of functionality.","title":"jsPsych.pluginAPI"},{"location":"reference/jspsych-pluginAPI/#keyboard-input","text":"","title":"Keyboard Input"},{"location":"reference/jspsych-pluginAPI/#cancelallkeyboardresponses","text":"jsPsych . pluginAPI . cancelAllKeyboardResponses ()","title":"cancelAllKeyboardResponses"},{"location":"reference/jspsych-pluginAPI/#parameters","text":"None.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description","text":"Cancels all currently active keyboard listeners created by jsPsych.pluginAPI.getKeyboardResponse .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example","text":"jsPsych . pluginAPI . cancelAllKeyboardResponses ();","title":"Example"},{"location":"reference/jspsych-pluginAPI/#cancelkeyboardresponse","text":"jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id )","title":"cancelKeyboardResponse"},{"location":"reference/jspsych-pluginAPI/#parameters_1","text":"Parameter Type Description listener_id object The listener_id object generated by the call to jsPsych.pluginAPI.getKeyboardResponse .","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_1","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_1","text":"Cancels a specific keyboard listener created by jsPsych.pluginAPI.getKeyboardResponse .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_1","text":"// create a persistent keyboard listener var listener_id = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : [ 'p' , 'q' ], rt_method : 'performance' , persist : true , allow_held_key : false }); // cancel keyboard listener jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#comparekeys","text":"jsPsych . pluginAPI . compareKeys ( key1 , key2 )","title":"compareKeys"},{"location":"reference/jspsych-pluginAPI/#parameters_2","text":"Parameter Type Description key1 string or numeric The representation of a key, either string or keycode key2 string or numeric The representation of a key, either string or keycode","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_2","text":"Returns true if keycodes or strings refer to the same key, regardless of type. Returns false if the keycodes or strings do not match.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_2","text":"Compares two keys to see if they are the same, ignoring differences in representational type, and using the appropriate case sensitivity based on the experiment's settings. If case_sensitive_responses is set to false in initJsPsych (the default), then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will match, and this function will return true . If case_sensitive_responses is set to true in initJsPsych , then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will not match, and this function will return false . We recommend using this function to compare keys in all plugin and experiment code, rather than using something like if (response == 'j')... . This is because the response key returned by the jsPsych.pluginAPI.getKeyboardResponse function will be converted to lowercase when case_sensitive_responses is false , and it will match the exact key press representation when case_sensitive_responses is true . Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting, and that you do not need to remember to check key responses against different case versions of the comparison key (e.g. if (response == 'ArrowLeft' || response == 'arrowleft')... ).","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-examples","text":"jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns true when case_sensitive_responses is false in initJsPsych jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns false when case_sensitive_responses is true in initJsPsych // also works with numeric key codes (but note that numeric keyCode values are now deprecated) jsPsych . pluginAPI . compareKeys ( 'a' , 65 ); // returns true jsPsych . pluginAPI . compareKeys ( 'space' , 31 ); // returns false","title":"Basic examples"},{"location":"reference/jspsych-pluginAPI/#comparing-a-key-response-and-key-parameter-value-in-plugins","text":"// this is the callback_function passed to jsPsych.pluginAPI.getKeyboardResponse var after_response = function ( info ) { // score the response by comparing the key that was pressed against the trial's key_answer parameter var correct = jsPsych . pluginAPI . compareKeys ( trial . key_answer , info . key ); //... }","title":"Comparing a key response and key parameter value in plugins"},{"location":"reference/jspsych-pluginAPI/#scoring-a-key-response-in-experiment-code","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], prompt : 'Press f for left. Press j for right.' , on_finish : function ( data ){ // score the response by comparing the key that was pressed (data.response) against the // correct response for this trial ('f'), and store reponse accuracy in the trial data if ( jsPsych . pluginAPI . compareKeys ( data . response , 'f' )){ data . correct = true ; } else { data . correct = false ; } } }","title":"Scoring a key response in experiment code"},{"location":"reference/jspsych-pluginAPI/#getkeyboardresponse","text":"jsPsych . pluginAPI . getKeyboardResponse ( parameters )","title":"getKeyboardResponse"},{"location":"reference/jspsych-pluginAPI/#parameters_3","text":"The method accepts an object of parameter values (see example below). The valid keys for this object are listed in the table below. Parameter Type Description callback_function function The function to execute whenever a valid keyboard response is generated. valid_responses array An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable. rt_method string Indicates which method of recording time to use. The 'performance' method uses calls to performance.now() , which is the standard way of measuring timing in jsPsych. It is supported by up-to-date versions of all the major browsers . The audio method is used in conjuction with an audio_context (set as an additional parameter). This uses the clock time of the audio_context when audio stimuli are being played. audio_context AudioContext object The AudioContext of the audio file that is being played. audio_context_start_time numeric The scheduled time of the sound file in the AudioContext. This will be used as the start time. allow_held_key boolean If true , then responses will be registered from keys that are being held down. If false , then a held key can only register a response the first time that getKeyboardResponse is called for that key. For example, if a participant holds down the A key before the experiment starts, then the first time getKeyboardResponse is called, the A will register as a key press. However, any future calls to getKeyboardResponse will not register the A until the participant releases the key and presses it again. persist boolean If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by jsPsych.pluginAPI.cancelKeyboardResponse or jsPsych.pluginAPI.cancelAllKeyboardResponses .","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_3","text":"Return an object that uniquely identifies the keyboard listener. This object can be passed to jsPsych.pluginAPI.cancelKeyboardResponse to cancel the keyboard listener.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_3","text":"Gets a keyboard response from the participant, recording the response time from when the function is first called until a valid response is generated. The keyboard event listener will be bound to the display_element declared in initJsPsych() (or the <body> element if no display_element is specified). This allows jsPsych experiments to be embedded in websites with other content without disrupting the functionality of other UI elements. A valid response triggers the callback_function specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties key and rt . key contains the string representation of the response key, and rt contains the response time. This function uses the .key value of the keyboard event, which is case sensitive . When case_sensitive_responses is false in initJsPsych (the default), this function will convert both the valid_responses strings and the response key to lowercase before comparing them, and it will pass the lowercase version of the response key to the callback_function . For example, if valid_responses is ['a'] , then both 'A' and 'a' will be considered valid key presses, and 'a' will be returned as the response key. When case_sensitive_responses is true in initJsPsych , this function will not convert the case when comparing the valid_responses and response key, and it will not convert the case of the response key that is passed to the callback_function . For example, if valid_responses is ['a'] , then 'a' will be the only valid key press, and 'A' (i.e. 'a' with CapsLock on or Shift held down) will not be accepted. Also, if valid_responses includes multiple letter case options (e.g. \"ALL_KEYS\" ), then you may need to check the response key against both letter cases when scoring etc., e.g. if (response == 'ArrowLeft' || response =='arrowleft') ... .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#get-a-single-response-from-any-key","text":"var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); } jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : false });","title":"Get a single response from any key"},{"location":"reference/jspsych-pluginAPI/#get-a-responses-from-a-key-until-the-letter-q-is-pressed","text":"var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); if ( jsPsych . pluginAPI . compareKeys ( info . key , 'q' )){ / jsPsych . pluginAPI . cancelKeyboardResponse ( listener ); } } var listener = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : true });","title":"Get a responses from a key until the letter q is pressed"},{"location":"reference/jspsych-pluginAPI/#media","text":"","title":"Media"},{"location":"reference/jspsych-pluginAPI/#getaudiobuffer","text":"jsPsych . pluginAPI . getAudioBuffer ( filepath )","title":"getAudioBuffer"},{"location":"reference/jspsych-pluginAPI/#parameters_4","text":"Parameter Type Description filepath string The path to the audio file that was preloaded.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_4","text":"Returns a Promise that resolves when the audio file loads. Success handler's parameter will be the audio buffer. If the experiment is running using the WebAudio API it will be an AudioBuffer object. Otherwise, it will be an HTML5 Audio object. The failure handler's parameter is the error generated by preloadAudio .","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_4","text":"Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. It is strongly recommended that you preload audio files before calling this method. This method will load the files if they are not preloaded, but this may result in delays during the experiment as audio is downloaded.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_2","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#html-5-audio","text":"jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( audio ){ audio . play (); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) })","title":"HTML 5 Audio"},{"location":"reference/jspsych-pluginAPI/#webaudio-api","text":"var context = jsPsych . pluginAPI . audioContext (); jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( buffer ){ audio = context . createBufferSource (); audio . buffer = buffer ; audio . connect ( context . destination ); audio . start ( context . currentTime ); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) See the audio-keyboard-response plugin for an example in a fuller context.","title":"WebAudio API"},{"location":"reference/jspsych-pluginAPI/#getautopreloadlist","text":"jsPsych . pluginAPI . getAutoPreloadList ( timeline )","title":"getAutoPreloadList"},{"location":"reference/jspsych-pluginAPI/#parameters_5","text":"Parameter Type Description timeline array An array containing the trial object(s) from which a list of media files should be automatically generated. This array can contain the entire experiment timeline, or any individual parts of a larger timeline, such as specific timeline nodes and trial objects.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_5","text":"An object with properties for each media type: images , audio , and video . Each property contains an array of the unique files of that media type that were automatically extracted from the timeline. If no files are found in the timeline for a particular media type, then the array will be empty for that type.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_5","text":"This method is used to automatically generate lists of unique image, audio, and video files from a timeline. It is used by the preload plugin to generate a list of to-be-preloaded files based on the trials passed to the trials parameter and/or the experiment timeline passed to jsPsych.run (when auto_preload is true). It can be used in custom plugins and experiment code to generate a list of audio/image/video files, based on a timeline. This function will only return files from plugin parameters that are marked as parameter type AUDIO / IMAGE / VIDEO , and only when the preload flag of the corresponding parameter definition has not been set to false , and the trial's parameter value is not a function. When a file path is returned to the trial parameter from a function (including the jsPsych.timelineVariable function), or when the file path is embedded in an HTML string, that file will not be detected by the getAutoPreloadList method. In these cases, the file should be preloaded manually. See Media Preloading for more information.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_2","text":"var audio_trial = { type : jsPsychAudioKeyboardResponse stimulus : 'file.mp3' } var image_trial = { type : jsPsychImageKeyboardResponse stimulus : 'file.png' } var video_trial = { type : jsPsychVideoKeyboardResponse stimulus : 'file.mp4' } var timeline = [ audio_trial , image_trial , video_trial ]; jsPsych . pluginAPI . getAutoPreloadList ( timeline );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#getmicrophonerecorder","text":"jsPsych . pluginAPI . getMicrophoneRecorder ()","title":"getMicrophoneRecorder"},{"location":"reference/jspsych-pluginAPI/#parameters_6","text":"None","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_6","text":"A MediaRecorder object connected to the MediaStream for the active microphone.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_6","text":"Provides access to the MediaRecorder created by initializeMicrophoneRecorder() . If no microphone recorder exists, it returns null .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_3","text":"const recorder = jsPsych . pluginAPI . getMicrophoneRecorder ();","title":"Example"},{"location":"reference/jspsych-pluginAPI/#initializemicrophonerecorder","text":"jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream )","title":"initializeMicrophoneRecorder"},{"location":"reference/jspsych-pluginAPI/#parameters_7","text":"Parameter Type Description stream MediaStream The MediaStream object from an active microphone device.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_7","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_7","text":"Generates a MediaRecorder object from provided MediaStream and stores this for access via getMicrophoneRecorder() .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_4","text":"const stream = await navigator . mediaDevices . getUserMedia ({ audio : { deviceId : mic_id } }); jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#preloadaudio","text":"jsPsych . pluginAPI . preloadAudio ( files , callback_complete , callback_load , callback_error )","title":"preloadAudio"},{"location":"reference/jspsych-pluginAPI/#parameters_8","text":"Parameter Type Description files array An array of audio file paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the files have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_8","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_8","text":"This function is used to preload audio files. It is used by the preload plugin, and could be called directly to preload audio files in custom plugins or experiment. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the files are loaded. Thus, it is possible that an audio file would be required for playing before it is done preloading. The callback_complete function will only execute after all the audio files are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_3","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use","text":"var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading","text":"var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / sounds . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of audio files' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#preloadimages","text":"jsPsych . pluginAPI . preloadImages ( images , callback_complete , callback_load , callback_error )","title":"preloadImages"},{"location":"reference/jspsych-pluginAPI/#parameters_9","text":"Parameter Type Description images array An array of image paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the images have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_9","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_9","text":"This function is used to preload image files. It is used by the preload plugin, and could be called directly to preload image files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the images are loaded. Thus, it is possible that an image would be required for display before it is done preloading. The callback_complete function will only execute after all the images are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_4","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use_1","text":"var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading_1","text":"var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / images . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of images' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#preloadvideo","text":"jsPsych . pluginAPI . preloadVideo ( video , callback_complete , callback_load , callback_error )","title":"preloadVideo"},{"location":"reference/jspsych-pluginAPI/#parameters_10","text":"Parameter Type Description video array An array of video paths to load. The array can be nested (e.g., if videos are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the videos have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_10","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_10","text":"This function is used to preload video files. It is used by the preload plugin, and could be called directly to preload video files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the videos are loaded. Thus, it is possible that a video would be requested before it is done preloading. The callback_complete function will only execute after all the videos are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_5","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use_2","text":"var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading_2","text":"var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / videos . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of videos' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#simulation","text":"","title":"Simulation"},{"location":"reference/jspsych-pluginAPI/#clicktarget","text":"jsPsych . pluginAPI . clickTarget ( target , delay )","title":"clickTarget"},{"location":"reference/jspsych-pluginAPI/#parameters_11","text":"Parameter Type Description target Element The DOM element to simulate clicking on. delay number Time to wait in milliseconds. The click will be executed after the delay.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_11","text":"None","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_11","text":"Simulates clicking on a DOM element by dispatching three MouseEvents on the target : 'mousedown' , then 'mouseup' , then 'click' . If delay is positive, then the events are scheduled to execute after the delay via setTimeout .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_5","text":"const target = document . querySelector ( '.jspsych-btn' ); jsPsych . pluginAPI . clickTarget ( target , 500 );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#ensuresimulationdataconsistency","text":"jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data )","title":"ensureSimulationDataConsistency"},{"location":"reference/jspsych-pluginAPI/#parameters_12","text":"Parameter Type Description trial object Parameters for the trial, e.g., those passed to the plugin's trial() method. data object An object containing data for the trial.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_12","text":"None. The data object is modified in place by this method.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_12","text":"Performs some basic consistency checks on the data based on the parameters specified in trial . For example, if trial.choices is \"NO_KEYS\" but data.response is a key string then data.response and data.rt are set to null .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_6","text":"jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#filltextinput","text":"jsPsych . pluginAPI . fillTextInput ( target , text , delay )","title":"fillTextInput"},{"location":"reference/jspsych-pluginAPI/#parameters_13","text":"Parameter Type Description target HTMLInputElement The input element to fill in with text. text string The text to input. delay number Time to wait in milliseconds. The text will be inserted after the delay.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_13","text":"None","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_13","text":"Sets the value of the target HTMLInputElement to equal text .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_7","text":"const target = document . querySelector ( 'input[type=\"text\"]' ); jsPsych . pluginAPI . fillTextInput ( target , \"hello!\" , 500 );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#getvalidkey","text":"jsPsych . pluginAPI . getValidKey ( choices )","title":"getValidKey"},{"location":"reference/jspsych-pluginAPI/#parameters_14","text":"Parameter Type Description choices \"NO_KEYS\" or \"ALL_KEYS\" or array of strings Representation of the valid keys allowed for a keyboard response used by the getKeyboardResponse method.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_14","text":"A valid key given the choices parameter, chosen at random from the possible keys.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_14","text":"Picks a random key given a set of options. Currently it only picks letters and numbers when choices is \"ALL_KEYS\" .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_8","text":"const random_key = jsPsych . pluginAPI . getValidKey ( trial . choices );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#keydown","text":"jsPsych . pluginAPI . keyDown ( key )","title":"keyDown"},{"location":"reference/jspsych-pluginAPI/#parameters_15","text":"Parameter Type Description key string The .key property of the corresponding key on the keyboard.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_15","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_15","text":"Dispatches a 'keydown' event for the specified key .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_9","text":"jsPsych . pluginAPI . keyDown ( 'a' );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#keyup","text":"jsPsych . pluginAPI . keyUp ( key )","title":"keyUp"},{"location":"reference/jspsych-pluginAPI/#parameters_16","text":"Parameter Type Description key string The .key property of the corresponding key on the keyboard.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_16","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_16","text":"Dispatches a 'keyup' event for the specified key .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_10","text":"jsPsych . pluginAPI . keyUp ( 'a' );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#mergesimulationdata","text":"jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options )","title":"mergeSimulationData"},{"location":"reference/jspsych-pluginAPI/#parameters_17","text":"Parameter Type Description default_data object An object containing data values for the simulated trial. simulation_options object The simulation_options specified for the trial.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_17","text":"An object of data.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_17","text":"This method merges the default_data with any data specified in simulation_options.data , giving priority to values specified in simulation_options.data . It returns the merged data.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_11","text":"const default_data = { rt : 500 , response : 'a' } const simulation_options = { data : { rt : 200 } } const data = jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ); data . rt === 200 ; // true","title":"Example"},{"location":"reference/jspsych-pluginAPI/#timeouts","text":"","title":"Timeouts"},{"location":"reference/jspsych-pluginAPI/#clearalltimeouts","text":"jsPsych . pluginAPI . clearAllTimeouts ()","title":"clearAllTimeouts"},{"location":"reference/jspsych-pluginAPI/#parameters_18","text":"None.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_18","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_18","text":"Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout().","title":"Description"},{"location":"reference/jspsych-pluginAPI/#settimeout","text":"jsPsych . pluginAPI . setTimeout ( callback , delay )","title":"setTimeout"},{"location":"reference/jspsych-pluginAPI/#parameters_19","text":"Parameter Type Description callback function A function to execute after waiting for delay. delay integer Time to wait in milliseconds.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_19","text":"Returns the ID of the setTimeout handle.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_19","text":"This is simply a call to the standard setTimeout function in JavaScript with the added benefit of registering the setTimeout call in a central list. This is useful for scenarios where some other event (the trial ending, aborting the experiment) should stop the execution of queued timeouts.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_12","text":"// print the time console . log ( Date . now ()) // print the time 1s later jsPsych . pluginAPI . setTimeout ( function (){ console . log ( Date . now ()) }, 1000 );","title":"Example"},{"location":"reference/jspsych-randomization/","text":"jsPsych.randomization \u00b6 The jsPsych.randomization module contains methods that are useful for generating random lists of trial variables. jsPsych.randomization.factorial \u00b6 jsPsych . randomization . factorial ( factors , repetitions , unpack ) Parameters \u00b6 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 \u00b6 The return value depends on the unpack parameter. See description of the parameter above, and examples below. Description \u00b6 This method takes a list of factors and their levels, and creates a full factorial design by creating each unique combination of the factors. The returned set of combinations is in a random order. Examples \u00b6 Create full factorial design \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 ); /* output: full_design = [ {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, ] */ Create full factorial design with repeats \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 2 ); /* output: full_design = [ {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, ] */ Create full factorial design, unpacked \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 , true ); /* output: full_design = { stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'], ms_delay: [200, 100, 200, 100] ] */ jsPsych.randomization.randomID \u00b6 jsPsych . randomization . randomID ( length ) Parameters \u00b6 Parameter Type Description length integer The length of the randomly generated ID Return value \u00b6 Returns a string of length length where each character is randomly selected from the numbers 0-9 and all lowercase English letters a-z. Description \u00b6 Generates a random string that is likely to be unique. If length is undefined, then the string length is 32. Example \u00b6 console . log ( jsPsych . randomization . randomID ()); // outputs: \"t7dwz0e713pc8juuaayyfvpkdd9un239\" console . log ( jsPsych . randomization . randomID ( 8 )); // outputs: \"3xtpcbck\" jsPsych.randomization.randomInt \u00b6 jsPsych . randomization . randomInt ( lower , upper ) Parameters \u00b6 Parameter Type Description lower integer The smallest value it is possible to generate upper integer The largest value it is possible to generate Return value \u00b6 An integer Description \u00b6 Generates a random integer from lower to upper Example \u00b6 console . log ( jsPsych . randomization . randomInt ( 2 , 4 )); // outputs: 2 or 3 or 4. jsPsych.randomization.repeat \u00b6 jsPsych . randomization . repeat ( array , repetitions , unpack ) Parameters \u00b6 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 \u00b6 The return value depends on the unpack parameter. See description of the parameter above, and examples below. Description \u00b6 This method takes an array of values and generates a new random order of the array, with the option of repeating each element of the array a specified number of times. If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block. Examples \u00b6 Shuffle an array, no repeats \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 1 ); // output: shuffledArray = [3,2,4,1,5] Shuffle an array with repeats \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [1,3,4,2,2,4,5,1,5,3] Shuffle an array of objects \u00b6 var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [ trial1, trial3, trial3, trial2, trial1, trial2 ] Shuffle an array of objects, with unpack \u00b6 var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; 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: ['p', 'p', 'q', 'p', 'q', 'p'], person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred'] } */ jsPsych.randomization.sampleBernoulli \u00b6 jsPsych . randomization . sampleBernoulli ( p ) Parameters \u00b6 Parameter Type Description p number Probability of sampling 1 Return value \u00b6 Returns 0 with probability 1-p and 1 with probability p . Description \u00b6 Generates a random sample from a Bernoulli distribution. Examples \u00b6 Sample a value \u00b6 if ( jsPsych . randomization . sampleBernoulli ( 0.8 )){ // this happens 80% of the time } else { // this happens 20% of the time } jsPsych.randomization.sampleExGaussian \u00b6 jsPsych . randomization . sampleExGaussian ( mean , standard_deviation , rate , positive = false ) Parameters \u00b6 Parameter Type Description mean number Mean of the normal distribution component of the exGaussian standard_deviation number Standard deviation of the normal distribution component of the exGaussian rate number Rate of the exponential distribution component of the exGaussian positive bool If true sample will be constrained to > 0. Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from an exponentially modified Gaussian distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleExGaussian ( 500 , 100 , 0.01 ); jsPsych.randomization.sampleExponential \u00b6 jsPsych . randomization . sampleExponential ( rate ) Parameters \u00b6 Parameter Type Description rate number Rate of the exponential distribution Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from an exponential distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleExponential ( 0.01 ); jsPsych.randomization.sampleNormal \u00b6 jsPsych . randomization . sampleNormal ( mean , standard_deviation ) Parameters \u00b6 Parameter Type Description mean number Mean of the normal distribution standard_deviation number Standard deviation of the normal distribution Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from a normal distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleNormal ( 500 , 250 ); jsPsych.randomization.sampleWithReplacement \u00b6 jsPsych . randomization . sampleWithReplacement ( array , sampleSize , weights ) Parameters \u00b6 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 \u00b6 An array containing the sample. Description \u00b6 This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the weights . Examples \u00b6 Sample with equal probability \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 ); // output: sample = [3, 1, 2, 2, 5, 1, 4, 3, 1, 5]; Sample with unequal probability \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 , [ 6 , 1 , 1 , 1 , 1 ]); // output: sample = [3, 4, 5, 1, 2, 1, 3, 1, 1, 1]; jsPsych.randomization.sampleWithoutReplacement \u00b6 jsPsych . randomization . sampleWithoutReplacement ( array , sampleSize ) Parameters \u00b6 Parameter Type Description array array The array of values to sample from sampleSize numeric The number of samples to draw Return value \u00b6 An array containing the sample. Description \u00b6 This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array. Examples \u00b6 Sample without replacement \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithoutReplacement ( myArray , 2 ); // output: sample = [3,2]; jsPsych.randomization.setSeed \u00b6 jsPsych . randomization . setSeed ( seed ) Parameters \u00b6 Parameter Type Description seed string A seed for the random number generator Return value \u00b6 Returns the seed value. Description \u00b6 This function will override the behavior of Math.random() to produce a seedable pseudo random number generator. It uses the seedrandom package . Note that calling setSeed() will change how Math.random() behaves for the entire document. If you have non-jsPsych components on the page that use Math.random() they will be affected. Using setSeed() without passing in a seed will generate a random 32-bit seed. The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed. Examples \u00b6 Use a random 32-bit seed and save to data \u00b6 const seed = jsPsych . randomization . setSeed (); jsPsych . data . addProperties ({ rng_seed : seed }); Use your own seed \u00b6 jsPsych . randomization . setSeed ( \"jspsych\" ); jsPsych.randomization.shuffle \u00b6 jsPsych . randomization . shuffle ( array ) Parameters \u00b6 Parameter Type Description array array The array of values to shuffle Return value \u00b6 Returns an array with the same elements as the input array in a random order. Description \u00b6 A simple method for shuffling the order of an array. Examples \u00b6 Shuffle an array \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffle ( myArray ); // output: shuffledArray = [3,2,4,1,5] jsPsych.randomization.shuffleNoRepeats \u00b6 jsPsych . randomization . shuffleNoRepeats ( array , equalityTest ) Parameters \u00b6 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 \u00b6 Returns an array with the same elements as the input array in a random order, with no repeating neighbors. Description \u00b6 Shuffle an array, ensuring that neighboring elements in the array are different. Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang. Examples \u00b6 Basic example \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffleNoRepeats ( myArray ); // output: shuffledArray = [2, 3, 5, 1, 2, 4, 1, 5, 4, 1, 3, 5, 4, 3, 2] Custom equalityTest \u00b6 var myObjects = [ { color : \"blue\" }, { color : \"red\" }, { color : \"yellow\" }, { color : \"orange\" } ]; var repeatedSet = jsPsych . randomization . repeat ( myObjects , 3 ); var shuffled = jsPsych . randomization . shuffleNoRepeats ( repeatedSet , function ( a , b ) { return a . color === b . color }); // console.log(JSON.stringify(shuffled)) // \"[{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"blue\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"blue\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"blue\"}]\"","title":"jsPsych.randomization"},{"location":"reference/jspsych-randomization/#jspsychrandomization","text":"The jsPsych.randomization module contains methods that are useful for generating random lists of trial variables.","title":"jsPsych.randomization"},{"location":"reference/jspsych-randomization/#jspsychrandomizationfactorial","text":"jsPsych . randomization . factorial ( factors , repetitions , unpack )","title":"jsPsych.randomization.factorial"},{"location":"reference/jspsych-randomization/#parameters","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value","text":"The return value depends on the unpack parameter. See description of the parameter above, and examples below.","title":"Return value"},{"location":"reference/jspsych-randomization/#description","text":"This method takes a list of factors and their levels, and creates a full factorial design by creating each unique combination of the factors. The returned set of combinations is in a random order.","title":"Description"},{"location":"reference/jspsych-randomization/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#create-full-factorial-design","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 ); /* output: full_design = [ {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, ] */","title":"Create full factorial design"},{"location":"reference/jspsych-randomization/#create-full-factorial-design-with-repeats","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 2 ); /* output: full_design = [ {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, ] */","title":"Create full factorial design with repeats"},{"location":"reference/jspsych-randomization/#create-full-factorial-design-unpacked","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 , true ); /* output: full_design = { stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'], ms_delay: [200, 100, 200, 100] ] */","title":"Create full factorial design, unpacked"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrandomid","text":"jsPsych . randomization . randomID ( length )","title":"jsPsych.randomization.randomID"},{"location":"reference/jspsych-randomization/#parameters_1","text":"Parameter Type Description length integer The length of the randomly generated ID","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_1","text":"Returns a string of length length where each character is randomly selected from the numbers 0-9 and all lowercase English letters a-z.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_1","text":"Generates a random string that is likely to be unique. If length is undefined, then the string length is 32.","title":"Description"},{"location":"reference/jspsych-randomization/#example","text":"console . log ( jsPsych . randomization . randomID ()); // outputs: \"t7dwz0e713pc8juuaayyfvpkdd9un239\" console . log ( jsPsych . randomization . randomID ( 8 )); // outputs: \"3xtpcbck\"","title":"Example"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrandomint","text":"jsPsych . randomization . randomInt ( lower , upper )","title":"jsPsych.randomization.randomInt"},{"location":"reference/jspsych-randomization/#parameters_2","text":"Parameter Type Description lower integer The smallest value it is possible to generate upper integer The largest value it is possible to generate","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_2","text":"An integer","title":"Return value"},{"location":"reference/jspsych-randomization/#description_2","text":"Generates a random integer from lower to upper","title":"Description"},{"location":"reference/jspsych-randomization/#example_1","text":"console . log ( jsPsych . randomization . randomInt ( 2 , 4 )); // outputs: 2 or 3 or 4.","title":"Example"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrepeat","text":"jsPsych . randomization . repeat ( array , repetitions , unpack )","title":"jsPsych.randomization.repeat"},{"location":"reference/jspsych-randomization/#parameters_3","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_3","text":"The return value depends on the unpack parameter. See description of the parameter above, and examples below.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_3","text":"This method takes an array of values and generates a new random order of the array, with the option of repeating each element of the array a specified number of times. If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#shuffle-an-array-no-repeats","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 1 ); // output: shuffledArray = [3,2,4,1,5]","title":"Shuffle an array, no repeats"},{"location":"reference/jspsych-randomization/#shuffle-an-array-with-repeats","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [1,3,4,2,2,4,5,1,5,3]","title":"Shuffle an array with repeats"},{"location":"reference/jspsych-randomization/#shuffle-an-array-of-objects","text":"var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [ trial1, trial3, trial3, trial2, trial1, trial2 ]","title":"Shuffle an array of objects"},{"location":"reference/jspsych-randomization/#shuffle-an-array-of-objects-with-unpack","text":"var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; 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: ['p', 'p', 'q', 'p', 'q', 'p'], person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred'] } */","title":"Shuffle an array of objects, with unpack"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplebernoulli","text":"jsPsych . randomization . sampleBernoulli ( p )","title":"jsPsych.randomization.sampleBernoulli"},{"location":"reference/jspsych-randomization/#parameters_4","text":"Parameter Type Description p number Probability of sampling 1","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_4","text":"Returns 0 with probability 1-p and 1 with probability p .","title":"Return value"},{"location":"reference/jspsych-randomization/#description_4","text":"Generates a random sample from a Bernoulli distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_2","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value","text":"if ( jsPsych . randomization . sampleBernoulli ( 0.8 )){ // this happens 80% of the time } else { // this happens 20% of the time }","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsampleexgaussian","text":"jsPsych . randomization . sampleExGaussian ( mean , standard_deviation , rate , positive = false )","title":"jsPsych.randomization.sampleExGaussian"},{"location":"reference/jspsych-randomization/#parameters_5","text":"Parameter Type Description mean number Mean of the normal distribution component of the exGaussian standard_deviation number Standard deviation of the normal distribution component of the exGaussian rate number Rate of the exponential distribution component of the exGaussian positive bool If true sample will be constrained to > 0.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_5","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_5","text":"Generates a random sample from an exponentially modified Gaussian distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_3","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_1","text":"var rand_sample_exg = jsPsych . randomization . sampleExGaussian ( 500 , 100 , 0.01 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsampleexponential","text":"jsPsych . randomization . sampleExponential ( rate )","title":"jsPsych.randomization.sampleExponential"},{"location":"reference/jspsych-randomization/#parameters_6","text":"Parameter Type Description rate number Rate of the exponential distribution","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_6","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_6","text":"Generates a random sample from an exponential distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_4","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_2","text":"var rand_sample_exg = jsPsych . randomization . sampleExponential ( 0.01 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplenormal","text":"jsPsych . randomization . sampleNormal ( mean , standard_deviation )","title":"jsPsych.randomization.sampleNormal"},{"location":"reference/jspsych-randomization/#parameters_7","text":"Parameter Type Description mean number Mean of the normal distribution standard_deviation number Standard deviation of the normal distribution","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_7","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_7","text":"Generates a random sample from a normal distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_5","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_3","text":"var rand_sample_exg = jsPsych . randomization . sampleNormal ( 500 , 250 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplewithreplacement","text":"jsPsych . randomization . sampleWithReplacement ( array , sampleSize , weights )","title":"jsPsych.randomization.sampleWithReplacement"},{"location":"reference/jspsych-randomization/#parameters_8","text":"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 .","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_8","text":"An array containing the sample.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_8","text":"This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the weights .","title":"Description"},{"location":"reference/jspsych-randomization/#examples_6","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-with-equal-probability","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 ); // output: sample = [3, 1, 2, 2, 5, 1, 4, 3, 1, 5];","title":"Sample with equal probability"},{"location":"reference/jspsych-randomization/#sample-with-unequal-probability","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 , [ 6 , 1 , 1 , 1 , 1 ]); // output: sample = [3, 4, 5, 1, 2, 1, 3, 1, 1, 1];","title":"Sample with unequal probability"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplewithoutreplacement","text":"jsPsych . randomization . sampleWithoutReplacement ( array , sampleSize )","title":"jsPsych.randomization.sampleWithoutReplacement"},{"location":"reference/jspsych-randomization/#parameters_9","text":"Parameter Type Description array array The array of values to sample from sampleSize numeric The number of samples to draw","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_9","text":"An array containing the sample.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_9","text":"This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_7","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-without-replacement","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithoutReplacement ( myArray , 2 ); // output: sample = [3,2];","title":"Sample without replacement"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsetseed","text":"jsPsych . randomization . setSeed ( seed )","title":"jsPsych.randomization.setSeed"},{"location":"reference/jspsych-randomization/#parameters_10","text":"Parameter Type Description seed string A seed for the random number generator","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_10","text":"Returns the seed value.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_10","text":"This function will override the behavior of Math.random() to produce a seedable pseudo random number generator. It uses the seedrandom package . Note that calling setSeed() will change how Math.random() behaves for the entire document. If you have non-jsPsych components on the page that use Math.random() they will be affected. Using setSeed() without passing in a seed will generate a random 32-bit seed. The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_8","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#use-a-random-32-bit-seed-and-save-to-data","text":"const seed = jsPsych . randomization . setSeed (); jsPsych . data . addProperties ({ rng_seed : seed });","title":"Use a random 32-bit seed and save to data"},{"location":"reference/jspsych-randomization/#use-your-own-seed","text":"jsPsych . randomization . setSeed ( \"jspsych\" );","title":"Use your own seed"},{"location":"reference/jspsych-randomization/#jspsychrandomizationshuffle","text":"jsPsych . randomization . shuffle ( array )","title":"jsPsych.randomization.shuffle"},{"location":"reference/jspsych-randomization/#parameters_11","text":"Parameter Type Description array array The array of values to shuffle","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_11","text":"Returns an array with the same elements as the input array in a random order.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_11","text":"A simple method for shuffling the order of an array.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_9","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#shuffle-an-array","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffle ( myArray ); // output: shuffledArray = [3,2,4,1,5]","title":"Shuffle an array"},{"location":"reference/jspsych-randomization/#jspsychrandomizationshufflenorepeats","text":"jsPsych . randomization . shuffleNoRepeats ( array , equalityTest )","title":"jsPsych.randomization.shuffleNoRepeats"},{"location":"reference/jspsych-randomization/#parameters_12","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_12","text":"Returns an array with the same elements as the input array in a random order, with no repeating neighbors.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_12","text":"Shuffle an array, ensuring that neighboring elements in the array are different. Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_10","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#basic-example","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffleNoRepeats ( myArray ); // output: shuffledArray = [2, 3, 5, 1, 2, 4, 1, 5, 4, 1, 3, 5, 4, 3, 2]","title":"Basic example"},{"location":"reference/jspsych-randomization/#custom-equalitytest","text":"var myObjects = [ { color : \"blue\" }, { color : \"red\" }, { color : \"yellow\" }, { color : \"orange\" } ]; var repeatedSet = jsPsych . randomization . repeat ( myObjects , 3 ); var shuffled = jsPsych . randomization . shuffleNoRepeats ( repeatedSet , function ( a , b ) { return a . color === b . color }); // console.log(JSON.stringify(shuffled)) // \"[{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"blue\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"blue\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"blue\"}]\"","title":"Custom equalityTest"},{"location":"reference/jspsych-turk/","text":"jsPsych.turk \u00b6 The jsPsych.turk module contains functions for interacting with Mechanical Turk. jsPsych.turk.submitToTurk \u00b6 jsPsych . turk . submitToTurk ( data ) Parameters \u00b6 Parameter Type Description data object The data parameter is an object of key: value pairs. Any pairs in the data parameter will be saved by Mechanical Turk, and can be downloaded in a CSV file through the Mechanical Turk interface. Important : the data parameter must contain at least one key: value pair, even just a dummy value, or the HIT will not be submitted correctly. Return value \u00b6 Returns nothing. Description \u00b6 This method will submit a HIT to Mechanical Turk, causing the HIT to finish. This method will only work when called from within the mechanical turk website. If you are using an external HIT to send workers to your own server, this method will not work on an externally hosted page. It will work if your external content is loaded in the iframe on the Mechanical Turk website. Example \u00b6 < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > // this content must be loaded in the iframe on the mechanical turk website. // usually, this means that the content is part of your 'recruitment ad', the // page the workers can see when they are deciding whether or not to accept a HIT. // one option is to include a simple form on this page that workers submit, with a // special code that they get at the end of the experiment. function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > jsPsych.turk.turkInfo \u00b6 jsPsych . turk . turkInfo () Parameters \u00b6 None. Return value \u00b6 Returns an object with six properties: .assignmentId contains the assignment ID string of the HIT. .hitId contains the HIT ID. .workerId contains the worker ID of the worker completing the HIT. .turkSubmitTo contains the URL for submitting the HIT. This parameter is used in the jsPsych.turk.submitToTurk method, and is probably not useful outside of that context. .previewMode is a boolean value indicating whether or not the worker has accepted the HIT yet. If the page is viewed inside Mechancial Turk and the worker has not clicked 'Accept HIT' then this will be true. If the page is viewed outside Mechanical Turk or the worker has acccepted the HIT, then it will be false. .outsideTurk is a boolean value indicating if the page is being viewed within Mechanical Turk, or if it is being viewed from another source (e.g., someone directly going to the page URL instead of going through mturk). Description \u00b6 This method returns basic information about the current Mechanical Turk session, including the worker ID, assignment ID, and HIT ID. Example \u00b6 var turkInfo = jsPsych . turk . turkInfo (); alert ( 'Worker ID is: ' + turkInfo . workerId ); alert ( 'Assignment ID is: ' + turkInfo . assignmentId ); alert ( 'HIT ID is: ' + turkInfo . hitId ); // true if the page is viewed within Mechanical Turk, // but worker has not accepted the HIT yet. // false if the page is viewed outside Mechanical Turk, // OR the worker has accepted the HIT. alert ( 'Preview mode? ' + turkInfo . previewMode ); // true if the page is viewed outside mechanical turk, // false otherwise. alert ( 'Outside turk? ' + turkInfo . outsideTurk );","title":"jsPsych.turk"},{"location":"reference/jspsych-turk/#jspsychturk","text":"The jsPsych.turk module contains functions for interacting with Mechanical Turk.","title":"jsPsych.turk"},{"location":"reference/jspsych-turk/#jspsychturksubmittoturk","text":"jsPsych . turk . submitToTurk ( data )","title":"jsPsych.turk.submitToTurk"},{"location":"reference/jspsych-turk/#parameters","text":"Parameter Type Description data object The data parameter is an object of key: value pairs. Any pairs in the data parameter will be saved by Mechanical Turk, and can be downloaded in a CSV file through the Mechanical Turk interface. Important : the data parameter must contain at least one key: value pair, even just a dummy value, or the HIT will not be submitted correctly.","title":"Parameters"},{"location":"reference/jspsych-turk/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-turk/#description","text":"This method will submit a HIT to Mechanical Turk, causing the HIT to finish. This method will only work when called from within the mechanical turk website. If you are using an external HIT to send workers to your own server, this method will not work on an externally hosted page. It will work if your external content is loaded in the iframe on the Mechanical Turk website.","title":"Description"},{"location":"reference/jspsych-turk/#example","text":"< p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > // this content must be loaded in the iframe on the mechanical turk website. // usually, this means that the content is part of your 'recruitment ad', the // page the workers can see when they are deciding whether or not to accept a HIT. // one option is to include a simple form on this page that workers submit, with a // special code that they get at the end of the experiment. function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script >","title":"Example"},{"location":"reference/jspsych-turk/#jspsychturkturkinfo","text":"jsPsych . turk . turkInfo ()","title":"jsPsych.turk.turkInfo"},{"location":"reference/jspsych-turk/#parameters_1","text":"None.","title":"Parameters"},{"location":"reference/jspsych-turk/#return-value_1","text":"Returns an object with six properties: .assignmentId contains the assignment ID string of the HIT. .hitId contains the HIT ID. .workerId contains the worker ID of the worker completing the HIT. .turkSubmitTo contains the URL for submitting the HIT. This parameter is used in the jsPsych.turk.submitToTurk method, and is probably not useful outside of that context. .previewMode is a boolean value indicating whether or not the worker has accepted the HIT yet. If the page is viewed inside Mechancial Turk and the worker has not clicked 'Accept HIT' then this will be true. If the page is viewed outside Mechanical Turk or the worker has acccepted the HIT, then it will be false. .outsideTurk is a boolean value indicating if the page is being viewed within Mechanical Turk, or if it is being viewed from another source (e.g., someone directly going to the page URL instead of going through mturk).","title":"Return value"},{"location":"reference/jspsych-turk/#description_1","text":"This method returns basic information about the current Mechanical Turk session, including the worker ID, assignment ID, and HIT ID.","title":"Description"},{"location":"reference/jspsych-turk/#example_1","text":"var turkInfo = jsPsych . turk . turkInfo (); alert ( 'Worker ID is: ' + turkInfo . workerId ); alert ( 'Assignment ID is: ' + turkInfo . assignmentId ); alert ( 'HIT ID is: ' + turkInfo . hitId ); // true if the page is viewed within Mechanical Turk, // but worker has not accepted the HIT yet. // false if the page is viewed outside Mechanical Turk, // OR the worker has accepted the HIT. alert ( 'Preview mode? ' + turkInfo . previewMode ); // true if the page is viewed outside mechanical turk, // false otherwise. alert ( 'Outside turk? ' + turkInfo . outsideTurk );","title":"Example"},{"location":"reference/jspsych/","text":"jsPsych \u00b6 initJsPsych \u00b6 var jsPsych = initJsPsych ( settings ); Parameters \u00b6 Parameter Type Description settings object The settings object for initializing jsPsych. See table below. The settings object can contain several parameters. None of the parameters are required. Parameter Type Description 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 participant 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 participant can use to complete the experiment. See list of options below. This feature is deprecated as of v7.1 and will be removed in v8.0. The browser-check plugin is an improved way to handle exclusions. show_progress_bar boolean If true , then a progress bar is shown at the top of the page. Default is false . 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. 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. 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. case_sensitive_responses boolean If true , then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. \"A\" (uppercase) will not be recognized as a valid response if the trial only accepts \"a\" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both \"a\" and \"A\" responses will be valid when the trial's key choice parameter is \"a\". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is false . extensions array Array containing information about one or more jsPsych extensions that are used during the experiment. Each extension should be specified as an object with type (required), which is the name of the extension, and params (optional), which is an object containing any parameter-value pairs to be passed to the extension's initialize function. Default value is an empty array. 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 participant 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 \u00b6 Returns a jsPsych instance, which all jsPsych methods on this page are called on. Therefore it is not possible to call any of the jsPsych methods listed on this page until this initJsPsych function is called and a jsPsych instance is created. Description \u00b6 This function initializes jsPsych with the specified experiment settings. Example \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); }, show_progress_bar : true , default_iti : 500 }); For more examples, see the HTML files in the examples folder . jsPsych.addNodeToEndOfTimeline \u00b6 jsPsych . addNodeToEndOfTimeline ( node_parameters ) Parameters \u00b6 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. Return value \u00b6 None. Description \u00b6 Adds the timeline to the end of the experiment. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a new trial.' } var new_timeline = { timeline : [ trial ] } jsPsych . addNodeToEndOfTimeline ( new_timeline ) jsPsych.endCurrentTimeline \u00b6 jsPsych . endCurrentTimeline () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Ends the current timeline. If timelines are nested, then only the timeline that contains the current trial is ended. Example \u00b6 End timeline if a particular key is pressed \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); var images = [ \"img/1.gif\" , \"img/2.gif\" , \"img/3.gif\" , \"img/4.gif\" , \"img/5.gif\" , \"img/6.gif\" , \"img/7.gif\" , \"img/8.gif\" , \"img/9.gif\" , \"img/10.gif\" ]; var trials = []; for ( var i = 0 ; i < images . length ; i ++ ) { trials . push ({ stimulus : images [ i ] }); } var block = { type : jsPsychImageKeyboardResponse , choices : [ 'y' , 'n' ], prompt : '<p>Press \"y\" to Continue. Press \"n\" to end this node of the experiment.</p>' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'n' )) { jsPsych . endCurrentTimeline (); } }, timeline : trials } var after_block = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>The next node</p>' } jsPsych . run ([ block , after_block ]); jsPsych.endExperiment \u00b6 jsPsych . endExperiment ( end_message , data ) Parameters \u00b6 Parameter Type Description end_message string A message to display on the screen after the experiment is over. Can include HTML formatting. data object An optional object of key-value pairs to store as data in the final trial of the experiment. Return value \u00b6 None. Description \u00b6 Ends the experiment, skipping all remaining trials. If the on_finish event handler for jsPsych returns a Promise then the end_message will not be displayed until the promise is resolved. Example \u00b6 End the experiment if a particular response is given \u00b6 var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'image1.jpg' , choices : [ 'y' , 'n' ] prompt : '<p>Press \"y\" to Continue. Press \"n\" to end the experiment</p>' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"n\" )){ jsPsych . endExperiment ( 'The experiment was ended by pressing \"n\".' ); } } } jsPsych.finishTrial \u00b6 jsPsych . finishTrial ( data ) Parameters \u00b6 Parameter Type Description data object The data to store for the trial. Return value \u00b6 Returns nothing. Description \u00b6 This method tells jsPsych that the current trial is over. It is used in all of the plugins to end the current trial. When the trial ends a few things happen: The data is stored using jsPsych.data.write() The on_finish callback function is executed for the trial The on_trial_finish callback function is executed The progress bar is updated if it is being displayed The experiment ends if the trial is the last one (and the on_finish callback function is executed). The next trial, if one exists, is started. Example \u00b6 // this code would be in a plugin jsPsych . finishTrial ({ correct_response : true }); jsPsych.getAllTimelineVariables \u00b6 jsPsych . getAllTimelineVariables () Parameters \u00b6 None. Return value \u00b6 Returns an object with all available timeline variables at this moment in the experiment, represented as key: value pairs. Description \u00b6 This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating data, such as in the example below. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Just a demo' , on_finish : function ( data ){ // merge all timeline variables available at this trial into the data for this trial Object . assign ( data , jsPsych . getAllTimelineVariables ()) } } jsPsych.getCurrentTimelineNodeID \u00b6 jsPsych . getCurrentTimelineNodeID () Parameters \u00b6 None. Return value \u00b6 Returns the ID of the TimelineNode that is currently active. Description \u00b6 Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: \"0.0\" is the ID of the first top-level TimelineNode \"1.0\" is the ID of the second top-level TimelineNode \"2.0\" is the ID of the third top-level TimelineNode, and so on... If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: \"0.0\" is the ID of the first top-level TimelineNode during the first iteration \"0.1\" is the ID of the first top-level TimelineNode during the second iteration \"0.2\" is the ID of the first top-level TimelineNode during the third iteration, and so on... If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with \".\" : \"0.0-1.0\" is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. \"0.0-2.0\" is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... The rules about iterations apply throughout the hierarchical ID: \"0.2-1.3\" is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time. Example \u00b6 var id = jsPsych . getCurrentTimelineNodeID (); console . log ( 'The current TimelineNode ID is ' + id ); jsPsych.getCurrentTrial \u00b6 jsPsych . getCurrentTrial () Parameters \u00b6 None. Return value \u00b6 Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial. Description \u00b6 Get a description of the current trial Example \u00b6 var trial = jsPsych . getCurrentTrial (); console . log ( 'The current trial is using the ' + trial . type + ' plugin' ); jsPsych.getDisplayElement \u00b6 jsPsych . getDisplayElement () Parameters \u00b6 None. Return value \u00b6 Returns the HTML DOM element used for displaying the experiment. Description \u00b6 Get the DOM element that displays the experiment. Example \u00b6 var el = jsPsych . getDisplayElement (); // hide the jsPsych display el . style . visibility = 'hidden' ; \u00b6 jsPsych.getInitSettings \u00b6 jsPsych . getInitSettings () Parameters \u00b6 None Return value \u00b6 Returns the settings object used to initialize the experiment. Description \u00b6 Gets the object containing the settings for the current experiment. Example \u00b6 var settings = jsPsych . getInitSettings (); // check the experiment structure console . log ( JSON . stringify ( settings . timeline )); jsPsych.getProgress \u00b6 jsPsych . getProgress () Parameters \u00b6 None. Return value \u00b6 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. Description \u00b6 This method returns information about the length of the experiment and the participant's current location in the experiment timeline. Example \u00b6 var progress = jsPsych . getProgress (); alert ( 'You have completed approximately ' + progress . percent_complete + '% of the experiment' ); jsPsych.getProgressBarCompleted \u00b6 jsPsych . getProgressBarCompleted () Parameters \u00b6 None. Return value \u00b6 Returns a value between 0 and 1 representing how full the progress bar currently is. Description \u00b6 Used to get the current value of the progress bar. Works for automated and manual control. Example \u00b6 var progress_bar_amount = jsPsych . getProgressBarCompleted (); jsPsych.getStartTime \u00b6 jsPsych . getStartTime () Parameters \u00b6 None. Return value \u00b6 Returns a Date object indicating when the experiment began. Description \u00b6 Get the time that the experiment began. Example \u00b6 var start_time = jsPsych . getStartTime (); jsPsych.getTotalTime \u00b6 jsPsych . getTotalTime () Parameters \u00b6 None. Return value \u00b6 Returns a numeric value indicating the number of milliseconds since jsPsych.run was called. Description \u00b6 Gets the total time the participant has been in the experiment. Example \u00b6 var time = jsPsych . getTotalTime (); console . log ( time ); jsPsych.pauseExperiment \u00b6 jsPsych . pauseExperiment () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Pauses the experiment. The experiment will finish the current trial, but will not execute any additional trials until jsPsych.resumeExperiment() is called. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } } jsPsych.resumeExperiment \u00b6 jsPsych . resumeExperiment () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Resumes the experiment after a call to jsPsych.pauseExperiment() . If the post trial delay ( post_trial_gap ) has not yet been reached, then the experiment will not continue until the delay is finished. For example, if post_trial_gap was 10,000ms and jsPsych.resumeExperiment() was called 6,000ms after the previous trial finished, then the experiment would not continue for another 4,000ms. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } } jsPsych.run \u00b6 jsPsych . run ( timeline ) Parameters \u00b6 Parameter Type Description timeline array An array containing the objects that describe the experiment timeline. See Creating an Experiment: The Timeline . Return value \u00b6 None. Description \u00b6 Start the jsPsych experiment with the specified timeline. Example \u00b6 var timeline = [ trial1 , trial2 , trial3 ]; jsPsych . run ( timeline ); jsPsych.setProgressBar \u00b6 jsPsych . setProgressBar ( value ) Parameters \u00b6 Parameter Type Description value numeric Proprotion (between 0 and 1) to fill the progress bar. Return value \u00b6 None. Description \u00b6 Set the progress bar to a custom amount. Proportion must be between 0 and 1. Values larger than 1 are treated as 1. Example \u00b6 jsPsych . setProgressBar ( 0.85 ); jsPsych.timelineVariable \u00b6 jsPsych . timelineVariable ( variable , call_immediate ) Parameters \u00b6 Parameter Type Description variable string Name of the timeline variable call_immediate bool This parameter is optional and can usually be omitted. It determines the return value of jsPsych.timelineVariable . If true , the function returns the value of the current timeline variable. If false , the function returns a function that returns the value of the current timeline variable. When call_immediate is omitted, the appropriate option is determined automatically based on the context in which this function is called. When jsPsych.timelineVariable is used as a parameter value, call_immediate will be false . This allows it to be used as a dynamic trial parameter . When jsPsych.timelineVariable is used inside of a function, call_immediate will be true . It is possible to explicitly set this option to true to force the function to immediately return the current value of the timeline variable. Return value \u00b6 Either a function that returns the value of the timeline variable, or the value of the timeline variable, depending on the context in which it is used. See call_immediate description above. Description \u00b6 Timeline variables are a powerful technique for generating experiments with repetitive procedures but different parameter values. This function fetches the current value of a particular timeline variable. It must be used in conjunction with a timeline that has timeline variables. See the timeline variable section for details. Examples \u00b6 Standard use as a parameter for a trial \u00b6 var trial = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'image' ) } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Invoking immediately in a function \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Prior to jsPsych v6.3.0, the call_immediate parameter must be set to true when jsPsych.timelineVariable is called from within a function, such as a dynamic parameter : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' , true ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } jsPsych.version \u00b6 jsPsych . version () Parameters \u00b6 None. Return value \u00b6 Returns the version number as a string. Description \u00b6 Gets the version of jsPsych. Example \u00b6 var version = jsPsych . version (); console . log ( version );","title":"jsPsych"},{"location":"reference/jspsych/#jspsych","text":"","title":"jsPsych"},{"location":"reference/jspsych/#initjspsych","text":"var jsPsych = initJsPsych ( settings );","title":"initJsPsych"},{"location":"reference/jspsych/#parameters","text":"Parameter Type Description settings object The settings object for initializing jsPsych. See table below. The settings object can contain several parameters. None of the parameters are required. Parameter Type Description 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 participant 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 participant can use to complete the experiment. See list of options below. This feature is deprecated as of v7.1 and will be removed in v8.0. The browser-check plugin is an improved way to handle exclusions. show_progress_bar boolean If true , then a progress bar is shown at the top of the page. Default is false . 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. 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. 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. case_sensitive_responses boolean If true , then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. \"A\" (uppercase) will not be recognized as a valid response if the trial only accepts \"a\" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both \"a\" and \"A\" responses will be valid when the trial's key choice parameter is \"a\". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is false . extensions array Array containing information about one or more jsPsych extensions that are used during the experiment. Each extension should be specified as an object with type (required), which is the name of the extension, and params (optional), which is an object containing any parameter-value pairs to be passed to the extension's initialize function. Default value is an empty array. 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 participant 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).","title":"Parameters"},{"location":"reference/jspsych/#return-value","text":"Returns a jsPsych instance, which all jsPsych methods on this page are called on. Therefore it is not possible to call any of the jsPsych methods listed on this page until this initJsPsych function is called and a jsPsych instance is created.","title":"Return value"},{"location":"reference/jspsych/#description","text":"This function initializes jsPsych with the specified experiment settings.","title":"Description"},{"location":"reference/jspsych/#example","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); }, show_progress_bar : true , default_iti : 500 }); For more examples, see the HTML files in the examples folder .","title":"Example"},{"location":"reference/jspsych/#jspsychaddnodetoendoftimeline","text":"jsPsych . addNodeToEndOfTimeline ( node_parameters )","title":"jsPsych.addNodeToEndOfTimeline"},{"location":"reference/jspsych/#parameters_1","text":"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.","title":"Parameters"},{"location":"reference/jspsych/#return-value_1","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_1","text":"Adds the timeline to the end of the experiment.","title":"Description"},{"location":"reference/jspsych/#example_1","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a new trial.' } var new_timeline = { timeline : [ trial ] } jsPsych . addNodeToEndOfTimeline ( new_timeline )","title":"Example"},{"location":"reference/jspsych/#jspsychendcurrenttimeline","text":"jsPsych . endCurrentTimeline ()","title":"jsPsych.endCurrentTimeline"},{"location":"reference/jspsych/#parameters_2","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_2","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_2","text":"Ends the current timeline. If timelines are nested, then only the timeline that contains the current trial is ended.","title":"Description"},{"location":"reference/jspsych/#example_2","text":"","title":"Example"},{"location":"reference/jspsych/#end-timeline-if-a-particular-key-is-pressed","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); var images = [ \"img/1.gif\" , \"img/2.gif\" , \"img/3.gif\" , \"img/4.gif\" , \"img/5.gif\" , \"img/6.gif\" , \"img/7.gif\" , \"img/8.gif\" , \"img/9.gif\" , \"img/10.gif\" ]; var trials = []; for ( var i = 0 ; i < images . length ; i ++ ) { trials . push ({ stimulus : images [ i ] }); } var block = { type : jsPsychImageKeyboardResponse , choices : [ 'y' , 'n' ], prompt : '<p>Press \"y\" to Continue. Press \"n\" to end this node of the experiment.</p>' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'n' )) { jsPsych . endCurrentTimeline (); } }, timeline : trials } var after_block = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>The next node</p>' } jsPsych . run ([ block , after_block ]);","title":"End timeline if a particular key is pressed"},{"location":"reference/jspsych/#jspsychendexperiment","text":"jsPsych . endExperiment ( end_message , data )","title":"jsPsych.endExperiment"},{"location":"reference/jspsych/#parameters_3","text":"Parameter Type Description end_message string A message to display on the screen after the experiment is over. Can include HTML formatting. data object An optional object of key-value pairs to store as data in the final trial of the experiment.","title":"Parameters"},{"location":"reference/jspsych/#return-value_3","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_3","text":"Ends the experiment, skipping all remaining trials. If the on_finish event handler for jsPsych returns a Promise then the end_message will not be displayed until the promise is resolved.","title":"Description"},{"location":"reference/jspsych/#example_3","text":"","title":"Example"},{"location":"reference/jspsych/#end-the-experiment-if-a-particular-response-is-given","text":"var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'image1.jpg' , choices : [ 'y' , 'n' ] prompt : '<p>Press \"y\" to Continue. Press \"n\" to end the experiment</p>' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"n\" )){ jsPsych . endExperiment ( 'The experiment was ended by pressing \"n\".' ); } } }","title":"End the experiment if a particular response is given"},{"location":"reference/jspsych/#jspsychfinishtrial","text":"jsPsych . finishTrial ( data )","title":"jsPsych.finishTrial"},{"location":"reference/jspsych/#parameters_4","text":"Parameter Type Description data object The data to store for the trial.","title":"Parameters"},{"location":"reference/jspsych/#return-value_4","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych/#description_4","text":"This method tells jsPsych that the current trial is over. It is used in all of the plugins to end the current trial. When the trial ends a few things happen: The data is stored using jsPsych.data.write() The on_finish callback function is executed for the trial The on_trial_finish callback function is executed The progress bar is updated if it is being displayed The experiment ends if the trial is the last one (and the on_finish callback function is executed). The next trial, if one exists, is started.","title":"Description"},{"location":"reference/jspsych/#example_4","text":"// this code would be in a plugin jsPsych . finishTrial ({ correct_response : true });","title":"Example"},{"location":"reference/jspsych/#jspsychgetalltimelinevariables","text":"jsPsych . getAllTimelineVariables ()","title":"jsPsych.getAllTimelineVariables"},{"location":"reference/jspsych/#parameters_5","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_5","text":"Returns an object with all available timeline variables at this moment in the experiment, represented as key: value pairs.","title":"Return value"},{"location":"reference/jspsych/#description_5","text":"This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating data, such as in the example below.","title":"Description"},{"location":"reference/jspsych/#example_5","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Just a demo' , on_finish : function ( data ){ // merge all timeline variables available at this trial into the data for this trial Object . assign ( data , jsPsych . getAllTimelineVariables ()) } }","title":"Example"},{"location":"reference/jspsych/#jspsychgetcurrenttimelinenodeid","text":"jsPsych . getCurrentTimelineNodeID ()","title":"jsPsych.getCurrentTimelineNodeID"},{"location":"reference/jspsych/#parameters_6","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_6","text":"Returns the ID of the TimelineNode that is currently active.","title":"Return value"},{"location":"reference/jspsych/#description_6","text":"Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: \"0.0\" is the ID of the first top-level TimelineNode \"1.0\" is the ID of the second top-level TimelineNode \"2.0\" is the ID of the third top-level TimelineNode, and so on... If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: \"0.0\" is the ID of the first top-level TimelineNode during the first iteration \"0.1\" is the ID of the first top-level TimelineNode during the second iteration \"0.2\" is the ID of the first top-level TimelineNode during the third iteration, and so on... If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with \".\" : \"0.0-1.0\" is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. \"0.0-2.0\" is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... The rules about iterations apply throughout the hierarchical ID: \"0.2-1.3\" is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time.","title":"Description"},{"location":"reference/jspsych/#example_6","text":"var id = jsPsych . getCurrentTimelineNodeID (); console . log ( 'The current TimelineNode ID is ' + id );","title":"Example"},{"location":"reference/jspsych/#jspsychgetcurrenttrial","text":"jsPsych . getCurrentTrial ()","title":"jsPsych.getCurrentTrial"},{"location":"reference/jspsych/#parameters_7","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_7","text":"Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial.","title":"Return value"},{"location":"reference/jspsych/#description_7","text":"Get a description of the current trial","title":"Description"},{"location":"reference/jspsych/#example_7","text":"var trial = jsPsych . getCurrentTrial (); console . log ( 'The current trial is using the ' + trial . type + ' plugin' );","title":"Example"},{"location":"reference/jspsych/#jspsychgetdisplayelement","text":"jsPsych . getDisplayElement ()","title":"jsPsych.getDisplayElement"},{"location":"reference/jspsych/#parameters_8","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_8","text":"Returns the HTML DOM element used for displaying the experiment.","title":"Return value"},{"location":"reference/jspsych/#description_8","text":"Get the DOM element that displays the experiment.","title":"Description"},{"location":"reference/jspsych/#example_8","text":"","title":"Example"},{"location":"reference/jspsych/#var-el-jspsychgetdisplayelement-hide-the-jspsych-display-elstylevisibility-hidden","text":"","title":"var el = jsPsych.getDisplayElement();\n\n// hide the jsPsych display\nel.style.visibility = &#39;hidden&#39;;\n"},{"location":"reference/jspsych/#jspsychgetinitsettings","text":"jsPsych . getInitSettings ()","title":"jsPsych.getInitSettings"},{"location":"reference/jspsych/#parameters_9","text":"None","title":"Parameters"},{"location":"reference/jspsych/#return-value_9","text":"Returns the settings object used to initialize the experiment.","title":"Return value"},{"location":"reference/jspsych/#description_9","text":"Gets the object containing the settings for the current experiment.","title":"Description"},{"location":"reference/jspsych/#example_9","text":"var settings = jsPsych . getInitSettings (); // check the experiment structure console . log ( JSON . stringify ( settings . timeline ));","title":"Example"},{"location":"reference/jspsych/#jspsychgetprogress","text":"jsPsych . getProgress ()","title":"jsPsych.getProgress"},{"location":"reference/jspsych/#parameters_10","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_10","text":"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.","title":"Return value"},{"location":"reference/jspsych/#description_10","text":"This method returns information about the length of the experiment and the participant's current location in the experiment timeline.","title":"Description"},{"location":"reference/jspsych/#example_10","text":"var progress = jsPsych . getProgress (); alert ( 'You have completed approximately ' + progress . percent_complete + '% of the experiment' );","title":"Example"},{"location":"reference/jspsych/#jspsychgetprogressbarcompleted","text":"jsPsych . getProgressBarCompleted ()","title":"jsPsych.getProgressBarCompleted"},{"location":"reference/jspsych/#parameters_11","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_11","text":"Returns a value between 0 and 1 representing how full the progress bar currently is.","title":"Return value"},{"location":"reference/jspsych/#description_11","text":"Used to get the current value of the progress bar. Works for automated and manual control.","title":"Description"},{"location":"reference/jspsych/#example_11","text":"var progress_bar_amount = jsPsych . getProgressBarCompleted ();","title":"Example"},{"location":"reference/jspsych/#jspsychgetstarttime","text":"jsPsych . getStartTime ()","title":"jsPsych.getStartTime"},{"location":"reference/jspsych/#parameters_12","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_12","text":"Returns a Date object indicating when the experiment began.","title":"Return value"},{"location":"reference/jspsych/#description_12","text":"Get the time that the experiment began.","title":"Description"},{"location":"reference/jspsych/#example_12","text":"var start_time = jsPsych . getStartTime ();","title":"Example"},{"location":"reference/jspsych/#jspsychgettotaltime","text":"jsPsych . getTotalTime ()","title":"jsPsych.getTotalTime"},{"location":"reference/jspsych/#parameters_13","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_13","text":"Returns a numeric value indicating the number of milliseconds since jsPsych.run was called.","title":"Return value"},{"location":"reference/jspsych/#description_13","text":"Gets the total time the participant has been in the experiment.","title":"Description"},{"location":"reference/jspsych/#example_13","text":"var time = jsPsych . getTotalTime (); console . log ( time );","title":"Example"},{"location":"reference/jspsych/#jspsychpauseexperiment","text":"jsPsych . pauseExperiment ()","title":"jsPsych.pauseExperiment"},{"location":"reference/jspsych/#parameters_14","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_14","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_14","text":"Pauses the experiment. The experiment will finish the current trial, but will not execute any additional trials until jsPsych.resumeExperiment() is called.","title":"Description"},{"location":"reference/jspsych/#example_14","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } }","title":"Example"},{"location":"reference/jspsych/#jspsychresumeexperiment","text":"jsPsych . resumeExperiment ()","title":"jsPsych.resumeExperiment"},{"location":"reference/jspsych/#parameters_15","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_15","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_15","text":"Resumes the experiment after a call to jsPsych.pauseExperiment() . If the post trial delay ( post_trial_gap ) has not yet been reached, then the experiment will not continue until the delay is finished. For example, if post_trial_gap was 10,000ms and jsPsych.resumeExperiment() was called 6,000ms after the previous trial finished, then the experiment would not continue for another 4,000ms.","title":"Description"},{"location":"reference/jspsych/#example_15","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } }","title":"Example"},{"location":"reference/jspsych/#jspsychrun","text":"jsPsych . run ( timeline )","title":"jsPsych.run"},{"location":"reference/jspsych/#parameters_16","text":"Parameter Type Description timeline array An array containing the objects that describe the experiment timeline. See Creating an Experiment: The Timeline .","title":"Parameters"},{"location":"reference/jspsych/#return-value_16","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_16","text":"Start the jsPsych experiment with the specified timeline.","title":"Description"},{"location":"reference/jspsych/#example_16","text":"var timeline = [ trial1 , trial2 , trial3 ]; jsPsych . run ( timeline );","title":"Example"},{"location":"reference/jspsych/#jspsychsetprogressbar","text":"jsPsych . setProgressBar ( value )","title":"jsPsych.setProgressBar"},{"location":"reference/jspsych/#parameters_17","text":"Parameter Type Description value numeric Proprotion (between 0 and 1) to fill the progress bar.","title":"Parameters"},{"location":"reference/jspsych/#return-value_17","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_17","text":"Set the progress bar to a custom amount. Proportion must be between 0 and 1. Values larger than 1 are treated as 1.","title":"Description"},{"location":"reference/jspsych/#example_17","text":"jsPsych . setProgressBar ( 0.85 );","title":"Example"},{"location":"reference/jspsych/#jspsychtimelinevariable","text":"jsPsych . timelineVariable ( variable , call_immediate )","title":"jsPsych.timelineVariable"},{"location":"reference/jspsych/#parameters_18","text":"Parameter Type Description variable string Name of the timeline variable call_immediate bool This parameter is optional and can usually be omitted. It determines the return value of jsPsych.timelineVariable . If true , the function returns the value of the current timeline variable. If false , the function returns a function that returns the value of the current timeline variable. When call_immediate is omitted, the appropriate option is determined automatically based on the context in which this function is called. When jsPsych.timelineVariable is used as a parameter value, call_immediate will be false . This allows it to be used as a dynamic trial parameter . When jsPsych.timelineVariable is used inside of a function, call_immediate will be true . It is possible to explicitly set this option to true to force the function to immediately return the current value of the timeline variable.","title":"Parameters"},{"location":"reference/jspsych/#return-value_18","text":"Either a function that returns the value of the timeline variable, or the value of the timeline variable, depending on the context in which it is used. See call_immediate description above.","title":"Return value"},{"location":"reference/jspsych/#description_18","text":"Timeline variables are a powerful technique for generating experiments with repetitive procedures but different parameter values. This function fetches the current value of a particular timeline variable. It must be used in conjunction with a timeline that has timeline variables. See the timeline variable section for details.","title":"Description"},{"location":"reference/jspsych/#examples","text":"","title":"Examples"},{"location":"reference/jspsych/#standard-use-as-a-parameter-for-a-trial","text":"var trial = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'image' ) } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] }","title":"Standard use as a parameter for a trial"},{"location":"reference/jspsych/#invoking-immediately-in-a-function","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Prior to jsPsych v6.3.0, the call_immediate parameter must be set to true when jsPsych.timelineVariable is called from within a function, such as a dynamic parameter : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' , true ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] }","title":"Invoking immediately in a function"},{"location":"reference/jspsych/#jspsychversion","text":"jsPsych . version ()","title":"jsPsych.version"},{"location":"reference/jspsych/#parameters_19","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_19","text":"Returns the version number as a string.","title":"Return value"},{"location":"reference/jspsych/#description_19","text":"Gets the version of jsPsych.","title":"Description"},{"location":"reference/jspsych/#example_18","text":"var version = jsPsych . version (); console . log ( version );","title":"Example"},{"location":"support/migration-v7/","text":"Migrating an experiment to v7.x \u00b6 The release of version 7.0 changes a number of core components of jsPsych. We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych. Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. However, we did have to change a few critical things. This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x. Loading jsPsych \u00b6 There are now three different ways you can load jsPsych into your HTML file. We've updated the hello world tutorial to walk through each of the three options. If you are looking for the option that is most similar to the version 6.x experience, check out option 2 . The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently. Initializing and running jsPsych \u00b6 We've removed jsPsych.init() and split the features into two different functions. At the start of your experiment script, you'll now call initJsPsych() to get a new instance of jsPsych and store it in a variable called jsPsych . This is where you will pass in the variety of parameters that used to go into jsPsych.init() , with the exception of the timeline parameter. var jsPsych = initJsPsych ({ use_webaudio : false , on_finish : function (){ jsPsych . data . displayData (); } }); Once you've created your timeline, then you'll launch the experiment by calling jsPsych.run() , passing in the timeline as the only argument. This is the point in your script where you've used the jsPsych.init function in jsPsych v6.x. Because the jsPsych.run function only needs the experiment timeline, this argument should be an array (rather than an object like {timeline: timeline} in jsPsych v6.x). var timeline = [...] jsPsych . run ( timeline ); The type parameter for trials \u00b6 The type parameter now expects the value to be a plugin class rather than a string. For example, if you load the html-keyboard-response plugin from the CDN... < script src = \"http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.0\" ></ script > ... or from the plugin-html-keyboard-response.js file in the release archive... < script src = \"plugin-html-keyboard-response.js\" ></ script > ... then a global variable defining the plugin's class called jsPsychHtmlKeyboardResponse is available. To create a trial using the plugin, pass this class as the type parameter. The plugin classes are named starting with jsPsych , followed by the plugin name written in camel case (rather than with dashes between words). See the \"Using a plugin\" section of the Plugins overview page for more examples. Note that the value is not a string . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' } The choices parameter for keyboard response trials \u00b6 The choices parameter for keyboard response trials no longer supports jsPsych.NO_KEYS and jsPsych.ALL_KEYS , and they have been replaced by the strings \"NO_KEYS\" and \"ALL_KEYS\" respectively. For example, if you load the audio-keyboard-response plugin, you can prevent any user input like... var trial = { type : jsPsychAudioKeyboardResponse , choices : \"NO_KEYS\" , stimulus : 'example.ogg' , trial_ends_after_audio : true } Using extensions \u00b6 Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in initJsPsych() instead of jsPsych.init() . Extension classes are named similarly to plugins, except that they start with jsPsychExtension . var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) The class is also used in trials that use the extension. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' , extensions : [ { type : jsPsychExtensionWebgazer } ] } Custom plugins \u00b6 If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our plugin template . The new template implements plugins as a class, but the core components are essentially unchanged. Anything in plugin.info from a v6.x plugin should be moved into the info object. Note that the type argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then assigned as a static property of the class . Anything in plugin.trial from a v6.x plugin should be moved into the trial method inside the class. The new template has a constructor() function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin. There are a few changes to be aware of that may affect your plugin code. We removed the registerPreload function and we now auto-detect media to preload via the type argument specified in the info object. If a parameter is listed as IMAGE , AUDIO , or VIDEO , it will be automatically preloaded. If you wish to disable preloading you can set the preload flag to false for the parameter. If you invoke any functions from jsPsych, like jsPsych.finishTrial() , note that jsPsych is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simply prefix all jsPsych references with this. , e.g., jsPsych.finishTrial() becomes this.jsPsych.finishTrial() . If your reference to a jsPsych function is inside of another function, then in order for the this keyword to appropriately reference the jsPsych instance, you must also use a JavaScript arrow function expression for the outer function. For example, this: function end_trial () { // ... jsPsych . finishTrial ( data ); } Would be re-written as: const end_trial = () => { // ... this . jsPsych . finishTrial ( data ); } Need help? \u00b6 If you encounter issues migrating code to v7.x, feel free to post in our support thread for migration .","title":"Migrating from 6.x to 7.x"},{"location":"support/migration-v7/#migrating-an-experiment-to-v7x","text":"The release of version 7.0 changes a number of core components of jsPsych. We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych. Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. However, we did have to change a few critical things. This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x.","title":"Migrating an experiment to v7.x"},{"location":"support/migration-v7/#loading-jspsych","text":"There are now three different ways you can load jsPsych into your HTML file. We've updated the hello world tutorial to walk through each of the three options. If you are looking for the option that is most similar to the version 6.x experience, check out option 2 . The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently.","title":"Loading jsPsych"},{"location":"support/migration-v7/#initializing-and-running-jspsych","text":"We've removed jsPsych.init() and split the features into two different functions. At the start of your experiment script, you'll now call initJsPsych() to get a new instance of jsPsych and store it in a variable called jsPsych . This is where you will pass in the variety of parameters that used to go into jsPsych.init() , with the exception of the timeline parameter. var jsPsych = initJsPsych ({ use_webaudio : false , on_finish : function (){ jsPsych . data . displayData (); } }); Once you've created your timeline, then you'll launch the experiment by calling jsPsych.run() , passing in the timeline as the only argument. This is the point in your script where you've used the jsPsych.init function in jsPsych v6.x. Because the jsPsych.run function only needs the experiment timeline, this argument should be an array (rather than an object like {timeline: timeline} in jsPsych v6.x). var timeline = [...] jsPsych . run ( timeline );","title":"Initializing and running jsPsych"},{"location":"support/migration-v7/#the-type-parameter-for-trials","text":"The type parameter now expects the value to be a plugin class rather than a string. For example, if you load the html-keyboard-response plugin from the CDN... < script src = \"http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.0\" ></ script > ... or from the plugin-html-keyboard-response.js file in the release archive... < script src = \"plugin-html-keyboard-response.js\" ></ script > ... then a global variable defining the plugin's class called jsPsychHtmlKeyboardResponse is available. To create a trial using the plugin, pass this class as the type parameter. The plugin classes are named starting with jsPsych , followed by the plugin name written in camel case (rather than with dashes between words). See the \"Using a plugin\" section of the Plugins overview page for more examples. Note that the value is not a string . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' }","title":"The type parameter for trials"},{"location":"support/migration-v7/#the-choices-parameter-for-keyboard-response-trials","text":"The choices parameter for keyboard response trials no longer supports jsPsych.NO_KEYS and jsPsych.ALL_KEYS , and they have been replaced by the strings \"NO_KEYS\" and \"ALL_KEYS\" respectively. For example, if you load the audio-keyboard-response plugin, you can prevent any user input like... var trial = { type : jsPsychAudioKeyboardResponse , choices : \"NO_KEYS\" , stimulus : 'example.ogg' , trial_ends_after_audio : true }","title":"The choices parameter for keyboard response trials"},{"location":"support/migration-v7/#using-extensions","text":"Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in initJsPsych() instead of jsPsych.init() . Extension classes are named similarly to plugins, except that they start with jsPsychExtension . var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) The class is also used in trials that use the extension. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' , extensions : [ { type : jsPsychExtensionWebgazer } ] }","title":"Using extensions"},{"location":"support/migration-v7/#custom-plugins","text":"If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our plugin template . The new template implements plugins as a class, but the core components are essentially unchanged. Anything in plugin.info from a v6.x plugin should be moved into the info object. Note that the type argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then assigned as a static property of the class . Anything in plugin.trial from a v6.x plugin should be moved into the trial method inside the class. The new template has a constructor() function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin. There are a few changes to be aware of that may affect your plugin code. We removed the registerPreload function and we now auto-detect media to preload via the type argument specified in the info object. If a parameter is listed as IMAGE , AUDIO , or VIDEO , it will be automatically preloaded. If you wish to disable preloading you can set the preload flag to false for the parameter. If you invoke any functions from jsPsych, like jsPsych.finishTrial() , note that jsPsych is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simply prefix all jsPsych references with this. , e.g., jsPsych.finishTrial() becomes this.jsPsych.finishTrial() . If your reference to a jsPsych function is inside of another function, then in order for the this keyword to appropriately reference the jsPsych instance, you must also use a JavaScript arrow function expression for the outer function. For example, this: function end_trial () { // ... jsPsych . finishTrial ( data ); } Would be re-written as: const end_trial = () => { // ... this . jsPsych . finishTrial ( data ); }","title":"Custom plugins"},{"location":"support/migration-v7/#need-help","text":"If you encounter issues migrating code to v7.x, feel free to post in our support thread for migration .","title":"Need help?"},{"location":"support/support/","text":"Support \u00b6 For questions about jsPsych, the preferred method of support is GitHub Discussions . Questions are most likely to be answered when they include a reproducible example of the problem. If you can make your code available online and link to the experiment, that will make the question easier to answer. Please consider searching through the archive of Q&As before posting a new question. If you have identified a problem with jsPsych, such as a bug in the code or an error in the documentation, please open a new issue on GitHub. If you have a suggestion for fixing the problem, feel free to contribute to the project ! Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to josh.deleeuw@gmail.com .","title":"Getting Help"},{"location":"support/support/#support","text":"For questions about jsPsych, the preferred method of support is GitHub Discussions . Questions are most likely to be answered when they include a reproducible example of the problem. If you can make your code available online and link to the experiment, that will make the question easier to answer. Please consider searching through the archive of Q&As before posting a new question. If you have identified a problem with jsPsych, such as a bug in the code or an error in the documentation, please open a new issue on GitHub. If you have a suggestion for fixing the problem, feel free to contribute to the project ! Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to josh.deleeuw@gmail.com .","title":"Support"},{"location":"tutorials/hello-world/","text":"jsPsych \"Hello world\" experiment \u00b6 In the long tradition of \"Hello world!\" examples, this tutorial creates an experiment that outputs the phrase \"Hello world!\" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library. Choose your own (setup) adventure \u00b6 Starting with the release of version 7.0 of jsPsych there are three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are. I want the simplest possible setup . This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient. I want to be able to do some customization, but have a simple setup. . This approach involves downloading a bundle of scripts that make up jsPsych. If you used jsPsych prior to version 7.0, this will feel like the most familiar approach . Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior. I want to use modern JavaScript tooling, like npm and import statements. You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from NPM. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more. Option 1: Using CDN-hosted scripts \u00b6 Step 1: Create an HTML file \u00b6 Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html . There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. Step 2: Load the jsPsych library \u00b6 To use jsPsych, add a <script> tag to load the library. We'll load the library from a CDN , which means that the library is hosted on another server and can be loaded without having your own copy. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > </ head > < body ></ body > </ html > Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych. You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html > Step 3: Create a script element and initialize jsPsych \u00b6 To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Step 4: Use a plugin to print a message \u00b6 For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html > Step 5: Run the experiment \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). Option 2: Download and host jsPsych \u00b6 Step 1: Download jsPsych \u00b6 Start by downloading the latest release of jsPsych. Here's a direct link (jspsych.zip) . The most recent version can always be found at the top of the GitHub releases page . Note that even the releases that are for a particular plugin or extension will contain the full set of files needed to run jsPsych locally in the dist archive (zip) release asset. You should download the zip file for whatever the most recently released package is. This will ensure that you have the most recent version of all the packages associated with jsPsych. Step 2: Create a folder to store your experiment files \u00b6 Create a folder on your computer to put the experiment files in. We'll call this \"MyExperiment\" for the tutorial. Add a subfolder called jspsych . Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the dist folder into the jspsych folder. It should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc2 jspsych ---- \ud83d\udcc4 jspsych.js ---- \ud83d\udcc4 plugin-animation.js ---- \ud83d\udcc4 plugin-audio-keyboard-response.js ---- ... Step 3: Create an HTML file \u00b6 Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html in the MyExperiment folder. The directory structure should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc4 experiment.html -- \ud83d\udcc2 jspsych There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. Step 4: Load the jsPsych library \u00b6 To use jsPsych, add a <script> tag to load the library. Set the src attribute to the path to the jspsych.js file. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > </ head > < body ></ body > </ html > You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html > Step 5: Create a script element and initialize jsPsych \u00b6 To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Step 6: Use a plugin to print a message \u00b6 For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html > Step 7: Run the experiment \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). Option 3: Using NPM \u00b6 If you are electing to use npm to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. We will also assume that you are using a webpack or a similar bundler. Info You may want to check out the jsPsych Builder CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles using webpack. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page. Step 1: Install jspsych \u00b6 Run npm install jspsych . This installs the core jsPsych package. Plugins and extensions are installed separately. Step 2: Import the initJsPsych function and create a new JsPsych instance \u00b6 We create a new instance of the JsPsych class by calling initJsPsych . The instance can optionally be configured via a variety of options , passed as an object to initJsPsych . import { initJsPsych } from 'jspsych' ; const jsPsych = initJsPsych (); Step 3: Static markup and CSS \u00b6 jsPsych requires nothing but a body element in your HTML document. For the jsPsych stylesheet, depending on your bundler setup, you can either directly import 'jspsych/css/jspsych.css' into your JavaScript file or add a link tag (like <link href=\"path/to/jspsych.css\" rel=\"stylesheet\" type=\"text/css\" /> ) to your HTML document's head. Step 4: Install and import a plugin \u00b6 Install the html-keyboard-response plugin with: npm install @jspsych/plugin-html-keyboard-response Then import the htmlKeyboardResponse plugin class. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); Step 5: Create a trial \u00b6 Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to htmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } Step 6: Run \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } jsPsych . run ([ trial ]);","title":"The Basics: Hello World"},{"location":"tutorials/hello-world/#jspsych-hello-world-experiment","text":"In the long tradition of \"Hello world!\" examples, this tutorial creates an experiment that outputs the phrase \"Hello world!\" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library.","title":"jsPsych \"Hello world\" experiment"},{"location":"tutorials/hello-world/#choose-your-own-setup-adventure","text":"Starting with the release of version 7.0 of jsPsych there are three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are. I want the simplest possible setup . This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient. I want to be able to do some customization, but have a simple setup. . This approach involves downloading a bundle of scripts that make up jsPsych. If you used jsPsych prior to version 7.0, this will feel like the most familiar approach . Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior. I want to use modern JavaScript tooling, like npm and import statements. You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from NPM. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more.","title":"Choose your own (setup) adventure"},{"location":"tutorials/hello-world/#option-1-using-cdn-hosted-scripts","text":"","title":"Option 1: Using CDN-hosted scripts"},{"location":"tutorials/hello-world/#step-1-create-an-html-file","text":"Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html . There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.","title":"Step 1: Create an HTML file"},{"location":"tutorials/hello-world/#step-2-load-the-jspsych-library","text":"To use jsPsych, add a <script> tag to load the library. We'll load the library from a CDN , which means that the library is hosted on another server and can be loaded without having your own copy. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > </ head > < body ></ body > </ html > Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych. You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html >","title":"Step 2: Load the jsPsych library"},{"location":"tutorials/hello-world/#step-3-create-a-script-element-and-initialize-jspsych","text":"To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html >","title":"Step 3: Create a script element and initialize jsPsych"},{"location":"tutorials/hello-world/#step-4-use-a-plugin-to-print-a-message","text":"For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html >","title":"Step 4: Use a plugin to print a message"},{"location":"tutorials/hello-world/#step-5-run-the-experiment","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).","title":"Step 5: Run the experiment"},{"location":"tutorials/hello-world/#option-2-download-and-host-jspsych","text":"","title":"Option 2: Download and host jsPsych"},{"location":"tutorials/hello-world/#step-1-download-jspsych","text":"Start by downloading the latest release of jsPsych. Here's a direct link (jspsych.zip) . The most recent version can always be found at the top of the GitHub releases page . Note that even the releases that are for a particular plugin or extension will contain the full set of files needed to run jsPsych locally in the dist archive (zip) release asset. You should download the zip file for whatever the most recently released package is. This will ensure that you have the most recent version of all the packages associated with jsPsych.","title":"Step 1: Download jsPsych"},{"location":"tutorials/hello-world/#step-2-create-a-folder-to-store-your-experiment-files","text":"Create a folder on your computer to put the experiment files in. We'll call this \"MyExperiment\" for the tutorial. Add a subfolder called jspsych . Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the dist folder into the jspsych folder. It should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc2 jspsych ---- \ud83d\udcc4 jspsych.js ---- \ud83d\udcc4 plugin-animation.js ---- \ud83d\udcc4 plugin-audio-keyboard-response.js ---- ...","title":"Step 2: Create a folder to store your experiment files"},{"location":"tutorials/hello-world/#step-3-create-an-html-file","text":"Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html in the MyExperiment folder. The directory structure should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc4 experiment.html -- \ud83d\udcc2 jspsych There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.","title":"Step 3: Create an HTML file"},{"location":"tutorials/hello-world/#step-4-load-the-jspsych-library","text":"To use jsPsych, add a <script> tag to load the library. Set the src attribute to the path to the jspsych.js file. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > </ head > < body ></ body > </ html > You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html >","title":"Step 4: Load the jsPsych library"},{"location":"tutorials/hello-world/#step-5-create-a-script-element-and-initialize-jspsych","text":"To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html >","title":"Step 5: Create a script element and initialize jsPsych"},{"location":"tutorials/hello-world/#step-6-use-a-plugin-to-print-a-message","text":"For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html >","title":"Step 6: Use a plugin to print a message"},{"location":"tutorials/hello-world/#step-7-run-the-experiment","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).","title":"Step 7: Run the experiment"},{"location":"tutorials/hello-world/#option-3-using-npm","text":"If you are electing to use npm to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. We will also assume that you are using a webpack or a similar bundler. Info You may want to check out the jsPsych Builder CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles using webpack. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page.","title":"Option 3: Using NPM"},{"location":"tutorials/hello-world/#step-1-install-jspsych","text":"Run npm install jspsych . This installs the core jsPsych package. Plugins and extensions are installed separately.","title":"Step 1: Install jspsych"},{"location":"tutorials/hello-world/#step-2-import-the-initjspsych-function-and-create-a-new-jspsych-instance","text":"We create a new instance of the JsPsych class by calling initJsPsych . The instance can optionally be configured via a variety of options , passed as an object to initJsPsych . import { initJsPsych } from 'jspsych' ; const jsPsych = initJsPsych ();","title":"Step 2: Import the initJsPsych function and create a new JsPsych instance"},{"location":"tutorials/hello-world/#step-3-static-markup-and-css","text":"jsPsych requires nothing but a body element in your HTML document. For the jsPsych stylesheet, depending on your bundler setup, you can either directly import 'jspsych/css/jspsych.css' into your JavaScript file or add a link tag (like <link href=\"path/to/jspsych.css\" rel=\"stylesheet\" type=\"text/css\" /> ) to your HTML document's head.","title":"Step 3: Static markup and CSS"},{"location":"tutorials/hello-world/#step-4-install-and-import-a-plugin","text":"Install the html-keyboard-response plugin with: npm install @jspsych/plugin-html-keyboard-response Then import the htmlKeyboardResponse plugin class. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych ();","title":"Step 4: Install and import a plugin"},{"location":"tutorials/hello-world/#step-5-create-a-trial","text":"Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to htmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , }","title":"Step 5: Create a trial"},{"location":"tutorials/hello-world/#step-6-run","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } jsPsych . run ([ trial ]);","title":"Step 6: Run"},{"location":"tutorials/rt-task/","text":"Summary of Tutorial Content \u00b6 This tutorial will work through the creation of a simple response time task. The task is to press one key for a blue colored circle and another key for an orange colored circle. Despite this simple task, the tutorial covers many of the key features of jsPsych, including: Using a plugin to create a standard trial. Combining plugins together to create new kinds of trials. Using timeline variables to maximize code reuse. Preloading media. Randomizing presentation order. Manipulating, filtering, and aggregating data. Using dynamic content to change the experiment parameters based on the participant's responses. Part 1: Creating a blank experiment \u00b6 Start by setting up a new HTML file with jsPsych, the html-keyboard-response plugin, and the jspsych.css file loaded. If you are unsure how to do this, follow the Hello World tutorial . You should have an HTML document that looks like this: Info: Loading jsPsych This tutorial assumes that you are using the CDN-based method of loading jsPsych . If you are using another method then everything is the same except for how jsPsych is loaded. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > This will be our starting point for building the rest of the experiment. Part 2: Display welcome message \u00b6 First we have to initialize jsPsych. We can do this using the initJsPsych() function , and saving the result to a variable called jsPsych . var jsPsych = initJsPsych (); All jsPsych experiments are defined by a timeline. The timeline is an array that contains the set of trials we want to run in the experiment. We can start by defining an empty timeline array. We'll add trials to this array as we create them. var timeline = []; Let's greet the participant with a simple welcome message using the html-keyboard-response plugin. First, we create a trial that uses the html-keyboard-response plugin and contains a simple string to show the participant. As explained on the plugins documentation page , the trial object must have a type parameter that tells jsPsych which plugin to use. The value of type is similar to the plugin name, but starts with jsPsych and is written in camel case rather than with dashes. So to use the html-keyboard-response plugin, we need to write jsPsychHtmlKeyboardResponse as the trial type. var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; Next, we push the welcome trial to the timeline, which adds it to the end of the array. timeline . push ( welcome ); Finally, we tell jsPsych to run the experiment by calling the jsPsych.run() function and passing in the array that defines the experiment timeline. jsPsych . run ( timeline ); After each step in the tutorial you can view the complete code up to that point by clicking on the expandable box below. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 3: Show instructions \u00b6 We can use the same basic structure from part 2 to create a new html-keyboard-response trial that shows instructions to the participant. The only difference in this trial is that we will use HTML formatting to control how the instructions display and we will add a two second gap after the trial using the post_trial_gap parameter. The trial definition looks like this: var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; Tip In JavaScript there are three different ways to define a string . You can use single quotes ' , double quotes \" , or backticks ` . Using backticks has two advantages over the other approaches, especially when you are creating long strings with HTML. You can extend the string across multiple lines and you can use template strings to easily incorporate variables. Notice that the HTML includes <img> tags to display the images that the participant will be responding to. You'll need to download these image files. Right-click on each image below and select Save image as... . Put the images in a folder called img in the experiment folder you created in part 1. Don't forget to add the trial to the timeline: timeline . push ( instructions ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 4: Displaying stimuli and getting responses \u00b6 Creating trials to show the stimuli is conceptually the same as creating a trial to show instructions, except that now we are displaying an image instead of text or html. This means we need to use a different plugin: image-keyboard-response . We need to start by loading this plugin by adding a <script> tag to the document. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > For now, we will just show each image once. The path to the image file should be set as the stimulus parameter. We will also set the option for which keys the participant is allowed to use to respond ( choices ) so that only the 'f' and 'j' keys are valid responses. var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; As usual, we need to add the trials to the timeline. timeline . push ( blue_trial , orange_trial ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 5: Preloading media \u00b6 Whenever we use media elements (images, audio, or video) in an experiment it is a good idea to preload them prior to needing them for a trial. By preloading media we ask the participant's browser to download the media ahead of needing it, so that when we do need to display or play it there is no lag from needing to download it. We are going to use the preload plugin to preload the two images. The media preloading section goes into a lot of detail about various options for preloading and different ways that you can use this plugin. Here we are simply going to give the plugin a list of the files that we want to be preloaded. First we need to add the preload plugin to our <head> section. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > We'll put this trial at the very start of the experiment, so add this code before the welcome trial. var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; As always, add the trial to the timeline. timeline . push ( preload ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 6: Timeline variables \u00b6 In the full experiment, we will want more than two trials. One way we could do this is to create many more objects that define trials and push them all onto the timeline, but there is a more efficient way: using timeline variables. The parameters for showing the blue and orange circle are very similar. The only difference is which image is displayed. Timeline variables allow us to define the procedure for showing the stimulus once, and then repeatedly use it with different variables. We'll see how, even in this relatively simple case, this can save us a lot of lines of code. To start, let's make an array that contains all the different trials we want to run in the test phase. There are only two for the experiment: blue trials and orange trials. var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; Instead of just showing the blue and orange circles, let's also set up the experiment to show a fixation cross (+) in between trials. We can define a trial to show the fixation cross for a fixed amount of time by using the trial_duration parameter of the html-keyboard-response plugin and setting the choices parameter to the special value \"NO_KEYS\" , which means that no responses will be accepted as a valid response and the trial will last however long the trial_duration parameter specifies. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; To show the circles, we'll set up another trial with the image-keyboard-response plugin, but we'll use the function jsPsych.timelineVariable() to indicate that we want jsPsych to substitute the value of the parameter in from the timeline variables. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] } To link the variables that we declared in the test_stimuli array with the call to jsPsych.timelineVariable() we need to create a new timeline and set the timeline_variables property: var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli } We have to add the test_procedure to the main timeline array, but the fixation and test trial do not need to be added to timeline because they already exist on the test_procedure timeline. timeline . push ( test_procedure ); What happens when the experiment reaches the test procedure? jsPsych will run the test_procedure timeline one time for each entry in the test_stimuli array (two times total, in this case). The first time through, jsPsych will substitute the timeline variables from the first array entry (blue image), and the second time through the second array entry will be used (orange image). Notice that the fixation trial occurs before both the orange and the blue circles, because the entire timeline of the test_procedure is repeated for each entry in the timeline_variables array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 7: Parameters for timelines with timeline variables \u00b6 Right now our experiment is a measly two trials long. Even worse is that the order of the stimuli is the same every time! When we use timeline variables, we get access to some methods to randomize the order and repeat the trials. To randomize the order, simply set randomize_order: true on the object with the timeline_variables : var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true }; We can also easily make the test phase longer by setting the repetitions parameter. This parameter controls how many times the experiment will loop through all of the entries in the timeline_variables array. For example, if we set repetitions: 5 , then the experiment will loop through the two entries in the timeline_variables 5 times, for a total of 10 test trials. var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; Info: Randomizing timeline variables In a timeline variables procedure, when randomize_order is true and repetitions is greater than 1, the trial order will be re-randomized on each repetition through the timeline_variables array. This means that there will be some constraints on the randomization of all trials in the procedure. For example, if a timeline_variables array contains one trial per stimulus, then the same stimulus could occur twice in a row (since it could be at the end of one repetition and the start of the next one), but it could not be repeated more than twice in a row, regardless of the number of repetitions . If you want to repeat your timeline_variables array but randomize across all trials, you could use the sample parameter with the fixed-repetitions option: this will combine all the repeitions of your timeline_variables array into one larger array, and then randomize the whole thing. You can read more about the randomization, repetition, and sampling options for timeline variables in the Timeline Variables documentation . The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 8: Using functions to generate parameters \u00b6 One aspect of the experiment that could be improved is the duration of the fixation cross. As the experiment stands right now, the timing of the circles appearing is very predictable. We can change that by using a different value for the trial_duration parameter in the fixation trial for each trial. But how can we do that and keep the simple code structure we have now where we only have to define the fixation trial once? One option would be to add another timeline variable, like \"fixation_duration\" and use that to control the timing. But another option is to specify the trial_duration parameter as a function. If a parameter is a function, jsPsych will execute the function every time the trial runs. That means that if the function returns different results probabilistically, we can get a different parameter value every time the trial runs. To do that here, we'll use one of the built-in randomization methods in jsPsych's randomization module . jsPsych.randomization.sampleWithoutReplacement() takes an array of items to sample from and generates a new array of length N by sampling without replacement. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } } In the code above, we replaced the trial_duration: 1000 parameter in fixation with a function. Inside the function, we take a sample from the array [250, 500, 750, 1000, 1250, 1500, 1750, 2000] of size 1 (second parameter to jsPsych.randomization.sampleWithoutReplacement ). The return value from calling jsPsych.randomization.sampleWithoutReplacement is an array of length 1, so we add the [0] selection at the end to get the value out of the array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 10: Displaying the data \u00b6 We have created a complete, if simple, experiment at this point, so let's take a look at the data being generated. jsPsych has a built-in function called jsPsych.data.displayData() that is useful for debugging your experiment. It will remove all of the information on the screen and replace it with the raw data collected so far. This isn't terribly useful when you are actually running an experiment, but it's nice for checking the data during development. We need the displayData function to execute when the experiment ends. One way to do this is to use the on_finish callback function . This function will automatically execute once all the trials in the experiment are finished. We can specify this function in the experiment settings when we initialize jsPsych with the initJsPsych method. var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 11: Tagging trials with additional data \u00b6 All trials in jsPsych can be tagged with additional arbitrary data. This data will get stored alongside the data that the plugin normally generates, which allows experimenters to record properties of a trial along with the data from the trial. When might you use this feature? In this experiment, it would be nice to tag each trial with a circle as a response trial, so that the resulting data can be easily filtered to look at only the critical trials. We can do that like this. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' } }; We also could tag the test trials with a property that indicates what the correct response should be (F for the blue circles, J for the orange). In our current code, we are using the timeline variables feature of jsPsych to choose which circle gets presented on a trial. Since we want to tag the trials differently based on which circle is presented, we need to add the tagging data to the test_stimuli array, and then use the jsPsych.timelineVariable() function to get the value and assign it to a property in the data of the trial. We start by adding a \"correct_response\" property and value to each object in the test_stimuli : var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; Now we can use timelineVariable() in the data parameter of the test trial to get the appropriate \"correct_response\" value for each trial. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; Another kind of tagging that would be useful is to mark each fixation trial as such, to make removing the data from fixation trials easier. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 12: Manipulating data during the experiment \u00b6 Now that the data from the test trials has a tag that describes the correct response, it would be easy to analyze the data after the fact and calculate whether the participant responded correctly. But, we can also do this in jsPsych as the experiment runs to save time later and enable a limited set of data analysis directly in the experiment code. To do this, we'll use the on_finish event of the test trial. We can assign a function to on_finish , and that function will receive an object containing the data generated by the trial. This object can be manipulated inside the function, and any changes made to the object will be stored in jsPsych's internal representation of the data. For this example, we'll determine whether the participant responded correctly, and add a new correct property to the data object. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; The data.response value is a string representation of the key the participant pressed. We can compare this with the data.correct_response value, and assign this computed value to a new property data.correct . Info: The compareKeys function Here we are comparing the values of data.response and data.correct_response using a jsPsych function called jsPsych.pluginAPI.compareKeys . We're using this function because it allows us to compare keys in either a case sensitive or case insensitive way, depending on the case_sensitive_responses parameter in the experiment settings . The participant's key response will be recorded in a case-sensitive way in the data (e.g. 'f' or 'F'), but in most cases, we don't care if their response corresponds to an upper or lower case letter (which is why the case_sensitive_responses experiment setting is false by default). Using the jsPsych.pluginAPI.commpareKeys function here means that the response will be scored correctly, even if the participant holds down Shift or has Caps Lock on. This function is only relevant for keyboard responses; for other kinds of responses, such as button presses, you can simply compare the response and correct response values directly, e.g. data . correct = data . response === data . correct_response ; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 13: Data aggregation \u00b6 jsPsych provides a limited set of analysis functions to allow you to calculate things like mean response times for a selected set of trials. In this part, we'll use these functions to add a final trial to the experiment that tells the participant their accuracy and their mean response time for correct responses. We'll use the html-keyboard-response plugin. Because the text that we want to display changes based on the participant's performance in the experiment, we need to use a function for the stimulus parameter and return the desired text. Info: Dynamic parameters Using a function as the value of a 'normal' parameter (i.e. a parameter that isn't usually a function) provides lots of flexibility in jsPsych experiments, because it allows you to dynamically change the parameter's value based on the participant's earlier responses, and any other information that you don't know before the experiment has started. For more information and examples, see the dynamic parameter documentation page . Here's what the code looks like, and a description follows below. var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); To create the variable trials , we use jsPsych.data.get() which returns a jsPsych data collection containing all of the data from the experiment. We can then use .filter to select only the trials where task is 'response' (a benefit of tagging the trials in part 11). trials contains all of the data from the trials where a circle was shown. To get only the correct trials, we can use .filter() again to select only the trials from the trials data collection where the property correct is true . To calculate accuracy, we can use the .count() method to determine how many trials were correct and how many trials there were total. We also use Math.round() to avoid extra digits after the decimal. Finally, to calculate the mean response time on correct trials, we use the .select method on the correct_trials data collection to select only the 'rt' property of those trials. We can then use the .mean() method to find the mean of all the RT values. The final code \u00b6 This code is available in the /examples folder in the jsPsych release download. It is called demo-simple-rt-task.html . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , repetitions : 5 , randomize_order : true }; timeline . push ( test_procedure ); /* define debrief */ var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Demo Experiment: Simple Reaction Time Task"},{"location":"tutorials/rt-task/#summary-of-tutorial-content","text":"This tutorial will work through the creation of a simple response time task. The task is to press one key for a blue colored circle and another key for an orange colored circle. Despite this simple task, the tutorial covers many of the key features of jsPsych, including: Using a plugin to create a standard trial. Combining plugins together to create new kinds of trials. Using timeline variables to maximize code reuse. Preloading media. Randomizing presentation order. Manipulating, filtering, and aggregating data. Using dynamic content to change the experiment parameters based on the participant's responses.","title":"Summary of Tutorial Content"},{"location":"tutorials/rt-task/#part-1-creating-a-blank-experiment","text":"Start by setting up a new HTML file with jsPsych, the html-keyboard-response plugin, and the jspsych.css file loaded. If you are unsure how to do this, follow the Hello World tutorial . You should have an HTML document that looks like this: Info: Loading jsPsych This tutorial assumes that you are using the CDN-based method of loading jsPsych . If you are using another method then everything is the same except for how jsPsych is loaded. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > This will be our starting point for building the rest of the experiment.","title":"Part 1: Creating a blank experiment"},{"location":"tutorials/rt-task/#part-2-display-welcome-message","text":"First we have to initialize jsPsych. We can do this using the initJsPsych() function , and saving the result to a variable called jsPsych . var jsPsych = initJsPsych (); All jsPsych experiments are defined by a timeline. The timeline is an array that contains the set of trials we want to run in the experiment. We can start by defining an empty timeline array. We'll add trials to this array as we create them. var timeline = []; Let's greet the participant with a simple welcome message using the html-keyboard-response plugin. First, we create a trial that uses the html-keyboard-response plugin and contains a simple string to show the participant. As explained on the plugins documentation page , the trial object must have a type parameter that tells jsPsych which plugin to use. The value of type is similar to the plugin name, but starts with jsPsych and is written in camel case rather than with dashes. So to use the html-keyboard-response plugin, we need to write jsPsychHtmlKeyboardResponse as the trial type. var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; Next, we push the welcome trial to the timeline, which adds it to the end of the array. timeline . push ( welcome ); Finally, we tell jsPsych to run the experiment by calling the jsPsych.run() function and passing in the array that defines the experiment timeline. jsPsych . run ( timeline ); After each step in the tutorial you can view the complete code up to that point by clicking on the expandable box below. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 2: Display welcome message"},{"location":"tutorials/rt-task/#part-3-show-instructions","text":"We can use the same basic structure from part 2 to create a new html-keyboard-response trial that shows instructions to the participant. The only difference in this trial is that we will use HTML formatting to control how the instructions display and we will add a two second gap after the trial using the post_trial_gap parameter. The trial definition looks like this: var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; Tip In JavaScript there are three different ways to define a string . You can use single quotes ' , double quotes \" , or backticks ` . Using backticks has two advantages over the other approaches, especially when you are creating long strings with HTML. You can extend the string across multiple lines and you can use template strings to easily incorporate variables. Notice that the HTML includes <img> tags to display the images that the participant will be responding to. You'll need to download these image files. Right-click on each image below and select Save image as... . Put the images in a folder called img in the experiment folder you created in part 1. Don't forget to add the trial to the timeline: timeline . push ( instructions ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 3: Show instructions"},{"location":"tutorials/rt-task/#part-4-displaying-stimuli-and-getting-responses","text":"Creating trials to show the stimuli is conceptually the same as creating a trial to show instructions, except that now we are displaying an image instead of text or html. This means we need to use a different plugin: image-keyboard-response . We need to start by loading this plugin by adding a <script> tag to the document. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > For now, we will just show each image once. The path to the image file should be set as the stimulus parameter. We will also set the option for which keys the participant is allowed to use to respond ( choices ) so that only the 'f' and 'j' keys are valid responses. var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; As usual, we need to add the trials to the timeline. timeline . push ( blue_trial , orange_trial ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 4: Displaying stimuli and getting responses"},{"location":"tutorials/rt-task/#part-5-preloading-media","text":"Whenever we use media elements (images, audio, or video) in an experiment it is a good idea to preload them prior to needing them for a trial. By preloading media we ask the participant's browser to download the media ahead of needing it, so that when we do need to display or play it there is no lag from needing to download it. We are going to use the preload plugin to preload the two images. The media preloading section goes into a lot of detail about various options for preloading and different ways that you can use this plugin. Here we are simply going to give the plugin a list of the files that we want to be preloaded. First we need to add the preload plugin to our <head> section. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > We'll put this trial at the very start of the experiment, so add this code before the welcome trial. var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; As always, add the trial to the timeline. timeline . push ( preload ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 5: Preloading media"},{"location":"tutorials/rt-task/#part-6-timeline-variables","text":"In the full experiment, we will want more than two trials. One way we could do this is to create many more objects that define trials and push them all onto the timeline, but there is a more efficient way: using timeline variables. The parameters for showing the blue and orange circle are very similar. The only difference is which image is displayed. Timeline variables allow us to define the procedure for showing the stimulus once, and then repeatedly use it with different variables. We'll see how, even in this relatively simple case, this can save us a lot of lines of code. To start, let's make an array that contains all the different trials we want to run in the test phase. There are only two for the experiment: blue trials and orange trials. var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; Instead of just showing the blue and orange circles, let's also set up the experiment to show a fixation cross (+) in between trials. We can define a trial to show the fixation cross for a fixed amount of time by using the trial_duration parameter of the html-keyboard-response plugin and setting the choices parameter to the special value \"NO_KEYS\" , which means that no responses will be accepted as a valid response and the trial will last however long the trial_duration parameter specifies. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; To show the circles, we'll set up another trial with the image-keyboard-response plugin, but we'll use the function jsPsych.timelineVariable() to indicate that we want jsPsych to substitute the value of the parameter in from the timeline variables. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] } To link the variables that we declared in the test_stimuli array with the call to jsPsych.timelineVariable() we need to create a new timeline and set the timeline_variables property: var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli } We have to add the test_procedure to the main timeline array, but the fixation and test trial do not need to be added to timeline because they already exist on the test_procedure timeline. timeline . push ( test_procedure ); What happens when the experiment reaches the test procedure? jsPsych will run the test_procedure timeline one time for each entry in the test_stimuli array (two times total, in this case). The first time through, jsPsych will substitute the timeline variables from the first array entry (blue image), and the second time through the second array entry will be used (orange image). Notice that the fixation trial occurs before both the orange and the blue circles, because the entire timeline of the test_procedure is repeated for each entry in the timeline_variables array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 6: Timeline variables"},{"location":"tutorials/rt-task/#part-7-parameters-for-timelines-with-timeline-variables","text":"Right now our experiment is a measly two trials long. Even worse is that the order of the stimuli is the same every time! When we use timeline variables, we get access to some methods to randomize the order and repeat the trials. To randomize the order, simply set randomize_order: true on the object with the timeline_variables : var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true }; We can also easily make the test phase longer by setting the repetitions parameter. This parameter controls how many times the experiment will loop through all of the entries in the timeline_variables array. For example, if we set repetitions: 5 , then the experiment will loop through the two entries in the timeline_variables 5 times, for a total of 10 test trials. var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; Info: Randomizing timeline variables In a timeline variables procedure, when randomize_order is true and repetitions is greater than 1, the trial order will be re-randomized on each repetition through the timeline_variables array. This means that there will be some constraints on the randomization of all trials in the procedure. For example, if a timeline_variables array contains one trial per stimulus, then the same stimulus could occur twice in a row (since it could be at the end of one repetition and the start of the next one), but it could not be repeated more than twice in a row, regardless of the number of repetitions . If you want to repeat your timeline_variables array but randomize across all trials, you could use the sample parameter with the fixed-repetitions option: this will combine all the repeitions of your timeline_variables array into one larger array, and then randomize the whole thing. You can read more about the randomization, repetition, and sampling options for timeline variables in the Timeline Variables documentation . The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 7: Parameters for timelines with timeline variables"},{"location":"tutorials/rt-task/#part-8-using-functions-to-generate-parameters","text":"One aspect of the experiment that could be improved is the duration of the fixation cross. As the experiment stands right now, the timing of the circles appearing is very predictable. We can change that by using a different value for the trial_duration parameter in the fixation trial for each trial. But how can we do that and keep the simple code structure we have now where we only have to define the fixation trial once? One option would be to add another timeline variable, like \"fixation_duration\" and use that to control the timing. But another option is to specify the trial_duration parameter as a function. If a parameter is a function, jsPsych will execute the function every time the trial runs. That means that if the function returns different results probabilistically, we can get a different parameter value every time the trial runs. To do that here, we'll use one of the built-in randomization methods in jsPsych's randomization module . jsPsych.randomization.sampleWithoutReplacement() takes an array of items to sample from and generates a new array of length N by sampling without replacement. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } } In the code above, we replaced the trial_duration: 1000 parameter in fixation with a function. Inside the function, we take a sample from the array [250, 500, 750, 1000, 1250, 1500, 1750, 2000] of size 1 (second parameter to jsPsych.randomization.sampleWithoutReplacement ). The return value from calling jsPsych.randomization.sampleWithoutReplacement is an array of length 1, so we add the [0] selection at the end to get the value out of the array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 8: Using functions to generate parameters"},{"location":"tutorials/rt-task/#part-10-displaying-the-data","text":"We have created a complete, if simple, experiment at this point, so let's take a look at the data being generated. jsPsych has a built-in function called jsPsych.data.displayData() that is useful for debugging your experiment. It will remove all of the information on the screen and replace it with the raw data collected so far. This isn't terribly useful when you are actually running an experiment, but it's nice for checking the data during development. We need the displayData function to execute when the experiment ends. One way to do this is to use the on_finish callback function . This function will automatically execute once all the trials in the experiment are finished. We can specify this function in the experiment settings when we initialize jsPsych with the initJsPsych method. var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 10: Displaying the data"},{"location":"tutorials/rt-task/#part-11-tagging-trials-with-additional-data","text":"All trials in jsPsych can be tagged with additional arbitrary data. This data will get stored alongside the data that the plugin normally generates, which allows experimenters to record properties of a trial along with the data from the trial. When might you use this feature? In this experiment, it would be nice to tag each trial with a circle as a response trial, so that the resulting data can be easily filtered to look at only the critical trials. We can do that like this. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' } }; We also could tag the test trials with a property that indicates what the correct response should be (F for the blue circles, J for the orange). In our current code, we are using the timeline variables feature of jsPsych to choose which circle gets presented on a trial. Since we want to tag the trials differently based on which circle is presented, we need to add the tagging data to the test_stimuli array, and then use the jsPsych.timelineVariable() function to get the value and assign it to a property in the data of the trial. We start by adding a \"correct_response\" property and value to each object in the test_stimuli : var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; Now we can use timelineVariable() in the data parameter of the test trial to get the appropriate \"correct_response\" value for each trial. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; Another kind of tagging that would be useful is to mark each fixation trial as such, to make removing the data from fixation trials easier. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 11: Tagging trials with additional data"},{"location":"tutorials/rt-task/#part-12-manipulating-data-during-the-experiment","text":"Now that the data from the test trials has a tag that describes the correct response, it would be easy to analyze the data after the fact and calculate whether the participant responded correctly. But, we can also do this in jsPsych as the experiment runs to save time later and enable a limited set of data analysis directly in the experiment code. To do this, we'll use the on_finish event of the test trial. We can assign a function to on_finish , and that function will receive an object containing the data generated by the trial. This object can be manipulated inside the function, and any changes made to the object will be stored in jsPsych's internal representation of the data. For this example, we'll determine whether the participant responded correctly, and add a new correct property to the data object. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; The data.response value is a string representation of the key the participant pressed. We can compare this with the data.correct_response value, and assign this computed value to a new property data.correct . Info: The compareKeys function Here we are comparing the values of data.response and data.correct_response using a jsPsych function called jsPsych.pluginAPI.compareKeys . We're using this function because it allows us to compare keys in either a case sensitive or case insensitive way, depending on the case_sensitive_responses parameter in the experiment settings . The participant's key response will be recorded in a case-sensitive way in the data (e.g. 'f' or 'F'), but in most cases, we don't care if their response corresponds to an upper or lower case letter (which is why the case_sensitive_responses experiment setting is false by default). Using the jsPsych.pluginAPI.commpareKeys function here means that the response will be scored correctly, even if the participant holds down Shift or has Caps Lock on. This function is only relevant for keyboard responses; for other kinds of responses, such as button presses, you can simply compare the response and correct response values directly, e.g. data . correct = data . response === data . correct_response ; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 12: Manipulating data during the experiment"},{"location":"tutorials/rt-task/#part-13-data-aggregation","text":"jsPsych provides a limited set of analysis functions to allow you to calculate things like mean response times for a selected set of trials. In this part, we'll use these functions to add a final trial to the experiment that tells the participant their accuracy and their mean response time for correct responses. We'll use the html-keyboard-response plugin. Because the text that we want to display changes based on the participant's performance in the experiment, we need to use a function for the stimulus parameter and return the desired text. Info: Dynamic parameters Using a function as the value of a 'normal' parameter (i.e. a parameter that isn't usually a function) provides lots of flexibility in jsPsych experiments, because it allows you to dynamically change the parameter's value based on the participant's earlier responses, and any other information that you don't know before the experiment has started. For more information and examples, see the dynamic parameter documentation page . Here's what the code looks like, and a description follows below. var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); To create the variable trials , we use jsPsych.data.get() which returns a jsPsych data collection containing all of the data from the experiment. We can then use .filter to select only the trials where task is 'response' (a benefit of tagging the trials in part 11). trials contains all of the data from the trials where a circle was shown. To get only the correct trials, we can use .filter() again to select only the trials from the trials data collection where the property correct is true . To calculate accuracy, we can use the .count() method to determine how many trials were correct and how many trials there were total. We also use Math.round() to avoid extra digits after the decimal. Finally, to calculate the mean response time on correct trials, we use the .select method on the correct_trials data collection to select only the 'rt' property of those trials. We can then use the .mean() method to find the mean of all the RT values.","title":"Part 13: Data aggregation"},{"location":"tutorials/rt-task/#the-final-code","text":"This code is available in the /examples folder in the jsPsych release download. It is called demo-simple-rt-task.html . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , repetitions : 5 , randomize_order : true }; timeline . push ( test_procedure ); /* define debrief */ var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"The final code"},{"location":"tutorials/video-tutorials/","text":"Video tutorials \u00b6 Warning Most of these videos are using version 6.x of jsPsych. Using version 7.x requires a few changes that are not covered in these videos. We recommend starting with the tutorials on this website to understand how to work with 7.x and then watching these videos for additional information. Much of the content covered in the videos still applies to 7.x , but you'll need a solid understanding of how to use 7.x in order to make use of the examples in the videos. YouTube Channel \u00b6 A variety of video tutorials are available on Josh de Leeuw's YouTube channel . Some tutorials walk through creating a basic version of an entire experiment, like the tutorial on creating a dichotic listening experiment aimed at new users. Others focus on specific features of jsPsych, like how to use functions as parameters to create experiments that change in response to participant input or how to create a new plugin . Workshops \u00b6 Moving Research Online (2020) . Recordings from a Summer 2020 workshop on conducting online research are available on the workshop's YouTube channel . Session 1 provides an overview of jsPsych suitable for brand new users. Session 3 covers some more advanced features of jsPsych. This workshop was funded by the National Science Foundation. babySTEP (2021) . The Centre for Comparative Psycholinguistics (CCP, University of Alberta Department of Linguistics) hosted a two-part jsPsych workshop in 2021 as part of their annual STEP program . Day 1 covered the basics of creating a jsPsych experiment, with an emphasis on audio stimuli. Day 2 was organized around pre-submitted questions. The video demonstrates how to create a more complex experiment involving reading a sentence and hearing different audio options for completing the sentences, and answers several questions about timing accuracy, recording participant generated audio, embedding jsPsych into course (or other) websites, and some (non-empirical) advice about attention checks.","title":"Video Tutorials"},{"location":"tutorials/video-tutorials/#video-tutorials","text":"Warning Most of these videos are using version 6.x of jsPsych. Using version 7.x requires a few changes that are not covered in these videos. We recommend starting with the tutorials on this website to understand how to work with 7.x and then watching these videos for additional information. Much of the content covered in the videos still applies to 7.x , but you'll need a solid understanding of how to use 7.x in order to make use of the examples in the videos.","title":"Video tutorials"},{"location":"tutorials/video-tutorials/#youtube-channel","text":"A variety of video tutorials are available on Josh de Leeuw's YouTube channel . Some tutorials walk through creating a basic version of an entire experiment, like the tutorial on creating a dichotic listening experiment aimed at new users. Others focus on specific features of jsPsych, like how to use functions as parameters to create experiments that change in response to participant input or how to create a new plugin .","title":"YouTube Channel"},{"location":"tutorials/video-tutorials/#workshops","text":"Moving Research Online (2020) . Recordings from a Summer 2020 workshop on conducting online research are available on the workshop's YouTube channel . Session 1 provides an overview of jsPsych suitable for brand new users. Session 3 covers some more advanced features of jsPsych. This workshop was funded by the National Science Foundation. babySTEP (2021) . The Centre for Comparative Psycholinguistics (CCP, University of Alberta Department of Linguistics) hosted a two-part jsPsych workshop in 2021 as part of their annual STEP program . Day 1 covered the basics of creating a jsPsych experiment, with an emphasis on audio stimuli. Day 2 was organized around pre-submitted questions. The video demonstrates how to create a more complex experiment involving reading a sentence and hearing different audio options for completing the sentences, and answers several questions about timing accuracy, recording participant generated audio, embedding jsPsych into course (or other) websites, and some (non-empirical) advice about attention checks.","title":"Workshops"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"\u00b6 jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. Experiments in jsPsych are created using plugins . Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. You can use the plugins that are included with jsPsych , use plugins that are developed by community members in the contrib repository , or create your own plugins . By assembling different plugins together into a timeline , it is possible to create a wide range of experiments. The page on timelines is a good place to start learning about jsPsych. From there, you might want to complete the hello world tutorial to learn how to set up a jsPsych experiment and the reaction time experiment tutorial to learn the core features of the framework.","title":"Introduction"},{"location":"#_1","text":"jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. Experiments in jsPsych are created using plugins . Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. You can use the plugins that are included with jsPsych , use plugins that are developed by community members in the contrib repository , or create your own plugins . By assembling different plugins together into a timeline , it is possible to create a wide range of experiments. The page on timelines is a good place to start learning about jsPsych. From there, you might want to complete the hello world tutorial to learn how to set up a jsPsych experiment and the reaction time experiment tutorial to learn the core features of the framework.","title":""},{"location":"about/about/","text":"About jsPsych \u00b6 jsPsych is open source project with numerous contributors . The project is currently managed by the core team of Josh de Leeuw ( @jodeleeuw ), Becky Gilbert ( @becky-gilbert ), and Bj\u00f6rn Luchterhandt ( @bjoluc ). jsPsych was created by Josh de Leeuw . Citation \u00b6 If you use jsPsych please cite the following paper. de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. Behavior Research Methods , 47 (1), 1-12. doi:10.3758/s13428-014-0458-y .","title":"About jsPsych"},{"location":"about/about/#about-jspsych","text":"jsPsych is open source project with numerous contributors . The project is currently managed by the core team of Josh de Leeuw ( @jodeleeuw ), Becky Gilbert ( @becky-gilbert ), and Bj\u00f6rn Luchterhandt ( @bjoluc ). jsPsych was created by Josh de Leeuw .","title":"About jsPsych"},{"location":"about/about/#citation","text":"If you use jsPsych please cite the following paper. de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. Behavior Research Methods , 47 (1), 1-12. doi:10.3758/s13428-014-0458-y .","title":"Citation"},{"location":"about/license/","text":"License \u00b6 jsPsych is licensed under the MIT license. The MIT License (MIT) Copyright (c) 2014-2022 Joshua R. de Leeuw Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","title":"License"},{"location":"about/license/#license","text":"jsPsych is licensed under the MIT license. The MIT License (MIT) Copyright (c) 2014-2022 Joshua R. de Leeuw Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","title":"License"},{"location":"developers/configuration/","text":"Configuring the jsPsych development environment \u00b6 Setup \u00b6 JsPsych is written using TypeScript , a superset of JavaScript that adds static typing, but compiles to plain JavaScript. The TypeScript compiler itself is written in JavaScript and can be run by Node.js , a runtime to execute JavaScript code without a web browser. Node.js comes with a package manager called NPM (Node Package Manager) that can install JavaScript libraries to run on your machine, such as TypeScript and other build tools for jsPsych. In order to work on code in the jsPsych or the jspsych-contrib repository, it is recommended that you follow the steps below to set up your development environment. Install Node.js \u00b6 The jsPsych development setup requires Node.js >= v14 to be installed on your machine. We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use). If you are bound to Node.js v14, make sure to install NPM v7 manually (via npm install -g npm@7 ). Clone the repository and install the dependencies \u00b6 Clone either the jsPsych repository or the jspsych-contrib repository by running git clone https://github.com/jspsych/jsPsych.git && cd jsPsych or git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib in a terminal. Then run npm install . This will create a node_modules directory and install all the dependencies into it that are required to build and test jsPsych. Attention It is important that npm install is only run in the root directory of the repository (due to the NPM workspaces feature). If you accidentally ran npm install anywhere else, remove the node_modules directory and the package-lock.json file that were created at that location and run npm install in the root directory again. Info If you are running npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository. This step may take a few minutes. If you would like to use that time efficiently, consider reading the following two sections to know what's happening. Repository structure \u00b6 A Node.js package is a directory that contains a package.json file describing it. Most importantly, a package.json file lists other packages that the package depends on. The jsPsych and jspsych-contrib repositories use NPM workspaces . That means, running npm install in the repository root will install the dependencies for all packages in the packages directory. The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package. These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg ). Build chain and build artifacts \u00b6 JsPsych comes with a build chain (specified in the @jspsych/config package) that can be executed by running npm run build in a package's directory. The build chain will read the package (starting at its src/index.ts file) and create the following build artifacts in the package's dist directory: index.js This file contains everything from index.ts , but as plain JavaScript and bundled in a single file (i.e. without import ing files from the same package). It is used by bundlers like webpack . index.cjs Like index.js , but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework. index.browser.js This file, like index.js , contains the entire package as plain JavaScript, but this time wrapped in a function so that it can be included directly by browsers using the <script> tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after export default in the index.ts file) is assigned to a global variable. The name of this global variable is specified in the package's rollup.config.mjs file, as a parameter to the makeRollupConfig() function. Hence, for instance, including the index.browser.js file from the plugin-html-keyboard-response package would assign the HtmlKeyboardResponsePlugin class to the global jsPsychHtmlKeyboardResponse variable. Because the code in index.browser.js looks very similar to the index.ts code but is fully supported by modern web browsers, all examples in the examples directory reference the index.browser.js files so users can also modify the source code directly without running the build chain. index.browser.min.js There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features. That's why the jsPsych build chain uses Babel to translate the source files into code that a majority of web browsers can understand. The result of this operation is index.browser.min.js . It behaves just like index.browser.js , but adds support for older browsers by substituting new JavaScript features using older ones. Because this is the recommended build artifact for production usage (and is automatically served by unpkg), the code in index.browser.min.js is also processed by Terser to reduce its size and speed up experiment loading times. *.js.map When debugging code in a browser (especially index.browser.min.js , which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a .map file which contains a mapping of the generated code to the original source code. Browsers automatically read these .map files and display the original code in their debuggers instead of the generated one. *.d.ts The .d.ts files contain the TypeScript type definitions that would otherwise be lost during compilation to plain JavaScript. They are read by Typescript and editors when a package is imported into another TypeScript project. Testing \u00b6 Automated code testing for jsPsych is implemented with Jest . To run the tests, install Node and npm. Run npm install in the root jsPsych directory. Then run npm test . You can also run npm test in the directory of the package that you would like to test. For example, if you are developing tests for the html-keyboard-response plugin you can run npm test in /packages/plugin-html-keyboard-response . If you want to run one file from the root directory, using the aforementioned example, you can run npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts . Tests for the core jsPsych library are located in /packages/jspsych/tests . Tests for plugins and extensions are located in the /src folder of the corresponding package. Test files for plugins and extensions are named index.spec.ts . There are helper functions for testing in /packages/jspsych/tests/utils.ts . We recommend looking at other test files to observe conventions for testing.","title":"Configuration"},{"location":"developers/configuration/#configuring-the-jspsych-development-environment","text":"","title":"Configuring the jsPsych development environment"},{"location":"developers/configuration/#setup","text":"JsPsych is written using TypeScript , a superset of JavaScript that adds static typing, but compiles to plain JavaScript. The TypeScript compiler itself is written in JavaScript and can be run by Node.js , a runtime to execute JavaScript code without a web browser. Node.js comes with a package manager called NPM (Node Package Manager) that can install JavaScript libraries to run on your machine, such as TypeScript and other build tools for jsPsych. In order to work on code in the jsPsych or the jspsych-contrib repository, it is recommended that you follow the steps below to set up your development environment.","title":"Setup"},{"location":"developers/configuration/#install-nodejs","text":"The jsPsych development setup requires Node.js >= v14 to be installed on your machine. We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use). If you are bound to Node.js v14, make sure to install NPM v7 manually (via npm install -g npm@7 ).","title":"Install Node.js"},{"location":"developers/configuration/#clone-the-repository-and-install-the-dependencies","text":"Clone either the jsPsych repository or the jspsych-contrib repository by running git clone https://github.com/jspsych/jsPsych.git && cd jsPsych or git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib in a terminal. Then run npm install . This will create a node_modules directory and install all the dependencies into it that are required to build and test jsPsych. Attention It is important that npm install is only run in the root directory of the repository (due to the NPM workspaces feature). If you accidentally ran npm install anywhere else, remove the node_modules directory and the package-lock.json file that were created at that location and run npm install in the root directory again. Info If you are running npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository. This step may take a few minutes. If you would like to use that time efficiently, consider reading the following two sections to know what's happening.","title":"Clone the repository and install the dependencies"},{"location":"developers/configuration/#repository-structure","text":"A Node.js package is a directory that contains a package.json file describing it. Most importantly, a package.json file lists other packages that the package depends on. The jsPsych and jspsych-contrib repositories use NPM workspaces . That means, running npm install in the repository root will install the dependencies for all packages in the packages directory. The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package. These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg ).","title":"Repository structure"},{"location":"developers/configuration/#build-chain-and-build-artifacts","text":"JsPsych comes with a build chain (specified in the @jspsych/config package) that can be executed by running npm run build in a package's directory. The build chain will read the package (starting at its src/index.ts file) and create the following build artifacts in the package's dist directory: index.js This file contains everything from index.ts , but as plain JavaScript and bundled in a single file (i.e. without import ing files from the same package). It is used by bundlers like webpack . index.cjs Like index.js , but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework. index.browser.js This file, like index.js , contains the entire package as plain JavaScript, but this time wrapped in a function so that it can be included directly by browsers using the <script> tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after export default in the index.ts file) is assigned to a global variable. The name of this global variable is specified in the package's rollup.config.mjs file, as a parameter to the makeRollupConfig() function. Hence, for instance, including the index.browser.js file from the plugin-html-keyboard-response package would assign the HtmlKeyboardResponsePlugin class to the global jsPsychHtmlKeyboardResponse variable. Because the code in index.browser.js looks very similar to the index.ts code but is fully supported by modern web browsers, all examples in the examples directory reference the index.browser.js files so users can also modify the source code directly without running the build chain. index.browser.min.js There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features. That's why the jsPsych build chain uses Babel to translate the source files into code that a majority of web browsers can understand. The result of this operation is index.browser.min.js . It behaves just like index.browser.js , but adds support for older browsers by substituting new JavaScript features using older ones. Because this is the recommended build artifact for production usage (and is automatically served by unpkg), the code in index.browser.min.js is also processed by Terser to reduce its size and speed up experiment loading times. *.js.map When debugging code in a browser (especially index.browser.min.js , which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a .map file which contains a mapping of the generated code to the original source code. Browsers automatically read these .map files and display the original code in their debuggers instead of the generated one. *.d.ts The .d.ts files contain the TypeScript type definitions that would otherwise be lost during compilation to plain JavaScript. They are read by Typescript and editors when a package is imported into another TypeScript project.","title":"Build chain and build artifacts"},{"location":"developers/configuration/#testing","text":"Automated code testing for jsPsych is implemented with Jest . To run the tests, install Node and npm. Run npm install in the root jsPsych directory. Then run npm test . You can also run npm test in the directory of the package that you would like to test. For example, if you are developing tests for the html-keyboard-response plugin you can run npm test in /packages/plugin-html-keyboard-response . If you want to run one file from the root directory, using the aforementioned example, you can run npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts . Tests for the core jsPsych library are located in /packages/jspsych/tests . Tests for plugins and extensions are located in the /src folder of the corresponding package. Test files for plugins and extensions are named index.spec.ts . There are helper functions for testing in /packages/jspsych/tests/utils.ts . We recommend looking at other test files to observe conventions for testing.","title":"Testing"},{"location":"developers/contributing/","text":"Contributing to jsPsych \u00b6 We welcome contributions of all kinds, including changes to the core codebase, the development of new plugins and extensions, and improvements to the documentation. The project is managed entirely through the GitHub repository . There you can: Use discussions to propose ideas for development and seek feedback on contributions, such as a new plugin. Use issues to identify anything with an actionable next step. For example, a page in the documentation that needs to be fixed, a bug in the code, or a specific feature that has a clear scope. Submit a pull request with modifications to the codebase. Pull requests will be reviewed by one or more members of the core team. Guidelines for contibuting \u00b6 Contributing to the codebase \u00b6 We welcome contributions of any scope. Before we can merge changes into the main codebase, we generally require a few things. Note that you are welcome to contribute code without these things in place, but it will help us get to your contribution faster if you take care of whatever components you are comfortable doing. The code must be tested through our automated testing system. We use Jest as the testing framework. If you are fixing a bug, consider adding a test case that shows the bug has been resolved. If you are contributing new features, like a new plugin, a test suite for the plugin is very helpful. See testing jsPsych for more information about configuring the test tools and writing tests. Relevant documentation must be updated. Any pages in /docs that are affected by the contribution should be updated, and if new pages are needed they should be created. For example, if you are contributing a plugin then adding documentation for the plugin and updating the list of available plugins as well as the mkdocs configuration file is very helpful! An example file should be included if applicable. If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the /examples folder in the repository. A changeset must be included in the pull request . We use changesets to generate new releases and their corresponding release notes. This is a good overview of changesets that explains how to add one to your pull request. Feel free to ask for help with this! Update the contributors.md file . If you are a first time contributor to jsPsych please add your name to our contributors file . And thanks! Contributing to the documentation \u00b6 We are very appreciative of both small and large contributions to the documentation, from fixing a typo to adding a whole new tutorial. All of the documentation that appears on this site is contained in the /docs folder of the repository. The documentation is built using MkDocs and themed using Material for MkDocs . You can edit any of the markdown files and submit a pull request to modify documentation. If you'd like to test your changes to the documentation locally you'll need to install MkDocs and Material for MkDocs . Then you can run the command mike serve in the root folder of the repository to launch a local webserver and view the documentation. Contributing to jspsych vs. jspsych-contrib \u00b6 If you are developing a new plugin or extension there are two different repositories that you can contribute to: jspsych or jspsych-contrib . The main jspsych repository is open to new plugins and extensions that are likely to be widely used. We require that contributions to main repository are well documented and tested before they are merged. Contributions to the main repository must use TypeScript. We limit contributions to this repository because once a plugin or extension is in the main codebase we are generally committed to providing updates as we develop new versions of jsPsych. Each new plugin and extension potentially increases the amount of development work that we will need to do in the future, so we are somewhat selective about what we will merge. If you have an idea that you'd like to discuss please open a discussion thread and we'd love to chat about it! The jspsych-contrib repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our TypeScript template or using our JavaScript template . Contributions to jspsych-contrib are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from jspsych-contrib based on their popularity and completeness (documentation and testing).","title":"Contributing to jsPsych"},{"location":"developers/contributing/#contributing-to-jspsych","text":"We welcome contributions of all kinds, including changes to the core codebase, the development of new plugins and extensions, and improvements to the documentation. The project is managed entirely through the GitHub repository . There you can: Use discussions to propose ideas for development and seek feedback on contributions, such as a new plugin. Use issues to identify anything with an actionable next step. For example, a page in the documentation that needs to be fixed, a bug in the code, or a specific feature that has a clear scope. Submit a pull request with modifications to the codebase. Pull requests will be reviewed by one or more members of the core team.","title":"Contributing to jsPsych"},{"location":"developers/contributing/#guidelines-for-contibuting","text":"","title":"Guidelines for contibuting"},{"location":"developers/contributing/#contributing-to-the-codebase","text":"We welcome contributions of any scope. Before we can merge changes into the main codebase, we generally require a few things. Note that you are welcome to contribute code without these things in place, but it will help us get to your contribution faster if you take care of whatever components you are comfortable doing. The code must be tested through our automated testing system. We use Jest as the testing framework. If you are fixing a bug, consider adding a test case that shows the bug has been resolved. If you are contributing new features, like a new plugin, a test suite for the plugin is very helpful. See testing jsPsych for more information about configuring the test tools and writing tests. Relevant documentation must be updated. Any pages in /docs that are affected by the contribution should be updated, and if new pages are needed they should be created. For example, if you are contributing a plugin then adding documentation for the plugin and updating the list of available plugins as well as the mkdocs configuration file is very helpful! An example file should be included if applicable. If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the /examples folder in the repository. A changeset must be included in the pull request . We use changesets to generate new releases and their corresponding release notes. This is a good overview of changesets that explains how to add one to your pull request. Feel free to ask for help with this! Update the contributors.md file . If you are a first time contributor to jsPsych please add your name to our contributors file . And thanks!","title":"Contributing to the codebase"},{"location":"developers/contributing/#contributing-to-the-documentation","text":"We are very appreciative of both small and large contributions to the documentation, from fixing a typo to adding a whole new tutorial. All of the documentation that appears on this site is contained in the /docs folder of the repository. The documentation is built using MkDocs and themed using Material for MkDocs . You can edit any of the markdown files and submit a pull request to modify documentation. If you'd like to test your changes to the documentation locally you'll need to install MkDocs and Material for MkDocs . Then you can run the command mike serve in the root folder of the repository to launch a local webserver and view the documentation.","title":"Contributing to the documentation"},{"location":"developers/contributing/#contributing-to-jspsych-vs-jspsych-contrib","text":"If you are developing a new plugin or extension there are two different repositories that you can contribute to: jspsych or jspsych-contrib . The main jspsych repository is open to new plugins and extensions that are likely to be widely used. We require that contributions to main repository are well documented and tested before they are merged. Contributions to the main repository must use TypeScript. We limit contributions to this repository because once a plugin or extension is in the main codebase we are generally committed to providing updates as we develop new versions of jsPsych. Each new plugin and extension potentially increases the amount of development work that we will need to do in the future, so we are somewhat selective about what we will merge. If you have an idea that you'd like to discuss please open a discussion thread and we'd love to chat about it! The jspsych-contrib repository is open to any contributions that are complete and working code. There are some minimal guidelines in place about basic documentation that should be provided. Contributors can choose whether to develop their plugin or extension using our TypeScript template or using our JavaScript template . Contributions to jspsych-contrib are not evaluated for general usefulness in the same way that contributions to the main repository are. We also periodically consider whether to move contributions into the main repository from jspsych-contrib based on their popularity and completeness (documentation and testing).","title":"Contributing to jspsych vs. jspsych-contrib"},{"location":"developers/documentation/","text":"Building the jsPsych documentation \u00b6 The documentation hosted at https://www.jspsych.org is generated using mkdocs and the mkdocs-material theme . The documentation files are located in the /docs directory of the GitHub repository . The documentation is written using markdown. To build a local copy of the docs, you will need to install mkdocs , mkdocs-material , and mike using poetry . Install poetry \u00b6 Poetry is a package manager for python. Follow the install instructions on the poetry website to get it running. Install dev dependencies \u00b6 Run the command poetry install in the root directory of jsPsych to install mkdocs , mkdocs-material , and their dependencies. Building a local copy of the docs \u00b6 Run poetry run mike deploy [version] -u to build a new version of the documentation or to override an existing version. For example, if you are testing an edit to version 7.2 of the documentation, run poetry run mike deploy 7.2 -u . You can also use jsPsych's custom npm command: npm run docs:deploy [version] , e.g. npm run docs:deploy 7.2 . This will build the documentation and commit it directly to the gh-pages branch. We use mike instead of mkdocs for the build step to support versioning of the documentation. mike runs the mkdocs command under the hood. Viewing the local docs \u00b6 To launch a local webserver, run poetry run mike serve , or use jsPsych's custom npm command: npm run docs:serve . The docs will be viewable at http://localhost:8000 . Updating the public docs site \u00b6 For core maintainers only After the documentation has been built locally (and therefore committed to your local gh-pages branch), you can update the live documentation site by switching to your gh-pages branch and pushing to the remote gh-pages branch.","title":"Building the Documentation"},{"location":"developers/documentation/#building-the-jspsych-documentation","text":"The documentation hosted at https://www.jspsych.org is generated using mkdocs and the mkdocs-material theme . The documentation files are located in the /docs directory of the GitHub repository . The documentation is written using markdown. To build a local copy of the docs, you will need to install mkdocs , mkdocs-material , and mike using poetry .","title":"Building the jsPsych documentation"},{"location":"developers/documentation/#install-poetry","text":"Poetry is a package manager for python. Follow the install instructions on the poetry website to get it running.","title":"Install poetry"},{"location":"developers/documentation/#install-dev-dependencies","text":"Run the command poetry install in the root directory of jsPsych to install mkdocs , mkdocs-material , and their dependencies.","title":"Install dev dependencies"},{"location":"developers/documentation/#building-a-local-copy-of-the-docs","text":"Run poetry run mike deploy [version] -u to build a new version of the documentation or to override an existing version. For example, if you are testing an edit to version 7.2 of the documentation, run poetry run mike deploy 7.2 -u . You can also use jsPsych's custom npm command: npm run docs:deploy [version] , e.g. npm run docs:deploy 7.2 . This will build the documentation and commit it directly to the gh-pages branch. We use mike instead of mkdocs for the build step to support versioning of the documentation. mike runs the mkdocs command under the hood.","title":"Building a local copy of the docs"},{"location":"developers/documentation/#viewing-the-local-docs","text":"To launch a local webserver, run poetry run mike serve , or use jsPsych's custom npm command: npm run docs:serve . The docs will be viewable at http://localhost:8000 .","title":"Viewing the local docs"},{"location":"developers/documentation/#updating-the-public-docs-site","text":"For core maintainers only After the documentation has been built locally (and therefore committed to your local gh-pages branch), you can update the live documentation site by switching to your gh-pages branch and pushing to the remote gh-pages branch.","title":"Updating the public docs site"},{"location":"developers/extension-development/","text":"Extension development \u00b6 Requirements for an extension \u00b6 As of version 7.0, extensions are JavaScript Classes . An extension must implement: A constructor() that accepts an instance of jsPsych. An initialize() function to handle the initialize event of the extension. An on_start() function to handle the on_start event of the extension. An on_load() function to handle the on_load event of the extension. An on_finish() function to handle the on_finish event of the extension and store data that the extension collects. A static info property containing a unique name for the extension. Templates \u00b6 Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository . Extension components \u00b6 constructor() \u00b6 The extension's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. class MyAwesomeExtension { constructor ( jsPsych ){ this . jsPsych = jsPsych ; } } initialize() \u00b6 The initialize() function is called when an instance of jsPsych is first initialized, either through initJsPsych() or new JsPsych() . This is where setup code for the extension should be run. This event will happen once per experiment, unlike the other events which occur with each trial. The params object can include whatever parameters are necessary to configure the extension. The params object is passed from the call to initJsPsych() to initialize() method. initialize() must return a Promise that resolves when the extension is finished initializing. //... experiment code ...// let jsPsych = initJsPsych ({ extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ return new Promise (( resolve , reject )=>{ console . log ( params . demo ); // will output 'value' resolve (); // finish initialzing }) } } on_start() \u00b6 on_start() is called at the start of the plugin execution, prior to calling plugin.trial . This is where trial-specific initialization can happen, such as creating empty containers to hold data or resetting internal state. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ console . log ( params . demo ); // outputs 'value' before the trial begins. } } on_load() \u00b6 on_load() is called after the on_load event for the plugin has completed, which is typically when the plugin has finished executing initial DOM-modifying code and has set up various event listeners. This is where the extension can begin actively interacting with the DOM and recording data. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ // replaces the contents of the display with 'value'; this . jsPsych . getDisplayElement (). innerHTML = params . demo ; } } on_finish() \u00b6 on_finish() is called after the plugin invokes jsPsych.finishTrial() . This can be used for any teardown at the end of the trial. This method should return an object of data to append to the plugin's data. Note that this event fires before the on_finish event for the plugin, so data added by the extension is accessible in any trial on_finish event handlers. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ], on_finish : ( data ) => { console . log ( data . awesome ); // will output 'value'. } }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ ... } on_finish ( params ){ return { awesome : params . value } } } static .info \u00b6 The info property for the class must contain an object with a name property that has a unique name for the extension. class MyAwesomeExtension { } MyAwesomeExtension . info = { name : 'awesome' } Optional methods \u00b6 The extension can also include any additional methods that are necessary for interacting with it. See the webgazer extension for an example. Advice for writing extensions \u00b6 If you are developing an extension with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . In general, extensions should be able to work with any plugin. They should make very few assumptions about what the DOM will contain beyond the container elements generated by jsPsych. If you are making an extension targeted at one or a small number of specific plugins, consider modifying the plugin code instead.","title":"Extension Development"},{"location":"developers/extension-development/#extension-development","text":"","title":"Extension development"},{"location":"developers/extension-development/#requirements-for-an-extension","text":"As of version 7.0, extensions are JavaScript Classes . An extension must implement: A constructor() that accepts an instance of jsPsych. An initialize() function to handle the initialize event of the extension. An on_start() function to handle the on_start event of the extension. An on_load() function to handle the on_load event of the extension. An on_finish() function to handle the on_finish event of the extension and store data that the extension collects. A static info property containing a unique name for the extension.","title":"Requirements for an extension"},{"location":"developers/extension-development/#templates","text":"Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository .","title":"Templates"},{"location":"developers/extension-development/#extension-components","text":"","title":"Extension components"},{"location":"developers/extension-development/#constructor","text":"The extension's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. class MyAwesomeExtension { constructor ( jsPsych ){ this . jsPsych = jsPsych ; } }","title":"constructor()"},{"location":"developers/extension-development/#initialize","text":"The initialize() function is called when an instance of jsPsych is first initialized, either through initJsPsych() or new JsPsych() . This is where setup code for the extension should be run. This event will happen once per experiment, unlike the other events which occur with each trial. The params object can include whatever parameters are necessary to configure the extension. The params object is passed from the call to initJsPsych() to initialize() method. initialize() must return a Promise that resolves when the extension is finished initializing. //... experiment code ...// let jsPsych = initJsPsych ({ extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ return new Promise (( resolve , reject )=>{ console . log ( params . demo ); // will output 'value' resolve (); // finish initialzing }) } }","title":"initialize()"},{"location":"developers/extension-development/#on_start","text":"on_start() is called at the start of the plugin execution, prior to calling plugin.trial . This is where trial-specific initialization can happen, such as creating empty containers to hold data or resetting internal state. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ console . log ( params . demo ); // outputs 'value' before the trial begins. } }","title":"on_start()"},{"location":"developers/extension-development/#on_load","text":"on_load() is called after the on_load event for the plugin has completed, which is typically when the plugin has finished executing initial DOM-modifying code and has set up various event listeners. This is where the extension can begin actively interacting with the DOM and recording data. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ] }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ // replaces the contents of the display with 'value'; this . jsPsych . getDisplayElement (). innerHTML = params . demo ; } }","title":"on_load()"},{"location":"developers/extension-development/#on_finish","text":"on_finish() is called after the plugin invokes jsPsych.finishTrial() . This can be used for any teardown at the end of the trial. This method should return an object of data to append to the plugin's data. Note that this event fires before the on_finish event for the plugin, so data added by the extension is accessible in any trial on_finish event handlers. The params object is passed from the declaration of the extension in the trial object. You can use params to customize the behavior of the extension for each trial. //... experiment code ...// let trial = { type : htmlKeyboardResponse , stimulus : \"You're awesome!\" , extensions : [ { type : myAwesomeExtension , params : { demo : 'value' }} ], on_finish : ( data ) => { console . log ( data . awesome ); // will output 'value'. } }); //... extension code ...// class MyAwesomeExtension { initialize ( params ){ ... } on_start ( params ){ ... } on_load ( params ){ ... } on_finish ( params ){ return { awesome : params . value } } }","title":"on_finish()"},{"location":"developers/extension-development/#static-info","text":"The info property for the class must contain an object with a name property that has a unique name for the extension. class MyAwesomeExtension { } MyAwesomeExtension . info = { name : 'awesome' }","title":"static .info"},{"location":"developers/extension-development/#optional-methods","text":"The extension can also include any additional methods that are necessary for interacting with it. See the webgazer extension for an example.","title":"Optional methods"},{"location":"developers/extension-development/#advice-for-writing-extensions","text":"If you are developing an extension with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . In general, extensions should be able to work with any plugin. They should make very few assumptions about what the DOM will contain beyond the container elements generated by jsPsych. If you are making an extension targeted at one or a small number of specific plugins, consider modifying the plugin code instead.","title":"Advice for writing extensions"},{"location":"developers/plugin-development/","text":"Plugin development \u00b6 Requirements for a plugin \u00b6 As of version 7.0, plugins are JavaScript Classes . A plugin must implement: A constructor() that accepts an instance of jsPsych. A trial() method that accepts an HTMLElement as its first argument and an object of trial parameters as its second argument. There is an optional third argument to handle the on_load event in certain cirumstances. The trial() method should invoke jsPsych.finishTrial() to end the trial and save data at the appropriate moment. A static info property on the class that contains an object describing the plugin's parameters. Templates \u00b6 Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository . Plugin components \u00b6 constructor() \u00b6 The plugin's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial() \u00b6 The plugin's trial() method is responsible for running a single trial. When the jsPsych timeline reaches a trial using the plugin it will invoke the trial() method for the plugin. There are three parameters that are passed into the trial method. display_element is the DOM element where jsPsych content is being rendered. This parameter will be an HTMLElement , and you can use it to modify the portion of the document that jsPsych controls. trial is an object containing all of the parameters specified in the corresponding TimelineNode . on_load is an optional parameter that contains a callback function to invoke when trial() has completed its initial loading. See handling the on_load event . The only requirement for the trial method is that it calls jsPsych.finishTrial() when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point. static info \u00b6 The plugin's info property is an object with a name and parameters property. const info = { name : 'my-awesome-plugin' , parameters : { } } The parameters property is an object containing all of the parameters for the plugin. Each parameter has a type and default property. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } If the default value is undefined then a user must specify a value for this parameter when creating a trial using the plugin on the timeline. If they do not, then an error will be generated and shown in the console. If a default value is specified in info then that value will be used by the plugin unless the user overrides it by specifying that property. jsPsych allows most plugin parameters to be dynamic , which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that shouldn't be evaluated before the trial starts, then you should make sure that the parameter type is 'FUNCTION' . This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the canvas-* plugins for examples. The info object should be a static member of the class, as shown below. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } class MyAwesomePlugin { constructor (...) trial (...) } MyAwesomePlugin . info = info ; Plugin functionality \u00b6 Inside the .trial() method you can do pretty much anything that you want, including modifying the DOM, setting up event listeners, and making asynchronous requests. In this section we'll highlight a few common things that you might want to do as examples. Changing the content of the display \u00b6 There are a few ways to change the content of the display. The display_element parameter of the trial method contains the HTMLElement for displaying jsPsych content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the innerHTML . Here's an example of using innerHTML to display an image specified in the trial parameters. trial ( display_element , trial ){ let html_content = `<img src=\" ${ trial . image } \"></img>` ; display_element . innerHTML = html_content ; } jsPsych doesn't clear the display before or after each trial, so it is usually appropriate to use innerHTML to clear the display at the end of a trial. display_element . innerHTML = '' ; Waiting for specified durations \u00b6 If you need to delay code execution for a fixed amount of time, we recommend using jsPsych's wrapper of the setTimeout() function, jsPsych.pluginAPI.setTimeout() . In 7.0 the only advantage of using this method is that it registers the timeout handler so that it can be easily cleared at the end of the trial using jsPsych.pluginAPI.clearAllTimeouts() . In future versions we may replace the implementation of jsPsych.pluginAPI.setTimeout() with improved timing functionality based on requestAnimationFrame . trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; // hide image after trial.image_duration milliseconds this . jsPsych . pluginAPI . setTimeout (()=>{ display_element . innerHTML = '' ; }, trial . image_duration ); } Responding to keyboard events \u00b6 While the plugin framework allows you to set up any events that you would like to, including normal handling of keyup or keydown events, the jsPsych.pluginAPI module contains the getKeyboardResponse function , which implements some additional helpful functionality for key responses in an experiment. Here's a basic example. See the getKeyboardResponse docs for additional examples. trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; const after_key_response = ( info ) => { // hide the image display_element . innerHTML = '' ; // record the response time as data let data = { rt : info . rt } // end the trial this . jsPsych . finishTrial ( data ); } // set up a keyboard event to respond only to the spacebar this . jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_key_response , valid_responses : [ ' ' ], persist : false }); } Asynchronous loading \u00b6 One of the trial events is on_load , which is normally triggered automatically when the .trial() method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the audio-keyboard-response plugin, in which the check to see if the audio file is loaded is asynchronous and the .trial() method returns before the audio file has been initialized and the display updated. If you would like to manually trigger the on_load event for a plugin, the .trial() method accepts an optional third parameter that is a callback function to invoke when loading is complete. In order to tell jsPsych to not invoke the regular callback when the .trial() method returns, you need to explicitly return a Promise . As of version 7.0 this Promise only serves as a flag to tell jsPsych that the on_load event should not be triggered. In future versions we may make the Promise functional so that the trial operation can be an async function. Here's a sketch of how the on_load event can be utilized in a plugin. Note that this example is only a sketch and leaves out all the stuff that happens between loading and finishing the trial. See the source for the audio-keyboard-response plugin for a complete exampe. trial ( display_element , trial , on_load ){ let trial_complete ; do_something_asynchronous (). then (()=>{ on_load (); }); const end_trial = () => { this . jsPsych . finishTrial ({...}) trial_complete (); // not strictly necessary, but doesn't hurt. } return new Promise (( resolve )=>{ trial_complete = resolve ; }) } Save data \u00b6 To write data to jsPsych's data collection pass an object of data as the parameter to jsPsych.finishTrial() . constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial ( display_element , trial ){ let data = { correct : true , rt : 350 } this . jsPsych . finishTrial ( data ); } The data recorded will be that correct is true and that rt is 350 . Additional data for the trial will also be collected automatically. Simulation mode \u00b6 Plugins can optionally support simulation modes . To add simulation support, a plugin needs a simulate() function that accepts four arguments simulate(trial, simulation_mode, simulation_options, load_callback) trial : This is the same as the trial parameter passed to the plugin's trial() method. It contains an object of the parameters for the trial. simulation_mode : A string, either \"data-only\" or \"visual\" . This specifies which simulation mode is being requested. Plugins can optionally support \"visual\" mode. If \"visual\" mode is not supported, the plugin should default to \"data-only\" mode when \"visual\" mode is requested. simulation_options : An object of simulation-specific options. load_callback : A function handle to invoke when the simulation is ready to trigger the on_load event for the trial. It is important to invoke this at the correct time during the simulation so that any on_load events in the experiment execute as expected. Typically the flow for supporting simulation mode involves: Generating artificial data that is consistent with the trial parameters. Merging that data with any data specified by the user in simulation_options . Verifying that the final data object is still consistent with the trial parameters. For example, checking that RTs are not longer than the duration of the trial. In data-only mode, call jsPsych.finishTrial() with the artificial data. In visual mode, invoke the trial() method of the plugin and then use the artificial data to trigger the appropriate events. There are a variety of methods in the Plugin API module to assist with things like simulating key presses and mouse clicks. We plan to add a longer guide about simulation development in the future. For now, we recommend browsing the source code of plugins that support simulation mode to see how the flow described above is implemented. Advice for writing plugins \u00b6 If you are developing a plugin with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . We also recommend that you make your plugin as general as possible . Consider using parameters to give the user of the plugin as many options for customization as possible. For example, if you have any text that displays in the plugin including things like button labels, implement the text as a parameter. This allows users running experiments in other languages to replace text values as needed.","title":"Plugin Development"},{"location":"developers/plugin-development/#plugin-development","text":"","title":"Plugin development"},{"location":"developers/plugin-development/#requirements-for-a-plugin","text":"As of version 7.0, plugins are JavaScript Classes . A plugin must implement: A constructor() that accepts an instance of jsPsych. A trial() method that accepts an HTMLElement as its first argument and an object of trial parameters as its second argument. There is an optional third argument to handle the on_load event in certain cirumstances. The trial() method should invoke jsPsych.finishTrial() to end the trial and save data at the appropriate moment. A static info property on the class that contains an object describing the plugin's parameters.","title":"Requirements for a plugin"},{"location":"developers/plugin-development/#templates","text":"Plugins can be written in either plain JavaScript or in TypeScript. Template files for both JavaScript and TypeScript are available in the jspsych-contrib repository .","title":"Templates"},{"location":"developers/plugin-development/#plugin-components","text":"","title":"Plugin components"},{"location":"developers/plugin-development/#constructor","text":"The plugin's constructor() will be passed a reference to the instance of the JsPsych class that is running the experiment. The constructor should store this reference so that the plugin can access functionality from the core library and its modules. constructor ( jsPsych ){ this . jsPsych = jsPsych ; }","title":"constructor()"},{"location":"developers/plugin-development/#trial","text":"The plugin's trial() method is responsible for running a single trial. When the jsPsych timeline reaches a trial using the plugin it will invoke the trial() method for the plugin. There are three parameters that are passed into the trial method. display_element is the DOM element where jsPsych content is being rendered. This parameter will be an HTMLElement , and you can use it to modify the portion of the document that jsPsych controls. trial is an object containing all of the parameters specified in the corresponding TimelineNode . on_load is an optional parameter that contains a callback function to invoke when trial() has completed its initial loading. See handling the on_load event . The only requirement for the trial method is that it calls jsPsych.finishTrial() when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point.","title":"trial()"},{"location":"developers/plugin-development/#static-info","text":"The plugin's info property is an object with a name and parameters property. const info = { name : 'my-awesome-plugin' , parameters : { } } The parameters property is an object containing all of the parameters for the plugin. Each parameter has a type and default property. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } If the default value is undefined then a user must specify a value for this parameter when creating a trial using the plugin on the timeline. If they do not, then an error will be generated and shown in the console. If a default value is specified in info then that value will be used by the plugin unless the user overrides it by specifying that property. jsPsych allows most plugin parameters to be dynamic , which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that shouldn't be evaluated before the trial starts, then you should make sure that the parameter type is 'FUNCTION' . This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the canvas-* plugins for examples. The info object should be a static member of the class, as shown below. const info = { name : 'my-awesome-plugin' , parameters : { image : { type : jspsych . ParameterType . IMAGE , default : undefined }, image_duration : { type : jspsych . ParameterType . INT , default : 500 } } } class MyAwesomePlugin { constructor (...) trial (...) } MyAwesomePlugin . info = info ;","title":"static info"},{"location":"developers/plugin-development/#plugin-functionality","text":"Inside the .trial() method you can do pretty much anything that you want, including modifying the DOM, setting up event listeners, and making asynchronous requests. In this section we'll highlight a few common things that you might want to do as examples.","title":"Plugin functionality"},{"location":"developers/plugin-development/#changing-the-content-of-the-display","text":"There are a few ways to change the content of the display. The display_element parameter of the trial method contains the HTMLElement for displaying jsPsych content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the innerHTML . Here's an example of using innerHTML to display an image specified in the trial parameters. trial ( display_element , trial ){ let html_content = `<img src=\" ${ trial . image } \"></img>` ; display_element . innerHTML = html_content ; } jsPsych doesn't clear the display before or after each trial, so it is usually appropriate to use innerHTML to clear the display at the end of a trial. display_element . innerHTML = '' ;","title":"Changing the content of the display"},{"location":"developers/plugin-development/#waiting-for-specified-durations","text":"If you need to delay code execution for a fixed amount of time, we recommend using jsPsych's wrapper of the setTimeout() function, jsPsych.pluginAPI.setTimeout() . In 7.0 the only advantage of using this method is that it registers the timeout handler so that it can be easily cleared at the end of the trial using jsPsych.pluginAPI.clearAllTimeouts() . In future versions we may replace the implementation of jsPsych.pluginAPI.setTimeout() with improved timing functionality based on requestAnimationFrame . trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; // hide image after trial.image_duration milliseconds this . jsPsych . pluginAPI . setTimeout (()=>{ display_element . innerHTML = '' ; }, trial . image_duration ); }","title":"Waiting for specified durations"},{"location":"developers/plugin-development/#responding-to-keyboard-events","text":"While the plugin framework allows you to set up any events that you would like to, including normal handling of keyup or keydown events, the jsPsych.pluginAPI module contains the getKeyboardResponse function , which implements some additional helpful functionality for key responses in an experiment. Here's a basic example. See the getKeyboardResponse docs for additional examples. trial ( display_element , trial ){ // show image display_element . innerHTML = `<img src=\" ${ trial . image } \"></img>` ; const after_key_response = ( info ) => { // hide the image display_element . innerHTML = '' ; // record the response time as data let data = { rt : info . rt } // end the trial this . jsPsych . finishTrial ( data ); } // set up a keyboard event to respond only to the spacebar this . jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_key_response , valid_responses : [ ' ' ], persist : false }); }","title":"Responding to keyboard events"},{"location":"developers/plugin-development/#asynchronous-loading","text":"One of the trial events is on_load , which is normally triggered automatically when the .trial() method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the audio-keyboard-response plugin, in which the check to see if the audio file is loaded is asynchronous and the .trial() method returns before the audio file has been initialized and the display updated. If you would like to manually trigger the on_load event for a plugin, the .trial() method accepts an optional third parameter that is a callback function to invoke when loading is complete. In order to tell jsPsych to not invoke the regular callback when the .trial() method returns, you need to explicitly return a Promise . As of version 7.0 this Promise only serves as a flag to tell jsPsych that the on_load event should not be triggered. In future versions we may make the Promise functional so that the trial operation can be an async function. Here's a sketch of how the on_load event can be utilized in a plugin. Note that this example is only a sketch and leaves out all the stuff that happens between loading and finishing the trial. See the source for the audio-keyboard-response plugin for a complete exampe. trial ( display_element , trial , on_load ){ let trial_complete ; do_something_asynchronous (). then (()=>{ on_load (); }); const end_trial = () => { this . jsPsych . finishTrial ({...}) trial_complete (); // not strictly necessary, but doesn't hurt. } return new Promise (( resolve )=>{ trial_complete = resolve ; }) }","title":"Asynchronous loading"},{"location":"developers/plugin-development/#save-data","text":"To write data to jsPsych's data collection pass an object of data as the parameter to jsPsych.finishTrial() . constructor ( jsPsych ){ this . jsPsych = jsPsych ; } trial ( display_element , trial ){ let data = { correct : true , rt : 350 } this . jsPsych . finishTrial ( data ); } The data recorded will be that correct is true and that rt is 350 . Additional data for the trial will also be collected automatically.","title":"Save data"},{"location":"developers/plugin-development/#simulation-mode","text":"Plugins can optionally support simulation modes . To add simulation support, a plugin needs a simulate() function that accepts four arguments simulate(trial, simulation_mode, simulation_options, load_callback) trial : This is the same as the trial parameter passed to the plugin's trial() method. It contains an object of the parameters for the trial. simulation_mode : A string, either \"data-only\" or \"visual\" . This specifies which simulation mode is being requested. Plugins can optionally support \"visual\" mode. If \"visual\" mode is not supported, the plugin should default to \"data-only\" mode when \"visual\" mode is requested. simulation_options : An object of simulation-specific options. load_callback : A function handle to invoke when the simulation is ready to trigger the on_load event for the trial. It is important to invoke this at the correct time during the simulation so that any on_load events in the experiment execute as expected. Typically the flow for supporting simulation mode involves: Generating artificial data that is consistent with the trial parameters. Merging that data with any data specified by the user in simulation_options . Verifying that the final data object is still consistent with the trial parameters. For example, checking that RTs are not longer than the duration of the trial. In data-only mode, call jsPsych.finishTrial() with the artificial data. In visual mode, invoke the trial() method of the plugin and then use the artificial data to trigger the appropriate events. There are a variety of methods in the Plugin API module to assist with things like simulating key presses and mouse clicks. We plan to add a longer guide about simulation development in the future. For now, we recommend browsing the source code of plugins that support simulation mode to see how the flow described above is implemented.","title":"Simulation mode"},{"location":"developers/plugin-development/#advice-for-writing-plugins","text":"If you are developing a plugin with the aim of including it in the main jsPsych repository we encourage you to follow the contribution guidelines . We also recommend that you make your plugin as general as possible . Consider using parameters to give the user of the plugin as many options for customization as possible. For example, if you have any text that displays in the plugin including things like button labels, implement the text as a parameter. This allows users running experiments in other languages to replace text values as needed.","title":"Advice for writing plugins"},{"location":"extensions/list-of-extensions/","text":"List of Plugins \u00b6 These are the extensions that are included in the jsPsych release. Additional extensions may be available in the community contributions repository . For an overview of what extensions are and how they work, see our extensions overview . Extension Description mouse\u2011tracking Enables tracking of mouse events and recording location of objects on screen. record\u2011video Record video data from the participant's webcam during a trial. webgazer Enables eye tracking using the WebGazer library.","title":"List of Extensions"},{"location":"extensions/list-of-extensions/#list-of-plugins","text":"These are the extensions that are included in the jsPsych release. Additional extensions may be available in the community contributions repository . For an overview of what extensions are and how they work, see our extensions overview . Extension Description mouse\u2011tracking Enables tracking of mouse events and recording location of objects on screen. record\u2011video Record video data from the participant's webcam during a trial. webgazer Enables eye tracking using the WebGazer library.","title":"List of Plugins"},{"location":"extensions/mouse-tracking/","text":"mouse-tracking \u00b6 This extension supports mouse tracking. Specifically, it can record the x and y coordinates, along with the time of mousemove events , mousedown events , and mouseup events . It also allows recording of the bounding rectangle of elements on the screen to support the calculation of mouse events relative to different elements. Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] }) Parameter Type Default Value Description minimum_sample_time number 0 The minimum time between samples for mousemove events in milliseconds. If mousemove events occur more rapidly than this limit, they will not be recorded. Use this if you want to keep the data files smaller and don't need high resolution tracking data. The default value of 0 means that all events will be recorded. Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the mouse tracking data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. events array ['mousemove'] A list of events to track. Can include 'mousemove', 'mousedown', and 'mouseup'. Data Generated \u00b6 Name Type Value mouse_tracking_data array An array of objects containing mouse movement data for the trial. Each object has an x , a y , a t , and an event property. The x and y properties specify the mouse coordinates in pixels relative to the top left corner of the viewport and t specifies the time in milliseconds since the start of the trial. The event will be either 'mousemove', 'mousedown', or 'mouseup' depending on which event was generated. mouse_tracking_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element. Examples \u00b6 Record mouse movement data and play it back Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Move your mouse around inside the square.</p>\" , extensions : [ { type : jsPsychExtensionMouseTracking , params : { targets : [ '#target' ]}} ], data : { task : 'draw' } }; var replay = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto; position: relative;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Here's the recording of your mouse movements</p>\" , on_load : function (){ var mouseMovements = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_data ; var targetRect = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_targets [ '#target' ]; var startTime = performance . now (); function draw_frame () { var timeElapsed = performance . now () - startTime ; var points = mouseMovements . filter (( x ) => x . t <= timeElapsed ); var html = `` ; for ( var p of points ){ html += `<div style=\"width: 3px; height: 3px; background-color: blue; position: absolute; top: ${ p . y - 1 - targetRect . top } px; left: ${ p . x - 1 - targetRect . left } px;\"></div>` } document . querySelector ( '#target' ). innerHTML = html ; if ( points . length < mouseMovements . length ) { requestAnimationFrame ( draw_frame ); } } requestAnimationFrame ( draw_frame ); }, data : { task : 'replay' } } Open demo in new tab","title":"mouse-tracking"},{"location":"extensions/mouse-tracking/#mouse-tracking","text":"This extension supports mouse tracking. Specifically, it can record the x and y coordinates, along with the time of mousemove events , mousedown events , and mouseup events . It also allows recording of the bounding rectangle of elements on the screen to support the calculation of mouse events relative to different elements.","title":"mouse-tracking"},{"location":"extensions/mouse-tracking/#parameters","text":"","title":"Parameters"},{"location":"extensions/mouse-tracking/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] }) Parameter Type Default Value Description minimum_sample_time number 0 The minimum time between samples for mousemove events in milliseconds. If mousemove events occur more rapidly than this limit, they will not be recorded. Use this if you want to keep the data files smaller and don't need high resolution tracking data. The default value of 0 means that all events will be recorded.","title":"Initialization Parameters"},{"location":"extensions/mouse-tracking/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionMouseTracking , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the mouse tracking data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. events array ['mousemove'] A list of events to track. Can include 'mousemove', 'mousedown', and 'mouseup'.","title":"Trial Parameters"},{"location":"extensions/mouse-tracking/#data-generated","text":"Name Type Value mouse_tracking_data array An array of objects containing mouse movement data for the trial. Each object has an x , a y , a t , and an event property. The x and y properties specify the mouse coordinates in pixels relative to the top left corner of the viewport and t specifies the time in milliseconds since the start of the trial. The event will be either 'mousemove', 'mousedown', or 'mouseup' depending on which event was generated. mouse_tracking_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element.","title":"Data Generated"},{"location":"extensions/mouse-tracking/#examples","text":"Record mouse movement data and play it back Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Move your mouse around inside the square.</p>\" , extensions : [ { type : jsPsychExtensionMouseTracking , params : { targets : [ '#target' ]}} ], data : { task : 'draw' } }; var replay = { type : jsPsychHtmlButtonResponse , stimulus : '<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; margin: auto; position: relative;\"></div>' , choices : [ 'Done' ], prompt : \"<p>Here's the recording of your mouse movements</p>\" , on_load : function (){ var mouseMovements = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_data ; var targetRect = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. mouse_tracking_targets [ '#target' ]; var startTime = performance . now (); function draw_frame () { var timeElapsed = performance . now () - startTime ; var points = mouseMovements . filter (( x ) => x . t <= timeElapsed ); var html = `` ; for ( var p of points ){ html += `<div style=\"width: 3px; height: 3px; background-color: blue; position: absolute; top: ${ p . y - 1 - targetRect . top } px; left: ${ p . x - 1 - targetRect . left } px;\"></div>` } document . querySelector ( '#target' ). innerHTML = html ; if ( points . length < mouseMovements . length ) { requestAnimationFrame ( draw_frame ); } } requestAnimationFrame ( draw_frame ); }, data : { task : 'replay' } } Open demo in new tab","title":"Examples"},{"location":"extensions/record-video/","text":"record-video \u00b6 This extension records video from the participant's webcam during a trial. This extension encodes the video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] }) Parameter Type Default Value Description None Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] } Parameter Type Default Value Description None Data Generated \u00b6 Name Type Value record_video_data base64 string Base 64 encoded representation of the video data. Examples \u00b6 Record video data during a trial Code Demo const init_camera = { type : jsPsychInitializeCamera }; const trial = { type : jsPsychHtmlButtonResponse , stimulus : `<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; position: relative; margin: 2em auto;\"> <div class=\"orbit\" style=\"width:25px; height:25px; border-radius:25px;background-color: #f00; position: absolute; top:calc(50% - 12px); left:calc(50% - 12px);\"></div> </div> <style> .orbit { transform: translateX(100px); animation: orbit 4s infinite; } @keyframes orbit { 0% { transform: rotate(0deg) translateX(100px); } 100% { transform: rotate(360deg) translateX(100px); } } </style>` , choices : [ 'Done' ], prompt : \"<p>Video is recording. Click done after a few seconds.</p>\" , extensions : [ { type : jsPsychExtensionRecordVideo } ] }; Open demo in new tab","title":"record-video"},{"location":"extensions/record-video/#record-video","text":"This extension records video from the participant's webcam during a trial. This extension encodes the video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R.","title":"record-video"},{"location":"extensions/record-video/#parameters","text":"","title":"Parameters"},{"location":"extensions/record-video/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] }) Parameter Type Default Value Description None","title":"Initialization Parameters"},{"location":"extensions/record-video/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionRecordVideo , params : {...}} ] } Parameter Type Default Value Description None","title":"Trial Parameters"},{"location":"extensions/record-video/#data-generated","text":"Name Type Value record_video_data base64 string Base 64 encoded representation of the video data.","title":"Data Generated"},{"location":"extensions/record-video/#examples","text":"Record video data during a trial Code Demo const init_camera = { type : jsPsychInitializeCamera }; const trial = { type : jsPsychHtmlButtonResponse , stimulus : `<div id=\"target\" style=\"width:250px; height: 250px; background-color: #333; position: relative; margin: 2em auto;\"> <div class=\"orbit\" style=\"width:25px; height:25px; border-radius:25px;background-color: #f00; position: absolute; top:calc(50% - 12px); left:calc(50% - 12px);\"></div> </div> <style> .orbit { transform: translateX(100px); animation: orbit 4s infinite; } @keyframes orbit { 0% { transform: rotate(0deg) translateX(100px); } 100% { transform: rotate(360deg) translateX(100px); } } </style>` , choices : [ 'Done' ], prompt : \"<p>Video is recording. Click done after a few seconds.</p>\" , extensions : [ { type : jsPsychExtensionRecordVideo } ] }; Open demo in new tab","title":"Examples"},{"location":"extensions/webgazer/","text":"webgazer \u00b6 This extension supports eye tracking through the WebGazer library. For a narrative description of how to use this extension see the eye tracking overview . Parameters \u00b6 Initialization Parameters \u00b6 Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] }) Parameter Type Default Value Description webgazer object undefined You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global webgazer object. If you are loading webgazer.js via a <script> tag you do not need to set this parameter in most circumstances. auto_initialize bool false Whether to automatically initialize webgazer when the experiment begins. If set to true then the experiment will attempt to access the user's webcam immediately upon page load. The default value is false because it is probably a good idea to explain to the user why camera permission will be needed before asking for it. The webgazer-init-camera plugin can be used to initialize the camera during the experiment. round_predictions bool true Whether to round the x , y coordinates predicted by WebGazer to the nearest whole number. This greatly reduces the size of the data, as WebGazer records data to 15 decimal places by default. Given the noise of the system, there's really no need to record data to this level of precision. sampling_interval numeric 34 Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second. Trial Parameters \u00b6 Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the WebGazer data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded. Data Generated \u00b6 Name Type Value webgazer_data array An array of objects containing gaze data for the trial. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. webgazer_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element. Functions \u00b6 In addition to the jsPsych webgazer-* plugins, the jsPsych webgazer extension provides a set of functions that allow the researcher to interact more directly with WebGazer. These functions can be called at any point during an experiment, and are crucial for building trial plugins that interact with WebGazer. All of the functions below must be prefixed with jsPsych.extensions.webgazer (e.g. jsPsych.extensions.webgazer.faceDetected() ). start() \u00b6 Performs initialization of webgazer, including requesting permissions from the user to access the camera. Returns a Promise that resolves when the camera is initialized and fails if the camera cannot be accessed, e.g., because the user denies permission. This is handled automatically if using the webgazer-init-camera plugin or setting auto_initialize to true in the extension parameters. isInitialized() \u00b6 Returns true if start() has been successfully called at some point, and false otherwise. faceDetected() \u00b6 Returns true if WebGazer is ready to make predictions ( webgazer.getTracker().predictionReady is true ). showPredictions() \u00b6 Turns on WebGazer's real-time visualization of predicted gaze location. hidePredictions() \u00b6 Turns off WebGazer's real-time visualization of predicted gaze location. showVideo() \u00b6 Turns on a display of the webcam image, guiding box for positioning the face, and WebGazer's estimate of the location of facial landmarks. hideVideo() \u00b6 Turns off the camera display. resume() \u00b6 Turns on gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer. pause() \u00b6 Turns off gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer. resetCalibration() \u00b6 Clears all calibration data. startMouseCalibration() \u00b6 Turns on mouse movement and mouse clicks as calibration events. While the webgazer-calibration plugin can also be used to run a parmeterized calibration routine, this calibration function call allows you to continuously calibrate WebGazer to any mouse movements or clicks throughout the experiment. For example, any *-button-response trial would also function as a WebGazer calibration event. stopMouseCalibration() \u00b6 Stops WebGazer from using mouse movements and mouse clicks as calibration events. calibratePoint(x, y) \u00b6 Instructs WebGazer to register the location x , y (in screen pixel coordinates) as a calibration event. Can be used for passive viewing calibration, i.e., instructing participants to fixate at a particular location. setRegressionType(regression_type) \u00b6 Change the method that WebGazer is using to perform feature -> location regression. Valid options are ridge , weightedRidge , and threadedRidge . See the WebGazer docs for more information about these options. The extension uses the default mode specified by WebGazer (currently ridge ). getCurrentPrediction() \u00b6 Get the current predicted gaze location from WebGazer. This returns a Promise that resolves once WebGazer has finished computing the gaze prediction. The Promise has a single parameter with an object with x , y , and, t parameters. t will be the value of performance.now() at approximately the time that the video frame was recorded. startSampleInterval(interval) \u00b6 Starts sampling gaze predictions every interval milliseconds. If interval is left undefined then the default value at extension initialization is used. Every sample will trigger an onGazeUpdate callback, as well as side effects that result in data storage within the extension. stopSampleInterval() \u00b6 Stops the sampling started by startSampleInterval() . onGazeUpdate(callback) \u00b6 Subscribe to gaze updates. The callback will be invoked every time a new gaze prediction is generated. The first argument of the callback will be an object with x , y , and, if currently in a trial with the extension turned on, the time t in ms since the start of the trial. t will be the value of performance.now() at approximately the time that the video frame was recorded. If currently in an active trial then t will be relative to the start of the trial. This function returns a close handler. When you no longer need to subscribe to gaze updates, call the close handler. Example: var cancelGazeUpdateHandler = jsPsych . extensions . webgazer . onGazeUpdate ( function ( prediction ){ console . log ( `Currently looking at ${ prediction . x } , ${ prediction . y } ` ); }); cancelGazeUpdateHandler (); You can add multiple handlers. Handlers are not closed automatically, so be sure to cancel them when no longer needed.","title":"webgazer"},{"location":"extensions/webgazer/#webgazer","text":"This extension supports eye tracking through the WebGazer library. For a narrative description of how to use this extension see the eye tracking overview .","title":"webgazer"},{"location":"extensions/webgazer/#parameters","text":"","title":"Parameters"},{"location":"extensions/webgazer/#initialization-parameters","text":"Initialization parameters can be set when calling initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] }) Parameter Type Default Value Description webgazer object undefined You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global webgazer object. If you are loading webgazer.js via a <script> tag you do not need to set this parameter in most circumstances. auto_initialize bool false Whether to automatically initialize webgazer when the experiment begins. If set to true then the experiment will attempt to access the user's webcam immediately upon page load. The default value is false because it is probably a good idea to explain to the user why camera permission will be needed before asking for it. The webgazer-init-camera plugin can be used to initialize the camera during the experiment. round_predictions bool true Whether to round the x , y coordinates predicted by WebGazer to the nearest whole number. This greatly reduces the size of the data, as WebGazer records data to 15 decimal places by default. Given the noise of the system, there's really no need to record data to this level of precision. sampling_interval numeric 34 Sets the interval between gaze predictions. Because the underlying code is partially asynchronous, this interval is only approximate. The sampling interval will not be faster than this, on average, but the time between samples may fluctuate. Setting the interval too fast will create performance problems and produce redundant data, as the video feed from most webcams only updates about 30 times per second.","title":"Initialization Parameters"},{"location":"extensions/webgazer/#trial-parameters","text":"Trial parameters can be set when adding the extension to a trial object. var trial = { type : jsPsych ..., extensions : [ { type : jsPsychExtensionWebgazer , params : {...}} ] } Parameter Type Default Value Description targets array [] A list of elements on the page that you would like to record the coordinates of for comparison with the WebGazer data. Each entry in the array should be a valid CSS selector string that identifies the element. The selector string should be valid for exactly one element on the page. If the selector is valid for more than one element then only the first matching element will be recorded.","title":"Trial Parameters"},{"location":"extensions/webgazer/#data-generated","text":"Name Type Value webgazer_data array An array of objects containing gaze data for the trial. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. webgazer_targets object An object contain the pixel coordinates of elements on the screen specified by the .targets parameter. Each key in this object will be a selector property, containing the CSS selector string used to find the element. The object corresponding to each key will contain x and y properties specifying the top-left corner of the object, width and height values, plus top , bottom , left , and right parameters which specify the bounding rectangle of the element.","title":"Data Generated"},{"location":"extensions/webgazer/#functions","text":"In addition to the jsPsych webgazer-* plugins, the jsPsych webgazer extension provides a set of functions that allow the researcher to interact more directly with WebGazer. These functions can be called at any point during an experiment, and are crucial for building trial plugins that interact with WebGazer. All of the functions below must be prefixed with jsPsych.extensions.webgazer (e.g. jsPsych.extensions.webgazer.faceDetected() ).","title":"Functions"},{"location":"extensions/webgazer/#start","text":"Performs initialization of webgazer, including requesting permissions from the user to access the camera. Returns a Promise that resolves when the camera is initialized and fails if the camera cannot be accessed, e.g., because the user denies permission. This is handled automatically if using the webgazer-init-camera plugin or setting auto_initialize to true in the extension parameters.","title":"start()"},{"location":"extensions/webgazer/#isinitialized","text":"Returns true if start() has been successfully called at some point, and false otherwise.","title":"isInitialized()"},{"location":"extensions/webgazer/#facedetected","text":"Returns true if WebGazer is ready to make predictions ( webgazer.getTracker().predictionReady is true ).","title":"faceDetected()"},{"location":"extensions/webgazer/#showpredictions","text":"Turns on WebGazer's real-time visualization of predicted gaze location.","title":"showPredictions()"},{"location":"extensions/webgazer/#hidepredictions","text":"Turns off WebGazer's real-time visualization of predicted gaze location.","title":"hidePredictions()"},{"location":"extensions/webgazer/#showvideo","text":"Turns on a display of the webcam image, guiding box for positioning the face, and WebGazer's estimate of the location of facial landmarks.","title":"showVideo()"},{"location":"extensions/webgazer/#hidevideo","text":"Turns off the camera display.","title":"hideVideo()"},{"location":"extensions/webgazer/#resume","text":"Turns on gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer.","title":"resume()"},{"location":"extensions/webgazer/#pause","text":"Turns off gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with WebGazer.","title":"pause()"},{"location":"extensions/webgazer/#resetcalibration","text":"Clears all calibration data.","title":"resetCalibration()"},{"location":"extensions/webgazer/#startmousecalibration","text":"Turns on mouse movement and mouse clicks as calibration events. While the webgazer-calibration plugin can also be used to run a parmeterized calibration routine, this calibration function call allows you to continuously calibrate WebGazer to any mouse movements or clicks throughout the experiment. For example, any *-button-response trial would also function as a WebGazer calibration event.","title":"startMouseCalibration()"},{"location":"extensions/webgazer/#stopmousecalibration","text":"Stops WebGazer from using mouse movements and mouse clicks as calibration events.","title":"stopMouseCalibration()"},{"location":"extensions/webgazer/#calibratepointx-y","text":"Instructs WebGazer to register the location x , y (in screen pixel coordinates) as a calibration event. Can be used for passive viewing calibration, i.e., instructing participants to fixate at a particular location.","title":"calibratePoint(x, y)"},{"location":"extensions/webgazer/#setregressiontyperegression_type","text":"Change the method that WebGazer is using to perform feature -> location regression. Valid options are ridge , weightedRidge , and threadedRidge . See the WebGazer docs for more information about these options. The extension uses the default mode specified by WebGazer (currently ridge ).","title":"setRegressionType(regression_type)"},{"location":"extensions/webgazer/#getcurrentprediction","text":"Get the current predicted gaze location from WebGazer. This returns a Promise that resolves once WebGazer has finished computing the gaze prediction. The Promise has a single parameter with an object with x , y , and, t parameters. t will be the value of performance.now() at approximately the time that the video frame was recorded.","title":"getCurrentPrediction()"},{"location":"extensions/webgazer/#startsampleintervalinterval","text":"Starts sampling gaze predictions every interval milliseconds. If interval is left undefined then the default value at extension initialization is used. Every sample will trigger an onGazeUpdate callback, as well as side effects that result in data storage within the extension.","title":"startSampleInterval(interval)"},{"location":"extensions/webgazer/#stopsampleinterval","text":"Stops the sampling started by startSampleInterval() .","title":"stopSampleInterval()"},{"location":"extensions/webgazer/#ongazeupdatecallback","text":"Subscribe to gaze updates. The callback will be invoked every time a new gaze prediction is generated. The first argument of the callback will be an object with x , y , and, if currently in a trial with the extension turned on, the time t in ms since the start of the trial. t will be the value of performance.now() at approximately the time that the video frame was recorded. If currently in an active trial then t will be relative to the start of the trial. This function returns a close handler. When you no longer need to subscribe to gaze updates, call the close handler. Example: var cancelGazeUpdateHandler = jsPsych . extensions . webgazer . onGazeUpdate ( function ( prediction ){ console . log ( `Currently looking at ${ prediction . x } , ${ prediction . y } ` ); }); cancelGazeUpdateHandler (); You can add multiple handlers. Handlers are not closed automatically, so be sure to cancel them when no longer needed.","title":"onGazeUpdate(callback)"},{"location":"overview/browser-device-support/","text":"Browser and Device Support \u00b6 Desktop and Laptop Browsers \u00b6 Supported jsPsych supports recent versions of the four most commonly-used web browsers: Chrome Firefox Safari Edge This means that jsPsych should work on these browsers. If something doesn't work as you expect on one of the browsers above, it might be a bug that should be fixed. You can search for and report bugs on the jsPsych GitHub Issues page . We're very grateful for anyone who takes the time to report bugs - it helps improve the library for everyone! Unsupported There are many other web browsers that are available, but that are not commonly used. The most well-known of these are Internet Explorer and Opera. jsPsych is not tested on these and other browsers not listed in the Supported section above. jsPsych experiments might work in these browsers, but they might not . If you want to give participants the option to use unsupported browsers, then we recommend carefully testing your experiment to make sure that everything works as expected. Otherwise, we suggest asking your participants to only use a supported browser, or incorporating browser, device, and/or feature checks at the start of your experiment. jsPsych offers built-in methods for exclusion based on minimum browser size and WebAudio API compatibility . You can incorporate other browser/device/feature checks into your experiment by adding custom JavaScript code. Mobile Devices \u00b6 In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen. If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that: * Font sizes are readable on smaller screens * Stimuli sizes are large enough and appropriate for the task * Page is laid out as intended (e.g. elements are centered and do not overlap) * Response options are touchscreen-friendly (e.g. buttons rather than key presses) * Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap It's possible to use your browser's developer tools to emulate mobile devices ( this page shows how to do it in Chrome ), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate. Mobile Browsers \u00b6 The browser options for mobile phones and tablets are slightly different than those for desktop and laptop computers. In addition to mobile versions of Chrome, Firefox, Safari, and Edge, other notable mobile browsers include Opera Mobile, Samsung Internet, UC Browser, and Dolphin. Because of the greater diversity of mobile browsers and volatility in their usage statistics, jsPsych does not officially support any particular set of mobile browsers. However, we do anticipate that most experiments should work in most mobile browsers, especially the mobile versions of browsers that we do support in Desktop mode. If you run into a problem using jsPsych in mobile browsers, please report it on the jsPsych GitHub Issues page ! We do our best to fix browser incompatibilities that are not specific to a single experiment.","title":"Browser and Device Support"},{"location":"overview/browser-device-support/#browser-and-device-support","text":"","title":"Browser and Device Support"},{"location":"overview/browser-device-support/#desktop-and-laptop-browsers","text":"Supported jsPsych supports recent versions of the four most commonly-used web browsers: Chrome Firefox Safari Edge This means that jsPsych should work on these browsers. If something doesn't work as you expect on one of the browsers above, it might be a bug that should be fixed. You can search for and report bugs on the jsPsych GitHub Issues page . We're very grateful for anyone who takes the time to report bugs - it helps improve the library for everyone! Unsupported There are many other web browsers that are available, but that are not commonly used. The most well-known of these are Internet Explorer and Opera. jsPsych is not tested on these and other browsers not listed in the Supported section above. jsPsych experiments might work in these browsers, but they might not . If you want to give participants the option to use unsupported browsers, then we recommend carefully testing your experiment to make sure that everything works as expected. Otherwise, we suggest asking your participants to only use a supported browser, or incorporating browser, device, and/or feature checks at the start of your experiment. jsPsych offers built-in methods for exclusion based on minimum browser size and WebAudio API compatibility . You can incorporate other browser/device/feature checks into your experiment by adding custom JavaScript code.","title":"Desktop and Laptop Browsers"},{"location":"overview/browser-device-support/#mobile-devices","text":"In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen. If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that: * Font sizes are readable on smaller screens * Stimuli sizes are large enough and appropriate for the task * Page is laid out as intended (e.g. elements are centered and do not overlap) * Response options are touchscreen-friendly (e.g. buttons rather than key presses) * Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap It's possible to use your browser's developer tools to emulate mobile devices ( this page shows how to do it in Chrome ), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate.","title":"Mobile Devices"},{"location":"overview/browser-device-support/#mobile-browsers","text":"The browser options for mobile phones and tablets are slightly different than those for desktop and laptop computers. In addition to mobile versions of Chrome, Firefox, Safari, and Edge, other notable mobile browsers include Opera Mobile, Samsung Internet, UC Browser, and Dolphin. Because of the greater diversity of mobile browsers and volatility in their usage statistics, jsPsych does not officially support any particular set of mobile browsers. However, we do anticipate that most experiments should work in most mobile browsers, especially the mobile versions of browsers that we do support in Desktop mode. If you run into a problem using jsPsych in mobile browsers, please report it on the jsPsych GitHub Issues page ! We do our best to fix browser incompatibilities that are not specific to a single experiment.","title":"Mobile Browsers"},{"location":"overview/data/","text":"Data in jsPsych: permanent and non-permanent data. \u00b6 There are two very different kinds of data storage: data stored in memory and data stored permanently . Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a server. Data stored in memory exists only as long the browser window running jsPsych is open. jsPsych has many features for interacting with data stored in memory, but few for permanent data storage. This is a deliberate choice, as there are dozens of ways that data could be stored permanently. jsPsych does not lock you into one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and the second half of this page contains a few suggestions on how to accomplish permanent data storage. Storing data in jsPsych's data structure \u00b6 jsPsych has a centralized collection of data that is built as the experiment runs. Each trial adds to the collection, and you can access the data with various functions, including jsPsych.data.get() , which returns the entire set of data. In most cases, data collection will be automatic and hidden. Plugins save data on their own so it is not uncommon to have the only interaction with the data be at the end of the experiment when it is time to save it in a permanent manner (see sections below about how to do this). However, there are some situations in which you may want to interact with the data; in particular, you may want to store additional data that the plugins are not recording, like a subject identifier or condition assignment. You may also want to add data on a trial by trial basis. For example, in a Stroop paradigm you would want to label which trials are congruent and which are incongruent. These scenarios are explored below. Adding data to all trials \u00b6 Often it is useful to add a piece of data to all of the trials in the experiment. For example, appending the subject ID to each trial. This can be done with the jsPsych.data.addProperties() function. Here is an example: // generate a random subject ID with 15 characters var subject_id = jsPsych . randomization . randomID ( 15 ); // pick a random condition for the subject at the start of the experiment var condition_assignment = jsPsych . randomization . sampleWithoutReplacement ([ 'conditionA' , 'conditionB' , 'conditionC' ], 1 )[ 0 ]; // record the condition assignment in the jsPsych data // this adds a property called 'subject' and a property called 'condition' to every trial jsPsych . data . addProperties ({ subject : subject_id , condition : condition_assignment }); Adding data to a particular trial or set of trials \u00b6 Data can be added to a particular trial by setting the data parameter for the trial. The data parameter is an object of key-value pairs, and each pair is added to the data for that trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , data : { image_type : 'A' } } Data declared in this way is also saved in the trials on any nested timelines: var block = { type : jsPsychImageKeyboardResponse , data : { image_type : 'A' }, timeline : [ { stimulus : 'imgA1.jpg' }, { stimulus : 'imgA2.jpg' } ] } The data object for a trial can also be updated in the on_finish event handler. You can override properties or add new ones. This is particularly useful for cases where the value depends on something that happened during the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } } Aggregating and manipulating jsPsych data \u00b6 When accessing the data with jsPsych.data.get() the returned object is a special data collection object that exposes a number of methods for aggregating and manipulating the data. The full list of methods is detailed in the data module documentation . Here are some examples of data collection manipulation. All data generated by the image-keyboard-response plugin: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }); All data generated by the categorize-image plugin with a correct response: var data = jsPsych . data . get (). filter ({ trial_type : 'categorize-image' , correct : true }); All data with a response time between 100 and 500ms: var data = jsPsych . data . get (). filterCustom ( function ( x ){ return x . rt >= 100 && x . rt <= 500 }); Applying filters consecutively to get all trials from a particular plugin with a response time above 100ms: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }). filterCustom ( function ( x ){ return x . rt > 100 ; }); Getting the data from the last n trials: var n = 3 ; var data = jsPsych . data . get (). last ( n ); Getting the data from the last n trials with a correct response: var n = 3 ; var data = jsPsych . data . get (). filter ({ correct : true }). last ( n ); Getting the data from the first n trials: var n = 3 ; var data = jsPsych . data . get (). first ( n ); Counting the number of trials with a correct response in a data collection: var count = jsPsych . data . get (). filter ({ correct : true }). count (); Selecting all of the response times from a data collection: var response_times = jsPsych . data . get (). select ( 'rt' ); Calculating various descriptive statistics on the response times in a data collection: jsPsych . data . get (). select ( 'rt' ). mean (); jsPsych . data . get (). select ( 'rt' ). sum (); jsPsych . data . get (). select ( 'rt' ). min (); jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). variance (); jsPsych . data . get (). select ( 'rt' ). sd (); jsPsych . data . get (). select ( 'rt' ). median (); jsPsych . data . get (). select ( 'rt' ). count (); Storing data permanently as a file \u00b6 This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server. This method will only work if you are running on a web server with PHP installed, or a local server with PHP (e.g., XAMPP ). This method uses a short PHP script to write files to the server: <?php // get the data from the POST message $post_data = json_decode ( file_get_contents ( 'php://input' ), true ); $data = $post_data [ 'filedata' ]; // generate a unique ID for the file, e.g., session-6feu833950202 $file = uniqid ( \"session-\" ); // the directory \"data\" must be writable by the server $name = \"data/ { $file } .csv\" ; // write the file to disk file_put_contents ( $name , $data ); ?> The file_put_contents($name, $data) method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission to that directory. In the above example, the directory data/ is used to store files. To use the PHP script, the JavaScript that runs jsPsych needs to send the filedata information. This is done through an AJAX call. function saveData ( name , data ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // 'write_data.php' is the path to the php file described above. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . send ( JSON . stringify ({ filedata : data })); } // call the saveData function after the experiment is over initJsPsych ({ on_finish : function (){ saveData ( jsPsych . data . get (). csv ()); } }); Danger The example above has minimal security and should probably not be used without additional security measures put in place. The risk is that someone can write arbitrary data using the saveData() function and store it to a file on your webserver. If they can guess the file name generated by the PHP script, or access a directory listing containing all of the filenames, then they can potentially write executable code to your server and run it. One fix is to store the CSV files outside the web directory on the server. This requires changing the path in the PHP script above from /data to a folder that is not accessible on the web. You should only use this solution if you have access to more than just the web directory on your server. You can also configure your web server to block access to the folder you are storing data in . The MySQL option below is more secure. Storing data permanently in a MySQL database \u00b6 Another solution for storing data generated by jsPsych is to write it to a database. There are dozens of database options. MySQL is one of the most popular relational databases , is free to use, and relatively easy to install . This code will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code. If you are trying to run on a local machine, you'll need to install a local server environment like XAMPP . You'll need two PHP scripts. The first is a configuration file for your database. Save it as database_config.php on your server. Within this file are configuration options for the database. You'll need to change these according to how you have configured your MySQL installation. <?php $servername = \"localhost\" ; $port = 3306 ; $username = \"username\" ; $password = \"password\" ; $dbname = \"database\" ; $table = \"tablename\" ; ?> The second PHP file will write data to the database. This script reads the database to discover what columns are in the table, and then only allows data to be entered in that matches those columns. This is a security feature. Save this file as write_data.php on your server. <?php // this path should point to your configuration file. include ( 'database_config.php' ); $data_array = json_decode ( file_get_contents ( 'php://input' ), true ); try { $conn = new PDO ( \"mysql:host= $servername ;port= $port ;dbname= $dbname \" , $username , $password ); $conn -> setAttribute ( PDO :: ATTR_ERRMODE , PDO :: ERRMODE_EXCEPTION ); // First stage is to get all column names from the table and store // them in $col_names array. $stmt = $conn -> prepare ( \"SHOW COLUMNS FROM ` $table `\" ); $stmt -> execute (); $col_names = array (); while ( $row = $stmt -> fetchColumn ()) { $col_names [] = $row ; } // Second stage is to create prepared SQL statement using the column // names as a guide to what values might be in the JSON. // If a value is missing from a particular trial, then NULL is inserted $sql = \"INSERT INTO $table VALUES(\" ; for ( $i = 0 ; $i < count ( $col_names ); $i ++ ){ $name = $col_names [ $i ]; $sql .= \": $name \" ; if ( $i != count ( $col_names ) - 1 ){ $sql .= \", \" ; } } $sql .= \");\" ; $insertstmt = $conn -> prepare ( $sql ); for ( $i = 0 ; $i < count ( $data_array ); $i ++ ){ for ( $j = 0 ; $j < count ( $col_names ); $j ++ ){ $colname = $col_names [ $j ]; if ( ! isset ( $data_array [ $i ][ $colname ])){ $insertstmt -> bindValue ( \": $colname \" , null , PDO :: PARAM_NULL ); } else { $insertstmt -> bindValue ( \": $colname \" , $data_array [ $i ][ $colname ]); } } $insertstmt -> execute (); } echo '{\"success\": true}' ; } catch ( PDOException $e ) { echo '{\"success\": false, \"message\": ' . $e -> getMessage (); } $conn = null ; ?> To send the data, we use an XMLHttpRequest request in JavaScript. function saveData () { var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // change 'write_data.php' to point to php script. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } }; xhr . send ( jsPsych . data . get (). json ()); } It's important that the XMLHttpRequest is able to complete before the experiment is closed. If you invoke the saveData() function at the end of your experiment and the participant closes the window before all of the data has been transferred you will lose that data. To mitigate this risk, you can use the call-function plugin's async option to prevent the experiment from progressing until the request is complete. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } done (); // invoking done() causes experiment to progress to next trial. }; xhr . send ( jsPsych . data . get (). json ()); } }","title":"Data Storage, Aggregation, and Manipulation"},{"location":"overview/data/#data-in-jspsych-permanent-and-non-permanent-data","text":"There are two very different kinds of data storage: data stored in memory and data stored permanently . Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a server. Data stored in memory exists only as long the browser window running jsPsych is open. jsPsych has many features for interacting with data stored in memory, but few for permanent data storage. This is a deliberate choice, as there are dozens of ways that data could be stored permanently. jsPsych does not lock you into one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and the second half of this page contains a few suggestions on how to accomplish permanent data storage.","title":"Data in jsPsych: permanent and non-permanent data."},{"location":"overview/data/#storing-data-in-jspsychs-data-structure","text":"jsPsych has a centralized collection of data that is built as the experiment runs. Each trial adds to the collection, and you can access the data with various functions, including jsPsych.data.get() , which returns the entire set of data. In most cases, data collection will be automatic and hidden. Plugins save data on their own so it is not uncommon to have the only interaction with the data be at the end of the experiment when it is time to save it in a permanent manner (see sections below about how to do this). However, there are some situations in which you may want to interact with the data; in particular, you may want to store additional data that the plugins are not recording, like a subject identifier or condition assignment. You may also want to add data on a trial by trial basis. For example, in a Stroop paradigm you would want to label which trials are congruent and which are incongruent. These scenarios are explored below.","title":"Storing data in jsPsych's data structure"},{"location":"overview/data/#adding-data-to-all-trials","text":"Often it is useful to add a piece of data to all of the trials in the experiment. For example, appending the subject ID to each trial. This can be done with the jsPsych.data.addProperties() function. Here is an example: // generate a random subject ID with 15 characters var subject_id = jsPsych . randomization . randomID ( 15 ); // pick a random condition for the subject at the start of the experiment var condition_assignment = jsPsych . randomization . sampleWithoutReplacement ([ 'conditionA' , 'conditionB' , 'conditionC' ], 1 )[ 0 ]; // record the condition assignment in the jsPsych data // this adds a property called 'subject' and a property called 'condition' to every trial jsPsych . data . addProperties ({ subject : subject_id , condition : condition_assignment });","title":"Adding data to all trials"},{"location":"overview/data/#adding-data-to-a-particular-trial-or-set-of-trials","text":"Data can be added to a particular trial by setting the data parameter for the trial. The data parameter is an object of key-value pairs, and each pair is added to the data for that trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , data : { image_type : 'A' } } Data declared in this way is also saved in the trials on any nested timelines: var block = { type : jsPsychImageKeyboardResponse , data : { image_type : 'A' }, timeline : [ { stimulus : 'imgA1.jpg' }, { stimulus : 'imgA2.jpg' } ] } The data object for a trial can also be updated in the on_finish event handler. You can override properties or add new ones. This is particularly useful for cases where the value depends on something that happened during the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.jpg' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } }","title":"Adding data to a particular trial or set of trials"},{"location":"overview/data/#aggregating-and-manipulating-jspsych-data","text":"When accessing the data with jsPsych.data.get() the returned object is a special data collection object that exposes a number of methods for aggregating and manipulating the data. The full list of methods is detailed in the data module documentation . Here are some examples of data collection manipulation. All data generated by the image-keyboard-response plugin: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }); All data generated by the categorize-image plugin with a correct response: var data = jsPsych . data . get (). filter ({ trial_type : 'categorize-image' , correct : true }); All data with a response time between 100 and 500ms: var data = jsPsych . data . get (). filterCustom ( function ( x ){ return x . rt >= 100 && x . rt <= 500 }); Applying filters consecutively to get all trials from a particular plugin with a response time above 100ms: var data = jsPsych . data . get (). filter ({ trial_type : 'image-keyboard-response' }). filterCustom ( function ( x ){ return x . rt > 100 ; }); Getting the data from the last n trials: var n = 3 ; var data = jsPsych . data . get (). last ( n ); Getting the data from the last n trials with a correct response: var n = 3 ; var data = jsPsych . data . get (). filter ({ correct : true }). last ( n ); Getting the data from the first n trials: var n = 3 ; var data = jsPsych . data . get (). first ( n ); Counting the number of trials with a correct response in a data collection: var count = jsPsych . data . get (). filter ({ correct : true }). count (); Selecting all of the response times from a data collection: var response_times = jsPsych . data . get (). select ( 'rt' ); Calculating various descriptive statistics on the response times in a data collection: jsPsych . data . get (). select ( 'rt' ). mean (); jsPsych . data . get (). select ( 'rt' ). sum (); jsPsych . data . get (). select ( 'rt' ). min (); jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). variance (); jsPsych . data . get (). select ( 'rt' ). sd (); jsPsych . data . get (). select ( 'rt' ). median (); jsPsych . data . get (). select ( 'rt' ). count ();","title":"Aggregating and manipulating jsPsych data"},{"location":"overview/data/#storing-data-permanently-as-a-file","text":"This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server. This method will only work if you are running on a web server with PHP installed, or a local server with PHP (e.g., XAMPP ). This method uses a short PHP script to write files to the server: <?php // get the data from the POST message $post_data = json_decode ( file_get_contents ( 'php://input' ), true ); $data = $post_data [ 'filedata' ]; // generate a unique ID for the file, e.g., session-6feu833950202 $file = uniqid ( \"session-\" ); // the directory \"data\" must be writable by the server $name = \"data/ { $file } .csv\" ; // write the file to disk file_put_contents ( $name , $data ); ?> The file_put_contents($name, $data) method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission to that directory. In the above example, the directory data/ is used to store files. To use the PHP script, the JavaScript that runs jsPsych needs to send the filedata information. This is done through an AJAX call. function saveData ( name , data ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // 'write_data.php' is the path to the php file described above. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . send ( JSON . stringify ({ filedata : data })); } // call the saveData function after the experiment is over initJsPsych ({ on_finish : function (){ saveData ( jsPsych . data . get (). csv ()); } }); Danger The example above has minimal security and should probably not be used without additional security measures put in place. The risk is that someone can write arbitrary data using the saveData() function and store it to a file on your webserver. If they can guess the file name generated by the PHP script, or access a directory listing containing all of the filenames, then they can potentially write executable code to your server and run it. One fix is to store the CSV files outside the web directory on the server. This requires changing the path in the PHP script above from /data to a folder that is not accessible on the web. You should only use this solution if you have access to more than just the web directory on your server. You can also configure your web server to block access to the folder you are storing data in . The MySQL option below is more secure.","title":"Storing data permanently as a file"},{"location":"overview/data/#storing-data-permanently-in-a-mysql-database","text":"Another solution for storing data generated by jsPsych is to write it to a database. There are dozens of database options. MySQL is one of the most popular relational databases , is free to use, and relatively easy to install . This code will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code. If you are trying to run on a local machine, you'll need to install a local server environment like XAMPP . You'll need two PHP scripts. The first is a configuration file for your database. Save it as database_config.php on your server. Within this file are configuration options for the database. You'll need to change these according to how you have configured your MySQL installation. <?php $servername = \"localhost\" ; $port = 3306 ; $username = \"username\" ; $password = \"password\" ; $dbname = \"database\" ; $table = \"tablename\" ; ?> The second PHP file will write data to the database. This script reads the database to discover what columns are in the table, and then only allows data to be entered in that matches those columns. This is a security feature. Save this file as write_data.php on your server. <?php // this path should point to your configuration file. include ( 'database_config.php' ); $data_array = json_decode ( file_get_contents ( 'php://input' ), true ); try { $conn = new PDO ( \"mysql:host= $servername ;port= $port ;dbname= $dbname \" , $username , $password ); $conn -> setAttribute ( PDO :: ATTR_ERRMODE , PDO :: ERRMODE_EXCEPTION ); // First stage is to get all column names from the table and store // them in $col_names array. $stmt = $conn -> prepare ( \"SHOW COLUMNS FROM ` $table `\" ); $stmt -> execute (); $col_names = array (); while ( $row = $stmt -> fetchColumn ()) { $col_names [] = $row ; } // Second stage is to create prepared SQL statement using the column // names as a guide to what values might be in the JSON. // If a value is missing from a particular trial, then NULL is inserted $sql = \"INSERT INTO $table VALUES(\" ; for ( $i = 0 ; $i < count ( $col_names ); $i ++ ){ $name = $col_names [ $i ]; $sql .= \": $name \" ; if ( $i != count ( $col_names ) - 1 ){ $sql .= \", \" ; } } $sql .= \");\" ; $insertstmt = $conn -> prepare ( $sql ); for ( $i = 0 ; $i < count ( $data_array ); $i ++ ){ for ( $j = 0 ; $j < count ( $col_names ); $j ++ ){ $colname = $col_names [ $j ]; if ( ! isset ( $data_array [ $i ][ $colname ])){ $insertstmt -> bindValue ( \": $colname \" , null , PDO :: PARAM_NULL ); } else { $insertstmt -> bindValue ( \": $colname \" , $data_array [ $i ][ $colname ]); } } $insertstmt -> execute (); } echo '{\"success\": true}' ; } catch ( PDOException $e ) { echo '{\"success\": false, \"message\": ' . $e -> getMessage (); } $conn = null ; ?> To send the data, we use an XMLHttpRequest request in JavaScript. function saveData () { var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); // change 'write_data.php' to point to php script. xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } }; xhr . send ( jsPsych . data . get (). json ()); } It's important that the XMLHttpRequest is able to complete before the experiment is closed. If you invoke the saveData() function at the end of your experiment and the participant closes the window before all of the data has been transferred you will lose that data. To mitigate this risk, you can use the call-function plugin's async option to prevent the experiment from progressing until the request is complete. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ var xhr = new XMLHttpRequest (); xhr . open ( 'POST' , 'write_data.php' ); xhr . setRequestHeader ( 'Content-Type' , 'application/json' ); xhr . onload = function () { if ( xhr . status == 200 ){ var response = JSON . parse ( xhr . responseText ); console . log ( response . success ); } done (); // invoking done() causes experiment to progress to next trial. }; xhr . send ( jsPsych . data . get (). json ()); } }","title":"Storing data permanently in a MySQL database"},{"location":"overview/dynamic-parameters/","text":"Dynamic parameters \u00b6 Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial . This enables dynamic updating of the parameter based on data that a participant has generated or any other information that you do not know in advance. Examples \u00b6 Providing Feedback \u00b6 Here is a sketch of how this functionality could be used to display feedback to a participant in the Flanker Task. var timeline = []; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_finish : function ( data ){ // Score the keyboard response as correct or incorrect. if ( jsPsych . pluginAPI . compareKeys ( data . response , \"f\" )){ data . correct = true ; } else { data . correct = false ; } } } var feedback = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ // The feedback stimulus is a dynamic parameter because we can't know in advance whether // the stimulus should be 'correct' or 'incorrect'. // Instead, this function will check the accuracy of the last response and use that information to set // the stimulus value on each trial. var last_trial_correct = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. correct ; if ( last_trial_correct ){ return \"<p>Correct!</p>\" ; // the parameter value has to be returned from the function } else { return \"<p>Wrong.</p>\" ; // the parameter value has to be returned from the function } } } timeline . push ( trial , feedback ); Note When scoring a participant's response, the jsPsych.pluginAPI.compareKeys function is only needed to compare keyboard responses. For other kinds of response types, such as button presses, you can compare the participant's response and correct response values directly, e.g. if ( data . response == 0 )){ data . correct = true ; } else { data . correct = false ; } Or: data . correct = data . response === data . correct_response ; Randomizing a parameter value \u00b6 Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function. var random_duration = function () { var rand_dur = jsPsych . randomization . sampleWithoutReplacement ([ 500 , 600 , 700 , 800 ], 1 )[ 0 ]; return rand_dur ; } var trial = { type : jsPsychHtmlKeyboardResponse stimulus : '+' , post_trial_gap : random_duration // if you use a named function for a dynamic parameter, then just use the function name (without parentheses after it) } Storing changing variables in the data \u00b6 The trial's data parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called current_difficulty that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this: var current_difficulty ; // value changes during the experiment var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : function () { return { difficulty : current_difficulty }; } } It's also possible to use a function for any of the individual properties in the trial's data object, for instance if you want to combine static and dynamic information in the data: var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : { difficulty : function () { return current_difficulty ; // the difficulty value changes during the experiment }, task_part : 'recall' , // this part of the data is always the same block_number : 1 } } Nested Parameters \u00b6 Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a questions parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the questions parameter dynamic, you can use a function that returns the array with all of the parameters for each question: var subject_id ; // value is set during the experiment var trial = { type : jsPsychSurveyText , questions : function (){ var questions_array = [ { prompt : \"Hi \" + subject_id + \"! What's your favorite city?\" , required : true , name : 'fav_city' }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' }, ]; return questions_array ; } } You can also use a function for any of the individual parameters inside of a nested parameter. var trial = { type : jsPsychSurveyText , questions : [ { prompt : function () { // this question prompt is dynamic - the text that is shown // will change based on the participant's earlier response var favorite_city = jsPsych . data . getLastTrialData (). values ()[ 0 ]. response . fav_city ; var text = \"Earlier you said your favorite city is \" + favorite_city + \". What do you like most about \" + favorite_city + \"?\" return text ; }, required : true , rows : 40 , columns : 10 }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' } ] } When dynamic parameters can't be used \u00b6 Note that if the plugin expects the value of a given parameter to be a function, then this function will not be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the stimulus parameter in the canvas-* plugins, the mistake_fn parameter in the cloze plugin, and the stim_function parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's type in the plugin.info section of the plugin file. If the parameter type is ParameterType.FUNCTION , then this parameter must be a function and it will not be executed before the trial starts. Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.","title":"Dynamic Parameters"},{"location":"overview/dynamic-parameters/#dynamic-parameters","text":"Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial . This enables dynamic updating of the parameter based on data that a participant has generated or any other information that you do not know in advance.","title":"Dynamic parameters"},{"location":"overview/dynamic-parameters/#examples","text":"","title":"Examples"},{"location":"overview/dynamic-parameters/#providing-feedback","text":"Here is a sketch of how this functionality could be used to display feedback to a participant in the Flanker Task. var timeline = []; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_finish : function ( data ){ // Score the keyboard response as correct or incorrect. if ( jsPsych . pluginAPI . compareKeys ( data . response , \"f\" )){ data . correct = true ; } else { data . correct = false ; } } } var feedback = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ // The feedback stimulus is a dynamic parameter because we can't know in advance whether // the stimulus should be 'correct' or 'incorrect'. // Instead, this function will check the accuracy of the last response and use that information to set // the stimulus value on each trial. var last_trial_correct = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. correct ; if ( last_trial_correct ){ return \"<p>Correct!</p>\" ; // the parameter value has to be returned from the function } else { return \"<p>Wrong.</p>\" ; // the parameter value has to be returned from the function } } } timeline . push ( trial , feedback ); Note When scoring a participant's response, the jsPsych.pluginAPI.compareKeys function is only needed to compare keyboard responses. For other kinds of response types, such as button presses, you can compare the participant's response and correct response values directly, e.g. if ( data . response == 0 )){ data . correct = true ; } else { data . correct = false ; } Or: data . correct = data . response === data . correct_response ;","title":"Providing Feedback"},{"location":"overview/dynamic-parameters/#randomizing-a-parameter-value","text":"Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function. var random_duration = function () { var rand_dur = jsPsych . randomization . sampleWithoutReplacement ([ 500 , 600 , 700 , 800 ], 1 )[ 0 ]; return rand_dur ; } var trial = { type : jsPsychHtmlKeyboardResponse stimulus : '+' , post_trial_gap : random_duration // if you use a named function for a dynamic parameter, then just use the function name (without parentheses after it) }","title":"Randomizing a parameter value"},{"location":"overview/dynamic-parameters/#storing-changing-variables-in-the-data","text":"The trial's data parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called current_difficulty that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this: var current_difficulty ; // value changes during the experiment var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : function () { return { difficulty : current_difficulty }; } } It's also possible to use a function for any of the individual properties in the trial's data object, for instance if you want to combine static and dynamic information in the data: var trial = { type : jsPsychSurveyText , questions : [{ prompt : \"Please enter your response.\" }] data : { difficulty : function () { return current_difficulty ; // the difficulty value changes during the experiment }, task_part : 'recall' , // this part of the data is always the same block_number : 1 } }","title":"Storing changing variables in the data"},{"location":"overview/dynamic-parameters/#nested-parameters","text":"Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a questions parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the questions parameter dynamic, you can use a function that returns the array with all of the parameters for each question: var subject_id ; // value is set during the experiment var trial = { type : jsPsychSurveyText , questions : function (){ var questions_array = [ { prompt : \"Hi \" + subject_id + \"! What's your favorite city?\" , required : true , name : 'fav_city' }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' }, ]; return questions_array ; } } You can also use a function for any of the individual parameters inside of a nested parameter. var trial = { type : jsPsychSurveyText , questions : [ { prompt : function () { // this question prompt is dynamic - the text that is shown // will change based on the participant's earlier response var favorite_city = jsPsych . data . getLastTrialData (). values ()[ 0 ]. response . fav_city ; var text = \"Earlier you said your favorite city is \" + favorite_city + \". What do you like most about \" + favorite_city + \"?\" return text ; }, required : true , rows : 40 , columns : 10 }, { prompt : \"What is your favorite fruit?\" , required : true , name : 'fav_fruit' } ] }","title":"Nested Parameters"},{"location":"overview/dynamic-parameters/#when-dynamic-parameters-cant-be-used","text":"Note that if the plugin expects the value of a given parameter to be a function, then this function will not be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the stimulus parameter in the canvas-* plugins, the mistake_fn parameter in the cloze plugin, and the stim_function parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's type in the plugin.info section of the plugin file. If the parameter type is ParameterType.FUNCTION , then this parameter must be a function and it will not be executed before the trial starts. Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.","title":"When dynamic parameters can't be used"},{"location":"overview/events/","text":"Event-related callback functions \u00b6 jsPsych offers the ability to call arbitrary functions in response to certain events occurring, like the end of a trial or when new data is saved. This page summarizes the different opportunities for callback functions and how to specify them. on_close \u00b6 The on_close callback can be declared in the initJsPsych method. The callback triggers when the user leaves the page, but before any content on the page is removed from the browser's memory. This can be used, for example, to save data as the user is leaving the page. initJsPsych ({ on_close : function (){ var data = jsPsych . data . get (). json (); save_data_to_server ( data ); } }); on_data_update \u00b6 The on_data_update callback can be declared in the initJsPsych method. The callback triggers at the end of a data update cycle. This happens after every trial, after the on_finish (trial) and on_trial_finish events execute, allowing you to modify the data in those callbacks, and then use this callback to store the data. The function will be passed a single argument, which contains the data that was written. initJsPsych ({ on_data_update : function ( data ) { console . log ( 'Just added new data. The contents of the data are: ' + JSON . stringify ( data )); } }); on_finish (trial) \u00b6 The on_finish callback can be added to any trial. The callback will trigger whenever the trial ends. The callback function will be passed a single argument, containing the data object from the trial. This data object is editable . Any changes made in the on_finish function will be stored in the internal data collection. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } }; on_finish (experiment) \u00b6 The on_finish callback can be declared in the initJsPsych method. The callback will trigger once all trials in the experiment have been run. The method will be passed a single argument, containing all of the data generated in the experiment. initJsPsych ({ on_finish : function ( data ) { console . log ( 'The experiment is over! Here is all the data: ' + JSON . stringify ( data )); } }); on_load \u00b6 The on_load callback can be added to any trial. The callback will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { console . log ( 'The trial just finished loading.' ); } }; on_start (trial) \u00b6 The on_start callback can be added to any trial. The callback will trigger right before the trial begins. The callback function will be passed a single argument, containing the trial object. If any of the parameters of the trial are functions or timeline variables, these will be evaluated before on_start is called, and the trial object will contain the evaluated value. The trial object is modifiable, and any changes made will affect the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_start : function ( trial ) { console . log ( 'The trial is about to start.' ); trial . stimulus = 'imgB.png' ; // this will change what stimulus is displayed in the trial } }; on_timeline_finish \u00b6 The on_timeline_finish callback can be declared in a timeline node. The callback will be triggered when the timeline ends during the experiment. If timeline_variables , conditional_function , loop_function , or sample options are used, this function will execute when all trials have finished. If a loop_function is used, then this on_timeline_finish function will be triggered before the loop function. If the repetitions option is used, this function will be triggered at the end of every repetition. var procedure = { timeline : [ trial1 , trial2 ], timeline_variables : [ { stimulus : 'person-1.jpg' }, { stimulus : 'person-2.jpg' }, { stimulus : 'person-3.jpg' }, { stimulus : 'person-4.jpg' } ], on_timeline_finish : function () { console . log ( 'This timeline has finished.' ); }, loop_function : function () { console . log ( 'This loop function will execute after on_timeline_finish.' ); return false ; } } on_timeline_start \u00b6 The on_timeline_start callback can be declared in a timeline node. The callback will be triggered when the timeline starts during the experiment, including when timeline_variables , loop_function , or sample options are used. If a conditional_function is used, then the conditional function will execute first, and the on_timeline_start function will only execute if the conditional function returns true . If the repetitions option is used, this function will be triggered at the start of every repetition. var procedure = { timeline : [ trial1 , trial2 ], conditional_function : function () { console . log ( 'This conditional function will execute first.' ) return true ; }, on_timeline_start : function () { console . log ( 'This timeline has started' ); } } on_trial_finish \u00b6 The on_trial_finish callback can be declared in the initJsPsych method. The callback will trigger at the end of every trial in the experiment. If you want a callback to trigger only for the end of certain trials, use the on_finish callback on the trial object. The callback function will be passed a single argument, containing the data object from the trial. initJsPsych ({ on_trial_finish : function ( data ) { console . log ( 'A trial just ended.' ); console . log ( JSON . stringify ( data )); } }); on_trial_start \u00b6 The on_trial_start callback can be declared in the initJsPsych method. The callback will trigger at the start of every trial in the experiment. The function receives a single argument: a modifiable copy of the trial object that will be used to run the next trial. Changes can be made to this object to alter the parameters of the upcoming trial. var current_score = 0 ; // a variable that is updated throughout the experiment to keep track of the current score. initJsPsych ({ on_trial_start : function ( trial ) { trial . data . score_at_start_of_trial = current_score ; console . log ( 'A trial just started.' ); } });","title":"Events"},{"location":"overview/events/#event-related-callback-functions","text":"jsPsych offers the ability to call arbitrary functions in response to certain events occurring, like the end of a trial or when new data is saved. This page summarizes the different opportunities for callback functions and how to specify them.","title":"Event-related callback functions"},{"location":"overview/events/#on_close","text":"The on_close callback can be declared in the initJsPsych method. The callback triggers when the user leaves the page, but before any content on the page is removed from the browser's memory. This can be used, for example, to save data as the user is leaving the page. initJsPsych ({ on_close : function (){ var data = jsPsych . data . get (). json (); save_data_to_server ( data ); } });","title":"on_close"},{"location":"overview/events/#on_data_update","text":"The on_data_update callback can be declared in the initJsPsych method. The callback triggers at the end of a data update cycle. This happens after every trial, after the on_finish (trial) and on_trial_finish events execute, allowing you to modify the data in those callbacks, and then use this callback to store the data. The function will be passed a single argument, which contains the data that was written. initJsPsych ({ on_data_update : function ( data ) { console . log ( 'Just added new data. The contents of the data are: ' + JSON . stringify ( data )); } });","title":"on_data_update"},{"location":"overview/events/#on_finish-trial","text":"The on_finish callback can be added to any trial. The callback will trigger whenever the trial ends. The callback function will be passed a single argument, containing the data object from the trial. This data object is editable . Any changes made in the on_finish function will be stored in the internal data collection. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'j' )){ data . correct = true ; } else { data . correct = false ; } } };","title":"on_finish (trial)"},{"location":"overview/events/#on_finish-experiment","text":"The on_finish callback can be declared in the initJsPsych method. The callback will trigger once all trials in the experiment have been run. The method will be passed a single argument, containing all of the data generated in the experiment. initJsPsych ({ on_finish : function ( data ) { console . log ( 'The experiment is over! Here is all the data: ' + JSON . stringify ( data )); } });","title":"on_finish (experiment)"},{"location":"overview/events/#on_load","text":"The on_load callback can be added to any trial. The callback will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { console . log ( 'The trial just finished loading.' ); } };","title":"on_load"},{"location":"overview/events/#on_start-trial","text":"The on_start callback can be added to any trial. The callback will trigger right before the trial begins. The callback function will be passed a single argument, containing the trial object. If any of the parameters of the trial are functions or timeline variables, these will be evaluated before on_start is called, and the trial object will contain the evaluated value. The trial object is modifiable, and any changes made will affect the trial. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_start : function ( trial ) { console . log ( 'The trial is about to start.' ); trial . stimulus = 'imgB.png' ; // this will change what stimulus is displayed in the trial } };","title":"on_start (trial)"},{"location":"overview/events/#on_timeline_finish","text":"The on_timeline_finish callback can be declared in a timeline node. The callback will be triggered when the timeline ends during the experiment. If timeline_variables , conditional_function , loop_function , or sample options are used, this function will execute when all trials have finished. If a loop_function is used, then this on_timeline_finish function will be triggered before the loop function. If the repetitions option is used, this function will be triggered at the end of every repetition. var procedure = { timeline : [ trial1 , trial2 ], timeline_variables : [ { stimulus : 'person-1.jpg' }, { stimulus : 'person-2.jpg' }, { stimulus : 'person-3.jpg' }, { stimulus : 'person-4.jpg' } ], on_timeline_finish : function () { console . log ( 'This timeline has finished.' ); }, loop_function : function () { console . log ( 'This loop function will execute after on_timeline_finish.' ); return false ; } }","title":"on_timeline_finish"},{"location":"overview/events/#on_timeline_start","text":"The on_timeline_start callback can be declared in a timeline node. The callback will be triggered when the timeline starts during the experiment, including when timeline_variables , loop_function , or sample options are used. If a conditional_function is used, then the conditional function will execute first, and the on_timeline_start function will only execute if the conditional function returns true . If the repetitions option is used, this function will be triggered at the start of every repetition. var procedure = { timeline : [ trial1 , trial2 ], conditional_function : function () { console . log ( 'This conditional function will execute first.' ) return true ; }, on_timeline_start : function () { console . log ( 'This timeline has started' ); } }","title":"on_timeline_start"},{"location":"overview/events/#on_trial_finish","text":"The on_trial_finish callback can be declared in the initJsPsych method. The callback will trigger at the end of every trial in the experiment. If you want a callback to trigger only for the end of certain trials, use the on_finish callback on the trial object. The callback function will be passed a single argument, containing the data object from the trial. initJsPsych ({ on_trial_finish : function ( data ) { console . log ( 'A trial just ended.' ); console . log ( JSON . stringify ( data )); } });","title":"on_trial_finish"},{"location":"overview/events/#on_trial_start","text":"The on_trial_start callback can be declared in the initJsPsych method. The callback will trigger at the start of every trial in the experiment. The function receives a single argument: a modifiable copy of the trial object that will be used to run the next trial. Changes can be made to this object to alter the parameters of the upcoming trial. var current_score = 0 ; // a variable that is updated throughout the experiment to keep track of the current score. initJsPsych ({ on_trial_start : function ( trial ) { trial . data . score_at_start_of_trial = current_score ; console . log ( 'A trial just started.' ); } });","title":"on_trial_start"},{"location":"overview/exclude-browser/","text":"Exclude Participants Based on Browser Features \u00b6 Changed in 7.1 Online participants will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. As of v7.1 of jsPsych, the recommended way to do this is using the browser-check plugin . This plugin can record many features of the participant's browser and exclude participants who do not meet a defined set of inclusion criteria. Please see the browser-check plugin documentation for more details. The prior approach of using the exclusions parameter in initJsPsych() is deprecated and will be removed in v8.0 . You can find the documentation for it in the 7.0 docs .","title":"Exclude Participants Based on Browser Features"},{"location":"overview/exclude-browser/#exclude-participants-based-on-browser-features","text":"Changed in 7.1 Online participants will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. As of v7.1 of jsPsych, the recommended way to do this is using the browser-check plugin . This plugin can record many features of the participant's browser and exclude participants who do not meet a defined set of inclusion criteria. Please see the browser-check plugin documentation for more details. The prior approach of using the exclusions parameter in initJsPsych() is deprecated and will be removed in v8.0 . You can find the documentation for it in the 7.0 docs .","title":"Exclude Participants Based on Browser Features"},{"location":"overview/experiment-options/","text":"Experiment-wide settings \u00b6 There are several options that can be set when calling initJsPsych() to initialize the jsPsych experiment. Options are specified in the object passed to initJsPsych . For example, to specify a default inter-trial interval, a minimum valid response time duration, and a maximum width for all of the experiment's page content, the object would contain: initJsPsych ({ default_iti : 250 , minimum_valid_rt : 100 , experiment_width : 800 }); Controlling where jsPsych renders on the page \u00b6 By default, jsPsych will render the experiment in the <body> element of a page. It is possible to display the experiment in a different element (e.g., a <div> ) by specifying the display_element parameter. < body > < div id = \"jspsych-target\" ></ div > </ body > < script > initJsPsych ({ display_element : 'jspsych-target' }); </ script > This option is useful if the experiment needs to be rendered on a page with other content (e.g., a demo version of the experiment with annotation text), or if additional control over the display element is desired. Custom CSS rules can be applied to position, size, scale, etc. the display element. Experiment events \u00b6 Several experiment-wide events can trigger functions. This is documented in more detail on the event-related callback functions page . The events that trigger functions are: on_finish : Called at the end of the experiment. on_trial_start : Called at the beginning of every trial. on_trial_finish : Called at the end of every trial. on_data_update : Called whenever new data is added to the jsPsych data object. on_interaction_data_update : Called whenever new interaction data (e.g., the participant enters or exits fullscreen mode) is added. on_close : Called right before the page closes, such as when a participant closes the experiment early. Specify exclusion criteria \u00b6 Exclusion criteria can be specified based on features of the user's web browser, such as the display size and whether certain features are reported. See the page on excluding participants based on browser features . Display a progress bar \u00b6 An automatic or manually updated progress bar can be displayed at the top of the screen. By default, the text next to the progress bar is \"Completion Progress\", but this text can be changed with the message_progress_bar parameter in initJsPsych . See the progress bar page for more details. Choose the method for playing audio files \u00b6 Specifying the use_webaudio parameter in initJsPsych() allows you to choose whether to use the WebAudio API or HTML5 audio for playing audio files during your experiment. By default, jsPsych uses the WebAudio API to play audio files. Among other features, the WebAudio API allows for more precise measurement of response times relative to the onset of the audio. However, loading files through the WebAudio API causes errors when running an experiment offline (i.e., by double-clicking on the HTML file, rather than hosting it on a web server). This is due to the cross-origin security policy implemented by web browsers. For this reason, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline, and automatically uses HTML5 audio to prevent errors, even when use_webaudio has been explicitly set to true . For more information, see the section Cross-origin requests (CORS) and safe mode on the Running Experiments page. initJsPsych ({ use_webaudio : false }); Set the default intertrial interval \u00b6 By default the next trial in a timeline will begin immediately after the conclusion of the previous trial. An experiment-wide delay can be specified using the default_iti parameter to initJsPsych() . initJsPsych ({ default_iti : 500 }); This parameter is specified in milliseconds. A blank screen will display between each trial for the duration of the ITI. Specify the maximum width of the experiment \u00b6 The experiment will, by default, take up 100% of the display element. Usually the display element is the <body> , and the experiment is the full width of the screen. (This can be overridden by specifying the display_element parameter described above). Specifying the experiment_width parameter will set a maximum width for the display. The parameter is specified in pixels. initJsPsych ({ experiment_width : 750 }); Specify a minimum valid response time \u00b6 By default, jsPsych will treat any keyboard response time as valid. However, it's possible to specify a minimum valid response time (in ms) for key presses. Any key press 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. // ignore any keyboard responses that are less than 100 ms initJsPsych ({ minimum_valid_rt : 100 }); Choose whether you want keyboard choices/responses to be case-sensitive \u00b6 JavaScript keyboard events make a distinction between uppercase and lowercase key responses (e.g. 'a' and 'A'). Often the researcher just cares about which physical key was pressed, and not whether the key press would result in an uppercase letter (for instance, if CapsLock is on or if the Shift key is held down). For this reason, jsPsych converts all key choice parameters and key responses as lowercase by default. This makes it easier to specify key choices (e.g. choices: ['a'] , instead of choices: ['a','A'] ), and it makes it easier to check and score a participant's response. There may be situations when you want key choices and responses to be case-sensitive. You can change this by setting the case_sensitive_responses parameter to true in initJsPsych . // use case-sensitive key choices and responses, // i.e. uppercase and lower case letters ('a' and 'A') will be treated as different key choices, // and will be recorded this way in the data initJsPsych ({ case_sensitive_responses : true }); Note that this setting only applies to key choices and responses that use jsPsych's keyboard response listener, such as in the * -keyboard-response plugins. This does NOT apply to responses that are made by typing into a text box, such as in the survey-text and cloze plugins. Override 'safe mode' when running experiments offline \u00b6 By default, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline (via the file:// protocol) in order to prevent certain errors. Specifically, in safe mode, HTML5 audio is used to play audio files (even when use_webaudio has been explicitly set to true ) and video preloading is disabled (both automatic and manual preloading). For more information, see the Cross-origin requests (CORS) and safe mode section on the Running Experiments page. It's possible to override this safe mode feature by setting the override_safe_mode parameter to true in initJsPsych . This is something you might do if you've disabled certain security settings in your browser for testing purposes. This parameter has no effect when your experiment is running online (on a server), because it will be using the http:// or https:// protocol, which does not trigger safe mode. initJsPsych ({ override_safe_mode : true }); Add extensions \u00b6 Extensions are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with initJsPsych . The extensions parameter in initJsPsych is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] });","title":"Experiment Settings"},{"location":"overview/experiment-options/#experiment-wide-settings","text":"There are several options that can be set when calling initJsPsych() to initialize the jsPsych experiment. Options are specified in the object passed to initJsPsych . For example, to specify a default inter-trial interval, a minimum valid response time duration, and a maximum width for all of the experiment's page content, the object would contain: initJsPsych ({ default_iti : 250 , minimum_valid_rt : 100 , experiment_width : 800 });","title":"Experiment-wide settings"},{"location":"overview/experiment-options/#controlling-where-jspsych-renders-on-the-page","text":"By default, jsPsych will render the experiment in the <body> element of a page. It is possible to display the experiment in a different element (e.g., a <div> ) by specifying the display_element parameter. < body > < div id = \"jspsych-target\" ></ div > </ body > < script > initJsPsych ({ display_element : 'jspsych-target' }); </ script > This option is useful if the experiment needs to be rendered on a page with other content (e.g., a demo version of the experiment with annotation text), or if additional control over the display element is desired. Custom CSS rules can be applied to position, size, scale, etc. the display element.","title":"Controlling where jsPsych renders on the page"},{"location":"overview/experiment-options/#experiment-events","text":"Several experiment-wide events can trigger functions. This is documented in more detail on the event-related callback functions page . The events that trigger functions are: on_finish : Called at the end of the experiment. on_trial_start : Called at the beginning of every trial. on_trial_finish : Called at the end of every trial. on_data_update : Called whenever new data is added to the jsPsych data object. on_interaction_data_update : Called whenever new interaction data (e.g., the participant enters or exits fullscreen mode) is added. on_close : Called right before the page closes, such as when a participant closes the experiment early.","title":"Experiment events"},{"location":"overview/experiment-options/#specify-exclusion-criteria","text":"Exclusion criteria can be specified based on features of the user's web browser, such as the display size and whether certain features are reported. See the page on excluding participants based on browser features .","title":"Specify exclusion criteria"},{"location":"overview/experiment-options/#display-a-progress-bar","text":"An automatic or manually updated progress bar can be displayed at the top of the screen. By default, the text next to the progress bar is \"Completion Progress\", but this text can be changed with the message_progress_bar parameter in initJsPsych . See the progress bar page for more details.","title":"Display a progress bar"},{"location":"overview/experiment-options/#choose-the-method-for-playing-audio-files","text":"Specifying the use_webaudio parameter in initJsPsych() allows you to choose whether to use the WebAudio API or HTML5 audio for playing audio files during your experiment. By default, jsPsych uses the WebAudio API to play audio files. Among other features, the WebAudio API allows for more precise measurement of response times relative to the onset of the audio. However, loading files through the WebAudio API causes errors when running an experiment offline (i.e., by double-clicking on the HTML file, rather than hosting it on a web server). This is due to the cross-origin security policy implemented by web browsers. For this reason, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline, and automatically uses HTML5 audio to prevent errors, even when use_webaudio has been explicitly set to true . For more information, see the section Cross-origin requests (CORS) and safe mode on the Running Experiments page. initJsPsych ({ use_webaudio : false });","title":"Choose the method for playing audio files"},{"location":"overview/experiment-options/#set-the-default-intertrial-interval","text":"By default the next trial in a timeline will begin immediately after the conclusion of the previous trial. An experiment-wide delay can be specified using the default_iti parameter to initJsPsych() . initJsPsych ({ default_iti : 500 }); This parameter is specified in milliseconds. A blank screen will display between each trial for the duration of the ITI.","title":"Set the default intertrial interval"},{"location":"overview/experiment-options/#specify-the-maximum-width-of-the-experiment","text":"The experiment will, by default, take up 100% of the display element. Usually the display element is the <body> , and the experiment is the full width of the screen. (This can be overridden by specifying the display_element parameter described above). Specifying the experiment_width parameter will set a maximum width for the display. The parameter is specified in pixels. initJsPsych ({ experiment_width : 750 });","title":"Specify the maximum width of the experiment"},{"location":"overview/experiment-options/#specify-a-minimum-valid-response-time","text":"By default, jsPsych will treat any keyboard response time as valid. However, it's possible to specify a minimum valid response time (in ms) for key presses. Any key press 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. // ignore any keyboard responses that are less than 100 ms initJsPsych ({ minimum_valid_rt : 100 });","title":"Specify a minimum valid response time"},{"location":"overview/experiment-options/#choose-whether-you-want-keyboard-choicesresponses-to-be-case-sensitive","text":"JavaScript keyboard events make a distinction between uppercase and lowercase key responses (e.g. 'a' and 'A'). Often the researcher just cares about which physical key was pressed, and not whether the key press would result in an uppercase letter (for instance, if CapsLock is on or if the Shift key is held down). For this reason, jsPsych converts all key choice parameters and key responses as lowercase by default. This makes it easier to specify key choices (e.g. choices: ['a'] , instead of choices: ['a','A'] ), and it makes it easier to check and score a participant's response. There may be situations when you want key choices and responses to be case-sensitive. You can change this by setting the case_sensitive_responses parameter to true in initJsPsych . // use case-sensitive key choices and responses, // i.e. uppercase and lower case letters ('a' and 'A') will be treated as different key choices, // and will be recorded this way in the data initJsPsych ({ case_sensitive_responses : true }); Note that this setting only applies to key choices and responses that use jsPsych's keyboard response listener, such as in the * -keyboard-response plugins. This does NOT apply to responses that are made by typing into a text box, such as in the survey-text and cloze plugins.","title":"Choose whether you want keyboard choices/responses to be case-sensitive"},{"location":"overview/experiment-options/#override-safe-mode-when-running-experiments-offline","text":"By default, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline (via the file:// protocol) in order to prevent certain errors. Specifically, in safe mode, HTML5 audio is used to play audio files (even when use_webaudio has been explicitly set to true ) and video preloading is disabled (both automatic and manual preloading). For more information, see the Cross-origin requests (CORS) and safe mode section on the Running Experiments page. It's possible to override this safe mode feature by setting the override_safe_mode parameter to true in initJsPsych . This is something you might do if you've disabled certain security settings in your browser for testing purposes. This parameter has no effect when your experiment is running online (on a server), because it will be using the http:// or https:// protocol, which does not trigger safe mode. initJsPsych ({ override_safe_mode : true });","title":"Override 'safe mode' when running experiments offline"},{"location":"overview/experiment-options/#add-extensions","text":"Extensions are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with initJsPsych . The extensions parameter in initJsPsych is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] });","title":"Add extensions"},{"location":"overview/extensions/","text":"Extensions \u00b6 Extensions are jsPsych modules that can interface with any plugin to extend the functionality of the plugin. A canonical example of an extension is eye tracking. An eye tracking extension allows a plugin to gather gaze data and add it to the plugin's data object. Using an Extension \u00b6 To use an extension in an experiment, you'll load the extension file via a <script> tag (just like adding a plugin) and then initialize the extension in the parameters of initJsPsych() . < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-example@1.0.0\" ></ script > </ head > initJsPsych ({ extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }) To enable an extension during a trial, add the extension to the extensions list for the trial. Some extensions may also support or require an object of parameters to configure the extension: var trial = { extensions : [ { type : jsPsychExtensionExample , params : {...} } ] } List of Extensions \u00b6 Extension Description jspsych\u2011ext\u2011webgazer.js Enables eye tracking using the WebGazer library. Writing an Extension \u00b6 See our developer's guide for extensions for information about how to create a new extension.","title":"Extensions"},{"location":"overview/extensions/#extensions","text":"Extensions are jsPsych modules that can interface with any plugin to extend the functionality of the plugin. A canonical example of an extension is eye tracking. An eye tracking extension allows a plugin to gather gaze data and add it to the plugin's data object.","title":"Extensions"},{"location":"overview/extensions/#using-an-extension","text":"To use an extension in an experiment, you'll load the extension file via a <script> tag (just like adding a plugin) and then initialize the extension in the parameters of initJsPsych() . < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-example@1.0.0\" ></ script > </ head > initJsPsych ({ extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }) To enable an extension during a trial, add the extension to the extensions list for the trial. Some extensions may also support or require an object of parameters to configure the extension: var trial = { extensions : [ { type : jsPsychExtensionExample , params : {...} } ] }","title":"Using an Extension"},{"location":"overview/extensions/#list-of-extensions","text":"Extension Description jspsych\u2011ext\u2011webgazer.js Enables eye tracking using the WebGazer library.","title":"List of Extensions"},{"location":"overview/extensions/#writing-an-extension","text":"See our developer's guide for extensions for information about how to create a new extension.","title":"Writing an Extension"},{"location":"overview/eye-tracking/","text":"Eye Tracking \u00b6 jsPsych supports eye tracking through the WebGazer library. WebGazer uses computer vision techniques to identify features of the participant's eyes via a webcam and predicts gaze location. The system is calibrated by having the participant click on or look at known locations on the screen. These locations are linked to eye features. Gaze location is predicted using regression. Getting Started \u00b6 Load webgazer.js \u00b6 The official version of WebGazer is currently not supported by jsPsych. Our fork of the library contains some minor improvements aimed at the kind of experiments that jsPsych is typically used for, e.g., situations in which the timing of display screens needs to be accurate. You must include the webgazer.js file in your experiment via a <script> tag. However, the webgazer.js file is not part of any of the jsPsych NPM packages and is therefore not available via the unpkg.com CDN. Instead, it can be found on the jsdelivr.net CDN at: \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > </ head > Note A copy of our forked webgazer.js file is also included in the jsPsych release, in the /examples/js/webgazer folder. So if you prefer to download and host all of your jsPsych files (i.e. set-up option 2 in the Hello World tutorial), then another option is to load that file rather than using the jsdelivr link above. Assuming you downloaded the release and copied the webgazer.js file into a folder called js/webgazer in your root project directory, then you would load the file like this: < script src = \"js/webgazer/webgazer.js\" ></ script > Load the jsPsych webgazer extension \u00b6 The webgazer extension adds functionality to jsPsych for interacting with webgazer. Load it like you would a plugin file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > </ head > To use the WebGazer extension in an experiment, include it in the list of extensions passed to initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) Initialize the camera \u00b6 To help the participant position their face correctly for eye tracking you can use the webgazer-init-camera plugin . This will show the participant what the camera sees, including facial feature landmarks, and prevent the participant from continuing until their face is in good position for eye tracking. This plugin will also trigger the experiment to request permission to access the user's webcam if it hasn't already been granted. var init_camera_trial = { type : jsPsychWebgazerInitCamera } Calibration \u00b6 To calibrate WebGazer, you can use the webgazer-calibrate plugin . This plugin allows you to specify a set of points on the screen for calibration and to choose the method for calibrating -- either clicking on each point or simply fixating on each point. The location of calibration points is specified in percentages, e.g., [25,50] will result in a point that is 25% of the width of the screen from the left edge and 50% of the height of the screen from the top edge. Options for controlling other details of the calibration are explained in the documentation for the plugin . Note that instructions are not included in the calibration plugin, so you'll likely want to use a different plugin (e.g., html-button-response ) to display instructions prior to running the calibration. var calibration_trial = { type : jsPsychWebgazerCalibrate , calibration_points : [[ 25 , 50 ], [ 50 , 50 ], [ 75 , 50 ], [ 50 , 25 ], [ 50 , 75 ]], calibration_mode : 'click' } Validation \u00b6 To measure the accuracy and precision of the calibration, you can use the webgazer-vaidate plugin . Like the calibration plugin, you can specify a list of points to perform validation on. Here you can specify the points as either percentages or in terms of the distance from the center of the screen in pixels. Which mode you use will probably depend on how you are defining your stimuli throughout the experiment. You can also specify the radius of tolerance around each point, and the plugin will calculate the percentage of measured gaze samples within that radius. This is a potentially useful heuristic for deciding whether or not to calibrate again. Options for controlling other details of the validation are explained in the documentation for the plugin . var validation_trial = { type : jsPsychWebgazerValidate , validation_points : [[ - 200 , 200 ], [ 200 , 200 ],[ - 200 , - 200 ],[ 200 , - 200 ]], validation_point_coordinates : 'center-offset-pixels' , roi_radius : 100 } The validation procedure stores the raw gaze data for each validation point, the computed average offset from each validation point, the percentage of samples within the roi_radius for each validation point, and the number of samples collected per second. { raw_gaze : [...], percent_in_roi : [...], average_offset : [...], samples_per_sec : ... } We recommend performing calibration and validation periodically throughout your experiment. Adding eye tracking to a trial \u00b6 To enable eye tracking for a trial in your experiment, you can simply add the WebGazer extension to the trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img id=\"scene\" src=\"my-scene.png\"></img>' , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#scene' ] } } ] } This will turn on WebGazer at the start of the trial. The params property in the extensions declaration allows you to pass in a list of CSS selector strings . The bounding rectangle of the DOM element that matches each selector will be recorded in the data for that trial. This allows for easy alignment of the gaze data and objects on the screen. webgazer_targets : { 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} } Gaze data will be added to the trial's data under the property webgazer_data . The gaze data is an array of objects. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. Note that establishing the precision and accuracy of these measurements across the variety of web browsers and systems that your experiment participants might be using is quite difficult. For example, different browsers may cause small systematic shifts in the accuracy of t values. webgazer_data : [ { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...} ] Tips for Improving Data Quality \u00b6 These are some anecdotal observations about factors that improve data quality. The quality of the camera feed is essential. Good lighting makes a big difference. You may want to encourage participants to perform any eye tracking experiments in a well-lit room. Participants need to keep their head relatively still during and after calibration. The calibration is not robust to head movements. WebGazer's click-based calibration can be used throughout the experiment. You can turn this on by calling jsPsych.extensions.webgazer.startMouseCalibration() at any point in the experiment. If you use a continue button to advance through the experiment and move the location of the continue button around you can be making small adjustments to the calibration throughout. Computing the gaze predictions consumes more computational resources than most other things that jsPsych is typically used for. The sampling rate that WebGazer is able to achieve will depend on the computing power of the participant's device. You may want to ask the participant to close any non-essential software and browser windows prior to completing the experiment. You may also want to check that the sampling rate is sufficiently high as part of validation. If you have tips based on your own experience please consider sharing them on our discussion forum and we'll add to this list! Example \u00b6 Tip Additional example experiments using WebGazer are available in the /examples folder of the jsPsych release. See webgazer.html , webgazer_image.html , and webgazer_audio.html . Example Here's an example of putting all of the pieces above together. This example also shows how to use data from the validation to decide whether or not to recalibrate. You can try this experiment here (opens in new tab) . <!DOCTYPE html> < html > < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jsPsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" /> < style > . jspsych-btn { margin-bottom : 10 px ; } </ style > </ head > < body ></ body > < script > var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }); var preload = { type : jsPsychPreload , images : [ 'img/blue.png' ] } var camera_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>In order to participate you must allow the experiment to use your camera.</p> <p>You will be prompted to do this on the next screen.</p> <p>If you do not wish to allow use of your camera, you cannot participate in this experiment.<p> <p>It may take up to 30 seconds for the camera to initialize after you give permission.</p> ` , choices : [ 'Got it' ], } var init_camera = { type : jsPsychWebgazerInitCamera } var calibration_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now you'll calibrate the eye tracking, so that the software can use the image of your eyes to predict where you are looking.</p> <p>You'll see a series of dots appear on the screen. Look at each dot and click on it.</p> ` , choices : [ 'Got it' ], } var calibration = { type : jsPsychWebgazerCalibrate , calibration_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], repetitions_per_point : 2 , randomize_calibration_order : true } var validation_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now we'll measure the accuracy of the calibration.</p> <p>Look at each dot as it appears on the screen.</p> <p style=\"font-weight: bold;\">You do not need to click on the dots this time.</p> ` , choices : [ 'Got it' ], post_trial_gap : 1000 } var validation = { type : jsPsychWebgazerValidate , validation_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], roi_radius : 200 , time_to_saccade : 1000 , validation_duration : 2000 , data : { task : 'validate' } } var recalibrate_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>The accuracy of the calibration is a little lower than we'd like.</p> <p>Let's try calibrating one more time.</p> <p>On the next screen, look at the dots and click on them.<p> ` , choices : [ 'OK' ], } var recalibrate = { timeline : [ recalibrate_instructions , calibration , validation_instructions , validation ], conditional_function : function (){ var validation_data = jsPsych . data . get (). filter ({ task : 'validate' }). values ()[ 0 ]; return validation_data . percent_in_roi . some ( function ( x ){ var minimum_percent_acceptable = 50 ; return x < minimum_percent_acceptable ; }); }, data : { phase : 'recalibration' } } var calibration_done = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Great, we're done with calibration!</p> ` , choices : [ 'OK' ] } var begin = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>The next screen will show an image to demonstrate adding the webgazer extension to a trial.</p> <p>Just look at the image while eye tracking data is collected. The trial will end automatically.</p> <p>Press any key to start.</p> ` } var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : \"NO_KEYS\" , trial_duration : 2000 , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#jspsych-image-keyboard-response-stimulus' ]} } ] } var show_data = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trial_data = jsPsych . data . getLastTrialData (). values (); var trial_json = JSON . stringify ( trial_data , null , 2 ); return `<p style=\"margin-bottom:0px;\"><strong>Trial data:</strong></p> <pre style=\"margin-top:0px;text-align:left;\"> ${ trial_json } </pre>` ; }, choices : \"NO_KEYS\" }; jsPsych . run ([ preload , camera_instructions , init_camera , calibration_instructions , calibration , validation_instructions , validation , recalibrate , calibration_done , begin , trial , show_data ]); </ script > </ html > Below is example data from the image-keyboard-response trial taken from the experiment above. In addition to the standard data that is collected for this plugin, you can see the additional webgazer_data and webgazer_targets arrays. The webgazer_data shows 21 gaze location estimates during the 1-second image presentation. The webgazer_targets array shows that there was one target, the image-keyboard-response stimulus, and tells you the x- and y-coordinate boundaries for the target (image) rectangle. By comparing each of the x/y locations from the webgazer_data locations array with the target boundaries in webgazer_targets , you can determine if/when the estimated gaze location was inside the target area. { \"rt\" : null , \"stimulus\" : \"img/blue.png\" , \"response\" : null , \"trial_type\" : \"image-keyboard-response\" , \"trial_index\" : 4 , \"time_elapsed\" : 30701 , \"internal_node_id\" : \"0.0-4.0\" , \"webgazer_data\" : [ { \"x\" : 1065 , \"y\" : 437 , \"t\" : 39 }, { \"x\" : 943 , \"y\" : 377 , \"t\" : 79 }, { \"x\" : 835 , \"y\" : 332 , \"t\" : 110 }, { \"x\" : 731 , \"y\" : 299 , \"t\" : 146 }, { \"x\" : 660 , \"y\" : 271 , \"t\" : 189 }, { \"x\" : 606 , \"y\" : 251 , \"t\" : 238 }, { \"x\" : 582 , \"y\" : 213 , \"t\" : 288 }, { \"x\" : 551 , \"y\" : 200 , \"t\" : 335 }, { \"x\" : 538 , \"y\" : 183 , \"t\" : 394 }, { \"x\" : 514 , \"y\" : 177 , \"t\" : 436 }, { \"x\" : 500 , \"y\" : 171 , \"t\" : 493 }, { \"x\" : 525 , \"y\" : 178 , \"t\" : 542 }, { \"x\" : 537 , \"y\" : 182 , \"t\" : 592 }, { \"x\" : 543 , \"y\" : 178 , \"t\" : 633 }, { \"x\" : 547 , \"y\" : 177 , \"t\" : 691 }, { \"x\" : 558 , \"y\" : 174 , \"t\" : 739 }, { \"x\" : 574 , \"y\" : 183 , \"t\" : 789 }, { \"x\" : 577 , \"y\" : 197 , \"t\" : 838 }, { \"x\" : 584 , \"y\" : 214 , \"t\" : 889 }, { \"x\" : 603 , \"y\" : 218 , \"t\" : 937 }, { \"x\" : 606 , \"y\" : 221 , \"t\" : 987 } ], \"webgazer_targets\" : [ \"#jspsych-image-keyboard-response-stimulus\" : { \"x\" : 490 , \"y\" : 135 , \"height\" : 300 , \"width\" : 300 , \"top\" : 135 , \"bottom\" : 435 , \"left\" : 490 , \"right\" : 790 } ] }","title":"Eye Tracking"},{"location":"overview/eye-tracking/#eye-tracking","text":"jsPsych supports eye tracking through the WebGazer library. WebGazer uses computer vision techniques to identify features of the participant's eyes via a webcam and predicts gaze location. The system is calibrated by having the participant click on or look at known locations on the screen. These locations are linked to eye features. Gaze location is predicted using regression.","title":"Eye Tracking"},{"location":"overview/eye-tracking/#getting-started","text":"","title":"Getting Started"},{"location":"overview/eye-tracking/#load-webgazerjs","text":"The official version of WebGazer is currently not supported by jsPsych. Our fork of the library contains some minor improvements aimed at the kind of experiments that jsPsych is typically used for, e.g., situations in which the timing of display screens needs to be accurate. You must include the webgazer.js file in your experiment via a <script> tag. However, the webgazer.js file is not part of any of the jsPsych NPM packages and is therefore not available via the unpkg.com CDN. Instead, it can be found on the jsdelivr.net CDN at: \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > </ head > Note A copy of our forked webgazer.js file is also included in the jsPsych release, in the /examples/js/webgazer folder. So if you prefer to download and host all of your jsPsych files (i.e. set-up option 2 in the Hello World tutorial), then another option is to load that file rather than using the jsdelivr link above. Assuming you downloaded the release and copied the webgazer.js file into a folder called js/webgazer in your root project directory, then you would load the file like this: < script src = \"js/webgazer/webgazer.js\" ></ script >","title":"Load webgazer.js"},{"location":"overview/eye-tracking/#load-the-jspsych-webgazer-extension","text":"The webgazer extension adds functionality to jsPsych for interacting with webgazer. Load it like you would a plugin file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > </ head > To use the WebGazer extension in an experiment, include it in the list of extensions passed to initJsPsych() initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] })","title":"Load the jsPsych webgazer extension"},{"location":"overview/eye-tracking/#initialize-the-camera","text":"To help the participant position their face correctly for eye tracking you can use the webgazer-init-camera plugin . This will show the participant what the camera sees, including facial feature landmarks, and prevent the participant from continuing until their face is in good position for eye tracking. This plugin will also trigger the experiment to request permission to access the user's webcam if it hasn't already been granted. var init_camera_trial = { type : jsPsychWebgazerInitCamera }","title":"Initialize the camera"},{"location":"overview/eye-tracking/#calibration","text":"To calibrate WebGazer, you can use the webgazer-calibrate plugin . This plugin allows you to specify a set of points on the screen for calibration and to choose the method for calibrating -- either clicking on each point or simply fixating on each point. The location of calibration points is specified in percentages, e.g., [25,50] will result in a point that is 25% of the width of the screen from the left edge and 50% of the height of the screen from the top edge. Options for controlling other details of the calibration are explained in the documentation for the plugin . Note that instructions are not included in the calibration plugin, so you'll likely want to use a different plugin (e.g., html-button-response ) to display instructions prior to running the calibration. var calibration_trial = { type : jsPsychWebgazerCalibrate , calibration_points : [[ 25 , 50 ], [ 50 , 50 ], [ 75 , 50 ], [ 50 , 25 ], [ 50 , 75 ]], calibration_mode : 'click' }","title":"Calibration"},{"location":"overview/eye-tracking/#validation","text":"To measure the accuracy and precision of the calibration, you can use the webgazer-vaidate plugin . Like the calibration plugin, you can specify a list of points to perform validation on. Here you can specify the points as either percentages or in terms of the distance from the center of the screen in pixels. Which mode you use will probably depend on how you are defining your stimuli throughout the experiment. You can also specify the radius of tolerance around each point, and the plugin will calculate the percentage of measured gaze samples within that radius. This is a potentially useful heuristic for deciding whether or not to calibrate again. Options for controlling other details of the validation are explained in the documentation for the plugin . var validation_trial = { type : jsPsychWebgazerValidate , validation_points : [[ - 200 , 200 ], [ 200 , 200 ],[ - 200 , - 200 ],[ 200 , - 200 ]], validation_point_coordinates : 'center-offset-pixels' , roi_radius : 100 } The validation procedure stores the raw gaze data for each validation point, the computed average offset from each validation point, the percentage of samples within the roi_radius for each validation point, and the number of samples collected per second. { raw_gaze : [...], percent_in_roi : [...], average_offset : [...], samples_per_sec : ... } We recommend performing calibration and validation periodically throughout your experiment.","title":"Validation"},{"location":"overview/eye-tracking/#adding-eye-tracking-to-a-trial","text":"To enable eye tracking for a trial in your experiment, you can simply add the WebGazer extension to the trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img id=\"scene\" src=\"my-scene.png\"></img>' , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#scene' ] } } ] } This will turn on WebGazer at the start of the trial. The params property in the extensions declaration allows you to pass in a list of CSS selector strings . The bounding rectangle of the DOM element that matches each selector will be recorded in the data for that trial. This allows for easy alignment of the gaze data and objects on the screen. webgazer_targets : { 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} 'selector' : { x : ..., y : ..., height : ..., width : ..., top : ..., left : ..., right : ..., bottom : ...} } Gaze data will be added to the trial's data under the property webgazer_data . The gaze data is an array of objects. Each object has an x , a y , and a t property. The x and y properties specify the gaze location in pixels and t specifies the time in milliseconds since the start of the trial. Note that establishing the precision and accuracy of these measurements across the variety of web browsers and systems that your experiment participants might be using is quite difficult. For example, different browsers may cause small systematic shifts in the accuracy of t values. webgazer_data : [ { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...}, { x : ..., y : ..., t : ...} ]","title":"Adding eye tracking to a trial"},{"location":"overview/eye-tracking/#tips-for-improving-data-quality","text":"These are some anecdotal observations about factors that improve data quality. The quality of the camera feed is essential. Good lighting makes a big difference. You may want to encourage participants to perform any eye tracking experiments in a well-lit room. Participants need to keep their head relatively still during and after calibration. The calibration is not robust to head movements. WebGazer's click-based calibration can be used throughout the experiment. You can turn this on by calling jsPsych.extensions.webgazer.startMouseCalibration() at any point in the experiment. If you use a continue button to advance through the experiment and move the location of the continue button around you can be making small adjustments to the calibration throughout. Computing the gaze predictions consumes more computational resources than most other things that jsPsych is typically used for. The sampling rate that WebGazer is able to achieve will depend on the computing power of the participant's device. You may want to ask the participant to close any non-essential software and browser windows prior to completing the experiment. You may also want to check that the sampling rate is sufficiently high as part of validation. If you have tips based on your own experience please consider sharing them on our discussion forum and we'll add to this list!","title":"Tips for Improving Data Quality"},{"location":"overview/eye-tracking/#example","text":"Tip Additional example experiments using WebGazer are available in the /examples folder of the jsPsych release. See webgazer.html , webgazer_image.html , and webgazer_audio.html . Example Here's an example of putting all of the pieces above together. This example also shows how to use data from the validation to decide whether or not to recalibrate. You can try this experiment here (opens in new tab) . <!DOCTYPE html> < html > < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" ></ script > < script src = \"https://cdn.jsdelivr.net/gh/jspsych/jsPsych@jspsych@7.1.2/examples/js/webgazer/webgazer.js\" ></ script > < script src = \"https://unpkg.com/@jspsych/extension-webgazer@1.0.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" /> < style > . jspsych-btn { margin-bottom : 10 px ; } </ style > </ head > < body ></ body > < script > var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }); var preload = { type : jsPsychPreload , images : [ 'img/blue.png' ] } var camera_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>In order to participate you must allow the experiment to use your camera.</p> <p>You will be prompted to do this on the next screen.</p> <p>If you do not wish to allow use of your camera, you cannot participate in this experiment.<p> <p>It may take up to 30 seconds for the camera to initialize after you give permission.</p> ` , choices : [ 'Got it' ], } var init_camera = { type : jsPsychWebgazerInitCamera } var calibration_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now you'll calibrate the eye tracking, so that the software can use the image of your eyes to predict where you are looking.</p> <p>You'll see a series of dots appear on the screen. Look at each dot and click on it.</p> ` , choices : [ 'Got it' ], } var calibration = { type : jsPsychWebgazerCalibrate , calibration_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], repetitions_per_point : 2 , randomize_calibration_order : true } var validation_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Now we'll measure the accuracy of the calibration.</p> <p>Look at each dot as it appears on the screen.</p> <p style=\"font-weight: bold;\">You do not need to click on the dots this time.</p> ` , choices : [ 'Got it' ], post_trial_gap : 1000 } var validation = { type : jsPsychWebgazerValidate , validation_points : [ [ 25 , 25 ],[ 75 , 25 ],[ 50 , 50 ],[ 25 , 75 ],[ 75 , 75 ] ], roi_radius : 200 , time_to_saccade : 1000 , validation_duration : 2000 , data : { task : 'validate' } } var recalibrate_instructions = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>The accuracy of the calibration is a little lower than we'd like.</p> <p>Let's try calibrating one more time.</p> <p>On the next screen, look at the dots and click on them.<p> ` , choices : [ 'OK' ], } var recalibrate = { timeline : [ recalibrate_instructions , calibration , validation_instructions , validation ], conditional_function : function (){ var validation_data = jsPsych . data . get (). filter ({ task : 'validate' }). values ()[ 0 ]; return validation_data . percent_in_roi . some ( function ( x ){ var minimum_percent_acceptable = 50 ; return x < minimum_percent_acceptable ; }); }, data : { phase : 'recalibration' } } var calibration_done = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Great, we're done with calibration!</p> ` , choices : [ 'OK' ] } var begin = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>The next screen will show an image to demonstrate adding the webgazer extension to a trial.</p> <p>Just look at the image while eye tracking data is collected. The trial will end automatically.</p> <p>Press any key to start.</p> ` } var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : \"NO_KEYS\" , trial_duration : 2000 , extensions : [ { type : jsPsychExtensionWebgazer , params : { targets : [ '#jspsych-image-keyboard-response-stimulus' ]} } ] } var show_data = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trial_data = jsPsych . data . getLastTrialData (). values (); var trial_json = JSON . stringify ( trial_data , null , 2 ); return `<p style=\"margin-bottom:0px;\"><strong>Trial data:</strong></p> <pre style=\"margin-top:0px;text-align:left;\"> ${ trial_json } </pre>` ; }, choices : \"NO_KEYS\" }; jsPsych . run ([ preload , camera_instructions , init_camera , calibration_instructions , calibration , validation_instructions , validation , recalibrate , calibration_done , begin , trial , show_data ]); </ script > </ html > Below is example data from the image-keyboard-response trial taken from the experiment above. In addition to the standard data that is collected for this plugin, you can see the additional webgazer_data and webgazer_targets arrays. The webgazer_data shows 21 gaze location estimates during the 1-second image presentation. The webgazer_targets array shows that there was one target, the image-keyboard-response stimulus, and tells you the x- and y-coordinate boundaries for the target (image) rectangle. By comparing each of the x/y locations from the webgazer_data locations array with the target boundaries in webgazer_targets , you can determine if/when the estimated gaze location was inside the target area. { \"rt\" : null , \"stimulus\" : \"img/blue.png\" , \"response\" : null , \"trial_type\" : \"image-keyboard-response\" , \"trial_index\" : 4 , \"time_elapsed\" : 30701 , \"internal_node_id\" : \"0.0-4.0\" , \"webgazer_data\" : [ { \"x\" : 1065 , \"y\" : 437 , \"t\" : 39 }, { \"x\" : 943 , \"y\" : 377 , \"t\" : 79 }, { \"x\" : 835 , \"y\" : 332 , \"t\" : 110 }, { \"x\" : 731 , \"y\" : 299 , \"t\" : 146 }, { \"x\" : 660 , \"y\" : 271 , \"t\" : 189 }, { \"x\" : 606 , \"y\" : 251 , \"t\" : 238 }, { \"x\" : 582 , \"y\" : 213 , \"t\" : 288 }, { \"x\" : 551 , \"y\" : 200 , \"t\" : 335 }, { \"x\" : 538 , \"y\" : 183 , \"t\" : 394 }, { \"x\" : 514 , \"y\" : 177 , \"t\" : 436 }, { \"x\" : 500 , \"y\" : 171 , \"t\" : 493 }, { \"x\" : 525 , \"y\" : 178 , \"t\" : 542 }, { \"x\" : 537 , \"y\" : 182 , \"t\" : 592 }, { \"x\" : 543 , \"y\" : 178 , \"t\" : 633 }, { \"x\" : 547 , \"y\" : 177 , \"t\" : 691 }, { \"x\" : 558 , \"y\" : 174 , \"t\" : 739 }, { \"x\" : 574 , \"y\" : 183 , \"t\" : 789 }, { \"x\" : 577 , \"y\" : 197 , \"t\" : 838 }, { \"x\" : 584 , \"y\" : 214 , \"t\" : 889 }, { \"x\" : 603 , \"y\" : 218 , \"t\" : 937 }, { \"x\" : 606 , \"y\" : 221 , \"t\" : 987 } ], \"webgazer_targets\" : [ \"#jspsych-image-keyboard-response-stimulus\" : { \"x\" : 490 , \"y\" : 135 , \"height\" : 300 , \"width\" : 300 , \"top\" : 135 , \"bottom\" : 435 , \"left\" : 490 , \"right\" : 790 } ] }","title":"Example"},{"location":"overview/fullscreen/","text":"Fullscreen Experiments \u00b6 You can run your experiment in fullscreen mode by using the jspsych-fullscreen plugin. var jsPsych = initJsPsych (); var timeline = []; timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : true }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be in fullscreen mode.' }); // exit fullscreen mode timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : false }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will NOT be in fullscreen mode.' }); jsPsych . run ( timeline ); For security reasons, web browsers require that users initiate an action to launch fullscreen mode. The fullscreen plugin displays a button that the user must click to change the display to fullscreen. Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"Fullscreen Experiments"},{"location":"overview/fullscreen/#fullscreen-experiments","text":"You can run your experiment in fullscreen mode by using the jspsych-fullscreen plugin. var jsPsych = initJsPsych (); var timeline = []; timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : true }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be in fullscreen mode.' }); // exit fullscreen mode timeline . push ({ type : jsPsychFullscreen , fullscreen_mode : false }); timeline . push ({ type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will NOT be in fullscreen mode.' }); jsPsych . run ( timeline ); For security reasons, web browsers require that users initiate an action to launch fullscreen mode. The fullscreen plugin displays a button that the user must click to change the display to fullscreen. Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"Fullscreen Experiments"},{"location":"overview/media-preloading/","text":"Media Preloading \u00b6 If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the jsPsych preload plugin . Preloading files means that the participant's browser will download the files and store them in local memory on the participant's computer. This is important because displaying or playing a media file is much faster if it is already in memory on the participant's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a participant's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment. Warning Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The Cross-origin requests (CORS) and safe mode section on the Running Experiments page contains more information about this. Automatic Preloading \u00b6 jsPsych can automatically preload audio, video, and image files that are used as parameters for the standard set of plugins, based on the timeline that is passed to jsPsych.run . You must initiate this preloading using a preload trial. You should add this preload trial into your timeline when you want the preloading to occur, and set the auto_preload parameter to true . // the \"auto_preload: true\" setting tells the plugin to automatically find // stimuli to preload based the main experiment timeline (used in jsPsych.run) var preload = { type : jsPsychPreload , auto_preload : true } // this image file can be automatically preloaded var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // the sound file can be automatically preloaded var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // the video file can be automatically preloaded (as long as the experiment // is running on a server) var video_trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/sample_video.mp4' ] } jsPsych . run ([ preload , image_trial , sound_trial , video_trial ]); Manual preloading \u00b6 If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the media files, you are using timeline variables, or you are embedding the media files in an HTML string), then these files will not be detected when you use the auto_preload option, so you must manually specify them. The preload plugin allows you to add these files using the images , audio and video parameters. // this image file cannot be automatically preloaded because it is embedded in // an HTML string var image_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img src=\"img/file1.png\"></img>' , } // this audio file cannot be automatically preloaded because it is returned // from a function var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : function () { return 'audio/sound1.mp3' } } // these video files cannot be automatically preloaded because they are passed // into a trial using the jsPsych.timelineVariable function var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } // to manually preload media files, create an array of file paths for each // media type var images = [ 'img/file1.png' ]; var audio = [ 'audio/sound1.mp3' ]; var video = [ 'video/1.mp4' , 'video/2.mp4' ]; // these array can be passed into the preload plugin using the images, audio // and video parameters var preload = { type : jsPsychPreload , images : images , audio : audio , video : video } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]); Combining automatic and manual preloading \u00b6 It's possible to combine automatic and manual preloading. For instance, you may want to automatically preload all of the media files based on your experiment timeline, while also manually preloading any files that can't be automatically preloaded. Any duplicate file names across all preloading methods will be removed before preloading starts, so including the same file names in multiple preload parameters will not affect the preloading duration. // this file can be preloaded automatically var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // this file can be preloaded automatically var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // these files must be preloaded manually var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } var video = [ 'video/1.mp4' , 'video/2.mp4' ]; var preload = { type : jsPsychPreload , auto_preload : true , // automatically preload the image and audio files video : video // manually preload the videos used with timeline variables } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]); Preloading in batches \u00b6 Some experiments use many and/or large media files. This can cause problems when participants have slow and/or unreliable internet connections, because it increases the chances of loading errors during preloading. This can also cause problems with file caching, i.e. ensuring that the preloaded files remain in the browser's memory, because loading all stimuli at once may exceed the browser's cache limits. One option for mitigating these problems is to load the media files in smaller batches throughout the experiment. Files should be preloaded as close as possible to when they will be needed. For instance, if you have several blocks of trials, then right before each block, you can preload the stimuli that are needed for that block. Here is an example with trials where the stimuli files can be preloaded automatically. In this case, the trials parameter is used to tell the preload plugin to preload the stimuli from a specific part of the timeline. // these image files in these trial blocks can be automatically preloaded var block_1 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file2.png' } ] } var block_2 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file3.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file4.png' } ] } var preload_1 = { type : jsPsychPreload , trials : block_1 // automatically preload just the images from block_1 trials } var preload_2 = { type : jsPsychPreload , trials : block_2 // automatically preload just the images from block_2 trials } jsPsych . run ( // add each preload trial onto the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Below is an example with trials where the stimuli files cannot be preloaded automatically, because the stimuli files are passed to the trials via jsPsych.timelineVariable . In this case, we create separate arrays for each batch of files, and then pass those arrays to the each preload trial. // these trial blocks cannot be automatically preloaded because // the media files are passed to the trial parameters with timeline variables var block_1 = { timeline : [...], timeline_variables : [ { stim : 'file1.png' }, { stim : 'file1.png' } ] } var block_2 = { timeline : [...], timeline_variables : [ { stim : 'file3.png' }, { stim : 'file4.png' } ] } var images_block_1 = [ 'file1.png' , 'file2.png' ]; var images_block_2 = [ 'file3.png' , 'file4.png' ]; // preload trial for preloading the block 1 stimuli var preload_1 = { type : jsPsychPreload , images : images_block_1 } // preload trial for preloading the block 2 stimuli var preload_2 = { type : jsPsychPreload , images : images_block_2 } jsPsych . run ( // add each preload trial to the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Preloading progress bar \u00b6 By default, the preload plugin will display a progress bar while files are being preloaded. This progress bar represents all files that are being preloaded during the trial, regardless of whether the file is being preloaded automatically via the auto_preload or trials parameters, or manually via the audio , images , and video parameters. You may wish to turn the preload progress bar off if you are only loading a small number of files, as it will appear and disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the show_progress_bar parameter in the preload trial. var preload_trial = { type : jsPsychPreload , auto_preload : true show_progress_bar : false // hide progress bar } Loading time limits \u00b6 It's usually a good idea to set a time limit for file loading, to ensure that participants aren't waiting for an unreasonable amount of time. Time limits can be specified in milliseconds using the max_load_time parameter. If you set a loading time limit and all files haven't finished loading before this time, then the preload trial will either stop an error (if continue_after_error is false, the default) or the trial will end and the experiment will continue (if continue_after_error is true ). If max_load_time is null (the default), then there is no time limit. var preload_trial = { type : jsPsychPreload , auto_preload : true max_load_time : 60000 // 1 minute } Loading and error messages \u00b6 It's possible to specify custom messages to be shown on the page while the media files are loading, and in case of one or more file loading errors. The message parameter allows you to customize the loading message using an HML-formatted string. If show_progress_bar is true , then this message will be shown above the progress bar. var preload_trial = { type : jsPsychPreload , auto_preload : true message : 'Please wait while the experiment loads. This may take a few minutes.' , } A preloading error will occur when either (a) one or more files produces a loading error, and/or (b) all files have not finished loading before the max_load_time duration. The error_message parameter allows you to customize the messsage that's shown on the page in these cases. This message will only be shown if continue_after_error is false (the default). var preload_trial = { type : jsPsychPreload , auto_preload : true , error_message : 'The experiment failed to load. Please contact the researcher.' } In addition to the error_message parameter, it's also possible to show more detailed error messages on the page about any files that failed to load. You can control this with the show_detailed_errors parameter. Detailed error messages will appear below the general error message. This only applies if continue_after_error is false (the default). Detailed error messages can be useful when testing and debugging your experiment. If show_detailed_errors is true , then if one or more loading errors occurs before the max_load_time is reached, then the error page will also contian a list of the file(s) that produced an error, along with error information (if there is any). Note that this may not be a complete list, because it will only report any errors that occurred before the max_load_time was reached. If there are no file loading errors but preloading hasn't finished before the max_load_time , then detailed error message will just tell you that loading timed out. var preload_trial = { type : jsPsychPreload , auto_preload : true , // show details of any file loading errors and/or loading time out show_detailed_errors : true } Options for handling errors \u00b6 If continue_after_error is true , then the experiment will not stop if one or more files fails to load. Instead, the trial will end and the experiment will continue. However, the preload trial data will contain a property called success , which is whether or not all files were loaded successfully, timeout , which is whether or not the files loaded successfully before the max_load_time . The preload trial data will also contain lists of any image , audio , and video files that failed to load. This gives you the option to continue the experiment after preloading fails and use the preload trial data decide what to do next. For instance, you may decide to skip the trials that use the stimuli files that failed to load, or try loading the failed files again. Another option is to simply end the experiment when preloading fails, but send the data back to your server so that you have more information about the loading failure. var preload_trial = { type : jsPsychPreload , auto_preload : true , message : 'Please wait while the experiment loads...' , // don't stop the experiment if there are file loading errors or if loading times out continue_after_error : true } var save_data = { type : jsPsychCallFunction , async : true , func : function ( done ){ var data = jsPsych . data . get (). json (); save_data ( data , function () { done ()}) } } // the experiment will stop here, since there are no valid key choices or trial duration var fail_message = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The experiment failed to load. Please contact the researcher.' , choices : \"NO_KEYS\" , trial_duration : null } var if_loading_fails = { timeline : [ save_data , fail_message ], conditional_function : function () { if ( jsPsych . data . getLastTrialData ()[ 0 ]. values (). success ) { // preloading was successful, so skip this conditional timeline // and move on with the experiment return false ; } else { // preloading failed, so run this conditional timeline: // save the data to the server and show the fail message return true ; } } } // ... rest of experiment jsPsych . run ([ preload_trial , if_loading_fails , ... ]) The preload plugin's on_success and on_error callback functions provide another way of tracking preloading progress and handling file loading errors. These functions are called after any file either loads successfully or produces an error, respectively. These functions receive a single argument, which is the path of the file (string) that loaded or produced an error. var file_load_count = 0 ; var file_error_count = 0 ; var preload_trial = { type : jsPsychPreload , auto_preload : true , on_error : function ( file ) { file_error_count ++ ; console . log ( 'Error: ' , file ); }, on_success : function ( file ) { file_load_count ++ ; console . log ( 'Loaded: ' , file ); } }; Note that there's no guarantee that any/all files will trigger one of these two callback functions, because they are cancelled after the preload trial ends. For instance, if a file takes longer to load then the max_load_time , then the preload trial will end due to timing out, and the on_success and on_error callbacks for any in-progress files will be cancelled.","title":"Media Preloading"},{"location":"overview/media-preloading/#media-preloading","text":"If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the jsPsych preload plugin . Preloading files means that the participant's browser will download the files and store them in local memory on the participant's computer. This is important because displaying or playing a media file is much faster if it is already in memory on the participant's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a participant's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment. Warning Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The Cross-origin requests (CORS) and safe mode section on the Running Experiments page contains more information about this.","title":"Media Preloading"},{"location":"overview/media-preloading/#automatic-preloading","text":"jsPsych can automatically preload audio, video, and image files that are used as parameters for the standard set of plugins, based on the timeline that is passed to jsPsych.run . You must initiate this preloading using a preload trial. You should add this preload trial into your timeline when you want the preloading to occur, and set the auto_preload parameter to true . // the \"auto_preload: true\" setting tells the plugin to automatically find // stimuli to preload based the main experiment timeline (used in jsPsych.run) var preload = { type : jsPsychPreload , auto_preload : true } // this image file can be automatically preloaded var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // the sound file can be automatically preloaded var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // the video file can be automatically preloaded (as long as the experiment // is running on a server) var video_trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/sample_video.mp4' ] } jsPsych . run ([ preload , image_trial , sound_trial , video_trial ]);","title":"Automatic Preloading"},{"location":"overview/media-preloading/#manual-preloading","text":"If you are using media files in your experiment but they are not being passed directly as parameters to the trials (e.g., because you are using functions as parameters that return the media files, you are using timeline variables, or you are embedding the media files in an HTML string), then these files will not be detected when you use the auto_preload option, so you must manually specify them. The preload plugin allows you to add these files using the images , audio and video parameters. // this image file cannot be automatically preloaded because it is embedded in // an HTML string var image_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<img src=\"img/file1.png\"></img>' , } // this audio file cannot be automatically preloaded because it is returned // from a function var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : function () { return 'audio/sound1.mp3' } } // these video files cannot be automatically preloaded because they are passed // into a trial using the jsPsych.timelineVariable function var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } // to manually preload media files, create an array of file paths for each // media type var images = [ 'img/file1.png' ]; var audio = [ 'audio/sound1.mp3' ]; var video = [ 'video/1.mp4' , 'video/2.mp4' ]; // these array can be passed into the preload plugin using the images, audio // and video parameters var preload = { type : jsPsychPreload , images : images , audio : audio , video : video } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]);","title":"Manual preloading"},{"location":"overview/media-preloading/#combining-automatic-and-manual-preloading","text":"It's possible to combine automatic and manual preloading. For instance, you may want to automatically preload all of the media files based on your experiment timeline, while also manually preloading any files that can't be automatically preloaded. Any duplicate file names across all preloading methods will be removed before preloading starts, so including the same file names in multiple preload parameters will not affect the preloading duration. // this file can be preloaded automatically var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' } // this file can be preloaded automatically var sound_trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'audio/hello.mp3' } // these files must be preloaded manually var video_trials = { timeline : [ { type : jsPsychVideoKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'video' ) } ], timeline_variables : [ { video : [ 'video/1.mp4' ]}, { video : [ 'video/2.mp4' ]} ] } var video = [ 'video/1.mp4' , 'video/2.mp4' ]; var preload = { type : jsPsychPreload , auto_preload : true , // automatically preload the image and audio files video : video // manually preload the videos used with timeline variables } jsPsych . run ([ preload , image_trial , sound_trial , video_trials ]);","title":"Combining automatic and manual preloading"},{"location":"overview/media-preloading/#preloading-in-batches","text":"Some experiments use many and/or large media files. This can cause problems when participants have slow and/or unreliable internet connections, because it increases the chances of loading errors during preloading. This can also cause problems with file caching, i.e. ensuring that the preloaded files remain in the browser's memory, because loading all stimuli at once may exceed the browser's cache limits. One option for mitigating these problems is to load the media files in smaller batches throughout the experiment. Files should be preloaded as close as possible to when they will be needed. For instance, if you have several blocks of trials, then right before each block, you can preload the stimuli that are needed for that block. Here is an example with trials where the stimuli files can be preloaded automatically. In this case, the trials parameter is used to tell the preload plugin to preload the stimuli from a specific part of the timeline. // these image files in these trial blocks can be automatically preloaded var block_1 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file1.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file2.png' } ] } var block_2 = { timeline : [ { type : jsPsychImageKeyboardResponse , stimulus : 'img/file3.png' }, { type : jsPsychImageKeyboardResponse , stimulus : 'img/file4.png' } ] } var preload_1 = { type : jsPsychPreload , trials : block_1 // automatically preload just the images from block_1 trials } var preload_2 = { type : jsPsychPreload , trials : block_2 // automatically preload just the images from block_2 trials } jsPsych . run ( // add each preload trial onto the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] ); Below is an example with trials where the stimuli files cannot be preloaded automatically, because the stimuli files are passed to the trials via jsPsych.timelineVariable . In this case, we create separate arrays for each batch of files, and then pass those arrays to the each preload trial. // these trial blocks cannot be automatically preloaded because // the media files are passed to the trial parameters with timeline variables var block_1 = { timeline : [...], timeline_variables : [ { stim : 'file1.png' }, { stim : 'file1.png' } ] } var block_2 = { timeline : [...], timeline_variables : [ { stim : 'file3.png' }, { stim : 'file4.png' } ] } var images_block_1 = [ 'file1.png' , 'file2.png' ]; var images_block_2 = [ 'file3.png' , 'file4.png' ]; // preload trial for preloading the block 1 stimuli var preload_1 = { type : jsPsychPreload , images : images_block_1 } // preload trial for preloading the block 2 stimuli var preload_2 = { type : jsPsychPreload , images : images_block_2 } jsPsych . run ( // add each preload trial to the timeline before the appropriate trial block [ preload_1 , block_1 , preload_2 , block_2 ] );","title":"Preloading in batches"},{"location":"overview/media-preloading/#preloading-progress-bar","text":"By default, the preload plugin will display a progress bar while files are being preloaded. This progress bar represents all files that are being preloaded during the trial, regardless of whether the file is being preloaded automatically via the auto_preload or trials parameters, or manually via the audio , images , and video parameters. You may wish to turn the preload progress bar off if you are only loading a small number of files, as it will appear and disappear so quickly that the participant may be confused about what it was. You can control whether the preloading progress bar appears by setting the show_progress_bar parameter in the preload trial. var preload_trial = { type : jsPsychPreload , auto_preload : true show_progress_bar : false // hide progress bar }","title":"Preloading progress bar"},{"location":"overview/media-preloading/#loading-time-limits","text":"It's usually a good idea to set a time limit for file loading, to ensure that participants aren't waiting for an unreasonable amount of time. Time limits can be specified in milliseconds using the max_load_time parameter. If you set a loading time limit and all files haven't finished loading before this time, then the preload trial will either stop an error (if continue_after_error is false, the default) or the trial will end and the experiment will continue (if continue_after_error is true ). If max_load_time is null (the default), then there is no time limit. var preload_trial = { type : jsPsychPreload , auto_preload : true max_load_time : 60000 // 1 minute }","title":"Loading time limits"},{"location":"overview/media-preloading/#loading-and-error-messages","text":"It's possible to specify custom messages to be shown on the page while the media files are loading, and in case of one or more file loading errors. The message parameter allows you to customize the loading message using an HML-formatted string. If show_progress_bar is true , then this message will be shown above the progress bar. var preload_trial = { type : jsPsychPreload , auto_preload : true message : 'Please wait while the experiment loads. This may take a few minutes.' , } A preloading error will occur when either (a) one or more files produces a loading error, and/or (b) all files have not finished loading before the max_load_time duration. The error_message parameter allows you to customize the messsage that's shown on the page in these cases. This message will only be shown if continue_after_error is false (the default). var preload_trial = { type : jsPsychPreload , auto_preload : true , error_message : 'The experiment failed to load. Please contact the researcher.' } In addition to the error_message parameter, it's also possible to show more detailed error messages on the page about any files that failed to load. You can control this with the show_detailed_errors parameter. Detailed error messages will appear below the general error message. This only applies if continue_after_error is false (the default). Detailed error messages can be useful when testing and debugging your experiment. If show_detailed_errors is true , then if one or more loading errors occurs before the max_load_time is reached, then the error page will also contian a list of the file(s) that produced an error, along with error information (if there is any). Note that this may not be a complete list, because it will only report any errors that occurred before the max_load_time was reached. If there are no file loading errors but preloading hasn't finished before the max_load_time , then detailed error message will just tell you that loading timed out. var preload_trial = { type : jsPsychPreload , auto_preload : true , // show details of any file loading errors and/or loading time out show_detailed_errors : true }","title":"Loading and error messages"},{"location":"overview/media-preloading/#options-for-handling-errors","text":"If continue_after_error is true , then the experiment will not stop if one or more files fails to load. Instead, the trial will end and the experiment will continue. However, the preload trial data will contain a property called success , which is whether or not all files were loaded successfully, timeout , which is whether or not the files loaded successfully before the max_load_time . The preload trial data will also contain lists of any image , audio , and video files that failed to load. This gives you the option to continue the experiment after preloading fails and use the preload trial data decide what to do next. For instance, you may decide to skip the trials that use the stimuli files that failed to load, or try loading the failed files again. Another option is to simply end the experiment when preloading fails, but send the data back to your server so that you have more information about the loading failure. var preload_trial = { type : jsPsychPreload , auto_preload : true , message : 'Please wait while the experiment loads...' , // don't stop the experiment if there are file loading errors or if loading times out continue_after_error : true } var save_data = { type : jsPsychCallFunction , async : true , func : function ( done ){ var data = jsPsych . data . get (). json (); save_data ( data , function () { done ()}) } } // the experiment will stop here, since there are no valid key choices or trial duration var fail_message = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The experiment failed to load. Please contact the researcher.' , choices : \"NO_KEYS\" , trial_duration : null } var if_loading_fails = { timeline : [ save_data , fail_message ], conditional_function : function () { if ( jsPsych . data . getLastTrialData ()[ 0 ]. values (). success ) { // preloading was successful, so skip this conditional timeline // and move on with the experiment return false ; } else { // preloading failed, so run this conditional timeline: // save the data to the server and show the fail message return true ; } } } // ... rest of experiment jsPsych . run ([ preload_trial , if_loading_fails , ... ]) The preload plugin's on_success and on_error callback functions provide another way of tracking preloading progress and handling file loading errors. These functions are called after any file either loads successfully or produces an error, respectively. These functions receive a single argument, which is the path of the file (string) that loaded or produced an error. var file_load_count = 0 ; var file_error_count = 0 ; var preload_trial = { type : jsPsychPreload , auto_preload : true , on_error : function ( file ) { file_error_count ++ ; console . log ( 'Error: ' , file ); }, on_success : function ( file ) { file_load_count ++ ; console . log ( 'Loaded: ' , file ); } }; Note that there's no guarantee that any/all files will trigger one of these two callback functions, because they are cancelled after the preload trial ends. For instance, if a file takes longer to load then the max_load_time , then the preload trial will end due to timing out, and the on_success and on_error callbacks for any in-progress files will be cancelled.","title":"Options for handling errors"},{"location":"overview/mturk/","text":"Integrating with Mechanical Turk \u00b6 A common use of jsPsych is to build an online experiment and find participants using Mechanical Turk . Once an experiment is available through a web server and data is being saved on the server , connecting the experiment with Mechanical Turk takes only a few additional steps. jsPsych has some built-in functionality to assist with this process. The jsPsych.turk module \u00b6 The jsPsych.turk module contains functions that are relevant for experiments running on Mechanical Turk. Creating an advertisement page \u00b6 When potential participants view your experiment on Mechanical Turk, they will be able to see a single webpage before deciding whether or not to accept the HIT (start the experiment). This first page is often used as an advertisement for the experiment, similar to posting a flier in a department hallway. The important thing to remember about this page is that potential participants will be able to interact with it even if they haven't accepted the HIT. Therefore, it can be useful to change the content of the page depending on whether the HIT has been accepted or not. This is relatively easy to do: < div id = \"experiment_link\" > You must accept the HIT to begin the experiment </ div > . < script > // jsPsych has a method turkInfo() which can determine whether or not the // HIT has been accepted. var turkInfo = jsPsych . turkInfo (); // turkInfo.previewMode is true in two cases: when the HIT has not been // accepted yet OR when the page is viewed outside of mechanical turk. // The second property, outsideTurk, is true when the page is viewed // outside of mechanical turk, so together, the statement will be true // only when in Turk and when the HIT is not accepted yet. if ( ! turkInfo . previewMode && ! turkInfo . outsideTurk ) { document . querySelector ( '#experiment_link' ). innerHMTL = '<a href=\"link_to_experiment.html\" target=\"_blank\">Click Here to Start Experiment</a>' ; } </ script > One important issue with advertisement pages is that they must be served using the https protocol, which requires having an SSL certificate on the web server hosting the page. Instructions for how to do this vary depending on what kind of server you are using, so the best advice is to simply Google for instructions on how to acquire and install an SSL certificate on your particular server. Getting the worker ID \u00b6 Every account on Mechanical Turk is given a unique identification string. Recording this ID is a useful way to keep track of who is doing your experiment. In particular, while Turk has built in tools for preventing the same person from doing a HIT more than once, there may be cases where you don't want participants to complete related experiments. If you store the worker ID of every person who starts an experiment in a database, then you can exclude people by running a query on the database to check for the ID. jsPsych can get the workerID, assignmentID, and hitID with the turkInfo method. var turkInfo = jsPsych . turk . turkInfo (); // workerID turkInfo . workerId // hitID turkInfo . hitId // assignmentID turkInfo . assignmentId Recording the workerId at the start of the experiment is also a good way to track dropouts. Submitting results to Mechanical Turk \u00b6 If you are running a HIT on Mechanical Turk using the ExternalQuestion template, then you'll need to provide a way for participants to indicate that they have completed the HIT. (If you are using another template, then the template will provide this code for you). jsPSych makes this a relatively easy task. A common strategy for external HITs is to display an HTML page on the Mechanical Turk website that links to your HIT. Participants click the link, which opens the actual experiment content in a new browser window or tab, allowing the experiment to take up the whole browser window instead of just the iframe that displays content on Mechanical Turk. On this page, you might include a submit button for workers to indicate that they have finished the experiment. The page would look something like this: < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > When workers click the button, the contents of the code text field will be sent to Mechanical Turk, and you'll be able to view the participants and the codes that they entered in the Mechanical Turk GUI. You can then approve or reject work using the Mechanical Turk website. Limitations \u00b6 jsPsych is not designed to communicate with the Mechanical Turk API in a comprehensive manner. If you are looking for software to help you post and manage HITs, then you may want to look at PsiTurk . jsPsych and PsiTurk complement each other nicely, and there is an example of combining the two platforms on PsiTurk's experiment exchange.","title":"Integrating with Mechanical Turk"},{"location":"overview/mturk/#integrating-with-mechanical-turk","text":"A common use of jsPsych is to build an online experiment and find participants using Mechanical Turk . Once an experiment is available through a web server and data is being saved on the server , connecting the experiment with Mechanical Turk takes only a few additional steps. jsPsych has some built-in functionality to assist with this process.","title":"Integrating with Mechanical Turk"},{"location":"overview/mturk/#the-jspsychturk-module","text":"The jsPsych.turk module contains functions that are relevant for experiments running on Mechanical Turk.","title":"The jsPsych.turk module"},{"location":"overview/mturk/#creating-an-advertisement-page","text":"When potential participants view your experiment on Mechanical Turk, they will be able to see a single webpage before deciding whether or not to accept the HIT (start the experiment). This first page is often used as an advertisement for the experiment, similar to posting a flier in a department hallway. The important thing to remember about this page is that potential participants will be able to interact with it even if they haven't accepted the HIT. Therefore, it can be useful to change the content of the page depending on whether the HIT has been accepted or not. This is relatively easy to do: < div id = \"experiment_link\" > You must accept the HIT to begin the experiment </ div > . < script > // jsPsych has a method turkInfo() which can determine whether or not the // HIT has been accepted. var turkInfo = jsPsych . turkInfo (); // turkInfo.previewMode is true in two cases: when the HIT has not been // accepted yet OR when the page is viewed outside of mechanical turk. // The second property, outsideTurk, is true when the page is viewed // outside of mechanical turk, so together, the statement will be true // only when in Turk and when the HIT is not accepted yet. if ( ! turkInfo . previewMode && ! turkInfo . outsideTurk ) { document . querySelector ( '#experiment_link' ). innerHMTL = '<a href=\"link_to_experiment.html\" target=\"_blank\">Click Here to Start Experiment</a>' ; } </ script > One important issue with advertisement pages is that they must be served using the https protocol, which requires having an SSL certificate on the web server hosting the page. Instructions for how to do this vary depending on what kind of server you are using, so the best advice is to simply Google for instructions on how to acquire and install an SSL certificate on your particular server.","title":"Creating an advertisement page"},{"location":"overview/mturk/#getting-the-worker-id","text":"Every account on Mechanical Turk is given a unique identification string. Recording this ID is a useful way to keep track of who is doing your experiment. In particular, while Turk has built in tools for preventing the same person from doing a HIT more than once, there may be cases where you don't want participants to complete related experiments. If you store the worker ID of every person who starts an experiment in a database, then you can exclude people by running a query on the database to check for the ID. jsPsych can get the workerID, assignmentID, and hitID with the turkInfo method. var turkInfo = jsPsych . turk . turkInfo (); // workerID turkInfo . workerId // hitID turkInfo . hitId // assignmentID turkInfo . assignmentId Recording the workerId at the start of the experiment is also a good way to track dropouts.","title":"Getting the worker ID"},{"location":"overview/mturk/#submitting-results-to-mechanical-turk","text":"If you are running a HIT on Mechanical Turk using the ExternalQuestion template, then you'll need to provide a way for participants to indicate that they have completed the HIT. (If you are using another template, then the template will provide this code for you). jsPSych makes this a relatively easy task. A common strategy for external HITs is to display an HTML page on the Mechanical Turk website that links to your HIT. Participants click the link, which opens the actual experiment content in a new browser window or tab, allowing the experiment to take up the whole browser window instead of just the iframe that displays content on Mechanical Turk. On this page, you might include a submit button for workers to indicate that they have finished the experiment. The page would look something like this: < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > When workers click the button, the contents of the code text field will be sent to Mechanical Turk, and you'll be able to view the participants and the codes that they entered in the Mechanical Turk GUI. You can then approve or reject work using the Mechanical Turk website.","title":"Submitting results to Mechanical Turk"},{"location":"overview/mturk/#limitations","text":"jsPsych is not designed to communicate with the Mechanical Turk API in a comprehensive manner. If you are looking for software to help you post and manage HITs, then you may want to look at PsiTurk . jsPsych and PsiTurk complement each other nicely, and there is an example of combining the two platforms on PsiTurk's experiment exchange.","title":"Limitations"},{"location":"overview/plugins/","text":"Plugins \u00b6 In jsPsych, plugins define the kinds of trials or events that should occur during the experiment. Some plugins define very general events, like displaying a set of instructions pages , displaying an image and recording a keyboard response , or playing a sound file and recording a button response . Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a circular visual search array ), or run a specific version of particular kind of task (e.g., the Implicit Association Test ). Part of creating an experiment with jsPsych involves figuring out which plugins are needed to create the tasks you want your participants to perform. Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the image-keyboard-response plugin defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only need to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects. Using a plugin \u00b6 To use a plugin, you'll need to load the plugin's JavaScript file in your experiment's HTML page. All jsPsych experiments also need to load the \"jsPsych.js\" file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" type = \"text/javascript\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" type = \"text/javascript\" ></ script > </ head > Once a plugin is loaded, you can use JavaScript to define a trial that uses that plugin. All jsPsych trials need a type parameter, which tells jsPsych what plugin to use to run the trial. The trial's type is similar to the plugin name, but it always starts with \"jsPsych\" and is written in camel case rather than with dashes between the words. The trial's type parameter should NOT be a string (i.e., no quotes around the type value). Here are some examples of plugin names and types: Plugin name Type image-keyboard-response jsPsychImageKeyboardResponse fullscreen jsPsychFullscreen webgazer-init-camera jsPsychWebgazerInitCamera The following JavaScript code defines a trial using the image-keyboard-response plugin to display an image file. This trial uses the default values for valid keys, stimulus duration, trial duration, and other parameters. var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' } You can override any default parameter values by adding them into your trial object. Here's an example of overriding the default values for trial_duration and post_trial_gap : var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' , trial_duration : 3000 , post_trial_gap : 2000 } Parameters available in all plugins \u00b6 Each plugin specifies its own set of parameters. Check the documentation for a plugin to see what parameters are available and what they do. There is also a set of parameters that can be specified for any plugin: Parameter Type Default Value Description data object undefined An object containing additional data to store for the trial. See the Data page for more details. post_trial_gap numeric null Sets the time, in milliseconds, between the current trial and the next trial. If null, there will be no gap. on_start function function(){ return; } A callback function to execute when the trial begins, before any loading has occurred. See the Event-Related Callbacks page for more details. on_finish function function(){ return; } A callback function to execute when the trial finishes, and before the next trial begins. See the Event-Related Callbacks page for more details. on_load function function(){ return; } A callback function to execute when the trial has loaded, which typically happens after the initial display of the plugin has loaded. See the Event-Related Callbacks page for more details. css_classes string null A list of CSS classes to add to the jsPsych display element for the duration of this trial. This allows you to create custom formatting rules (CSS classes) that are only applied to specific trials. For more information and examples, see the Controlling Visual Appearance page and the \"css-classes-parameter.html\" file in the jsPsych examples folder. save_trial_parameters object {} An object containing any trial parameters that should or should not be saved to the trial data. Each key is the name of a trial parameter, and its value should be true or false , depending on whether or not its value should be saved to the data. If the parameter is a function that returns the parameter value, then the value that is returned will be saved to the data. If the parameter is always expected to be a function (e.g., an event-related callback function), then the function itself will be saved as a string. For more examples, see the \"save-trial-parameters.html\" file in the jsPsych examples folder. The data parameter \u00b6 The data parameter allows you to add additional properties to the trial data. This can be useful for storing properties of the trial that are not directly apparent from the values that the plugin records. The data parameter value must be an object that contains key-value pairs. A simple example is the Flanker Task . In this experiment, participants respond to the direction of a central arrow by pressing a key to the left for a left-pointing arrow (<) and a key to the right for a right-pointing arrow (>). The arrow appears in the center of flankers , or arrows that the participant should ignore. Those flankers can be congruent (>>>>>) or incongruent (<<><<). A trial for the Flanker Task written with jsPsych might look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' } } Note the use of the data parameter to add a property stimulus_type with the value congruent and a property target_direction with the value left . Having these properties recorded directly in the data simplifies data analysis, making it easy to aggregate data by stimulus_type and/or target_direction . The post_trial_gap (ITI) parameter \u00b6 The default inter-trial interval (ITI) in jsPsych is 0 ms. This can be adjusted at the experiment-wide level by changing the default_iti parameter in initJsPsych() . The ITI can also be controlled at the trial level through the post_trial_gap parameter. Setting this parameter to a positive integer x will cause a blank screen to display after the trial for x milliseconds. Setting this parameter for a trial will override the default_iti value set in initJsPsych . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'There will be a 1.5 second blank screen after this trial.' , post_trial_gap : 1500 } The on_start parameter \u00b6 Immediately before a trial runs, there is an opportunity to run an arbitrary function through the on_start event handler. This event handler is passed a single argument containing an editable copy of the trial parameters. This function can therefore be used to alter the trial based on the state of the experiment, among other uses. // when this trial runs, the on_start function will change the trial's stimulus and data parameters, // so the trial will display an incongruent Flanker stimulus with a right-facing central arrow var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_start : function ( trial ){ trial . stimulus = '<<><<' ; trial . data . stimulus_type = 'incongruent' ; trial . data . target_direction = 'right' ; } } The on_finish parameter \u00b6 After a trial is completed, there is an opportunity to run an arbitrary function through the on_finish event handler. This function is passed a single argument containing an editable copy of the data recorded for that trial. This function can therefore be used to update the state of the experiment based on the data collected, or modify the data collected. The on_finish function can be useful to calculate new data properties that were unknowable at the start of the trial. For example, with the Flanker Task example above, the on_finish function could check the response and use to this information to add a new property to the data called correct , which is either true or false . // in addition to all of the standard data collected for this trial, // this on_finish function adds a property called 'correct' // which is either 'true' or 'false' // depending on the response that was made var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' , correct_response : 'f' }, on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response )){ data . correct = true ; } else { data . correct = false ; } } } The on_load parameter \u00b6 The on_load callback function will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. This can be useful for changing various aspects of the page elements and their properties that would otherwise require modifying the plugin file. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { // this will change the src attribute of the image after 500ms setTimeout ( function (){ document . querySelector ( 'img' ). src = 'imgB.png' }, 500 ); } }; The css_classes parameter \u00b6 The css_classes parameter allows you to add an array of CSS class names to the jsPsych display element on that specific trial. This allows you to create custom style and formatting rules that are only applied to specific trials. If you want CSS rules that only apply to specific elements during a trial, you can use additional CSS selectors. < style > . flanker-stimulus { font-size : 500 % ; } . flanker-stimulus # prompt { font-size : 18 px ; } . fixation { font-size : 80 px ; } </ style > < script > var fixation_trial = { type : jsPsychHtmlKeyboardResponse , choices : \"NO_KEYS\" , stimulus : '+' , css_classes : [ 'fixation' ] }; var flanker_trial = { type : jsPsychHtmlKeyboardResponse , choices : [ \"ArrowLeft\" , \"ArrowRight\" ], stimulus : '>>>>>' , prompt : '<span id=\"prompt\">Press the left or right arrow key.</span>' , css_classes : [ 'flanker-stimulus' ] }; </ script > The save_trial_parameters parameter \u00b6 The save_trial_parameters parameter allows you to tell jsPsych what parameters you want to be saved to the data. This can be used to override the parameter values that the plugin saves by default. You can add more parameter values to the data that are not normally saved, or remove parameter values that normally are saved. This can be especially useful when the parameter value is dynamic (i.e. a function) and you want to record the value that was used during the trial. var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"color: orange; font-size: 48px; font-weight: bold;\">BLUE</p>' , choices : function () { return jsPsych . randomization . shuffle ([ 'Yes' , 'No' ]); }, post_trial_gap : function () { return jsPsych . randomization . sampleWithoutReplacement ([ 200 , 300 , 400 , 500 ], 1 )[ 0 ]; }, save_trial_parameters : { // save the randomly-selected button order and post trial gap duration to the trial data choices : true , post_trial_gap : true , // don't save the stimulus stimulus : false } } Note You cannot remove the internal_node_id and trial_index values from the trial data, because these are used internally by jsPsych. Data collected by all plugins \u00b6 Each plugin defines what data is collected on the trial. The documentation for each plugin specifies what information will be stored in the trial data. In addition to the data collected by a plugin, there is a default set of data that is collected on every trial. Name Type Value trial_type string The name of the plugin used to run the trial. trial_index numeric The index of the current trial across the whole experiment. time_elapsed numeric The number of milliseconds between the start of the experiment and when the trial ended. internal_node_id string A string identifier for the current TimelineNode. Creating a new plugin \u00b6 See our developer's guide for plugins for information about how to create a new plugin.","title":"Plugins"},{"location":"overview/plugins/#plugins","text":"In jsPsych, plugins define the kinds of trials or events that should occur during the experiment. Some plugins define very general events, like displaying a set of instructions pages , displaying an image and recording a keyboard response , or playing a sound file and recording a button response . Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a circular visual search array ), or run a specific version of particular kind of task (e.g., the Implicit Association Test ). Part of creating an experiment with jsPsych involves figuring out which plugins are needed to create the tasks you want your participants to perform. Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the image-keyboard-response plugin defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only need to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects.","title":"Plugins"},{"location":"overview/plugins/#using-a-plugin","text":"To use a plugin, you'll need to load the plugin's JavaScript file in your experiment's HTML page. All jsPsych experiments also need to load the \"jsPsych.js\" file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" type = \"text/javascript\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" type = \"text/javascript\" ></ script > </ head > Once a plugin is loaded, you can use JavaScript to define a trial that uses that plugin. All jsPsych trials need a type parameter, which tells jsPsych what plugin to use to run the trial. The trial's type is similar to the plugin name, but it always starts with \"jsPsych\" and is written in camel case rather than with dashes between the words. The trial's type parameter should NOT be a string (i.e., no quotes around the type value). Here are some examples of plugin names and types: Plugin name Type image-keyboard-response jsPsychImageKeyboardResponse fullscreen jsPsychFullscreen webgazer-init-camera jsPsychWebgazerInitCamera The following JavaScript code defines a trial using the image-keyboard-response plugin to display an image file. This trial uses the default values for valid keys, stimulus duration, trial duration, and other parameters. var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' } You can override any default parameter values by adding them into your trial object. Here's an example of overriding the default values for trial_duration and post_trial_gap : var image_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'images/happy_face.jpg' , trial_duration : 3000 , post_trial_gap : 2000 }","title":"Using a plugin"},{"location":"overview/plugins/#parameters-available-in-all-plugins","text":"Each plugin specifies its own set of parameters. Check the documentation for a plugin to see what parameters are available and what they do. There is also a set of parameters that can be specified for any plugin: Parameter Type Default Value Description data object undefined An object containing additional data to store for the trial. See the Data page for more details. post_trial_gap numeric null Sets the time, in milliseconds, between the current trial and the next trial. If null, there will be no gap. on_start function function(){ return; } A callback function to execute when the trial begins, before any loading has occurred. See the Event-Related Callbacks page for more details. on_finish function function(){ return; } A callback function to execute when the trial finishes, and before the next trial begins. See the Event-Related Callbacks page for more details. on_load function function(){ return; } A callback function to execute when the trial has loaded, which typically happens after the initial display of the plugin has loaded. See the Event-Related Callbacks page for more details. css_classes string null A list of CSS classes to add to the jsPsych display element for the duration of this trial. This allows you to create custom formatting rules (CSS classes) that are only applied to specific trials. For more information and examples, see the Controlling Visual Appearance page and the \"css-classes-parameter.html\" file in the jsPsych examples folder. save_trial_parameters object {} An object containing any trial parameters that should or should not be saved to the trial data. Each key is the name of a trial parameter, and its value should be true or false , depending on whether or not its value should be saved to the data. If the parameter is a function that returns the parameter value, then the value that is returned will be saved to the data. If the parameter is always expected to be a function (e.g., an event-related callback function), then the function itself will be saved as a string. For more examples, see the \"save-trial-parameters.html\" file in the jsPsych examples folder.","title":"Parameters available in all plugins"},{"location":"overview/plugins/#the-data-parameter","text":"The data parameter allows you to add additional properties to the trial data. This can be useful for storing properties of the trial that are not directly apparent from the values that the plugin records. The data parameter value must be an object that contains key-value pairs. A simple example is the Flanker Task . In this experiment, participants respond to the direction of a central arrow by pressing a key to the left for a left-pointing arrow (<) and a key to the right for a right-pointing arrow (>). The arrow appears in the center of flankers , or arrows that the participant should ignore. Those flankers can be congruent (>>>>>) or incongruent (<<><<). A trial for the Flanker Task written with jsPsych might look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' } } Note the use of the data parameter to add a property stimulus_type with the value congruent and a property target_direction with the value left . Having these properties recorded directly in the data simplifies data analysis, making it easy to aggregate data by stimulus_type and/or target_direction .","title":"The data parameter"},{"location":"overview/plugins/#the-post_trial_gap-iti-parameter","text":"The default inter-trial interval (ITI) in jsPsych is 0 ms. This can be adjusted at the experiment-wide level by changing the default_iti parameter in initJsPsych() . The ITI can also be controlled at the trial level through the post_trial_gap parameter. Setting this parameter to a positive integer x will cause a blank screen to display after the trial for x milliseconds. Setting this parameter for a trial will override the default_iti value set in initJsPsych . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'There will be a 1.5 second blank screen after this trial.' , post_trial_gap : 1500 }","title":"The post_trial_gap (ITI) parameter"},{"location":"overview/plugins/#the-on_start-parameter","text":"Immediately before a trial runs, there is an opportunity to run an arbitrary function through the on_start event handler. This event handler is passed a single argument containing an editable copy of the trial parameters. This function can therefore be used to alter the trial based on the state of the experiment, among other uses. // when this trial runs, the on_start function will change the trial's stimulus and data parameters, // so the trial will display an incongruent Flanker stimulus with a right-facing central arrow var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' }, on_start : function ( trial ){ trial . stimulus = '<<><<' ; trial . data . stimulus_type = 'incongruent' ; trial . data . target_direction = 'right' ; } }","title":"The on_start parameter"},{"location":"overview/plugins/#the-on_finish-parameter","text":"After a trial is completed, there is an opportunity to run an arbitrary function through the on_finish event handler. This function is passed a single argument containing an editable copy of the data recorded for that trial. This function can therefore be used to update the state of the experiment based on the data collected, or modify the data collected. The on_finish function can be useful to calculate new data properties that were unknowable at the start of the trial. For example, with the Flanker Task example above, the on_finish function could check the response and use to this information to add a new property to the data called correct , which is either true or false . // in addition to all of the standard data collected for this trial, // this on_finish function adds a property called 'correct' // which is either 'true' or 'false' // depending on the response that was made var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], data : { stimulus_type : 'congruent' , target_direction : 'left' , correct_response : 'f' }, on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response )){ data . correct = true ; } else { data . correct = false ; } } }","title":"The on_finish parameter"},{"location":"overview/plugins/#the-on_load-parameter","text":"The on_load callback function will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred. This can be useful for changing various aspects of the page elements and their properties that would otherwise require modifying the plugin file. var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'imgA.png' , on_load : function () { // this will change the src attribute of the image after 500ms setTimeout ( function (){ document . querySelector ( 'img' ). src = 'imgB.png' }, 500 ); } };","title":"The on_load parameter"},{"location":"overview/plugins/#the-css_classes-parameter","text":"The css_classes parameter allows you to add an array of CSS class names to the jsPsych display element on that specific trial. This allows you to create custom style and formatting rules that are only applied to specific trials. If you want CSS rules that only apply to specific elements during a trial, you can use additional CSS selectors. < style > . flanker-stimulus { font-size : 500 % ; } . flanker-stimulus # prompt { font-size : 18 px ; } . fixation { font-size : 80 px ; } </ style > < script > var fixation_trial = { type : jsPsychHtmlKeyboardResponse , choices : \"NO_KEYS\" , stimulus : '+' , css_classes : [ 'fixation' ] }; var flanker_trial = { type : jsPsychHtmlKeyboardResponse , choices : [ \"ArrowLeft\" , \"ArrowRight\" ], stimulus : '>>>>>' , prompt : '<span id=\"prompt\">Press the left or right arrow key.</span>' , css_classes : [ 'flanker-stimulus' ] }; </ script >","title":"The css_classes parameter"},{"location":"overview/plugins/#the-save_trial_parameters-parameter","text":"The save_trial_parameters parameter allows you to tell jsPsych what parameters you want to be saved to the data. This can be used to override the parameter values that the plugin saves by default. You can add more parameter values to the data that are not normally saved, or remove parameter values that normally are saved. This can be especially useful when the parameter value is dynamic (i.e. a function) and you want to record the value that was used during the trial. var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"color: orange; font-size: 48px; font-weight: bold;\">BLUE</p>' , choices : function () { return jsPsych . randomization . shuffle ([ 'Yes' , 'No' ]); }, post_trial_gap : function () { return jsPsych . randomization . sampleWithoutReplacement ([ 200 , 300 , 400 , 500 ], 1 )[ 0 ]; }, save_trial_parameters : { // save the randomly-selected button order and post trial gap duration to the trial data choices : true , post_trial_gap : true , // don't save the stimulus stimulus : false } } Note You cannot remove the internal_node_id and trial_index values from the trial data, because these are used internally by jsPsych.","title":"The save_trial_parameters parameter"},{"location":"overview/plugins/#data-collected-by-all-plugins","text":"Each plugin defines what data is collected on the trial. The documentation for each plugin specifies what information will be stored in the trial data. In addition to the data collected by a plugin, there is a default set of data that is collected on every trial. Name Type Value trial_type string The name of the plugin used to run the trial. trial_index numeric The index of the current trial across the whole experiment. time_elapsed numeric The number of milliseconds between the start of the experiment and when the trial ended. internal_node_id string A string identifier for the current TimelineNode.","title":"Data collected by all plugins"},{"location":"overview/plugins/#creating-a-new-plugin","text":"See our developer's guide for plugins for information about how to create a new plugin.","title":"Creating a new plugin"},{"location":"overview/progress-bar/","text":"Automatic Progress Bar \u00b6 jsPsych can show a progress bar at the top of the experiment page indicating the participant's overall completion progress. The progress bar is rendered outside the jsPsych display element, and it requires the jspsych.css file to be loaded on the page. As of version 6.0, the progress bar looks like this: To show the progress bar, set the show_progress_bar option in initJsPsych to true : var jsPsych = initJsPsych ({ show_progress_bar : true }); The progress bar updates after every node on the top-level timeline updates. This avoids distracting updates in the middle of trials that are composed of multiple plugins, or confusing updates due to looping or conditional structures that may or may not execute depending on the actions of the participant. This also allows some flexibility for the programmer; by nesting timelines in a deliberate manner, the timing of progress bar updates can be controlled. Manual Control \u00b6 The progress bar can also be manually controlled using the function jsPsych.setProgressBar() . This function takes a numeric value between 0 and 1, representing the proportion of the progress bar to fill. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Almost done...' , on_finish : function (){ jsPsych . setProgressBar ( 0.85 ); // set progress bar to 85% full. } } You can also get the current value of the progress bar with jsPsych.getProgressBarCompleted() . var proportion_complete = jsPsych . getProgressBarCompleted (); If you are going to use manual progress bar control, you may want to disable the automatic progress bar updates by setting the auto_update_progress_bar property in initJsPsych() to false . var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); Here's a complete example showing how to use these functions and initJsPsych() settings to manually update the progress bar: var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); var n_trials = 5 ; var start = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press any key to start!' , on_start : function () { // set progress bar to 0 at the start of experiment jsPsych . setProgressBar ( 0 ); } }; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a trial!' , on_finish : function () { // at the end of each trial, update the progress bar // based on the current value and the proportion to update for each trial var curr_progress_bar_value = jsPsych . getProgressBarCompleted (); jsPsych . setProgressBar ( curr_progress_bar_value + ( 1 / n_trials )); } }; var trials = { timeline : [ trial ], repetitions : n_trials }; var done = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Done!' }; jsPsych . run ([ start , trials , done ]); Custom Text \u00b6 By default, jsPsych adds the text \"Completion Progress\" to the left of the progress bar. You can specify custom text using the message_progress_bar parameter in initJsPsych . // support for different spoken languages var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : 'Porcentaje completo' }); // no message var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : '' });","title":"Automatic Progress Bar"},{"location":"overview/progress-bar/#automatic-progress-bar","text":"jsPsych can show a progress bar at the top of the experiment page indicating the participant's overall completion progress. The progress bar is rendered outside the jsPsych display element, and it requires the jspsych.css file to be loaded on the page. As of version 6.0, the progress bar looks like this: To show the progress bar, set the show_progress_bar option in initJsPsych to true : var jsPsych = initJsPsych ({ show_progress_bar : true }); The progress bar updates after every node on the top-level timeline updates. This avoids distracting updates in the middle of trials that are composed of multiple plugins, or confusing updates due to looping or conditional structures that may or may not execute depending on the actions of the participant. This also allows some flexibility for the programmer; by nesting timelines in a deliberate manner, the timing of progress bar updates can be controlled.","title":"Automatic Progress Bar"},{"location":"overview/progress-bar/#manual-control","text":"The progress bar can also be manually controlled using the function jsPsych.setProgressBar() . This function takes a numeric value between 0 and 1, representing the proportion of the progress bar to fill. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Almost done...' , on_finish : function (){ jsPsych . setProgressBar ( 0.85 ); // set progress bar to 85% full. } } You can also get the current value of the progress bar with jsPsych.getProgressBarCompleted() . var proportion_complete = jsPsych . getProgressBarCompleted (); If you are going to use manual progress bar control, you may want to disable the automatic progress bar updates by setting the auto_update_progress_bar property in initJsPsych() to false . var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); Here's a complete example showing how to use these functions and initJsPsych() settings to manually update the progress bar: var jsPsych = initJsPsych ({ show_progress_bar : true , auto_update_progress_bar : false }); var n_trials = 5 ; var start = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press any key to start!' , on_start : function () { // set progress bar to 0 at the start of experiment jsPsych . setProgressBar ( 0 ); } }; var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a trial!' , on_finish : function () { // at the end of each trial, update the progress bar // based on the current value and the proportion to update for each trial var curr_progress_bar_value = jsPsych . getProgressBarCompleted (); jsPsych . setProgressBar ( curr_progress_bar_value + ( 1 / n_trials )); } }; var trials = { timeline : [ trial ], repetitions : n_trials }; var done = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Done!' }; jsPsych . run ([ start , trials , done ]);","title":"Manual Control"},{"location":"overview/progress-bar/#custom-text","text":"By default, jsPsych adds the text \"Completion Progress\" to the left of the progress bar. You can specify custom text using the message_progress_bar parameter in initJsPsych . // support for different spoken languages var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : 'Porcentaje completo' }); // no message var jsPsych = initJsPsych ({ show_progress_bar : true , message_progress_bar : '' });","title":"Custom Text"},{"location":"overview/prolific/","text":"Integrating with Prolific \u00b6 Prolific is a participant recruitment service aimed at research. Integrating a jsPsych experiment with Prolific requires capturing the participant's ID and sending the participant to a completion URL at the end of the experiment. Capturing the Participant ID, Study ID, and Session ID \u00b6 When creating a study on Prolific you must provide the URL to your study. You can host your jsPsych experiment however you'd like - some options are discussed in the Running Experiments documentation page. Once you've got a URL to your experiment, you can enter that in the study link section of Prolific. Then, click the option to record Prolific IDs via URL parameters. This will append information about the participant's prolific ID ( PROLIFIC_PID ), the study's ID ( STUDY_ID ), and the session ID ( SESSION_ID ) to the URL that participants use to access your experiment. We can capture these variables with jsPsych, and add them to jsPsych's data. This can be done anywhere in your code. This code does not need to run as part of your experiment timeline. < script > var jsPsych = initJsPsych (); // capture info from Prolific var subject_id = jsPsych . data . getURLVariable ( 'PROLIFIC_PID' ); var study_id = jsPsych . data . getURLVariable ( 'STUDY_ID' ); var session_id = jsPsych . data . getURLVariable ( 'SESSION_ID' ); jsPsych . data . addProperties ({ subject_id : subject_id , study_id : study_id , session_id : session_id }); // create the rest of the experiment var timeline = [...] jsPsych . run ( timeline ) </ script > Completing the Experiment \u00b6 When the experiment is complete, Prolific requires that you send the participant to a specific URL that marks the session as complete on Prolific's server. The link is provided to you by Prolific in the study completion section of the setup. You can accomplish this in a couple different ways. Warning It's important that you've saved all the data from your experiment before the participant returns to Prolific. Make sure that any server communication has completed prior to redirecting the participant. One way to do this is by using the async features of the call-function plugin ( example ). Participant clicks a link \u00b6 One option is to create a trial that contains a link that the participant clicks to end the experiment and return to Prolific. For example, the html-keyboard-response plugin can be used to display text that includes a link. This could go on a debriefing page. Here's an example trial that could be used. Note that choices is set to \"NO_KEYS\" , which will prevent the participant from continuing past this point in the experiment. var final_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>You've finished the last task. Thanks for participating!</p> <p><a href=\"https://app.prolific.co/submissions/complete?cc=XXXXXXX\">Click here to return to Prolific and complete the study</a>.</p>` , choices : \"NO_KEYS\" } Automatically redirect \u00b6 A second option is to automatically redirect the participant to the completion URL when the experiment is finished. You could do this in a number of places in the jsPsych timeline. Here's an example using the on_finish event for the entire experiment. var jsPsych = initJsPsych ({ on_finish : function (){ window . location = \"https://app.prolific.co/submissions/complete?cc=XXXXXXX\" } });","title":"Integrating with Prolific"},{"location":"overview/prolific/#integrating-with-prolific","text":"Prolific is a participant recruitment service aimed at research. Integrating a jsPsych experiment with Prolific requires capturing the participant's ID and sending the participant to a completion URL at the end of the experiment.","title":"Integrating with Prolific"},{"location":"overview/prolific/#capturing-the-participant-id-study-id-and-session-id","text":"When creating a study on Prolific you must provide the URL to your study. You can host your jsPsych experiment however you'd like - some options are discussed in the Running Experiments documentation page. Once you've got a URL to your experiment, you can enter that in the study link section of Prolific. Then, click the option to record Prolific IDs via URL parameters. This will append information about the participant's prolific ID ( PROLIFIC_PID ), the study's ID ( STUDY_ID ), and the session ID ( SESSION_ID ) to the URL that participants use to access your experiment. We can capture these variables with jsPsych, and add them to jsPsych's data. This can be done anywhere in your code. This code does not need to run as part of your experiment timeline. < script > var jsPsych = initJsPsych (); // capture info from Prolific var subject_id = jsPsych . data . getURLVariable ( 'PROLIFIC_PID' ); var study_id = jsPsych . data . getURLVariable ( 'STUDY_ID' ); var session_id = jsPsych . data . getURLVariable ( 'SESSION_ID' ); jsPsych . data . addProperties ({ subject_id : subject_id , study_id : study_id , session_id : session_id }); // create the rest of the experiment var timeline = [...] jsPsych . run ( timeline ) </ script >","title":"Capturing the Participant ID, Study ID, and Session ID"},{"location":"overview/prolific/#completing-the-experiment","text":"When the experiment is complete, Prolific requires that you send the participant to a specific URL that marks the session as complete on Prolific's server. The link is provided to you by Prolific in the study completion section of the setup. You can accomplish this in a couple different ways. Warning It's important that you've saved all the data from your experiment before the participant returns to Prolific. Make sure that any server communication has completed prior to redirecting the participant. One way to do this is by using the async features of the call-function plugin ( example ).","title":"Completing the Experiment"},{"location":"overview/prolific/#participant-clicks-a-link","text":"One option is to create a trial that contains a link that the participant clicks to end the experiment and return to Prolific. For example, the html-keyboard-response plugin can be used to display text that includes a link. This could go on a debriefing page. Here's an example trial that could be used. Note that choices is set to \"NO_KEYS\" , which will prevent the participant from continuing past this point in the experiment. var final_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : `<p>You've finished the last task. Thanks for participating!</p> <p><a href=\"https://app.prolific.co/submissions/complete?cc=XXXXXXX\">Click here to return to Prolific and complete the study</a>.</p>` , choices : \"NO_KEYS\" }","title":"Participant clicks a link"},{"location":"overview/prolific/#automatically-redirect","text":"A second option is to automatically redirect the participant to the completion URL when the experiment is finished. You could do this in a number of places in the jsPsych timeline. Here's an example using the on_finish event for the entire experiment. var jsPsych = initJsPsych ({ on_finish : function (){ window . location = \"https://app.prolific.co/submissions/complete?cc=XXXXXXX\" } });","title":"Automatically redirect"},{"location":"overview/record-browser-interactions/","text":"Record browser interactions \u00b6 Participants in an online experiment have the freedom to multitask while performing an experiment. jsPsych automatically records information about when the user clicks on a window that is not the experiment, and about when the user exits full screen mode if the experiment is running in full screen mode. This data is stored separately from the main experiment data, and can be accessed with jsPsych.data.getInteractionData() . Each time the user leaves the experiment window, returns to the experiment window, exits full screen mode, or enters full screen mode, the event is recorded in the interaction data. Each event has the following structure. { event : 'focus' , // 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' trial : 12 , // the index of the active trial when the event happened time : 1240543 // time in ms since the start of the experiment } You can specify a custom function, in the initJsPsych() method, that is called whenever one of these events occurs initJsPsych ({ on_interaction_data_update : function ( data ) { console . log ( JSON . stringify ( data )) } });","title":"Record Browser Interactions"},{"location":"overview/record-browser-interactions/#record-browser-interactions","text":"Participants in an online experiment have the freedom to multitask while performing an experiment. jsPsych automatically records information about when the user clicks on a window that is not the experiment, and about when the user exits full screen mode if the experiment is running in full screen mode. This data is stored separately from the main experiment data, and can be accessed with jsPsych.data.getInteractionData() . Each time the user leaves the experiment window, returns to the experiment window, exits full screen mode, or enters full screen mode, the event is recorded in the interaction data. Each event has the following structure. { event : 'focus' , // 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' trial : 12 , // the index of the active trial when the event happened time : 1240543 // time in ms since the start of the experiment } You can specify a custom function, in the initJsPsych() method, that is called whenever one of these events occurs initJsPsych ({ on_interaction_data_update : function ( data ) { console . log ( JSON . stringify ( data )) } });","title":"Record browser interactions"},{"location":"overview/running-experiments/","text":"Running Experiments \u00b6 You can run your jsPsych experiment: Offline , by opening the HTML file directly in the browser using the file:// protocol. Online , by hosting the files on a web server using the http:// or https:// protocol. The way that you run your experiment will have consequences for certain aspects about how the experiment works, and what your experiment will be able to do. This page explains what you need to know about both of these options. Info If you are looking for a tool to automate deployment-related tasks, check out the jsPsych Builder CLI utility. It automatically bundles scripts and style sheets, configures media preloading, and yields a zip file that contains all files for deployment (online or offline). jsPsych Builder can also directly build JATOS experiment files (.jzip) that you can upload to a JATOS server (see this section below for more info about JATOS and other server options). Offline \u00b6 You can run your jsPsych experiment offline by opening the HTML file directly in a web browser, for instance by double-clicking on it. This uses the file:// protocol. It's usually the fastest and easiest way to run through an experiment, and is very useful while writing and testing the code. At some point you will need to move your experiment files onto a server and send the data to a database, since this is how you will ultimately collect the data (unless you're planning to collect data on your local computer). There are some important differences between the way the experiment runs offline compared to online via a web server. Note that, unless noted, here we're using the word \"server\" to mean either a local server (which runs on your computer and only makes the experiment files available from within that computer, and is often used during development), or a remote server (which does not run on your computer and does share your experiment files over the internet). Cross-origin requests (CORS) and safe mode \u00b6 Web browsers have a security policy called cross-origin resource sharing (CORS) that determines whether the webpage can request files that come from a different origin (i.e. protocol, host/domain, and port). This isn't a problem when your study runs online , because in that case your experiment files all have the same origin. However, when you run your experiment offline , the CORS policy blocks some jsPsych features that require loading local files . If your experiment uses these features, then CORS errors will prevent the experiment from running. To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTML page is running via the file:// protocol, and if so, automatically disables the features that don't work in that context. Specifically, when a jsPsych experiment runs offline: Web Audio is disabled (even if use_webaudio is set to true in initJsPsych ). The WebAudio API option is used by default because it allows more precise measurement of response times relative to the onset of the audio. But because WebAudio doesn't work offline, audio will be played using HTML5 audio instead. This is equivalent to setting use_webaudio to false in initJsPsych . Video preloading is disabled (both automatic and manual preloading via the preload plugin). Videos will still play when you run your experiment offline, but they will load during the experiment, which might cause noticeable delays before video playback starts. This safe mode feature is controlled by the override_safe_mode parameter in initJsPsych , which defaults to false . If you leave this setting as the default, then you won't need to worry about CORS errors while running your experiment offline, or remembering to change your initJsPsych settings when you move the experiment online. It's possible to override jsPsych's safe mode by setting override_safe_mode to true in initJsPsych . One reason you might do this is if you've disabled web security features in your browser (see here and here for instructions in Chrome), which is safe to do if you know what you're doing. If your experiment does not use Web Audio or preloaded videos, then jsPsych's safe mode feature will not have any effect. The override_safe_mode parameter also has no effect when your experiment is running online a web server, because the page will be loaded via the http:// or https:// protocol. Media loading \u00b6 While running your experiment offline, any media files are likely to load very quickly because they are stored on your own computer's disk. Therefore you may not notice problems with file loading delays while running your experiment locally (either offline or on a local server) because the files will load fast enough that they never cause disruption. However, when your experiment is hosted on a remote server, the files will need to be transferred over the internet, which means they will take longer to load - in some cases much longer. Loading delays are most noticeable with media files: images, audio, and video. As explained on the Media Preloading page, loading delays during your experiment can cause problems for stimulus display and response times. It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see here for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the max_load_time parameter in the preload plugin so that participants with slow/unreliable internet connections will be able to take part in your experiment. Permanent data storage \u00b6 As explained in the Data Storage, Aggregation, and Manipulation page, jsPsych stores information in the participant's browser. While running an experiment offline, you won't be able to send the data to a database. However you can still see the data that jsPsych collects by saving it as a local file (using jsPsych.data.get().localSave ), displaying it in the webpage at the end of the experiment (using jsPsych.data.displayData ), or printing it to the browser's console (using console.log ). Permanent data storage is also necessary when the code that runs the experiment depends on information that can't be known in advance, and that changes throughout data collection. Some common examples of this in cognitive behavioral research are version counterbalancing , where the experiment code needs to access and update the history of version assignment in order to determine which version should be assigned, and multi-session/training studies , where the experiment might need to access and update information about each participant like their current session number, task difficulty level, etc. Doing these things in an automated way requires the use of a server. While developing and testing your experiment offline, you might choose to simulate some of these things and then implement them properly once you move your experiment online. For instance, you could randomize instead of counterbalancing version assignment: var versions = [ 1 , 2 ]; var random_version = jsPsych . randomization . sampleWithoutReplacement ( versions , 1 )[ 0 ]; And use URL query parameters to pass in variables like session number and difficulty level: // add the variables onto the end of the URL that appears in the browser when you open the file // e.g., file:///C:/my_experiment.html?id=1&sess=2&diff=3 var participant_id = jsPsych . data . getURLVariable ( 'id' ); var session = jsPsych . data . getURLVariable ( 'sess' ); var difficulty = jsPsych . data . getURLVariable ( 'diff' ); Online \u00b6 Hosting the Experiment and Saving the Data \u00b6 jsPsych is a front-end JavaScript library that runs entirely on the participant's computer. To run a jsPsych experiment over the internet, the files need to be hosted on a public web server so that participants can access the experiment using a web browser. When the participant completes the experiment in the browser, all of the data that jsPsych collects is stored on the participant's computer in the browser's memory. To get access to this data, it needs to be sent from the participant's browser back to the web server and stored in a database or a file. To be maximally flexible, jsPsych doesn't provide a single built-in solution for the web server component of your experiment. This makes jsPsych compatible with a wide range of hosting services and tools, allowing researchers to choose the web server option that best suit their needs. Some options for running your jsPsych experiment online include: Cognition.run - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. JATOS - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers. Pavlovia - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia. PsiTurk - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option. Pushkin - A set of tools to help you set up your own virtual laboratory for online experiments. This option differs from the others in that it helps you set up a complete website that may contain many different experiments, information about the laboratory, participant logins, and other features that are targeted at hosting large-scale data collection efforts. Full DIY - You can setup your own web server and database and handle the communication yourself. Traditional web server 'stacks' include LAMP / LEMP (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include Flask (Python) and Node.js (JavaScript). Recruiting Participants \u00b6 Once your experiment is running online, you could recruit participants in the same way that you would for lab-based studies. For instance, if your institution uses SONA, you can advertise your web-based study link on SONA. SONA allows you to automactically embed a unique ID in online study URLs, which you can then save in your data using jsPsych's URL query parameters function . SONA will also generate a completion URL that you can redirect participants to at the end of the study, and this will mark them as having completed the study in SONA. To take full advantage of hosting an experiment online, many researchers advertise their experiments more widely. Social media and other media outlets provide one option for reaching a large number of potential participants. There are also some commercial platforms that you can use to advertise your study and pay anonymous online participants. These recruitment platforms charge a fee for use. The advantages of these platforms are that they handle the participant payments and allow you to specify pre-screening criteria. The most commonly used recruitment platforms in online behavioral research are: Prolific : An online labor market designed specifically for web-based research. Amazon Mechanical Turk (MTurk) : An online labor market designed for advertising paid 'human intelligence tasks'. This service was designed for use by commercial businesses but has been used by behavioral researchers for many years. Like SONA, Prolific and MTurk use URL query parameters to get participant information, and redirection to specific URLs to mark participants as having finished the study. jsPsych includes convenience functions for interacting with MTurk participants . Information about integrating with Prolific can be found in the researcher support section of their website.","title":"Running Experiments"},{"location":"overview/running-experiments/#running-experiments","text":"You can run your jsPsych experiment: Offline , by opening the HTML file directly in the browser using the file:// protocol. Online , by hosting the files on a web server using the http:// or https:// protocol. The way that you run your experiment will have consequences for certain aspects about how the experiment works, and what your experiment will be able to do. This page explains what you need to know about both of these options. Info If you are looking for a tool to automate deployment-related tasks, check out the jsPsych Builder CLI utility. It automatically bundles scripts and style sheets, configures media preloading, and yields a zip file that contains all files for deployment (online or offline). jsPsych Builder can also directly build JATOS experiment files (.jzip) that you can upload to a JATOS server (see this section below for more info about JATOS and other server options).","title":"Running Experiments"},{"location":"overview/running-experiments/#offline","text":"You can run your jsPsych experiment offline by opening the HTML file directly in a web browser, for instance by double-clicking on it. This uses the file:// protocol. It's usually the fastest and easiest way to run through an experiment, and is very useful while writing and testing the code. At some point you will need to move your experiment files onto a server and send the data to a database, since this is how you will ultimately collect the data (unless you're planning to collect data on your local computer). There are some important differences between the way the experiment runs offline compared to online via a web server. Note that, unless noted, here we're using the word \"server\" to mean either a local server (which runs on your computer and only makes the experiment files available from within that computer, and is often used during development), or a remote server (which does not run on your computer and does share your experiment files over the internet).","title":"Offline"},{"location":"overview/running-experiments/#cross-origin-requests-cors-and-safe-mode","text":"Web browsers have a security policy called cross-origin resource sharing (CORS) that determines whether the webpage can request files that come from a different origin (i.e. protocol, host/domain, and port). This isn't a problem when your study runs online , because in that case your experiment files all have the same origin. However, when you run your experiment offline , the CORS policy blocks some jsPsych features that require loading local files . If your experiment uses these features, then CORS errors will prevent the experiment from running. To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTML page is running via the file:// protocol, and if so, automatically disables the features that don't work in that context. Specifically, when a jsPsych experiment runs offline: Web Audio is disabled (even if use_webaudio is set to true in initJsPsych ). The WebAudio API option is used by default because it allows more precise measurement of response times relative to the onset of the audio. But because WebAudio doesn't work offline, audio will be played using HTML5 audio instead. This is equivalent to setting use_webaudio to false in initJsPsych . Video preloading is disabled (both automatic and manual preloading via the preload plugin). Videos will still play when you run your experiment offline, but they will load during the experiment, which might cause noticeable delays before video playback starts. This safe mode feature is controlled by the override_safe_mode parameter in initJsPsych , which defaults to false . If you leave this setting as the default, then you won't need to worry about CORS errors while running your experiment offline, or remembering to change your initJsPsych settings when you move the experiment online. It's possible to override jsPsych's safe mode by setting override_safe_mode to true in initJsPsych . One reason you might do this is if you've disabled web security features in your browser (see here and here for instructions in Chrome), which is safe to do if you know what you're doing. If your experiment does not use Web Audio or preloaded videos, then jsPsych's safe mode feature will not have any effect. The override_safe_mode parameter also has no effect when your experiment is running online a web server, because the page will be loaded via the http:// or https:// protocol.","title":"Cross-origin requests (CORS) and safe mode"},{"location":"overview/running-experiments/#media-loading","text":"While running your experiment offline, any media files are likely to load very quickly because they are stored on your own computer's disk. Therefore you may not notice problems with file loading delays while running your experiment locally (either offline or on a local server) because the files will load fast enough that they never cause disruption. However, when your experiment is hosted on a remote server, the files will need to be transferred over the internet, which means they will take longer to load - in some cases much longer. Loading delays are most noticeable with media files: images, audio, and video. As explained on the Media Preloading page, loading delays during your experiment can cause problems for stimulus display and response times. It is important to test your experiment to ensure that any media files are preloading successfully and not being requested again during the experiment. You can use the Network tab in your browser's developer tools to see when files are loaded and to simulate a slow internet connection (see here for Chrome Network tab documentation). If you are preloading many and/or large files, such as videos, you may want to increase the max_load_time parameter in the preload plugin so that participants with slow/unreliable internet connections will be able to take part in your experiment.","title":"Media loading"},{"location":"overview/running-experiments/#permanent-data-storage","text":"As explained in the Data Storage, Aggregation, and Manipulation page, jsPsych stores information in the participant's browser. While running an experiment offline, you won't be able to send the data to a database. However you can still see the data that jsPsych collects by saving it as a local file (using jsPsych.data.get().localSave ), displaying it in the webpage at the end of the experiment (using jsPsych.data.displayData ), or printing it to the browser's console (using console.log ). Permanent data storage is also necessary when the code that runs the experiment depends on information that can't be known in advance, and that changes throughout data collection. Some common examples of this in cognitive behavioral research are version counterbalancing , where the experiment code needs to access and update the history of version assignment in order to determine which version should be assigned, and multi-session/training studies , where the experiment might need to access and update information about each participant like their current session number, task difficulty level, etc. Doing these things in an automated way requires the use of a server. While developing and testing your experiment offline, you might choose to simulate some of these things and then implement them properly once you move your experiment online. For instance, you could randomize instead of counterbalancing version assignment: var versions = [ 1 , 2 ]; var random_version = jsPsych . randomization . sampleWithoutReplacement ( versions , 1 )[ 0 ]; And use URL query parameters to pass in variables like session number and difficulty level: // add the variables onto the end of the URL that appears in the browser when you open the file // e.g., file:///C:/my_experiment.html?id=1&sess=2&diff=3 var participant_id = jsPsych . data . getURLVariable ( 'id' ); var session = jsPsych . data . getURLVariable ( 'sess' ); var difficulty = jsPsych . data . getURLVariable ( 'diff' );","title":"Permanent data storage"},{"location":"overview/running-experiments/#online","text":"","title":"Online"},{"location":"overview/running-experiments/#hosting-the-experiment-and-saving-the-data","text":"jsPsych is a front-end JavaScript library that runs entirely on the participant's computer. To run a jsPsych experiment over the internet, the files need to be hosted on a public web server so that participants can access the experiment using a web browser. When the participant completes the experiment in the browser, all of the data that jsPsych collects is stored on the participant's computer in the browser's memory. To get access to this data, it needs to be sent from the participant's browser back to the web server and stored in a database or a file. To be maximally flexible, jsPsych doesn't provide a single built-in solution for the web server component of your experiment. This makes jsPsych compatible with a wide range of hosting services and tools, allowing researchers to choose the web server option that best suit their needs. Some options for running your jsPsych experiment online include: Cognition.run - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. JATOS - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers. Pavlovia - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia. PsiTurk - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option. Pushkin - A set of tools to help you set up your own virtual laboratory for online experiments. This option differs from the others in that it helps you set up a complete website that may contain many different experiments, information about the laboratory, participant logins, and other features that are targeted at hosting large-scale data collection efforts. Full DIY - You can setup your own web server and database and handle the communication yourself. Traditional web server 'stacks' include LAMP / LEMP (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include Flask (Python) and Node.js (JavaScript).","title":"Hosting the Experiment and Saving the Data"},{"location":"overview/running-experiments/#recruiting-participants","text":"Once your experiment is running online, you could recruit participants in the same way that you would for lab-based studies. For instance, if your institution uses SONA, you can advertise your web-based study link on SONA. SONA allows you to automactically embed a unique ID in online study URLs, which you can then save in your data using jsPsych's URL query parameters function . SONA will also generate a completion URL that you can redirect participants to at the end of the study, and this will mark them as having completed the study in SONA. To take full advantage of hosting an experiment online, many researchers advertise their experiments more widely. Social media and other media outlets provide one option for reaching a large number of potential participants. There are also some commercial platforms that you can use to advertise your study and pay anonymous online participants. These recruitment platforms charge a fee for use. The advantages of these platforms are that they handle the participant payments and allow you to specify pre-screening criteria. The most commonly used recruitment platforms in online behavioral research are: Prolific : An online labor market designed specifically for web-based research. Amazon Mechanical Turk (MTurk) : An online labor market designed for advertising paid 'human intelligence tasks'. This service was designed for use by commercial businesses but has been used by behavioral researchers for many years. Like SONA, Prolific and MTurk use URL query parameters to get participant information, and redirection to specific URLs to mark participants as having finished the study. jsPsych includes convenience functions for interacting with MTurk participants . Information about integrating with Prolific can be found in the researcher support section of their website.","title":"Recruiting Participants"},{"location":"overview/simulation/","text":"Simulation Modes \u00b6 Added in 7.1 Simulation mode allows you run your experiment automatically and generate artificial data. Info For a detailed description of the motivation behind simulation mode and a discussion of different use cases of simulation mode, see de Leeuw, J.R., Gilbert, R.A., Petrov, N.B., & Luchterhandt, B. (2022). Simulation behavior to help researchers build experiments. Behavior Research Methods , https://doi.org/10.3758/s13428-022-01899-0 . A pre-print version is available on PsyArXiv . Getting Started \u00b6 To use simulation mode, replace jsPsych.run() with jsPsych.simulate() . jsPsych . simulate ( timeline ); This will run jsPsych in the default data-only simulation mode. To use the visual simulation mode you can specify the second parameter. jsPsych . simulate ( timeline , \"data-only\" ); jsPsych . simulate ( timeline , \"visual\" ); What happens in simulation mode \u00b6 In simulation mode, plugins call their simulate() method instead of calling their trial() method. If a plugin doesn't implement a simulate() method, then the trial will run as usual (using the trial() method) and any interaction that is needed to advance to the next trial will be required. If a plugin doesn't support visual mode, then it will run in data-only mode. data-only mode \u00b6 In data-only mode plugins typically generate resonable artificial data given the parameters specified for the trial. For example, if the trial_duration parameter is set to 2,000 ms, then any response times generated will be capped at this value. Generally the default data generated by the plugin randomly selects any available options (e.g., buttons to click) with equal probability. Response times are usually generated by sampling from an exponentially-modified Gaussian distribution truncated to positive values using jsPsych.randomization.sampleExGaussian() . In data-only mode, the plugin's trial() method usually does not run. The data are simply calculated based on trial parameters and the finishTrial() method is called immediately with the simulated data. visual mode \u00b6 In visual mode a plugin will typically generate simulated data for the trial and then use that data to mimic the kinds of actions that a participant would do. The plugin's trial() method is called by the simulation, and you'll see the experiment progress in real time. Mouse, keyboard, and touch events are simulated to control the experiment. In visual mode each plugin will generate simulated data in the same manner as data-only mode, but this data will instead be used to generate actions in the experiment and the plugin's trial() method will ultimately be responsible for generating the data. This can create some subtle differences in data between the two modes. For example, if the simulated data generates a response time of 500 ms, the data.rt value will be exactly 500 in data-only mode, but may be 501 or another slightly larger value in visual mode. This is because the simulated response is triggered at 500 ms and small delays due to JavaScript's event loop might add a few ms to the measure. Controlling simulation mode with simulation_options \u00b6 The parameters for simulation mode can be set using the simulation_options parameter in both jsPsych.simulate() and at the level of individual trials. Trial-level options \u00b6 You can specify simulation options for an individual trial by setting the simulation_options parameter. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : 500 } } } Currently the three options that are available are data , mode , and simulate . data \u00b6 Setting the data option will replace the default data generated by the plugin with whatever data you specify. You can specify some or all of the data parameters. Any parameters you do not specify will be generated by the plugin. In most cases plugins will try to ensure that the data generated is consistent with the trial parameters. For example, if a trial has a trial_duration parameter of 2000 but the simulation_options specify a rt of 2500 , this creates an impossible situation because the trial would have ended before the response at 2,500ms. In most cases, the plugin will act as if a response was attempted at 2500 , which will mean that no response is generated for the trial. As you might imagine, there are a lot of parameter combinations that can generate peculiar cases where data may be inconsistent with trial parameters. We recommend double checking the simulation output, and please alert us if you discover a situation where the simulation produces inconsistent data. mode \u00b6 You can override the simulation mode specified in jsPsych.simulate() for any trial. Setting mode: 'data-only' will run the trial in data-only mode and setting mode: 'visual' will run the trial in visual mode. simulate \u00b6 If you want to turn off simulation mode for a trial, set simulate: false . Functions and timeline variables \u00b6 The simulation_options parameter is compatible with both dynamic parameters and timeline variables . Dynamic parameters can be especially useful if you want to randomize the data for each run of the simulation. For example, you can specify the rt as a sample from an ExGaussian distribution. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : ()=>{ return jsPsych . randomization . sampleExGaussian ( 500 , 50 , 1 / 100 , true ) } } } } Experiment-level options \u00b6 You can also control the parameters for simulation by passing in an object to the simulation_options argument of jsPsych.simulate() . const simulation_options = { default : { data : { rt : 200 } } } jsPsych . simulate ( timeline , \"visual\" , simulation_options ) The above example will set the rt for any trial that doesn't have its own simulation_options specified to 200 . This could be useful, for example, to create a very fast preview of the experiment to verify that everything is displaying correctly without having to wait through longer trials. You can also specify sets of parameters by name using the experiment-level simulation options. const simulation_options = { default : { data : { rt : 200 } }, long_response : { data : { rt : () => { return jsPsych . randomization . sampleExGaussian ( 5000 , 500 , 1 / 500 , true ) } } } } const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>This is gonna take a bit.</p>' , simulation_options : 'long_response' } timeline . push ( trial ); jsPsych . simulate ( timeline , \"visual\" , simulation_options ) In the example above, we specified the simulation_options for trial using a string ( 'long_response' ). This will look up the corresponding set of options in the experiment-level simulation_options . We had a few use cases in mind with this approach: You could group together trials with similar behavior without needing to specify unique options for each trial. You could easily swap out different simulation options to test different kinds of behavior. For example, if you want to test that a timeline with a conditional_function is working as expected, you could have one set of simulation options where the data will cause the conditional_function to evaluate to true and another to false . By using string-based identifiers, you don't need to change the timeline code at all. You can just change the object being passed to jsPsych.simulate() . In an extreme case of the previous example, every trial on the timeline could have its own unique identifier and you could have multiple sets of simulation options to have very precise control over the data output. Current Limitations \u00b6 Simulation mode is not yet as comprehensively tested as the rest of jsPsych. While we are confident that the simulation is accurate enough for many use cases, it's very likely that there are circumstances where the simulated behavior will be inconsistent with what is actually possible in the experiment. If you come across any such circumstances, please let us know ! Currently extensions are not supported in simulation mode. Some plugins are also not supported. This will be noted on their documentation page.","title":"Simulation Modes"},{"location":"overview/simulation/#simulation-modes","text":"Added in 7.1 Simulation mode allows you run your experiment automatically and generate artificial data. Info For a detailed description of the motivation behind simulation mode and a discussion of different use cases of simulation mode, see de Leeuw, J.R., Gilbert, R.A., Petrov, N.B., & Luchterhandt, B. (2022). Simulation behavior to help researchers build experiments. Behavior Research Methods , https://doi.org/10.3758/s13428-022-01899-0 . A pre-print version is available on PsyArXiv .","title":"Simulation Modes"},{"location":"overview/simulation/#getting-started","text":"To use simulation mode, replace jsPsych.run() with jsPsych.simulate() . jsPsych . simulate ( timeline ); This will run jsPsych in the default data-only simulation mode. To use the visual simulation mode you can specify the second parameter. jsPsych . simulate ( timeline , \"data-only\" ); jsPsych . simulate ( timeline , \"visual\" );","title":"Getting Started"},{"location":"overview/simulation/#what-happens-in-simulation-mode","text":"In simulation mode, plugins call their simulate() method instead of calling their trial() method. If a plugin doesn't implement a simulate() method, then the trial will run as usual (using the trial() method) and any interaction that is needed to advance to the next trial will be required. If a plugin doesn't support visual mode, then it will run in data-only mode.","title":"What happens in simulation mode"},{"location":"overview/simulation/#data-only-mode","text":"In data-only mode plugins typically generate resonable artificial data given the parameters specified for the trial. For example, if the trial_duration parameter is set to 2,000 ms, then any response times generated will be capped at this value. Generally the default data generated by the plugin randomly selects any available options (e.g., buttons to click) with equal probability. Response times are usually generated by sampling from an exponentially-modified Gaussian distribution truncated to positive values using jsPsych.randomization.sampleExGaussian() . In data-only mode, the plugin's trial() method usually does not run. The data are simply calculated based on trial parameters and the finishTrial() method is called immediately with the simulated data.","title":"data-only mode"},{"location":"overview/simulation/#visual-mode","text":"In visual mode a plugin will typically generate simulated data for the trial and then use that data to mimic the kinds of actions that a participant would do. The plugin's trial() method is called by the simulation, and you'll see the experiment progress in real time. Mouse, keyboard, and touch events are simulated to control the experiment. In visual mode each plugin will generate simulated data in the same manner as data-only mode, but this data will instead be used to generate actions in the experiment and the plugin's trial() method will ultimately be responsible for generating the data. This can create some subtle differences in data between the two modes. For example, if the simulated data generates a response time of 500 ms, the data.rt value will be exactly 500 in data-only mode, but may be 501 or another slightly larger value in visual mode. This is because the simulated response is triggered at 500 ms and small delays due to JavaScript's event loop might add a few ms to the measure.","title":"visual mode"},{"location":"overview/simulation/#controlling-simulation-mode-with-simulation_options","text":"The parameters for simulation mode can be set using the simulation_options parameter in both jsPsych.simulate() and at the level of individual trials.","title":"Controlling simulation mode with simulation_options"},{"location":"overview/simulation/#trial-level-options","text":"You can specify simulation options for an individual trial by setting the simulation_options parameter. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : 500 } } } Currently the three options that are available are data , mode , and simulate .","title":"Trial-level options"},{"location":"overview/simulation/#data","text":"Setting the data option will replace the default data generated by the plugin with whatever data you specify. You can specify some or all of the data parameters. Any parameters you do not specify will be generated by the plugin. In most cases plugins will try to ensure that the data generated is consistent with the trial parameters. For example, if a trial has a trial_duration parameter of 2000 but the simulation_options specify a rt of 2500 , this creates an impossible situation because the trial would have ended before the response at 2,500ms. In most cases, the plugin will act as if a response was attempted at 2500 , which will mean that no response is generated for the trial. As you might imagine, there are a lot of parameter combinations that can generate peculiar cases where data may be inconsistent with trial parameters. We recommend double checking the simulation output, and please alert us if you discover a situation where the simulation produces inconsistent data.","title":"data"},{"location":"overview/simulation/#mode","text":"You can override the simulation mode specified in jsPsych.simulate() for any trial. Setting mode: 'data-only' will run the trial in data-only mode and setting mode: 'visual' will run the trial in visual mode.","title":"mode"},{"location":"overview/simulation/#simulate","text":"If you want to turn off simulation mode for a trial, set simulate: false .","title":"simulate"},{"location":"overview/simulation/#functions-and-timeline-variables","text":"The simulation_options parameter is compatible with both dynamic parameters and timeline variables . Dynamic parameters can be especially useful if you want to randomize the data for each run of the simulation. For example, you can specify the rt as a sample from an ExGaussian distribution. const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>Hello!</p>' , simulation_options : { data : { rt : ()=>{ return jsPsych . randomization . sampleExGaussian ( 500 , 50 , 1 / 100 , true ) } } } }","title":"Functions and timeline variables"},{"location":"overview/simulation/#experiment-level-options","text":"You can also control the parameters for simulation by passing in an object to the simulation_options argument of jsPsych.simulate() . const simulation_options = { default : { data : { rt : 200 } } } jsPsych . simulate ( timeline , \"visual\" , simulation_options ) The above example will set the rt for any trial that doesn't have its own simulation_options specified to 200 . This could be useful, for example, to create a very fast preview of the experiment to verify that everything is displaying correctly without having to wait through longer trials. You can also specify sets of parameters by name using the experiment-level simulation options. const simulation_options = { default : { data : { rt : 200 } }, long_response : { data : { rt : () => { return jsPsych . randomization . sampleExGaussian ( 5000 , 500 , 1 / 500 , true ) } } } } const trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>This is gonna take a bit.</p>' , simulation_options : 'long_response' } timeline . push ( trial ); jsPsych . simulate ( timeline , \"visual\" , simulation_options ) In the example above, we specified the simulation_options for trial using a string ( 'long_response' ). This will look up the corresponding set of options in the experiment-level simulation_options . We had a few use cases in mind with this approach: You could group together trials with similar behavior without needing to specify unique options for each trial. You could easily swap out different simulation options to test different kinds of behavior. For example, if you want to test that a timeline with a conditional_function is working as expected, you could have one set of simulation options where the data will cause the conditional_function to evaluate to true and another to false . By using string-based identifiers, you don't need to change the timeline code at all. You can just change the object being passed to jsPsych.simulate() . In an extreme case of the previous example, every trial on the timeline could have its own unique identifier and you could have multiple sets of simulation options to have very precise control over the data output.","title":"Experiment-level options"},{"location":"overview/simulation/#current-limitations","text":"Simulation mode is not yet as comprehensively tested as the rest of jsPsych. While we are confident that the simulation is accurate enough for many use cases, it's very likely that there are circumstances where the simulated behavior will be inconsistent with what is actually possible in the experiment. If you come across any such circumstances, please let us know ! Currently extensions are not supported in simulation mode. Some plugins are also not supported. This will be noted on their documentation page.","title":"Current Limitations"},{"location":"overview/style/","text":"Controlling Visual Appearance \u00b6 Your experiment's style and formatting comes from the CSS (cascading style sheet) rules that are stored in the jspsych.css file, and the browser's defaults. There are a few ways to change the style and formatting in your experiment. The method that you choose is partly a matter of personal preference. It might also depend on whether you want the style/formatting change(s) to apply to specific trials , to the whole experiment (HTML page), or across different experiments . This section discusses the different ways of incorporating CSS into your jsPsych experiment. You can also see this page about adding CSS to web pages to learn more. Inline CSS \u00b6 Whenever you're using a parameter that accepts an HTML-formatted string, you have the option to include inline CSS. Inline CSS is a way of adding style and formatting directly into a specific HTML element using its \"style\" attribute . This is a good option for when you want to make few and/or simple style changes to an HTML trial parameter. To change an element's style using inline CSS, you can set the element's \"style\" attribute to a string that contains the CSS parameters that you want to change, along with the values that you want to use. The syntax is \" <parameter-name> : <parameter-value> ;\". In the example below, the stimulus font size is set to 30px and the text color is set to red. These changes will only be applied to this stimulus text in this specific trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:30px;color:red;\">hello world!</p>' } You can also use a dynamic parameter to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and timeline variables : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var stim = '<p style=\"font-size:30px;font-weight:bold;\">' + jsPsych . timelineVariable ( 'text' ) + '</p>' ; return stim ; } } var trial_procedure = { timeline : [ trial ], timeline_variables : [ { text : 'Welcome' }, { text : 'to' }, { text : 'the' }, { text : 'experiment!' } ] } Adding CSS rules \u00b6 You may want to add a lot of different CSS changes to your experiment, re-use the same change(s) across lots of different trials, and/or separate the style/formatting from the HTML string. In these cases, you might find it useful to create CSS rules rather than using inline CSS. Creating CSS rules is a lot like using inline CSS, except that you also need to use a CSS selector . This is because your CSS rules aren't attached to any specific HTML element (unlike inline CSS), so you need to tell the browser which element(s) the style rules should apply to. The syntax is \"css-selector { <parameter-name> : <parameter-value> ; }\". In the example below, the CSS selector \"p\" tells the browser to apply the font size change to any text that is inside of a <p> element. p { font-size : 30 px ; } You can make more specific changes using CSS rules. The specificity will depend on the CSS selectors that are used. In addition to using the tag name (e.g. \"p\"), other common CSS selectors include the element's ID or class . If you are selecting an element using it's ID, then the CSS selector needs to have a # in front of the ID, e.g. \"#stimulus\". If you are selecting elements based on their class, then you need to include a . in front of the class, e.g. \".large-text\". In the example below, the \"#stimulus\" CSS selector means that the width change will only affect elements with the \"stimulus\" ID, and the \".large-text\" CSS selector means that the font size change will only affect elements that have the \"large-text\" class. # stimulus width : 300px ; } . large-text { font-size : 200 % ; } It is possible to create even more specific CSS selectors, for instance by combining tags, IDs, and/or classes. For example, let's say that you are showing feedback text to participants, and that this text is inside of a <p> tag. You could add the ID \"correct\" to the <p> element for correct response feedback, and the ID \"incorrect\" to the <p> element for incorrect response feedback. Then you can define separate styles for correct and incorrect feedback text like this: p # incorrect { color : red ; } p # correct { color : green ; } See this page about CSS selectors for a complete reference of CSS selector patterns and their meanings. With style tags \u00b6 You can add CSS rules to your HTML page by putting them inside of <style> tags. These rules will be applied to your whole experiment . This method can be useful for making general changes to the way that your experiment looks. In the example below, the default font size is set to 25px throughout the experiment. This will overrule the default font size of 18px that is set in the jspsych.css file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . jspsych-display-element { font-size : 25 px ; } </ style > </ head > With a stylesheet \u00b6 CSS rules can also be applied to your experiment with a link to an external CSS file. This is the same method that is usually used to apply the style from jspsych.css to an experiment. These rules will be applied to your whole experiment . You may find it useful to use a custom stylesheet when you want to re-use the same CSS rules across multiple experiments (HTML files). This example shows how to add a custom CSS file in addition to the styles provided in jspsych.css. In this example, the custom CSS file is called \"my_experiment_style.css\" and it is located in the same directory as your HTML file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < link rel = \"stylesheet\" href = \"my_experiment_style.css\" > </ head > Below are the some example contents of an external CSS file, like the \"my_experiment_style.css\" from the example above. This CSS will (1) change the page background color to black, (2) change the default font to 25px and white, and (3) limit the width of the page content so that it can only take up to 80% of its normal width. body { background-color : black ; } . jspsych-display-element { font-size : 25 px ; color : white ; } . jspsych-content { max-width : 80 % ; } Note <style> tags are not used inside of an external CSS file. Using the css_classes trial parameter \u00b6 CSS rules can also be applied in a trial-specific way using the css_classes parameter. This parameter will apply one or more class to the <div> element that holds all of the jsPsych page content during that specific trial. This way you can treat CSS styles just like any other trial parameter. You can use a static css_classes parameter value if you always want to apply the same CSS rules to the trial. In the 'fixation' example below, separating the style rules from the stimulus string makes the code a little bit 'cleaner', and this makes it easier to re-use the same style rules in other parts of the experiment. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . fixation { font-size : 90 px ; font-weight : bold ; color : gray ;} </ style > </ head > < script > var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 , css_classes : [ 'fixation' ] } // ... </ script > You may want the css_classes parameter to vary across trials. If so, you can turn it into a dynamic parameter or use timeline variables (see examples below). One thing to note about the css_classes parameter is that it only adds the class(es) to the jspsych-content <div> element, which is the \"parent\" element that contains all of the experiment content. Often you'll want your CSS rules to be applied to other elements inside of this jspsych-content div. Sometimes your CSS rules will be \"inherited\" by all of the other jsPsych content inside of this parent <div>. For instance, in the fixation example above, the CSS rules that change the font size, weight and color are applied to the parent <div> and automatically passed on to the stimulus text through inheritance. There are two reasons why a CSS rule like the one above for fixation may not work the way you expect: Not all CSS properties are inherited from the parent element. When a CSS property is inherited from the parent element, it will affect all elements in a given trial. In these cases, you can change your CSS selector to make it more specific: add a space after class name, then add more CSS selectors to select the specific element(s) that you want to change. Tip To find out this more specific CSS selector, you can right-click on the element and select Inspect . In the inspector window, right-click on the property corresponding to the element and copy the selector. You might need to increase the trial's trial_duration to give yourself enough time to inspect the elements on the page. See more tips for working with CSS below. In the example below, the CSS selector .left-align #stimulus selects the element with the ID \"stimulus\" that is inside of an element with the class \"left-align\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ) }], timeline_variables : [ { css_classes : [ 'left-align' ]}, { css_classes : [ 'right-align' ]} ] } // ... </ script > It's also possible to pass multiple class names to the css_classes parameter. This can be useful for creating conditions that involve crossing different style-related factors. This example shows you to combine two text alignment and two text color factors to produce four different stimulus conditions: < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} . teal # stimulus { color : teal ;} . purple # stimulus { color : purple ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ), data : { condition : jsPsych . timelineVariable ( 'condition' )} }], timeline_variables : [ { css_classes : [ 'left-align' , 'teal' ], condition : 'left-teal' }, { css_classes : [ 'right-align' , 'teal' ], condition : 'right-teal' }, { css_classes : [ 'left-align' , 'purple' ], condition : 'left-purple' }, { css_classes : [ 'right-align' , 'purple' ], condition : 'right-purple' } ] } // ... </ script > See the \"css-classes-parameter.html\" file in jsPsych's examples subfolder for more explanation and examples. Tips for working with CSS \u00b6 Your browser's developer tools contain very useful features for exploring and debugging your experiment's style and formatting. Open your browser's developer tools and click on the Element Inspector button or go to the Elements tab. Once you have selected an element on the page, you can see all of the information that can be used to select it, including: tag name, e.g., \"div\", \"p\", \"img\", \"button\" ID, if it has one class(es), if it has any You can then use this information to create a CSS selector to modify that element's style. As you can see, jsPsych adds its own IDs and classes to many elements. You can use the developer tools to determine what IDs and classes already exist for the elements that you want to modify, as you may can often just use these instead of adding your own. For instance, in the \"html-keyboard-response\" plugin, the stimulus will always be shown in a <div> with the ID \"jspsych-html-keyboard-response-stimulus\". So you can create a CSS rule that is applied to all \"html-keyboard-response\" stimuli like this: # jspsych-html-keyboard-response-stimulus { color : white ; background-color : blue ; width : 100 px ; border : 4 px solid black ; } As another example, most jsPsych buttons have the class \"jspsych-btn\", so you can use this class to change the default button styling: . jspsych-btn { padding : 20 px 20 px ; font-size : 25 px ; border-color : black ; } You can also use the developer tools to change an element's CSS and immediately see the effect that the changes will have on the page. These changes are just temporary, so you will still need to use one of methods described above to add the CSS changes to your experiment. However, making changes in the developer tools is very useful for figuring out which CSS properties to change and which values to use. This area of the developer tools also shows what styles are currently applied to the element and where those style rules are coming from. There are a few things to be aware of while debugging problems with CSS. When there are conflicting CSS rules, some CSS rules will take precedence over others . For instance, inline CSS usually takes precedence over other CSS rules, and more specific CSS selectors usually take precedence over less specific ones. When there are conflicting CSS rules that have the same level of precedence, the last rule will override any earlier rules . For that reason it's important to add your own custom stylesheet after the default jspsych.css stylesheet. See this page about CSS precedence for more information. If one CSS style rule is overridden by another one, the rule that is overridden will appear in strikethrough text in the element's \"Styles\" section. Also, if you are using an incorrect CSS property name or an invalid value, then that will show up here as an error, indicated by both strikethrough text and a little yellow warning symbol.","title":"Controlling Visual Appearance"},{"location":"overview/style/#controlling-visual-appearance","text":"Your experiment's style and formatting comes from the CSS (cascading style sheet) rules that are stored in the jspsych.css file, and the browser's defaults. There are a few ways to change the style and formatting in your experiment. The method that you choose is partly a matter of personal preference. It might also depend on whether you want the style/formatting change(s) to apply to specific trials , to the whole experiment (HTML page), or across different experiments . This section discusses the different ways of incorporating CSS into your jsPsych experiment. You can also see this page about adding CSS to web pages to learn more.","title":"Controlling Visual Appearance"},{"location":"overview/style/#inline-css","text":"Whenever you're using a parameter that accepts an HTML-formatted string, you have the option to include inline CSS. Inline CSS is a way of adding style and formatting directly into a specific HTML element using its \"style\" attribute . This is a good option for when you want to make few and/or simple style changes to an HTML trial parameter. To change an element's style using inline CSS, you can set the element's \"style\" attribute to a string that contains the CSS parameters that you want to change, along with the values that you want to use. The syntax is \" <parameter-name> : <parameter-value> ;\". In the example below, the stimulus font size is set to 30px and the text color is set to red. These changes will only be applied to this stimulus text in this specific trial. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:30px;color:red;\">hello world!</p>' } You can also use a dynamic parameter to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and timeline variables : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var stim = '<p style=\"font-size:30px;font-weight:bold;\">' + jsPsych . timelineVariable ( 'text' ) + '</p>' ; return stim ; } } var trial_procedure = { timeline : [ trial ], timeline_variables : [ { text : 'Welcome' }, { text : 'to' }, { text : 'the' }, { text : 'experiment!' } ] }","title":"Inline CSS"},{"location":"overview/style/#adding-css-rules","text":"You may want to add a lot of different CSS changes to your experiment, re-use the same change(s) across lots of different trials, and/or separate the style/formatting from the HTML string. In these cases, you might find it useful to create CSS rules rather than using inline CSS. Creating CSS rules is a lot like using inline CSS, except that you also need to use a CSS selector . This is because your CSS rules aren't attached to any specific HTML element (unlike inline CSS), so you need to tell the browser which element(s) the style rules should apply to. The syntax is \"css-selector { <parameter-name> : <parameter-value> ; }\". In the example below, the CSS selector \"p\" tells the browser to apply the font size change to any text that is inside of a <p> element. p { font-size : 30 px ; } You can make more specific changes using CSS rules. The specificity will depend on the CSS selectors that are used. In addition to using the tag name (e.g. \"p\"), other common CSS selectors include the element's ID or class . If you are selecting an element using it's ID, then the CSS selector needs to have a # in front of the ID, e.g. \"#stimulus\". If you are selecting elements based on their class, then you need to include a . in front of the class, e.g. \".large-text\". In the example below, the \"#stimulus\" CSS selector means that the width change will only affect elements with the \"stimulus\" ID, and the \".large-text\" CSS selector means that the font size change will only affect elements that have the \"large-text\" class. # stimulus width : 300px ; } . large-text { font-size : 200 % ; } It is possible to create even more specific CSS selectors, for instance by combining tags, IDs, and/or classes. For example, let's say that you are showing feedback text to participants, and that this text is inside of a <p> tag. You could add the ID \"correct\" to the <p> element for correct response feedback, and the ID \"incorrect\" to the <p> element for incorrect response feedback. Then you can define separate styles for correct and incorrect feedback text like this: p # incorrect { color : red ; } p # correct { color : green ; } See this page about CSS selectors for a complete reference of CSS selector patterns and their meanings.","title":"Adding CSS rules"},{"location":"overview/style/#with-style-tags","text":"You can add CSS rules to your HTML page by putting them inside of <style> tags. These rules will be applied to your whole experiment . This method can be useful for making general changes to the way that your experiment looks. In the example below, the default font size is set to 25px throughout the experiment. This will overrule the default font size of 18px that is set in the jspsych.css file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . jspsych-display-element { font-size : 25 px ; } </ style > </ head >","title":"With style tags"},{"location":"overview/style/#with-a-stylesheet","text":"CSS rules can also be applied to your experiment with a link to an external CSS file. This is the same method that is usually used to apply the style from jspsych.css to an experiment. These rules will be applied to your whole experiment . You may find it useful to use a custom stylesheet when you want to re-use the same CSS rules across multiple experiments (HTML files). This example shows how to add a custom CSS file in addition to the styles provided in jspsych.css. In this example, the custom CSS file is called \"my_experiment_style.css\" and it is located in the same directory as your HTML file. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < link rel = \"stylesheet\" href = \"my_experiment_style.css\" > </ head > Below are the some example contents of an external CSS file, like the \"my_experiment_style.css\" from the example above. This CSS will (1) change the page background color to black, (2) change the default font to 25px and white, and (3) limit the width of the page content so that it can only take up to 80% of its normal width. body { background-color : black ; } . jspsych-display-element { font-size : 25 px ; color : white ; } . jspsych-content { max-width : 80 % ; } Note <style> tags are not used inside of an external CSS file.","title":"With a stylesheet"},{"location":"overview/style/#using-the-css_classes-trial-parameter","text":"CSS rules can also be applied in a trial-specific way using the css_classes parameter. This parameter will apply one or more class to the <div> element that holds all of the jsPsych page content during that specific trial. This way you can treat CSS styles just like any other trial parameter. You can use a static css_classes parameter value if you always want to apply the same CSS rules to the trial. In the 'fixation' example below, separating the style rules from the stimulus string makes the code a little bit 'cleaner', and this makes it easier to re-use the same style rules in other parts of the experiment. < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . fixation { font-size : 90 px ; font-weight : bold ; color : gray ;} </ style > </ head > < script > var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 , css_classes : [ 'fixation' ] } // ... </ script > You may want the css_classes parameter to vary across trials. If so, you can turn it into a dynamic parameter or use timeline variables (see examples below). One thing to note about the css_classes parameter is that it only adds the class(es) to the jspsych-content <div> element, which is the \"parent\" element that contains all of the experiment content. Often you'll want your CSS rules to be applied to other elements inside of this jspsych-content div. Sometimes your CSS rules will be \"inherited\" by all of the other jsPsych content inside of this parent <div>. For instance, in the fixation example above, the CSS rules that change the font size, weight and color are applied to the parent <div> and automatically passed on to the stimulus text through inheritance. There are two reasons why a CSS rule like the one above for fixation may not work the way you expect: Not all CSS properties are inherited from the parent element. When a CSS property is inherited from the parent element, it will affect all elements in a given trial. In these cases, you can change your CSS selector to make it more specific: add a space after class name, then add more CSS selectors to select the specific element(s) that you want to change. Tip To find out this more specific CSS selector, you can right-click on the element and select Inspect . In the inspector window, right-click on the property corresponding to the element and copy the selector. You might need to increase the trial's trial_duration to give yourself enough time to inspect the elements on the page. See more tips for working with CSS below. In the example below, the CSS selector .left-align #stimulus selects the element with the ID \"stimulus\" that is inside of an element with the class \"left-align\". < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ) }], timeline_variables : [ { css_classes : [ 'left-align' ]}, { css_classes : [ 'right-align' ]} ] } // ... </ script > It's also possible to pass multiple class names to the css_classes parameter. This can be useful for creating conditions that involve crossing different style-related factors. This example shows you to combine two text alignment and two text color factors to produce four different stimulus conditions: < head > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link rel = \"stylesheet\" href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" > < style > . left-align # stimulus { text-align : left ; width : 600 px ;} . right-align # stimulus { text-align : right ; width : 600 px ;} . teal # stimulus { color : teal ;} . purple # stimulus { color : purple ;} </ style > </ head > < script > var trial_procedure = { timeline : [{ type : jsPsychHtmlKeyboardResponse , stimulus : '<p id=\"stimulus\">This is the stimulus.</p>' , prompt : '<p>This text will not be affected by the CSS classes ' + 'because it does not have the \"stimulus\" ID.</p>' , css_classes : jsPsych . timelineVariable ( 'css_classes' ), data : { condition : jsPsych . timelineVariable ( 'condition' )} }], timeline_variables : [ { css_classes : [ 'left-align' , 'teal' ], condition : 'left-teal' }, { css_classes : [ 'right-align' , 'teal' ], condition : 'right-teal' }, { css_classes : [ 'left-align' , 'purple' ], condition : 'left-purple' }, { css_classes : [ 'right-align' , 'purple' ], condition : 'right-purple' } ] } // ... </ script > See the \"css-classes-parameter.html\" file in jsPsych's examples subfolder for more explanation and examples.","title":"Using the css_classes trial parameter"},{"location":"overview/style/#tips-for-working-with-css","text":"Your browser's developer tools contain very useful features for exploring and debugging your experiment's style and formatting. Open your browser's developer tools and click on the Element Inspector button or go to the Elements tab. Once you have selected an element on the page, you can see all of the information that can be used to select it, including: tag name, e.g., \"div\", \"p\", \"img\", \"button\" ID, if it has one class(es), if it has any You can then use this information to create a CSS selector to modify that element's style. As you can see, jsPsych adds its own IDs and classes to many elements. You can use the developer tools to determine what IDs and classes already exist for the elements that you want to modify, as you may can often just use these instead of adding your own. For instance, in the \"html-keyboard-response\" plugin, the stimulus will always be shown in a <div> with the ID \"jspsych-html-keyboard-response-stimulus\". So you can create a CSS rule that is applied to all \"html-keyboard-response\" stimuli like this: # jspsych-html-keyboard-response-stimulus { color : white ; background-color : blue ; width : 100 px ; border : 4 px solid black ; } As another example, most jsPsych buttons have the class \"jspsych-btn\", so you can use this class to change the default button styling: . jspsych-btn { padding : 20 px 20 px ; font-size : 25 px ; border-color : black ; } You can also use the developer tools to change an element's CSS and immediately see the effect that the changes will have on the page. These changes are just temporary, so you will still need to use one of methods described above to add the CSS changes to your experiment. However, making changes in the developer tools is very useful for figuring out which CSS properties to change and which values to use. This area of the developer tools also shows what styles are currently applied to the element and where those style rules are coming from. There are a few things to be aware of while debugging problems with CSS. When there are conflicting CSS rules, some CSS rules will take precedence over others . For instance, inline CSS usually takes precedence over other CSS rules, and more specific CSS selectors usually take precedence over less specific ones. When there are conflicting CSS rules that have the same level of precedence, the last rule will override any earlier rules . For that reason it's important to add your own custom stylesheet after the default jspsych.css stylesheet. See this page about CSS precedence for more information. If one CSS style rule is overridden by another one, the rule that is overridden will appear in strikethrough text in the element's \"Styles\" section. Also, if you are using an incorrect CSS property name or an invalid value, then that will show up here as an error, indicated by both strikethrough text and a little yellow warning symbol.","title":"Tips for working with CSS"},{"location":"overview/timeline/","text":"Creating an Experiment: The Timeline \u00b6 To create an experiment using jsPsych, you need to specify a timeline that describes the structure of the experiment. The timeline is an ordered set of trials. You must create the timeline before launching the experiment. Most of the code you will write for an experiment will be code to create the timeline. This page walks through the creation of timelines, including very basic examples and more advanced features. A single trial \u00b6 To create a trial, you need to create an object that describes the trial. The most important feature of this object is the type parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the html-keyboard-response plugin to display a short message, the trial object would look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Welcome to the experiment.' } The parameters for this object (e.g., stimulus ) will depend on the plugin that you choose. Each plugin defines the set of parameters that are needed to run a trial with that plugin. Visit the documentation for a plugin to learn about the parameters that you can use with that plugin. To create a timeline with the single trial and run the experiment, just embed the trial object in an array. A timeline can simply be an array of trials. var timeline = [ trial ]; jsPsych . run ( timeline ); To create and run a simple experiment like this complete the hello world tutorial . Multiple trials \u00b6 Scaling up to multiple trials is straightforward. Create an object for each trial, and add each object to the timeline array. // with lots of trials, it might be easier to add the trials // to the timeline array as they are defined. var timeline = []; var trial_1 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 1.' } timeline . push ( trial_1 ); var trial_2 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 2.' } timeline . push ( trial_2 ); var trial_3 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 3.' } timeline . push ( trial_3 ); Nested timelines \u00b6 Each object on the timeline can also have it's own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the image-keyboard-response plugin , where the only thing that changes from trial-to-trial is the image file being displayed on the screen. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' }, { stimulus : 'image3.png' } ] } In the above code, the type , prompt , and choices parameters are automatically applied to all of the objects in the timeline array. This creates three trials with the same type , prompt , and choices parameters, but different values for the stimulus parameter. You can also override the values by declaring a new value in the timeline array. In the example below, the second trial will display a different prompt message. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' , prompt : '<p>Press 1 for this trial.</p>' }, { stimulus : 'image3.png' } ] } Timelines can be nested any number of times. Timeline variables \u00b6 A common pattern in behavioral experiments is to repeat the same procedure/task many times with slightly different parameters. A procedure might be a single trial, but it also might be a series of trials. For example, a task might involve a fixation cross appearing, followed by a blank screen, followed by an image for a short duration, followed by a prompt and a text box to report on some aspect of the image. One shortcut to implement this pattern is with the nested timeline approach described in the previous section, but this only works if all the trials use the same plugin type. Timeline variables are a more general solution. With timeline variables you define the procedure once (as a timeline) and specify a set of parameters and their values for each iteration through the timeline. What follows is an example of how to use timeline variables. The simple reaction time tutorial also explains how to use timeline variables. Suppose we want to create an experiment where people see a set of faces. Perhaps this is a memory experiment and this is the phase of the experiment where the faces are being presented for the first time. In between each face, a fixation cross is displayed on the screen. Without timeline variables, we would need to add many trials to the timeline, alternating between trials showing the fixation cross and trials showing the face and name. This could be done efficiently using a loop or function to create the timeline, but timeline variables make it even easier - as well as adding extra features like sampling and randomization. Here's a basic version of the task with timeline variables. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' }, { face : 'person-2.jpg' }, { face : 'person-3.jpg' }, { face : 'person-4.jpg' } ] } In the above version, there are four separate trials defined in the timeline_variables parameter. Each trial has a variable face and a variable name . The timeline defines a procedure of showing a fixation cross for 500ms followed by the face and name for 2500ms. This procedure will repeat four times, with the first trial showing 'person-1.jpg' , the second 'person-2.jpg' , and so on. The variables are referenced within the procedure by calling the jsPsych.timelineVariable() method and passing in the name of the variable. What if we wanted to add an additional step to the task where the name is displayed prior to the face appearing? (Maybe this is one condition of an experiment investigating whether the order of name-face or face-name affects retention.) We can add another variable to our list that gives the name associated with each image. Then we can add another trial to our timeline to show the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 1000 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] } Using in a function \u00b6 Continung the example from the previous section, what if we wanted to show the name with the face, combining the two variables together? To do this, we can use a dynamic parameter (a function) to create an HTML-string that uses both variables in a single parameter. The value of the stimulus parameter will be a function that returns an HTML string that contains both the image and the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ var html = ` <img src=\" ${ jsPsych . timelineVariable ( 'face' ) } \"> <p> ${ jsPsych . timelineVariable ( 'name' ) } </p>` ; return html ; }, choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] } Random orders of trials \u00b6 If we want to randomize the order of the trials, we can set randomize_order to true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true } Sampling methods \u00b6 There are also sampling methods that can be used to select a set of trials from the timeline_variables. Sampling is declared by creating a sample parameter. The sample parameter is given an object of arguments. The type parameter in this object controls the type of sampling that is done. Valid values for type are \"with-replacement\" : Sample size items from the timeline variables with the possibility of choosing the same item multiple time. \"without-replacement\" : Sample size items from timeline variables, with each item being selected a maximum of 1 time. \"fixed-repetitons\" : Repeat each item in the timeline variables size times, in a random order. Unlike using the repetitons parameter, this method allows for consecutive trials to use the same timeline variable set. \"alternate-groups\" : Sample in an alternating order based on a declared group membership. Groups are defined by the groups parameter. This parameter takes an array of arrays, where each inner array is a group and the items in the inner array are the indices of the timeline variables in the timeline_variables array that belong to that group. \"custom\" : Write a function that returns a custom order of the timeline variables. Sampling with replacement \u00b6 This sample parameter will create 10 repetitions, sampling with replacement. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 } } Sampling with replacement, unequal probabilities \u00b6 This sample parameter will make the \"Alex\" trial three times as likely to be sampled as the others. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 , weights : [ 3 , 1 , 1 , 1 ] } } Sampling without replacement \u00b6 This sample parameter will pick three of the four possible trials to run at random. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'without-replacement' , size : 3 } } Repeating each trial a fixed number of times in a random order \u00b6 This sample parameter will create 3 repetitions of each trial, for a total of 12 trials, with a random order. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'fixed-repetitions' , size : 3 } } Alternating groups \u00b6 This sample parameter puts the \"Alex\" and \"Chad\" trials in group 1 and the \"Beth\" and \"Dave\" trials in group 2. The resulting sample of trials will follow the pattern group 1 -> group 2 -> group 1 -> group 2 . Each trial will be selected only one time. If you wanted group 2 to sometimes be first, you could set randomize_group_order: true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'alternate-groups' , groups : [[ 0 , 2 ],[ 1 , 3 ]], randomize_group_order : false } } Custom sampling function \u00b6 Any sampling method can be implemented using the custom type sampler. The order of trials will be determined by running the function supplied as fn . The function has a single parameter, t , which is an array of integers from 0 to n-1 , where n is the number of trials in the timeline_variables array. The function must return an array that specifies the order of the trials, e.g., returning [3,3,2,2,1,1,0,0] would result in the order Dave -> Dave -> Chad -> Chad -> Beth -> Beth -> Alex -> Alex . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'custom' , fn : function ( t ){ return t . reverse (); // show the trials in the reverse order } } } Repeating a set of trials \u00b6 To repeat a timeline multiple times, you can create an object (node) that contains a timeline , which is the timeline array to repeat, and repetitions , which is the number of times to repeat that timeline. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be repeated twice.' } var node = { timeline : [ trial ], repetitions : 2 } The repetitions parameter can be used alongside other node parameters, such as timeline variables, loop functions, and/or conditional functions. If you are using timeline_variables and randomize_order is true , then the order of the timeline variables will re-randomize before every repetition. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , repetitions : 3 } Looping timelines \u00b6 Any timeline can be looped using the loop_function option. The loop function must be a function that evaluates to true if the timeline should repeat, and false if the timeline should end. It receives a single parameter, named data by convention. This parameter will be the DataCollection object with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial is in a loop. Press R to repeat this trial, or C to continue.' } var loop_node = { timeline : [ trial ], loop_function : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . values ()[ 0 ]. response , 'r' )){ return true ; } else { return false ; } } } Conditional timelines \u00b6 A timeline can be skipped or not based on the evaluation of the conditional_function option. If the conditional function evaluates to true , the timeline will execute normally. If the conditional function evaluates to false then the timeline will be skipped. The conditional function is evaluated whenever jsPsych is about to run the first trial on the timeline. var jsPsych = initJsPsych (); var pre_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The next trial is in a conditional statement. Press S to skip it, or V to view it.' } var if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'You chose to view the trial. Press any key to continue.' } var if_node = { timeline : [ if_trial ], conditional_function : function (){ // get the data from the previous trial, // and check which key was pressed var data = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]; if ( jsPsych . pluginAPI . compareKeys ( data . response , 's' )){ return false ; } else { return true ; } } } var after_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is the trial after the conditional.' } jsPsych . run ([ pre_if_trial , if_node , after_if_trial ]); Timeline start and finish functions \u00b6 You can run a custom function at the start and end of a timeline node using the on_timeline_start and on_timeline_finish callback function parameters. These are functions that will run when the timeline starts and ends, respectively. var procedure = { timeline : [ trial_1 , trial_2 ], on_timeline_start : function () { console . log ( 'The trial procedure just started.' ) }, on_timeline_finish : function () { console . log ( 'The trial procedure just finished.' ) } } This works the same way with timeline variables. The on_timeline_start and on_timeline_finish functions will run when timeline variables trials start and end, respectively. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , on_timeline_start : function () { console . log ( 'First trial is starting.' ) }, on_timeline_finish : function () { console . log ( 'Last trial just finished.' ) } } When the repetititons option is used (and is greater than 1), these functions will run once per repetition of the timeline. var repetition_count = 0 ; var procedure = { timeline : [ trial_1 , trial_2 ], repetitions : 3 , on_timeline_start : function () { repetition_count ++ ; console . log ( 'Repetition number ' , repetition_count , ' has just started.' ); }, on_timeline_finish : function () { console . log ( 'Repetition number ' , repetition_count , ' has just finished.' ) } }","title":"Creating an Experiment: The Timeline"},{"location":"overview/timeline/#creating-an-experiment-the-timeline","text":"To create an experiment using jsPsych, you need to specify a timeline that describes the structure of the experiment. The timeline is an ordered set of trials. You must create the timeline before launching the experiment. Most of the code you will write for an experiment will be code to create the timeline. This page walks through the creation of timelines, including very basic examples and more advanced features.","title":"Creating an Experiment: The Timeline"},{"location":"overview/timeline/#a-single-trial","text":"To create a trial, you need to create an object that describes the trial. The most important feature of this object is the type parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the html-keyboard-response plugin to display a short message, the trial object would look like this: var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Welcome to the experiment.' } The parameters for this object (e.g., stimulus ) will depend on the plugin that you choose. Each plugin defines the set of parameters that are needed to run a trial with that plugin. Visit the documentation for a plugin to learn about the parameters that you can use with that plugin. To create a timeline with the single trial and run the experiment, just embed the trial object in an array. A timeline can simply be an array of trials. var timeline = [ trial ]; jsPsych . run ( timeline ); To create and run a simple experiment like this complete the hello world tutorial .","title":"A single trial"},{"location":"overview/timeline/#multiple-trials","text":"Scaling up to multiple trials is straightforward. Create an object for each trial, and add each object to the timeline array. // with lots of trials, it might be easier to add the trials // to the timeline array as they are defined. var timeline = []; var trial_1 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 1.' } timeline . push ( trial_1 ); var trial_2 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 2.' } timeline . push ( trial_2 ); var trial_3 = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is trial 3.' } timeline . push ( trial_3 );","title":"Multiple trials"},{"location":"overview/timeline/#nested-timelines","text":"Each object on the timeline can also have it's own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the image-keyboard-response plugin , where the only thing that changes from trial-to-trial is the image file being displayed on the screen. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' }, { stimulus : 'image3.png' } ] } In the above code, the type , prompt , and choices parameters are automatically applied to all of the objects in the timeline array. This creates three trials with the same type , prompt , and choices parameters, but different values for the stimulus parameter. You can also override the values by declaring a new value in the timeline array. In the example below, the second trial will display a different prompt message. var judgment_trials = { type : jsPsychImageKeyboardResponse , prompt : '<p>Press a number 1-7 to indicate how unusual the image is.</p>' , choices : [ '1' , '2' , '3' , '4' , '5' , '6' , '7' ], timeline : [ { stimulus : 'image1.png' }, { stimulus : 'image2.png' , prompt : '<p>Press 1 for this trial.</p>' }, { stimulus : 'image3.png' } ] } Timelines can be nested any number of times.","title":"Nested timelines"},{"location":"overview/timeline/#timeline-variables","text":"A common pattern in behavioral experiments is to repeat the same procedure/task many times with slightly different parameters. A procedure might be a single trial, but it also might be a series of trials. For example, a task might involve a fixation cross appearing, followed by a blank screen, followed by an image for a short duration, followed by a prompt and a text box to report on some aspect of the image. One shortcut to implement this pattern is with the nested timeline approach described in the previous section, but this only works if all the trials use the same plugin type. Timeline variables are a more general solution. With timeline variables you define the procedure once (as a timeline) and specify a set of parameters and their values for each iteration through the timeline. What follows is an example of how to use timeline variables. The simple reaction time tutorial also explains how to use timeline variables. Suppose we want to create an experiment where people see a set of faces. Perhaps this is a memory experiment and this is the phase of the experiment where the faces are being presented for the first time. In between each face, a fixation cross is displayed on the screen. Without timeline variables, we would need to add many trials to the timeline, alternating between trials showing the fixation cross and trials showing the face and name. This could be done efficiently using a loop or function to create the timeline, but timeline variables make it even easier - as well as adding extra features like sampling and randomization. Here's a basic version of the task with timeline variables. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' }, { face : 'person-2.jpg' }, { face : 'person-3.jpg' }, { face : 'person-4.jpg' } ] } In the above version, there are four separate trials defined in the timeline_variables parameter. Each trial has a variable face and a variable name . The timeline defines a procedure of showing a fixation cross for 500ms followed by the face and name for 2500ms. This procedure will repeat four times, with the first trial showing 'person-1.jpg' , the second 'person-2.jpg' , and so on. The variables are referenced within the procedure by calling the jsPsych.timelineVariable() method and passing in the name of the variable. What if we wanted to add an additional step to the task where the name is displayed prior to the face appearing? (Maybe this is one condition of an experiment investigating whether the order of name-face or face-name affects retention.) We can add another variable to our list that gives the name associated with each image. Then we can add another trial to our timeline to show the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'face' ), choices : \"NO_KEYS\" , trial_duration : 1000 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] }","title":"Timeline variables"},{"location":"overview/timeline/#using-in-a-function","text":"Continung the example from the previous section, what if we wanted to show the name with the face, combining the two variables together? To do this, we can use a dynamic parameter (a function) to create an HTML-string that uses both variables in a single parameter. The value of the stimulus parameter will be a function that returns an HTML string that contains both the image and the name. var face_name_procedure = { timeline : [ { type : jsPsychHtmlKeyboardResponse , stimulus : '+' , choices : \"NO_KEYS\" , trial_duration : 500 }, { type : jsPsychHtmlKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'name' ), trial_duration : 1000 , choices : \"NO_KEYS\" }, { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ var html = ` <img src=\" ${ jsPsych . timelineVariable ( 'face' ) } \"> <p> ${ jsPsych . timelineVariable ( 'name' ) } </p>` ; return html ; }, choices : \"NO_KEYS\" , trial_duration : 2500 } ], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ] }","title":"Using in a function"},{"location":"overview/timeline/#random-orders-of-trials","text":"If we want to randomize the order of the trials, we can set randomize_order to true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true }","title":"Random orders of trials"},{"location":"overview/timeline/#sampling-methods","text":"There are also sampling methods that can be used to select a set of trials from the timeline_variables. Sampling is declared by creating a sample parameter. The sample parameter is given an object of arguments. The type parameter in this object controls the type of sampling that is done. Valid values for type are \"with-replacement\" : Sample size items from the timeline variables with the possibility of choosing the same item multiple time. \"without-replacement\" : Sample size items from timeline variables, with each item being selected a maximum of 1 time. \"fixed-repetitons\" : Repeat each item in the timeline variables size times, in a random order. Unlike using the repetitons parameter, this method allows for consecutive trials to use the same timeline variable set. \"alternate-groups\" : Sample in an alternating order based on a declared group membership. Groups are defined by the groups parameter. This parameter takes an array of arrays, where each inner array is a group and the items in the inner array are the indices of the timeline variables in the timeline_variables array that belong to that group. \"custom\" : Write a function that returns a custom order of the timeline variables.","title":"Sampling methods"},{"location":"overview/timeline/#sampling-with-replacement","text":"This sample parameter will create 10 repetitions, sampling with replacement. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 } }","title":"Sampling with replacement"},{"location":"overview/timeline/#sampling-with-replacement-unequal-probabilities","text":"This sample parameter will make the \"Alex\" trial three times as likely to be sampled as the others. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'with-replacement' , size : 10 , weights : [ 3 , 1 , 1 , 1 ] } }","title":"Sampling with replacement, unequal probabilities"},{"location":"overview/timeline/#sampling-without-replacement","text":"This sample parameter will pick three of the four possible trials to run at random. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'without-replacement' , size : 3 } }","title":"Sampling without replacement"},{"location":"overview/timeline/#repeating-each-trial-a-fixed-number-of-times-in-a-random-order","text":"This sample parameter will create 3 repetitions of each trial, for a total of 12 trials, with a random order. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'fixed-repetitions' , size : 3 } }","title":"Repeating each trial a fixed number of times in a random order"},{"location":"overview/timeline/#alternating-groups","text":"This sample parameter puts the \"Alex\" and \"Chad\" trials in group 1 and the \"Beth\" and \"Dave\" trials in group 2. The resulting sample of trials will follow the pattern group 1 -> group 2 -> group 1 -> group 2 . Each trial will be selected only one time. If you wanted group 2 to sometimes be first, you could set randomize_group_order: true . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'alternate-groups' , groups : [[ 0 , 2 ],[ 1 , 3 ]], randomize_group_order : false } }","title":"Alternating groups"},{"location":"overview/timeline/#custom-sampling-function","text":"Any sampling method can be implemented using the custom type sampler. The order of trials will be determined by running the function supplied as fn . The function has a single parameter, t , which is an array of integers from 0 to n-1 , where n is the number of trials in the timeline_variables array. The function must return an array that specifies the order of the trials, e.g., returning [3,3,2,2,1,1,0,0] would result in the order Dave -> Dave -> Chad -> Chad -> Beth -> Beth -> Alex -> Alex . var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], sample : { type : 'custom' , fn : function ( t ){ return t . reverse (); // show the trials in the reverse order } } }","title":"Custom sampling function"},{"location":"overview/timeline/#repeating-a-set-of-trials","text":"To repeat a timeline multiple times, you can create an object (node) that contains a timeline , which is the timeline array to repeat, and repetitions , which is the number of times to repeat that timeline. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial will be repeated twice.' } var node = { timeline : [ trial ], repetitions : 2 } The repetitions parameter can be used alongside other node parameters, such as timeline variables, loop functions, and/or conditional functions. If you are using timeline_variables and randomize_order is true , then the order of the timeline variables will re-randomize before every repetition. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , repetitions : 3 }","title":"Repeating a set of trials"},{"location":"overview/timeline/#looping-timelines","text":"Any timeline can be looped using the loop_function option. The loop function must be a function that evaluates to true if the timeline should repeat, and false if the timeline should end. It receives a single parameter, named data by convention. This parameter will be the DataCollection object with all of the data from the trials executed in the last iteration of the timeline. The loop function will be evaluated after the timeline is completed. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This trial is in a loop. Press R to repeat this trial, or C to continue.' } var loop_node = { timeline : [ trial ], loop_function : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . values ()[ 0 ]. response , 'r' )){ return true ; } else { return false ; } } }","title":"Looping timelines"},{"location":"overview/timeline/#conditional-timelines","text":"A timeline can be skipped or not based on the evaluation of the conditional_function option. If the conditional function evaluates to true , the timeline will execute normally. If the conditional function evaluates to false then the timeline will be skipped. The conditional function is evaluated whenever jsPsych is about to run the first trial on the timeline. var jsPsych = initJsPsych (); var pre_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'The next trial is in a conditional statement. Press S to skip it, or V to view it.' } var if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'You chose to view the trial. Press any key to continue.' } var if_node = { timeline : [ if_trial ], conditional_function : function (){ // get the data from the previous trial, // and check which key was pressed var data = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]; if ( jsPsych . pluginAPI . compareKeys ( data . response , 's' )){ return false ; } else { return true ; } } } var after_if_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is the trial after the conditional.' } jsPsych . run ([ pre_if_trial , if_node , after_if_trial ]);","title":"Conditional timelines"},{"location":"overview/timeline/#timeline-start-and-finish-functions","text":"You can run a custom function at the start and end of a timeline node using the on_timeline_start and on_timeline_finish callback function parameters. These are functions that will run when the timeline starts and ends, respectively. var procedure = { timeline : [ trial_1 , trial_2 ], on_timeline_start : function () { console . log ( 'The trial procedure just started.' ) }, on_timeline_finish : function () { console . log ( 'The trial procedure just finished.' ) } } This works the same way with timeline variables. The on_timeline_start and on_timeline_finish functions will run when timeline variables trials start and end, respectively. var face_name_procedure = { timeline : [...], timeline_variables : [ { face : 'person-1.jpg' , name : 'Alex' }, { face : 'person-2.jpg' , name : 'Beth' }, { face : 'person-3.jpg' , name : 'Chad' }, { face : 'person-4.jpg' , name : 'Dave' } ], randomize_order : true , on_timeline_start : function () { console . log ( 'First trial is starting.' ) }, on_timeline_finish : function () { console . log ( 'Last trial just finished.' ) } } When the repetititons option is used (and is greater than 1), these functions will run once per repetition of the timeline. var repetition_count = 0 ; var procedure = { timeline : [ trial_1 , trial_2 ], repetitions : 3 , on_timeline_start : function () { repetition_count ++ ; console . log ( 'Repetition number ' , repetition_count , ' has just started.' ); }, on_timeline_finish : function () { console . log ( 'Repetition number ' , repetition_count , ' has just finished.' ) } }","title":"Timeline start and finish functions"},{"location":"overview/timing-accuracy/","text":"Timing accuracy \u00b6 Wondering if jsPsych can be used for research that depends on accurate display times or response time measurement? For most purposes, the answer is yes. Display timing is somewhat less accurate in JavaScript than in standard experimental software that runs on a desktop. Desktop software can have closer integration with the graphics devices of the machine than JavaScript currently permits. If a one or two frame (17-33ms) difference in display timing matters for your experiment, then you'll want to be careful with JavaScript-based experiments. It is possible to achieve this level of control in JavaScript, but it often requires code that is more tailored to your experiment and some restrictions about which browsers can be used to run the experiment. Tip If you are hoping to run an experiment with the best timing that jsPsych can offer, we currently recommend using the jspsych-psychophysics plugin developed by Daiichiro Kuroki . Kuroki, D. (2021). A new jsPsych plugin for psychophysics, providing accurate display duration and stimulus onset asynchrony. Behavior Research Methods , 53 , 301\u2013310. https://doi.org/10.3758/s13428-020-01445-w Response time measurements in jsPsych (and JavaScript in general) are comparable to those taken in standard lab software like Psychophysics Toolbox and E-Prime. Response times measured in JavaScript tend to be a little bit longer (10-40ms), but have similar variance. References \u00b6 See the following papers for extensive work on display and response timing in browser-based experiments. Note that browsers are updating frequently and the JavaScript language specification is also changing. It's possible that the results from these papers do not apply to current versions of web browsers. Future updates to JavaScript APIs will likely improve the ability of online experiments to provide more accurate display timing and response time measurement. Bridges, D., Pitiot, A., MacAskill, M. R., & Peirce, J. W. (2020). The timing mega-study: Comparing a range of experiment generators, both lab-based and online. PeerJ, 8 , e9414. Anwyl-Irvine, A., Dalmaijer, E. S., Hodges, N., & Evershed, J. K. (2020). Realistic precision and accuracy of online experiment platforms, web browsers, and devices. Behavior Research Methods, 53, 1-19. Pronk, T., Wiers, R. W., Molenkamp, B., & Murre, J. (2020). Mental chronometry in the pocket? Timing accuracy of web applications on touchscreen and keyboard devices. Behavior Research Methods, 52 (3), 1371-1382. Pinet, S., Zielinski, C., Math\u00f4t, S. et al. (2017). Measuring sequences of keystrokes with jsPsych: Reliability of response times and interkeystroke intervals. Behavior Research Methods , 49 (3), 1177-1178. de Leeuw, J. R., & Motz, B. A. (2016). Psychophysics in a Web browser? Comparing response times collected with JavaScript and Psychophysics Toolbox in a visual search task. Behavior Research Methods , 48 (1), 1-12. Hilbig, B. E. (2016). Reaction time effects in lab- versus web-based research: Experimental evidence. Behavior Research Methods , 48 (4), 1718-1724. Reimers, S., & Stewart, N. (2015). Presentation and response time accuracy in Adobe Flash and HTML5/JavaScript Web experiments. Behavior Research Methods , 47 (2), 309-327.","title":"Timing Accuracy"},{"location":"overview/timing-accuracy/#timing-accuracy","text":"Wondering if jsPsych can be used for research that depends on accurate display times or response time measurement? For most purposes, the answer is yes. Display timing is somewhat less accurate in JavaScript than in standard experimental software that runs on a desktop. Desktop software can have closer integration with the graphics devices of the machine than JavaScript currently permits. If a one or two frame (17-33ms) difference in display timing matters for your experiment, then you'll want to be careful with JavaScript-based experiments. It is possible to achieve this level of control in JavaScript, but it often requires code that is more tailored to your experiment and some restrictions about which browsers can be used to run the experiment. Tip If you are hoping to run an experiment with the best timing that jsPsych can offer, we currently recommend using the jspsych-psychophysics plugin developed by Daiichiro Kuroki . Kuroki, D. (2021). A new jsPsych plugin for psychophysics, providing accurate display duration and stimulus onset asynchrony. Behavior Research Methods , 53 , 301\u2013310. https://doi.org/10.3758/s13428-020-01445-w Response time measurements in jsPsych (and JavaScript in general) are comparable to those taken in standard lab software like Psychophysics Toolbox and E-Prime. Response times measured in JavaScript tend to be a little bit longer (10-40ms), but have similar variance.","title":"Timing accuracy"},{"location":"overview/timing-accuracy/#references","text":"See the following papers for extensive work on display and response timing in browser-based experiments. Note that browsers are updating frequently and the JavaScript language specification is also changing. It's possible that the results from these papers do not apply to current versions of web browsers. Future updates to JavaScript APIs will likely improve the ability of online experiments to provide more accurate display timing and response time measurement. Bridges, D., Pitiot, A., MacAskill, M. R., & Peirce, J. W. (2020). The timing mega-study: Comparing a range of experiment generators, both lab-based and online. PeerJ, 8 , e9414. Anwyl-Irvine, A., Dalmaijer, E. S., Hodges, N., & Evershed, J. K. (2020). Realistic precision and accuracy of online experiment platforms, web browsers, and devices. Behavior Research Methods, 53, 1-19. Pronk, T., Wiers, R. W., Molenkamp, B., & Murre, J. (2020). Mental chronometry in the pocket? Timing accuracy of web applications on touchscreen and keyboard devices. Behavior Research Methods, 52 (3), 1371-1382. Pinet, S., Zielinski, C., Math\u00f4t, S. et al. (2017). Measuring sequences of keystrokes with jsPsych: Reliability of response times and interkeystroke intervals. Behavior Research Methods , 49 (3), 1177-1178. de Leeuw, J. R., & Motz, B. A. (2016). Psychophysics in a Web browser? Comparing response times collected with JavaScript and Psychophysics Toolbox in a visual search task. Behavior Research Methods , 48 (1), 1-12. Hilbig, B. E. (2016). Reaction time effects in lab- versus web-based research: Experimental evidence. Behavior Research Methods , 48 (4), 1718-1724. Reimers, S., & Stewart, N. (2015). Presentation and response time accuracy in Adobe Flash and HTML5/JavaScript Web experiments. Behavior Research Methods , 47 (2), 309-327.","title":"References"},{"location":"plugins/animation/","text":"animation \u00b6 Current version: 1.1.2. See version history . This plugin displays a sequence of images at a fixed frame rate. The sequence can be looped a specified number of times. The participant is free to respond at any point during the animation, and the time of the response is recorded. Parameters \u00b6 In addition to the 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. 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 in milliseconds. 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value animation_sequence array An array, where each element is an object that represents a stimulus in the animation sequence. Each object has a stimulus property, which is the image that was displayed, and a time property, which is the time in ms, measured from when the sequence began, that the stimulus was displayed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. response array An array, where each element is an object representing a response given by the participant. Each object has a stimulus property, indicating which image was displayed when the key was pressed, an rt property, indicating the time of the key press relative to the start of the animation, and a key_press property, indicating which key was pressed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-animation import animation from '@jspsych/plugin-animation' ; Examples \u00b6 Displaying a single sequence multiple times Code Demo var animation_sequence = [ \"img/happy_face_1.jpg\" , \"img/happy_face_2.jpg\" , \"img/happy_face_3.jpg\" , \"img/happy_face_4.jpg\" ]; var animation_trial = { type : jsPsychAnimation , stimuli : animation_sequence , sequence_reps : 3 , frame_time : 300 , prompt : '<p>Watch the faces.</p>' , }; Open demo in new tab","title":"animation"},{"location":"plugins/animation/#animation","text":"Current version: 1.1.2. See version history . This plugin displays a sequence of images at a fixed frame rate. The sequence can be looped a specified number of times. The participant is free to respond at any point during the animation, and the time of the response is recorded.","title":"animation"},{"location":"plugins/animation/#parameters","text":"In addition to the 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. 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 in milliseconds. 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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.","title":"Parameters"},{"location":"plugins/animation/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value animation_sequence array An array, where each element is an object that represents a stimulus in the animation sequence. Each object has a stimulus property, which is the image that was displayed, and a time property, which is the time in ms, measured from when the sequence began, that the stimulus was displayed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions. response array An array, where each element is an object representing a response given by the participant. Each object has a stimulus property, indicating which image was displayed when the key was pressed, an rt property, indicating the time of the key press relative to the start of the animation, and a key_press property, indicating which key was pressed. The array will be encoded in JSON format when data is saved using either the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/animation/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-animation import animation from '@jspsych/plugin-animation' ;","title":"Install"},{"location":"plugins/animation/#examples","text":"Displaying a single sequence multiple times Code Demo var animation_sequence = [ \"img/happy_face_1.jpg\" , \"img/happy_face_2.jpg\" , \"img/happy_face_3.jpg\" , \"img/happy_face_4.jpg\" ]; var animation_trial = { type : jsPsychAnimation , stimuli : animation_sequence , sequence_reps : 3 , frame_time : 300 , prompt : '<p>Watch the faces.</p>' , }; Open demo in new tab","title":"Examples"},{"location":"plugins/audio-button-response/","text":"audio-button-response \u00b6 Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with a button click. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the audio has finished playing. Parameters \u00b6 In addition to the 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-button-response import audioButtonResponse from '@jspsych/plugin-audio-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/tone.mp3' , choices : [ 'Low' , 'High' ], prompt : \"<p>Is the pitch high or low?</p>\" }; Open demo in new tab Using custom button HTML to use images as buttons Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/roar.mp3' , choices : [ 'lion.png' , 'elephant.png' , 'monkey.png' ], prompt : \"<p>Which animal made the sound?</p>\" , button_html : '<img src=\"%choice%\" />' }; Open demo in new tab Note : if you want the images to look more like jsPsych buttons, i.e. with borders and different styles for hover/active/disabled states, then you can also embed the image element inside the default button_html string: button_html : '<button class=\"jspsych-btn\"><img src=\"%choice%\" /></button>'","title":"audio-button-response"},{"location":"plugins/audio-button-response/#audio-button-response","text":"Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with a button click. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the audio has finished playing.","title":"audio-button-response"},{"location":"plugins/audio-button-response/#parameters","text":"In addition to the 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on.","title":"Data Generated"},{"location":"plugins/audio-button-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-button-response import audioButtonResponse from '@jspsych/plugin-audio-button-response' ;","title":"Install"},{"location":"plugins/audio-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/tone.mp3' , choices : [ 'Low' , 'High' ], prompt : \"<p>Is the pitch high or low?</p>\" }; Open demo in new tab Using custom button HTML to use images as buttons Code Demo var trial = { type : jsPsychAudioButtonResponse , stimulus : 'sound/roar.mp3' , choices : [ 'lion.png' , 'elephant.png' , 'monkey.png' ], prompt : \"<p>Which animal made the sound?</p>\" , button_html : '<img src=\"%choice%\" />' }; Open demo in new tab Note : if you want the images to look more like jsPsych buttons, i.e. with borders and different styles for hover/active/disabled states, then you can also embed the image element inside the default button_html string: button_html : '<button class=\"jspsych-btn\"><img src=\"%choice%\" /></button>'","title":"Examples"},{"location":"plugins/audio-keyboard-response/","text":"audio-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with the keyboard. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the audio has finished playing. Parameters \u00b6 In addition to the 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant 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. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-keyboard-response import audioKeyboardResponse from '@jspsych/plugin-audio-keyboard-response' ; Examples \u00b6 Trial continues until participant gives a response Code Demo var trial = { type : jsPsychAudioKeyboardResponse , 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 : true }; Open demo in new tab Play a sound with no user response; trial ends after sound plays Code Demo var trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'sound/tone.mp3' , choices : \"NO_KEYS\" , trial_ends_after_audio : true }; Open demo in new tab","title":"audio-keyboard-response"},{"location":"plugins/audio-keyboard-response/#audio-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin plays audio files and records responses generated with the keyboard. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, when the audio file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the audio has finished playing.","title":"audio-keyboard-response"},{"location":"plugins/audio-keyboard-response/#parameters","text":"In addition to the 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant 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.","title":"Data Generated"},{"location":"plugins/audio-keyboard-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-keyboard-response import audioKeyboardResponse from '@jspsych/plugin-audio-keyboard-response' ;","title":"Install"},{"location":"plugins/audio-keyboard-response/#examples","text":"Trial continues until participant gives a response Code Demo var trial = { type : jsPsychAudioKeyboardResponse , 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 : true }; Open demo in new tab Play a sound with no user response; trial ends after sound plays Code Demo var trial = { type : jsPsychAudioKeyboardResponse , stimulus : 'sound/tone.mp3' , choices : \"NO_KEYS\" , trial_ends_after_audio : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/audio-slider-response/","text":"audio-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin plays an audio file and allows the participant to respond by dragging a slider. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the audio has finished playing. Parameters \u00b6 In addition to the 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 participant 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. stimulus string The path of the audio file that was played. slider_start numeric The starting value of the slider. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-slider-response import audioSliderResponse from '@jspsych/plugin-audio-slider-response' ; Examples \u00b6 A simple rating scale Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' } Open demo in new tab No response allowed until audio finishes; participant must interact with slider to continue Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' , response_allowed_while_playing : false , require_movement : true } Open demo in new tab","title":"audio-slider-response"},{"location":"plugins/audio-slider-response/#audio-slider-response","text":"Current version: 1.1.2. See version history . This plugin plays an audio file and allows the participant to respond by dragging a slider. If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio. Audio files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the audio stimulus, then you will need to manually preload the audio. The trial can end when the participant responds, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the audio has finished playing.","title":"audio-slider-response"},{"location":"plugins/audio-slider-response/#parameters","text":"In addition to the 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 participant 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/audio-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first began playing until the participant's response. stimulus string The path of the audio file that was played. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/audio-slider-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/audio-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-audio-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-audio-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-audio-slider-response import audioSliderResponse from '@jspsych/plugin-audio-slider-response' ;","title":"Install"},{"location":"plugins/audio-slider-response/#examples","text":"A simple rating scale Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' } Open demo in new tab No response allowed until audio finishes; participant must interact with slider to continue Code Demo var trial = { type : jsPsychAudioSliderResponse , stimulus : 'sound/speech_joke.mp3' , labels : [ 'Not Funny' , 'Funny' ], prompt : '<p>How funny is the joke?</p>' , response_allowed_while_playing : false , require_movement : true } Open demo in new tab","title":"Examples"},{"location":"plugins/browser-check/","text":"browser-check \u00b6 Current version: 1.0.2. See version history . This plugin measures and records various features of the participant's browser and can end the experiment if defined inclusion criteria are not met. The plugin currently can record the following features: The width and height of the browser window in pixels. The type of browser used (e.g., Chrome, Firefox, Edge, etc.) and the version number of the browser.* Whether the participant is using a mobile device.* The operating system.* Support for the WebAudio API. Support for the Fullscreen API, e.g., through the fullscreen plugin . The display refresh rate in frames per second. Whether the device has a webcam and microphone. Note that this only reveals whether a webcam/microphone exists. The participant still needs to grant permission in order for the experiment to use these devices. Warning Features with an * are recorded by parsing the user agent string . This method is accurate most of the time, but is not guaranteed to be correct. The plugin uses the detect-browser package to perform user agent parsing. You can find a list of supported browsers and OSes in the source file . The plugin begins by measuring the set of features requested. An inclusion function is evaluated to see if the paricipant passes the inclusion criteria. If they do, then the trial ends and the experiment continues. If they do not, then the experiment ends immediately. If a minimum width and/or minimum height is desired, the plugin will optionally display a message to participants whose browser windows are too small to give them an opportunity to make the window larger if possible. See the examples below for more guidance. Parameters \u00b6 In addition to the 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 features array of strings [\"width\", \"height\", \"webaudio\", \"browser\", \"browser_version\", \"mobile\", \"os\", \"fullscreen\", \"vsync_rate\", \"webcam\", \"microphone\"] The list of browser features to record. The default value includes all of the available options. skip_features array of strings [] Any features listed here will be skipped, even if they appear in features . Use this when you want to run most of the defaults. vsync_frame_count int 60 The number of frames to sample when measuring the display refresh rate ( \"vsync_rate\" ). Increasing the number will potenially improve the stability of the estimate at the cost of increasing the amount of time the plugin takes during this test. On most devices, 60 frames takes about 1 second to measure. allow_window_resize bool true Whether to allow the participant to resize the browser window if the window is smaller than minimum_width and/or minimum_height . If false , then the minimum_width and minimum_height parameters are ignored and you can validate the size in the inclusion_function . minimum_height int 0 If allow_window_resize is true , then this is the minimum height of the window (in pixels) that must be met before continuing. minimum_width int 0 If allow_window_resize is true , then this is the minimum width of the window (in pixels) that must be met before continuing. window_resize_message string see description The message that will be displayed during the interactive resize when allow_window_resize is true and the window is too small. If the message contains HTML elements with the special IDs browser-check-min-width , browser-check-min-height , browser-check-actual-height , and/or browser-check-actual-width , then the contents of those elements will be dynamically updated to reflect the minimum_width , minimum_height and measured width and height of the browser. The default message is: <p>Your browser window is too small to complete this experiment. Please maximize the size of your browser window. If your browser window is already maximized, you will not be able to complete this experiment.</p><p>The minimum window width is <span id=\"browser-check-min-width\"></span> px.</p><p>Your current window width is <span id=\"browser-check-actual-width\"></span> px.</p><p>The minimum window height is <span id=\"browser-check-min-height\"></span> px.</p><p>Your current window height is <span id=\"browser-check-actual-height\"></span> px.</p> . resize_fail_button_text string \"I cannot make the window any larger\" During the interactive resize, a button with this text will be displayed below the window_resize_message for the participant to click if the window cannot meet the minimum size needed. When the button is clicked, the experiment will end and exclusion_message will be displayed. inclusion_function function () => { return true; } A function that evaluates to true if the browser meets all of the inclusion criteria for the experiment, and false otherwise. The first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. exclusion_message function () => { return <p>Your browser does not meet the requirements to participate in this experiment.</p> } A function that returns the message to display if inclusion_function evaluates to false or if the participant clicks on the resize fail button during the interactive resize. In order to allow customization of the message, the first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value width int The width of the browser window in pixels. If interactive resizing happens, this is the width after resizing. height int The height of the browser window in pixels. If interactive resizing happens, this is the height after resizing. browser string The browser used. browser_version string The version number of the browser. os string The operating system used. mobile bool Whether the browser is a mobile device. webaudio bool Whether the browser supports the WebAudio API. fullscreen bool Whether the browser supports the Fullscreen API. vsync_rate number An estimate of the refresh rate of the screen, in frames per second. webcam bool Whether there is a webcam device available. Note that the participant still must grant permission to access the device before it can be used. microphone bool Whether there is an audio input device available. Note that the participant still must grant permission to access the device before it can be used. Note that all of these values are only recorded when the corresponding key is included in the features parameter for the trial. Simulation Mode \u00b6 In simulation mode the plugin will report the actual features of the browser, with the exception of vsync_rate , which is always 60. In data-only mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the reported width and height will be equal to minimum_width and minimum_height , as if the participant resized the browser to meet the specifications. In visual mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the experiment will wait for 3 seconds before clicking the resize fail button. During this time, you can adjust the window if you would like to. As with all simulated plugins, you can override the default (actual) data with fake data using simulation_options . This allows you to test your exclusion criteria by simulating other configurations. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-browser-check@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-browser-check.js\" >< /script> Using NPM: npm install @jspsych/plugin-browser-check import browserCheck from '@jspsych/plugin-browser-check' ; Examples \u00b6 Recording all of the available features, no exclusions Code Demo var trial = { type : jsPsychBrowserCheck }; Open demo in new tab Using the inclusion function to mandate the use of Chrome or Firefox as the browser Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return [ 'chrome' , 'firefox' ]. includes ( data . browser ); }, exclusion_message : `<p>You must use Chrome or Firefox to complete this experiment.</p>` }; Open demo in new tab Setting a minimum window height & width, with the option to resize the window Code Demo var trial = { type : jsPsychBrowserCheck , minimum_width : 1000 , minimum_height : 600 }; This demo only works in a resizable window. Please open it in new tab Open demo in new tab Custom exclusion message based on measured features Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return data . browser == 'chrome' && data . mobile === false }, exclusion_message : ( data ) => { if ( data . mobile ){ return '<p>You must use a desktop/laptop computer to participate in this experiment.</p>' ; } else if ( data . browser !== 'chrome' ){ return '<p>You must use Chrome as your browser to complete this experiment.</p>' } } }; Open demo in new tab","title":"browser-check"},{"location":"plugins/browser-check/#browser-check","text":"Current version: 1.0.2. See version history . This plugin measures and records various features of the participant's browser and can end the experiment if defined inclusion criteria are not met. The plugin currently can record the following features: The width and height of the browser window in pixels. The type of browser used (e.g., Chrome, Firefox, Edge, etc.) and the version number of the browser.* Whether the participant is using a mobile device.* The operating system.* Support for the WebAudio API. Support for the Fullscreen API, e.g., through the fullscreen plugin . The display refresh rate in frames per second. Whether the device has a webcam and microphone. Note that this only reveals whether a webcam/microphone exists. The participant still needs to grant permission in order for the experiment to use these devices. Warning Features with an * are recorded by parsing the user agent string . This method is accurate most of the time, but is not guaranteed to be correct. The plugin uses the detect-browser package to perform user agent parsing. You can find a list of supported browsers and OSes in the source file . The plugin begins by measuring the set of features requested. An inclusion function is evaluated to see if the paricipant passes the inclusion criteria. If they do, then the trial ends and the experiment continues. If they do not, then the experiment ends immediately. If a minimum width and/or minimum height is desired, the plugin will optionally display a message to participants whose browser windows are too small to give them an opportunity to make the window larger if possible. See the examples below for more guidance.","title":"browser-check"},{"location":"plugins/browser-check/#parameters","text":"In addition to the 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 features array of strings [\"width\", \"height\", \"webaudio\", \"browser\", \"browser_version\", \"mobile\", \"os\", \"fullscreen\", \"vsync_rate\", \"webcam\", \"microphone\"] The list of browser features to record. The default value includes all of the available options. skip_features array of strings [] Any features listed here will be skipped, even if they appear in features . Use this when you want to run most of the defaults. vsync_frame_count int 60 The number of frames to sample when measuring the display refresh rate ( \"vsync_rate\" ). Increasing the number will potenially improve the stability of the estimate at the cost of increasing the amount of time the plugin takes during this test. On most devices, 60 frames takes about 1 second to measure. allow_window_resize bool true Whether to allow the participant to resize the browser window if the window is smaller than minimum_width and/or minimum_height . If false , then the minimum_width and minimum_height parameters are ignored and you can validate the size in the inclusion_function . minimum_height int 0 If allow_window_resize is true , then this is the minimum height of the window (in pixels) that must be met before continuing. minimum_width int 0 If allow_window_resize is true , then this is the minimum width of the window (in pixels) that must be met before continuing. window_resize_message string see description The message that will be displayed during the interactive resize when allow_window_resize is true and the window is too small. If the message contains HTML elements with the special IDs browser-check-min-width , browser-check-min-height , browser-check-actual-height , and/or browser-check-actual-width , then the contents of those elements will be dynamically updated to reflect the minimum_width , minimum_height and measured width and height of the browser. The default message is: <p>Your browser window is too small to complete this experiment. Please maximize the size of your browser window. If your browser window is already maximized, you will not be able to complete this experiment.</p><p>The minimum window width is <span id=\"browser-check-min-width\"></span> px.</p><p>Your current window width is <span id=\"browser-check-actual-width\"></span> px.</p><p>The minimum window height is <span id=\"browser-check-min-height\"></span> px.</p><p>Your current window height is <span id=\"browser-check-actual-height\"></span> px.</p> . resize_fail_button_text string \"I cannot make the window any larger\" During the interactive resize, a button with this text will be displayed below the window_resize_message for the participant to click if the window cannot meet the minimum size needed. When the button is clicked, the experiment will end and exclusion_message will be displayed. inclusion_function function () => { return true; } A function that evaluates to true if the browser meets all of the inclusion criteria for the experiment, and false otherwise. The first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below. exclusion_message function () => { return <p>Your browser does not meet the requirements to participate in this experiment.</p> } A function that returns the message to display if inclusion_function evaluates to false or if the participant clicks on the resize fail button during the interactive resize. In order to allow customization of the message, the first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features . See example below.","title":"Parameters"},{"location":"plugins/browser-check/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value width int The width of the browser window in pixels. If interactive resizing happens, this is the width after resizing. height int The height of the browser window in pixels. If interactive resizing happens, this is the height after resizing. browser string The browser used. browser_version string The version number of the browser. os string The operating system used. mobile bool Whether the browser is a mobile device. webaudio bool Whether the browser supports the WebAudio API. fullscreen bool Whether the browser supports the Fullscreen API. vsync_rate number An estimate of the refresh rate of the screen, in frames per second. webcam bool Whether there is a webcam device available. Note that the participant still must grant permission to access the device before it can be used. microphone bool Whether there is an audio input device available. Note that the participant still must grant permission to access the device before it can be used. Note that all of these values are only recorded when the corresponding key is included in the features parameter for the trial.","title":"Data Generated"},{"location":"plugins/browser-check/#simulation-mode","text":"In simulation mode the plugin will report the actual features of the browser, with the exception of vsync_rate , which is always 60. In data-only mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the reported width and height will be equal to minimum_width and minimum_height , as if the participant resized the browser to meet the specifications. In visual mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the experiment will wait for 3 seconds before clicking the resize fail button. During this time, you can adjust the window if you would like to. As with all simulated plugins, you can override the default (actual) data with fake data using simulation_options . This allows you to test your exclusion criteria by simulating other configurations.","title":"Simulation Mode"},{"location":"plugins/browser-check/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-browser-check@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-browser-check.js\" >< /script> Using NPM: npm install @jspsych/plugin-browser-check import browserCheck from '@jspsych/plugin-browser-check' ;","title":"Install"},{"location":"plugins/browser-check/#examples","text":"Recording all of the available features, no exclusions Code Demo var trial = { type : jsPsychBrowserCheck }; Open demo in new tab Using the inclusion function to mandate the use of Chrome or Firefox as the browser Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return [ 'chrome' , 'firefox' ]. includes ( data . browser ); }, exclusion_message : `<p>You must use Chrome or Firefox to complete this experiment.</p>` }; Open demo in new tab Setting a minimum window height & width, with the option to resize the window Code Demo var trial = { type : jsPsychBrowserCheck , minimum_width : 1000 , minimum_height : 600 }; This demo only works in a resizable window. Please open it in new tab Open demo in new tab Custom exclusion message based on measured features Code Demo var trial = { type : jsPsychBrowserCheck , inclusion_function : ( data ) => { return data . browser == 'chrome' && data . mobile === false }, exclusion_message : ( data ) => { if ( data . mobile ){ return '<p>You must use a desktop/laptop computer to participate in this experiment.</p>' ; } else if ( data . browser !== 'chrome' ){ return '<p>You must use Chrome as your browser to complete this experiment.</p>' } } }; Open demo in new tab","title":"Examples"},{"location":"plugins/call-function/","text":"call-function \u00b6 Current version: 1.1.2. See version history . This plugin executes a specified function. This allows the experimenter to run arbitrary code at any point during the experiment. The function cannot take any arguments. If arguments are needed, then an anonymous function should be used to wrap the function call (see examples below). Parameters \u00b6 In addition to the 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 func function undefined The function to call. async boolean false Set to true if func is an asynchoronous function. If this is true, then the first argument passed to func will be a callback that you should call when the async operation is complete. You can pass data to the callback. See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value value any The return value of the called function. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-call-function@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-call-function.js\" >< /script> Using NPM: npm install @jspsych/plugin-call-function import callFunction from '@jspsych/plugin-call-function' ; Examples \u00b6 Calling a simple function Code Demo var myfunc = function () { return 'you called?' ; } var trial = { type : jsPsychCallFunction , func : myfunc } Open demo in new tab Using an anonymous function to pass variables Code Demo var myfunc = function ( data ){ // data contains all the experiment data so far, // so this function could implement code to write // the data to a database. console . log ( data . values ()) } var trial = { type : jsPsychCallFunction , func : function (){ myfunc ( jsPsych . data . get ()) } } Open demo in new tab Async function call: wait for data to be saved to a server Code There's no demo for this code, because it requires a server to communicate with. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // can perform async operations here like // creating an XMLHttpRequest to communicate // with a server var xhttp = new XMLHttpRequest (); xhttp . onreadystatechange = function () { if ( this . readyState == 4 && this . status == 200 ) { var response_data = xhttp . responseText ; // line below is what causes jsPsych to // continue to next trial. response_data // will be stored in jsPsych data object. done ( response_data ); } }; xhttp . open ( \"GET\" , \"path_to_server_script.php\" , true ); xhttp . send (); } } Async function call: simulate waiting for an event to finish Code Demo var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // generate a delay between 1500 and 3000 milliseconds to simulate // waiting for an event to finish after an unknown duration, // then move on with the experiment var rand_delay = ( Math . floor ( Math . random () * ( 3000 - 1500 + 1 ) + 1500 )); jsPsych . pluginAPI . setTimeout ( function () { // end the trial and save the delay duration to the data done ( rand_delay . toString () + \"ms\" ); }, rand_delay ) } }; Open demo in new tab","title":"call-function"},{"location":"plugins/call-function/#call-function","text":"Current version: 1.1.2. See version history . This plugin executes a specified function. This allows the experimenter to run arbitrary code at any point during the experiment. The function cannot take any arguments. If arguments are needed, then an anonymous function should be used to wrap the function call (see examples below).","title":"call-function"},{"location":"plugins/call-function/#parameters","text":"In addition to the 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 func function undefined The function to call. async boolean false Set to true if func is an asynchoronous function. If this is true, then the first argument passed to func will be a callback that you should call when the async operation is complete. You can pass data to the callback. See example below.","title":"Parameters"},{"location":"plugins/call-function/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value value any The return value of the called function.","title":"Data Generated"},{"location":"plugins/call-function/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-call-function@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-call-function.js\" >< /script> Using NPM: npm install @jspsych/plugin-call-function import callFunction from '@jspsych/plugin-call-function' ;","title":"Install"},{"location":"plugins/call-function/#examples","text":"Calling a simple function Code Demo var myfunc = function () { return 'you called?' ; } var trial = { type : jsPsychCallFunction , func : myfunc } Open demo in new tab Using an anonymous function to pass variables Code Demo var myfunc = function ( data ){ // data contains all the experiment data so far, // so this function could implement code to write // the data to a database. console . log ( data . values ()) } var trial = { type : jsPsychCallFunction , func : function (){ myfunc ( jsPsych . data . get ()) } } Open demo in new tab Async function call: wait for data to be saved to a server Code There's no demo for this code, because it requires a server to communicate with. var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // can perform async operations here like // creating an XMLHttpRequest to communicate // with a server var xhttp = new XMLHttpRequest (); xhttp . onreadystatechange = function () { if ( this . readyState == 4 && this . status == 200 ) { var response_data = xhttp . responseText ; // line below is what causes jsPsych to // continue to next trial. response_data // will be stored in jsPsych data object. done ( response_data ); } }; xhttp . open ( \"GET\" , \"path_to_server_script.php\" , true ); xhttp . send (); } } Async function call: simulate waiting for an event to finish Code Demo var trial = { type : jsPsychCallFunction , async : true , func : function ( done ){ // generate a delay between 1500 and 3000 milliseconds to simulate // waiting for an event to finish after an unknown duration, // then move on with the experiment var rand_delay = ( Math . floor ( Math . random () * ( 3000 - 1500 + 1 ) + 1500 )); jsPsych . pluginAPI . setTimeout ( function () { // end the trial and save the delay duration to the data done ( rand_delay . toString () + \"ms\" ); }, rand_delay ) } }; Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-button-response/","text":"canvas-button-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element , and record a button click response and response time. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. One or more button choices will be displayed under the canvas, and the button style can be customized using HTML formatting. Parameters \u00b6 In addition to the 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 strings [] 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 participant is supposed to take (e.g., what question to answer). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. 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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-button-response import canvasButtonResponse from '@jspsych/plugin-canvas-button-response' ; Examples \u00b6 Drawing circles based on parameters Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_1 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 100 , 'blue' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { color : 'blue' , radius : 100 } }; var circle_2 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 150 , 'green' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Larger' , 'Smaller' ], stimulus_duration : 1000 , prompt : '<p>Is this circle larger or smaller than the last one?</p>' + '<p>Stimulus will be hidden after 1 second.</p>' , data : { color : 'green' , radius : 150 } }; Open demo in new tab Using an anonymous stimulus function Code Demo var lines = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { var ctx = c . getContext ( \"2d\" ); // first line ctx . beginPath (); ctx . moveTo ( 200 , 10 ); ctx . lineTo ( 200 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumBlue' ; ctx . stroke (); // second line ctx . beginPath (); ctx . moveTo ( 20 , 100 ); ctx . lineTo ( 100 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumPurple' ; ctx . stroke (); }, canvas_size : [ 300 , 300 ], choices : [ 'Blue line' , 'Purple line' ], prompt : '<p>Which line is longer?</p>' , data : { line1_color : 'blue' , line1_length : 290 , line2_color : \"purple\" , line2_length : 170 } }; Open demo in new tab Using the canvas stimulus function with timeline variables, and recording the correctness of responses Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_procedure = { timeline : [ { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , jsPsych . timelineVariable ( 'radius' ), jsPsych . timelineVariable ( 'color' )); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { radius : jsPsych . timelineVariable ( 'radius' ), color : jsPsych . timelineVariable ( 'color' ), correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = data . response == data . correct_response ; } } ], timeline_variables : [ { radius : 80 , color : 'red' , correct_response : 0 }, { radius : 100 , color : 'green' , correct_response : 1 }, { radius : 50 , color : 'blue' , correct_response : 2 } ], randomize_order : true }; Open demo in new tab","title":"canvas-button-response"},{"location":"plugins/canvas-button-response/#canvas-button-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element , and record a button click response and response time. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. One or more button choices will be displayed under the canvas, and the button style can be customized using HTML formatting.","title":"canvas-button-response"},{"location":"plugins/canvas-button-response/#parameters","text":"In addition to the 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 strings [] 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 participant is supposed to take (e.g., what question to answer). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. 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.","title":"Data Generated"},{"location":"plugins/canvas-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-button-response import canvasButtonResponse from '@jspsych/plugin-canvas-button-response' ;","title":"Install"},{"location":"plugins/canvas-button-response/#examples","text":"Drawing circles based on parameters Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_1 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 100 , 'blue' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { color : 'blue' , radius : 100 } }; var circle_2 = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , 150 , 'green' ); }, canvas_size : [ 300 , 300 ], choices : [ 'Larger' , 'Smaller' ], stimulus_duration : 1000 , prompt : '<p>Is this circle larger or smaller than the last one?</p>' + '<p>Stimulus will be hidden after 1 second.</p>' , data : { color : 'green' , radius : 150 } }; Open demo in new tab Using an anonymous stimulus function Code Demo var lines = { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { var ctx = c . getContext ( \"2d\" ); // first line ctx . beginPath (); ctx . moveTo ( 200 , 10 ); ctx . lineTo ( 200 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumBlue' ; ctx . stroke (); // second line ctx . beginPath (); ctx . moveTo ( 20 , 100 ); ctx . lineTo ( 100 , 250 ); ctx . lineWidth = 10 ; ctx . strokeStyle = 'MediumPurple' ; ctx . stroke (); }, canvas_size : [ 300 , 300 ], choices : [ 'Blue line' , 'Purple line' ], prompt : '<p>Which line is longer?</p>' , data : { line1_color : 'blue' , line1_length : 290 , line2_color : \"purple\" , line2_length : 170 } }; Open demo in new tab Using the canvas stimulus function with timeline variables, and recording the correctness of responses Code Demo function filledCirc ( canvas , radius , color ) { var ctx = canvas . getContext ( \"2d\" ); ctx . beginPath (); ctx . arc ( 150 , 150 , radius , 0 , 2 * Math . PI ); ctx . fillStyle = color ; ctx . fill (); } var circle_procedure = { timeline : [ { type : jsPsychCanvasButtonResponse , stimulus : function ( c ) { filledCirc ( c , jsPsych . timelineVariable ( 'radius' ), jsPsych . timelineVariable ( 'color' )); }, canvas_size : [ 300 , 300 ], choices : [ 'Red' , 'Green' , 'Blue' ], prompt : '<p>What color is the circle?</p>' , data : { radius : jsPsych . timelineVariable ( 'radius' ), color : jsPsych . timelineVariable ( 'color' ), correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = data . response == data . correct_response ; } } ], timeline_variables : [ { radius : 80 , color : 'red' , correct_response : 0 }, { radius : 100 , color : 'green' , correct_response : 1 }, { radius : 50 , color : 'blue' , correct_response : 2 } ], randomize_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-keyboard-response/","text":"canvas-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and record a keyboard response. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-keyboard-response import canvasKeyboardResponse from '@jspsych/plugin-canvas-keyboard-response' ; Examples \u00b6 Draw rectangle and wait for response Code Demo function drawRect ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . rect ( 30 , 30 , 200 , 50 ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawRect , choices : [ 'e' , 'i' ], prompt : '<p>Is this a circle or a rectangle? Press \"e\" for circle and \"i\" for rectangle.</p>' , data : { shape : 'rectangle' } } Open demo in new tab Draw circle, no response allowed Code Demo function drawCirc ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . arc ( 100 , 75 , 50 , 0 , 2 * Math . PI ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawCirc , prompt : '<p>No key response is allowed.</p><p>The stimulus disappears after 3 seconds.</p>' , choices : \"NO_KEYS\" , trial_duration : 3000 , data : { shape : 'circle' , radius : 50 } } Open demo in new tab","title":"canvas-keyboard-response"},{"location":"plugins/canvas-keyboard-response/#canvas-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and record a keyboard response. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time.","title":"canvas-keyboard-response"},{"location":"plugins/canvas-keyboard-response/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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.","title":"Data Generated"},{"location":"plugins/canvas-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-keyboard-response import canvasKeyboardResponse from '@jspsych/plugin-canvas-keyboard-response' ;","title":"Install"},{"location":"plugins/canvas-keyboard-response/#examples","text":"Draw rectangle and wait for response Code Demo function drawRect ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . rect ( 30 , 30 , 200 , 50 ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawRect , choices : [ 'e' , 'i' ], prompt : '<p>Is this a circle or a rectangle? Press \"e\" for circle and \"i\" for rectangle.</p>' , data : { shape : 'rectangle' } } Open demo in new tab Draw circle, no response allowed Code Demo function drawCirc ( c ){ var ctx = c . getContext ( '2d' ); ctx . beginPath (); ctx . arc ( 100 , 75 , 50 , 0 , 2 * Math . PI ); ctx . stroke (); } var trial = { type : jsPsychCanvasKeyboardResponse , canvas_size : [ 300 , 300 ], stimulus : drawCirc , prompt : '<p>No key response is allowed.</p><p>The stimulus disappears after 3 seconds.</p>' , choices : \"NO_KEYS\" , trial_duration : 3000 , data : { shape : 'circle' , radius : 50 } } Open demo in new tab","title":"Examples"},{"location":"plugins/canvas-slider-response/","text":"canvas-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and collect a response within a range of values, which is made by dragging a slider. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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. 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 participant must click 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 participant is supposed to take (e.g., what question to answer). 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-slider-response import canvasSliderResponse from '@jspsych/plugin-canvas-slider-response' ; Examples \u00b6 Draw two squares Code Demo var colors = [ '#FF3333' , '#FF6A33' ]; function twoSquares ( c ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : twoSquares , labels : [ '0' , '10' ], canvas_size : [ 150 , 500 ], prompt : '<p>How different would you say the colors of these two squares are on a scale from 0 (the same) to 10 (completely different)</p>' , data : { color1 : colors [ 0 ], color2 : colors [ 1 ]} } Open demo in new tab Draw two squares with additional parameters Code Demo var colors ; function twoSquares ( c , colors ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : function ( c ) { colors = [ 'darkred' , 'cyan' ]; twoSquares ( c , colors ); }, labels : [ 'Exactly<br>the same' , 'Totally<br>different' ], canvas_size : [ 200 , 500 ], prompt : '<p>How different would you say the colors of these two squares are?</p>' , on_finish : function ( data ) { data . color1 = colors [ 0 ]; data . color2 = colors [ 1 ]; } }; Open demo in new tab","title":"canvas-slider-response"},{"location":"plugins/canvas-slider-response/#canvas-slider-response","text":"Current version: 1.1.2. See version history . This plugin can be used to draw a stimulus on a HTML canvas element and collect a response within a range of values, which is made by dragging a slider. The canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). 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 participant has failed to respond within a fixed length of time.","title":"canvas-slider-response"},{"location":"plugins/canvas-slider-response/#parameters","text":"In addition to the 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. 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 participant must click 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 participant is supposed to take (e.g., what question to answer). 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/canvas-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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.","title":"Data Generated"},{"location":"plugins/canvas-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-canvas-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-canvas-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-canvas-slider-response import canvasSliderResponse from '@jspsych/plugin-canvas-slider-response' ;","title":"Install"},{"location":"plugins/canvas-slider-response/#examples","text":"Draw two squares Code Demo var colors = [ '#FF3333' , '#FF6A33' ]; function twoSquares ( c ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : twoSquares , labels : [ '0' , '10' ], canvas_size : [ 150 , 500 ], prompt : '<p>How different would you say the colors of these two squares are on a scale from 0 (the same) to 10 (completely different)</p>' , data : { color1 : colors [ 0 ], color2 : colors [ 1 ]} } Open demo in new tab Draw two squares with additional parameters Code Demo var colors ; function twoSquares ( c , colors ) { var ctx = c . getContext ( '2d' ); ctx . fillStyle = colors [ 0 ]; ctx . fillRect ( 200 , 70 , 40 , 40 ); ctx . fillStyle = colors [ 1 ]; ctx . fillRect ( 260 , 70 , 40 , 40 ); } var trial = { type : jsPsychCanvasSliderResponse , stimulus : function ( c ) { colors = [ 'darkred' , 'cyan' ]; twoSquares ( c , colors ); }, labels : [ 'Exactly<br>the same' , 'Totally<br>different' ], canvas_size : [ 200 , 500 ], prompt : '<p>How different would you say the colors of these two squares are?</p>' , on_finish : function ( data ) { data . color1 = colors [ 0 ]; data . color2 = colors [ 1 ]; } }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-animation/","text":"categorize-animation \u00b6 Current version: 1.1.2. See version history . The categorize animation plugin shows a sequence of images at a specified frame rate. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 or the end of the animation depending on the allow_response_before_complete parameter. The intention is that it can be used to provide a reminder about the action the participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array Array of stimuli displayed in the trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-animation import categorizeAnimation from '@jspsych/plugin-categorize-animation' ; Examples \u00b6 Basic example Code Demo var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ], prompt : `Press the P or Q key.` , choices : [ 'p' , 'q' ], key_answer : 'q' , }; Open demo in new tab Giving feedback with %ANS% string Code Demo var images = [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ]; var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : images , choices : [ 'p' , 'q' ], prompt : `Press the P or Q key.` , 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%.' }; Open demo in new tab","title":"categorize-animation"},{"location":"plugins/categorize-animation/#categorize-animation","text":"Current version: 1.1.2. See version history . The categorize animation plugin shows a sequence of images at a specified frame rate. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-animation"},{"location":"plugins/categorize-animation/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 or the end of the animation depending on the allow_response_before_complete parameter. The intention is that it can be used to provide a reminder about the action the participant 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.","title":"Parameters"},{"location":"plugins/categorize-animation/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array Array of stimuli displayed in the trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-animation/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-animation@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-animation.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-animation import categorizeAnimation from '@jspsych/plugin-categorize-animation' ;","title":"Install"},{"location":"plugins/categorize-animation/#examples","text":"Basic example Code Demo var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ], prompt : `Press the P or Q key.` , choices : [ 'p' , 'q' ], key_answer : 'q' , }; Open demo in new tab Giving feedback with %ANS% string Code Demo var images = [ 'img/happy_face_1.jpg' , 'img/happy_face_2.jpg' , 'img/happy_face_3.jpg' , 'img/happy_face_4.jpg' ]; var animation_trial = { type : jsPsychCategorizeAnimation , stimuli : images , choices : [ 'p' , 'q' ], prompt : `Press the P or Q key.` , 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%.' }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-html/","text":"categorize-html \u00b6 Current version: 1.1.2. See version history . The categorize html plugin shows an HTML object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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 \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-html import categorizeHtml from '@jspsych/plugin-categorize-html' ; Examples \u00b6 Categorizing HTML content Code Demo var categorization_trial = { type : jsPsychCategorizeHtml , stimulus : '<p>B</p>' , key_answer : 'p' , text_answer : 'letter' , 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>\" }; Open demo in new tab","title":"categorize-html"},{"location":"plugins/categorize-html/#categorize-html","text":"Current version: 1.1.2. See version history . The categorize html plugin shows an HTML object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-html"},{"location":"plugins/categorize-html/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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.","title":"Parameters"},{"location":"plugins/categorize-html/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-html import categorizeHtml from '@jspsych/plugin-categorize-html' ;","title":"Install"},{"location":"plugins/categorize-html/#examples","text":"Categorizing HTML content Code Demo var categorization_trial = { type : jsPsychCategorizeHtml , stimulus : '<p>B</p>' , key_answer : 'p' , text_answer : 'letter' , 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>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/categorize-image/","text":"categorize-image \u00b6 Current version: 1.1.2. See version history . The categorize image plugin shows an image object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given. Parameters \u00b6 In addition to the 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 string undefined The key character indicating the correct response. choices array of strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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 \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-image import categorizeImage from '@jspsych/plugin-categorize-image' ; Examples \u00b6 Categorizing an image Code Demo var categorization_trial = { type : jsPsychCategorizeImage , stimulus : 'img/blue.png' , key_answer : 'b' , text_answer : 'Blue' , choices : [ 'r' , 'g' , 'b' ], correct_text : \"<p class='prompt'>Correct! The color is %ANS%.</p>\" , incorrect_text : \"<p class='prompt'>Incorrect. The color is %ANS%.</p>\" , prompt : \"<p>Is the color of this circle (R)ed, (G)reen, or (B)lue?</p>\" }; Open demo in new tab","title":"categorize-image"},{"location":"plugins/categorize-image/#categorize-image","text":"Current version: 1.1.2. See version history . The categorize image plugin shows an image object on the screen. The participant responds by pressing a key. Feedback indicating the correctness of the response is given.","title":"categorize-image"},{"location":"plugins/categorize-image/#parameters","text":"In addition to the 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 string undefined The key character indicating the correct response. choices array of strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant is supposed to take (e.g., which key to press). force_correct_button_press boolean false If set to true, then the participant 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.","title":"Parameters"},{"location":"plugins/categorize-image/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean true if the participant got the correct answer, false otherwise.","title":"Data Generated"},{"location":"plugins/categorize-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-categorize-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-categorize-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-categorize-image import categorizeImage from '@jspsych/plugin-categorize-image' ;","title":"Install"},{"location":"plugins/categorize-image/#examples","text":"Categorizing an image Code Demo var categorization_trial = { type : jsPsychCategorizeImage , stimulus : 'img/blue.png' , key_answer : 'b' , text_answer : 'Blue' , choices : [ 'r' , 'g' , 'b' ], correct_text : \"<p class='prompt'>Correct! The color is %ANS%.</p>\" , incorrect_text : \"<p class='prompt'>Incorrect. The color is %ANS%.</p>\" , prompt : \"<p>Is the color of this circle (R)ed, (G)reen, or (B)lue?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/cloze/","text":"cloze \u00b6 Current version: 1.2.0. See version history . This plugin displays a text with certain words omitted. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding. Parameters \u00b6 In addition to the 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. allow_blanks boolean true Boolean value indicating if the answers given by participants should be checked for completion after the button was clicked. If true , answers are not checked for completion and blank answers are allowed. The trial will then automatically finish upon the clicking the button. If false , answers are checked for completion, and in case there are some fields with missing answers, the mistake_fn is called. In this case, the trial does not automatically finish. mistake_fn function function(){} Function called if check_answers is set to true and there is a difference between the participant's answers and the correct solution provided in the text, or if allow_blanks is set to false and there is at least one field with a blank answer. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response array of strings Answers the partcipant gave Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-cloze@1.2.0\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-cloze.js\" >< /script> Using NPM: npm install @jspsych/plugin-cloze import cloze from '@jspsych/plugin-cloze' ; Examples \u00b6 Simple cloze using default settings (no check against correct solution, no custom button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'The %% is the largest terrestrial mammal. It lives in both %% and %%.' }; Open demo in new tab Cloze example using default settings with completion checking and custom error handling Code Demo var cloze_trial = { type : jsPsychCloze , text : 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.' , allow_blanks : false , mistake_fn : function () { alert ( 'Please fill in all blanks.' ); } }; Open demo in new tab More elaborate example (with check against correct solution, custom error handling and modified button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'A rectangle has % 4 % corners and a triangle has % 3 %.' , check_answers : true , button_text : 'Next' , mistake_fn : function (){ alert ( \"Wrong answer. Please check again.\" ) } }; Open demo in new tab","title":"cloze"},{"location":"plugins/cloze/#cloze","text":"Current version: 1.2.0. See version history . This plugin displays a text with certain words omitted. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding.","title":"cloze"},{"location":"plugins/cloze/#parameters","text":"In addition to the 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. allow_blanks boolean true Boolean value indicating if the answers given by participants should be checked for completion after the button was clicked. If true , answers are not checked for completion and blank answers are allowed. The trial will then automatically finish upon the clicking the button. If false , answers are checked for completion, and in case there are some fields with missing answers, the mistake_fn is called. In this case, the trial does not automatically finish. mistake_fn function function(){} Function called if check_answers is set to true and there is a difference between the participant's answers and the correct solution provided in the text, or if allow_blanks is set to false and there is at least one field with a blank answer.","title":"Parameters"},{"location":"plugins/cloze/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response array of strings Answers the partcipant gave","title":"Data Generated"},{"location":"plugins/cloze/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-cloze@1.2.0\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-cloze.js\" >< /script> Using NPM: npm install @jspsych/plugin-cloze import cloze from '@jspsych/plugin-cloze' ;","title":"Install"},{"location":"plugins/cloze/#examples","text":"Simple cloze using default settings (no check against correct solution, no custom button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'The %% is the largest terrestrial mammal. It lives in both %% and %%.' }; Open demo in new tab Cloze example using default settings with completion checking and custom error handling Code Demo var cloze_trial = { type : jsPsychCloze , text : 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.' , allow_blanks : false , mistake_fn : function () { alert ( 'Please fill in all blanks.' ); } }; Open demo in new tab More elaborate example (with check against correct solution, custom error handling and modified button text) Code Demo var cloze_trial = { type : jsPsychCloze , text : 'A rectangle has % 4 % corners and a triangle has % 3 %.' , check_answers : true , button_text : 'Next' , mistake_fn : function (){ alert ( \"Wrong answer. Please check again.\" ) } }; Open demo in new tab","title":"Examples"},{"location":"plugins/external-html/","text":"external-html \u00b6 Current version: 1.1.2. See version history . 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 \u00b6 In addition to the 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 string null The key character the participant can use to advance to the next trial. If left as null, then the participant 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 participant attempts to advance the trial. The trial will only advance if the function return true . This can be used to verify that the participant 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 \u00b6 In addition to the default data collected by all 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 participant to finish the trial. Simulation Mode \u00b6 In visual simulation mode, the plugin cannot interact with any form elements on the screen other than the cont_btn specified in the trial parameters. If your check_fn requires other user interaction, for example, clicking a checkbox, then you'll need to disable simulation for the trial and complete the interaction manually. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-external-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-external-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-external-html import externalHtml from '@jspsych/plugin-external-html' ; Examples \u00b6 Loading a consent form \u00b6 This content would be in a file called 'external_page.html' \u00b6 < div id = \"consent\" > < p > 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\". </ p > < p > < input type = \"checkbox\" id = \"consent_checkbox\" /> I agree to take part in this study. </ p > < button type = \"button\" id = \"start\" > Start Experiment </ button > </ div > jsPsych code to load above page. Code Demo // sample function that might be used to check if a participant has given // consent to participate. var check_consent = function ( elem ) { if ( document . getElementById ( 'consent_checkbox' ). checked ) { return true ; } else { alert ( \"If you wish to participate, you must check the box next to the statement 'I agree to participate in this study.'\" ); return false ; } return false ; }; // declare the block. var trial = { type : jsPsychExternalHtml , url : \"external_page.html\" , cont_btn : \"start\" , check_fn : check_consent }; Open demo in new tab","title":"external-html"},{"location":"plugins/external-html/#external-html","text":"Current version: 1.1.2. See version history . 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.","title":"external-html"},{"location":"plugins/external-html/#parameters","text":"In addition to the 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 string null The key character the participant can use to advance to the next trial. If left as null, then the participant 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 participant attempts to advance the trial. The trial will only advance if the function return true . This can be used to verify that the participant 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.","title":"Parameters"},{"location":"plugins/external-html/#data-generated","text":"In addition to the default data collected by all 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 participant to finish the trial.","title":"Data Generated"},{"location":"plugins/external-html/#simulation-mode","text":"In visual simulation mode, the plugin cannot interact with any form elements on the screen other than the cont_btn specified in the trial parameters. If your check_fn requires other user interaction, for example, clicking a checkbox, then you'll need to disable simulation for the trial and complete the interaction manually.","title":"Simulation Mode"},{"location":"plugins/external-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-external-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-external-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-external-html import externalHtml from '@jspsych/plugin-external-html' ;","title":"Install"},{"location":"plugins/external-html/#examples","text":"","title":"Examples"},{"location":"plugins/external-html/#loading-a-consent-form","text":"","title":"Loading a consent form"},{"location":"plugins/external-html/#this-content-would-be-in-a-file-called-external_pagehtml","text":"< div id = \"consent\" > < p > 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\". </ p > < p > < input type = \"checkbox\" id = \"consent_checkbox\" /> I agree to take part in this study. </ p > < button type = \"button\" id = \"start\" > Start Experiment </ button > </ div > jsPsych code to load above page. Code Demo // sample function that might be used to check if a participant has given // consent to participate. var check_consent = function ( elem ) { if ( document . getElementById ( 'consent_checkbox' ). checked ) { return true ; } else { alert ( \"If you wish to participate, you must check the box next to the statement 'I agree to participate in this study.'\" ); return false ; } return false ; }; // declare the block. var trial = { type : jsPsychExternalHtml , url : \"external_page.html\" , cont_btn : \"start\" , check_fn : check_consent }; Open demo in new tab","title":"This content would be in a file called 'external_page.html'"},{"location":"plugins/free-sort/","text":"free-sort \u00b6 Current version: 1.0.2. See version history . The free-sort plugin displays one or more images on the screen that the participant can interact with by clicking and dragging with a mouse, or touching and dragging with a touchscreen device. When the trial starts, the images can be positioned outside or inside the sort area. All images must be moved into the sorting area before the participant can click a button to end the trial. All of the moves that the participant performs are recorded, as well as the final positions of all images. This plugin could be useful when asking participants to position images based on similarity to one another, or to recall image spatial locations. Parameters \u00b6 In addition to the 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 this array is an image path. stim_height numeric 100 The height of the images in pixels. stim_width numeric 100 The width of the images in pixels. scale_factor numeric 1.5 How much larger to make the stimulus while moving (1 = no scaling). sort_area_height numeric 800 The height of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_width numeric 800 The width of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_shape string \"ellipse\" The shape of the sorting area, can be \"ellipse\" or \"square\". prompt string null This string can contain HTML markup. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). prompt_location string \"above\" Indicates whether to show the prompt \"above\" or \"below\" the sorting area. button_label string 'Continue' The text that appears on the button to continue to the next trial. change_border_background_color boolean true If true , the sort area border color will change while items are being moved in and out of the sort area, and the background color will change once all items have been moved into the sort area. If false , the border will remain black and the background will remain white throughout the trial. border_color_in string '#a1d99b' If change_border_background_color is true , the sort area border will change to this color when an item is being moved into the sort area, and the background will change to this color when all of the items have been moved into the sort area. border_color_out string '#fc9272' If change_border_background_color is true , this will be the color of the sort area border when there are one or more items that still need to be moved into the sort area. border_width numeric null The width in pixels of the border around the sort area. If null , the border width will be 3% of the sort_area_height . counter_text_unfinished string You still need to place %n% item%s% inside the sort area. Text to display when there are one or more items that still need to be placed in the sort area. If \"%n%\" is included in the string, it will be replaced with the number of items that still need to be moved inside. If \"%s%\" is included in the string, a \"s\" will be included when the number of items remaining is greater than one. counter_text_finished string All items placed. Feel free to reposition items if necessary. Text that will take the place of the counter_text_unfinished text when all items have been moved inside the sort area. stim_starts_inside boolean false If false , the images will be positioned to the left and right of the sort area when the trial loads. If true , the images will be positioned at random locations inside the sort area when the trial loads. column_spread_factor numeric 1 When the images appear outside the sort area, this determines the x-axis spread of the image columns. Default value is 1. Values less than 1 will compress the image columns along the x-axis, and values greater than 1 will spread them farther apart. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value init_locations array An array containing objects representing the initial locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. moves array An array containing objects representing all of the moves the participant made when sorting. Each object represents a move. Each element in the array has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location after the move. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. final_locations array An array containing objects representing the final locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to finish all sorting. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-free-sort@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-free-sort.js\" >< /script> Using NPM: npm install @jspsych/plugin-free-sort import freeSort from '@jspsych/plugin-free-sort' ; Examples \u00b6 Basic example Code Demo var sort_trial = { type : jsPsychFreeSort , stimuli : sorting_stimuli , stim_width : 80 , stim_height : 60 , sort_area_width : 500 , sort_area_height : 500 , prompt : \"<p>Click and drag the images below to sort them so that similar items are close together.</p>\" }; Open demo in new tab","title":"free-sort"},{"location":"plugins/free-sort/#free-sort","text":"Current version: 1.0.2. See version history . The free-sort plugin displays one or more images on the screen that the participant can interact with by clicking and dragging with a mouse, or touching and dragging with a touchscreen device. When the trial starts, the images can be positioned outside or inside the sort area. All images must be moved into the sorting area before the participant can click a button to end the trial. All of the moves that the participant performs are recorded, as well as the final positions of all images. This plugin could be useful when asking participants to position images based on similarity to one another, or to recall image spatial locations.","title":"free-sort"},{"location":"plugins/free-sort/#parameters","text":"In addition to the 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 this array is an image path. stim_height numeric 100 The height of the images in pixels. stim_width numeric 100 The width of the images in pixels. scale_factor numeric 1.5 How much larger to make the stimulus while moving (1 = no scaling). sort_area_height numeric 800 The height of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_width numeric 800 The width of the container that participants can move the stimuli in. Stimuli will be constrained to this area. sort_area_shape string \"ellipse\" The shape of the sorting area, can be \"ellipse\" or \"square\". prompt string null This string can contain HTML markup. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). prompt_location string \"above\" Indicates whether to show the prompt \"above\" or \"below\" the sorting area. button_label string 'Continue' The text that appears on the button to continue to the next trial. change_border_background_color boolean true If true , the sort area border color will change while items are being moved in and out of the sort area, and the background color will change once all items have been moved into the sort area. If false , the border will remain black and the background will remain white throughout the trial. border_color_in string '#a1d99b' If change_border_background_color is true , the sort area border will change to this color when an item is being moved into the sort area, and the background will change to this color when all of the items have been moved into the sort area. border_color_out string '#fc9272' If change_border_background_color is true , this will be the color of the sort area border when there are one or more items that still need to be moved into the sort area. border_width numeric null The width in pixels of the border around the sort area. If null , the border width will be 3% of the sort_area_height . counter_text_unfinished string You still need to place %n% item%s% inside the sort area. Text to display when there are one or more items that still need to be placed in the sort area. If \"%n%\" is included in the string, it will be replaced with the number of items that still need to be moved inside. If \"%s%\" is included in the string, a \"s\" will be included when the number of items remaining is greater than one. counter_text_finished string All items placed. Feel free to reposition items if necessary. Text that will take the place of the counter_text_unfinished text when all items have been moved inside the sort area. stim_starts_inside boolean false If false , the images will be positioned to the left and right of the sort area when the trial loads. If true , the images will be positioned at random locations inside the sort area when the trial loads. column_spread_factor numeric 1 When the images appear outside the sort area, this determines the x-axis spread of the image columns. Default value is 1. Values less than 1 will compress the image columns along the x-axis, and values greater than 1 will spread them farther apart.","title":"Parameters"},{"location":"plugins/free-sort/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value init_locations array An array containing objects representing the initial locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. moves array An array containing objects representing all of the moves the participant made when sorting. Each object represents a move. Each element in the array has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location after the move. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. final_locations array An array containing objects representing the final locations of all the stimuli in the sorting area. Each element in the array represents a stimulus, and has a \"src\", \"x\", and \"y\" value. \"src\" is the image path, and \"x\" and \"y\" are the object location. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to finish all sorting.","title":"Data Generated"},{"location":"plugins/free-sort/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/free-sort/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-free-sort@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-free-sort.js\" >< /script> Using NPM: npm install @jspsych/plugin-free-sort import freeSort from '@jspsych/plugin-free-sort' ;","title":"Install"},{"location":"plugins/free-sort/#examples","text":"Basic example Code Demo var sort_trial = { type : jsPsychFreeSort , stimuli : sorting_stimuli , stim_width : 80 , stim_height : 60 , sort_area_width : 500 , sort_area_height : 500 , prompt : \"<p>Click and drag the images below to sort them so that similar items are close together.</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/fullscreen/","text":"fullscreen \u00b6 Current version: 1.1.2. See version history . The fullscreen plugin allows the experiment to enter or exit fullscreen mode. For security reasons, all browsers require that entry into fullscreen mode is triggered by a user action. To enter fullscreen mode, this plugin has the user click a button. Exiting fullscreen mode can be done without user input. Warning Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari. Parameters \u00b6 In addition to the 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 fullscreen_mode boolean true A value of true causes the experiment to enter fullscreen mode. A value of false causes the browser to exit fullscreen mode. message string <p>The experiment will switch to full screen mode when you press the button below</p> The HTML content to display above the button to enter fullscreen mode. button_label string 'Continue' The text that appears on the button to enter fullscreen mode. delay_after numeric 1000 The length of time to delay after entering fullscreen mode before ending the trial. This can be useful because entering fullscreen is jarring and most browsers display some kind of message that the browser has entered fullscreen mode. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean true if the browser supports fullscreen mode (i.e., is not Safari) Simulation Mode \u00b6 Web browsers do not allow fullscreen mode to be triggered by a script to avoid malicious usage of fullscreen behavior when the user is not wanting it. In visual simulation mode, the trial will run normally and the button will get a simulated click, but the display will not change. If you want the display to actually enter fullscreen mode during the simulation, you should disable simulation for the fullscreen trial and manually click the button. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-fullscreen@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-fullscreen.js\" >< /script> Using NPM: npm install @jspsych/plugin-fullscreen import fullscreen from '@jspsych/plugin-fullscreen' ; Examples \u00b6 Entering and exiting fullscreen Code Demo var enter_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : true } var trial_in_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will be in fullscreen mode.' , choices : [ 'Continue' ] } var exit_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : false , delay_after : 0 } var trial_after_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will NOT be in fullscreen mode.' , choices : [ 'Continue' ] } Open demo in new tab","title":"fullscreen"},{"location":"plugins/fullscreen/#fullscreen","text":"Current version: 1.1.2. See version history . The fullscreen plugin allows the experiment to enter or exit fullscreen mode. For security reasons, all browsers require that entry into fullscreen mode is triggered by a user action. To enter fullscreen mode, this plugin has the user click a button. Exiting fullscreen mode can be done without user input. Warning Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.","title":"fullscreen"},{"location":"plugins/fullscreen/#parameters","text":"In addition to the 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 fullscreen_mode boolean true A value of true causes the experiment to enter fullscreen mode. A value of false causes the browser to exit fullscreen mode. message string <p>The experiment will switch to full screen mode when you press the button below</p> The HTML content to display above the button to enter fullscreen mode. button_label string 'Continue' The text that appears on the button to enter fullscreen mode. delay_after numeric 1000 The length of time to delay after entering fullscreen mode before ending the trial. This can be useful because entering fullscreen is jarring and most browsers display some kind of message that the browser has entered fullscreen mode.","title":"Parameters"},{"location":"plugins/fullscreen/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean true if the browser supports fullscreen mode (i.e., is not Safari)","title":"Data Generated"},{"location":"plugins/fullscreen/#simulation-mode","text":"Web browsers do not allow fullscreen mode to be triggered by a script to avoid malicious usage of fullscreen behavior when the user is not wanting it. In visual simulation mode, the trial will run normally and the button will get a simulated click, but the display will not change. If you want the display to actually enter fullscreen mode during the simulation, you should disable simulation for the fullscreen trial and manually click the button.","title":"Simulation Mode"},{"location":"plugins/fullscreen/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-fullscreen@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-fullscreen.js\" >< /script> Using NPM: npm install @jspsych/plugin-fullscreen import fullscreen from '@jspsych/plugin-fullscreen' ;","title":"Install"},{"location":"plugins/fullscreen/#examples","text":"Entering and exiting fullscreen Code Demo var enter_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : true } var trial_in_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will be in fullscreen mode.' , choices : [ 'Continue' ] } var exit_fullscreen = { type : jsPsychFullscreen , fullscreen_mode : false , delay_after : 0 } var trial_after_fullscreen = { type : jsPsychHtmlButtonResponse , stimulus : 'This trial will NOT be in fullscreen mode.' , choices : [ 'Continue' ] } Open demo in new tab","title":"Examples"},{"location":"plugins/html-audio-response/","text":"html-audio-response \u00b6 Current version: 1.0.2. See version history . This plugin displays HTML content and records audio from the participant via a microphone. In order to get access to the microphone, you need to use the initialize-microphone plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records audio data in base 64 format . This is a text-based representation of the audio which can be coverted to various audio formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of audio recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of audio, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded audio files as Object URLs via save_audio_url: true . This will generate a URL that is storing a copy of the recorded audio, which can be used for subsequent playback. See below for an example where the recorded audio is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of audio snippets, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded audio and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_audio_url bool false If true , then an Object URL will be generated and stored for the recorded audio. Only set this to true if you plan to reuse the recorded audio later in the experiment, as it is a potentially memory-intensive feature. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded audio data. stimulus string The HTML content that was displayed on the screen. estimated_stimulus_onset number This is an estimate of when the stimulus appeared relative to the start of the audio recording. The plugin is configured so that the recording should start prior to the display of the stimulus. We have not yet been able to verify the accuracy of this estimate with external measurement devices. audio_url string A URL to a copy of the audio data. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-audio-response@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-audio-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-audio-response import htmlAudioResponse from '@jspsych/plugin-html-audio-response' ; Examples \u00b6 Simple spoken response to a stimulus Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p style=\"font-size:48px; color:red;\">GREEN</p> <p>Speak the color of the ink.</p>` , recording_duration : 3500 }; Open demo in new tab Allow playback and rerecording; save data to server immediately Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p>Please sing the first few seconds of a song and click the button when you are done.</p> ` , recording_duration : 15000 , allow_playback : true , on_finish : function ( data ){ fetch ( '/save-my-data.php' , { audio_base64 : data . response }) . then (( audio_id ){ data . response = audio_id ; }); } }; This example assumes that there is a script on your experiment server that accepts the data called save-my-data.php . It also assumes that the script will generate a response with an ID for the stored audio file ( audio_id ). In the example, we replace the very long base64 representation of the audio file with the generated ID, which could be just a handful of characters. This would let you link files to responses in data analysis, without having to store long audio files in memory during the experiment. Open demo in new tab Use recorded audio as a subsequent stimulus Code Demo var instruction = { type : jsPsychHtmlButtonResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Make up a name for this shape. When you have one in mind, click the button and then say the name aloud.</p> ` , choices : [ 'I am ready.' ] } var record = { type : jsPsychHtmlAudioResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Recording...</p> ` , recording_duration : 1500 , save_audio_url : true }; var playback = { type : jsPsychAudioButtonResponse , stimulus : ()=>{ return jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. audio_url ; }, prompt : '<p>Click the object the matches the spoken name.</p>' , choices : [ 'img/9.gif' , 'img/10.gif' , 'img/11.gif' , 'img/12.gif' ], button_html : '<img src=\"%choice%\" style=\"width:100px; padding: 20px;\"></img>' } Open demo in new tab","title":"html-audio-response"},{"location":"plugins/html-audio-response/#html-audio-response","text":"Current version: 1.0.2. See version history . This plugin displays HTML content and records audio from the participant via a microphone. In order to get access to the microphone, you need to use the initialize-microphone plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records audio data in base 64 format . This is a text-based representation of the audio which can be coverted to various audio formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of audio recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of audio, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded audio files as Object URLs via save_audio_url: true . This will generate a URL that is storing a copy of the recorded audio, which can be used for subsequent playback. See below for an example where the recorded audio is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of audio snippets, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"html-audio-response"},{"location":"plugins/html-audio-response/#parameters","text":"In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded audio and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_audio_url bool false If true , then an Object URL will be generated and stored for the recorded audio. Only set this to true if you plan to reuse the recorded audio later in the experiment, as it is a potentially memory-intensive feature.","title":"Parameters"},{"location":"plugins/html-audio-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded audio data. stimulus string The HTML content that was displayed on the screen. estimated_stimulus_onset number This is an estimate of when the stimulus appeared relative to the start of the audio recording. The plugin is configured so that the recording should start prior to the display of the stimulus. We have not yet been able to verify the accuracy of this estimate with external measurement devices. audio_url string A URL to a copy of the audio data.","title":"Data Generated"},{"location":"plugins/html-audio-response/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/html-audio-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-audio-response@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-audio-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-audio-response import htmlAudioResponse from '@jspsych/plugin-html-audio-response' ;","title":"Install"},{"location":"plugins/html-audio-response/#examples","text":"Simple spoken response to a stimulus Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p style=\"font-size:48px; color:red;\">GREEN</p> <p>Speak the color of the ink.</p>` , recording_duration : 3500 }; Open demo in new tab Allow playback and rerecording; save data to server immediately Code Demo var trial = { type : jsPsychHtmlAudioResponse , stimulus : ` <p>Please sing the first few seconds of a song and click the button when you are done.</p> ` , recording_duration : 15000 , allow_playback : true , on_finish : function ( data ){ fetch ( '/save-my-data.php' , { audio_base64 : data . response }) . then (( audio_id ){ data . response = audio_id ; }); } }; This example assumes that there is a script on your experiment server that accepts the data called save-my-data.php . It also assumes that the script will generate a response with an ID for the stored audio file ( audio_id ). In the example, we replace the very long base64 representation of the audio file with the generated ID, which could be just a handful of characters. This would let you link files to responses in data analysis, without having to store long audio files in memory during the experiment. Open demo in new tab Use recorded audio as a subsequent stimulus Code Demo var instruction = { type : jsPsychHtmlButtonResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Make up a name for this shape. When you have one in mind, click the button and then say the name aloud.</p> ` , choices : [ 'I am ready.' ] } var record = { type : jsPsychHtmlAudioResponse , stimulus : ` <img src='img/10.gif' style=\"width:100px; padding: 20px;\"></img> <p>Recording...</p> ` , recording_duration : 1500 , save_audio_url : true }; var playback = { type : jsPsychAudioButtonResponse , stimulus : ()=>{ return jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. audio_url ; }, prompt : '<p>Click the object the matches the spoken name.</p>' , choices : [ 'img/9.gif' , 'img/10.gif' , 'img/11.gif' , 'img/12.gif' ], button_html : '<img src=\"%choice%\" style=\"width:100px; padding: 20px;\"></img>' } Open demo in new tab","title":"Examples"},{"location":"plugins/html-button-response/","text":"html-button-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated by button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Parameters \u00b6 In addition to the 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 content to be displayed. choices array of strings [] 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The HTML content that was displayed on the screen. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-button-response import htmlButtonResponse from '@jspsych/plugin-html-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"font-size:48px; color:red;\">GREEN</p>' , choices : [ 'Red' , 'Green' , 'Blue' ], prompt : \"<p>What color is the ink?</p>\" }; Open demo in new tab","title":"html-button-response"},{"location":"plugins/html-button-response/#html-button-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated by button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting.","title":"html-button-response"},{"location":"plugins/html-button-response/#parameters","text":"In addition to the 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 content to be displayed. choices array of strings [] 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 participant is supposed to take (e.g., which key to press). trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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. 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. 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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The HTML content that was displayed on the screen.","title":"Data Generated"},{"location":"plugins/html-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-button-response import htmlButtonResponse from '@jspsych/plugin-html-button-response' ;","title":"Install"},{"location":"plugins/html-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychHtmlButtonResponse , stimulus : '<p style=\"font-size:48px; color:red;\">GREEN</p>' , choices : [ 'Red' , 'Green' , 'Blue' ], prompt : \"<p>What color is the ink?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-keyboard-response/","text":"html-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated with 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 participant has failed to respond within a fixed length of time. Parameters \u00b6 In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-keyboard-response import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:48px; color:green;\">BLUE</p>' , choices : [ 'r' , 'g' , 'b' ], prompt : \"<p>Is the ink color (r)ed, (g)reen, or (b)lue?</p>\" }; Open demo in new tab Showing a 1 second fixation cross; no response allowed Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size: 48px;\">+</p>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; Open demo in new tab","title":"html-keyboard-response"},{"location":"plugins/html-keyboard-response/#html-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and records responses generated with 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 participant has failed to respond within a fixed length of time.","title":"html-keyboard-response"},{"location":"plugins/html-keyboard-response/#parameters","text":"In addition to the 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 strings \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen.","title":"Data Generated"},{"location":"plugins/html-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-keyboard-response import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ;","title":"Install"},{"location":"plugins/html-keyboard-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size:48px; color:green;\">BLUE</p>' , choices : [ 'r' , 'g' , 'b' ], prompt : \"<p>Is the ink color (r)ed, (g)reen, or (b)lue?</p>\" }; Open demo in new tab Showing a 1 second fixation cross; no response allowed Code Demo var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p style=\"font-size: 48px;\">+</p>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-slider-response/","text":"html-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin displays HTML content and allows the participant to respond by dragging a slider. Parameters \u00b6 In addition to the 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 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 participant 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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. slider_start numeric The starting value of the slider. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-slider-response import htmlSliderResponse from '@jspsych/plugin-html-slider-response' ; Examples \u00b6 Displaying question until participant moves the slider Code Demo var trial = { type : jsPsychHtmlSliderResponse , stimulus : `<div style=\"width:500px;\"> <p>How likely is it that team A will win this match?</p> <div style=\"width:240px; float: left;\"> <p>TEAM A</p> <p>10 wins, 5 losses, 6 draws</p> </div> <div style=\"width:240px; float: right;\"> <p>TEAM B</p> <p>6 wins, 4 losses, 11 draws</p> </div> </div>` , require_movement : true , labels : [ '100% chance' , '50% chance' , '0% chance' ] }; Open demo in new tab","title":"html-slider-response"},{"location":"plugins/html-slider-response/#html-slider-response","text":"Current version: 1.1.2. See version history . This plugin displays HTML content and allows the participant to respond by dragging a slider.","title":"html-slider-response"},{"location":"plugins/html-slider-response/#parameters","text":"In addition to the 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 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 participant 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 participant 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/html-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The HTML content that was displayed on the screen. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/html-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-slider-response import htmlSliderResponse from '@jspsych/plugin-html-slider-response' ;","title":"Install"},{"location":"plugins/html-slider-response/#examples","text":"Displaying question until participant moves the slider Code Demo var trial = { type : jsPsychHtmlSliderResponse , stimulus : `<div style=\"width:500px;\"> <p>How likely is it that team A will win this match?</p> <div style=\"width:240px; float: left;\"> <p>TEAM A</p> <p>10 wins, 5 losses, 6 draws</p> </div> <div style=\"width:240px; float: right;\"> <p>TEAM B</p> <p>6 wins, 4 losses, 11 draws</p> </div> </div>` , require_movement : true , labels : [ '100% chance' , '50% chance' , '0% chance' ] }; Open demo in new tab","title":"Examples"},{"location":"plugins/html-video-response/","text":"html-video-response \u00b6 Current version: 1.0.1. See version history . This plugin displays HTML content and records video from the participant via a webcam. In order to get access to the camera, you need to use the initialize-camera plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of video recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of video, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded video files as Object URLs via save_video_url: true . This will generate a URL that stores a copy of the recorded video, which can be used for subsequent playback during the experiment. See below for an example where the recorded video is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of video clips, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems . Parameters \u00b6 In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded video and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_video_url bool false If true , then an Object URL will be generated and stored for the recorded video. Only set this to true if you plan to reuse the recorded video later in the experiment, as it is a potentially memory-intensive feature. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded video data. stimulus string The HTML content that was displayed on the screen. video_url string A URL to a copy of the video data. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-video-response@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-video-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-video-response import htmlVideoResponse from '@jspsych/plugin-html-video-response' ; Examples \u00b6 Simple recorded response to a stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : ` <p style=\"font-size:48px; color:red;\"> <-- </p> <p>Turn your head in the direction of the arrow</p>` , recording_duration : 3500 , show_done_button : false , }; Open demo in new tab Allow playback and rerecording Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face</p>` , recording_duration : 3500 , show_done_button : false , allow_playback : true }; Open demo in new tab Use recorded video as a subsequent stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var record = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face.</p>` , recording_duration : 1500 , show_done_button : false , save_video_url : true }; var classify = { type : jsPsychVideoButtonResponse , stimulus : () => { return [ jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. video_url ]; }, choices : [ \"Happy\" , \"Sad\" , \"Angry\" , \"Surprised\" ], prompt : \"<p>What emotion is this?</p>\" , } Open demo in new tab","title":"html-video-response"},{"location":"plugins/html-video-response/#html-video-response","text":"Current version: 1.0.1. See version history . This plugin displays HTML content and records video from the participant via a webcam. In order to get access to the camera, you need to use the initialize-camera plugin on your timeline prior to using this plugin. Once access is granted for an experiment you do not need to get permission again. This plugin records video data in base 64 format . This is a text-based representation of the video which can be coverted to various video formats using a variety of online tools as well as in languages like python and R. This plugin will generate a large amount of data, and you will need to be careful about how you handle this data. Even a few seconds of video recording will add 10s of kB to jsPsych's data. Multiply this by a handful (or more) of trials, and the data objects will quickly get large. If you need to record a lot of video, either many trials worth or just a few trials with longer responses, we recommend that you save the data to your server immediately after the trial and delete the data in jsPsych's data object. See below for an example of how to do this. This plugin also provides the option to store the recorded video files as Object URLs via save_video_url: true . This will generate a URL that stores a copy of the recorded video, which can be used for subsequent playback during the experiment. See below for an example where the recorded video is used as the stimulus in a subsequent trial. This feature is turned off by default because it uses a relatively large amount of memory compared to most jsPsych features. If you are running an experiment where you need this feature and you are recording lots of video clips, you may want to manually revoke the URLs when you no longer need them using URL.revokeObjectURL(objectURL) . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems .","title":"html-video-response"},{"location":"plugins/html-video-response/#parameters","text":"In addition to the 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 content to be displayed. recording_duration numeric 2000 The maximum length of the recording, in milliseconds. The default value is intentionally set low because of the potential to accidentally record very large data files if left too high. You can set this to null to allow the participant to control the length of the recording via the done button, but be careful with this option as it can lead to crashing the browser if the participant waits too long to stop the recording. 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. show_done_button bool true Whether to show a button on the screen that the participant can click to finish the recording. done_button_label string 'Continue' The label for the done button. allow_playback bool false Whether to allow the participant to listen to their recording and decide whether to rerecord or not. If true , then the participant will be shown an interface to play their recorded video and click one of two buttons to either accept the recording or rerecord. If rerecord is selected, then stimulus will be shown again, as if the trial is starting again from the beginning. record_again_button_label string 'Record again' The label for the record again button enabled when allow_playback: true . accept_button_label string 'Continue' The label for the accept button enabled when allow_playback: true . save_video_url bool false If true , then an Object URL will be generated and stored for the recorded video. Only set this to true if you plan to reuse the recorded video later in the experiment, as it is a potentially memory-intensive feature.","title":"Parameters"},{"location":"plugins/html-video-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The time, since the onset of the stimulus, for the participant to click the done button. If the button is not clicked (or not enabled), then rt will be null . response base64 string The base64-encoded video data. stimulus string The HTML content that was displayed on the screen. video_url string A URL to a copy of the video data.","title":"Data Generated"},{"location":"plugins/html-video-response/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/html-video-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-html-video-response@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-html-video-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-html-video-response import htmlVideoResponse from '@jspsych/plugin-html-video-response' ;","title":"Install"},{"location":"plugins/html-video-response/#examples","text":"Simple recorded response to a stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : ` <p style=\"font-size:48px; color:red;\"> <-- </p> <p>Turn your head in the direction of the arrow</p>` , recording_duration : 3500 , show_done_button : false , }; Open demo in new tab Allow playback and rerecording Code Demo var init_camera = { type : jsPsychInitializeCamera } var trial = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face</p>` , recording_duration : 3500 , show_done_button : false , allow_playback : true }; Open demo in new tab Use recorded video as a subsequent stimulus Code Demo var init_camera = { type : jsPsychInitializeCamera } var record = { type : jsPsychHtmlVideoResponse , stimulus : `<p>Make a sad face.</p>` , recording_duration : 1500 , show_done_button : false , save_video_url : true }; var classify = { type : jsPsychVideoButtonResponse , stimulus : () => { return [ jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. video_url ]; }, choices : [ \"Happy\" , \"Sad\" , \"Angry\" , \"Surprised\" ], prompt : \"<p>What emotion is this?</p>\" , } Open demo in new tab","title":"Examples"},{"location":"plugins/iat-html/","text":"iat-html \u00b6 Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using HTML content as the stimulus. Parameters \u00b6 In addition to the 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 HTML-formatted stimulus to display. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The content to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then html_when_wrong and wrong_image_name is required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string undefined Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of strings \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given stimulus. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-html import iatHtml from '@jspsych/plugin-iat-html' ; Examples \u00b6 Displaying IAT question using html Code Demo var trial = { type : jsPsychIatHtml , stimulus : 'Joyous' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"iat-html"},{"location":"plugins/iat-html/#iat-html","text":"Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using HTML content as the stimulus.","title":"iat-html"},{"location":"plugins/iat-html/#parameters","text":"In addition to the 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 HTML-formatted stimulus to display. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The content to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then html_when_wrong and wrong_image_name is required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string undefined Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of strings \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/iat-html/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given stimulus.","title":"Data Generated"},{"location":"plugins/iat-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-html import iatHtml from '@jspsych/plugin-iat-html' ;","title":"Install"},{"location":"plugins/iat-html/#examples","text":"Displaying IAT question using html Code Demo var trial = { type : jsPsychIatHtml , stimulus : 'Joyous' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"Examples"},{"location":"plugins/iat-image/","text":"iat-image \u00b6 Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using an image as the stimulus. Parameters \u00b6 In addition to the 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 stimulus to display. The path to an image. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The HTML to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then image_when_wrong and wrong_image_name are required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string 'undefined' Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of characters \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete. Data Generated \u00b6 In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given image. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-image import iatImage from '@jspsych/plugin-iat-image' ; Examples \u00b6 Displaying IAT question using image files Code Demo var trial_block = { type : jsPsychIatImage , stimulus : 'img/iat_old_face.jpg' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"iat-image"},{"location":"plugins/iat-image/#iat-image","text":"Current version: 1.1.2. See version history . This plugin runs a single trial of the implicit association test (IAT) , using an image as the stimulus.","title":"iat-image"},{"location":"plugins/iat-image/#parameters","text":"In addition to the 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 stimulus to display. The path to an image. html_when_wrong string <span style=\"color: red; font-size: 80px\">X</span> The HTML to display when a user presses the wrong key. bottom_instructions string <p>If you press the wrong key, a red X will appear. Press any key to continue.</p> Instructions about making a wrong key press and whether another key press is needed to continue. force_correct_key_press boolean false If this is true and the user presses the wrong key then they have to press the other key to continue. An example would be two keys 'e' and 'i'. If the key associated with the stimulus is 'e' and key 'i' was pressed, then pressing 'e' is needed to continue the trial. When this is true , then parameter key_to_move_forward is not used. display_feedback boolean false If true , then image_when_wrong and wrong_image_name are required. If false , trial_duration is needed and trial will continue automatically. left_category_key string 'e' Key press that is associated with the left_category_label . right_category_key string 'i' Key press that is associated with the right_category_label . left_category_label string ['left'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the left side of the page. right_category_label string ['right'] An array that contains the words/labels associated with a certain stimulus. The labels are aligned to the right side of the page. stim_key_association string 'undefined' Either 'left' or 'right'. This indicates whether the stimulus is associated with the key press and category on the left or right side of the page ( left_category_key or right_category_key ). key_to_move_forward array of characters \"ALL_KEYS\" This array contains the characters the participant is allowed to press to move on to the next trial if their key press was incorrect and feedback was displayed. Can also have 'other key' as an option which will only allow the user to select the right key to move forward. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant to view a stimulus for a fixed amount of time, even if they respond before the time is complete.","title":"Parameters"},{"location":"plugins/iat-image/#data-generated","text":"In addition to the default data collected by all 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 participant saw on this trial. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. correct boolean Boolean indicating whether the user's key press was correct or incorrect for the given image.","title":"Data Generated"},{"location":"plugins/iat-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-iat-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-iat-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-iat-image import iatImage from '@jspsych/plugin-iat-image' ;","title":"Install"},{"location":"plugins/iat-image/#examples","text":"Displaying IAT question using image files Code Demo var trial_block = { type : jsPsychIatImage , stimulus : 'img/iat_old_face.jpg' , stim_key_association : 'left' , html_when_wrong : '<span style=\"color: red; font-size: 80px\">X</span>' , bottom_instructions : '<p>If you press the wrong key, a red X will appear. Press the other key to continue</p>' , force_correct_key_press : true , display_feedback : true , trial_duration : 3000 , //Only if display_feedback is false left_category_key : 'e' , right_category_key : 'i' , left_category_label : [ 'OLD' , 'GOOD' ], right_category_label : [ 'YOUNG' , 'BAD' ], response_ends_trial : true } Open demo in new tab","title":"Examples"},{"location":"plugins/image-button-response/","text":"image-button-response \u00b6 Current version: 1.1.2. See version history . This plugin displays an image and records responses generated with a button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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_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 [] 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The path of the image that was displayed. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-button-response import imageButtonResponse from '@jspsych/plugin-image-button-response' ; Examples \u00b6 Displaying question until participant gives a response Code Demo var trial = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'Happy' , 'Sad' ], prompt : \"<p>Is this person happy or sad?</p>\" }; Open demo in new tab","title":"image-button-response"},{"location":"plugins/image-button-response/#image-button-response","text":"Current version: 1.1.2. See version history . This plugin displays an image and records responses generated with a button click. 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 participant has failed to respond within a fixed length of time. The button itself can be customized using HTML formatting. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-button-response"},{"location":"plugins/image-button-response/#parameters","text":"In addition to the 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_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 [] 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. stimulus string The path of the image that was displayed.","title":"Data Generated"},{"location":"plugins/image-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-button-response import imageButtonResponse from '@jspsych/plugin-image-button-response' ;","title":"Install"},{"location":"plugins/image-button-response/#examples","text":"Displaying question until participant gives a response Code Demo var trial = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'Happy' , 'Sad' ], prompt : \"<p>Is this person happy or sad?</p>\" }; Open demo in new tab","title":"Examples"},{"location":"plugins/image-keyboard-response/","text":"image-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin displays and image and records responses generated with 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 participant has failed to respond within a fixed length of time. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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_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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-keyboard-response import imageKeyboardResponse from '@jspsych/plugin-image-keyboard-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'e' , 'i' ], prompt : \"<p>Is this person happy or sad? Press 'e' for happy and 'i' for sad.</p>\" , }; Open demo in new tab Displaying image for a fixed duration; no response allowed Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : \"NO_KEYS\" , prompt : \"<p>Study this face for 5 seconds.</p>\" , trial_duration : 5000 }; Open demo in new tab","title":"image-keyboard-response"},{"location":"plugins/image-keyboard-response/#image-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin displays and image and records responses generated with 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 participant has failed to respond within a fixed length of time. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-keyboard-response"},{"location":"plugins/image-keyboard-response/#parameters","text":"In addition to the 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_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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed.","title":"Data Generated"},{"location":"plugins/image-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-keyboard-response import imageKeyboardResponse from '@jspsych/plugin-image-keyboard-response' ;","title":"Install"},{"location":"plugins/image-keyboard-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : [ 'e' , 'i' ], prompt : \"<p>Is this person happy or sad? Press 'e' for happy and 'i' for sad.</p>\" , }; Open demo in new tab Displaying image for a fixed duration; no response allowed Code Demo var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/happy_face_1.png' , choices : \"NO_KEYS\" , prompt : \"<p>Study this face for 5 seconds.</p>\" , trial_duration : 5000 }; Open demo in new tab","title":"Examples"},{"location":"plugins/image-slider-response/","text":"image-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin displays and image and allows the participant to respond by dragging a slider. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images. Parameters \u00b6 In addition to the 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 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. 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 advance/submit 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 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 participant 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images. Data Generated \u00b6 In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. slider_start numeric The starting value of the slider. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-slider-response import imageSliderResponse from '@jspsych/plugin-image-slider-response' ; Examples \u00b6 Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageSliderResponse , stimulus : 'img/happy_face_1.png' , labels : [ 'happy' , 'sad' ], prompt : \"<p>How happy/sad is this person?</p>\" , }; Open demo in new tab","title":"image-slider-response"},{"location":"plugins/image-slider-response/#image-slider-response","text":"Current version: 1.1.2. See version history . This plugin displays and image and allows the participant to respond by dragging a slider. Image files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the image stimulus, you will need to manually preload the images.","title":"image-slider-response"},{"location":"plugins/image-slider-response/#parameters","text":"In addition to the 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 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. 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 advance/submit 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 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 participant 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 participant 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 participant makes a response. trial_duration numeric null How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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. If the stimulus is an animated gif , you must set this parameter to false, because the canvas rendering method will only present static images.","title":"Parameters"},{"location":"plugins/image-slider-response/#data-generated","text":"In addition to the default data collected by all 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 participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus string The path of the image that was displayed. slider_start numeric The starting value of the slider.","title":"Data Generated"},{"location":"plugins/image-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-image-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-image-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-image-slider-response import imageSliderResponse from '@jspsych/plugin-image-slider-response' ;","title":"Install"},{"location":"plugins/image-slider-response/#examples","text":"Displaying trial until participant gives a response Code Demo var trial = { type : jsPsychImageSliderResponse , stimulus : 'img/happy_face_1.png' , labels : [ 'happy' , 'sad' ], prompt : \"<p>How happy/sad is this person?</p>\" , }; Open demo in new tab","title":"Examples"},{"location":"plugins/initialize-camera/","text":"initialize-camera \u00b6 Current version: 1.0.0 See version history . This plugin asks the participant to grant permission to access a camera. If multiple cameras are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the camera is selected with this plugin it can be accessed with jsPsych.pluginAPI.getCameraRecorder() . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 device_select_message html string <p>Please select the camera you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this camera.' The label for the select button. include_audio bool false Set to true to include an audio track in the recordings. width int null Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . height int null Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . mime_type string null Set this to use a specific MIME type for the recording. Set the entire type, e.g., 'video/mp4; codecs=\"avc1.424028, mp4a.40.2\"' . Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected camera. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-camera import initializeCamera from '@jspsych/plugin-initialize-camera' ; Examples \u00b6 Ask for camera permission Code Demo var trial = { type : jsPsychInitializeCamera }; Open demo in new tab","title":"initialize-camera"},{"location":"plugins/initialize-camera/#initialize-camera","text":"Current version: 1.0.0 See version history . This plugin asks the participant to grant permission to access a camera. If multiple cameras are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the camera is selected with this plugin it can be accessed with jsPsych.pluginAPI.getCameraRecorder() . Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"initialize-camera"},{"location":"plugins/initialize-camera/#parameters","text":"In addition to the 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 device_select_message html string <p>Please select the camera you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this camera.' The label for the select button. include_audio bool false Set to true to include an audio track in the recordings. width int null Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . height int null Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about MediaRecorder constraints here . mime_type string null Set this to use a specific MIME type for the recording. Set the entire type, e.g., 'video/mp4; codecs=\"avc1.424028, mp4a.40.2\"' .","title":"Parameters"},{"location":"plugins/initialize-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected camera.","title":"Data Generated"},{"location":"plugins/initialize-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/initialize-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-camera import initializeCamera from '@jspsych/plugin-initialize-camera' ;","title":"Install"},{"location":"plugins/initialize-camera/#examples","text":"Ask for camera permission Code Demo var trial = { type : jsPsychInitializeCamera }; Open demo in new tab","title":"Examples"},{"location":"plugins/initialize-microphone/","text":"initialize-microphone \u00b6 Current version: 1.0.2. See version history . This plugin asks the participant to grant permission to access a microphone. If multiple microphones are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the microphone is selected with this plugin it can be accessed with jsPsych.pluginAPI.getMicrophoneRecorder() . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems . Parameters \u00b6 In addition to the 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 device_select_message html string <p>Please select the microphone you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this microphone.' The label for the select button. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected microphone. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-microphone@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-microphone.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-microphone import initializeMicrophone from '@jspsych/plugin-initialize-microphone' ; Examples \u00b6 Ask for microphone permission Code Demo var trial = { type : jsPsychInitializeMicrophone }; Open demo in new tab","title":"initialize-microphone"},{"location":"plugins/initialize-microphone/#initialize-microphone","text":"Current version: 1.0.2. See version history . This plugin asks the participant to grant permission to access a microphone. If multiple microphones are connected to the participant's device, then it allows the participant to pick which device to use. Once access is granted for an experiment you do not need to get permission again. Once the microphone is selected with this plugin it can be accessed with jsPsych.pluginAPI.getMicrophoneRecorder() . Warning When recording from a microphone your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the microphone because of potential security problems .","title":"initialize-microphone"},{"location":"plugins/initialize-microphone/#parameters","text":"In addition to the 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 device_select_message html string <p>Please select the microphone you would like to use.</p> The message to display when the user is presented with a dropdown list of available devices. button_label sting 'Use this microphone.' The label for the select button.","title":"Parameters"},{"location":"plugins/initialize-microphone/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value device_id string The device ID of the selected microphone.","title":"Data Generated"},{"location":"plugins/initialize-microphone/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/initialize-microphone/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-initialize-microphone@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-initialize-microphone.js\" >< /script> Using NPM: npm install @jspsych/plugin-initialize-microphone import initializeMicrophone from '@jspsych/plugin-initialize-microphone' ;","title":"Install"},{"location":"plugins/initialize-microphone/#examples","text":"Ask for microphone permission Code Demo var trial = { type : jsPsychInitializeMicrophone }; Open demo in new tab","title":"Examples"},{"location":"plugins/instructions/","text":"instructions \u00b6 Current version: 1.1.2. See version history . This plugin is for showing instructions to the participant. It allows participants to navigate through multiple pages of instructions at their own pace, recording how long the participant spends on each page. Navigation can be done using the mouse or keyboard. participants can be allowed to navigate forwards and backwards through pages, if desired. Parameters \u00b6 In addition to the 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 string 'ArrowRight' This is the key that the participant 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 participant 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 participant 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 participant 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. Participants 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value view_history array An array containing the order of pages the participant viewed (including when the participant returned to previous pages) and the time spent viewing each page. Each object in the array represents a single page view, and contains keys called page_index (the page number, starting with 0) and viewing_time (duration of the page view). This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to view all of the pages. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-instructions@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-instructions.js\" >< /script> Using NPM: npm install @jspsych/plugin-instructions import instructions from '@jspsych/plugin-instructions' ; Examples \u00b6 Showing simple text instructions \u00b6 Showing simple text instructions Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], show_clickable_nav : true } Open demo in new tab Including images \u00b6 Including Images Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'You will be looking at images of arrows: ' + '<br>' + '<img src=\"con2.png\"></img>' ], show_clickable_nav : true } Open demo in new tab Changing Button Text \u00b6 Changing Button Text Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], button_label_next : \"Continue\" , button_label_previous : \"Return to the dark side\" , show_clickable_nav : true } Open demo in new tab","title":"instructions"},{"location":"plugins/instructions/#instructions","text":"Current version: 1.1.2. See version history . This plugin is for showing instructions to the participant. It allows participants to navigate through multiple pages of instructions at their own pace, recording how long the participant spends on each page. Navigation can be done using the mouse or keyboard. participants can be allowed to navigate forwards and backwards through pages, if desired.","title":"instructions"},{"location":"plugins/instructions/#parameters","text":"In addition to the 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 string 'ArrowRight' This is the key that the participant 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 participant 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 participant 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 participant 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. Participants 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.","title":"Parameters"},{"location":"plugins/instructions/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value view_history array An array containing the order of pages the participant viewed (including when the participant returned to previous pages) and the time spent viewing each page. Each object in the array represents a single page view, and contains keys called page_index (the page number, starting with 0) and viewing_time (duration of the page view). This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to view all of the pages.","title":"Data Generated"},{"location":"plugins/instructions/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-instructions@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-instructions.js\" >< /script> Using NPM: npm install @jspsych/plugin-instructions import instructions from '@jspsych/plugin-instructions' ;","title":"Install"},{"location":"plugins/instructions/#examples","text":"","title":"Examples"},{"location":"plugins/instructions/#showing-simple-text-instructions","text":"Showing simple text instructions Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], show_clickable_nav : true } Open demo in new tab","title":"Showing simple text instructions"},{"location":"plugins/instructions/#including-images","text":"Including Images Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'You will be looking at images of arrows: ' + '<br>' + '<img src=\"con2.png\"></img>' ], show_clickable_nav : true } Open demo in new tab","title":"Including images"},{"location":"plugins/instructions/#changing-button-text","text":"Changing Button Text Code Demo var trial = { type : jsPsychInstructions , pages : [ 'Welcome to the experiment. Click next to begin.' , 'This is the second page of instructions.' , 'This is the final page.' ], button_label_next : \"Continue\" , button_label_previous : \"Return to the dark side\" , show_clickable_nav : true } Open demo in new tab","title":"Changing Button Text"},{"location":"plugins/list-of-plugins/","text":"List of Plugins \u00b6 These are the plugins that are included in the jsPsych release. Additional plugins may be available in the community contributions repository . For an overview of what plugins are and how they work, see our plugins overview . Plugin Description animation Shows a sequence of images at a specified frame rate. Records key presses (including timing information) made by the participant while they are viewing the animation. audio\u2011button\u2011response Play an audio file and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. audio\u2011keyboard\u2011response Play an audio file and allow the participant to respond by pressing a key. audio\u2011slider\u2011response Play an audio file and allow the participant to respond by moving a slider to indicate a value. browser\u2011check Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. call\u2011function Executes an arbitrary function call. Doesn't display anything to the participant, and the participant is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. canvas\u2011button\u2011response Draw a stimulus on a HTML canvas element , and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011keyboard\u2011response Draw a stimulus on a HTML canvas element , and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011slider\u2011response Draw a stimulus on a HTML canvas element , and ask the participant to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). categorize\u2011animation The participant responds to an animation and can be given feedback about their response. categorize\u2011html The participant responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response. categorize\u2011image The participant responds to an image using the keyboard and can be given feedback about the correctness of their response. cloze Plugin for displaying a cloze test and checking participants answers against a correct solution. external\u2011html Displays an external HTML page (such as a consent form) and lets the participant respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a participant has granted consent before starting the experiment. free\u2011sort Displays a set of images on the screen in random locations. Participants can click and drag the images to move them around the screen. Records all the moves made by the participant, so the sequence of moves can be recovered from the data. fullscreen Toggles the experiment in and out of fullscreen mode. html\u2011audio\u2011response Display an HTML-formatted stimulus and records an audio response via a microphone. html\u2011button\u2011response Display an HTML-formatted stimulus and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. html\u2011keyboard\u2011response Display an HTML-formatted stimulus and allow the participant to respond by pressing a key. html\u2011slider\u2011response Display an HTML-formatted stimulus and allow the participant to respond by moving a slider to indicate a value. html\u2011video\u2011response Display an HTML-formatted stimulus and records video data via a webcam. iat\u2011html The implicit association task, using HTML-formatted stimuli. iat\u2011image The implicit association task, using images as stimuli. image\u2011button\u2011response Display an image and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. image\u2011keyboard\u2011response Display an image and allow the participant to respond by pressing a key. image\u2011slider\u2011response Display an image and allow the participant to respond by moving a slider to indicate a value. initialize\u2011camera Request permission to use the participant's camera to record video and allows the participant to choose which camera to use if multiple devices are enabled. Also allows setting the mime type of the recorded video. initialize\u2011microphone Request permission to use the participant's microphone to record audio and allows the participant to choose which microphone to use if multiple devices are enabled. instructions For displaying instructions to the participant. Allows the participant to navigate between pages of instructions using keys or buttons. maxdiff Displays rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. mirror\u2011camera Shows a live feed of the participant's camera on the screen. preload This plugin loads images, audio, and video files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and to avoid disrupting the flow of the experiment. reconstruction The participant interacts with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. resize Calibrate the display so that materials display with a known physical size. same\u2011different\u2011html A same-different judgment task. An HTML-formatted stimulus is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. same\u2011different\u2011image A same-different judgment task. An image is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. serial\u2011reaction\u2011time A set of boxes are displayed on the screen and one of them changes color. The participant presses a key that corresponds to the different color box as fast as possible. serial\u2011reaction\u2011time\u2011mouse A set of boxes are displayed on the screen and one of them changes color. The participants clicks the box that changed color as fast as possible. sketchpad Creates an interactive canvas that the participant can draw on using their mouse or touchscreen. survey\u2011html\u2011form Renders a custom HTML form. Allows for mixing multiple kinds of form input. survey\u2011likert Displays likert-style questions. survey\u2011multi\u2011choice Displays multiple choice questions with one answer allowed per question. survey\u2011multi\u2011select Displays multiple choice questions with multiple answes allowed per question. survey\u2011text Shows a prompt with a text box. The participant writes a response and then submits by clicking a button. video\u2011button\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a button. video\u2011keyboard\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a key. video\u2011slider\u2011response Displays a video file with many options for customizing playback. participant responds to the video by moving a slider. virtual\u2011chinrest An implementation of the \"virutal chinrest\" procedure developed by Li, Joo, Yeatman, and Reinecke (2020) . Calibrates the monitor to display items at a known physical size by having participants scale an image to be the same size as a physical credit card. Then uses a blind spot task to estimate the distance between the participant and the display. visual\u2011search\u2011circle A customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. webgazer\u2011calibrate Calibrates the WebGazer extension for eye tracking. webgazer\u2011init\u2011camera Initializes the camera and helps the participant center their face for eye tracking. webgazer\u2011validate Performs validation to measure precision and accuracy of WebGazer eye tracking predictions.","title":"List of Plugins"},{"location":"plugins/list-of-plugins/#list-of-plugins","text":"These are the plugins that are included in the jsPsych release. Additional plugins may be available in the community contributions repository . For an overview of what plugins are and how they work, see our plugins overview . Plugin Description animation Shows a sequence of images at a specified frame rate. Records key presses (including timing information) made by the participant while they are viewing the animation. audio\u2011button\u2011response Play an audio file and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. audio\u2011keyboard\u2011response Play an audio file and allow the participant to respond by pressing a key. audio\u2011slider\u2011response Play an audio file and allow the participant to respond by moving a slider to indicate a value. browser\u2011check Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. call\u2011function Executes an arbitrary function call. Doesn't display anything to the participant, and the participant is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. canvas\u2011button\u2011response Draw a stimulus on a HTML canvas element , and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011keyboard\u2011response Draw a stimulus on a HTML canvas element , and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). canvas\u2011slider\u2011response Draw a stimulus on a HTML canvas element , and ask the participant to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). categorize\u2011animation The participant responds to an animation and can be given feedback about their response. categorize\u2011html The participant responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response. categorize\u2011image The participant responds to an image using the keyboard and can be given feedback about the correctness of their response. cloze Plugin for displaying a cloze test and checking participants answers against a correct solution. external\u2011html Displays an external HTML page (such as a consent form) and lets the participant respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a participant has granted consent before starting the experiment. free\u2011sort Displays a set of images on the screen in random locations. Participants can click and drag the images to move them around the screen. Records all the moves made by the participant, so the sequence of moves can be recovered from the data. fullscreen Toggles the experiment in and out of fullscreen mode. html\u2011audio\u2011response Display an HTML-formatted stimulus and records an audio response via a microphone. html\u2011button\u2011response Display an HTML-formatted stimulus and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. html\u2011keyboard\u2011response Display an HTML-formatted stimulus and allow the participant to respond by pressing a key. html\u2011slider\u2011response Display an HTML-formatted stimulus and allow the participant to respond by moving a slider to indicate a value. html\u2011video\u2011response Display an HTML-formatted stimulus and records video data via a webcam. iat\u2011html The implicit association task, using HTML-formatted stimuli. iat\u2011image The implicit association task, using images as stimuli. image\u2011button\u2011response Display an image and allow the participant to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. image\u2011keyboard\u2011response Display an image and allow the participant to respond by pressing a key. image\u2011slider\u2011response Display an image and allow the participant to respond by moving a slider to indicate a value. initialize\u2011camera Request permission to use the participant's camera to record video and allows the participant to choose which camera to use if multiple devices are enabled. Also allows setting the mime type of the recorded video. initialize\u2011microphone Request permission to use the participant's microphone to record audio and allows the participant to choose which microphone to use if multiple devices are enabled. instructions For displaying instructions to the participant. Allows the participant to navigate between pages of instructions using keys or buttons. maxdiff Displays rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. mirror\u2011camera Shows a live feed of the participant's camera on the screen. preload This plugin loads images, audio, and video files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and to avoid disrupting the flow of the experiment. reconstruction The participant interacts with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. resize Calibrate the display so that materials display with a known physical size. same\u2011different\u2011html A same-different judgment task. An HTML-formatted stimulus is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. same\u2011different\u2011image A same-different judgment task. An image is shown, followed by a brief gap, and then another stimulus is shown. The participant indicates whether the stimuli are the same or different. serial\u2011reaction\u2011time A set of boxes are displayed on the screen and one of them changes color. The participant presses a key that corresponds to the different color box as fast as possible. serial\u2011reaction\u2011time\u2011mouse A set of boxes are displayed on the screen and one of them changes color. The participants clicks the box that changed color as fast as possible. sketchpad Creates an interactive canvas that the participant can draw on using their mouse or touchscreen. survey\u2011html\u2011form Renders a custom HTML form. Allows for mixing multiple kinds of form input. survey\u2011likert Displays likert-style questions. survey\u2011multi\u2011choice Displays multiple choice questions with one answer allowed per question. survey\u2011multi\u2011select Displays multiple choice questions with multiple answes allowed per question. survey\u2011text Shows a prompt with a text box. The participant writes a response and then submits by clicking a button. video\u2011button\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a button. video\u2011keyboard\u2011response Displays a video file with many options for customizing playback. participant responds to the video by pressing a key. video\u2011slider\u2011response Displays a video file with many options for customizing playback. participant responds to the video by moving a slider. virtual\u2011chinrest An implementation of the \"virutal chinrest\" procedure developed by Li, Joo, Yeatman, and Reinecke (2020) . Calibrates the monitor to display items at a known physical size by having participants scale an image to be the same size as a physical credit card. Then uses a blind spot task to estimate the distance between the participant and the display. visual\u2011search\u2011circle A customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. webgazer\u2011calibrate Calibrates the WebGazer extension for eye tracking. webgazer\u2011init\u2011camera Initializes the camera and helps the participant center their face for eye tracking. webgazer\u2011validate Performs validation to measure precision and accuracy of WebGazer eye tracking predictions.","title":"List of Plugins"},{"location":"plugins/maxdiff/","text":"maxdiff \u00b6 Current version: 1.1.2. See version history . The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously. Parameters \u00b6 In addition to the 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 alternatives array undefined An array of one or more alternatives of string type to fill the rows of the maxdiff table. If required is true, then the array must contain two or more alternatives, so that at least one can be selected for both the left and right columns. labels array undefined An array with exactly two labels of string type to display as column headings (to the left and right of the alternatives) for responses on the criteria of interest. randomize_alternative_order boolean false If true, the display order of alternatives is randomly determined at the start of the trial. preamble string empty string HTML formatted string to display at the top of the page above the maxdiff table. required boolean false If true, prevents the user from submitting the response and proceeding until a radio button in both the left and right response columns has been selected. button_label string 'Continue' Label of the button. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the maxdiff table first appears on the screen until the participant's response. labels object An object with two keys, left and right , containing the labels (strings) corresponding to the left and right response columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response object An object with two keys, left and right , containing the alternatives selected on the left and right columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-maxdiff@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-maxdiff.js\" >< /script> Using NPM: npm install @jspsych/plugin-maxdiff import maxdiff from '@jspsych/plugin-maxdiff' ; Examples \u00b6 Basic example Code Demo var maxdiff_page = { type : jsPsychMaxdiff , alternatives : [ 'apple' , 'orange' , 'pear' , 'banana' ], labels : [ 'Most Preferred' , 'Least Preferred' ], preamble : '<p> Please select your <b>most preferred</b> and <b>least preferred</b> fruits. </p>' }; Open demo in new tab","title":"maxdiff"},{"location":"plugins/maxdiff/#maxdiff","text":"Current version: 1.1.2. See version history . The maxdiff plugin displays a table with rows of alternatives to be selected for two mutually-exclusive categories, typically as 'most' or 'least' on a particular criteria (e.g. importance, preference, similarity). The participant responds by selecting one radio button corresponding to an alternative in both the left and right response columns. The same alternative cannot be endorsed on both the left and right response columns (e.g. 'most' and 'least') simultaneously.","title":"maxdiff"},{"location":"plugins/maxdiff/#parameters","text":"In addition to the 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 alternatives array undefined An array of one or more alternatives of string type to fill the rows of the maxdiff table. If required is true, then the array must contain two or more alternatives, so that at least one can be selected for both the left and right columns. labels array undefined An array with exactly two labels of string type to display as column headings (to the left and right of the alternatives) for responses on the criteria of interest. randomize_alternative_order boolean false If true, the display order of alternatives is randomly determined at the start of the trial. preamble string empty string HTML formatted string to display at the top of the page above the maxdiff table. required boolean false If true, prevents the user from submitting the response and proceeding until a radio button in both the left and right response columns has been selected. button_label string 'Continue' Label of the button.","title":"Parameters"},{"location":"plugins/maxdiff/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the maxdiff table first appears on the screen until the participant's response. labels object An object with two keys, left and right , containing the labels (strings) corresponding to the left and right response columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response object An object with two keys, left and right , containing the alternatives selected on the left and right columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/maxdiff/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-maxdiff@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-maxdiff.js\" >< /script> Using NPM: npm install @jspsych/plugin-maxdiff import maxdiff from '@jspsych/plugin-maxdiff' ;","title":"Install"},{"location":"plugins/maxdiff/#examples","text":"Basic example Code Demo var maxdiff_page = { type : jsPsychMaxdiff , alternatives : [ 'apple' , 'orange' , 'pear' , 'banana' ], labels : [ 'Most Preferred' , 'Least Preferred' ], preamble : '<p> Please select your <b>most preferred</b> and <b>least preferred</b> fruits. </p>' }; Open demo in new tab","title":"Examples"},{"location":"plugins/mirror-camera/","text":"mirror-camera \u00b6 Current version: 1.0.0 See version history . This plugin shows a live feed of the participant's camera. It can be useful in experiments that need to record video in order to give the participant a chance to see what is in the view of the camera. You must initialize the camera using the initialize-camera plugin prior to running this plugin. Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems . Parameters \u00b6 In addition to the 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 prompt html string null HTML-formatted content to display below the camera feed. width int null The width of the video playback element. If left null then it will match the size of the recording. height int null The height of the video playback element. If left null then it will match the size of the recording. button_label string \"Continue\" The label of the button to advance to the next trial. mirror_camera bool true Whether to mirror the video image. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time the participant viewed the video playback. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-mirror-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-mirror-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-mirror-camera import mirrorCamera from '@jspsych/plugin-mirror-camera' ; Examples \u00b6 Show the camera feed Code Demo const init_camera = { type : jsPsychInitializeCamera , } const mirror_camera = { type : jsPsychMirrorCamera , } Open demo in new tab","title":"mirror-camera"},{"location":"plugins/mirror-camera/#mirror-camera","text":"Current version: 1.0.0 See version history . This plugin shows a live feed of the participant's camera. It can be useful in experiments that need to record video in order to give the participant a chance to see what is in the view of the camera. You must initialize the camera using the initialize-camera plugin prior to running this plugin. Warning When recording from a camera your experiment will need to be running over https:// protocol. If you try to run the experiment locally using the file:// protocol or over http:// protocol you will not be able to access the camera because of potential security problems .","title":"mirror-camera"},{"location":"plugins/mirror-camera/#parameters","text":"In addition to the 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 prompt html string null HTML-formatted content to display below the camera feed. width int null The width of the video playback element. If left null then it will match the size of the recording. height int null The height of the video playback element. If left null then it will match the size of the recording. button_label string \"Continue\" The label of the button to advance to the next trial. mirror_camera bool true Whether to mirror the video image.","title":"Parameters"},{"location":"plugins/mirror-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time the participant viewed the video playback.","title":"Data Generated"},{"location":"plugins/mirror-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/mirror-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-mirror-camera@1.0.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-mirror-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-mirror-camera import mirrorCamera from '@jspsych/plugin-mirror-camera' ;","title":"Install"},{"location":"plugins/mirror-camera/#examples","text":"Show the camera feed Code Demo const init_camera = { type : jsPsychInitializeCamera , } const mirror_camera = { type : jsPsychMirrorCamera , } Open demo in new tab","title":"Examples"},{"location":"plugins/preload/","text":"preload \u00b6 Current version: 1.1.2. See version history . This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the Media Preloading page for more information. The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the max_load_time duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The continue_after_error parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful. Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. While there are no specific parameters that are required, the plugin expects to be given a set of files to load through one or more of the following parameters: auto_preload or trials (for automatic loading), and/or images , audio , video (for manual loading). To automatically load files based on a timeline of trials, either set the auto_preload parameter is true (to load files based on the main timeline passed to jsPsych.run ) or use the trials parameter to load files based on a specific subset of trials. To manually load a set of files, use the images , audio , and video parameters. You can combine automatic and manual loading methods in a single preload trial. All other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description auto_preload boolean false If true , the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to jsPsych.run . If false , any file(s) to be preloaded should be specified by passing a timeline array to the trials parameter and/or an array of file paths to the images , audio , and/or video parameters. Setting this parameter to false is useful when you plan to preload your files in smaller batches throughout the experiment. trials timeline array [] An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See Creating an Experiment: The Timeline for information on constructing timelines. images array [] Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. audio array [] Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. video array [] Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. message HTML string null HTML-formatted message to show above the progress bar while the files are loading. If null , then no message is shown. show_progress_bar boolean true If true , a progress bar will be shown while the files are loading. If false , no progress bar is shown. continue_after_error boolean false If false , then the experiment will stop during this trial if either (a) one or more of the files fails to load, and/or (b) all files do not finish loading before the max_load_time duration is reached. The trial will display the error_message , as well as the detailed error messages if show_detailed_errors is true . If true , the experiment will continue even if loading fails or times out, and information about loading success/failure will be stored in the trial data (see \"Data Generated\" below). error_message HTML string 'The experiment failed to load.' HTML-formatted message to be shown on the page after loading fails or times out. Only applies when continue_after_error is false . show_detailed_errors boolean false If true , and if continue_after_error is false , then a list of detailed errors will be shown below the error_message . This list will contain the file paths for any files that produced a loading failure, as well as a message indicating that loading timed out, if that was the case. This setting is intended to help the researcher with testing/debugging. If false , and if continue_after_error is false , then only the error_message will be shown if loading fails or times out. max_load_time numeric null Duration to wait, in milliseconds, for all files to load before loading times out. If one or more files has not finished loading within this time limit, then the trial will stop with an error (if continue_after_error is false ), or the trial will end with information about the loading time-out in the trial data (see \"Data Generated\" below). If null , the trial will wait indefinitely for all files to either load or produce an error. on_error function null Function to be called immediately after a file loading request has returned an error. The function receives a single argument, which is the file path that produced the error. This callback is cancelled as soon as the trial ends. See example below. on_success function null Function to be called immediately after a file has successfully loaded. The function receives a single argument, which is the file path that finished loading. This callback is cancelled as soon as the trial ends. See example below. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean If true , then all files loaded successfully within the max_load_time . If false , then one or more file requests returned a failure and/or the file loading did not complete within the max_load_time duration. timeout boolean If true , then the files did not finish loading within the max_load_time duration. If false , then the file loading did not timeout. Note that when the preload trial does not timeout ( timeout: false ), it is still possible for loading to fail ( success: false ). This happens if one or more files fails to load and all file requests trigger either a success or failure event before the max_load_time duration. failed_images array One or more image file paths that produced a loading failure before the trial ended. failed_audio array One or more audio file paths that produced a loading failure before the trial ended. failed_video array One or more video file paths that produced a loading failure before the trial ended. Simulation Mode \u00b6 In visual simulation mode, the plugin will run the trial as if the experiment was running normally. Specifying simulation_options.data will not work in visual mode. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-preload.js\" >< /script> Using NPM: npm install @jspsych/plugin-preload import preload from '@jspsych/plugin-preload' ; Examples \u00b6 Automatically preloading based on other trials Code Demo var preload = { type : jsPsychPreload , auto_preload : true } var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } The stimulus parameter from the image-button-response trials will be automatically preloaded. Open demo in new tab Manually preloading an image Code Demo var preload = { type : jsPsychPreload , images : [ 'img/sad_face_1.jpg' ] } var trial_1 = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Study this face</p> <img src=\"img/sad_face_1.jpg\"></img> ` , choices : [ 'Next' ] } Because the image is embedded inside HTML from the html-button-response plugin, it will not be automatically preloaded. Instead we can preload manually. Open demo in new tab Loading files in batches Code Demo var jsPsych = initJsPsych (); var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } var block_1 = { timeline : [ trial_1 , trial_2 , trial_3 ] } var trial_4 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_1.jpg' , choices : [ 'Next' ] } var trial_5 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_2.jpg' , choices : [ 'Next' ] } var trial_6 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_3.jpg' , choices : [ 'Next' ] } var block_2 = { timeline : [ trial_4 , trial_5 , trial_6 ] } var preload_block_1 = { type : jsPsychPreload , trials : [ block_1 ] } var preload_block_2 = { type : jsPsychPreload , trials : [ block_2 ] } jsPsych . run ([ preload_block_1 , block_1 , preload_block_2 , block_2 ]) You can put trials using the preload plugin throughout your experiment to distribute when files are loaded. In the example above, there are two blocks of trials and the images for each are preloaded just before the corresponding block. Open demo in new tab Showing a detailed error message for debugging loading issues Code Demo var preload = { type : jsPsychPreload , images : [ 'img/bad_file_path.png' ], show_detailed_errors : true } Open demo in new tab For more examples, see the jspsych-preload.html file in the /examples folder of the release and the Media Preloading documentation page.","title":"preload"},{"location":"plugins/preload/#preload","text":"Current version: 1.1.2. See version history . This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the Media Preloading page for more information. The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the max_load_time duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The continue_after_error parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful.","title":"preload"},{"location":"plugins/preload/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. While there are no specific parameters that are required, the plugin expects to be given a set of files to load through one or more of the following parameters: auto_preload or trials (for automatic loading), and/or images , audio , video (for manual loading). To automatically load files based on a timeline of trials, either set the auto_preload parameter is true (to load files based on the main timeline passed to jsPsych.run ) or use the trials parameter to load files based on a specific subset of trials. To manually load a set of files, use the images , audio , and video parameters. You can combine automatic and manual loading methods in a single preload trial. All other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description auto_preload boolean false If true , the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to jsPsych.run . If false , any file(s) to be preloaded should be specified by passing a timeline array to the trials parameter and/or an array of file paths to the images , audio , and/or video parameters. Setting this parameter to false is useful when you plan to preload your files in smaller batches throughout the experiment. trials timeline array [] An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See Creating an Experiment: The Timeline for information on constructing timelines. images array [] Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. audio array [] Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. video array [] Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. message HTML string null HTML-formatted message to show above the progress bar while the files are loading. If null , then no message is shown. show_progress_bar boolean true If true , a progress bar will be shown while the files are loading. If false , no progress bar is shown. continue_after_error boolean false If false , then the experiment will stop during this trial if either (a) one or more of the files fails to load, and/or (b) all files do not finish loading before the max_load_time duration is reached. The trial will display the error_message , as well as the detailed error messages if show_detailed_errors is true . If true , the experiment will continue even if loading fails or times out, and information about loading success/failure will be stored in the trial data (see \"Data Generated\" below). error_message HTML string 'The experiment failed to load.' HTML-formatted message to be shown on the page after loading fails or times out. Only applies when continue_after_error is false . show_detailed_errors boolean false If true , and if continue_after_error is false , then a list of detailed errors will be shown below the error_message . This list will contain the file paths for any files that produced a loading failure, as well as a message indicating that loading timed out, if that was the case. This setting is intended to help the researcher with testing/debugging. If false , and if continue_after_error is false , then only the error_message will be shown if loading fails or times out. max_load_time numeric null Duration to wait, in milliseconds, for all files to load before loading times out. If one or more files has not finished loading within this time limit, then the trial will stop with an error (if continue_after_error is false ), or the trial will end with information about the loading time-out in the trial data (see \"Data Generated\" below). If null , the trial will wait indefinitely for all files to either load or produce an error. on_error function null Function to be called immediately after a file loading request has returned an error. The function receives a single argument, which is the file path that produced the error. This callback is cancelled as soon as the trial ends. See example below. on_success function null Function to be called immediately after a file has successfully loaded. The function receives a single argument, which is the file path that finished loading. This callback is cancelled as soon as the trial ends. See example below.","title":"Parameters"},{"location":"plugins/preload/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value success boolean If true , then all files loaded successfully within the max_load_time . If false , then one or more file requests returned a failure and/or the file loading did not complete within the max_load_time duration. timeout boolean If true , then the files did not finish loading within the max_load_time duration. If false , then the file loading did not timeout. Note that when the preload trial does not timeout ( timeout: false ), it is still possible for loading to fail ( success: false ). This happens if one or more files fails to load and all file requests trigger either a success or failure event before the max_load_time duration. failed_images array One or more image file paths that produced a loading failure before the trial ended. failed_audio array One or more audio file paths that produced a loading failure before the trial ended. failed_video array One or more video file paths that produced a loading failure before the trial ended.","title":"Data Generated"},{"location":"plugins/preload/#simulation-mode","text":"In visual simulation mode, the plugin will run the trial as if the experiment was running normally. Specifying simulation_options.data will not work in visual mode.","title":"Simulation Mode"},{"location":"plugins/preload/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-preload.js\" >< /script> Using NPM: npm install @jspsych/plugin-preload import preload from '@jspsych/plugin-preload' ;","title":"Install"},{"location":"plugins/preload/#examples","text":"Automatically preloading based on other trials Code Demo var preload = { type : jsPsychPreload , auto_preload : true } var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } The stimulus parameter from the image-button-response trials will be automatically preloaded. Open demo in new tab Manually preloading an image Code Demo var preload = { type : jsPsychPreload , images : [ 'img/sad_face_1.jpg' ] } var trial_1 = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>Study this face</p> <img src=\"img/sad_face_1.jpg\"></img> ` , choices : [ 'Next' ] } Because the image is embedded inside HTML from the html-button-response plugin, it will not be automatically preloaded. Instead we can preload manually. Open demo in new tab Loading files in batches Code Demo var jsPsych = initJsPsych (); var trial_1 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_1.jpg' , choices : [ 'Next' ] } var trial_2 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_2.jpg' , choices : [ 'Next' ] } var trial_3 = { type : jsPsychImageButtonResponse , stimulus : 'img/happy_face_3.jpg' , choices : [ 'Next' ] } var block_1 = { timeline : [ trial_1 , trial_2 , trial_3 ] } var trial_4 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_1.jpg' , choices : [ 'Next' ] } var trial_5 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_2.jpg' , choices : [ 'Next' ] } var trial_6 = { type : jsPsychImageButtonResponse , stimulus : 'img/sad_face_3.jpg' , choices : [ 'Next' ] } var block_2 = { timeline : [ trial_4 , trial_5 , trial_6 ] } var preload_block_1 = { type : jsPsychPreload , trials : [ block_1 ] } var preload_block_2 = { type : jsPsychPreload , trials : [ block_2 ] } jsPsych . run ([ preload_block_1 , block_1 , preload_block_2 , block_2 ]) You can put trials using the preload plugin throughout your experiment to distribute when files are loaded. In the example above, there are two blocks of trials and the images for each are preloaded just before the corresponding block. Open demo in new tab Showing a detailed error message for debugging loading issues Code Demo var preload = { type : jsPsychPreload , images : [ 'img/bad_file_path.png' ], show_detailed_errors : true } Open demo in new tab For more examples, see the jspsych-preload.html file in the /examples folder of the release and the Media Preloading documentation page.","title":"Examples"},{"location":"plugins/reconstruction/","text":"reconstruction \u00b6 Current version: 1.1.2. See version history . This plugin allows a participant to interact with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a single value, which is the parameter that can be modified by the participant. The value can only range from 0 to 1. See the example at the bottom of the page for a sample function. Parameters \u00b6 In addition to the 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 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 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value start_value numeric The starting value of the stimulus parameter. final_value numeric The final value of the stimulus parameter. rt numeric The length of time, in milliseconds, that the trial lasted. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-reconstruction@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-reconstruction.js\" >< /script> Using NPM: npm install @jspsych/plugin-reconstruction import reconstruction from '@jspsych/plugin-reconstruction' ; Examples \u00b6 Make a block larger and smaller Code Demo var sample_function = function ( param ){ var size = 50 + Math . floor ( param * 250 ); var html = '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - size / 2 ) + 'px; left:' + ( 150 - size / 2 ) + 'px; background-color: #000000; ' + 'width: ' + size + 'px; height: ' + size + 'px;\"></div></div><p>Press \"h\" to make the square larger. Press \"g\" to make the square smaller.</p>' + '<p>When the square is the same size as the previous one, click Continue.</p>' ; return html ; } var match_item = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - 210 / 2 ) + 'px; left:' + ( 150 - 210 / 2 ) + 'px; background-color: #000000; ' + 'width: 210px; height: 210px;\"></div></div>' , choices : [ 'c' ], post_trial_gap : 1250 , prompt : '<p>Study the size of this square carefully. On the next screen you will have to recreate it. When you are ready, press \"c\".</p>' } var reconstruction = { type : jsPsychReconstruction , stim_function : sample_function , starting_value : 0.5 , } Open demo in new tab","title":"reconstruction"},{"location":"plugins/reconstruction/#reconstruction","text":"Current version: 1.1.2. See version history . This plugin allows a participant to interact with a stimulus by modifying a parameter of the stimulus and observing the change in the stimulus in real-time. The stimulus must be defined through a function that returns an HTML-formatted string. The function should take a single value, which is the parameter that can be modified by the participant. The value can only range from 0 to 1. See the example at the bottom of the page for a sample function.","title":"reconstruction"},{"location":"plugins/reconstruction/#parameters","text":"In addition to the 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 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 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.","title":"Parameters"},{"location":"plugins/reconstruction/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value start_value numeric The starting value of the stimulus parameter. final_value numeric The final value of the stimulus parameter. rt numeric The length of time, in milliseconds, that the trial lasted.","title":"Data Generated"},{"location":"plugins/reconstruction/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-reconstruction@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-reconstruction.js\" >< /script> Using NPM: npm install @jspsych/plugin-reconstruction import reconstruction from '@jspsych/plugin-reconstruction' ;","title":"Install"},{"location":"plugins/reconstruction/#examples","text":"Make a block larger and smaller Code Demo var sample_function = function ( param ){ var size = 50 + Math . floor ( param * 250 ); var html = '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - size / 2 ) + 'px; left:' + ( 150 - size / 2 ) + 'px; background-color: #000000; ' + 'width: ' + size + 'px; height: ' + size + 'px;\"></div></div><p>Press \"h\" to make the square larger. Press \"g\" to make the square smaller.</p>' + '<p>When the square is the same size as the previous one, click Continue.</p>' ; return html ; } var match_item = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"display: block; margin: auto; height: 300px; width: 300px; position: relative;\">' + '<div style=\"display: block; position: absolute; top: ' + ( 150 - 210 / 2 ) + 'px; left:' + ( 150 - 210 / 2 ) + 'px; background-color: #000000; ' + 'width: 210px; height: 210px;\"></div></div>' , choices : [ 'c' ], post_trial_gap : 1250 , prompt : '<p>Study the size of this square carefully. On the next screen you will have to recreate it. When you are ready, press \"c\".</p>' } var reconstruction = { type : jsPsychReconstruction , stim_function : sample_function , starting_value : 0.5 , } Open demo in new tab","title":"Examples"},{"location":"plugins/resize/","text":"resize \u00b6 Current version: 1.0.2. See version history . This plugin displays a resizable div container that allows the user to drag until the container is the same size as the item being measured. Once the user measures the item as close as possible, clicking the button sets a scaling factor for the div containing jsPsych content. This causes the stimuli that follow to have a known size, independent of monitor resolution. Parameters \u00b6 In addition to the 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 item_height numeric 1 The height of the item to be measured. Any units can be used as long as you are consistent with using the same units for all parameters. item_width numeric 1 The width of the item to be measured. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement. prompt string '' HTML content to display below the resizable box, and above the button. button_label string 'Continue' Label to display on the button to complete calibration. starting_size numeric 100 The initial size of the box, in pixels, along the largest dimension. The aspect ratio will be set automatically to match the item width and height. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value final_width_px numeric Final width of the resizable div container, in pixels. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-resize@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-resize.js\" >< /script> Using NPM: npm install @jspsych/plugin-resize import resize from '@jspsych/plugin-resize' ; Examples \u00b6 Measuring a credit card and resizing the display to have 150 pixels equal an inch. Code Demo var inputs = { type : jsPsychResize , item_width : 3 + 3 / 8 , item_height : 2 + 1 / 8 , prompt : \"<p>Click and drag the lower right corner of the box until the box is the same size as a credit card held up to the screen.</p>\" , pixels_per_unit : 150 }; Open demo in new tab","title":"resize"},{"location":"plugins/resize/#resize","text":"Current version: 1.0.2. See version history . This plugin displays a resizable div container that allows the user to drag until the container is the same size as the item being measured. Once the user measures the item as close as possible, clicking the button sets a scaling factor for the div containing jsPsych content. This causes the stimuli that follow to have a known size, independent of monitor resolution.","title":"resize"},{"location":"plugins/resize/#parameters","text":"In addition to the 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 item_height numeric 1 The height of the item to be measured. Any units can be used as long as you are consistent with using the same units for all parameters. item_width numeric 1 The width of the item to be measured. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement. prompt string '' HTML content to display below the resizable box, and above the button. button_label string 'Continue' Label to display on the button to complete calibration. starting_size numeric 100 The initial size of the box, in pixels, along the largest dimension. The aspect ratio will be set automatically to match the item width and height.","title":"Parameters"},{"location":"plugins/resize/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value final_width_px numeric Final width of the resizable div container, in pixels. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content.","title":"Data Generated"},{"location":"plugins/resize/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/resize/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-resize@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-resize.js\" >< /script> Using NPM: npm install @jspsych/plugin-resize import resize from '@jspsych/plugin-resize' ;","title":"Install"},{"location":"plugins/resize/#examples","text":"Measuring a credit card and resizing the display to have 150 pixels equal an inch. Code Demo var inputs = { type : jsPsychResize , item_width : 3 + 3 / 8 , item_height : 2 + 1 / 8 , prompt : \"<p>Click and drag the lower right corner of the box until the box is the same size as a credit card held up to the screen.</p>\" , pixels_per_unit : 150 }; Open demo in new tab","title":"Examples"},{"location":"plugins/same-different-html/","text":"same-different-html \u00b6 Current version: 1.1.2. See version history . The same-different-html plugin displays two stimuli sequentially. Stimuli are HTML objects. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example. Parameters \u00b6 In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the HTML-formatted content that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-html import sameDifferentHtml from '@jspsych/plugin-same-different-html' ; Examples \u00b6 Two text choices Code Demo var trial = { type : jsPsychSameDifferentHtml , stimuli : [ '<p style=\"font-size:30px;\">Climbing</p>' , '<p style=\"font-size:30px;\">Walking</p>' ], prompt : `<p>Press 's' if the activities require the same amount of physical exertion.</p> <p>Press 'd' if the activities require different amount of physical exertion.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"same-different-html"},{"location":"plugins/same-different-html/#same-different-html","text":"Current version: 1.1.2. See version history . The same-different-html plugin displays two stimuli sequentially. Stimuli are HTML objects. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example.","title":"same-different-html"},{"location":"plugins/same-different-html/#parameters","text":"In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press).","title":"Parameters"},{"location":"plugins/same-different-html/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the HTML-formatted content that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue.","title":"Data Generated"},{"location":"plugins/same-different-html/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-html@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-html.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-html import sameDifferentHtml from '@jspsych/plugin-same-different-html' ;","title":"Install"},{"location":"plugins/same-different-html/#examples","text":"Two text choices Code Demo var trial = { type : jsPsychSameDifferentHtml , stimuli : [ '<p style=\"font-size:30px;\">Climbing</p>' , '<p style=\"font-size:30px;\">Walking</p>' ], prompt : `<p>Press 's' if the activities require the same amount of physical exertion.</p> <p>Press 'd' if the activities require different amount of physical exertion.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"Examples"},{"location":"plugins/same-different-image/","text":"same-different-image \u00b6 Current version: 1.1.2. See version history . The same-different-image plugin displays two stimuli sequentially. Stimuli are images. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example. Parameters \u00b6 In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the paths to the image files that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-image import sameDifferentImage from '@jspsych/plugin-same-different-image' ; Examples \u00b6 Identifying emotional expressions Code Demo var trial = { type : jsPsychSameDifferentImage , stimuli : [ 'img/happy_face_1.jpg' , 'img/sad_face_3.jpg' ], prompt : `<p>Press s if the faces had the same emotional expression.</p> <p>Press d if the faces had different emotional expressions.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"same-different-image"},{"location":"plugins/same-different-image/#same-different-image","text":"Current version: 1.1.2. See version history . The same-different-image plugin displays two stimuli sequentially. Stimuli are images. The participant responds using the keyboard, and indicates whether the stimuli were the same or different. Same does not necessarily mean identical; a category judgment could be made, for example.","title":"same-different-image"},{"location":"plugins/same-different-image/#parameters","text":"In addition to the 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 string 'q' The key that participants should press to indicate that the two stimuli are the same. different_key string 'p' The key that participants 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 participant 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 participant 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 participant is supposed to take (e.g., which key to press).","title":"Parameters"},{"location":"plugins/same-different-image/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value stimulus array An array of length 2 containing the paths to the image files that the participant saw for each trial. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant'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 participant to continue after the first stimulus. The time is measured from when the first stimulus appears on the screen until the participant's response. response_stim1 string Indicates which key the participant pressed to continue.","title":"Data Generated"},{"location":"plugins/same-different-image/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-same-different-image@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-same-different-image.js\" >< /script> Using NPM: npm install @jspsych/plugin-same-different-image import sameDifferentImage from '@jspsych/plugin-same-different-image' ;","title":"Install"},{"location":"plugins/same-different-image/#examples","text":"Identifying emotional expressions Code Demo var trial = { type : jsPsychSameDifferentImage , stimuli : [ 'img/happy_face_1.jpg' , 'img/sad_face_3.jpg' ], prompt : `<p>Press s if the faces had the same emotional expression.</p> <p>Press d if the faces had different emotional expressions.</p>` , same_key : 's' , different_key : 'd' , first_stim_duration : 800 , answer : 'different' } Open demo in new tab","title":"Examples"},{"location":"plugins/serial-reaction-time-mouse/","text":"serial-reaction-time-mouse \u00b6 Current version: 1.1.2. See version history . The serial reaction time mouse plugin implements a generalized version of the SRT task (Nissen & Bullmer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant must click on the square that changes color. Parameters \u00b6 In addition to the 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. 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 mouse click. 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. 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. allow_nontarget_responses boolean false If true, the user can make nontarget response. 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 participant is supposed to take (e.g., which keys to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The grid representation. Each inner array represents a single row. The entries in the inner arrays represent the columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The [row, column] target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. response array The [row, column] response location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. correct boolean Whether the response location matches the target location ( true ) or not ( false ). Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time-mouse@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time-mouse.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time-mouse import serialReactionTimeMouse from '@jspsych/plugin-serial-reaction-time-mouse' ; Examples \u00b6 A classic version of the SRT Code Demo var grid = [ [ 1 , 1 , 1 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 3 ] } Open demo in new tab A 2x2 grid with extra space and different colors Code Demo var grid = [ [ 1 , 0 , 1 ], [ 0 , 0 , 0 ], [ 1 , 0 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ], target_color : '#006738' } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ], target_color : '#F78F1E' } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 2 ], target_color : '#13B24B' } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 0 ], target_color : '#E74921' } Open demo in new tab","title":"serial-reaction-time-mouse"},{"location":"plugins/serial-reaction-time-mouse/#serial-reaction-time-mouse","text":"Current version: 1.1.2. See version history . The serial reaction time mouse plugin implements a generalized version of the SRT task (Nissen & Bullmer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant must click on the square that changes color.","title":"serial-reaction-time-mouse"},{"location":"plugins/serial-reaction-time-mouse/#parameters","text":"In addition to the 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. 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 mouse click. 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. 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. allow_nontarget_responses boolean false If true, the user can make nontarget response. 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 participant is supposed to take (e.g., which keys to press).","title":"Parameters"},{"location":"plugins/serial-reaction-time-mouse/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The grid representation. Each inner array represents a single row. The entries in the inner arrays represent the columns. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The [row, column] target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. response array The [row, column] response location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. correct boolean Whether the response location matches the target location ( true ) or not ( false ).","title":"Data Generated"},{"location":"plugins/serial-reaction-time-mouse/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time-mouse@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time-mouse.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time-mouse import serialReactionTimeMouse from '@jspsych/plugin-serial-reaction-time-mouse' ;","title":"Install"},{"location":"plugins/serial-reaction-time-mouse/#examples","text":"A classic version of the SRT Code Demo var grid = [ [ 1 , 1 , 1 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 3 ] } Open demo in new tab A 2x2 grid with extra space and different colors Code Demo var grid = [ [ 1 , 0 , 1 ], [ 0 , 0 , 0 ], [ 1 , 0 , 1 ] ] var trial_1 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 0 ], target_color : '#006738' } var trial_2 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 0 , 2 ], target_color : '#F78F1E' } var trial_3 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 2 ], target_color : '#13B24B' } var trial_4 = { type : jsPsychSerialReactionTimeMouse , grid : grid , target : [ 2 , 0 ], target_color : '#E74921' } Open demo in new tab","title":"Examples"},{"location":"plugins/serial-reaction-time/","text":"serial-reaction-time \u00b6 Current version: 1.1.2. See version history . The serial reaction time plugin implements a generalized version of the SRT task (Nissen & Bullemer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant presses a key that corresponds to the darkened key. Feedback is optionally displayed, showing the participant which square the key they pressed matches. Parameters \u00b6 In addition to the 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 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 participant is supposed to take (e.g., which keys to press). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The representation of the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The representation of the target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant's response matched the target. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time import serialReactionTime from '@jspsych/plugin-serial-reaction-time' ; Examples \u00b6 A classic SRT Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the S, F, H, and K keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 , 1 , 1 ] ] var response_map = [ [ 's' , 'f' , 'h' , 'k' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 3 ] } Open demo in new tab 2x2 grid with feedback Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the R, I, V, and M keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 ], [ 1 , 1 ] ] var response_map = [ [ 'r' , 'i' ], [ 'v' , 'm' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ], show_response_feedback : true , feedback_duration : 500 } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 0 ], show_response_feedback : true , feedback_duration : 500 } Open demo in new tab","title":"serial-reaction-time"},{"location":"plugins/serial-reaction-time/#serial-reaction-time","text":"Current version: 1.1.2. See version history . The serial reaction time plugin implements a generalized version of the SRT task (Nissen & Bullemer, 1987) . Squares are displayed in a grid-based system on the screen, and one square changes color. The participant presses a key that corresponds to the darkened key. Feedback is optionally displayed, showing the participant which square the key they pressed matches.","title":"serial-reaction-time"},{"location":"plugins/serial-reaction-time/#parameters","text":"In addition to the 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 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 participant is supposed to take (e.g., which keys to press).","title":"Parameters"},{"location":"plugins/serial-reaction-time/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value grid array The representation of the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. target array The representation of the target location on the grid. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the second stimulus first appears on the screen until the participant's response. correct boolean true if the participant's response matched the target.","title":"Data Generated"},{"location":"plugins/serial-reaction-time/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-serial-reaction-time@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-serial-reaction-time.js\" >< /script> Using NPM: npm install @jspsych/plugin-serial-reaction-time import serialReactionTime from '@jspsych/plugin-serial-reaction-time' ;","title":"Install"},{"location":"plugins/serial-reaction-time/#examples","text":"A classic SRT Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the S, F, H, and K keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 , 1 , 1 ] ] var response_map = [ [ 's' , 'f' , 'h' , 'k' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ] } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ] } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 2 ] } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 3 ] } Open demo in new tab 2x2 grid with feedback Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : '<p>Use the R, I, V, and M keys to respond.</p>' , choices : [ 'Continue' ] } var grid = [ [ 1 , 1 ], [ 1 , 1 ] ] var response_map = [ [ 'r' , 'i' ], [ 'v' , 'm' ] ] var trial_1 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 0 ], show_response_feedback : true , feedback_duration : 500 } var trial_2 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 0 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_3 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 1 ], show_response_feedback : true , feedback_duration : 500 } var trial_4 = { type : jsPsychSerialReactionTime , grid : grid , choices : response_map , target : [ 1 , 0 ], show_response_feedback : true , feedback_duration : 500 } Open demo in new tab","title":"Examples"},{"location":"plugins/sketchpad/","text":"sketchpad \u00b6 Current version: 1.0.3. See version history . This plugin creates an interactive canvas that the participant can draw on using their mouse or touchscreen. It can be used for sketching tasks, like asking the participant to draw a particular object. It can also be used for some image segmentation or annotation tasks by setting the background_image parameter to render an image on the canvas. The plugin stores a base 64 data URL representation of the final image. This can be converted to an image file using online tools or short programs in R , python , or another language of your choice. It also records all of the individual strokes that the participant made during the trial. Warning This plugin generates a lot of data. Each trial can easily add 500kb+ of data to a final JSON output. You can reduce the amount of data generated by turning off storage of the individual stroke data ( save_strokes: false ) or storage of the final image ( save_final_image: false ) if your use case doesn't require that information. If you are going to be collecting a lot of data with this plugin you may want to save your data to your server after each trial and not wait until the end of the experiment to perform a single bulk upload. You can do this by putting data saving code inside the on_data_update event handler . Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. Parameter Type Default Value Description canvas_shape \"rectangle\" or \"circle\" \"rectangle\" The shape of the canvas element. canvas_width int 500 Width of the canvas in pixels when canvas_shape is \"rectangle\" canvas_height int 500 Height of the canvas in pixels when canvas_shape is \"rectangle\" canvas_diameter int 500 Diameter of the canvas in pixels when canvas_shape is \"circle\" canvas_border_width int 0 Width of the canvas border canvas_border_color string \"#000\" Color of the canvas border background_image image path null Path to an image to render as the background of the canvas background_color string \"#fff\" Color of the canvas background. Note that a background_image will render on top of the color. stroke_width int 2 Width of the stroke on the canvas stroke_color string \"#000\" Color of the stroke on the canvas stroke_color_palette array of strings [] Array of colors to render as a palette of choices for stroke color. Clicking on the corresponding color button will change the stroke color. prompt string null HTML content to render on the screen. prompt_location \"abovecanvas\" or \"belowcanvas\" or \"belowbutton\" \"abovecanvas\" The location to render the prompt content. save_final_image bool true Whether to save the final image in the data as a base64 encoded data URL. save_strokes bool true Whether to save the individual stroke data that generated the final image. key_to_draw key string null If this key is held down then it is like the mouse button being held down. The \"ink\" will flow when the button is held and stop when it is lifted. Pass in the string representation of the key, e.g., 'a' for the A key or ' ' for the spacebar. show_finished_button bool true Whether to show the button that ends the trial. finished_button_label string \"Finished\" The label for the button that ends the trial. show_clear_button bool true Whether to show the button that clears the entire drawing. clear_button_label string \"Clear\" The label for the button that clears the entire drawing. show_undo_button bool true Whether to show the button that enables an undo action. undo_button_label string \"Undo\" The label for the button that enables an undo action. show_redo_button bool true Whether to show the button that enables a redo action. Note that show_undo_button must be true for the redo button to show up. redo_button_label string \"Redo\" The label for the button that enables a redo action. choices array of keys \"NO_KEYS\" This array contains the key(s) that the participant is allowed to press in order to end the trial. Keys should be specified as characters (e.g., 'a' , 'q' , ' ' , 'Enter' , 'ArrowDown' ) - see this page and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"NO_KEYS\" means that no keys will be accepted as valid responses. Specifying \"ALL_KEYS\" will mean that all responses are allowed. trial_duration int null Length of time before the trial ends. If null the trial will continue indefinitely (until another way of ending the trial occurs). show_countdown_trial_duration bool false Whether to show a timer that counts down until the end of the trial when trial_duration is not null . countdown_timer_html string '<span id=\"sketchpad-timer\"></span> remaining' The HTML to use for rendering the countdown timer. The element with id=\"sketchpad-timer\" will have its content replaced by a countdown timer in the format MM:SS . Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time from the start of the trial to the end of the trial. response string If the trial was ended by clicking the finished button, then \"button\" . If the trial was ended by pressing a key, then the key that was pressed. If the trial timed out, then null . png base64 data URL string If save_image is true, then this will contain the base64 encoded data URL for the image, in png format. strokes array of stroke objects If save_strokes is true, then this will contain an array of stroke objects. Objects have an action property that is either \"start\" , \"move\" , or \"end\" . If action is \"start\" or \"move\" it will have an x and y property that report the coordinates of the action relative to the upper-left corner of the canvas. If action is \"start\" then the object will also have a t and color property, specifying the time of the action relative to the onset of the trial (ms) and the color of the stroke. If action is \"end\" then it will only have a t property. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-sketchpad@1.0.3\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-sketchpad.js\" >< /script> Using NPM: npm install @jspsych/plugin-sketchpad import sketchpad from '@jspsych/plugin-sketchpad' ; Examples \u00b6 Basic sketchpad with a prompt Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p>Draw an apple!</p>' , prompt_location : 'abovecanvas' , canvas_width : 300 , canvas_height : 300 , canvas_border_width : 2 } Open demo in new tab Image segmentation with different colors Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p style=\"width:380px\">Circle the mouth using red. Circle the eyes using blue.</p>' , prompt_location : 'abovecanvas' , stroke_color_palette : [ 'red' , 'blue' ], stroke_color : 'red' , background_image : 'img/sad_face_4.jpg' , canvas_width : 380 , canvas_height : 252 } Open demo in new tab Draw an image in a time limit, then display the image and ask for a label. Code Demo var draw = { type : jsPsychSketchpad , prompt : '<p>Draw the first animal that comes to mind. You have 30 seconds!</p>' , prompt_location : 'belowcanvas' , trial_duration : 30000 , show_countdown_trial_duration : true , } var label = { type : jsPsychSurveyText , preamble : () => { var imageData = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. png ; return `<img src=\" ${ imageData } \"></img>` ; }, questions : [ { prompt : 'What animal did you draw?' } ] } Open demo in new tab","title":"sketchpad"},{"location":"plugins/sketchpad/#sketchpad","text":"Current version: 1.0.3. See version history . This plugin creates an interactive canvas that the participant can draw on using their mouse or touchscreen. It can be used for sketching tasks, like asking the participant to draw a particular object. It can also be used for some image segmentation or annotation tasks by setting the background_image parameter to render an image on the canvas. The plugin stores a base 64 data URL representation of the final image. This can be converted to an image file using online tools or short programs in R , python , or another language of your choice. It also records all of the individual strokes that the participant made during the trial. Warning This plugin generates a lot of data. Each trial can easily add 500kb+ of data to a final JSON output. You can reduce the amount of data generated by turning off storage of the individual stroke data ( save_strokes: false ) or storage of the final image ( save_final_image: false ) if your use case doesn't require that information. If you are going to be collecting a lot of data with this plugin you may want to save your data to your server after each trial and not wait until the end of the experiment to perform a single bulk upload. You can do this by putting data saving code inside the on_data_update event handler .","title":"sketchpad"},{"location":"plugins/sketchpad/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. Parameter Type Default Value Description canvas_shape \"rectangle\" or \"circle\" \"rectangle\" The shape of the canvas element. canvas_width int 500 Width of the canvas in pixels when canvas_shape is \"rectangle\" canvas_height int 500 Height of the canvas in pixels when canvas_shape is \"rectangle\" canvas_diameter int 500 Diameter of the canvas in pixels when canvas_shape is \"circle\" canvas_border_width int 0 Width of the canvas border canvas_border_color string \"#000\" Color of the canvas border background_image image path null Path to an image to render as the background of the canvas background_color string \"#fff\" Color of the canvas background. Note that a background_image will render on top of the color. stroke_width int 2 Width of the stroke on the canvas stroke_color string \"#000\" Color of the stroke on the canvas stroke_color_palette array of strings [] Array of colors to render as a palette of choices for stroke color. Clicking on the corresponding color button will change the stroke color. prompt string null HTML content to render on the screen. prompt_location \"abovecanvas\" or \"belowcanvas\" or \"belowbutton\" \"abovecanvas\" The location to render the prompt content. save_final_image bool true Whether to save the final image in the data as a base64 encoded data URL. save_strokes bool true Whether to save the individual stroke data that generated the final image. key_to_draw key string null If this key is held down then it is like the mouse button being held down. The \"ink\" will flow when the button is held and stop when it is lifted. Pass in the string representation of the key, e.g., 'a' for the A key or ' ' for the spacebar. show_finished_button bool true Whether to show the button that ends the trial. finished_button_label string \"Finished\" The label for the button that ends the trial. show_clear_button bool true Whether to show the button that clears the entire drawing. clear_button_label string \"Clear\" The label for the button that clears the entire drawing. show_undo_button bool true Whether to show the button that enables an undo action. undo_button_label string \"Undo\" The label for the button that enables an undo action. show_redo_button bool true Whether to show the button that enables a redo action. Note that show_undo_button must be true for the redo button to show up. redo_button_label string \"Redo\" The label for the button that enables a redo action. choices array of keys \"NO_KEYS\" This array contains the key(s) that the participant is allowed to press in order to end the trial. Keys should be specified as characters (e.g., 'a' , 'q' , ' ' , 'Enter' , 'ArrowDown' ) - see this page and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"NO_KEYS\" means that no keys will be accepted as valid responses. Specifying \"ALL_KEYS\" will mean that all responses are allowed. trial_duration int null Length of time before the trial ends. If null the trial will continue indefinitely (until another way of ending the trial occurs). show_countdown_trial_duration bool false Whether to show a timer that counts down until the end of the trial when trial_duration is not null . countdown_timer_html string '<span id=\"sketchpad-timer\"></span> remaining' The HTML to use for rendering the countdown timer. The element with id=\"sketchpad-timer\" will have its content replaced by a countdown timer in the format MM:SS .","title":"Parameters"},{"location":"plugins/sketchpad/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value rt int The length of time from the start of the trial to the end of the trial. response string If the trial was ended by clicking the finished button, then \"button\" . If the trial was ended by pressing a key, then the key that was pressed. If the trial timed out, then null . png base64 data URL string If save_image is true, then this will contain the base64 encoded data URL for the image, in png format. strokes array of stroke objects If save_strokes is true, then this will contain an array of stroke objects. Objects have an action property that is either \"start\" , \"move\" , or \"end\" . If action is \"start\" or \"move\" it will have an x and y property that report the coordinates of the action relative to the upper-left corner of the canvas. If action is \"start\" then the object will also have a t and color property, specifying the time of the action relative to the onset of the trial (ms) and the color of the stroke. If action is \"end\" then it will only have a t property.","title":"Data Generated"},{"location":"plugins/sketchpad/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/sketchpad/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-sketchpad@1.0.3\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-sketchpad.js\" >< /script> Using NPM: npm install @jspsych/plugin-sketchpad import sketchpad from '@jspsych/plugin-sketchpad' ;","title":"Install"},{"location":"plugins/sketchpad/#examples","text":"Basic sketchpad with a prompt Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p>Draw an apple!</p>' , prompt_location : 'abovecanvas' , canvas_width : 300 , canvas_height : 300 , canvas_border_width : 2 } Open demo in new tab Image segmentation with different colors Code Demo var trial = { type : jsPsychSketchpad , prompt : '<p style=\"width:380px\">Circle the mouth using red. Circle the eyes using blue.</p>' , prompt_location : 'abovecanvas' , stroke_color_palette : [ 'red' , 'blue' ], stroke_color : 'red' , background_image : 'img/sad_face_4.jpg' , canvas_width : 380 , canvas_height : 252 } Open demo in new tab Draw an image in a time limit, then display the image and ask for a label. Code Demo var draw = { type : jsPsychSketchpad , prompt : '<p>Draw the first animal that comes to mind. You have 30 seconds!</p>' , prompt_location : 'belowcanvas' , trial_duration : 30000 , show_countdown_trial_duration : true , } var label = { type : jsPsychSurveyText , preamble : () => { var imageData = jsPsych . data . get (). last ( 1 ). values ()[ 0 ]. png ; return `<img src=\" ${ imageData } \"></img>` ; }, questions : [ { prompt : 'What animal did you draw?' } ] } Open demo in new tab","title":"Examples"},{"location":"plugins/survey-html-form/","text":"survey-html-form \u00b6 Current version: 1.0.2. See version history . The survey-html-form plugin displays a set of <inputs> from a HTML string. The type of input can be freely chosen, for a list of possible input types see the MDN page on inputs . The participant provides answers to the input fields. Parameters \u00b6 In addition to the 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 html string undefined HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The <form> tag must not be included and is generated by the plugin. This string can contain other HTML elements besides the input fields. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. dataAsArray boolean false Retrieve the data as an array e.g. [{name: \"INPUT_NAME\", value: \"INPUT_VALUE\"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. This might be useful if you omit naming your inputs. autofocus string empty string The HTML element ID of a form field to autofocus on. The focused element is the element that will receive keyboard events. For elements like <input type=\"text\"> or <textbox> , autofocus means that the cursor will appear in the text input area when the trial loads. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-html-form@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-html-form.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-html-form import surveyHtmlForm from '@jspsych/plugin-survey-html-form' ; Examples \u00b6 Fill in the blanks Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>How are you feeling <b>right now?</b></p>' , html : '<p> I am feeling <input name=\"first\" type=\"text\" />, <input name=\"second\" type=\"text\" />, and <input name=\"third\" type=\"text\" />.</p>' }; Open demo in new tab Using the autofocus parameter Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>What is your favorite bird?</p>' , html : '<p>My favorite bird is <input type=\"text\" id=\"test-resp-box\" name=\"response\" size=\"10\" /></p>' , autofocus : 'test-resp-box' }; In this example, the browser will focus on the element with the ID test-resp-box when the trial loads. For <input type=\"text\"> elements, this means that the cursor will appear inside the text box. Open demo in new tab","title":"survey-html-form"},{"location":"plugins/survey-html-form/#survey-html-form","text":"Current version: 1.0.2. See version history . The survey-html-form plugin displays a set of <inputs> from a HTML string. The type of input can be freely chosen, for a list of possible input types see the MDN page on inputs . The participant provides answers to the input fields.","title":"survey-html-form"},{"location":"plugins/survey-html-form/#parameters","text":"In addition to the 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 html string undefined HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The <form> tag must not be included and is generated by the plugin. This string can contain other HTML elements besides the input fields. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. dataAsArray boolean false Retrieve the data as an array e.g. [{name: \"INPUT_NAME\", value: \"INPUT_VALUE\"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. This might be useful if you omit naming your inputs. autofocus string empty string The HTML element ID of a form field to autofocus on. The focused element is the element that will receive keyboard events. For elements like <input type=\"text\"> or <textbox> , autofocus means that the cursor will appear in the text input area when the trial loads. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-html-form/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response.","title":"Data Generated"},{"location":"plugins/survey-html-form/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/survey-html-form/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-html-form@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-html-form.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-html-form import surveyHtmlForm from '@jspsych/plugin-survey-html-form' ;","title":"Install"},{"location":"plugins/survey-html-form/#examples","text":"Fill in the blanks Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>How are you feeling <b>right now?</b></p>' , html : '<p> I am feeling <input name=\"first\" type=\"text\" />, <input name=\"second\" type=\"text\" />, and <input name=\"third\" type=\"text\" />.</p>' }; Open demo in new tab Using the autofocus parameter Code Demo var trial = { type : jsPsychSurveyHtmlForm , preamble : '<p>What is your favorite bird?</p>' , html : '<p>My favorite bird is <input type=\"text\" id=\"test-resp-box\" name=\"response\" size=\"10\" /></p>' , autofocus : 'test-resp-box' }; In this example, the browser will focus on the element with the ID test-resp-box when the trial loads. For <input type=\"text\"> elements, this means that the cursor will appear inside the text box. Open demo in new tab","title":"Examples"},{"location":"plugins/survey-likert/","text":"survey-likert \u00b6 Current version: 1.1.2. See version history . The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds by selecting a radio button. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, labels and required parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The strings are the question that will be associated with a slider. labels : Type array, default value is undefined . Each array element is an array of strings. The innermost arrays contain a set of labels to display for an individual question. If you want to use blank responses and only label the end points or some subset of the options, just insert a blank string for the unlabeled responses. required : Type boolean, default value is false. Makes answering questions required. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. scale_width numeric null The width of the likert scale in pixels. If left null , then the width of the scale will be equal to the width of the widest content on the page. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-likert@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-likert.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-likert import surveyLikert from '@jspsych/plugin-survey-likert' ; Examples \u00b6 Single Question Code Demo var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , labels : [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ] } ] }; Open demo in new tab Multiple questions in a random order Code Demo var likert_scale = [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ]; var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , name : 'Vegetables' , labels : likert_scale }, { prompt : \"I like fruit.\" , name : 'Fruit' , labels : likert_scale }, { prompt : \"I like meat.\" , name : 'Meat' , labels : likert_scale }, ], randomize_question_order : true }; Open demo in new tab","title":"survey-likert"},{"location":"plugins/survey-likert/#survey-likert","text":"Current version: 1.1.2. See version history . The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds by selecting a radio button.","title":"survey-likert"},{"location":"plugins/survey-likert/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, labels and required parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The strings are the question that will be associated with a slider. labels : Type array, default value is undefined . Each array element is an array of strings. The innermost arrays contain a set of labels to display for an individual question. If you want to use blank responses and only label the end points or some subset of the options, just insert a blank string for the unlabeled responses. required : Type boolean, default value is false. Makes answering questions required. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. scale_width numeric null The width of the likert scale in pixels. If left null , then the width of the scale will be equal to the width of the widest content on the page. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-likert/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-likert/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-likert@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-likert.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-likert import surveyLikert from '@jspsych/plugin-survey-likert' ;","title":"Install"},{"location":"plugins/survey-likert/#examples","text":"Single Question Code Demo var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , labels : [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ] } ] }; Open demo in new tab Multiple questions in a random order Code Demo var likert_scale = [ \"Strongly Disagree\" , \"Disagree\" , \"Neutral\" , \"Agree\" , \"Strongly Agree\" ]; var trial = { type : jsPsychSurveyLikert , questions : [ { prompt : \"I like vegetables.\" , name : 'Vegetables' , labels : likert_scale }, { prompt : \"I like fruit.\" , name : 'Fruit' , labels : likert_scale }, { prompt : \"I like meat.\" , name : 'Meat' , labels : likert_scale }, ], randomize_question_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-multi-choice/","text":"survey-multi-choice \u00b6 Current version: 1.1.2. See version history . The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options, required, and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The string is prompt/question that will be associated with a group of options (radio buttons). All questions will get presented on the same page (trial). options : Type array, defualt value is undefined . An array of strings. The array contains a set of options to display for an individual question. required : Type boolean, default value is null. The boolean value indicates if a question is required('true') or not ('false'), using the HTML5 required attribute. If this parameter is undefined, the question will be optional. horizontal :Type boolean, default value is false. If true, then the question is centered and the options are displayed horizontally. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as the name of the option label selected (string). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-choice@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-choice.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-choice import surveyMultiChoice from '@jspsych/plugin-survey-multi-choice' ; Examples \u00b6 Vertical Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false } ], }; Open demo in new tab Horizontal Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true , horizontal : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , horizontal : true } ], }; Open demo in new tab","title":"survey-multi-choice"},{"location":"plugins/survey-multi-choice/#survey-multi-choice","text":"Current version: 1.1.2. See version history . The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer.","title":"survey-multi-choice"},{"location":"plugins/survey-multi-choice/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options, required, and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value is undefined . The string is prompt/question that will be associated with a group of options (radio buttons). All questions will get presented on the same page (trial). options : Type array, defualt value is undefined . An array of strings. The array contains a set of options to display for an individual question. required : Type boolean, default value is null. The boolean value indicates if a question is required('true') or not ('false'), using the HTML5 required attribute. If this parameter is undefined, the question will be optional. horizontal :Type boolean, default value is false. If true, then the question is centered and the options are displayed horizontally. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-multi-choice/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. The responses are recorded as the name of the option label selected (string). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-multi-choice/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-choice@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-choice.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-choice import surveyMultiChoice from '@jspsych/plugin-survey-multi-choice' ;","title":"Install"},{"location":"plugins/survey-multi-choice/#examples","text":"Vertical Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false } ], }; Open demo in new tab Horizontal Question Alignment Code Demo var trial = { type : jsPsychSurveyMultiChoice , questions : [ { prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true , horizontal : true }, { prompt : \"Which of the following do you like the least?\" , name : 'FruitDislike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , horizontal : true } ], }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-multi-select/","text":"survey-multi-select \u00b6 Current version: 1.1.2. See version history . The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can select multiple answers. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt/question that will be associated with a group of options (check boxes). All questions will get presented on the same page (trial). options : Type array, default value of undefined . The array contains a set of options to display for an individual question. horizontal : Type boolean, default value of false. If true, the questions are centered and options are displayed horizontally. required : Type boolean, default value of true. If true, then at least one option must be selected. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. required_message string 'You must choose at least one response for this question' Message to display if required response is not given. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the responses are recorded as arrays containing any response options that were selected (strings). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-select@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-select.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-select import surveyMultiSelect from '@jspsych/plugin-survey-multi-select' ; Examples \u00b6 Multiple Questions on a Page Code Demo var trial = { type : jsPsychSurveyMultiSelect , questions : [ { prompt : \"Which of these colors do you like?\" , options : [ \"Red\" , \"Yellow\" , \"Green\" , \"Blue\" , \"Black\" ], horizontal : true , required : true , name : 'Colors' }, { prompt : \"Which of these foods do you like?\" , options : [ \"Apples\" , \"Bananas\" , \"Carrots\" , \"Donuts\" , \"Eggplant\" ], horizontal : true , required : true , name : 'Foods' } ], randomize_question_order : true }; Open demo in new tab","title":"survey-multi-select"},{"location":"plugins/survey-multi-select/#survey-multi-select","text":"Current version: 1.1.2. See version history . The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can select multiple answers.","title":"survey-multi-select"},{"location":"plugins/survey-multi-select/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, options and horizontal parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt/question that will be associated with a group of options (check boxes). All questions will get presented on the same page (trial). options : Type array, default value of undefined . The array contains a set of options to display for an individual question. horizontal : Type boolean, default value of false. If true, the questions are centered and options are displayed horizontally. required : Type boolean, default value of true. If true, then at least one option must be selected. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' Label of the button. required_message string 'You must choose at least one response for this question' Message to display if required response is not given. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-multi-select/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the responses are recorded as arrays containing any response options that were selected (strings). If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-multi-select/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-multi-select@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-multi-select.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-multi-select import surveyMultiSelect from '@jspsych/plugin-survey-multi-select' ;","title":"Install"},{"location":"plugins/survey-multi-select/#examples","text":"Multiple Questions on a Page Code Demo var trial = { type : jsPsychSurveyMultiSelect , questions : [ { prompt : \"Which of these colors do you like?\" , options : [ \"Red\" , \"Yellow\" , \"Green\" , \"Blue\" , \"Black\" ], horizontal : true , required : true , name : 'Colors' }, { prompt : \"Which of these foods do you like?\" , options : [ \"Apples\" , \"Bananas\" , \"Carrots\" , \"Donuts\" , \"Eggplant\" ], horizontal : true , required : true , name : 'Foods' } ], randomize_question_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/survey-text/","text":"survey-text \u00b6 Current version: 1.1.2. See version history . The survey-text plugin displays a set of questions with free response text fields. The participant types in answers. Parameters \u00b6 In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, placeholder, required, rows, and columns parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt for the participant to respond to. Each question gets its own response field. placeholder : Type string, default value of \"\" . The string will create placeholder text in the text field. required : Boolean; if true then the user must enter a response to submit. rows : Type integer, default value of 1. The number of rows for the response text box. columns : Type integer, default value of 40. The number of columns for the response text box. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the response is a string containing whatever text was in the response box when the responses were submitted. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-text@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-text.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-text import surveyText from '@jspsych/plugin-survey-text' ; Examples \u00b6 Single question and response Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'How old are you?' } ] } Open demo in new tab Multiple questions, with an optional placeholder and a required question Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What is your date of birth?' , placeholder : 'mm/dd/yyyy' , required : true }, { prompt : 'What country do you currently live in?' } ] } Open demo in new tab Naming questions to improve readability of the stored data Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What did you eat for breakfast?' , name : 'Breakfast' }, { prompt : 'What did you eat for lunch?' , name : 'Lunch' } ] } Open demo in new tab Using the preamble and a longer textbox response Code Demo var trial = { type : jsPsychSurveyText , preamble : `<img src=\"img/navarro_burst_03.jpg\" style=\"width:400px;\"></img>` , questions : [ { prompt : 'Describe your reaction to the image above' , rows : 5 } ] } The artwork in this demo is by Danielle Navarro Open demo in new tab","title":"survey-text"},{"location":"plugins/survey-text/#survey-text","text":"Current version: 1.1.2. See version history . The survey-text plugin displays a set of questions with free response text fields. The participant types in answers.","title":"survey-text"},{"location":"plugins/survey-text/#parameters","text":"In addition to the 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 questions array undefined An array of objects, each object represents a question that appears on the screen. Each object contains a prompt, placeholder, required, rows, and columns parameter that will be applied to the question. See examples below for further clarification. prompt : Type string, default value of undefined . The string is the prompt for the participant to respond to. Each question gets its own response field. placeholder : Type string, default value of \"\" . The string will create placeholder text in the text field. required : Boolean; if true then the user must enter a response to submit. rows : Type integer, default value of 1. The number of rows for the response text box. columns : Type integer, default value of 40. The number of columns for the response text box. name : Name of the question. Used for storing data. If left undefined then default names ( Q0 , Q1 , ... ) will be used for the questions. randomize_question_order boolean false If true, the display order of questions is randomly determined at the start of the trial. In the data object, Q0 will still refer to the first question in the array, regardless of where it was presented visually. preamble string empty string HTML formatted string to display at the top of the page above all the questions. button_label string 'Continue' The text that appears on the button to finish the trial. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form.","title":"Parameters"},{"location":"plugins/survey-text/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in Q0 , the second in Q1 , and so on. For each question, the response is a string containing whatever text was in the response box when the responses were submitted. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) were submitted. question_order array An array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0] , and the final question was trial.questions[1] . This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/survey-text/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey-text@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey-text.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey-text import surveyText from '@jspsych/plugin-survey-text' ;","title":"Install"},{"location":"plugins/survey-text/#examples","text":"Single question and response Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'How old are you?' } ] } Open demo in new tab Multiple questions, with an optional placeholder and a required question Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What is your date of birth?' , placeholder : 'mm/dd/yyyy' , required : true }, { prompt : 'What country do you currently live in?' } ] } Open demo in new tab Naming questions to improve readability of the stored data Code Demo var trial = { type : jsPsychSurveyText , questions : [ { prompt : 'What did you eat for breakfast?' , name : 'Breakfast' }, { prompt : 'What did you eat for lunch?' , name : 'Lunch' } ] } Open demo in new tab Using the preamble and a longer textbox response Code Demo var trial = { type : jsPsychSurveyText , preamble : `<img src=\"img/navarro_burst_03.jpg\" style=\"width:400px;\"></img>` , questions : [ { prompt : 'Describe your reaction to the image above' , rows : 5 } ] } The artwork in this demo is by Danielle Navarro Open demo in new tab","title":"Examples"},{"location":"plugins/survey/","text":"survey \u00b6 Current version: 0.2.1. See version history . The survey plugin displays one or more questions of different types, on one or more pages that the participant can navigate. This plugin is built on top of the SurveyJS library. The supported question types are: \"drop-down\" for presenting a question with a limited set of options in a drop-down menu. The participant can only select one option. \"likert\" for presenting a prompt along with a discrete rating scale. \"likert-table\" for presenting a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). \"multi-choice\" for presenting a question with a limited set of options. The participant can only select one option. \"multi-select\" for presenting a question with a limited set of options. The participant can select multiple options. \"ranking\" for presenting a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. \"text\" for presenting a question with a free response text field in which the participant can type in an answer. There is also an \"html\" type for adding arbitrary HTML-formatted content (without any associated response field) in the question set. Warning Development on this plugin is ongoing and we plan to incorporate more of the features that SurveyJS provides. Prior to release of version 1.0 of the plugin, we expect the parameters and implementation of this plugin to change. We recommend performing a little bit of extra testing with any experiments that utilize this plugin. CSS \u00b6 This plugin uses an additional stylesheet called survey.css . You can load it via: < link rel = \"stylesheet\" href = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1/css/survey.css\" > If you are using a bundler such as webpack , you can also import it in JavaScript as follows, depending on your bundler configuration: import '@jspsych/plugin-survey/css/survey.css' Parameters \u00b6 In addition to the 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. Survey parameters \u00b6 Parameter Type Default Value Description pages array undefined An array of arrays. Each inner array contains the content for a single page, which is made up of one or more question objects. button_label_next string 'Continue' Label of the button to move forward to the next page, or finish the survey. button_label_previous string 'Back' Label of the button to move to a previous page in the survey. button_label_finish string 'Finish' Label of the button to submit responses. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. show_question_numbers string \"off\" One of: \"on\", \"onPage\", \"off\". If \"on\", questions will be labelled starting with \"1.\" on the first page, and numbering will continue across pages. If \"onPage\", questions will be labelled starting with \"1.\", with separate numbering on each page. If \"off\", no numbers will be added before the question prompts. Note: HTML question types are ignored in automatic numbering. title string null If specified, this text will be shown at the top of the survey pages. required_error string \"Please answer the question.\" Text to display if a required question is not responeded to. required_question_label string \"*\" String to display at the end of required questions. Use an empty string (\"\") if you do not want to add a label to the end of required questions. Question types and parameters \u00b6 Parameters for all question types \u00b6 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 type string undefined The question type. Options are: \"drop-down\", \"html\", \"likert\", \"likert-table\", \"multi-choice\", \"multi-select\", \"ranking\", \"rating\", \"text\". prompt string undefined The prompt/question that will be associated with the question's response field. If the question type is \"html\", then this string is the HTML-formatted string to be displayed. If the question type is \"likert-table\", the prompt is a general question or title presented above the table. required boolean false Whether a response to the question is required ( true ) or not ( false ), using the HTML5 required attribute. name string null Name of the question to be used for storing data. If this parameter is not provided, then default names will be used to identify the questions in the data: P0_Q0 , P0_Q1 , P1_Q0 etc. Question names must be unique across all pages within the trial. Drop-down \u00b6 Present a question with a limited set of options in a drop-down menu. The participant can only select one option. In addition to the parameters for all question types, the drop-down question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). HTML \u00b6 Present arbitrary HTML-formatted content embedded in the list of questions, including text, images, and sounds. There are no response options. The only available parameters are those listed for all question types with a default value of undefined ( type and prompt ) and name . The name parameter is optional and used to identify the question in the data, with a response value of null . The required parameter will be ignored. Likert \u00b6 Present a prompt along with a discrete rating scale. The scale values are presented as buttons that can be selected and de-selected. The scale is specified by the likert_scale_values parameter, which is an array of text labels and associated values, or it is generated using the likert_rating_min / max / stepsize parameters (along with optional maximum/minimum descriptions). In addition to the parameters for all question types, the likert question type also offers 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 likert_scale_values array of objects null Array of objects that defines the rating scale labels and associated values to be stored in the data. Each object defines a single rating option. The objects must have a value property, which is an integer or string value that will be stored as the response in the data. The objects can optionally have a text property, which is a string that will be displayed for that rating option (example: [{value: 1, text: \"A lot\"},{value: 2, text: \"Somewhat\"},{value: 3, text: \"Not much\"}] ). If no text property is specified then the value will be displayed (examples: [{value: 1},{value: 2},{value: 3}] , [{value: \"Yes\"},{value: \"Maybe\"},{value: \"No\"}] ). If provided, this parameter will override the likert_rating_min / max / stepsize parameters. likert_scale_min integer 1 If the likert_scale_values array is not specified, then this parameter will define the minimum scale value. likert_scale_max integer 5 If the likert_scale_values array is not specified, then this parameter will define the maximum scale value. likert_scale_stepsize integer 1 If the likert_scale_values array is not specified, then this parameter will define the step size that should be used for generating rating options between the minimum and maximum values. likert_scale_min_label string null Description for the minimum (first) rating option. If provided, this text will be shown inside the first rating button, before the rating text/value. This parameter is meant for defining the scale's minimum when integer values are used for the rating scale buttons. likert_scale_max_label string null Description for the maximum (last) rating option. If provided, this text will be shown inside the first rating button, after the rating text/value. This parameter is meant for defining the scale's maximum when integer values are used for the rating scale buttons. Likert-table \u00b6 Present a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). In addition to the parameters for all question types, the likert-table question type also offers 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 statements array of objects undefined This array contains one or more objects representing the statements/questions to be presented in the table rows. Each object must have a prompt , which is the statement/question text. The objects can optionally include a name , which is how the statement should be identified in the data. If no name is provided, then the default values of \"S0\", \"S1\" etc. will be used. options array of strings undefined This array contains the set of multiple choice options to be presented in the table columns. randomize_statement_order boolean false If true , the order of statements/questions in the statements array will be randomized. Multi-choice \u00b6 Present a question with a limited set of options. The participant can only select one option. In addition to the parameters for all question types, the multi-choice question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Multi-select \u00b6 Present a question with a limited set of options. The participant can select multiple options. In addition to the parameters for all question types, the multi-select question type also offers 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 options array of strings undefined This array contains the set of options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response array of strings null Array of one or more strings from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Ranking \u00b6 Present a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. It is ideally used with a short list of options (up to about 7 items). It supports mouse responses, touch responses (mobile devices), and keyboard responses (Tab and Shift-Tab to select, and Up/Down arrow keys to re-order). In addition to the parameters for all question types, the ranking question type also offers 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 options array of strings undefined This array contains the set of to-be-ranked options for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response array of strings null The same array of strings used for the options array, but listed in the order that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ). Text \u00b6 Present a question with a free response text field in which the participant can type in an answer. In addition to the parameters for all question types, the text question also offers 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 placeholder string \"\" Placeholder text in the text response field. textbox_rows integer 1 The number of rows (height) for the response text box. textbox_columns integer 40 The number of columns (width) for the response text box. validation string \"\" A regular expression used to validate the response. input_type string \"text\" Type for the HTML <input> element. The input_type parameter must be one of \"color\", \"date\", \"datetime-local\", \"email\", \"month\", \"number\", \"password\", \"range\", \"tel\", \"text\", \"time\", \"url\", \"week\". If the textbox_rows parameter is larger than 1, the input_type parameter will be ignored. The textbox_columns parameter only affects questions with input_type \"email\", \"password\", \"tel\", \"url\", or \"text\". Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response to each question. The object will have a separate key (variable) for each question, with the first question on the first page being recorded in P0_Q0 , the second question on the first page in P0_Q1 , and so on. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. The response type will depend on the question type. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Note that, if any questions use the other option ( add_other_option: true ), then the response value will be the other_option_text (e.g. \"Other\") and any text written in the textbox will be saved as \"(question name)-Comment\". rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey import survey from '@jspsych/plugin-survey' ; Examples \u00b6 Basic single page Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'html' , prompt : 'Please answer the following questions:' , }, { type : 'multi-choice' , prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { type : 'multi-select' , prompt : \"Which of the following do you like?\" , name : 'FruitLike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , } ] ], }; Open demo in new tab Multiple pages, more customization Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'text' , prompt : \"Where were you born?\" , placeholder : 'City, State, Country' , name : 'birthplace' , required : true , }, { type : 'text' , prompt : \"How old are you?\" , name : 'age' , textbox_columns : 5 , required : false , } ], [ { type : 'multi-choice' , prompt : \"What&#39;s your favorite color?\" , options : [ 'blue' , 'yellow' , 'pink' , 'teal' , 'orange' , 'lime green' , 'other' , 'none of these' ], name : 'FavColor' , }, { type : 'multi-select' , prompt : \"Which of these animals do you like? Select all that apply.\" , options : [ 'lion' , 'squirrel' , 'badger' , 'whale' ], option_reorder : 'random' , columns : 0 , name : 'AnimalLike' , } ] ], title : 'My questionnaire' , button_label_next : 'Continue' , button_label_back : 'Previous' , button_label_finish : 'Submit' , show_question_numbers : 'onPage' }; Open demo in new tab Single and multiple item Likert-style scales Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'likert' , prompt : 'I like to eat vegetables.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat fruit.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat meat.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, ], [ { type : 'likert-table' , prompt : ' ' , statements : [ { prompt : 'I like to eat vegetables' , name : 'VeggiesTable' }, { prompt : 'I like to eat fruit' , name : 'FruitTable' }, { prompt : 'I like to eat meat' , name : 'MeatTable' }, ], options : [ 'Strongly Disagree' , 'Disagree' , 'Neutral' , 'Agree' , 'Strongly Agree' ], } ] ], }; Open demo in new tab Response scoring Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : 'During the experiment, are allowed to write things down on paper to help you?' , options : [ \"Yes\" , \"No\" ], correct_response : \"No\" , required : true }, ] ], }; Open demo in new tab Adding data to trial When adding any data to a Survey trial, you should add it via the data parameter at the whole-trial level (not inside the question objects), even if it only relates to one question out of multiple questions/pages contained wihtin the trial. Code Demo const question_info = [ { 'fruit' : 'apples' , 'Q1_prompt' : 'Do you like apples?' , 'Q1_type' : 'regular' }, { 'fruit' : 'bananas' , 'Q1_prompt' : 'Do you NOT like bananas?' , 'Q1_type' : 'reverse' }, ]; const survey = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : jsPsych . timelineVariable ( 'Q1_prompt' ), options : [ 'Yes' , 'No' ], name : 'Q1' }, { type : 'text' , prompt : function () { return `What's your favorite thing about ${ jsPsych . timelineVariable ( 'fruit' ) } ?` ; }, name : 'Q2' } ] ], // Add data at the whole-trial level here data : { 'Q1_prompt' : jsPsych . timelineVariable ( 'Q1_prompt' ), 'Q1_type' : jsPsych . timelineVariable ( 'Q1_type' ), 'fruit' : jsPsych . timelineVariable ( 'fruit' ) }, button_label_finish : 'Continue' }; const survey_procedure = { timeline : [ survey ], timeline_variables : question_info , randomize_order : true }; Open demo in new tab","title":"survey"},{"location":"plugins/survey/#survey","text":"Current version: 0.2.1. See version history . The survey plugin displays one or more questions of different types, on one or more pages that the participant can navigate. This plugin is built on top of the SurveyJS library. The supported question types are: \"drop-down\" for presenting a question with a limited set of options in a drop-down menu. The participant can only select one option. \"likert\" for presenting a prompt along with a discrete rating scale. \"likert-table\" for presenting a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). \"multi-choice\" for presenting a question with a limited set of options. The participant can only select one option. \"multi-select\" for presenting a question with a limited set of options. The participant can select multiple options. \"ranking\" for presenting a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. \"text\" for presenting a question with a free response text field in which the participant can type in an answer. There is also an \"html\" type for adding arbitrary HTML-formatted content (without any associated response field) in the question set. Warning Development on this plugin is ongoing and we plan to incorporate more of the features that SurveyJS provides. Prior to release of version 1.0 of the plugin, we expect the parameters and implementation of this plugin to change. We recommend performing a little bit of extra testing with any experiments that utilize this plugin.","title":"survey"},{"location":"plugins/survey/#css","text":"This plugin uses an additional stylesheet called survey.css . You can load it via: < link rel = \"stylesheet\" href = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1/css/survey.css\" > If you are using a bundler such as webpack , you can also import it in JavaScript as follows, depending on your bundler configuration: import '@jspsych/plugin-survey/css/survey.css'","title":"CSS"},{"location":"plugins/survey/#parameters","text":"In addition to the 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.","title":"Parameters"},{"location":"plugins/survey/#survey-parameters","text":"Parameter Type Default Value Description pages array undefined An array of arrays. Each inner array contains the content for a single page, which is made up of one or more question objects. button_label_next string 'Continue' Label of the button to move forward to the next page, or finish the survey. button_label_previous string 'Back' Label of the button to move to a previous page in the survey. button_label_finish string 'Finish' Label of the button to submit responses. autocomplete boolean false This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. show_question_numbers string \"off\" One of: \"on\", \"onPage\", \"off\". If \"on\", questions will be labelled starting with \"1.\" on the first page, and numbering will continue across pages. If \"onPage\", questions will be labelled starting with \"1.\", with separate numbering on each page. If \"off\", no numbers will be added before the question prompts. Note: HTML question types are ignored in automatic numbering. title string null If specified, this text will be shown at the top of the survey pages. required_error string \"Please answer the question.\" Text to display if a required question is not responeded to. required_question_label string \"*\" String to display at the end of required questions. Use an empty string (\"\") if you do not want to add a label to the end of required questions.","title":"Survey parameters"},{"location":"plugins/survey/#question-types-and-parameters","text":"","title":"Question types and parameters"},{"location":"plugins/survey/#parameters-for-all-question-types","text":"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 type string undefined The question type. Options are: \"drop-down\", \"html\", \"likert\", \"likert-table\", \"multi-choice\", \"multi-select\", \"ranking\", \"rating\", \"text\". prompt string undefined The prompt/question that will be associated with the question's response field. If the question type is \"html\", then this string is the HTML-formatted string to be displayed. If the question type is \"likert-table\", the prompt is a general question or title presented above the table. required boolean false Whether a response to the question is required ( true ) or not ( false ), using the HTML5 required attribute. name string null Name of the question to be used for storing data. If this parameter is not provided, then default names will be used to identify the questions in the data: P0_Q0 , P0_Q1 , P1_Q0 etc. Question names must be unique across all pages within the trial.","title":"Parameters for all question types"},{"location":"plugins/survey/#drop-down","text":"Present a question with a limited set of options in a drop-down menu. The participant can only select one option. In addition to the parameters for all question types, the drop-down question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Drop-down"},{"location":"plugins/survey/#html","text":"Present arbitrary HTML-formatted content embedded in the list of questions, including text, images, and sounds. There are no response options. The only available parameters are those listed for all question types with a default value of undefined ( type and prompt ) and name . The name parameter is optional and used to identify the question in the data, with a response value of null . The required parameter will be ignored.","title":"HTML"},{"location":"plugins/survey/#likert","text":"Present a prompt along with a discrete rating scale. The scale values are presented as buttons that can be selected and de-selected. The scale is specified by the likert_scale_values parameter, which is an array of text labels and associated values, or it is generated using the likert_rating_min / max / stepsize parameters (along with optional maximum/minimum descriptions). In addition to the parameters for all question types, the likert question type also offers 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 likert_scale_values array of objects null Array of objects that defines the rating scale labels and associated values to be stored in the data. Each object defines a single rating option. The objects must have a value property, which is an integer or string value that will be stored as the response in the data. The objects can optionally have a text property, which is a string that will be displayed for that rating option (example: [{value: 1, text: \"A lot\"},{value: 2, text: \"Somewhat\"},{value: 3, text: \"Not much\"}] ). If no text property is specified then the value will be displayed (examples: [{value: 1},{value: 2},{value: 3}] , [{value: \"Yes\"},{value: \"Maybe\"},{value: \"No\"}] ). If provided, this parameter will override the likert_rating_min / max / stepsize parameters. likert_scale_min integer 1 If the likert_scale_values array is not specified, then this parameter will define the minimum scale value. likert_scale_max integer 5 If the likert_scale_values array is not specified, then this parameter will define the maximum scale value. likert_scale_stepsize integer 1 If the likert_scale_values array is not specified, then this parameter will define the step size that should be used for generating rating options between the minimum and maximum values. likert_scale_min_label string null Description for the minimum (first) rating option. If provided, this text will be shown inside the first rating button, before the rating text/value. This parameter is meant for defining the scale's minimum when integer values are used for the rating scale buttons. likert_scale_max_label string null Description for the maximum (last) rating option. If provided, this text will be shown inside the first rating button, after the rating text/value. This parameter is meant for defining the scale's maximum when integer values are used for the rating scale buttons.","title":"Likert"},{"location":"plugins/survey/#likert-table","text":"Present a prompt along with a table of statements/questions (rows) and repeated response options for each statement/question (columns). In addition to the parameters for all question types, the likert-table question type also offers 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 statements array of objects undefined This array contains one or more objects representing the statements/questions to be presented in the table rows. Each object must have a prompt , which is the statement/question text. The objects can optionally include a name , which is how the statement should be identified in the data. If no name is provided, then the default values of \"S0\", \"S1\" etc. will be used. options array of strings undefined This array contains the set of multiple choice options to be presented in the table columns. randomize_statement_order boolean false If true , the order of statements/questions in the statements array will be randomized.","title":"Likert-table"},{"location":"plugins/survey/#multi-choice","text":"Present a question with a limited set of options. The participant can only select one option. In addition to the parameters for all question types, the multi-choice question type also offers 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 options array of strings undefined This array contains the set of multiple choice options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response string null String from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Multi-choice"},{"location":"plugins/survey/#multi-select","text":"Present a question with a limited set of options. The participant can select multiple options. In addition to the parameters for all question types, the multi-select question type also offers 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 options array of strings undefined This array contains the set of options to display for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. columns integer 1 Number of columns to use for displaying the options. If 1 (default), the choices will be displayed in a single column (vertically). If 0, choices will be displayed in a single row (horizontally). Any value greater than 1 can be used to display options in multiple columns. correct_response array of strings null Array of one or more strings from the options array that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Multi-select"},{"location":"plugins/survey/#ranking","text":"Present a question with a limited set of options, where participants respond by dragging and dropping (ordering/ranking) the options. It is ideally used with a short list of options (up to about 7 items). It supports mouse responses, touch responses (mobile devices), and keyboard responses (Tab and Shift-Tab to select, and Up/Down arrow keys to re-order). In addition to the parameters for all question types, the ranking question type also offers 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 options array of strings undefined This array contains the set of to-be-ranked options for the question. option_reorder string \"none\" One of: \"none\", \"asc\", \"desc\", \"random\". If \"none\", the options will be listed in the order given in the options array. If random , the option order will be randomized. If \"asc\" or \"desc\", the options will be presented in ascending or descending order, respectively. correct_response array of strings null The same array of strings used for the options array, but listed in the order that should be considered correct. If specified, the data will include a correct property that indicates whether the response was correct ( true ) or not ( false ).","title":"Ranking"},{"location":"plugins/survey/#text","text":"Present a question with a free response text field in which the participant can type in an answer. In addition to the parameters for all question types, the text question also offers 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 placeholder string \"\" Placeholder text in the text response field. textbox_rows integer 1 The number of rows (height) for the response text box. textbox_columns integer 40 The number of columns (width) for the response text box. validation string \"\" A regular expression used to validate the response. input_type string \"text\" Type for the HTML <input> element. The input_type parameter must be one of \"color\", \"date\", \"datetime-local\", \"email\", \"month\", \"number\", \"password\", \"range\", \"tel\", \"text\", \"time\", \"url\", \"week\". If the textbox_rows parameter is larger than 1, the input_type parameter will be ignored. The textbox_columns parameter only affects questions with input_type \"email\", \"password\", \"tel\", \"url\", or \"text\".","title":"Text"},{"location":"plugins/survey/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response object An object containing the response to each question. The object will have a separate key (variable) for each question, with the first question on the first page being recorded in P0_Q0 , the second question on the first page in P0_Q1 , and so on. If the name parameter is defined for the question, then the response object will use the value of name as the key for each question. The response type will depend on the question type. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Note that, if any questions use the other option ( add_other_option: true ), then the response value will be the other_option_text (e.g. \"Other\") and any text written in the textbox will be saved as \"(question name)-Comment\". rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted.","title":"Data Generated"},{"location":"plugins/survey/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/survey/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-survey@0.2.1\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-survey.js\" >< /script> Using NPM: npm install @jspsych/plugin-survey import survey from '@jspsych/plugin-survey' ;","title":"Install"},{"location":"plugins/survey/#examples","text":"Basic single page Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'html' , prompt : 'Please answer the following questions:' , }, { type : 'multi-choice' , prompt : \"Which of the following do you like the most?\" , name : 'VegetablesLike' , options : [ 'Tomato' , 'Cucumber' , 'Eggplant' , 'Corn' , 'Peas' ], required : true }, { type : 'multi-select' , prompt : \"Which of the following do you like?\" , name : 'FruitLike' , options : [ 'Apple' , 'Banana' , 'Orange' , 'Grape' , 'Strawberry' ], required : false , } ] ], }; Open demo in new tab Multiple pages, more customization Code Demo var trial = { type : jsPsychSurvey , pages : [ [ { type : 'text' , prompt : \"Where were you born?\" , placeholder : 'City, State, Country' , name : 'birthplace' , required : true , }, { type : 'text' , prompt : \"How old are you?\" , name : 'age' , textbox_columns : 5 , required : false , } ], [ { type : 'multi-choice' , prompt : \"What&#39;s your favorite color?\" , options : [ 'blue' , 'yellow' , 'pink' , 'teal' , 'orange' , 'lime green' , 'other' , 'none of these' ], name : 'FavColor' , }, { type : 'multi-select' , prompt : \"Which of these animals do you like? Select all that apply.\" , options : [ 'lion' , 'squirrel' , 'badger' , 'whale' ], option_reorder : 'random' , columns : 0 , name : 'AnimalLike' , } ] ], title : 'My questionnaire' , button_label_next : 'Continue' , button_label_back : 'Previous' , button_label_finish : 'Submit' , show_question_numbers : 'onPage' }; Open demo in new tab Single and multiple item Likert-style scales Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'likert' , prompt : 'I like to eat vegetables.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat fruit.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, { type : 'likert' , prompt : 'I like to eat meat.' , likert_scale_min_label : 'Strongly Disagree' , likert_scale_max_label : 'Strongly Agree' , likert_scale_values : [ { value : 1 }, { value : 2 }, { value : 3 }, { value : 4 }, { value : 5 } ] }, ], [ { type : 'likert-table' , prompt : ' ' , statements : [ { prompt : 'I like to eat vegetables' , name : 'VeggiesTable' }, { prompt : 'I like to eat fruit' , name : 'FruitTable' }, { prompt : 'I like to eat meat' , name : 'MeatTable' }, ], options : [ 'Strongly Disagree' , 'Disagree' , 'Neutral' , 'Agree' , 'Strongly Agree' ], } ] ], }; Open demo in new tab Response scoring Code Demo const trial = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : 'During the experiment, are allowed to write things down on paper to help you?' , options : [ \"Yes\" , \"No\" ], correct_response : \"No\" , required : true }, ] ], }; Open demo in new tab Adding data to trial When adding any data to a Survey trial, you should add it via the data parameter at the whole-trial level (not inside the question objects), even if it only relates to one question out of multiple questions/pages contained wihtin the trial. Code Demo const question_info = [ { 'fruit' : 'apples' , 'Q1_prompt' : 'Do you like apples?' , 'Q1_type' : 'regular' }, { 'fruit' : 'bananas' , 'Q1_prompt' : 'Do you NOT like bananas?' , 'Q1_type' : 'reverse' }, ]; const survey = { type : jsPsychSurvey , pages : [ [ { type : 'multi-choice' , prompt : jsPsych . timelineVariable ( 'Q1_prompt' ), options : [ 'Yes' , 'No' ], name : 'Q1' }, { type : 'text' , prompt : function () { return `What's your favorite thing about ${ jsPsych . timelineVariable ( 'fruit' ) } ?` ; }, name : 'Q2' } ] ], // Add data at the whole-trial level here data : { 'Q1_prompt' : jsPsych . timelineVariable ( 'Q1_prompt' ), 'Q1_type' : jsPsych . timelineVariable ( 'Q1_type' ), 'fruit' : jsPsych . timelineVariable ( 'fruit' ) }, button_label_finish : 'Continue' }; const survey_procedure = { timeline : [ survey ], timeline_variables : question_info , randomize_order : true }; Open demo in new tab","title":"Examples"},{"location":"plugins/video-button-response/","text":"video-button-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video and records responses generated by button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the video has finished playing. The button itself can be customized using HTML formatting. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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. 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. margin_vertical string '0px' Vertical margin of the button(s). margin_horizontal string '8px' Horizontal margin of the button(s). 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 participant 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 participant. 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. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the button choices are enabled and a response is accepted. Once the video has played all the way through, the buttons are enabled and a response is allowed (including while the video is being re-played via on-screen playback controls). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-button-response import videoButtonResponse from '@jspsych/plugin-video-button-response' ; Example \u00b6 Responses disabled until the video is complete Code Demo var trial = { type : jsPsychVideoButtonResponse , stimulus : [ 'video/fish.mp4' ], choices : [ '0-5' , '6-10' , '11-15' , '16-20' , '21-25' , '25+' ], prompt : \"<p>How many different fish are shown in the video?</p>\" , response_allowed_while_playing : false }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-button-response"},{"location":"plugins/video-button-response/#video-button-response","text":"Current version: 1.1.2. See version history . This plugin plays a video and records responses generated by button click. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a button response from being made before the video has finished playing. The button itself can be customized using HTML formatting. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-button-response"},{"location":"plugins/video-button-response/#parameters","text":"In addition to the 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 . 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. 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. margin_vertical string '0px' Vertical margin of the button(s). margin_horizontal string '8px' Horizontal margin of the button(s). 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 participant 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 participant. 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. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the button choices are enabled and a response is accepted. Once the video has played all the way through, the buttons are enabled and a response is allowed (including while the video is being re-played via on-screen playback controls).","title":"Parameters"},{"location":"plugins/video-button-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric Indicates which button the participant pressed. The first button in the choices array is 0, the second is 1, and so on. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/video-button-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-button-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-button-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-button-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-button-response import videoButtonResponse from '@jspsych/plugin-video-button-response' ;","title":"Install"},{"location":"plugins/video-button-response/#example","text":"Responses disabled until the video is complete Code Demo var trial = { type : jsPsychVideoButtonResponse , stimulus : [ 'video/fish.mp4' ], choices : [ '0-5' , '6-10' , '11-15' , '16-20' , '21-25' , '25+' ], prompt : \"<p>How many different fish are shown in the video?</p>\" , response_allowed_while_playing : false }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Example"},{"location":"plugins/video-keyboard-response/","text":"video-keyboard-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video file and records a keyboard response. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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 participant 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 participant. 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-keyboard-response import videoKeyboardResponse from '@jspsych/plugin-video-keyboard-response' ; Examples \u00b6 Show a video and advance to next trial automatically Code Demo var trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/fish.mp4' ], choices : \"NO_KEYS\" , trial_ends_after_video : true }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-keyboard-response"},{"location":"plugins/video-keyboard-response/#video-keyboard-response","text":"Current version: 1.1.2. See version history . This plugin plays a video file and records a keyboard response. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent a keyboard response from being recorded before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-keyboard-response"},{"location":"plugins/video-keyboard-response/#parameters","text":"In addition to the 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 . 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 participant 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 participant. 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 \"ALL_KEYS\" This array contains the key(s) that the participant 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 and this page (event.key column) for more examples. Any key presses that are not listed in the array will be ignored. The default value of \"ALL_KEYS\" means that all keys will be accepted as valid responses. Specifying \"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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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).","title":"Parameters"},{"location":"plugins/video-keyboard-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/video-keyboard-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-keyboard-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-keyboard-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-keyboard-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-keyboard-response import videoKeyboardResponse from '@jspsych/plugin-video-keyboard-response' ;","title":"Install"},{"location":"plugins/video-keyboard-response/#examples","text":"Show a video and advance to next trial automatically Code Demo var trial = { type : jsPsychVideoKeyboardResponse , stimulus : [ 'video/fish.mp4' ], choices : \"NO_KEYS\" , trial_ends_after_video : true }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Examples"},{"location":"plugins/video-slider-response/","text":"video-slider-response \u00b6 Current version: 1.1.2. See version history . This plugin plays a video and allows the participant to respond by dragging a slider. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information. Parameters \u00b6 In addition to the 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 . 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 participant 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 participant. 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. 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. 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. 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 participant must move the slider before clicking the continue button. button_label string 'Continue' Label of the button to end the trial. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the slider is enabled and the trial can end via the next button click. Once the video has played all the way through, the slider is enabled and a response is allowed (including while the video is being re-played via on-screen playback controls). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric The numeric value of the slider. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. slider_start numeric The starting value of the slider. start numeric The start time of the video clip. Simulation Mode \u00b6 In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-slider-response import videoSliderResponse from '@jspsych/plugin-video-slider-response' ; Example \u00b6 Rate enjoyment of a video clip Code Demo var trial = { type : jsPsychVideoSliderResponse , stimulus : [ 'video/fish.mp4' ], labels : [ \"Hated it\" , \"Loved it\" ], prompt : '<p>Please rate your enjoyment of the video clip.</p>' }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"video-slider-response"},{"location":"plugins/video-slider-response/#video-slider-response","text":"Current version: 1.1.2. See version history . This plugin plays a video and allows the participant to respond by dragging a slider. The stimulus can be displayed until a response is given, or for a pre-determined amount of time. The trial can be ended automatically when the participant responds, when the video file has finished playing, or if the participant has failed to respond within a fixed length of time. You can also prevent the slider response from being made before the video has finished playing. Video files can be automatically preloaded by jsPsych using the preload plugin . However, if you are using timeline variables or another dynamic method to specify the video stimulus, you will need to manually preload the videos. Also note that video preloading is disabled when the experiment is running as a file (i.e. opened directly in the browser, rather than through a server), in order to prevent CORS errors - see the section on Running Experiments for more information.","title":"video-slider-response"},{"location":"plugins/video-slider-response/#parameters","text":"In addition to the 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 . 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 participant 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 participant. 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. 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. 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. 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 participant must move the slider before clicking the continue button. button_label string 'Continue' Label of the button to end the trial. 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 participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant'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 participant 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 participant 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 the slider is enabled and the trial can end via the next button click. Once the video has played all the way through, the slider is enabled and a response is allowed (including while the video is being re-played via on-screen playback controls).","title":"Parameters"},{"location":"plugins/video-slider-response/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value response numeric The numeric value of the slider. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant's response. stimulus array The stimulus array. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. slider_start numeric The starting value of the slider. start numeric The start time of the video clip.","title":"Data Generated"},{"location":"plugins/video-slider-response/#simulation-mode","text":"In data-only simulation mode, the response_allowed_while_playing parameter does not currently influence the simulated response time. This is because the audio file is not loaded in data-only mode and therefore the length is unknown. This may change in a future version as we improve the simulation modes.","title":"Simulation Mode"},{"location":"plugins/video-slider-response/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-video-slider-response@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-video-slider-response.js\" >< /script> Using NPM: npm install @jspsych/plugin-video-slider-response import videoSliderResponse from '@jspsych/plugin-video-slider-response' ;","title":"Install"},{"location":"plugins/video-slider-response/#example","text":"Rate enjoyment of a video clip Code Demo var trial = { type : jsPsychVideoSliderResponse , stimulus : [ 'video/fish.mp4' ], labels : [ \"Hated it\" , \"Loved it\" ], prompt : '<p>Please rate your enjoyment of the video clip.</p>' }; Stock Footage provided by rjt98, from Pond5 Open demo in new tab","title":"Example"},{"location":"plugins/virtual-chinrest/","text":"virtual-chinrest \u00b6 Current version: 2.0.2. See version history . This plugin provides a \"virtual chinrest\" that can measure the distance between the participant and the screen. It can also standardize the jsPsych page content to a known physical dimension (e.g., ensuring that a 200px wide stimulus is 2.2cm wide on the participant's monitor). This is based on the work of Li, Joo, Yeatman, and Reinecke (2020) , and the plugin code is a modified version of their implementation . We recommend citing their work in any paper that makes use of this plugin. Citation Li, Q., Joo, S. J., Yeatman, J. D., & Reinecke, K. (2020). Controlling for Participants\u2019 Viewing Distance in Large-Scale, Psychophysical Online Experiments Using a Virtual Chinrest. Scientific Reports, 10 (1), 1-11. doi: 10.1038/s41598-019-57204-1 The plugin works in two phases. Phase 1 . To calculate the pixel-to-cm conversion rate for a participant\u2019s display, participants are asked to place a credit card or other item of the same size on the screen and resize an image until it is the same size as the credit card. Since we know the physical dimensions of the card, we can find the conversion rate for the participant's display. Phase 2 . To measure the participant's viewing distance from their screen we use a blind spot task. Participants are asked to focus on a black square on the screen with their right eye closed, while a red dot repeatedly sweeps from right to left. They press the spacebar on their keyboard whenever they perceive that the red dot has disappeared. This part allows the plugin to use the distance between the black square and the red dot when it disappears from eyesight to estimate how far the participant is from the monitor. This estimation assumes that the blind spot is located at 13.5\u00b0 temporally. Parameters \u00b6 Parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Descripton resize_units string \"none\" Units to resize the jsPsych content to after the trial is over: \"none\" \"cm\" \"inch\" or \"deg\" . If \"none\" , no resizing will be done to the jsPsych content after the virtual-chinrest trial ends. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement, where the units are indicated by resize_units . This is only used when resizing is done after the trial ends (i.e. the resize_units parameter is not \"none\"). adjustment_prompt HTML string \"Click and drag the lower right corner of the image until it is the same size as a credit card held up to the screen. You can use any card that is the same size as a credit card, like a membership card or driver's license. If you do not have access to a real card you can use a ruler to measure the image width to 3.37 inches or 85.6 mm.\" This string can contain HTML markup. Any content here will be displayed below the card stimulus during the resizing phase. adjustment_button_prompt HTML string \"Click here when the image is the correct size\" Content of the button displayed below the card stimulus during the resizing phase. item_path string null Path of the item to be presented in the card stimulus during the resizing phase. If null then no image is shown, and a solid color background is used instead. An example image is available in /examples/img/card.png item_height_mm numeric 53.98 The known height of the physical item (e.g. credit card) to be measured, in mm. item_width_mm numeric 85.6 The known width of the physical item (e.g. credit card) to be measured, in mm. item_init_size numeric 250 The initial size of the card stimulus, in pixels, along its largest dimension. blindspot_reps numeric 5 How many times to measure the blindspot location. If 0 , blindspot will not be detected, and viewing distance and degree data will not be computed. blindspot_prompt HTML string \"Now we will quickly measure how far away you are sitting. Put your left hand on the space bar. Cover your right eye with your right hand. Using your left eye, focus on the black square. Keep your focus on the black square. The red ball will disappear as it moves from right to left. Press the space bar as soon as the ball disappears. Press the space bar when you are ready to begin. This string can contain HTML markup. Any content here will be displayed above the blindspot task . redo_measurement_button_label HTML string 'No, that is not close. Try again' Text for the button on the viewing distance report page to re-do the viewing distance estimate. If the participant click this button, the blindspot task starts again. blindspot_done_prompt HTML string \"Yes\" Text for the button on the viewing distance report page that can be clicked to accept the viewing distance estimate. blindspot_measurements_prompt HTML string 'Remaining measurements: ' Text accompanying the remaining measurements counter that appears below the blindspot task. viewing_distance_report HTML string \"Based on your responses, you are sitting about <span id='distance-estimate' style='font-weight: bold;'></span> from the screen. Does that seem about right?\" Estimated viewing distance data displayed after blindspot task. If \"none\" is given, viewing distance will not be reported to the participant. The HTML span element with id = distance-estimate returns the distance. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Note: The deg data are only returned if viewing distance is estimated with the blindspot method (px2deg, win_height_deg, win_width_deg, item_width_deg). Name Type Value rt numeric The response time in milliseconds. item_height_mm numeric The height in millimeters of the item to be measured. item_width_mm numeric The width in millimeters of the item to be measured item_height_deg numeric Final height of the resizable div container, in degrees. item_width_deg numeric Final width of the resizable div container, in degrees. item_width_px numeric Final width of the resizable div container, in pixels. px2deg numeric Pixels to degrees conversion factor. px2mm numeric Pixels to millimeters conversion factor. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. win_width_deg numeric The interior width of the window in degrees. win_height_deg numeric The interior height of the window in degrees. view_dist_mm numeric Estimated distance to the screen in millimeters. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-virtual-chinrest@2.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-virtual-chinrest.js\" >< /script> Using NPM: npm install @jspsych/plugin-virtual-chinrest import virtualChinrest from '@jspsych/plugin-virtual-chinrest' ; Example \u00b6 Measure distance to screen and pixel ratio; no resizing Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"none\" }; This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on centimeters per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"cm\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should be 10 cm x 10 cm.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on degrees of visual angle per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"deg\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should take up about 10 degrees of visual angle.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab","title":"virtual-chinrest"},{"location":"plugins/virtual-chinrest/#virtual-chinrest","text":"Current version: 2.0.2. See version history . This plugin provides a \"virtual chinrest\" that can measure the distance between the participant and the screen. It can also standardize the jsPsych page content to a known physical dimension (e.g., ensuring that a 200px wide stimulus is 2.2cm wide on the participant's monitor). This is based on the work of Li, Joo, Yeatman, and Reinecke (2020) , and the plugin code is a modified version of their implementation . We recommend citing their work in any paper that makes use of this plugin. Citation Li, Q., Joo, S. J., Yeatman, J. D., & Reinecke, K. (2020). Controlling for Participants\u2019 Viewing Distance in Large-Scale, Psychophysical Online Experiments Using a Virtual Chinrest. Scientific Reports, 10 (1), 1-11. doi: 10.1038/s41598-019-57204-1 The plugin works in two phases. Phase 1 . To calculate the pixel-to-cm conversion rate for a participant\u2019s display, participants are asked to place a credit card or other item of the same size on the screen and resize an image until it is the same size as the credit card. Since we know the physical dimensions of the card, we can find the conversion rate for the participant's display. Phase 2 . To measure the participant's viewing distance from their screen we use a blind spot task. Participants are asked to focus on a black square on the screen with their right eye closed, while a red dot repeatedly sweeps from right to left. They press the spacebar on their keyboard whenever they perceive that the red dot has disappeared. This part allows the plugin to use the distance between the black square and the red dot when it disappears from eyesight to estimate how far the participant is from the monitor. This estimation assumes that the blind spot is located at 13.5\u00b0 temporally.","title":"virtual-chinrest"},{"location":"plugins/virtual-chinrest/#parameters","text":"Parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Descripton resize_units string \"none\" Units to resize the jsPsych content to after the trial is over: \"none\" \"cm\" \"inch\" or \"deg\" . If \"none\" , no resizing will be done to the jsPsych content after the virtual-chinrest trial ends. pixels_per_unit numeric 100 After the scaling factor is applied, this many pixels will equal one unit of measurement, where the units are indicated by resize_units . This is only used when resizing is done after the trial ends (i.e. the resize_units parameter is not \"none\"). adjustment_prompt HTML string \"Click and drag the lower right corner of the image until it is the same size as a credit card held up to the screen. You can use any card that is the same size as a credit card, like a membership card or driver's license. If you do not have access to a real card you can use a ruler to measure the image width to 3.37 inches or 85.6 mm.\" This string can contain HTML markup. Any content here will be displayed below the card stimulus during the resizing phase. adjustment_button_prompt HTML string \"Click here when the image is the correct size\" Content of the button displayed below the card stimulus during the resizing phase. item_path string null Path of the item to be presented in the card stimulus during the resizing phase. If null then no image is shown, and a solid color background is used instead. An example image is available in /examples/img/card.png item_height_mm numeric 53.98 The known height of the physical item (e.g. credit card) to be measured, in mm. item_width_mm numeric 85.6 The known width of the physical item (e.g. credit card) to be measured, in mm. item_init_size numeric 250 The initial size of the card stimulus, in pixels, along its largest dimension. blindspot_reps numeric 5 How many times to measure the blindspot location. If 0 , blindspot will not be detected, and viewing distance and degree data will not be computed. blindspot_prompt HTML string \"Now we will quickly measure how far away you are sitting. Put your left hand on the space bar. Cover your right eye with your right hand. Using your left eye, focus on the black square. Keep your focus on the black square. The red ball will disappear as it moves from right to left. Press the space bar as soon as the ball disappears. Press the space bar when you are ready to begin. This string can contain HTML markup. Any content here will be displayed above the blindspot task . redo_measurement_button_label HTML string 'No, that is not close. Try again' Text for the button on the viewing distance report page to re-do the viewing distance estimate. If the participant click this button, the blindspot task starts again. blindspot_done_prompt HTML string \"Yes\" Text for the button on the viewing distance report page that can be clicked to accept the viewing distance estimate. blindspot_measurements_prompt HTML string 'Remaining measurements: ' Text accompanying the remaining measurements counter that appears below the blindspot task. viewing_distance_report HTML string \"Based on your responses, you are sitting about <span id='distance-estimate' style='font-weight: bold;'></span> from the screen. Does that seem about right?\" Estimated viewing distance data displayed after blindspot task. If \"none\" is given, viewing distance will not be reported to the participant. The HTML span element with id = distance-estimate returns the distance.","title":"Parameters"},{"location":"plugins/virtual-chinrest/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Note: The deg data are only returned if viewing distance is estimated with the blindspot method (px2deg, win_height_deg, win_width_deg, item_width_deg). Name Type Value rt numeric The response time in milliseconds. item_height_mm numeric The height in millimeters of the item to be measured. item_width_mm numeric The width in millimeters of the item to be measured item_height_deg numeric Final height of the resizable div container, in degrees. item_width_deg numeric Final width of the resizable div container, in degrees. item_width_px numeric Final width of the resizable div container, in pixels. px2deg numeric Pixels to degrees conversion factor. px2mm numeric Pixels to millimeters conversion factor. scale_factor numeric Scaling factor that will be applied to the div containing jsPsych content. win_width_deg numeric The interior width of the window in degrees. win_height_deg numeric The interior height of the window in degrees. view_dist_mm numeric Estimated distance to the screen in millimeters.","title":"Data Generated"},{"location":"plugins/virtual-chinrest/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/virtual-chinrest/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-virtual-chinrest@2.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-virtual-chinrest.js\" >< /script> Using NPM: npm install @jspsych/plugin-virtual-chinrest import virtualChinrest from '@jspsych/plugin-virtual-chinrest' ;","title":"Install"},{"location":"plugins/virtual-chinrest/#example","text":"Measure distance to screen and pixel ratio; no resizing Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"none\" }; This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on centimeters per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"cm\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should be 10 cm x 10 cm.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab Resizing based on degrees of visual angle per pixel Code Demo var trial = { type : jsPsychVirtualChinrest , blindspot_reps : 3 , resize_units : \"deg\" , pixels_per_unit : 50 }; var resized_stimulus = { type : jsPsychHtmlButtonResponse , stimulus : ` <p>If the measurements were done correctly, the square below should take up about 10 degrees of visual angle.</p> <div style=\"background-color: black; width: 500px; height: 500px; margin: 20px auto;\"></div> ` , choices : [ 'Continue' ] } This demo requires a larger viewing area to complete. Please open the demo in a new tab Open demo in new tab","title":"Example"},{"location":"plugins/visual-search-circle/","text":"visual-search-circle \u00b6 Current version: 1.1.2. See version history . This plugin presents a customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. Here is an example using normal and backward Ns: Parameters \u00b6 In addition to the parameters available in all plugins , this plugin accepts the following parameters. The set of images to display must be defined in one of two ways: The target , foil and set_size parameters: the combination of these parameters can be used to construct a 'classic' visual search task, where there is a single foil/distractor image that makes up all of the images in the set, with the exception of the target image if it is present. OR The stimuli parameter: this array that can be used to present any arbitrary set of image files, with or without the target image, with any number of different foils/distractors, and with any number of repeated images. The target_present and fixation_image parameters must always be specified. Other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description target string null Path to image file that is the search target. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. foil string null Path to image file that is the foil/distractor. This image will be repeated for all distractors up to the set_size value. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. set_size numeric null How many items should be displayed, including the target when target_present is true . The foil image will be repeated up to this value when target_present is false , or up to set_size - 1 when target_present is true . This parameter must specified when using the target , foil and set_size parameters to define the stimuli set, but should NOT be specified when using the stimuli parameter. stimuli array of images null Array containing all of the image files to be displayed. This parameter must be specified when NOT using the target , foil , and set_size parameters to define the stimuli set. target_present boolean undefined Is the target present? This parameter must always be specified. When using the target , foil and set_size parameters, false means that the foil image will be repeated up to the set_size, and true means that the target will be presented along with the foil image repeated up to set_size - 1. When using the stimuli parameter, this parameter is only used to determine the response accuracy. fixation_image string undefined Path to image file that is a fixation target. This parameter must always be specified. 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 participant is allowed to search before the trial will continue. A value of null will allow the participant to search indefinitely. fixation_duration numeric 1000 How long to show the fixation image for before the search array (in milliseconds). Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value correct boolean True if the participant gave the correct response. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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 array Array where each element 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. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions. Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-visual-search-circle@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-visual-search-circle.js\" >< /script> Using NPM: npm install @jspsych/plugin-visual-search-circle import visualSearchCircle from '@jspsych/plugin-visual-search-circle' ; Examples \u00b6 Identical distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press J if there is a backwards N.</p> <p>Press F if all the Ns are in the normal orientation.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , target : 'img/backwardN.gif' , foil : 'img/normalN.gif' , fixation_image : 'img/fixation.gif' , target_present : true , set_size : 4 } Open demo in new tab Variety of different distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press E if there is an elephant in the group.</p> <p>Press N if there is no elephant in the group.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , stimuli : [ 'img/elephant.png' , 'img/lion.png' , 'img/monkey.png' ], fixation_image : 'img/fixation.gif' , target_present_key : 'e' , target_absent_key : 'n' , target_present : true } Open demo in new tab","title":"visual-search-circle"},{"location":"plugins/visual-search-circle/#visual-search-circle","text":"Current version: 1.1.2. See version history . This plugin presents a customizable visual-search task modelled after Wang, Cavanagh, & Green (1994) . The participant indicates whether or not a target is present among a set of distractors. The stimuli are displayed in a circle, evenly-spaced, equidistant from a fixation point. Here is an example using normal and backward Ns:","title":"visual-search-circle"},{"location":"plugins/visual-search-circle/#parameters","text":"In addition to the parameters available in all plugins , this plugin accepts the following parameters. The set of images to display must be defined in one of two ways: The target , foil and set_size parameters: the combination of these parameters can be used to construct a 'classic' visual search task, where there is a single foil/distractor image that makes up all of the images in the set, with the exception of the target image if it is present. OR The stimuli parameter: this array that can be used to present any arbitrary set of image files, with or without the target image, with any number of different foils/distractors, and with any number of repeated images. The target_present and fixation_image parameters must always be specified. Other parameters can be left unspecified if the default value is acceptable. Parameter Type Default Value Description target string null Path to image file that is the search target. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. foil string null Path to image file that is the foil/distractor. This image will be repeated for all distractors up to the set_size value. This parameter must specified when the stimuli set is defined using the target , foil and set_size parameters, but should NOT be specified when using the stimuli parameter. set_size numeric null How many items should be displayed, including the target when target_present is true . The foil image will be repeated up to this value when target_present is false , or up to set_size - 1 when target_present is true . This parameter must specified when using the target , foil and set_size parameters to define the stimuli set, but should NOT be specified when using the stimuli parameter. stimuli array of images null Array containing all of the image files to be displayed. This parameter must be specified when NOT using the target , foil , and set_size parameters to define the stimuli set. target_present boolean undefined Is the target present? This parameter must always be specified. When using the target , foil and set_size parameters, false means that the foil image will be repeated up to the set_size, and true means that the target will be presented along with the foil image repeated up to set_size - 1. When using the stimuli parameter, this parameter is only used to determine the response accuracy. fixation_image string undefined Path to image file that is a fixation target. This parameter must always be specified. 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 participant is allowed to search before the trial will continue. A value of null will allow the participant to search indefinitely. fixation_duration numeric 1000 How long to show the fixation image for before the search array (in milliseconds).","title":"Parameters"},{"location":"plugins/visual-search-circle/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value correct boolean True if the participant gave the correct response. response string Indicates which key the participant pressed. rt numeric The response time in milliseconds for the participant to make a response. The time is measured from when the stimulus first appears on the screen until the participant'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 array Array where each element 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. This will be encoded as a JSON string when data is saved using the .json() or .csv() functions.","title":"Data Generated"},{"location":"plugins/visual-search-circle/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-visual-search-circle@1.1.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-visual-search-circle.js\" >< /script> Using NPM: npm install @jspsych/plugin-visual-search-circle import visualSearchCircle from '@jspsych/plugin-visual-search-circle' ;","title":"Install"},{"location":"plugins/visual-search-circle/#examples","text":"Identical distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press J if there is a backwards N.</p> <p>Press F if all the Ns are in the normal orientation.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , target : 'img/backwardN.gif' , foil : 'img/normalN.gif' , fixation_image : 'img/fixation.gif' , target_present : true , set_size : 4 } Open demo in new tab Variety of different distractors Code Demo var instructions = { type : jsPsychHtmlButtonResponse , stimulus : `<p>Press E if there is an elephant in the group.</p> <p>Press N if there is no elephant in the group.</p>` , choices : [ 'Continue' ] } var trial = { type : jsPsychVisualSearchCircle , stimuli : [ 'img/elephant.png' , 'img/lion.png' , 'img/monkey.png' ], fixation_image : 'img/fixation.gif' , target_present_key : 'e' , target_absent_key : 'n' , target_present : true } Open demo in new tab","title":"Examples"},{"location":"plugins/webgazer-calibrate/","text":"webgazer-calibrate \u00b6 Current version: 1.0.2. See version history . This plugin can be used to calibrate the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 calibration_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. Specified as a percentage of the screen width and height, from the left and top edge. The default grid is 9 points. calibration_mode string 'click' Can specify click to have participants click on calibration points or view to have participants passively watch calibration points. repetitions_per_point numeric 1 The number of times to repeat the sequence of calibration points. point_size numeric 20 Diameter of the calibration points in pixels. randomize_calibration_order bool false Whether to randomize the order of the calibration points. time_to_saccade numeric 1000 If calibration_mode is set to view , then this is the delay before calibrating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. time_per_point numeric 1000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value No data currently added by this plugin. Use the webgazer-validate plugin to measure the precision and accuracy of calibration. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-calibrate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-calibrate import webgazerCalibrate from '@jspsych/plugin-webgazer-calibrate' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-calibrate"},{"location":"plugins/webgazer-calibrate/#webgazer-calibrate","text":"Current version: 1.0.2. See version history . This plugin can be used to calibrate the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-calibrate"},{"location":"plugins/webgazer-calibrate/#parameters","text":"In addition to the 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 calibration_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. Specified as a percentage of the screen width and height, from the left and top edge. The default grid is 9 points. calibration_mode string 'click' Can specify click to have participants click on calibration points or view to have participants passively watch calibration points. repetitions_per_point numeric 1 The number of times to repeat the sequence of calibration points. point_size numeric 20 Diameter of the calibration points in pixels. randomize_calibration_order bool false Whether to randomize the order of the calibration points. time_to_saccade numeric 1000 If calibration_mode is set to view , then this is the delay before calibrating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. time_per_point numeric 1000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked.","title":"Parameters"},{"location":"plugins/webgazer-calibrate/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value No data currently added by this plugin. Use the webgazer-validate plugin to measure the precision and accuracy of calibration.","title":"Data Generated"},{"location":"plugins/webgazer-calibrate/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-calibrate/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-calibrate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-calibrate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-calibrate import webgazerCalibrate from '@jspsych/plugin-webgazer-calibrate' ;","title":"Install"},{"location":"plugins/webgazer-calibrate/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"plugins/webgazer-init-camera/","text":"webgazer-init-camera \u00b6 Current version: 1.0.2. See version history . This plugin initializes the camera and helps the participant center their face in the camera view for using the the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 instructions string too long to put here Instructions for the participant to follow. button_text string Continue The text for the button that participants click to end the trial. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value load_time numeric The time it took for webgazer to initialize. This can be a long time in some situations, so this value is recorded for troubleshooting when participants are reporting difficulty. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-init-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-init-camera import webgazerInitCamera from '@jspsych/plugin-webgazer-init-camera' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-init-camera"},{"location":"plugins/webgazer-init-camera/#webgazer-init-camera","text":"Current version: 1.0.2. See version history . This plugin initializes the camera and helps the participant center their face in the camera view for using the the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-init-camera"},{"location":"plugins/webgazer-init-camera/#parameters","text":"In addition to the 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 instructions string too long to put here Instructions for the participant to follow. button_text string Continue The text for the button that participants click to end the trial.","title":"Parameters"},{"location":"plugins/webgazer-init-camera/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value load_time numeric The time it took for webgazer to initialize. This can be a long time in some situations, so this value is recorded for troubleshooting when participants are reporting difficulty.","title":"Data Generated"},{"location":"plugins/webgazer-init-camera/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-init-camera/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-init-camera@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-init-camera.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-init-camera import webgazerInitCamera from '@jspsych/plugin-webgazer-init-camera' ;","title":"Install"},{"location":"plugins/webgazer-init-camera/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"plugins/webgazer-validate/","text":"webgazer-validate \u00b6 Current version: 1.0.2. See version history . This plugin can be used to measure the accuracy and precision of gaze predictions made by the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview . Parameters \u00b6 In addition to the 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 validation_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. The default grid is 9 points. Meaning of coordinates controlled by validation_point_coordinates parameter. validation_point_coordinates string 'percent' Can specify percent to have validation point coordinates specified in percentage of screen width and height, or center-offset-pixels to specify each point as the distance in pixels from the center of the screen. roi_radius numeric 200 Tolerance around the validation point in pixels when calculating the percent of gaze measurements within the acceptable range. randomize_validation_order bool false Whether to randomize the order of the validation points. time_to_saccade numeric 1000 The delay before validating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. validation_duration numeric 2000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. point_size numeric 20 Diameter of the validation points in pixels. show_validation_data bool false If true then a visualization of the validation data will be shown on the screen after the validation is complete. This will show each measured gaze location color coded by whether it is within the roi_radius of the target point. This is mainly intended for testing and debugging. Data Generated \u00b6 In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value raw_gaze array Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of {x,y,dx,dy} values specifying the absolute x and y pixels, as well as the distance from the target for that gaze point. percent_in_roi array The percentage of samples within the roi_radius for each validation point. average_offset array The average x and y distance from each validation point, plus the median distance r of the points from this average offset. samples_per_sec numeric The average number of samples per second. Calculated by finding samples per second for each point and then averaging these estimates together. validation_points array The list of validation points, in the order that they appeared. Simulation Mode \u00b6 This plugin does not yet support simulation mode . Install \u00b6 Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-validate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-validate import webgazerValidate from '@jspsych/plugin-webgazer-validate' ; Example \u00b6 Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"webgazer-validate"},{"location":"plugins/webgazer-validate/#webgazer-validate","text":"Current version: 1.0.2. See version history . This plugin can be used to measure the accuracy and precision of gaze predictions made by the WebGazer extension . For a narrative description of eye tracking with jsPsych, see the eye tracking overview .","title":"webgazer-validate"},{"location":"plugins/webgazer-validate/#parameters","text":"In addition to the 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 validation_points array [[10,10], [10,50], [10,90], [50,10], [50,50], [50,90], [90,10], [90,50], [90,90]] Array of points in [x,y] coordinates. The default grid is 9 points. Meaning of coordinates controlled by validation_point_coordinates parameter. validation_point_coordinates string 'percent' Can specify percent to have validation point coordinates specified in percentage of screen width and height, or center-offset-pixels to specify each point as the distance in pixels from the center of the screen. roi_radius numeric 200 Tolerance around the validation point in pixels when calculating the percent of gaze measurements within the acceptable range. randomize_validation_order bool false Whether to randomize the order of the validation points. time_to_saccade numeric 1000 The delay before validating after showing a point. Gives the participant time to fixate on the new target before assuming that the participant is looking at the target. validation_duration numeric 2000 If calibration_mode is set to view , then this is the length of time to show a point while calibrating. Note that if click calibration is used then the point will remain on the screen until clicked. point_size numeric 20 Diameter of the validation points in pixels. show_validation_data bool false If true then a visualization of the validation data will be shown on the screen after the validation is complete. This will show each measured gaze location color coded by whether it is within the roi_radius of the target point. This is mainly intended for testing and debugging.","title":"Parameters"},{"location":"plugins/webgazer-validate/#data-generated","text":"In addition to the default data collected by all plugins , this plugin collects the following data for each trial. Name Type Value raw_gaze array Raw gaze data for the trial. The array will contain a nested array for each validation point. Within each nested array will be a list of {x,y,dx,dy} values specifying the absolute x and y pixels, as well as the distance from the target for that gaze point. percent_in_roi array The percentage of samples within the roi_radius for each validation point. average_offset array The average x and y distance from each validation point, plus the median distance r of the points from this average offset. samples_per_sec numeric The average number of samples per second. Calculated by finding samples per second for each point and then averaging these estimates together. validation_points array The list of validation points, in the order that they appeared.","title":"Data Generated"},{"location":"plugins/webgazer-validate/#simulation-mode","text":"This plugin does not yet support simulation mode .","title":"Simulation Mode"},{"location":"plugins/webgazer-validate/#install","text":"Using the CDN-hosted JavaScript file: < script src = \"https://unpkg.com/@jspsych/plugin-webgazer-validate@1.0.2\" >< /script> Using the JavaScript file downloaded from a GitHub release dist archive: < script src = \"jspsych/plugin-webgazer-validate.js\" >< /script> Using NPM: npm install @jspsych/plugin-webgazer-validate import webgazerValidate from '@jspsych/plugin-webgazer-validate' ;","title":"Install"},{"location":"plugins/webgazer-validate/#example","text":"Because the eye tracking plugins need to be used in conjunction with each other, please see the example on the eye tracking overview page for an integrated example.","title":"Example"},{"location":"reference/jspsych-data/","text":"jsPsych.data \u00b6 The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins. jsPsych.data.addProperties \u00b6 jsPsych . data . addProperties ( properties ) Parameters \u00b6 Parameter Type Description properties object Object of key: value pairs to add to the data. Return value \u00b6 Returns nothing. Description \u00b6 This method appends a set of properties to every trial in the data object, including trials that have already occurred and trials that have yet to occur. You can use this to record things like the subject ID or condition assignment. Examples \u00b6 Assigning a subject ID and condition code \u00b6 jsPsych . data . addProperties ({ subject : 1 , condition : 'control' }); jsPsych.data.displayData \u00b6 jsPsych . data . displayData ( format ) Parameters \u00b6 Parameter Type Description format string Specifies whether to display the data in 'csv' or 'json' format. Return value \u00b6 Returns nothing. Description \u00b6 Outputs all of the data collected in the experiment to the screen in either JSON or CSV format. This is a useful method for quick debugging when developing an experiment. Examples \u00b6 Using the on_finish callback function to show data at the end of the experiment \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData ( 'csv' ); } }) jsPsych.data.get \u00b6 jsPsych.data.get() Parameters \u00b6 None. Return value \u00b6 Returns the data collection of all data generated by the experiment. Description \u00b6 This function is the standard starting point for accessing the data generated by the experiment. It returns a DataCollection object, which has several methods that can be used to further filter, aggregate, and view the data. These methods are described under the DataCollection section on this page. Example \u00b6 // select all trials var all_data = jsPsych . data . get (); // get csv representation of data and log to console console . log ( all_data . csv ()); jsPsych.data.getDataByTimelineNode \u00b6 jsPsych . data . getDataByTimelineNode ( node_id ) Parameters \u00b6 Parameter Type Description node_id string The id of the TimelineNodes to get data from. Return value \u00b6 Returns a DataCollection of all of the data generated in a specified TimelineNode. Description \u00b6 Get all the data generated by a specified Timeline. Example \u00b6 var current_node_id = jsPsych . getCurrentTimelineNodeID (); var data_from_current_node = jsPsych . data . getDataByTimelineNode ( current_node_id ); jsPsych.data.getInteractionData \u00b6 jsPsych . data . getInteractionData () Parameters \u00b6 None. Return value \u00b6 Returns a DataCollection object with all of the interaction events. Description \u00b6 jsPsych automatically records a few different kinds of user interaction events. blur events occur when the user clicks on another window or tab during the experiment, indicating that they are no longer interacting with the experiment. focus events occur when the user clicks on the experiment window after having clicked somewhere else first (i.e., generated a blur event). fullscreenenter and fullscreenexit events are triggered by the browser entering and exiting fullscreen mode. However, fullscreenenter events only occur when the script switches the browser to fullscreen mode, e.g., with the fullscreen plugin . Manually entering fullscreen mode does not trigger this event. fullscreenexit events occur whether the user manually exits fullscreen mode or the script exits fullscreen mode. This method returns the DataCollection containing all interaction events. This is useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form: { type : 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' , trial : 10 , // the trial number when the event happened time : 13042 // total time elapsed since the start of the experiment } Example \u00b6 var interaction_data = jsPsych . data . getInteractionData (); // log data to console in json format console . log ( interaction_data . json ()); jsPsych.data.getLastTimelineData \u00b6 jsPsych . data . getLastTimelineData () Return value \u00b6 Returns a DataCollection. Description \u00b6 Gets all of the data generated in the same timeline as the last trial. Example \u00b6 var lasttimelinedata = jsPsych . data . getLastTimelineData (); jsPsych.data.getLastTrialData \u00b6 jsPsych . data . getLastTrialData () Return value \u00b6 Returns a DataCollection. Description \u00b6 Gets the data collection containing all data generated by the last trial. Example \u00b6 var lasttrialdata = jsPsych . data . getLastTrialData (); jsPsych.data.getURLVariable \u00b6 jsPsych . data . getURLVariable ( var_name ) Parameters \u00b6 Parameter Type Description var_name string Which variable to get the value of. Return value \u00b6 Returns the value of a variable passed in through the query string. Description \u00b6 For extracting a particular variable passed in through a URL query string. Example \u00b6 // if the URL of the page is: experiment.html?subject=1234&condition=test console . log ( jsPsych . data . getURLVariable ( 'subject' )) // logs \"1234\" console . log ( jsPsych . data . getURLVariable ( 'condition' )) // logs \"test\" jsPsych.data.urlVariables \u00b6 jsPsych . data . urlVariables () Return value \u00b6 Returns an object (associative array) of the variables in the URL query string. Description \u00b6 For extracting variables passed in through a URL query string. Example \u00b6 // if the URL of the page is: experiment.html?subject=1234&condition=test var urlvar = jsPsych . data . urlVariables (); console . log ( urlvar . subject ) // logs \"1234\" console . log ( urlvar . condition ) // logs \"test\" jsPsych.data.write \u00b6 jsPsych . data . write ( data_object ) Parameters \u00b6 Parameter Type Description data_object object Object of key: value pairs to store in jsPsych's data storage as a trial. Return value \u00b6 Returns nothing. Description \u00b6 This method is used by jsPsych.finishTrial for writing data. You should probably not use it to add data. Instead use jsPsych.data.addProperties . Example \u00b6 // don't use this! data should only be written once per trial. use jsPsych.finishTrial to save data. var trial_data = { correct : true , rt : 487 } jsPsych . data . write ( trial_data ); DataCollection \u00b6 All data is stored in the DataCollection object. Using methods like jsPsych.data.get() and jsPsych.data.getLastTrialData() return DataCollections containing the experiment data. This is a list of all of the methods that are available to call on a DataCollection object. .addToAll() \u00b6 Adds a set of properties to all items in the DataCollection. Similar to jsPsych.data.addProperties() , except that it can be applied to a subset of the whole DataCollection by filtering down to a smaller DataCollection first. jsPsych . data . get (). addToAll ({ subject_id : 123 , condition : 'control' }); .addToLast() \u00b6 Adds a set of properties to the last trial in the DataCollection. jsPsych . data . get (). addToLast ({ success : true }); .count() \u00b6 Counts the number of trials in the DataCollection. jsPsych . data . get (). count () .csv() \u00b6 Generates a CSV string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). csv ()); .filter() \u00b6 Returns a subset of the DataCollection based on the filter. The filter is an object, and trials are only kept in the returned DataCollection if they contain the key: value pair(s) in the filter object. For example, the code below selects all of the trials with a correct response. var correct_trials = jsPsych . data . get (). filter ({ correct : true }); The object can have multiple key: value pairs, and the trials must match all of them in order to be included in the returned collection. // keep only correct trials from the practice phase var correct_practice_trials = jsPsych . data . get (). filter ({ correct : true , phase : 'practice' }); The filter can also be an array of objects. In this case each object in the array acts as an OR filter. As long as the trial has all the key: value pairs of one of the objects in the array, it will appear in the returned collection. // select trials from block 1 and block 5. var trials = jsPsych . data . get (). filter ([{ block : 1 }, { block : 5 }]); The filter method returns a DataCollection object, so methods can be chained onto a single statement. // count the number of correct trials in block 1 var block_1_correct = jsPsych . data . get (). filter ({ block : 1 , correct : true }). count (); .filterColumns() \u00b6 Selects the set of columns listed in the array. This is the opposite of the .ignore() method. // Get only the subject, rt, and condition entries for each trial. const subset_of_data = jsPsych . data . get (). filterColumns ([ 'subject' , 'rt' , 'condition' ]) .filterCustom() \u00b6 This method is similar to the .filter() method, except that it accepts a function as the filter. The function is passed a single argument, containing the data for a trial. If the function returns true the trial is included in the returned DataCollection. // count the number of trials with a response time greater than 2000ms. var too_long = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 2000 ; }). count () .first() / .last() \u00b6 Returns a DataCollection containing the first/last n trials. If n is greater than the number of trials in the DataCollection, then these functions will return an array of length equal to the number of trials. If there are no trials in the DataCollection, then these functions will return an empty array. If the n argument is omitted, then the functions will use the default value of 1. If n is zero or a negative number, then these functions will throw an error. var first_trial = jsPsych . data . get (). first ( 1 ); var last_trial_with_correct_response = jsPsych . data . get (). filter ({ correct : true }). last ( 1 ); var last_10_trials = jsPsych . data . get (). last ( 10 ); .ignore() \u00b6 Returns a DataCollection with all instances of a particular key removed from the dataset. // log a csv file that does not contain the internal_node_id values for each trial console . log ( jsPsych . data . get (). ignore ( 'internal_node_id' ). csv ()); .join() \u00b6 Appends one DataCollection onto another and returns the combined collection. // get a DataCollection with all trials that are either correct or // have a response time greater than 200ms. var dc1 = jsPsych . data . get (). filter ({ correct : true }); var dc2 = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 200 }); var data = dc1 . join ( dc2 ); .json() \u00b6 Generates a JSON string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). json ()); .localSave() \u00b6 Saves a CSV or JSON file on the computer running the experiment. If conducting an online experiment, this will download the file onto the subject's computer, and is therefore not a recommended data storage solution for online data collection. Warning: This function may not behave correctly in older browsers. Upgrading to the latest version of any major web browser should solve the problem. // first argument is the format, second is the filename. // the format can be either 'csv' or 'json'. jsPsych . data . get (). localSave ( 'csv' , 'mydata.csv' ); .push() \u00b6 Add a new entry to the DataCollection. This method is mostly used internally, and you shouldn't need to call it under normal circumstances. var data = { correct : true , rt : 500 } jsPsych . data . get (). push ( data ); .readOnly() \u00b6 Creates a copy of the DataCollection so that any modification of the values in the DataCollection will not affect the original. // this line edits the rt property of the first trial jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt = 100 ; // readOnly creates a copy that can be modified without affecting the original jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // outputs 100 jsPsych . data . get (). readOnly (). first ( 1 ). values ()[ 0 ]. rt = 200 jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // still outputs 100 .select() \u00b6 Returns a DataColumn object (see documentation below) of a single property from a DataCollection object. var rt_data = jsPsych . data . get (). select ( 'rt' ); rt_data . mean () .uniqueNames() \u00b6 Generates an array of all the unique key names in the set of trials contained in the DataCollection. This is especially useful when setting up a relational database (e.g., MySQL) where the column names need to be specified in advance. console . log ( jsPsych . data . get (). uniqueNames ()); .values() \u00b6 Returns the raw data array associated with the DataCollection. This array is modifiable, so changes to the array and values of objects in the array will change the DataCollection. var raw_data = jsPsych . data . get (). values (); // was response in first trial correct? if ( raw_data [ 0 ]. correct ){ console . log ( 'correct!' ); } else { console . log ( 'incorrect.' ); } DataColumn \u00b6 DataColumn objects represent all the values of a single property in a DataCollection. They are generated by using the .select() method on a DataCollection. Once a DataColumn is generated, the following methods can be used. .all() \u00b6 Checks if all values in the DataColumn return true when passed to a function. The function takes a single argument, which represents one value from the DataColumn. // check if all the response times in the practice phase were under 1000ms jsPsych . data . get (). filter ({ phase : 'practice' }). select ( 'correct' ). all ( function ( x ) { return x < 1000 ; }); .count() \u00b6 Counts the number of values in the DataColumn. // count how many response times there are jsPsych . data . get (). select ( 'rt' ). count (); .frequencies() \u00b6 Counts the number of occurrences of each unique value in the DataColumn. Returns this value as an object, where each key is a unique value and the value of each key is the number of occurrences of that key. // get frequencies of correct and incorrect responses jsPsych . data . get (). select ( 'correct' ). frequencies (); .max() / .min() \u00b6 Returns the maximum or minimum value in a DataColumn. jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). min (); .mean() \u00b6 Returns the average of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). mean (); .median() \u00b6 Returns the median of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). median (); .sd() \u00b6 Returns the standard deviation of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sd (); .subset() \u00b6 Filters the DataColumn to include only values that return true when passed through the specified function. // below results will be less than 200. jsPsych . data . get (). select ( 'rt' ). subset ( function ( x ){ return x < 200 ; }). max (); .sum() \u00b6 Returns the sum of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sum (); .values \u00b6 The raw array of values in the DataColumn. // note that this is not a function call. jsPsych . data . get (). select ( 'rt' ). values ; .variance() \u00b6 Returns the variance of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). variance ();","title":"jsPsych.data"},{"location":"reference/jspsych-data/#jspsychdata","text":"The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins.","title":"jsPsych.data"},{"location":"reference/jspsych-data/#jspsychdataaddproperties","text":"jsPsych . data . addProperties ( properties )","title":"jsPsych.data.addProperties"},{"location":"reference/jspsych-data/#parameters","text":"Parameter Type Description properties object Object of key: value pairs to add to the data.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description","text":"This method appends a set of properties to every trial in the data object, including trials that have already occurred and trials that have yet to occur. You can use this to record things like the subject ID or condition assignment.","title":"Description"},{"location":"reference/jspsych-data/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-data/#assigning-a-subject-id-and-condition-code","text":"jsPsych . data . addProperties ({ subject : 1 , condition : 'control' });","title":"Assigning a subject ID and condition code"},{"location":"reference/jspsych-data/#jspsychdatadisplaydata","text":"jsPsych . data . displayData ( format )","title":"jsPsych.data.displayData"},{"location":"reference/jspsych-data/#parameters_1","text":"Parameter Type Description format string Specifies whether to display the data in 'csv' or 'json' format.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_1","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description_1","text":"Outputs all of the data collected in the experiment to the screen in either JSON or CSV format. This is a useful method for quick debugging when developing an experiment.","title":"Description"},{"location":"reference/jspsych-data/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-data/#using-the-on_finish-callback-function-to-show-data-at-the-end-of-the-experiment","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData ( 'csv' ); } })","title":"Using the on_finish callback function to show data at the end of the experiment"},{"location":"reference/jspsych-data/#jspsychdataget","text":"jsPsych.data.get()","title":"jsPsych.data.get"},{"location":"reference/jspsych-data/#parameters_2","text":"None.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_2","text":"Returns the data collection of all data generated by the experiment.","title":"Return value"},{"location":"reference/jspsych-data/#description_2","text":"This function is the standard starting point for accessing the data generated by the experiment. It returns a DataCollection object, which has several methods that can be used to further filter, aggregate, and view the data. These methods are described under the DataCollection section on this page.","title":"Description"},{"location":"reference/jspsych-data/#example","text":"// select all trials var all_data = jsPsych . data . get (); // get csv representation of data and log to console console . log ( all_data . csv ());","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetdatabytimelinenode","text":"jsPsych . data . getDataByTimelineNode ( node_id )","title":"jsPsych.data.getDataByTimelineNode"},{"location":"reference/jspsych-data/#parameters_3","text":"Parameter Type Description node_id string The id of the TimelineNodes to get data from.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_3","text":"Returns a DataCollection of all of the data generated in a specified TimelineNode.","title":"Return value"},{"location":"reference/jspsych-data/#description_3","text":"Get all the data generated by a specified Timeline.","title":"Description"},{"location":"reference/jspsych-data/#example_1","text":"var current_node_id = jsPsych . getCurrentTimelineNodeID (); var data_from_current_node = jsPsych . data . getDataByTimelineNode ( current_node_id );","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetinteractiondata","text":"jsPsych . data . getInteractionData ()","title":"jsPsych.data.getInteractionData"},{"location":"reference/jspsych-data/#parameters_4","text":"None.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_4","text":"Returns a DataCollection object with all of the interaction events.","title":"Return value"},{"location":"reference/jspsych-data/#description_4","text":"jsPsych automatically records a few different kinds of user interaction events. blur events occur when the user clicks on another window or tab during the experiment, indicating that they are no longer interacting with the experiment. focus events occur when the user clicks on the experiment window after having clicked somewhere else first (i.e., generated a blur event). fullscreenenter and fullscreenexit events are triggered by the browser entering and exiting fullscreen mode. However, fullscreenenter events only occur when the script switches the browser to fullscreen mode, e.g., with the fullscreen plugin . Manually entering fullscreen mode does not trigger this event. fullscreenexit events occur whether the user manually exits fullscreen mode or the script exits fullscreen mode. This method returns the DataCollection containing all interaction events. This is useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form: { type : 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit' , trial : 10 , // the trial number when the event happened time : 13042 // total time elapsed since the start of the experiment }","title":"Description"},{"location":"reference/jspsych-data/#example_2","text":"var interaction_data = jsPsych . data . getInteractionData (); // log data to console in json format console . log ( interaction_data . json ());","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetlasttimelinedata","text":"jsPsych . data . getLastTimelineData ()","title":"jsPsych.data.getLastTimelineData"},{"location":"reference/jspsych-data/#return-value_5","text":"Returns a DataCollection.","title":"Return value"},{"location":"reference/jspsych-data/#description_5","text":"Gets all of the data generated in the same timeline as the last trial.","title":"Description"},{"location":"reference/jspsych-data/#example_3","text":"var lasttimelinedata = jsPsych . data . getLastTimelineData ();","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatagetlasttrialdata","text":"jsPsych . data . getLastTrialData ()","title":"jsPsych.data.getLastTrialData"},{"location":"reference/jspsych-data/#return-value_6","text":"Returns a DataCollection.","title":"Return value"},{"location":"reference/jspsych-data/#description_6","text":"Gets the data collection containing all data generated by the last trial.","title":"Description"},{"location":"reference/jspsych-data/#example_4","text":"var lasttrialdata = jsPsych . data . getLastTrialData ();","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatageturlvariable","text":"jsPsych . data . getURLVariable ( var_name )","title":"jsPsych.data.getURLVariable"},{"location":"reference/jspsych-data/#parameters_5","text":"Parameter Type Description var_name string Which variable to get the value of.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_7","text":"Returns the value of a variable passed in through the query string.","title":"Return value"},{"location":"reference/jspsych-data/#description_7","text":"For extracting a particular variable passed in through a URL query string.","title":"Description"},{"location":"reference/jspsych-data/#example_5","text":"// if the URL of the page is: experiment.html?subject=1234&condition=test console . log ( jsPsych . data . getURLVariable ( 'subject' )) // logs \"1234\" console . log ( jsPsych . data . getURLVariable ( 'condition' )) // logs \"test\"","title":"Example"},{"location":"reference/jspsych-data/#jspsychdataurlvariables","text":"jsPsych . data . urlVariables ()","title":"jsPsych.data.urlVariables"},{"location":"reference/jspsych-data/#return-value_8","text":"Returns an object (associative array) of the variables in the URL query string.","title":"Return value"},{"location":"reference/jspsych-data/#description_8","text":"For extracting variables passed in through a URL query string.","title":"Description"},{"location":"reference/jspsych-data/#example_6","text":"// if the URL of the page is: experiment.html?subject=1234&condition=test var urlvar = jsPsych . data . urlVariables (); console . log ( urlvar . subject ) // logs \"1234\" console . log ( urlvar . condition ) // logs \"test\"","title":"Example"},{"location":"reference/jspsych-data/#jspsychdatawrite","text":"jsPsych . data . write ( data_object )","title":"jsPsych.data.write"},{"location":"reference/jspsych-data/#parameters_6","text":"Parameter Type Description data_object object Object of key: value pairs to store in jsPsych's data storage as a trial.","title":"Parameters"},{"location":"reference/jspsych-data/#return-value_9","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-data/#description_9","text":"This method is used by jsPsych.finishTrial for writing data. You should probably not use it to add data. Instead use jsPsych.data.addProperties .","title":"Description"},{"location":"reference/jspsych-data/#example_7","text":"// don't use this! data should only be written once per trial. use jsPsych.finishTrial to save data. var trial_data = { correct : true , rt : 487 } jsPsych . data . write ( trial_data );","title":"Example"},{"location":"reference/jspsych-data/#datacollection","text":"All data is stored in the DataCollection object. Using methods like jsPsych.data.get() and jsPsych.data.getLastTrialData() return DataCollections containing the experiment data. This is a list of all of the methods that are available to call on a DataCollection object.","title":"DataCollection"},{"location":"reference/jspsych-data/#addtoall","text":"Adds a set of properties to all items in the DataCollection. Similar to jsPsych.data.addProperties() , except that it can be applied to a subset of the whole DataCollection by filtering down to a smaller DataCollection first. jsPsych . data . get (). addToAll ({ subject_id : 123 , condition : 'control' });","title":".addToAll()"},{"location":"reference/jspsych-data/#addtolast","text":"Adds a set of properties to the last trial in the DataCollection. jsPsych . data . get (). addToLast ({ success : true });","title":".addToLast()"},{"location":"reference/jspsych-data/#count","text":"Counts the number of trials in the DataCollection. jsPsych . data . get (). count ()","title":".count()"},{"location":"reference/jspsych-data/#csv","text":"Generates a CSV string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). csv ());","title":".csv()"},{"location":"reference/jspsych-data/#filter","text":"Returns a subset of the DataCollection based on the filter. The filter is an object, and trials are only kept in the returned DataCollection if they contain the key: value pair(s) in the filter object. For example, the code below selects all of the trials with a correct response. var correct_trials = jsPsych . data . get (). filter ({ correct : true }); The object can have multiple key: value pairs, and the trials must match all of them in order to be included in the returned collection. // keep only correct trials from the practice phase var correct_practice_trials = jsPsych . data . get (). filter ({ correct : true , phase : 'practice' }); The filter can also be an array of objects. In this case each object in the array acts as an OR filter. As long as the trial has all the key: value pairs of one of the objects in the array, it will appear in the returned collection. // select trials from block 1 and block 5. var trials = jsPsych . data . get (). filter ([{ block : 1 }, { block : 5 }]); The filter method returns a DataCollection object, so methods can be chained onto a single statement. // count the number of correct trials in block 1 var block_1_correct = jsPsych . data . get (). filter ({ block : 1 , correct : true }). count ();","title":".filter()"},{"location":"reference/jspsych-data/#filtercolumns","text":"Selects the set of columns listed in the array. This is the opposite of the .ignore() method. // Get only the subject, rt, and condition entries for each trial. const subset_of_data = jsPsych . data . get (). filterColumns ([ 'subject' , 'rt' , 'condition' ])","title":".filterColumns()"},{"location":"reference/jspsych-data/#filtercustom","text":"This method is similar to the .filter() method, except that it accepts a function as the filter. The function is passed a single argument, containing the data for a trial. If the function returns true the trial is included in the returned DataCollection. // count the number of trials with a response time greater than 2000ms. var too_long = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 2000 ; }). count ()","title":".filterCustom()"},{"location":"reference/jspsych-data/#first-last","text":"Returns a DataCollection containing the first/last n trials. If n is greater than the number of trials in the DataCollection, then these functions will return an array of length equal to the number of trials. If there are no trials in the DataCollection, then these functions will return an empty array. If the n argument is omitted, then the functions will use the default value of 1. If n is zero or a negative number, then these functions will throw an error. var first_trial = jsPsych . data . get (). first ( 1 ); var last_trial_with_correct_response = jsPsych . data . get (). filter ({ correct : true }). last ( 1 ); var last_10_trials = jsPsych . data . get (). last ( 10 );","title":".first() / .last()"},{"location":"reference/jspsych-data/#ignore","text":"Returns a DataCollection with all instances of a particular key removed from the dataset. // log a csv file that does not contain the internal_node_id values for each trial console . log ( jsPsych . data . get (). ignore ( 'internal_node_id' ). csv ());","title":".ignore()"},{"location":"reference/jspsych-data/#join","text":"Appends one DataCollection onto another and returns the combined collection. // get a DataCollection with all trials that are either correct or // have a response time greater than 200ms. var dc1 = jsPsych . data . get (). filter ({ correct : true }); var dc2 = jsPsych . data . get (). filterCustom ( function ( trial ){ return trial . rt > 200 }); var data = dc1 . join ( dc2 );","title":".join()"},{"location":"reference/jspsych-data/#json","text":"Generates a JSON string representing all of the data in the DataCollection. console . log ( jsPsych . data . get (). json ());","title":".json()"},{"location":"reference/jspsych-data/#localsave","text":"Saves a CSV or JSON file on the computer running the experiment. If conducting an online experiment, this will download the file onto the subject's computer, and is therefore not a recommended data storage solution for online data collection. Warning: This function may not behave correctly in older browsers. Upgrading to the latest version of any major web browser should solve the problem. // first argument is the format, second is the filename. // the format can be either 'csv' or 'json'. jsPsych . data . get (). localSave ( 'csv' , 'mydata.csv' );","title":".localSave()"},{"location":"reference/jspsych-data/#push","text":"Add a new entry to the DataCollection. This method is mostly used internally, and you shouldn't need to call it under normal circumstances. var data = { correct : true , rt : 500 } jsPsych . data . get (). push ( data );","title":".push()"},{"location":"reference/jspsych-data/#readonly","text":"Creates a copy of the DataCollection so that any modification of the values in the DataCollection will not affect the original. // this line edits the rt property of the first trial jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt = 100 ; // readOnly creates a copy that can be modified without affecting the original jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // outputs 100 jsPsych . data . get (). readOnly (). first ( 1 ). values ()[ 0 ]. rt = 200 jsPsych . data . get (). first ( 1 ). values ()[ 0 ]. rt // still outputs 100","title":".readOnly()"},{"location":"reference/jspsych-data/#select","text":"Returns a DataColumn object (see documentation below) of a single property from a DataCollection object. var rt_data = jsPsych . data . get (). select ( 'rt' ); rt_data . mean ()","title":".select()"},{"location":"reference/jspsych-data/#uniquenames","text":"Generates an array of all the unique key names in the set of trials contained in the DataCollection. This is especially useful when setting up a relational database (e.g., MySQL) where the column names need to be specified in advance. console . log ( jsPsych . data . get (). uniqueNames ());","title":".uniqueNames()"},{"location":"reference/jspsych-data/#values","text":"Returns the raw data array associated with the DataCollection. This array is modifiable, so changes to the array and values of objects in the array will change the DataCollection. var raw_data = jsPsych . data . get (). values (); // was response in first trial correct? if ( raw_data [ 0 ]. correct ){ console . log ( 'correct!' ); } else { console . log ( 'incorrect.' ); }","title":".values()"},{"location":"reference/jspsych-data/#datacolumn","text":"DataColumn objects represent all the values of a single property in a DataCollection. They are generated by using the .select() method on a DataCollection. Once a DataColumn is generated, the following methods can be used.","title":"DataColumn"},{"location":"reference/jspsych-data/#all","text":"Checks if all values in the DataColumn return true when passed to a function. The function takes a single argument, which represents one value from the DataColumn. // check if all the response times in the practice phase were under 1000ms jsPsych . data . get (). filter ({ phase : 'practice' }). select ( 'correct' ). all ( function ( x ) { return x < 1000 ; });","title":".all()"},{"location":"reference/jspsych-data/#count_1","text":"Counts the number of values in the DataColumn. // count how many response times there are jsPsych . data . get (). select ( 'rt' ). count ();","title":".count()"},{"location":"reference/jspsych-data/#frequencies","text":"Counts the number of occurrences of each unique value in the DataColumn. Returns this value as an object, where each key is a unique value and the value of each key is the number of occurrences of that key. // get frequencies of correct and incorrect responses jsPsych . data . get (). select ( 'correct' ). frequencies ();","title":".frequencies()"},{"location":"reference/jspsych-data/#max-min","text":"Returns the maximum or minimum value in a DataColumn. jsPsych . data . get (). select ( 'rt' ). max (); jsPsych . data . get (). select ( 'rt' ). min ();","title":".max() / .min()"},{"location":"reference/jspsych-data/#mean","text":"Returns the average of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). mean ();","title":".mean()"},{"location":"reference/jspsych-data/#median","text":"Returns the median of all the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). median ();","title":".median()"},{"location":"reference/jspsych-data/#sd","text":"Returns the standard deviation of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sd ();","title":".sd()"},{"location":"reference/jspsych-data/#subset","text":"Filters the DataColumn to include only values that return true when passed through the specified function. // below results will be less than 200. jsPsych . data . get (). select ( 'rt' ). subset ( function ( x ){ return x < 200 ; }). max ();","title":".subset()"},{"location":"reference/jspsych-data/#sum","text":"Returns the sum of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). sum ();","title":".sum()"},{"location":"reference/jspsych-data/#values_1","text":"The raw array of values in the DataColumn. // note that this is not a function call. jsPsych . data . get (). select ( 'rt' ). values ;","title":".values"},{"location":"reference/jspsych-data/#variance","text":"Returns the variance of the values in a DataColumn. jsPsych . data . get (). select ( 'rt' ). variance ();","title":".variance()"},{"location":"reference/jspsych-pluginAPI/","text":"jsPsych.pluginAPI \u00b6 The pluginAPI module contains functions that are useful when developing plugins. All of the functions are accessible through the pluginAPI object. In this documentation we've divided them up based on different kinds of functionality. Keyboard Input \u00b6 cancelAllKeyboardResponses \u00b6 jsPsych . pluginAPI . cancelAllKeyboardResponses () Parameters \u00b6 None. Return value \u00b6 Returns nothing. Description \u00b6 Cancels all currently active keyboard listeners created by jsPsych.pluginAPI.getKeyboardResponse . Example \u00b6 jsPsych . pluginAPI . cancelAllKeyboardResponses (); cancelKeyboardResponse \u00b6 jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id ) Parameters \u00b6 Parameter Type Description listener_id object The listener_id object generated by the call to jsPsych.pluginAPI.getKeyboardResponse . Return value \u00b6 Returns nothing. Description \u00b6 Cancels a specific keyboard listener created by jsPsych.pluginAPI.getKeyboardResponse . Example \u00b6 // create a persistent keyboard listener var listener_id = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : [ 'p' , 'q' ], rt_method : 'performance' , persist : true , allow_held_key : false }); // cancel keyboard listener jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id ); compareKeys \u00b6 jsPsych . pluginAPI . compareKeys ( key1 , key2 ) Parameters \u00b6 Parameter Type Description key1 string or numeric The representation of a key, either string or keycode key2 string or numeric The representation of a key, either string or keycode Return value \u00b6 Returns true if keycodes or strings refer to the same key, regardless of type. Returns false if the keycodes or strings do not match. Description \u00b6 Compares two keys to see if they are the same, ignoring differences in representational type, and using the appropriate case sensitivity based on the experiment's settings. If case_sensitive_responses is set to false in initJsPsych (the default), then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will match, and this function will return true . If case_sensitive_responses is set to true in initJsPsych , then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will not match, and this function will return false . We recommend using this function to compare keys in all plugin and experiment code, rather than using something like if (response == 'j')... . This is because the response key returned by the jsPsych.pluginAPI.getKeyboardResponse function will be converted to lowercase when case_sensitive_responses is false , and it will match the exact key press representation when case_sensitive_responses is true . Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting, and that you do not need to remember to check key responses against different case versions of the comparison key (e.g. if (response == 'ArrowLeft' || response == 'arrowleft')... ). Examples \u00b6 Basic examples \u00b6 jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns true when case_sensitive_responses is false in initJsPsych jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns false when case_sensitive_responses is true in initJsPsych // also works with numeric key codes (but note that numeric keyCode values are now deprecated) jsPsych . pluginAPI . compareKeys ( 'a' , 65 ); // returns true jsPsych . pluginAPI . compareKeys ( 'space' , 31 ); // returns false Comparing a key response and key parameter value in plugins \u00b6 // this is the callback_function passed to jsPsych.pluginAPI.getKeyboardResponse var after_response = function ( info ) { // score the response by comparing the key that was pressed against the trial's key_answer parameter var correct = jsPsych . pluginAPI . compareKeys ( trial . key_answer , info . key ); //... } Scoring a key response in experiment code \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], prompt : 'Press f for left. Press j for right.' , on_finish : function ( data ){ // score the response by comparing the key that was pressed (data.response) against the // correct response for this trial ('f'), and store reponse accuracy in the trial data if ( jsPsych . pluginAPI . compareKeys ( data . response , 'f' )){ data . correct = true ; } else { data . correct = false ; } } } getKeyboardResponse \u00b6 jsPsych . pluginAPI . getKeyboardResponse ( parameters ) Parameters \u00b6 The method accepts an object of parameter values (see example below). The valid keys for this object are listed in the table below. Parameter Type Description callback_function function The function to execute whenever a valid keyboard response is generated. valid_responses array An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable. rt_method string Indicates which method of recording time to use. The 'performance' method uses calls to performance.now() , which is the standard way of measuring timing in jsPsych. It is supported by up-to-date versions of all the major browsers . The audio method is used in conjuction with an audio_context (set as an additional parameter). This uses the clock time of the audio_context when audio stimuli are being played. audio_context AudioContext object The AudioContext of the audio file that is being played. audio_context_start_time numeric The scheduled time of the sound file in the AudioContext. This will be used as the start time. allow_held_key boolean If true , then responses will be registered from keys that are being held down. If false , then a held key can only register a response the first time that getKeyboardResponse is called for that key. For example, if a participant holds down the A key before the experiment starts, then the first time getKeyboardResponse is called, the A will register as a key press. However, any future calls to getKeyboardResponse will not register the A until the participant releases the key and presses it again. persist boolean If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by jsPsych.pluginAPI.cancelKeyboardResponse or jsPsych.pluginAPI.cancelAllKeyboardResponses . Return value \u00b6 Return an object that uniquely identifies the keyboard listener. This object can be passed to jsPsych.pluginAPI.cancelKeyboardResponse to cancel the keyboard listener. Description \u00b6 Gets a keyboard response from the participant, recording the response time from when the function is first called until a valid response is generated. The keyboard event listener will be bound to the display_element declared in initJsPsych() (or the <body> element if no display_element is specified). This allows jsPsych experiments to be embedded in websites with other content without disrupting the functionality of other UI elements. A valid response triggers the callback_function specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties key and rt . key contains the string representation of the response key, and rt contains the response time. This function uses the .key value of the keyboard event, which is case sensitive . When case_sensitive_responses is false in initJsPsych (the default), this function will convert both the valid_responses strings and the response key to lowercase before comparing them, and it will pass the lowercase version of the response key to the callback_function . For example, if valid_responses is ['a'] , then both 'A' and 'a' will be considered valid key presses, and 'a' will be returned as the response key. When case_sensitive_responses is true in initJsPsych , this function will not convert the case when comparing the valid_responses and response key, and it will not convert the case of the response key that is passed to the callback_function . For example, if valid_responses is ['a'] , then 'a' will be the only valid key press, and 'A' (i.e. 'a' with CapsLock on or Shift held down) will not be accepted. Also, if valid_responses includes multiple letter case options (e.g. \"ALL_KEYS\" ), then you may need to check the response key against both letter cases when scoring etc., e.g. if (response == 'ArrowLeft' || response =='arrowleft') ... . Examples \u00b6 Get a single response from any key \u00b6 var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); } jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : false }); Get a responses from a key until the letter q is pressed \u00b6 var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); if ( jsPsych . pluginAPI . compareKeys ( info . key , 'q' )){ / jsPsych . pluginAPI . cancelKeyboardResponse ( listener ); } } var listener = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : true }); Media \u00b6 getAudioBuffer \u00b6 jsPsych . pluginAPI . getAudioBuffer ( filepath ) Parameters \u00b6 Parameter Type Description filepath string The path to the audio file that was preloaded. Return value \u00b6 Returns a Promise that resolves when the audio file loads. Success handler's parameter will be the audio buffer. If the experiment is running using the WebAudio API it will be an AudioBuffer object. Otherwise, it will be an HTML5 Audio object. The failure handler's parameter is the error generated by preloadAudio . Description \u00b6 Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. It is strongly recommended that you preload audio files before calling this method. This method will load the files if they are not preloaded, but this may result in delays during the experiment as audio is downloaded. Examples \u00b6 HTML 5 Audio \u00b6 jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( audio ){ audio . play (); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) WebAudio API \u00b6 var context = jsPsych . pluginAPI . audioContext (); jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( buffer ){ audio = context . createBufferSource (); audio . buffer = buffer ; audio . connect ( context . destination ); audio . start ( context . currentTime ); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) See the audio-keyboard-response plugin for an example in a fuller context. getAutoPreloadList \u00b6 jsPsych . pluginAPI . getAutoPreloadList ( timeline ) Parameters \u00b6 Parameter Type Description timeline array An array containing the trial object(s) from which a list of media files should be automatically generated. This array can contain the entire experiment timeline, or any individual parts of a larger timeline, such as specific timeline nodes and trial objects. Return value \u00b6 An object with properties for each media type: images , audio , and video . Each property contains an array of the unique files of that media type that were automatically extracted from the timeline. If no files are found in the timeline for a particular media type, then the array will be empty for that type. Description \u00b6 This method is used to automatically generate lists of unique image, audio, and video files from a timeline. It is used by the preload plugin to generate a list of to-be-preloaded files based on the trials passed to the trials parameter and/or the experiment timeline passed to jsPsych.run (when auto_preload is true). It can be used in custom plugins and experiment code to generate a list of audio/image/video files, based on a timeline. This function will only return files from plugin parameters that are marked as parameter type AUDIO / IMAGE / VIDEO , and only when the preload flag of the corresponding parameter definition has not been set to false , and the trial's parameter value is not a function. When a file path is returned to the trial parameter from a function (including the jsPsych.timelineVariable function), or when the file path is embedded in an HTML string, that file will not be detected by the getAutoPreloadList method. In these cases, the file should be preloaded manually. See Media Preloading for more information. Example \u00b6 var audio_trial = { type : jsPsychAudioKeyboardResponse stimulus : 'file.mp3' } var image_trial = { type : jsPsychImageKeyboardResponse stimulus : 'file.png' } var video_trial = { type : jsPsychVideoKeyboardResponse stimulus : 'file.mp4' } var timeline = [ audio_trial , image_trial , video_trial ]; jsPsych . pluginAPI . getAutoPreloadList ( timeline ); getMicrophoneRecorder \u00b6 jsPsych . pluginAPI . getMicrophoneRecorder () Parameters \u00b6 None Return value \u00b6 A MediaRecorder object connected to the MediaStream for the active microphone. Description \u00b6 Provides access to the MediaRecorder created by initializeMicrophoneRecorder() . If no microphone recorder exists, it returns null . Example \u00b6 const recorder = jsPsych . pluginAPI . getMicrophoneRecorder (); initializeMicrophoneRecorder \u00b6 jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream ) Parameters \u00b6 Parameter Type Description stream MediaStream The MediaStream object from an active microphone device. Return value \u00b6 None. Description \u00b6 Generates a MediaRecorder object from provided MediaStream and stores this for access via getMicrophoneRecorder() . Example \u00b6 const stream = await navigator . mediaDevices . getUserMedia ({ audio : { deviceId : mic_id } }); jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream ); preloadAudio \u00b6 jsPsych . pluginAPI . preloadAudio ( files , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description files array An array of audio file paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the files have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload audio files. It is used by the preload plugin, and could be called directly to preload audio files in custom plugins or experiment. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the files are loaded. Thus, it is possible that an audio file would be required for playing before it is done preloading. The callback_complete function will only execute after all the audio files are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / sounds . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of audio files' ); } function startExperiment (){ jsPsych . run ( exp ); } preloadImages \u00b6 jsPsych . pluginAPI . preloadImages ( images , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description images array An array of image paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the images have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload image files. It is used by the preload plugin, and could be called directly to preload image files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the images are loaded. Thus, it is possible that an image would be required for display before it is done preloading. The callback_complete function will only execute after all the images are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / images . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of images' ); } function startExperiment (){ jsPsych . run ( exp ); } preloadVideo \u00b6 jsPsych . pluginAPI . preloadVideo ( video , callback_complete , callback_load , callback_error ) Parameters \u00b6 Parameter Type Description video array An array of video paths to load. The array can be nested (e.g., if videos are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the videos have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error. Return value \u00b6 Returns nothing. Description \u00b6 This function is used to preload video files. It is used by the preload plugin, and could be called directly to preload video files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the videos are loaded. Thus, it is possible that a video would be requested before it is done preloading. The callback_complete function will only execute after all the videos are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below. Examples \u00b6 Basic use \u00b6 var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); } Show progress of loading \u00b6 var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / videos . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of videos' ); } function startExperiment (){ jsPsych . run ( exp ); } Simulation \u00b6 clickTarget \u00b6 jsPsych . pluginAPI . clickTarget ( target , delay ) Parameters \u00b6 Parameter Type Description target Element The DOM element to simulate clicking on. delay number Time to wait in milliseconds. The click will be executed after the delay. Return value \u00b6 None Description \u00b6 Simulates clicking on a DOM element by dispatching three MouseEvents on the target : 'mousedown' , then 'mouseup' , then 'click' . If delay is positive, then the events are scheduled to execute after the delay via setTimeout . Example \u00b6 const target = document . querySelector ( '.jspsych-btn' ); jsPsych . pluginAPI . clickTarget ( target , 500 ); ensureSimulationDataConsistency \u00b6 jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data ) Parameters \u00b6 Parameter Type Description trial object Parameters for the trial, e.g., those passed to the plugin's trial() method. data object An object containing data for the trial. Return value \u00b6 None. The data object is modified in place by this method. Description \u00b6 Performs some basic consistency checks on the data based on the parameters specified in trial . For example, if trial.choices is \"NO_KEYS\" but data.response is a key string then data.response and data.rt are set to null . Example \u00b6 jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data ); fillTextInput \u00b6 jsPsych . pluginAPI . fillTextInput ( target , text , delay ) Parameters \u00b6 Parameter Type Description target HTMLInputElement The input element to fill in with text. text string The text to input. delay number Time to wait in milliseconds. The text will be inserted after the delay. Return value \u00b6 None Description \u00b6 Sets the value of the target HTMLInputElement to equal text . Example \u00b6 const target = document . querySelector ( 'input[type=\"text\"]' ); jsPsych . pluginAPI . fillTextInput ( target , \"hello!\" , 500 ); getValidKey \u00b6 jsPsych . pluginAPI . getValidKey ( choices ) Parameters \u00b6 Parameter Type Description choices \"NO_KEYS\" or \"ALL_KEYS\" or array of strings Representation of the valid keys allowed for a keyboard response used by the getKeyboardResponse method. Return value \u00b6 A valid key given the choices parameter, chosen at random from the possible keys. Description \u00b6 Picks a random key given a set of options. Currently it only picks letters and numbers when choices is \"ALL_KEYS\" . Example \u00b6 const random_key = jsPsych . pluginAPI . getValidKey ( trial . choices ); keyDown \u00b6 jsPsych . pluginAPI . keyDown ( key ) Parameters \u00b6 Parameter Type Description key string The .key property of the corresponding key on the keyboard. Return value \u00b6 None. Description \u00b6 Dispatches a 'keydown' event for the specified key . Example \u00b6 jsPsych . pluginAPI . keyDown ( 'a' ); keyUp \u00b6 jsPsych . pluginAPI . keyUp ( key ) Parameters \u00b6 Parameter Type Description key string The .key property of the corresponding key on the keyboard. Return value \u00b6 None. Description \u00b6 Dispatches a 'keyup' event for the specified key . Example \u00b6 jsPsych . pluginAPI . keyUp ( 'a' ); mergeSimulationData \u00b6 jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ) Parameters \u00b6 Parameter Type Description default_data object An object containing data values for the simulated trial. simulation_options object The simulation_options specified for the trial. Return value \u00b6 An object of data. Description \u00b6 This method merges the default_data with any data specified in simulation_options.data , giving priority to values specified in simulation_options.data . It returns the merged data. Example \u00b6 const default_data = { rt : 500 , response : 'a' } const simulation_options = { data : { rt : 200 } } const data = jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ); data . rt === 200 ; // true Timeouts \u00b6 clearAllTimeouts \u00b6 jsPsych . pluginAPI . clearAllTimeouts () Parameters \u00b6 None. Return value \u00b6 Returns nothing. Description \u00b6 Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout(). setTimeout \u00b6 jsPsych . pluginAPI . setTimeout ( callback , delay ) Parameters \u00b6 Parameter Type Description callback function A function to execute after waiting for delay. delay integer Time to wait in milliseconds. Return value \u00b6 Returns the ID of the setTimeout handle. Description \u00b6 This is simply a call to the standard setTimeout function in JavaScript with the added benefit of registering the setTimeout call in a central list. This is useful for scenarios where some other event (the trial ending, aborting the experiment) should stop the execution of queued timeouts. Example \u00b6 // print the time console . log ( Date . now ()) // print the time 1s later jsPsych . pluginAPI . setTimeout ( function (){ console . log ( Date . now ()) }, 1000 );","title":"jsPsych.pluginAPI"},{"location":"reference/jspsych-pluginAPI/#jspsychpluginapi","text":"The pluginAPI module contains functions that are useful when developing plugins. All of the functions are accessible through the pluginAPI object. In this documentation we've divided them up based on different kinds of functionality.","title":"jsPsych.pluginAPI"},{"location":"reference/jspsych-pluginAPI/#keyboard-input","text":"","title":"Keyboard Input"},{"location":"reference/jspsych-pluginAPI/#cancelallkeyboardresponses","text":"jsPsych . pluginAPI . cancelAllKeyboardResponses ()","title":"cancelAllKeyboardResponses"},{"location":"reference/jspsych-pluginAPI/#parameters","text":"None.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description","text":"Cancels all currently active keyboard listeners created by jsPsych.pluginAPI.getKeyboardResponse .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example","text":"jsPsych . pluginAPI . cancelAllKeyboardResponses ();","title":"Example"},{"location":"reference/jspsych-pluginAPI/#cancelkeyboardresponse","text":"jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id )","title":"cancelKeyboardResponse"},{"location":"reference/jspsych-pluginAPI/#parameters_1","text":"Parameter Type Description listener_id object The listener_id object generated by the call to jsPsych.pluginAPI.getKeyboardResponse .","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_1","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_1","text":"Cancels a specific keyboard listener created by jsPsych.pluginAPI.getKeyboardResponse .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_1","text":"// create a persistent keyboard listener var listener_id = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : [ 'p' , 'q' ], rt_method : 'performance' , persist : true , allow_held_key : false }); // cancel keyboard listener jsPsych . pluginAPI . cancelKeyboardResponse ( listener_id );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#comparekeys","text":"jsPsych . pluginAPI . compareKeys ( key1 , key2 )","title":"compareKeys"},{"location":"reference/jspsych-pluginAPI/#parameters_2","text":"Parameter Type Description key1 string or numeric The representation of a key, either string or keycode key2 string or numeric The representation of a key, either string or keycode","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_2","text":"Returns true if keycodes or strings refer to the same key, regardless of type. Returns false if the keycodes or strings do not match.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_2","text":"Compares two keys to see if they are the same, ignoring differences in representational type, and using the appropriate case sensitivity based on the experiment's settings. If case_sensitive_responses is set to false in initJsPsych (the default), then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will match, and this function will return true . If case_sensitive_responses is set to true in initJsPsych , then the string key comparison will not be case-sensitive, e.g., \"a\" and \"A\" will not match, and this function will return false . We recommend using this function to compare keys in all plugin and experiment code, rather than using something like if (response == 'j')... . This is because the response key returned by the jsPsych.pluginAPI.getKeyboardResponse function will be converted to lowercase when case_sensitive_responses is false , and it will match the exact key press representation when case_sensitive_responses is true . Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting, and that you do not need to remember to check key responses against different case versions of the comparison key (e.g. if (response == 'ArrowLeft' || response == 'arrowleft')... ).","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-examples","text":"jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns true when case_sensitive_responses is false in initJsPsych jsPsych . pluginAPI . compareKeys ( 'a' , 'A' ); // returns false when case_sensitive_responses is true in initJsPsych // also works with numeric key codes (but note that numeric keyCode values are now deprecated) jsPsych . pluginAPI . compareKeys ( 'a' , 65 ); // returns true jsPsych . pluginAPI . compareKeys ( 'space' , 31 ); // returns false","title":"Basic examples"},{"location":"reference/jspsych-pluginAPI/#comparing-a-key-response-and-key-parameter-value-in-plugins","text":"// this is the callback_function passed to jsPsych.pluginAPI.getKeyboardResponse var after_response = function ( info ) { // score the response by comparing the key that was pressed against the trial's key_answer parameter var correct = jsPsych . pluginAPI . compareKeys ( trial . key_answer , info . key ); //... }","title":"Comparing a key response and key parameter value in plugins"},{"location":"reference/jspsych-pluginAPI/#scoring-a-key-response-in-experiment-code","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : '<<<<<' , choices : [ 'f' , 'j' ], prompt : 'Press f for left. Press j for right.' , on_finish : function ( data ){ // score the response by comparing the key that was pressed (data.response) against the // correct response for this trial ('f'), and store reponse accuracy in the trial data if ( jsPsych . pluginAPI . compareKeys ( data . response , 'f' )){ data . correct = true ; } else { data . correct = false ; } } }","title":"Scoring a key response in experiment code"},{"location":"reference/jspsych-pluginAPI/#getkeyboardresponse","text":"jsPsych . pluginAPI . getKeyboardResponse ( parameters )","title":"getKeyboardResponse"},{"location":"reference/jspsych-pluginAPI/#parameters_3","text":"The method accepts an object of parameter values (see example below). The valid keys for this object are listed in the table below. Parameter Type Description callback_function function The function to execute whenever a valid keyboard response is generated. valid_responses array An array of key codes or character strings representing valid responses. Responses not on the list will be ignored. An empty array indicates that all responses are acceptable. rt_method string Indicates which method of recording time to use. The 'performance' method uses calls to performance.now() , which is the standard way of measuring timing in jsPsych. It is supported by up-to-date versions of all the major browsers . The audio method is used in conjuction with an audio_context (set as an additional parameter). This uses the clock time of the audio_context when audio stimuli are being played. audio_context AudioContext object The AudioContext of the audio file that is being played. audio_context_start_time numeric The scheduled time of the sound file in the AudioContext. This will be used as the start time. allow_held_key boolean If true , then responses will be registered from keys that are being held down. If false , then a held key can only register a response the first time that getKeyboardResponse is called for that key. For example, if a participant holds down the A key before the experiment starts, then the first time getKeyboardResponse is called, the A will register as a key press. However, any future calls to getKeyboardResponse will not register the A until the participant releases the key and presses it again. persist boolean If false, then the keyboard listener will only trigger the first time a valid key is pressed. If true, then it will trigger every time a valid key is pressed until it is explicitly cancelled by jsPsych.pluginAPI.cancelKeyboardResponse or jsPsych.pluginAPI.cancelAllKeyboardResponses .","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_3","text":"Return an object that uniquely identifies the keyboard listener. This object can be passed to jsPsych.pluginAPI.cancelKeyboardResponse to cancel the keyboard listener.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_3","text":"Gets a keyboard response from the participant, recording the response time from when the function is first called until a valid response is generated. The keyboard event listener will be bound to the display_element declared in initJsPsych() (or the <body> element if no display_element is specified). This allows jsPsych experiments to be embedded in websites with other content without disrupting the functionality of other UI elements. A valid response triggers the callback_function specified in the parameters. A single argument is passed to the callback function. The argument contains an object with the properties key and rt . key contains the string representation of the response key, and rt contains the response time. This function uses the .key value of the keyboard event, which is case sensitive . When case_sensitive_responses is false in initJsPsych (the default), this function will convert both the valid_responses strings and the response key to lowercase before comparing them, and it will pass the lowercase version of the response key to the callback_function . For example, if valid_responses is ['a'] , then both 'A' and 'a' will be considered valid key presses, and 'a' will be returned as the response key. When case_sensitive_responses is true in initJsPsych , this function will not convert the case when comparing the valid_responses and response key, and it will not convert the case of the response key that is passed to the callback_function . For example, if valid_responses is ['a'] , then 'a' will be the only valid key press, and 'A' (i.e. 'a' with CapsLock on or Shift held down) will not be accepted. Also, if valid_responses includes multiple letter case options (e.g. \"ALL_KEYS\" ), then you may need to check the response key against both letter cases when scoring etc., e.g. if (response == 'ArrowLeft' || response =='arrowleft') ... .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#get-a-single-response-from-any-key","text":"var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); } jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : false });","title":"Get a single response from any key"},{"location":"reference/jspsych-pluginAPI/#get-a-responses-from-a-key-until-the-letter-q-is-pressed","text":"var after_response = function ( info ){ alert ( 'You pressed key ' + info . key + ' after ' + info . rt + 'ms' ); if ( jsPsych . pluginAPI . compareKeys ( info . key , 'q' )){ / jsPsych . pluginAPI . cancelKeyboardResponse ( listener ); } } var listener = jsPsych . pluginAPI . getKeyboardResponse ({ callback_function : after_response , valid_responses : \"ALL_KEYS\" , rt_method : 'performance' , persist : true });","title":"Get a responses from a key until the letter q is pressed"},{"location":"reference/jspsych-pluginAPI/#media","text":"","title":"Media"},{"location":"reference/jspsych-pluginAPI/#getaudiobuffer","text":"jsPsych . pluginAPI . getAudioBuffer ( filepath )","title":"getAudioBuffer"},{"location":"reference/jspsych-pluginAPI/#parameters_4","text":"Parameter Type Description filepath string The path to the audio file that was preloaded.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_4","text":"Returns a Promise that resolves when the audio file loads. Success handler's parameter will be the audio buffer. If the experiment is running using the WebAudio API it will be an AudioBuffer object. Otherwise, it will be an HTML5 Audio object. The failure handler's parameter is the error generated by preloadAudio .","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_4","text":"Gets an AudioBuffer that can be played with the WebAudio API or an Audio object that can be played with HTML5 Audio. It is strongly recommended that you preload audio files before calling this method. This method will load the files if they are not preloaded, but this may result in delays during the experiment as audio is downloaded.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_2","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#html-5-audio","text":"jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( audio ){ audio . play (); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) })","title":"HTML 5 Audio"},{"location":"reference/jspsych-pluginAPI/#webaudio-api","text":"var context = jsPsych . pluginAPI . audioContext (); jsPsych . pluginAPI . getAudioBuffer ( 'my-sound.mp3' ) . then ( function ( buffer ){ audio = context . createBufferSource (); audio . buffer = buffer ; audio . connect ( context . destination ); audio . start ( context . currentTime ); }) . catch ( function ( err ){ console . error ( 'Audio file failed to load' ) }) See the audio-keyboard-response plugin for an example in a fuller context.","title":"WebAudio API"},{"location":"reference/jspsych-pluginAPI/#getautopreloadlist","text":"jsPsych . pluginAPI . getAutoPreloadList ( timeline )","title":"getAutoPreloadList"},{"location":"reference/jspsych-pluginAPI/#parameters_5","text":"Parameter Type Description timeline array An array containing the trial object(s) from which a list of media files should be automatically generated. This array can contain the entire experiment timeline, or any individual parts of a larger timeline, such as specific timeline nodes and trial objects.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_5","text":"An object with properties for each media type: images , audio , and video . Each property contains an array of the unique files of that media type that were automatically extracted from the timeline. If no files are found in the timeline for a particular media type, then the array will be empty for that type.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_5","text":"This method is used to automatically generate lists of unique image, audio, and video files from a timeline. It is used by the preload plugin to generate a list of to-be-preloaded files based on the trials passed to the trials parameter and/or the experiment timeline passed to jsPsych.run (when auto_preload is true). It can be used in custom plugins and experiment code to generate a list of audio/image/video files, based on a timeline. This function will only return files from plugin parameters that are marked as parameter type AUDIO / IMAGE / VIDEO , and only when the preload flag of the corresponding parameter definition has not been set to false , and the trial's parameter value is not a function. When a file path is returned to the trial parameter from a function (including the jsPsych.timelineVariable function), or when the file path is embedded in an HTML string, that file will not be detected by the getAutoPreloadList method. In these cases, the file should be preloaded manually. See Media Preloading for more information.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_2","text":"var audio_trial = { type : jsPsychAudioKeyboardResponse stimulus : 'file.mp3' } var image_trial = { type : jsPsychImageKeyboardResponse stimulus : 'file.png' } var video_trial = { type : jsPsychVideoKeyboardResponse stimulus : 'file.mp4' } var timeline = [ audio_trial , image_trial , video_trial ]; jsPsych . pluginAPI . getAutoPreloadList ( timeline );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#getmicrophonerecorder","text":"jsPsych . pluginAPI . getMicrophoneRecorder ()","title":"getMicrophoneRecorder"},{"location":"reference/jspsych-pluginAPI/#parameters_6","text":"None","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_6","text":"A MediaRecorder object connected to the MediaStream for the active microphone.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_6","text":"Provides access to the MediaRecorder created by initializeMicrophoneRecorder() . If no microphone recorder exists, it returns null .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_3","text":"const recorder = jsPsych . pluginAPI . getMicrophoneRecorder ();","title":"Example"},{"location":"reference/jspsych-pluginAPI/#initializemicrophonerecorder","text":"jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream )","title":"initializeMicrophoneRecorder"},{"location":"reference/jspsych-pluginAPI/#parameters_7","text":"Parameter Type Description stream MediaStream The MediaStream object from an active microphone device.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_7","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_7","text":"Generates a MediaRecorder object from provided MediaStream and stores this for access via getMicrophoneRecorder() .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_4","text":"const stream = await navigator . mediaDevices . getUserMedia ({ audio : { deviceId : mic_id } }); jsPsych . pluginAPI . initializeMicrophoneRecorder ( stream );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#preloadaudio","text":"jsPsych . pluginAPI . preloadAudio ( files , callback_complete , callback_load , callback_error )","title":"preloadAudio"},{"location":"reference/jspsych-pluginAPI/#parameters_8","text":"Parameter Type Description files array An array of audio file paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the files have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_8","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_8","text":"This function is used to preload audio files. It is used by the preload plugin, and could be called directly to preload audio files in custom plugins or experiment. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the files are loaded. Thus, it is possible that an audio file would be required for playing before it is done preloading. The callback_complete function will only execute after all the audio files are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_3","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use","text":"var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading","text":"var sounds = [ 'file1.mp3' , 'file2.mp3' , 'file3.mp3' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadAudio ( sounds , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / sounds . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of audio files' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#preloadimages","text":"jsPsych . pluginAPI . preloadImages ( images , callback_complete , callback_load , callback_error )","title":"preloadImages"},{"location":"reference/jspsych-pluginAPI/#parameters_9","text":"Parameter Type Description images array An array of image paths to load. The array can be nested (e.g., if images are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the images have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_9","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_9","text":"This function is used to preload image files. It is used by the preload plugin, and could be called directly to preload image files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the images are loaded. Thus, it is possible that an image would be required for display before it is done preloading. The callback_complete function will only execute after all the images are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_4","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use_1","text":"var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading_1","text":"var images = [ 'img/file1.png' , 'img/file2.png' , 'img/file3.png' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadImages ( images , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / images . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of images' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#preloadvideo","text":"jsPsych . pluginAPI . preloadVideo ( video , callback_complete , callback_load , callback_error )","title":"preloadVideo"},{"location":"reference/jspsych-pluginAPI/#parameters_10","text":"Parameter Type Description video array An array of video paths to load. The array can be nested (e.g., if videos are in multiple arrays to help sort by condition or task). callback_complete function A function to execute when all the videos have been loaded. callback_load function A function to execute after a single file has been loaded. A single parameter is passed to this function which is the file source (string) that has loaded. callback_error function A function to execute after a single file has produced an error. A single parameter is passed to this function which is the file source (string) that produced the error.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_10","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_10","text":"This function is used to preload video files. It is used by the preload plugin, and could be called directly to preload video files in custom plugins or experiment code. See Media Preloading for more information. It is possible to run this function without specifying a callback function. However, in this case the code will continue executing while the videos are loaded. Thus, it is possible that a video would be requested before it is done preloading. The callback_complete function will only execute after all the videos are loaded, and can be used to control the flow of the experiment (e.g., by starting the experiment in the callback_complete function). The callback_load and callback_error functions are called after each file has either loaded or produced an error, so these functions can also be used to monitor loading progress. See example below.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#examples_5","text":"","title":"Examples"},{"location":"reference/jspsych-pluginAPI/#basic-use_2","text":"var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ){ console . log ( 'file loaded: ' , file ); } function ( file ){ console . log ( 'error loading file: ' , file ); } ); function startExperiment (){ jsPsych . run ( exp ); }","title":"Basic use"},{"location":"reference/jspsych-pluginAPI/#show-progress-of-loading_2","text":"var videos = [ 'vid/file1.mp4' , 'vid/file2.mp4' , 'vid/file3.mp4' ]; var n_loaded = 0 ; jsPsych . pluginAPI . preloadVideo ( videos , function (){ startExperiment (); }, function ( file ) { updateLoadedCount ( file ); }); function updateLoadedCount ( file ){ n_loaded ++ ; var percentcomplete = n_loaded / videos . length * 100 ; // could put something fancier here, like a progress bar // or updating text in the DOM. console . log ( 'Loaded ' + percentcomplete + '% of videos' ); } function startExperiment (){ jsPsych . run ( exp ); }","title":"Show progress of loading"},{"location":"reference/jspsych-pluginAPI/#simulation","text":"","title":"Simulation"},{"location":"reference/jspsych-pluginAPI/#clicktarget","text":"jsPsych . pluginAPI . clickTarget ( target , delay )","title":"clickTarget"},{"location":"reference/jspsych-pluginAPI/#parameters_11","text":"Parameter Type Description target Element The DOM element to simulate clicking on. delay number Time to wait in milliseconds. The click will be executed after the delay.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_11","text":"None","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_11","text":"Simulates clicking on a DOM element by dispatching three MouseEvents on the target : 'mousedown' , then 'mouseup' , then 'click' . If delay is positive, then the events are scheduled to execute after the delay via setTimeout .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_5","text":"const target = document . querySelector ( '.jspsych-btn' ); jsPsych . pluginAPI . clickTarget ( target , 500 );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#ensuresimulationdataconsistency","text":"jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data )","title":"ensureSimulationDataConsistency"},{"location":"reference/jspsych-pluginAPI/#parameters_12","text":"Parameter Type Description trial object Parameters for the trial, e.g., those passed to the plugin's trial() method. data object An object containing data for the trial.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_12","text":"None. The data object is modified in place by this method.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_12","text":"Performs some basic consistency checks on the data based on the parameters specified in trial . For example, if trial.choices is \"NO_KEYS\" but data.response is a key string then data.response and data.rt are set to null .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_6","text":"jsPsych . pluginAPI . ensureSimulationDataConsistency ( trial , data );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#filltextinput","text":"jsPsych . pluginAPI . fillTextInput ( target , text , delay )","title":"fillTextInput"},{"location":"reference/jspsych-pluginAPI/#parameters_13","text":"Parameter Type Description target HTMLInputElement The input element to fill in with text. text string The text to input. delay number Time to wait in milliseconds. The text will be inserted after the delay.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_13","text":"None","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_13","text":"Sets the value of the target HTMLInputElement to equal text .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_7","text":"const target = document . querySelector ( 'input[type=\"text\"]' ); jsPsych . pluginAPI . fillTextInput ( target , \"hello!\" , 500 );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#getvalidkey","text":"jsPsych . pluginAPI . getValidKey ( choices )","title":"getValidKey"},{"location":"reference/jspsych-pluginAPI/#parameters_14","text":"Parameter Type Description choices \"NO_KEYS\" or \"ALL_KEYS\" or array of strings Representation of the valid keys allowed for a keyboard response used by the getKeyboardResponse method.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_14","text":"A valid key given the choices parameter, chosen at random from the possible keys.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_14","text":"Picks a random key given a set of options. Currently it only picks letters and numbers when choices is \"ALL_KEYS\" .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_8","text":"const random_key = jsPsych . pluginAPI . getValidKey ( trial . choices );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#keydown","text":"jsPsych . pluginAPI . keyDown ( key )","title":"keyDown"},{"location":"reference/jspsych-pluginAPI/#parameters_15","text":"Parameter Type Description key string The .key property of the corresponding key on the keyboard.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_15","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_15","text":"Dispatches a 'keydown' event for the specified key .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_9","text":"jsPsych . pluginAPI . keyDown ( 'a' );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#keyup","text":"jsPsych . pluginAPI . keyUp ( key )","title":"keyUp"},{"location":"reference/jspsych-pluginAPI/#parameters_16","text":"Parameter Type Description key string The .key property of the corresponding key on the keyboard.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_16","text":"None.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_16","text":"Dispatches a 'keyup' event for the specified key .","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_10","text":"jsPsych . pluginAPI . keyUp ( 'a' );","title":"Example"},{"location":"reference/jspsych-pluginAPI/#mergesimulationdata","text":"jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options )","title":"mergeSimulationData"},{"location":"reference/jspsych-pluginAPI/#parameters_17","text":"Parameter Type Description default_data object An object containing data values for the simulated trial. simulation_options object The simulation_options specified for the trial.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_17","text":"An object of data.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_17","text":"This method merges the default_data with any data specified in simulation_options.data , giving priority to values specified in simulation_options.data . It returns the merged data.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_11","text":"const default_data = { rt : 500 , response : 'a' } const simulation_options = { data : { rt : 200 } } const data = jsPsych . pluginAPI . mergeSimulationData ( default_data , simulation_options ); data . rt === 200 ; // true","title":"Example"},{"location":"reference/jspsych-pluginAPI/#timeouts","text":"","title":"Timeouts"},{"location":"reference/jspsych-pluginAPI/#clearalltimeouts","text":"jsPsych . pluginAPI . clearAllTimeouts ()","title":"clearAllTimeouts"},{"location":"reference/jspsych-pluginAPI/#parameters_18","text":"None.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_18","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_18","text":"Clears any pending timeouts that were set using jsPsych.pluginAPI.setTimeout().","title":"Description"},{"location":"reference/jspsych-pluginAPI/#settimeout","text":"jsPsych . pluginAPI . setTimeout ( callback , delay )","title":"setTimeout"},{"location":"reference/jspsych-pluginAPI/#parameters_19","text":"Parameter Type Description callback function A function to execute after waiting for delay. delay integer Time to wait in milliseconds.","title":"Parameters"},{"location":"reference/jspsych-pluginAPI/#return-value_19","text":"Returns the ID of the setTimeout handle.","title":"Return value"},{"location":"reference/jspsych-pluginAPI/#description_19","text":"This is simply a call to the standard setTimeout function in JavaScript with the added benefit of registering the setTimeout call in a central list. This is useful for scenarios where some other event (the trial ending, aborting the experiment) should stop the execution of queued timeouts.","title":"Description"},{"location":"reference/jspsych-pluginAPI/#example_12","text":"// print the time console . log ( Date . now ()) // print the time 1s later jsPsych . pluginAPI . setTimeout ( function (){ console . log ( Date . now ()) }, 1000 );","title":"Example"},{"location":"reference/jspsych-randomization/","text":"jsPsych.randomization \u00b6 The jsPsych.randomization module contains methods that are useful for generating random lists of trial variables. jsPsych.randomization.factorial \u00b6 jsPsych . randomization . factorial ( factors , repetitions , unpack ) Parameters \u00b6 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 \u00b6 The return value depends on the unpack parameter. See description of the parameter above, and examples below. Description \u00b6 This method takes a list of factors and their levels, and creates a full factorial design by creating each unique combination of the factors. The returned set of combinations is in a random order. Examples \u00b6 Create full factorial design \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 ); /* output: full_design = [ {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, ] */ Create full factorial design with repeats \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 2 ); /* output: full_design = [ {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, ] */ Create full factorial design, unpacked \u00b6 var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 , true ); /* output: full_design = { stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'], ms_delay: [200, 100, 200, 100] ] */ jsPsych.randomization.randomID \u00b6 jsPsych . randomization . randomID ( length ) Parameters \u00b6 Parameter Type Description length integer The length of the randomly generated ID Return value \u00b6 Returns a string of length length where each character is randomly selected from the numbers 0-9 and all lowercase English letters a-z. Description \u00b6 Generates a random string that is likely to be unique. If length is undefined, then the string length is 32. Example \u00b6 console . log ( jsPsych . randomization . randomID ()); // outputs: \"t7dwz0e713pc8juuaayyfvpkdd9un239\" console . log ( jsPsych . randomization . randomID ( 8 )); // outputs: \"3xtpcbck\" jsPsych.randomization.randomInt \u00b6 jsPsych . randomization . randomInt ( lower , upper ) Parameters \u00b6 Parameter Type Description lower integer The smallest value it is possible to generate upper integer The largest value it is possible to generate Return value \u00b6 An integer Description \u00b6 Generates a random integer from lower to upper Example \u00b6 console . log ( jsPsych . randomization . randomInt ( 2 , 4 )); // outputs: 2 or 3 or 4. jsPsych.randomization.repeat \u00b6 jsPsych . randomization . repeat ( array , repetitions , unpack ) Parameters \u00b6 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 \u00b6 The return value depends on the unpack parameter. See description of the parameter above, and examples below. Description \u00b6 This method takes an array of values and generates a new random order of the array, with the option of repeating each element of the array a specified number of times. If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block. Examples \u00b6 Shuffle an array, no repeats \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 1 ); // output: shuffledArray = [3,2,4,1,5] Shuffle an array with repeats \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [1,3,4,2,2,4,5,1,5,3] Shuffle an array of objects \u00b6 var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [ trial1, trial3, trial3, trial2, trial1, trial2 ] Shuffle an array of objects, with unpack \u00b6 var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; 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: ['p', 'p', 'q', 'p', 'q', 'p'], person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred'] } */ jsPsych.randomization.sampleBernoulli \u00b6 jsPsych . randomization . sampleBernoulli ( p ) Parameters \u00b6 Parameter Type Description p number Probability of sampling 1 Return value \u00b6 Returns 0 with probability 1-p and 1 with probability p . Description \u00b6 Generates a random sample from a Bernoulli distribution. Examples \u00b6 Sample a value \u00b6 if ( jsPsych . randomization . sampleBernoulli ( 0.8 )){ // this happens 80% of the time } else { // this happens 20% of the time } jsPsych.randomization.sampleExGaussian \u00b6 jsPsych . randomization . sampleExGaussian ( mean , standard_deviation , rate , positive = false ) Parameters \u00b6 Parameter Type Description mean number Mean of the normal distribution component of the exGaussian standard_deviation number Standard deviation of the normal distribution component of the exGaussian rate number Rate of the exponential distribution component of the exGaussian positive bool If true sample will be constrained to > 0. Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from an exponentially modified Gaussian distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleExGaussian ( 500 , 100 , 0.01 ); jsPsych.randomization.sampleExponential \u00b6 jsPsych . randomization . sampleExponential ( rate ) Parameters \u00b6 Parameter Type Description rate number Rate of the exponential distribution Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from an exponential distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleExponential ( 0.01 ); jsPsych.randomization.sampleNormal \u00b6 jsPsych . randomization . sampleNormal ( mean , standard_deviation ) Parameters \u00b6 Parameter Type Description mean number Mean of the normal distribution standard_deviation number Standard deviation of the normal distribution Return value \u00b6 A random sample from the distribution Description \u00b6 Generates a random sample from a normal distribution. Examples \u00b6 Sample a value \u00b6 var rand_sample_exg = jsPsych . randomization . sampleNormal ( 500 , 250 ); jsPsych.randomization.sampleWithReplacement \u00b6 jsPsych . randomization . sampleWithReplacement ( array , sampleSize , weights ) Parameters \u00b6 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 \u00b6 An array containing the sample. Description \u00b6 This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the weights . Examples \u00b6 Sample with equal probability \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 ); // output: sample = [3, 1, 2, 2, 5, 1, 4, 3, 1, 5]; Sample with unequal probability \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 , [ 6 , 1 , 1 , 1 , 1 ]); // output: sample = [3, 4, 5, 1, 2, 1, 3, 1, 1, 1]; jsPsych.randomization.sampleWithoutReplacement \u00b6 jsPsych . randomization . sampleWithoutReplacement ( array , sampleSize ) Parameters \u00b6 Parameter Type Description array array The array of values to sample from sampleSize numeric The number of samples to draw Return value \u00b6 An array containing the sample. Description \u00b6 This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array. Examples \u00b6 Sample without replacement \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithoutReplacement ( myArray , 2 ); // output: sample = [3,2]; jsPsych.randomization.setSeed \u00b6 jsPsych . randomization . setSeed ( seed ) Parameters \u00b6 Parameter Type Description seed string A seed for the random number generator Return value \u00b6 Returns the seed value. Description \u00b6 This function will override the behavior of Math.random() to produce a seedable pseudo random number generator. It uses the seedrandom package . Note that calling setSeed() will change how Math.random() behaves for the entire document. If you have non-jsPsych components on the page that use Math.random() they will be affected. Using setSeed() without passing in a seed will generate a random 32-bit seed. The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed. Examples \u00b6 Use a random 32-bit seed and save to data \u00b6 const seed = jsPsych . randomization . setSeed (); jsPsych . data . addProperties ({ rng_seed : seed }); Use your own seed \u00b6 jsPsych . randomization . setSeed ( \"jspsych\" ); jsPsych.randomization.shuffle \u00b6 jsPsych . randomization . shuffle ( array ) Parameters \u00b6 Parameter Type Description array array The array of values to shuffle Return value \u00b6 Returns an array with the same elements as the input array in a random order. Description \u00b6 A simple method for shuffling the order of an array. Examples \u00b6 Shuffle an array \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffle ( myArray ); // output: shuffledArray = [3,2,4,1,5] jsPsych.randomization.shuffleNoRepeats \u00b6 jsPsych . randomization . shuffleNoRepeats ( array , equalityTest ) Parameters \u00b6 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 \u00b6 Returns an array with the same elements as the input array in a random order, with no repeating neighbors. Description \u00b6 Shuffle an array, ensuring that neighboring elements in the array are different. Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang. Examples \u00b6 Basic example \u00b6 var myArray = [ 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffleNoRepeats ( myArray ); // output: shuffledArray = [2, 3, 5, 1, 2, 4, 1, 5, 4, 1, 3, 5, 4, 3, 2] Custom equalityTest \u00b6 var myObjects = [ { color : \"blue\" }, { color : \"red\" }, { color : \"yellow\" }, { color : \"orange\" } ]; var repeatedSet = jsPsych . randomization . repeat ( myObjects , 3 ); var shuffled = jsPsych . randomization . shuffleNoRepeats ( repeatedSet , function ( a , b ) { return a . color === b . color }); // console.log(JSON.stringify(shuffled)) // \"[{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"blue\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"blue\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"blue\"}]\"","title":"jsPsych.randomization"},{"location":"reference/jspsych-randomization/#jspsychrandomization","text":"The jsPsych.randomization module contains methods that are useful for generating random lists of trial variables.","title":"jsPsych.randomization"},{"location":"reference/jspsych-randomization/#jspsychrandomizationfactorial","text":"jsPsych . randomization . factorial ( factors , repetitions , unpack )","title":"jsPsych.randomization.factorial"},{"location":"reference/jspsych-randomization/#parameters","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value","text":"The return value depends on the unpack parameter. See description of the parameter above, and examples below.","title":"Return value"},{"location":"reference/jspsych-randomization/#description","text":"This method takes a list of factors and their levels, and creates a full factorial design by creating each unique combination of the factors. The returned set of combinations is in a random order.","title":"Description"},{"location":"reference/jspsych-randomization/#examples","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#create-full-factorial-design","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 ); /* output: full_design = [ {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, ] */","title":"Create full factorial design"},{"location":"reference/jspsych-randomization/#create-full-factorial-design-with-repeats","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 2 ); /* output: full_design = [ {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'b.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, {stimulus: 'b.jpg', ms_delay: 200}, {stimulus: 'a.jpg', ms_delay: 100}, {stimulus: 'a.jpg', ms_delay: 200}, ] */","title":"Create full factorial design with repeats"},{"location":"reference/jspsych-randomization/#create-full-factorial-design-unpacked","text":"var factors = { stimulus : [ 'a.jpg' , 'b.jpg' ], ms_delay : [ 100 , 200 ] } var full_design = jsPsych . randomization . factorial ( factors , 1 , true ); /* output: full_design = { stimulus: ['a.jpg','b.jpg','b.jpg','a.jpg'], ms_delay: [200, 100, 200, 100] ] */","title":"Create full factorial design, unpacked"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrandomid","text":"jsPsych . randomization . randomID ( length )","title":"jsPsych.randomization.randomID"},{"location":"reference/jspsych-randomization/#parameters_1","text":"Parameter Type Description length integer The length of the randomly generated ID","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_1","text":"Returns a string of length length where each character is randomly selected from the numbers 0-9 and all lowercase English letters a-z.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_1","text":"Generates a random string that is likely to be unique. If length is undefined, then the string length is 32.","title":"Description"},{"location":"reference/jspsych-randomization/#example","text":"console . log ( jsPsych . randomization . randomID ()); // outputs: \"t7dwz0e713pc8juuaayyfvpkdd9un239\" console . log ( jsPsych . randomization . randomID ( 8 )); // outputs: \"3xtpcbck\"","title":"Example"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrandomint","text":"jsPsych . randomization . randomInt ( lower , upper )","title":"jsPsych.randomization.randomInt"},{"location":"reference/jspsych-randomization/#parameters_2","text":"Parameter Type Description lower integer The smallest value it is possible to generate upper integer The largest value it is possible to generate","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_2","text":"An integer","title":"Return value"},{"location":"reference/jspsych-randomization/#description_2","text":"Generates a random integer from lower to upper","title":"Description"},{"location":"reference/jspsych-randomization/#example_1","text":"console . log ( jsPsych . randomization . randomInt ( 2 , 4 )); // outputs: 2 or 3 or 4.","title":"Example"},{"location":"reference/jspsych-randomization/#jspsychrandomizationrepeat","text":"jsPsych . randomization . repeat ( array , repetitions , unpack )","title":"jsPsych.randomization.repeat"},{"location":"reference/jspsych-randomization/#parameters_3","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_3","text":"The return value depends on the unpack parameter. See description of the parameter above, and examples below.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_3","text":"This method takes an array of values and generates a new random order of the array, with the option of repeating each element of the array a specified number of times. If the array elements are objects with the same set of properties, then this method can optionally return a single object where each property is a randomized order of the properties defined in the original set of objects. This is useful for randomizing sets of parameters that are used to define a jsPsych block.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_1","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#shuffle-an-array-no-repeats","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 1 ); // output: shuffledArray = [3,2,4,1,5]","title":"Shuffle an array, no repeats"},{"location":"reference/jspsych-randomization/#shuffle-an-array-with-repeats","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [1,3,4,2,2,4,5,1,5,3]","title":"Shuffle an array with repeats"},{"location":"reference/jspsych-randomization/#shuffle-an-array-of-objects","text":"var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; var shuffledArray = jsPsych . randomization . repeat ( myArray , 2 ); // output: shuffledArray = [ trial1, trial3, trial3, trial2, trial1, trial2 ]","title":"Shuffle an array of objects"},{"location":"reference/jspsych-randomization/#shuffle-an-array-of-objects-with-unpack","text":"var trial1 = { stimulus : 'img/faceA.jpg' , correct_key : 'p' , person_name : 'Joe' } var trial2 = { stimulus : 'img/faceB.jpg' , correct_key : 'p' , person_name : 'Fred' } var trial3 = { stimulus : 'img/faceC.jpg' , correct_key : 'q' , person_name : 'Mary' } var myArray = [ trial1 , trial2 , trial3 ]; 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: ['p', 'p', 'q', 'p', 'q', 'p'], person_name: ['Fred', 'Joe', 'Mary', 'Joe', 'Mary', 'Fred'] } */","title":"Shuffle an array of objects, with unpack"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplebernoulli","text":"jsPsych . randomization . sampleBernoulli ( p )","title":"jsPsych.randomization.sampleBernoulli"},{"location":"reference/jspsych-randomization/#parameters_4","text":"Parameter Type Description p number Probability of sampling 1","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_4","text":"Returns 0 with probability 1-p and 1 with probability p .","title":"Return value"},{"location":"reference/jspsych-randomization/#description_4","text":"Generates a random sample from a Bernoulli distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_2","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value","text":"if ( jsPsych . randomization . sampleBernoulli ( 0.8 )){ // this happens 80% of the time } else { // this happens 20% of the time }","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsampleexgaussian","text":"jsPsych . randomization . sampleExGaussian ( mean , standard_deviation , rate , positive = false )","title":"jsPsych.randomization.sampleExGaussian"},{"location":"reference/jspsych-randomization/#parameters_5","text":"Parameter Type Description mean number Mean of the normal distribution component of the exGaussian standard_deviation number Standard deviation of the normal distribution component of the exGaussian rate number Rate of the exponential distribution component of the exGaussian positive bool If true sample will be constrained to > 0.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_5","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_5","text":"Generates a random sample from an exponentially modified Gaussian distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_3","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_1","text":"var rand_sample_exg = jsPsych . randomization . sampleExGaussian ( 500 , 100 , 0.01 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsampleexponential","text":"jsPsych . randomization . sampleExponential ( rate )","title":"jsPsych.randomization.sampleExponential"},{"location":"reference/jspsych-randomization/#parameters_6","text":"Parameter Type Description rate number Rate of the exponential distribution","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_6","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_6","text":"Generates a random sample from an exponential distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_4","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_2","text":"var rand_sample_exg = jsPsych . randomization . sampleExponential ( 0.01 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplenormal","text":"jsPsych . randomization . sampleNormal ( mean , standard_deviation )","title":"jsPsych.randomization.sampleNormal"},{"location":"reference/jspsych-randomization/#parameters_7","text":"Parameter Type Description mean number Mean of the normal distribution standard_deviation number Standard deviation of the normal distribution","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_7","text":"A random sample from the distribution","title":"Return value"},{"location":"reference/jspsych-randomization/#description_7","text":"Generates a random sample from a normal distribution.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_5","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-a-value_3","text":"var rand_sample_exg = jsPsych . randomization . sampleNormal ( 500 , 250 );","title":"Sample a value"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplewithreplacement","text":"jsPsych . randomization . sampleWithReplacement ( array , sampleSize , weights )","title":"jsPsych.randomization.sampleWithReplacement"},{"location":"reference/jspsych-randomization/#parameters_8","text":"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 .","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_8","text":"An array containing the sample.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_8","text":"This method returns a sample drawn at random from a set of values with replacement. The relative probability of drawing each item can be controlled by specifying the weights .","title":"Description"},{"location":"reference/jspsych-randomization/#examples_6","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-with-equal-probability","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 ); // output: sample = [3, 1, 2, 2, 5, 1, 4, 3, 1, 5];","title":"Sample with equal probability"},{"location":"reference/jspsych-randomization/#sample-with-unequal-probability","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithReplacement ( myArray , 10 , [ 6 , 1 , 1 , 1 , 1 ]); // output: sample = [3, 4, 5, 1, 2, 1, 3, 1, 1, 1];","title":"Sample with unequal probability"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsamplewithoutreplacement","text":"jsPsych . randomization . sampleWithoutReplacement ( array , sampleSize )","title":"jsPsych.randomization.sampleWithoutReplacement"},{"location":"reference/jspsych-randomization/#parameters_9","text":"Parameter Type Description array array The array of values to sample from sampleSize numeric The number of samples to draw","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_9","text":"An array containing the sample.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_9","text":"This method returns a sample drawn at random from a set of values without replacement. The sample size must be less than or equal to the length of the array.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_7","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#sample-without-replacement","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var sample = jsPsych . randomization . sampleWithoutReplacement ( myArray , 2 ); // output: sample = [3,2];","title":"Sample without replacement"},{"location":"reference/jspsych-randomization/#jspsychrandomizationsetseed","text":"jsPsych . randomization . setSeed ( seed )","title":"jsPsych.randomization.setSeed"},{"location":"reference/jspsych-randomization/#parameters_10","text":"Parameter Type Description seed string A seed for the random number generator","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_10","text":"Returns the seed value.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_10","text":"This function will override the behavior of Math.random() to produce a seedable pseudo random number generator. It uses the seedrandom package . Note that calling setSeed() will change how Math.random() behaves for the entire document. If you have non-jsPsych components on the page that use Math.random() they will be affected. Using setSeed() without passing in a seed will generate a random 32-bit seed. The seed value will be returned from the function call, allowing you to save it in the data for the experiment if needed.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_8","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#use-a-random-32-bit-seed-and-save-to-data","text":"const seed = jsPsych . randomization . setSeed (); jsPsych . data . addProperties ({ rng_seed : seed });","title":"Use a random 32-bit seed and save to data"},{"location":"reference/jspsych-randomization/#use-your-own-seed","text":"jsPsych . randomization . setSeed ( \"jspsych\" );","title":"Use your own seed"},{"location":"reference/jspsych-randomization/#jspsychrandomizationshuffle","text":"jsPsych . randomization . shuffle ( array )","title":"jsPsych.randomization.shuffle"},{"location":"reference/jspsych-randomization/#parameters_11","text":"Parameter Type Description array array The array of values to shuffle","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_11","text":"Returns an array with the same elements as the input array in a random order.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_11","text":"A simple method for shuffling the order of an array.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_9","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#shuffle-an-array","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffle ( myArray ); // output: shuffledArray = [3,2,4,1,5]","title":"Shuffle an array"},{"location":"reference/jspsych-randomization/#jspsychrandomizationshufflenorepeats","text":"jsPsych . randomization . shuffleNoRepeats ( array , equalityTest )","title":"jsPsych.randomization.shuffleNoRepeats"},{"location":"reference/jspsych-randomization/#parameters_12","text":"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.","title":"Parameters"},{"location":"reference/jspsych-randomization/#return-value_12","text":"Returns an array with the same elements as the input array in a random order, with no repeating neighbors.","title":"Return value"},{"location":"reference/jspsych-randomization/#description_12","text":"Shuffle an array, ensuring that neighboring elements in the array are different. Warning: if you provide an array that has very few valid permutations with no neighboring elements, then this method will fail and cause the browser to hang.","title":"Description"},{"location":"reference/jspsych-randomization/#examples_10","text":"","title":"Examples"},{"location":"reference/jspsych-randomization/#basic-example","text":"var myArray = [ 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 , 1 , 2 , 3 , 4 , 5 ]; var shuffledArray = jsPsych . randomization . shuffleNoRepeats ( myArray ); // output: shuffledArray = [2, 3, 5, 1, 2, 4, 1, 5, 4, 1, 3, 5, 4, 3, 2]","title":"Basic example"},{"location":"reference/jspsych-randomization/#custom-equalitytest","text":"var myObjects = [ { color : \"blue\" }, { color : \"red\" }, { color : \"yellow\" }, { color : \"orange\" } ]; var repeatedSet = jsPsych . randomization . repeat ( myObjects , 3 ); var shuffled = jsPsych . randomization . shuffleNoRepeats ( repeatedSet , function ( a , b ) { return a . color === b . color }); // console.log(JSON.stringify(shuffled)) // \"[{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"blue\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"yellow\"},{\"color\":\"orange\"},{\"color\":\"blue\"},{\"color\":\"orange\"},{\"color\":\"red\"},{\"color\":\"blue\"}]\"","title":"Custom equalityTest"},{"location":"reference/jspsych-turk/","text":"jsPsych.turk \u00b6 The jsPsych.turk module contains functions for interacting with Mechanical Turk. jsPsych.turk.submitToTurk \u00b6 jsPsych . turk . submitToTurk ( data ) Parameters \u00b6 Parameter Type Description data object The data parameter is an object of key: value pairs. Any pairs in the data parameter will be saved by Mechanical Turk, and can be downloaded in a CSV file through the Mechanical Turk interface. Important : the data parameter must contain at least one key: value pair, even just a dummy value, or the HIT will not be submitted correctly. Return value \u00b6 Returns nothing. Description \u00b6 This method will submit a HIT to Mechanical Turk, causing the HIT to finish. This method will only work when called from within the mechanical turk website. If you are using an external HIT to send workers to your own server, this method will not work on an externally hosted page. It will work if your external content is loaded in the iframe on the Mechanical Turk website. Example \u00b6 < p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > // this content must be loaded in the iframe on the mechanical turk website. // usually, this means that the content is part of your 'recruitment ad', the // page the workers can see when they are deciding whether or not to accept a HIT. // one option is to include a simple form on this page that workers submit, with a // special code that they get at the end of the experiment. function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script > jsPsych.turk.turkInfo \u00b6 jsPsych . turk . turkInfo () Parameters \u00b6 None. Return value \u00b6 Returns an object with six properties: .assignmentId contains the assignment ID string of the HIT. .hitId contains the HIT ID. .workerId contains the worker ID of the worker completing the HIT. .turkSubmitTo contains the URL for submitting the HIT. This parameter is used in the jsPsych.turk.submitToTurk method, and is probably not useful outside of that context. .previewMode is a boolean value indicating whether or not the worker has accepted the HIT yet. If the page is viewed inside Mechancial Turk and the worker has not clicked 'Accept HIT' then this will be true. If the page is viewed outside Mechanical Turk or the worker has acccepted the HIT, then it will be false. .outsideTurk is a boolean value indicating if the page is being viewed within Mechanical Turk, or if it is being viewed from another source (e.g., someone directly going to the page URL instead of going through mturk). Description \u00b6 This method returns basic information about the current Mechanical Turk session, including the worker ID, assignment ID, and HIT ID. Example \u00b6 var turkInfo = jsPsych . turk . turkInfo (); alert ( 'Worker ID is: ' + turkInfo . workerId ); alert ( 'Assignment ID is: ' + turkInfo . assignmentId ); alert ( 'HIT ID is: ' + turkInfo . hitId ); // true if the page is viewed within Mechanical Turk, // but worker has not accepted the HIT yet. // false if the page is viewed outside Mechanical Turk, // OR the worker has accepted the HIT. alert ( 'Preview mode? ' + turkInfo . previewMode ); // true if the page is viewed outside mechanical turk, // false otherwise. alert ( 'Outside turk? ' + turkInfo . outsideTurk );","title":"jsPsych.turk"},{"location":"reference/jspsych-turk/#jspsychturk","text":"The jsPsych.turk module contains functions for interacting with Mechanical Turk.","title":"jsPsych.turk"},{"location":"reference/jspsych-turk/#jspsychturksubmittoturk","text":"jsPsych . turk . submitToTurk ( data )","title":"jsPsych.turk.submitToTurk"},{"location":"reference/jspsych-turk/#parameters","text":"Parameter Type Description data object The data parameter is an object of key: value pairs. Any pairs in the data parameter will be saved by Mechanical Turk, and can be downloaded in a CSV file through the Mechanical Turk interface. Important : the data parameter must contain at least one key: value pair, even just a dummy value, or the HIT will not be submitted correctly.","title":"Parameters"},{"location":"reference/jspsych-turk/#return-value","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych-turk/#description","text":"This method will submit a HIT to Mechanical Turk, causing the HIT to finish. This method will only work when called from within the mechanical turk website. If you are using an external HIT to send workers to your own server, this method will not work on an externally hosted page. It will work if your external content is loaded in the iframe on the Mechanical Turk website.","title":"Description"},{"location":"reference/jspsych-turk/#example","text":"< p > Enter the code you were given: </ p > < input type = \"text\" id = \"code\" ></ input > < button onclick = \"sendData();\" > Submit HIT </ button > < script > // this content must be loaded in the iframe on the mechanical turk website. // usually, this means that the content is part of your 'recruitment ad', the // page the workers can see when they are deciding whether or not to accept a HIT. // one option is to include a simple form on this page that workers submit, with a // special code that they get at the end of the experiment. function sendData () { jsPsych . turk . submitToTurk ({ code : document . getElementById ( 'code' ). value }); } </ script >","title":"Example"},{"location":"reference/jspsych-turk/#jspsychturkturkinfo","text":"jsPsych . turk . turkInfo ()","title":"jsPsych.turk.turkInfo"},{"location":"reference/jspsych-turk/#parameters_1","text":"None.","title":"Parameters"},{"location":"reference/jspsych-turk/#return-value_1","text":"Returns an object with six properties: .assignmentId contains the assignment ID string of the HIT. .hitId contains the HIT ID. .workerId contains the worker ID of the worker completing the HIT. .turkSubmitTo contains the URL for submitting the HIT. This parameter is used in the jsPsych.turk.submitToTurk method, and is probably not useful outside of that context. .previewMode is a boolean value indicating whether or not the worker has accepted the HIT yet. If the page is viewed inside Mechancial Turk and the worker has not clicked 'Accept HIT' then this will be true. If the page is viewed outside Mechanical Turk or the worker has acccepted the HIT, then it will be false. .outsideTurk is a boolean value indicating if the page is being viewed within Mechanical Turk, or if it is being viewed from another source (e.g., someone directly going to the page URL instead of going through mturk).","title":"Return value"},{"location":"reference/jspsych-turk/#description_1","text":"This method returns basic information about the current Mechanical Turk session, including the worker ID, assignment ID, and HIT ID.","title":"Description"},{"location":"reference/jspsych-turk/#example_1","text":"var turkInfo = jsPsych . turk . turkInfo (); alert ( 'Worker ID is: ' + turkInfo . workerId ); alert ( 'Assignment ID is: ' + turkInfo . assignmentId ); alert ( 'HIT ID is: ' + turkInfo . hitId ); // true if the page is viewed within Mechanical Turk, // but worker has not accepted the HIT yet. // false if the page is viewed outside Mechanical Turk, // OR the worker has accepted the HIT. alert ( 'Preview mode? ' + turkInfo . previewMode ); // true if the page is viewed outside mechanical turk, // false otherwise. alert ( 'Outside turk? ' + turkInfo . outsideTurk );","title":"Example"},{"location":"reference/jspsych/","text":"jsPsych \u00b6 initJsPsych \u00b6 var jsPsych = initJsPsych ( settings ); Parameters \u00b6 Parameter Type Description settings object The settings object for initializing jsPsych. See table below. The settings object can contain several parameters. None of the parameters are required. Parameter Type Description 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 participant 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 participant can use to complete the experiment. See list of options below. This feature is deprecated as of v7.1 and will be removed in v8.0. The browser-check plugin is an improved way to handle exclusions. show_progress_bar boolean If true , then a progress bar is shown at the top of the page. Default is false . 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. 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. 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. case_sensitive_responses boolean If true , then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. \"A\" (uppercase) will not be recognized as a valid response if the trial only accepts \"a\" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both \"a\" and \"A\" responses will be valid when the trial's key choice parameter is \"a\". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is false . extensions array Array containing information about one or more jsPsych extensions that are used during the experiment. Each extension should be specified as an object with type (required), which is the name of the extension, and params (optional), which is an object containing any parameter-value pairs to be passed to the extension's initialize function. Default value is an empty array. 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 participant 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 \u00b6 Returns a jsPsych instance, which all jsPsych methods on this page are called on. Therefore it is not possible to call any of the jsPsych methods listed on this page until this initJsPsych function is called and a jsPsych instance is created. Description \u00b6 This function initializes jsPsych with the specified experiment settings. Example \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); }, show_progress_bar : true , default_iti : 500 }); For more examples, see the HTML files in the examples folder . jsPsych.addNodeToEndOfTimeline \u00b6 jsPsych . addNodeToEndOfTimeline ( node_parameters ) Parameters \u00b6 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. Return value \u00b6 None. Description \u00b6 Adds the timeline to the end of the experiment. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a new trial.' } var new_timeline = { timeline : [ trial ] } jsPsych . addNodeToEndOfTimeline ( new_timeline ) jsPsych.endCurrentTimeline \u00b6 jsPsych . endCurrentTimeline () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Ends the current timeline. If timelines are nested, then only the timeline that contains the current trial is ended. Example \u00b6 End timeline if a particular key is pressed \u00b6 var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); var images = [ \"img/1.gif\" , \"img/2.gif\" , \"img/3.gif\" , \"img/4.gif\" , \"img/5.gif\" , \"img/6.gif\" , \"img/7.gif\" , \"img/8.gif\" , \"img/9.gif\" , \"img/10.gif\" ]; var trials = []; for ( var i = 0 ; i < images . length ; i ++ ) { trials . push ({ stimulus : images [ i ] }); } var block = { type : jsPsychImageKeyboardResponse , choices : [ 'y' , 'n' ], prompt : '<p>Press \"y\" to Continue. Press \"n\" to end this node of the experiment.</p>' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'n' )) { jsPsych . endCurrentTimeline (); } }, timeline : trials } var after_block = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>The next node</p>' } jsPsych . run ([ block , after_block ]); jsPsych.endExperiment \u00b6 jsPsych . endExperiment ( end_message , data ) Parameters \u00b6 Parameter Type Description end_message string A message to display on the screen after the experiment is over. Can include HTML formatting. data object An optional object of key-value pairs to store as data in the final trial of the experiment. Return value \u00b6 None. Description \u00b6 Ends the experiment, skipping all remaining trials. If the on_finish event handler for jsPsych returns a Promise then the end_message will not be displayed until the promise is resolved. Example \u00b6 End the experiment if a particular response is given \u00b6 var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'image1.jpg' , choices : [ 'y' , 'n' ] prompt : '<p>Press \"y\" to Continue. Press \"n\" to end the experiment</p>' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"n\" )){ jsPsych . endExperiment ( 'The experiment was ended by pressing \"n\".' ); } } } jsPsych.finishTrial \u00b6 jsPsych . finishTrial ( data ) Parameters \u00b6 Parameter Type Description data object The data to store for the trial. Return value \u00b6 Returns nothing. Description \u00b6 This method tells jsPsych that the current trial is over. It is used in all of the plugins to end the current trial. When the trial ends a few things happen: The data is stored using jsPsych.data.write() The on_finish callback function is executed for the trial The on_trial_finish callback function is executed The progress bar is updated if it is being displayed The experiment ends if the trial is the last one (and the on_finish callback function is executed). The next trial, if one exists, is started. Example \u00b6 // this code would be in a plugin jsPsych . finishTrial ({ correct_response : true }); jsPsych.getAllTimelineVariables \u00b6 jsPsych . getAllTimelineVariables () Parameters \u00b6 None. Return value \u00b6 Returns an object with all available timeline variables at this moment in the experiment, represented as key: value pairs. Description \u00b6 This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating data, such as in the example below. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Just a demo' , on_finish : function ( data ){ // merge all timeline variables available at this trial into the data for this trial Object . assign ( data , jsPsych . getAllTimelineVariables ()) } } jsPsych.getCurrentTimelineNodeID \u00b6 jsPsych . getCurrentTimelineNodeID () Parameters \u00b6 None. Return value \u00b6 Returns the ID of the TimelineNode that is currently active. Description \u00b6 Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: \"0.0\" is the ID of the first top-level TimelineNode \"1.0\" is the ID of the second top-level TimelineNode \"2.0\" is the ID of the third top-level TimelineNode, and so on... If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: \"0.0\" is the ID of the first top-level TimelineNode during the first iteration \"0.1\" is the ID of the first top-level TimelineNode during the second iteration \"0.2\" is the ID of the first top-level TimelineNode during the third iteration, and so on... If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with \".\" : \"0.0-1.0\" is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. \"0.0-2.0\" is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... The rules about iterations apply throughout the hierarchical ID: \"0.2-1.3\" is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time. Example \u00b6 var id = jsPsych . getCurrentTimelineNodeID (); console . log ( 'The current TimelineNode ID is ' + id ); jsPsych.getCurrentTrial \u00b6 jsPsych . getCurrentTrial () Parameters \u00b6 None. Return value \u00b6 Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial. Description \u00b6 Get a description of the current trial Example \u00b6 var trial = jsPsych . getCurrentTrial (); console . log ( 'The current trial is using the ' + trial . type + ' plugin' ); jsPsych.getDisplayElement \u00b6 jsPsych . getDisplayElement () Parameters \u00b6 None. Return value \u00b6 Returns the HTML DOM element used for displaying the experiment. Description \u00b6 Get the DOM element that displays the experiment. Example \u00b6 var el = jsPsych . getDisplayElement (); // hide the jsPsych display el . style . visibility = 'hidden' ; \u00b6 jsPsych.getInitSettings \u00b6 jsPsych . getInitSettings () Parameters \u00b6 None Return value \u00b6 Returns the settings object used to initialize the experiment. Description \u00b6 Gets the object containing the settings for the current experiment. Example \u00b6 var settings = jsPsych . getInitSettings (); // check the experiment structure console . log ( JSON . stringify ( settings . timeline )); jsPsych.getProgress \u00b6 jsPsych . getProgress () Parameters \u00b6 None. Return value \u00b6 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. Description \u00b6 This method returns information about the length of the experiment and the participant's current location in the experiment timeline. Example \u00b6 var progress = jsPsych . getProgress (); alert ( 'You have completed approximately ' + progress . percent_complete + '% of the experiment' ); jsPsych.getProgressBarCompleted \u00b6 jsPsych . getProgressBarCompleted () Parameters \u00b6 None. Return value \u00b6 Returns a value between 0 and 1 representing how full the progress bar currently is. Description \u00b6 Used to get the current value of the progress bar. Works for automated and manual control. Example \u00b6 var progress_bar_amount = jsPsych . getProgressBarCompleted (); jsPsych.getStartTime \u00b6 jsPsych . getStartTime () Parameters \u00b6 None. Return value \u00b6 Returns a Date object indicating when the experiment began. Description \u00b6 Get the time that the experiment began. Example \u00b6 var start_time = jsPsych . getStartTime (); jsPsych.getTotalTime \u00b6 jsPsych . getTotalTime () Parameters \u00b6 None. Return value \u00b6 Returns a numeric value indicating the number of milliseconds since jsPsych.run was called. Description \u00b6 Gets the total time the participant has been in the experiment. Example \u00b6 var time = jsPsych . getTotalTime (); console . log ( time ); jsPsych.pauseExperiment \u00b6 jsPsych . pauseExperiment () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Pauses the experiment. The experiment will finish the current trial, but will not execute any additional trials until jsPsych.resumeExperiment() is called. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } } jsPsych.resumeExperiment \u00b6 jsPsych . resumeExperiment () Parameters \u00b6 None. Return value \u00b6 None. Description \u00b6 Resumes the experiment after a call to jsPsych.pauseExperiment() . If the post trial delay ( post_trial_gap ) has not yet been reached, then the experiment will not continue until the delay is finished. For example, if post_trial_gap was 10,000ms and jsPsych.resumeExperiment() was called 6,000ms after the previous trial finished, then the experiment would not continue for another 4,000ms. Example \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } } jsPsych.run \u00b6 jsPsych . run ( timeline ) Parameters \u00b6 Parameter Type Description timeline array An array containing the objects that describe the experiment timeline. See Creating an Experiment: The Timeline . Return value \u00b6 None. Description \u00b6 Start the jsPsych experiment with the specified timeline. Example \u00b6 var timeline = [ trial1 , trial2 , trial3 ]; jsPsych . run ( timeline ); jsPsych.setProgressBar \u00b6 jsPsych . setProgressBar ( value ) Parameters \u00b6 Parameter Type Description value numeric Proprotion (between 0 and 1) to fill the progress bar. Return value \u00b6 None. Description \u00b6 Set the progress bar to a custom amount. Proportion must be between 0 and 1. Values larger than 1 are treated as 1. Example \u00b6 jsPsych . setProgressBar ( 0.85 ); jsPsych.timelineVariable \u00b6 jsPsych . timelineVariable ( variable , call_immediate ) Parameters \u00b6 Parameter Type Description variable string Name of the timeline variable call_immediate bool This parameter is optional and can usually be omitted. It determines the return value of jsPsych.timelineVariable . If true , the function returns the value of the current timeline variable. If false , the function returns a function that returns the value of the current timeline variable. When call_immediate is omitted, the appropriate option is determined automatically based on the context in which this function is called. When jsPsych.timelineVariable is used as a parameter value, call_immediate will be false . This allows it to be used as a dynamic trial parameter . When jsPsych.timelineVariable is used inside of a function, call_immediate will be true . It is possible to explicitly set this option to true to force the function to immediately return the current value of the timeline variable. Return value \u00b6 Either a function that returns the value of the timeline variable, or the value of the timeline variable, depending on the context in which it is used. See call_immediate description above. Description \u00b6 Timeline variables are a powerful technique for generating experiments with repetitive procedures but different parameter values. This function fetches the current value of a particular timeline variable. It must be used in conjunction with a timeline that has timeline variables. See the timeline variable section for details. Examples \u00b6 Standard use as a parameter for a trial \u00b6 var trial = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'image' ) } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Invoking immediately in a function \u00b6 var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Prior to jsPsych v6.3.0, the call_immediate parameter must be set to true when jsPsych.timelineVariable is called from within a function, such as a dynamic parameter : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' , true ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } jsPsych.version \u00b6 jsPsych . version () Parameters \u00b6 None. Return value \u00b6 Returns the version number as a string. Description \u00b6 Gets the version of jsPsych. Example \u00b6 var version = jsPsych . version (); console . log ( version );","title":"jsPsych"},{"location":"reference/jspsych/#jspsych","text":"","title":"jsPsych"},{"location":"reference/jspsych/#initjspsych","text":"var jsPsych = initJsPsych ( settings );","title":"initJsPsych"},{"location":"reference/jspsych/#parameters","text":"Parameter Type Description settings object The settings object for initializing jsPsych. See table below. The settings object can contain several parameters. None of the parameters are required. Parameter Type Description 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 participant 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 participant can use to complete the experiment. See list of options below. This feature is deprecated as of v7.1 and will be removed in v8.0. The browser-check plugin is an improved way to handle exclusions. show_progress_bar boolean If true , then a progress bar is shown at the top of the page. Default is false . 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. 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. 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. case_sensitive_responses boolean If true , then jsPsych will make a distinction between uppercase and lowercase keys when evaluating keyboard responses, e.g. \"A\" (uppercase) will not be recognized as a valid response if the trial only accepts \"a\" (lowercase). If false, then jsPsych will not make a distinction between uppercase and lowercase keyboard responses, e.g. both \"a\" and \"A\" responses will be valid when the trial's key choice parameter is \"a\". Setting this parameter to false is useful if you want key responses to be treated the same way when CapsLock is turned on or the Shift key is held down. The default value is false . extensions array Array containing information about one or more jsPsych extensions that are used during the experiment. Each extension should be specified as an object with type (required), which is the name of the extension, and params (optional), which is an object containing any parameter-value pairs to be passed to the extension's initialize function. Default value is an empty array. 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 participant 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).","title":"Parameters"},{"location":"reference/jspsych/#return-value","text":"Returns a jsPsych instance, which all jsPsych methods on this page are called on. Therefore it is not possible to call any of the jsPsych methods listed on this page until this initJsPsych function is called and a jsPsych instance is created.","title":"Return value"},{"location":"reference/jspsych/#description","text":"This function initializes jsPsych with the specified experiment settings.","title":"Description"},{"location":"reference/jspsych/#example","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); }, show_progress_bar : true , default_iti : 500 }); For more examples, see the HTML files in the examples folder .","title":"Example"},{"location":"reference/jspsych/#jspsychaddnodetoendoftimeline","text":"jsPsych . addNodeToEndOfTimeline ( node_parameters )","title":"jsPsych.addNodeToEndOfTimeline"},{"location":"reference/jspsych/#parameters_1","text":"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.","title":"Parameters"},{"location":"reference/jspsych/#return-value_1","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_1","text":"Adds the timeline to the end of the experiment.","title":"Description"},{"location":"reference/jspsych/#example_1","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'This is a new trial.' } var new_timeline = { timeline : [ trial ] } jsPsych . addNodeToEndOfTimeline ( new_timeline )","title":"Example"},{"location":"reference/jspsych/#jspsychendcurrenttimeline","text":"jsPsych . endCurrentTimeline ()","title":"jsPsych.endCurrentTimeline"},{"location":"reference/jspsych/#parameters_2","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_2","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_2","text":"Ends the current timeline. If timelines are nested, then only the timeline that contains the current trial is ended.","title":"Description"},{"location":"reference/jspsych/#example_2","text":"","title":"Example"},{"location":"reference/jspsych/#end-timeline-if-a-particular-key-is-pressed","text":"var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); var images = [ \"img/1.gif\" , \"img/2.gif\" , \"img/3.gif\" , \"img/4.gif\" , \"img/5.gif\" , \"img/6.gif\" , \"img/7.gif\" , \"img/8.gif\" , \"img/9.gif\" , \"img/10.gif\" ]; var trials = []; for ( var i = 0 ; i < images . length ; i ++ ) { trials . push ({ stimulus : images [ i ] }); } var block = { type : jsPsychImageKeyboardResponse , choices : [ 'y' , 'n' ], prompt : '<p>Press \"y\" to Continue. Press \"n\" to end this node of the experiment.</p>' , on_finish : function ( data ) { if ( jsPsych . pluginAPI . compareKeys ( data . response , 'n' )) { jsPsych . endCurrentTimeline (); } }, timeline : trials } var after_block = { type : jsPsychHtmlKeyboardResponse , stimulus : '<p>The next node</p>' } jsPsych . run ([ block , after_block ]);","title":"End timeline if a particular key is pressed"},{"location":"reference/jspsych/#jspsychendexperiment","text":"jsPsych . endExperiment ( end_message , data )","title":"jsPsych.endExperiment"},{"location":"reference/jspsych/#parameters_3","text":"Parameter Type Description end_message string A message to display on the screen after the experiment is over. Can include HTML formatting. data object An optional object of key-value pairs to store as data in the final trial of the experiment.","title":"Parameters"},{"location":"reference/jspsych/#return-value_3","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_3","text":"Ends the experiment, skipping all remaining trials. If the on_finish event handler for jsPsych returns a Promise then the end_message will not be displayed until the promise is resolved.","title":"Description"},{"location":"reference/jspsych/#example_3","text":"","title":"Example"},{"location":"reference/jspsych/#end-the-experiment-if-a-particular-response-is-given","text":"var trial = { type : jsPsychImageKeyboardResponse , stimulus : 'image1.jpg' , choices : [ 'y' , 'n' ] prompt : '<p>Press \"y\" to Continue. Press \"n\" to end the experiment</p>' , on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"n\" )){ jsPsych . endExperiment ( 'The experiment was ended by pressing \"n\".' ); } } }","title":"End the experiment if a particular response is given"},{"location":"reference/jspsych/#jspsychfinishtrial","text":"jsPsych . finishTrial ( data )","title":"jsPsych.finishTrial"},{"location":"reference/jspsych/#parameters_4","text":"Parameter Type Description data object The data to store for the trial.","title":"Parameters"},{"location":"reference/jspsych/#return-value_4","text":"Returns nothing.","title":"Return value"},{"location":"reference/jspsych/#description_4","text":"This method tells jsPsych that the current trial is over. It is used in all of the plugins to end the current trial. When the trial ends a few things happen: The data is stored using jsPsych.data.write() The on_finish callback function is executed for the trial The on_trial_finish callback function is executed The progress bar is updated if it is being displayed The experiment ends if the trial is the last one (and the on_finish callback function is executed). The next trial, if one exists, is started.","title":"Description"},{"location":"reference/jspsych/#example_4","text":"// this code would be in a plugin jsPsych . finishTrial ({ correct_response : true });","title":"Example"},{"location":"reference/jspsych/#jspsychgetalltimelinevariables","text":"jsPsych . getAllTimelineVariables ()","title":"jsPsych.getAllTimelineVariables"},{"location":"reference/jspsych/#parameters_5","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_5","text":"Returns an object with all available timeline variables at this moment in the experiment, represented as key: value pairs.","title":"Return value"},{"location":"reference/jspsych/#description_5","text":"This function can be used to get all the timeline variables at a particular moment in the experiment. Can be useful for annotating data, such as in the example below.","title":"Description"},{"location":"reference/jspsych/#example_5","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Just a demo' , on_finish : function ( data ){ // merge all timeline variables available at this trial into the data for this trial Object . assign ( data , jsPsych . getAllTimelineVariables ()) } }","title":"Example"},{"location":"reference/jspsych/#jspsychgetcurrenttimelinenodeid","text":"jsPsych . getCurrentTimelineNodeID ()","title":"jsPsych.getCurrentTimelineNodeID"},{"location":"reference/jspsych/#parameters_6","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_6","text":"Returns the ID of the TimelineNode that is currently active.","title":"Return value"},{"location":"reference/jspsych/#description_6","text":"Gets the ID of the active TimelineNode. The ID is a string that follows a specific format: \"0.0\" is the ID of the first top-level TimelineNode \"1.0\" is the ID of the second top-level TimelineNode \"2.0\" is the ID of the third top-level TimelineNode, and so on... If a TimelineNode iterates multiple times (using the loop function, for example), then the iterations are indicated in the second number: \"0.0\" is the ID of the first top-level TimelineNode during the first iteration \"0.1\" is the ID of the first top-level TimelineNode during the second iteration \"0.2\" is the ID of the first top-level TimelineNode during the third iteration, and so on... If TimelineNodes are nested in other TimelineNodes, then the hierarchical structure is shown with \".\" : \"0.0-1.0\" is the ID of the second TimelineNode on the timeline of the first top-level TimelineNode. \"0.0-2.0\" is the ID of the third TimelineNode on the timeline of the first top-level TimelineNode, and so on... The rules about iterations apply throughout the hierarchical ID: \"0.2-1.3\" is the ID of the second TimelineNode, executing for the fourth time, on the timeline of the first top-level TimelineNode, executing for the third time.","title":"Description"},{"location":"reference/jspsych/#example_6","text":"var id = jsPsych . getCurrentTimelineNodeID (); console . log ( 'The current TimelineNode ID is ' + id );","title":"Example"},{"location":"reference/jspsych/#jspsychgetcurrenttrial","text":"jsPsych . getCurrentTrial ()","title":"jsPsych.getCurrentTrial"},{"location":"reference/jspsych/#parameters_7","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_7","text":"Returns the object describing the current trial. The object will contain all of the parameters associated with the current trial.","title":"Return value"},{"location":"reference/jspsych/#description_7","text":"Get a description of the current trial","title":"Description"},{"location":"reference/jspsych/#example_7","text":"var trial = jsPsych . getCurrentTrial (); console . log ( 'The current trial is using the ' + trial . type + ' plugin' );","title":"Example"},{"location":"reference/jspsych/#jspsychgetdisplayelement","text":"jsPsych . getDisplayElement ()","title":"jsPsych.getDisplayElement"},{"location":"reference/jspsych/#parameters_8","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_8","text":"Returns the HTML DOM element used for displaying the experiment.","title":"Return value"},{"location":"reference/jspsych/#description_8","text":"Get the DOM element that displays the experiment.","title":"Description"},{"location":"reference/jspsych/#example_8","text":"","title":"Example"},{"location":"reference/jspsych/#var-el-jspsychgetdisplayelement-hide-the-jspsych-display-elstylevisibility-hidden","text":"","title":"var el = jsPsych.getDisplayElement();\n\n// hide the jsPsych display\nel.style.visibility = &#39;hidden&#39;;\n"},{"location":"reference/jspsych/#jspsychgetinitsettings","text":"jsPsych . getInitSettings ()","title":"jsPsych.getInitSettings"},{"location":"reference/jspsych/#parameters_9","text":"None","title":"Parameters"},{"location":"reference/jspsych/#return-value_9","text":"Returns the settings object used to initialize the experiment.","title":"Return value"},{"location":"reference/jspsych/#description_9","text":"Gets the object containing the settings for the current experiment.","title":"Description"},{"location":"reference/jspsych/#example_9","text":"var settings = jsPsych . getInitSettings (); // check the experiment structure console . log ( JSON . stringify ( settings . timeline ));","title":"Example"},{"location":"reference/jspsych/#jspsychgetprogress","text":"jsPsych . getProgress ()","title":"jsPsych.getProgress"},{"location":"reference/jspsych/#parameters_10","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_10","text":"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.","title":"Return value"},{"location":"reference/jspsych/#description_10","text":"This method returns information about the length of the experiment and the participant's current location in the experiment timeline.","title":"Description"},{"location":"reference/jspsych/#example_10","text":"var progress = jsPsych . getProgress (); alert ( 'You have completed approximately ' + progress . percent_complete + '% of the experiment' );","title":"Example"},{"location":"reference/jspsych/#jspsychgetprogressbarcompleted","text":"jsPsych . getProgressBarCompleted ()","title":"jsPsych.getProgressBarCompleted"},{"location":"reference/jspsych/#parameters_11","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_11","text":"Returns a value between 0 and 1 representing how full the progress bar currently is.","title":"Return value"},{"location":"reference/jspsych/#description_11","text":"Used to get the current value of the progress bar. Works for automated and manual control.","title":"Description"},{"location":"reference/jspsych/#example_11","text":"var progress_bar_amount = jsPsych . getProgressBarCompleted ();","title":"Example"},{"location":"reference/jspsych/#jspsychgetstarttime","text":"jsPsych . getStartTime ()","title":"jsPsych.getStartTime"},{"location":"reference/jspsych/#parameters_12","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_12","text":"Returns a Date object indicating when the experiment began.","title":"Return value"},{"location":"reference/jspsych/#description_12","text":"Get the time that the experiment began.","title":"Description"},{"location":"reference/jspsych/#example_12","text":"var start_time = jsPsych . getStartTime ();","title":"Example"},{"location":"reference/jspsych/#jspsychgettotaltime","text":"jsPsych . getTotalTime ()","title":"jsPsych.getTotalTime"},{"location":"reference/jspsych/#parameters_13","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_13","text":"Returns a numeric value indicating the number of milliseconds since jsPsych.run was called.","title":"Return value"},{"location":"reference/jspsych/#description_13","text":"Gets the total time the participant has been in the experiment.","title":"Description"},{"location":"reference/jspsych/#example_13","text":"var time = jsPsych . getTotalTime (); console . log ( time );","title":"Example"},{"location":"reference/jspsych/#jspsychpauseexperiment","text":"jsPsych . pauseExperiment ()","title":"jsPsych.pauseExperiment"},{"location":"reference/jspsych/#parameters_14","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_14","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_14","text":"Pauses the experiment. The experiment will finish the current trial, but will not execute any additional trials until jsPsych.resumeExperiment() is called.","title":"Description"},{"location":"reference/jspsych/#example_14","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } }","title":"Example"},{"location":"reference/jspsych/#jspsychresumeexperiment","text":"jsPsych . resumeExperiment ()","title":"jsPsych.resumeExperiment"},{"location":"reference/jspsych/#parameters_15","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_15","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_15","text":"Resumes the experiment after a call to jsPsych.pauseExperiment() . If the post trial delay ( post_trial_gap ) has not yet been reached, then the experiment will not continue until the delay is finished. For example, if post_trial_gap was 10,000ms and jsPsych.resumeExperiment() was called 6,000ms after the previous trial finished, then the experiment would not continue for another 4,000ms.","title":"Description"},{"location":"reference/jspsych/#example_15","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Press p to take a 30 second break. Otherwise, press c to continue immediately.' , choices : [ 'p' , 'c' ], on_finish : function ( data ){ if ( jsPsych . pluginAPI . compareKeys ( data . response , \"p\" )) { jsPsych . pauseExperiment (); setTimeout ( jsPsych . resumeExperiment , 30000 ); } } }","title":"Example"},{"location":"reference/jspsych/#jspsychrun","text":"jsPsych . run ( timeline )","title":"jsPsych.run"},{"location":"reference/jspsych/#parameters_16","text":"Parameter Type Description timeline array An array containing the objects that describe the experiment timeline. See Creating an Experiment: The Timeline .","title":"Parameters"},{"location":"reference/jspsych/#return-value_16","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_16","text":"Start the jsPsych experiment with the specified timeline.","title":"Description"},{"location":"reference/jspsych/#example_16","text":"var timeline = [ trial1 , trial2 , trial3 ]; jsPsych . run ( timeline );","title":"Example"},{"location":"reference/jspsych/#jspsychsetprogressbar","text":"jsPsych . setProgressBar ( value )","title":"jsPsych.setProgressBar"},{"location":"reference/jspsych/#parameters_17","text":"Parameter Type Description value numeric Proprotion (between 0 and 1) to fill the progress bar.","title":"Parameters"},{"location":"reference/jspsych/#return-value_17","text":"None.","title":"Return value"},{"location":"reference/jspsych/#description_17","text":"Set the progress bar to a custom amount. Proportion must be between 0 and 1. Values larger than 1 are treated as 1.","title":"Description"},{"location":"reference/jspsych/#example_17","text":"jsPsych . setProgressBar ( 0.85 );","title":"Example"},{"location":"reference/jspsych/#jspsychtimelinevariable","text":"jsPsych . timelineVariable ( variable , call_immediate )","title":"jsPsych.timelineVariable"},{"location":"reference/jspsych/#parameters_18","text":"Parameter Type Description variable string Name of the timeline variable call_immediate bool This parameter is optional and can usually be omitted. It determines the return value of jsPsych.timelineVariable . If true , the function returns the value of the current timeline variable. If false , the function returns a function that returns the value of the current timeline variable. When call_immediate is omitted, the appropriate option is determined automatically based on the context in which this function is called. When jsPsych.timelineVariable is used as a parameter value, call_immediate will be false . This allows it to be used as a dynamic trial parameter . When jsPsych.timelineVariable is used inside of a function, call_immediate will be true . It is possible to explicitly set this option to true to force the function to immediately return the current value of the timeline variable.","title":"Parameters"},{"location":"reference/jspsych/#return-value_18","text":"Either a function that returns the value of the timeline variable, or the value of the timeline variable, depending on the context in which it is used. See call_immediate description above.","title":"Return value"},{"location":"reference/jspsych/#description_18","text":"Timeline variables are a powerful technique for generating experiments with repetitive procedures but different parameter values. This function fetches the current value of a particular timeline variable. It must be used in conjunction with a timeline that has timeline variables. See the timeline variable section for details.","title":"Description"},{"location":"reference/jspsych/#examples","text":"","title":"Examples"},{"location":"reference/jspsych/#standard-use-as-a-parameter-for-a-trial","text":"var trial = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'image' ) } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] }","title":"Standard use as a parameter for a trial"},{"location":"reference/jspsych/#invoking-immediately-in-a-function","text":"var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] } Prior to jsPsych v6.3.0, the call_immediate parameter must be set to true when jsPsych.timelineVariable is called from within a function, such as a dynamic parameter : var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : function (){ return \"<img style='width:100px; height:100px;' src='\" + jsPsych . timelineVariable ( 'image' , true ) + \"'></img>\" ; } } var procedure = { timeline : [ trial ], timeline_variables : [ { image : 'face1.png' }, { image : 'face2.png' }, { image : 'face3.png' }, { image : 'face4.png' } ] }","title":"Invoking immediately in a function"},{"location":"reference/jspsych/#jspsychversion","text":"jsPsych . version ()","title":"jsPsych.version"},{"location":"reference/jspsych/#parameters_19","text":"None.","title":"Parameters"},{"location":"reference/jspsych/#return-value_19","text":"Returns the version number as a string.","title":"Return value"},{"location":"reference/jspsych/#description_19","text":"Gets the version of jsPsych.","title":"Description"},{"location":"reference/jspsych/#example_18","text":"var version = jsPsych . version (); console . log ( version );","title":"Example"},{"location":"support/migration-v7/","text":"Migrating an experiment to v7.x \u00b6 The release of version 7.0 changes a number of core components of jsPsych. We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych. Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. However, we did have to change a few critical things. This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x. Loading jsPsych \u00b6 There are now three different ways you can load jsPsych into your HTML file. We've updated the hello world tutorial to walk through each of the three options. If you are looking for the option that is most similar to the version 6.x experience, check out option 2 . The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently. Initializing and running jsPsych \u00b6 We've removed jsPsych.init() and split the features into two different functions. At the start of your experiment script, you'll now call initJsPsych() to get a new instance of jsPsych and store it in a variable called jsPsych . This is where you will pass in the variety of parameters that used to go into jsPsych.init() , with the exception of the timeline parameter. var jsPsych = initJsPsych ({ use_webaudio : false , on_finish : function (){ jsPsych . data . displayData (); } }); Once you've created your timeline, then you'll launch the experiment by calling jsPsych.run() , passing in the timeline as the only argument. This is the point in your script where you've used the jsPsych.init function in jsPsych v6.x. Because the jsPsych.run function only needs the experiment timeline, this argument should be an array (rather than an object like {timeline: timeline} in jsPsych v6.x). var timeline = [...] jsPsych . run ( timeline ); The type parameter for trials \u00b6 The type parameter now expects the value to be a plugin class rather than a string. For example, if you load the html-keyboard-response plugin from the CDN... < script src = \"http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.0\" ></ script > ... or from the plugin-html-keyboard-response.js file in the release archive... < script src = \"plugin-html-keyboard-response.js\" ></ script > ... then a global variable defining the plugin's class called jsPsychHtmlKeyboardResponse is available. To create a trial using the plugin, pass this class as the type parameter. The plugin classes are named starting with jsPsych , followed by the plugin name written in camel case (rather than with dashes between words). See the \"Using a plugin\" section of the Plugins overview page for more examples. Note that the value is not a string . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' } The choices parameter for keyboard response trials \u00b6 The choices parameter for keyboard response trials no longer supports jsPsych.NO_KEYS and jsPsych.ALL_KEYS , and they have been replaced by the strings \"NO_KEYS\" and \"ALL_KEYS\" respectively. For example, if you load the audio-keyboard-response plugin, you can prevent any user input like... var trial = { type : jsPsychAudioKeyboardResponse , choices : \"NO_KEYS\" , stimulus : 'example.ogg' , trial_ends_after_audio : true } Using extensions \u00b6 Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in initJsPsych() instead of jsPsych.init() . Extension classes are named similarly to plugins, except that they start with jsPsychExtension . var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) The class is also used in trials that use the extension. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' , extensions : [ { type : jsPsychExtensionWebgazer } ] } Custom plugins \u00b6 If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our plugin template . The new template implements plugins as a class, but the core components are essentially unchanged. Anything in plugin.info from a v6.x plugin should be moved into the info object. Note that the type argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then assigned as a static property of the class . Anything in plugin.trial from a v6.x plugin should be moved into the trial method inside the class. The new template has a constructor() function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin. There are a few changes to be aware of that may affect your plugin code. We removed the registerPreload function and we now auto-detect media to preload via the type argument specified in the info object. If a parameter is listed as IMAGE , AUDIO , or VIDEO , it will be automatically preloaded. If you wish to disable preloading you can set the preload flag to false for the parameter. If you invoke any functions from jsPsych, like jsPsych.finishTrial() , note that jsPsych is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simply prefix all jsPsych references with this. , e.g., jsPsych.finishTrial() becomes this.jsPsych.finishTrial() . If your reference to a jsPsych function is inside of another function, then in order for the this keyword to appropriately reference the jsPsych instance, you must also use a JavaScript arrow function expression for the outer function. For example, this: function end_trial () { // ... jsPsych . finishTrial ( data ); } Would be re-written as: const end_trial = () => { // ... this . jsPsych . finishTrial ( data ); } Need help? \u00b6 If you encounter issues migrating code to v7.x, feel free to post in our support thread for migration .","title":"Migrating from 6.x to 7.x"},{"location":"support/migration-v7/#migrating-an-experiment-to-v7x","text":"The release of version 7.0 changes a number of core components of jsPsych. We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych. Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. However, we did have to change a few critical things. This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x.","title":"Migrating an experiment to v7.x"},{"location":"support/migration-v7/#loading-jspsych","text":"There are now three different ways you can load jsPsych into your HTML file. We've updated the hello world tutorial to walk through each of the three options. If you are looking for the option that is most similar to the version 6.x experience, check out option 2 . The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently.","title":"Loading jsPsych"},{"location":"support/migration-v7/#initializing-and-running-jspsych","text":"We've removed jsPsych.init() and split the features into two different functions. At the start of your experiment script, you'll now call initJsPsych() to get a new instance of jsPsych and store it in a variable called jsPsych . This is where you will pass in the variety of parameters that used to go into jsPsych.init() , with the exception of the timeline parameter. var jsPsych = initJsPsych ({ use_webaudio : false , on_finish : function (){ jsPsych . data . displayData (); } }); Once you've created your timeline, then you'll launch the experiment by calling jsPsych.run() , passing in the timeline as the only argument. This is the point in your script where you've used the jsPsych.init function in jsPsych v6.x. Because the jsPsych.run function only needs the experiment timeline, this argument should be an array (rather than an object like {timeline: timeline} in jsPsych v6.x). var timeline = [...] jsPsych . run ( timeline );","title":"Initializing and running jsPsych"},{"location":"support/migration-v7/#the-type-parameter-for-trials","text":"The type parameter now expects the value to be a plugin class rather than a string. For example, if you load the html-keyboard-response plugin from the CDN... < script src = \"http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.0\" ></ script > ... or from the plugin-html-keyboard-response.js file in the release archive... < script src = \"plugin-html-keyboard-response.js\" ></ script > ... then a global variable defining the plugin's class called jsPsychHtmlKeyboardResponse is available. To create a trial using the plugin, pass this class as the type parameter. The plugin classes are named starting with jsPsych , followed by the plugin name written in camel case (rather than with dashes between words). See the \"Using a plugin\" section of the Plugins overview page for more examples. Note that the value is not a string . var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' }","title":"The type parameter for trials"},{"location":"support/migration-v7/#the-choices-parameter-for-keyboard-response-trials","text":"The choices parameter for keyboard response trials no longer supports jsPsych.NO_KEYS and jsPsych.ALL_KEYS , and they have been replaced by the strings \"NO_KEYS\" and \"ALL_KEYS\" respectively. For example, if you load the audio-keyboard-response plugin, you can prevent any user input like... var trial = { type : jsPsychAudioKeyboardResponse , choices : \"NO_KEYS\" , stimulus : 'example.ogg' , trial_ends_after_audio : true }","title":"The choices parameter for keyboard response trials"},{"location":"support/migration-v7/#using-extensions","text":"Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in initJsPsych() instead of jsPsych.init() . Extension classes are named similarly to plugins, except that they start with jsPsychExtension . var jsPsych = initJsPsych ({ extensions : [ { type : jsPsychExtensionWebgazer } ] }) The class is also used in trials that use the extension. var trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello, version 7.0!' , extensions : [ { type : jsPsychExtensionWebgazer } ] }","title":"Using extensions"},{"location":"support/migration-v7/#custom-plugins","text":"If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our plugin template . The new template implements plugins as a class, but the core components are essentially unchanged. Anything in plugin.info from a v6.x plugin should be moved into the info object. Note that the type argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then assigned as a static property of the class . Anything in plugin.trial from a v6.x plugin should be moved into the trial method inside the class. The new template has a constructor() function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin. There are a few changes to be aware of that may affect your plugin code. We removed the registerPreload function and we now auto-detect media to preload via the type argument specified in the info object. If a parameter is listed as IMAGE , AUDIO , or VIDEO , it will be automatically preloaded. If you wish to disable preloading you can set the preload flag to false for the parameter. If you invoke any functions from jsPsych, like jsPsych.finishTrial() , note that jsPsych is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simply prefix all jsPsych references with this. , e.g., jsPsych.finishTrial() becomes this.jsPsych.finishTrial() . If your reference to a jsPsych function is inside of another function, then in order for the this keyword to appropriately reference the jsPsych instance, you must also use a JavaScript arrow function expression for the outer function. For example, this: function end_trial () { // ... jsPsych . finishTrial ( data ); } Would be re-written as: const end_trial = () => { // ... this . jsPsych . finishTrial ( data ); }","title":"Custom plugins"},{"location":"support/migration-v7/#need-help","text":"If you encounter issues migrating code to v7.x, feel free to post in our support thread for migration .","title":"Need help?"},{"location":"support/support/","text":"Support \u00b6 For questions about jsPsych, the preferred method of support is GitHub Discussions . Questions are most likely to be answered when they include a reproducible example of the problem. If you can make your code available online and link to the experiment, that will make the question easier to answer. Please consider searching through the archive of Q&As before posting a new question. If you have identified a problem with jsPsych, such as a bug in the code or an error in the documentation, please open a new issue on GitHub. If you have a suggestion for fixing the problem, feel free to contribute to the project ! Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to josh.deleeuw@gmail.com .","title":"Getting Help"},{"location":"support/support/#support","text":"For questions about jsPsych, the preferred method of support is GitHub Discussions . Questions are most likely to be answered when they include a reproducible example of the problem. If you can make your code available online and link to the experiment, that will make the question easier to answer. Please consider searching through the archive of Q&As before posting a new question. If you have identified a problem with jsPsych, such as a bug in the code or an error in the documentation, please open a new issue on GitHub. If you have a suggestion for fixing the problem, feel free to contribute to the project ! Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to josh.deleeuw@gmail.com .","title":"Support"},{"location":"tutorials/hello-world/","text":"jsPsych \"Hello world\" experiment \u00b6 In the long tradition of \"Hello world!\" examples, this tutorial creates an experiment that outputs the phrase \"Hello world!\" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library. Choose your own (setup) adventure \u00b6 Starting with the release of version 7.0 of jsPsych there are three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are. I want the simplest possible setup . This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient. I want to be able to do some customization, but have a simple setup. . This approach involves downloading a bundle of scripts that make up jsPsych. If you used jsPsych prior to version 7.0, this will feel like the most familiar approach . Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior. I want to use modern JavaScript tooling, like npm and import statements. You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from NPM. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more. Option 1: Using CDN-hosted scripts \u00b6 Step 1: Create an HTML file \u00b6 Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html . There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. Step 2: Load the jsPsych library \u00b6 To use jsPsych, add a <script> tag to load the library. We'll load the library from a CDN , which means that the library is hosted on another server and can be loaded without having your own copy. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > </ head > < body ></ body > </ html > Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych. You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html > Step 3: Create a script element and initialize jsPsych \u00b6 To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Step 4: Use a plugin to print a message \u00b6 For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html > Step 5: Run the experiment \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). Option 2: Download and host jsPsych \u00b6 Step 1: Download jsPsych \u00b6 Start by downloading the latest release of jsPsych. Here's a direct link (jspsych.zip) . The most recent version can always be found at the top of the GitHub releases page . Note that even the releases that are for a particular plugin or extension will contain the full set of files needed to run jsPsych locally in the dist archive (zip) release asset. You should download the zip file for whatever the most recently released package is. This will ensure that you have the most recent version of all the packages associated with jsPsych. Step 2: Create a folder to store your experiment files \u00b6 Create a folder on your computer to put the experiment files in. We'll call this \"MyExperiment\" for the tutorial. Add a subfolder called jspsych . Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the dist folder into the jspsych folder. It should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc2 jspsych ---- \ud83d\udcc4 jspsych.js ---- \ud83d\udcc4 plugin-animation.js ---- \ud83d\udcc4 plugin-audio-keyboard-response.js ---- ... Step 3: Create an HTML file \u00b6 Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html in the MyExperiment folder. The directory structure should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc4 experiment.html -- \ud83d\udcc2 jspsych There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. Step 4: Load the jsPsych library \u00b6 To use jsPsych, add a <script> tag to load the library. Set the src attribute to the path to the jspsych.js file. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > </ head > < body ></ body > </ html > You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html > Step 5: Create a script element and initialize jsPsych \u00b6 To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Step 6: Use a plugin to print a message \u00b6 For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html > Step 7: Run the experiment \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). Option 3: Using NPM \u00b6 If you are electing to use npm to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. We will also assume that you are using a webpack or a similar bundler. Info You may want to check out the jsPsych Builder CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles using webpack. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page. Step 1: Install jspsych \u00b6 Run npm install jspsych . This installs the core jsPsych package. Plugins and extensions are installed separately. Step 2: Import the initJsPsych function and create a new JsPsych instance \u00b6 We create a new instance of the JsPsych class by calling initJsPsych . The instance can optionally be configured via a variety of options , passed as an object to initJsPsych . import { initJsPsych } from 'jspsych' ; const jsPsych = initJsPsych (); Step 3: Static markup and CSS \u00b6 jsPsych requires nothing but a body element in your HTML document. For the jsPsych stylesheet, depending on your bundler setup, you can either directly import 'jspsych/css/jspsych.css' into your JavaScript file or add a link tag (like <link href=\"path/to/jspsych.css\" rel=\"stylesheet\" type=\"text/css\" /> ) to your HTML document's head. Step 4: Install and import a plugin \u00b6 Install the html-keyboard-response plugin with: npm install @jspsych/plugin-html-keyboard-response Then import the htmlKeyboardResponse plugin class. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); Step 5: Create a trial \u00b6 Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to htmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } Step 6: Run \u00b6 Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } jsPsych . run ([ trial ]);","title":"The Basics: Hello World"},{"location":"tutorials/hello-world/#jspsych-hello-world-experiment","text":"In the long tradition of \"Hello world!\" examples, this tutorial creates an experiment that outputs the phrase \"Hello world!\" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library.","title":"jsPsych \"Hello world\" experiment"},{"location":"tutorials/hello-world/#choose-your-own-setup-adventure","text":"Starting with the release of version 7.0 of jsPsych there are three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are. I want the simplest possible setup . This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient. I want to be able to do some customization, but have a simple setup. . This approach involves downloading a bundle of scripts that make up jsPsych. If you used jsPsych prior to version 7.0, this will feel like the most familiar approach . Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior. I want to use modern JavaScript tooling, like npm and import statements. You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from NPM. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more.","title":"Choose your own (setup) adventure"},{"location":"tutorials/hello-world/#option-1-using-cdn-hosted-scripts","text":"","title":"Option 1: Using CDN-hosted scripts"},{"location":"tutorials/hello-world/#step-1-create-an-html-file","text":"Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html . There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.","title":"Step 1: Create an HTML file"},{"location":"tutorials/hello-world/#step-2-load-the-jspsych-library","text":"To use jsPsych, add a <script> tag to load the library. We'll load the library from a CDN , which means that the library is hosted on another server and can be loaded without having your own copy. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > </ head > < body ></ body > </ html > Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych. You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html >","title":"Step 2: Load the jsPsych library"},{"location":"tutorials/hello-world/#step-3-create-a-script-element-and-initialize-jspsych","text":"To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html >","title":"Step 3: Create a script element and initialize jsPsych"},{"location":"tutorials/hello-world/#step-4-use-a-plugin-to-print-a-message","text":"For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html >","title":"Step 4: Use a plugin to print a message"},{"location":"tutorials/hello-world/#step-5-run-the-experiment","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).","title":"Step 5: Run the experiment"},{"location":"tutorials/hello-world/#option-2-download-and-host-jspsych","text":"","title":"Option 2: Download and host jsPsych"},{"location":"tutorials/hello-world/#step-1-download-jspsych","text":"Start by downloading the latest release of jsPsych. Here's a direct link (jspsych.zip) . The most recent version can always be found at the top of the GitHub releases page . Note that even the releases that are for a particular plugin or extension will contain the full set of files needed to run jsPsych locally in the dist archive (zip) release asset. You should download the zip file for whatever the most recently released package is. This will ensure that you have the most recent version of all the packages associated with jsPsych.","title":"Step 1: Download jsPsych"},{"location":"tutorials/hello-world/#step-2-create-a-folder-to-store-your-experiment-files","text":"Create a folder on your computer to put the experiment files in. We'll call this \"MyExperiment\" for the tutorial. Add a subfolder called jspsych . Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the dist folder into the jspsych folder. It should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc2 jspsych ---- \ud83d\udcc4 jspsych.js ---- \ud83d\udcc4 plugin-animation.js ---- \ud83d\udcc4 plugin-audio-keyboard-response.js ---- ...","title":"Step 2: Create a folder to store your experiment files"},{"location":"tutorials/hello-world/#step-3-create-an-html-file","text":"Tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is Visual Studio Code (Windows, OSX, Linux). Create a new file called experiment.html in the MyExperiment folder. The directory structure should look like this: \ud83d\udcc2 MyExperiment -- \ud83d\udcc4 experiment.html -- \ud83d\udcc2 jspsych There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > </ head > < body ></ body > </ html > Add the above code to the experiment.html file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'.","title":"Step 3: Create an HTML file"},{"location":"tutorials/hello-world/#step-4-load-the-jspsych-library","text":"To use jsPsych, add a <script> tag to load the library. Set the src attribute to the path to the jspsych.js file. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > </ head > < body ></ body > </ html > You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a <link> tag to the <head> section of the document. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > </ html >","title":"Step 4: Load the jsPsych library"},{"location":"tutorials/hello-world/#step-5-create-a-script-element-and-initialize-jspsych","text":"To add JavaScript code directly to the webpage we need to add a pair of <script> tags after the <body> tags. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > To initialize jsPsych we use the initJsPsych() function and assign the output to a new variable. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html >","title":"Step 5: Create a script element and initialize jsPsych"},{"location":"tutorials/hello-world/#step-6-use-a-plugin-to-print-a-message","text":"For this demo we want to show some text on the screen. This is exactly what the html-keyboard-response plugin is designed to do. To use the plugin, we need to load it with a <script> tag. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); </ script > </ html > Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to jsPsychHtmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } </ script > </ html >","title":"Step 6: Use a plugin to print a message"},{"location":"tutorials/hello-world/#step-7-run-the-experiment","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"jspsych/jspsych.js\" ></ script > < script src = \"jspsych/plugin-html-keyboard-response.js\" ></ script > < link href = \"jspsych/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > const jsPsych = initJsPsych (); const hello_trial = { type : jsPsychHtmlKeyboardResponse , stimulus : 'Hello world!' } jsPsych . run ([ hello_trial ]); </ script > </ html > Once you've saved the file, open it in a browser. You should see \"Hello world!\" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial).","title":"Step 7: Run the experiment"},{"location":"tutorials/hello-world/#option-3-using-npm","text":"If you are electing to use npm to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. We will also assume that you are using a webpack or a similar bundler. Info You may want to check out the jsPsych Builder CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles using webpack. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page.","title":"Option 3: Using NPM"},{"location":"tutorials/hello-world/#step-1-install-jspsych","text":"Run npm install jspsych . This installs the core jsPsych package. Plugins and extensions are installed separately.","title":"Step 1: Install jspsych"},{"location":"tutorials/hello-world/#step-2-import-the-initjspsych-function-and-create-a-new-jspsych-instance","text":"We create a new instance of the JsPsych class by calling initJsPsych . The instance can optionally be configured via a variety of options , passed as an object to initJsPsych . import { initJsPsych } from 'jspsych' ; const jsPsych = initJsPsych ();","title":"Step 2: Import the initJsPsych function and create a new JsPsych instance"},{"location":"tutorials/hello-world/#step-3-static-markup-and-css","text":"jsPsych requires nothing but a body element in your HTML document. For the jsPsych stylesheet, depending on your bundler setup, you can either directly import 'jspsych/css/jspsych.css' into your JavaScript file or add a link tag (like <link href=\"path/to/jspsych.css\" rel=\"stylesheet\" type=\"text/css\" /> ) to your HTML document's head.","title":"Step 3: Static markup and CSS"},{"location":"tutorials/hello-world/#step-4-install-and-import-a-plugin","text":"Install the html-keyboard-response plugin with: npm install @jspsych/plugin-html-keyboard-response Then import the htmlKeyboardResponse plugin class. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych ();","title":"Step 4: Install and import a plugin"},{"location":"tutorials/hello-world/#step-5-create-a-trial","text":"Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create an object with the property type equal to htmlKeyboardResponse . We can specify the other parameters of the plugin in the same object. Here we use the stimulus parameter to include a message. You can see the full set of parameters for each plugin on its documentation page . import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , }","title":"Step 5: Create a trial"},{"location":"tutorials/hello-world/#step-6-run","text":"Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the jsPsych.run function and passing in a timeline . For a simple experiment like this one, the timeline is just an array containing the list of trials to run. import { initJsPsych } from 'jspsych' ; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response' ; const jsPsych = initJsPsych (); const trial = { type : htmlKeyboardResponse , stimulus : 'Hello world!' , } jsPsych . run ([ trial ]);","title":"Step 6: Run"},{"location":"tutorials/rt-task/","text":"Summary of Tutorial Content \u00b6 This tutorial will work through the creation of a simple response time task. The task is to press one key for a blue colored circle and another key for an orange colored circle. Despite this simple task, the tutorial covers many of the key features of jsPsych, including: Using a plugin to create a standard trial. Combining plugins together to create new kinds of trials. Using timeline variables to maximize code reuse. Preloading media. Randomizing presentation order. Manipulating, filtering, and aggregating data. Using dynamic content to change the experiment parameters based on the participant's responses. Part 1: Creating a blank experiment \u00b6 Start by setting up a new HTML file with jsPsych, the html-keyboard-response plugin, and the jspsych.css file loaded. If you are unsure how to do this, follow the Hello World tutorial . You should have an HTML document that looks like this: Info: Loading jsPsych This tutorial assumes that you are using the CDN-based method of loading jsPsych . If you are using another method then everything is the same except for how jsPsych is loaded. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > This will be our starting point for building the rest of the experiment. Part 2: Display welcome message \u00b6 First we have to initialize jsPsych. We can do this using the initJsPsych() function , and saving the result to a variable called jsPsych . var jsPsych = initJsPsych (); All jsPsych experiments are defined by a timeline. The timeline is an array that contains the set of trials we want to run in the experiment. We can start by defining an empty timeline array. We'll add trials to this array as we create them. var timeline = []; Let's greet the participant with a simple welcome message using the html-keyboard-response plugin. First, we create a trial that uses the html-keyboard-response plugin and contains a simple string to show the participant. As explained on the plugins documentation page , the trial object must have a type parameter that tells jsPsych which plugin to use. The value of type is similar to the plugin name, but starts with jsPsych and is written in camel case rather than with dashes. So to use the html-keyboard-response plugin, we need to write jsPsychHtmlKeyboardResponse as the trial type. var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; Next, we push the welcome trial to the timeline, which adds it to the end of the array. timeline . push ( welcome ); Finally, we tell jsPsych to run the experiment by calling the jsPsych.run() function and passing in the array that defines the experiment timeline. jsPsych . run ( timeline ); After each step in the tutorial you can view the complete code up to that point by clicking on the expandable box below. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 3: Show instructions \u00b6 We can use the same basic structure from part 2 to create a new html-keyboard-response trial that shows instructions to the participant. The only difference in this trial is that we will use HTML formatting to control how the instructions display and we will add a two second gap after the trial using the post_trial_gap parameter. The trial definition looks like this: var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; Tip In JavaScript there are three different ways to define a string . You can use single quotes ' , double quotes \" , or backticks ` . Using backticks has two advantages over the other approaches, especially when you are creating long strings with HTML. You can extend the string across multiple lines and you can use template strings to easily incorporate variables. Notice that the HTML includes <img> tags to display the images that the participant will be responding to. You'll need to download these image files. Right-click on each image below and select Save image as... . Put the images in a folder called img in the experiment folder you created in part 1. Don't forget to add the trial to the timeline: timeline . push ( instructions ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 4: Displaying stimuli and getting responses \u00b6 Creating trials to show the stimuli is conceptually the same as creating a trial to show instructions, except that now we are displaying an image instead of text or html. This means we need to use a different plugin: image-keyboard-response . We need to start by loading this plugin by adding a <script> tag to the document. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > For now, we will just show each image once. The path to the image file should be set as the stimulus parameter. We will also set the option for which keys the participant is allowed to use to respond ( choices ) so that only the 'f' and 'j' keys are valid responses. var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; As usual, we need to add the trials to the timeline. timeline . push ( blue_trial , orange_trial ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 5: Preloading media \u00b6 Whenever we use media elements (images, audio, or video) in an experiment it is a good idea to preload them prior to needing them for a trial. By preloading media we ask the participant's browser to download the media ahead of needing it, so that when we do need to display or play it there is no lag from needing to download it. We are going to use the preload plugin to preload the two images. The media preloading section goes into a lot of detail about various options for preloading and different ways that you can use this plugin. Here we are simply going to give the plugin a list of the files that we want to be preloaded. First we need to add the preload plugin to our <head> section. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > We'll put this trial at the very start of the experiment, so add this code before the welcome trial. var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; As always, add the trial to the timeline. timeline . push ( preload ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 6: Timeline variables \u00b6 In the full experiment, we will want more than two trials. One way we could do this is to create many more objects that define trials and push them all onto the timeline, but there is a more efficient way: using timeline variables. The parameters for showing the blue and orange circle are very similar. The only difference is which image is displayed. Timeline variables allow us to define the procedure for showing the stimulus once, and then repeatedly use it with different variables. We'll see how, even in this relatively simple case, this can save us a lot of lines of code. To start, let's make an array that contains all the different trials we want to run in the test phase. There are only two for the experiment: blue trials and orange trials. var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; Instead of just showing the blue and orange circles, let's also set up the experiment to show a fixation cross (+) in between trials. We can define a trial to show the fixation cross for a fixed amount of time by using the trial_duration parameter of the html-keyboard-response plugin and setting the choices parameter to the special value \"NO_KEYS\" , which means that no responses will be accepted as a valid response and the trial will last however long the trial_duration parameter specifies. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; To show the circles, we'll set up another trial with the image-keyboard-response plugin, but we'll use the function jsPsych.timelineVariable() to indicate that we want jsPsych to substitute the value of the parameter in from the timeline variables. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] } To link the variables that we declared in the test_stimuli array with the call to jsPsych.timelineVariable() we need to create a new timeline and set the timeline_variables property: var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli } We have to add the test_procedure to the main timeline array, but the fixation and test trial do not need to be added to timeline because they already exist on the test_procedure timeline. timeline . push ( test_procedure ); What happens when the experiment reaches the test procedure? jsPsych will run the test_procedure timeline one time for each entry in the test_stimuli array (two times total, in this case). The first time through, jsPsych will substitute the timeline variables from the first array entry (blue image), and the second time through the second array entry will be used (orange image). Notice that the fixation trial occurs before both the orange and the blue circles, because the entire timeline of the test_procedure is repeated for each entry in the timeline_variables array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 7: Parameters for timelines with timeline variables \u00b6 Right now our experiment is a measly two trials long. Even worse is that the order of the stimuli is the same every time! When we use timeline variables, we get access to some methods to randomize the order and repeat the trials. To randomize the order, simply set randomize_order: true on the object with the timeline_variables : var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true }; We can also easily make the test phase longer by setting the repetitions parameter. This parameter controls how many times the experiment will loop through all of the entries in the timeline_variables array. For example, if we set repetitions: 5 , then the experiment will loop through the two entries in the timeline_variables 5 times, for a total of 10 test trials. var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; Info: Randomizing timeline variables In a timeline variables procedure, when randomize_order is true and repetitions is greater than 1, the trial order will be re-randomized on each repetition through the timeline_variables array. This means that there will be some constraints on the randomization of all trials in the procedure. For example, if a timeline_variables array contains one trial per stimulus, then the same stimulus could occur twice in a row (since it could be at the end of one repetition and the start of the next one), but it could not be repeated more than twice in a row, regardless of the number of repetitions . If you want to repeat your timeline_variables array but randomize across all trials, you could use the sample parameter with the fixed-repetitions option: this will combine all the repeitions of your timeline_variables array into one larger array, and then randomize the whole thing. You can read more about the randomization, repetition, and sampling options for timeline variables in the Timeline Variables documentation . The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 8: Using functions to generate parameters \u00b6 One aspect of the experiment that could be improved is the duration of the fixation cross. As the experiment stands right now, the timing of the circles appearing is very predictable. We can change that by using a different value for the trial_duration parameter in the fixation trial for each trial. But how can we do that and keep the simple code structure we have now where we only have to define the fixation trial once? One option would be to add another timeline variable, like \"fixation_duration\" and use that to control the timing. But another option is to specify the trial_duration parameter as a function. If a parameter is a function, jsPsych will execute the function every time the trial runs. That means that if the function returns different results probabilistically, we can get a different parameter value every time the trial runs. To do that here, we'll use one of the built-in randomization methods in jsPsych's randomization module . jsPsych.randomization.sampleWithoutReplacement() takes an array of items to sample from and generates a new array of length N by sampling without replacement. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } } In the code above, we replaced the trial_duration: 1000 parameter in fixation with a function. Inside the function, we take a sample from the array [250, 500, 750, 1000, 1250, 1500, 1750, 2000] of size 1 (second parameter to jsPsych.randomization.sampleWithoutReplacement ). The return value from calling jsPsych.randomization.sampleWithoutReplacement is an array of length 1, so we add the [0] selection at the end to get the value out of the array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 10: Displaying the data \u00b6 We have created a complete, if simple, experiment at this point, so let's take a look at the data being generated. jsPsych has a built-in function called jsPsych.data.displayData() that is useful for debugging your experiment. It will remove all of the information on the screen and replace it with the raw data collected so far. This isn't terribly useful when you are actually running an experiment, but it's nice for checking the data during development. We need the displayData function to execute when the experiment ends. One way to do this is to use the on_finish callback function . This function will automatically execute once all the trials in the experiment are finished. We can specify this function in the experiment settings when we initialize jsPsych with the initJsPsych method. var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 11: Tagging trials with additional data \u00b6 All trials in jsPsych can be tagged with additional arbitrary data. This data will get stored alongside the data that the plugin normally generates, which allows experimenters to record properties of a trial along with the data from the trial. When might you use this feature? In this experiment, it would be nice to tag each trial with a circle as a response trial, so that the resulting data can be easily filtered to look at only the critical trials. We can do that like this. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' } }; We also could tag the test trials with a property that indicates what the correct response should be (F for the blue circles, J for the orange). In our current code, we are using the timeline variables feature of jsPsych to choose which circle gets presented on a trial. Since we want to tag the trials differently based on which circle is presented, we need to add the tagging data to the test_stimuli array, and then use the jsPsych.timelineVariable() function to get the value and assign it to a property in the data of the trial. We start by adding a \"correct_response\" property and value to each object in the test_stimuli : var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; Now we can use timelineVariable() in the data parameter of the test trial to get the appropriate \"correct_response\" value for each trial. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; Another kind of tagging that would be useful is to mark each fixation trial as such, to make removing the data from fixation trials easier. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 12: Manipulating data during the experiment \u00b6 Now that the data from the test trials has a tag that describes the correct response, it would be easy to analyze the data after the fact and calculate whether the participant responded correctly. But, we can also do this in jsPsych as the experiment runs to save time later and enable a limited set of data analysis directly in the experiment code. To do this, we'll use the on_finish event of the test trial. We can assign a function to on_finish , and that function will receive an object containing the data generated by the trial. This object can be manipulated inside the function, and any changes made to the object will be stored in jsPsych's internal representation of the data. For this example, we'll determine whether the participant responded correctly, and add a new correct property to the data object. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; The data.response value is a string representation of the key the participant pressed. We can compare this with the data.correct_response value, and assign this computed value to a new property data.correct . Info: The compareKeys function Here we are comparing the values of data.response and data.correct_response using a jsPsych function called jsPsych.pluginAPI.compareKeys . We're using this function because it allows us to compare keys in either a case sensitive or case insensitive way, depending on the case_sensitive_responses parameter in the experiment settings . The participant's key response will be recorded in a case-sensitive way in the data (e.g. 'f' or 'F'), but in most cases, we don't care if their response corresponds to an upper or lower case letter (which is why the case_sensitive_responses experiment setting is false by default). Using the jsPsych.pluginAPI.commpareKeys function here means that the response will be scored correctly, even if the participant holds down Shift or has Caps Lock on. This function is only relevant for keyboard responses; for other kinds of responses, such as button presses, you can simply compare the response and correct response values directly, e.g. data . correct = data . response === data . correct_response ; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html > Part 13: Data aggregation \u00b6 jsPsych provides a limited set of analysis functions to allow you to calculate things like mean response times for a selected set of trials. In this part, we'll use these functions to add a final trial to the experiment that tells the participant their accuracy and their mean response time for correct responses. We'll use the html-keyboard-response plugin. Because the text that we want to display changes based on the participant's performance in the experiment, we need to use a function for the stimulus parameter and return the desired text. Info: Dynamic parameters Using a function as the value of a 'normal' parameter (i.e. a parameter that isn't usually a function) provides lots of flexibility in jsPsych experiments, because it allows you to dynamically change the parameter's value based on the participant's earlier responses, and any other information that you don't know before the experiment has started. For more information and examples, see the dynamic parameter documentation page . Here's what the code looks like, and a description follows below. var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); To create the variable trials , we use jsPsych.data.get() which returns a jsPsych data collection containing all of the data from the experiment. We can then use .filter to select only the trials where task is 'response' (a benefit of tagging the trials in part 11). trials contains all of the data from the trials where a circle was shown. To get only the correct trials, we can use .filter() again to select only the trials from the trials data collection where the property correct is true . To calculate accuracy, we can use the .count() method to determine how many trials were correct and how many trials there were total. We also use Math.round() to avoid extra digits after the decimal. Finally, to calculate the mean response time on correct trials, we use the .select method on the correct_trials data collection to select only the 'rt' property of those trials. We can then use the .mean() method to find the mean of all the RT values. The final code \u00b6 This code is available in the /examples folder in the jsPsych release download. It is called demo-simple-rt-task.html . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , repetitions : 5 , randomize_order : true }; timeline . push ( test_procedure ); /* define debrief */ var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Demo Experiment: Simple Reaction Time Task"},{"location":"tutorials/rt-task/#summary-of-tutorial-content","text":"This tutorial will work through the creation of a simple response time task. The task is to press one key for a blue colored circle and another key for an orange colored circle. Despite this simple task, the tutorial covers many of the key features of jsPsych, including: Using a plugin to create a standard trial. Combining plugins together to create new kinds of trials. Using timeline variables to maximize code reuse. Preloading media. Randomizing presentation order. Manipulating, filtering, and aggregating data. Using dynamic content to change the experiment parameters based on the participant's responses.","title":"Summary of Tutorial Content"},{"location":"tutorials/rt-task/#part-1-creating-a-blank-experiment","text":"Start by setting up a new HTML file with jsPsych, the html-keyboard-response plugin, and the jspsych.css file loaded. If you are unsure how to do this, follow the Hello World tutorial . You should have an HTML document that looks like this: Info: Loading jsPsych This tutorial assumes that you are using the CDN-based method of loading jsPsych . If you are using another method then everything is the same except for how jsPsych is loaded. <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > </ script > </ html > This will be our starting point for building the rest of the experiment.","title":"Part 1: Creating a blank experiment"},{"location":"tutorials/rt-task/#part-2-display-welcome-message","text":"First we have to initialize jsPsych. We can do this using the initJsPsych() function , and saving the result to a variable called jsPsych . var jsPsych = initJsPsych (); All jsPsych experiments are defined by a timeline. The timeline is an array that contains the set of trials we want to run in the experiment. We can start by defining an empty timeline array. We'll add trials to this array as we create them. var timeline = []; Let's greet the participant with a simple welcome message using the html-keyboard-response plugin. First, we create a trial that uses the html-keyboard-response plugin and contains a simple string to show the participant. As explained on the plugins documentation page , the trial object must have a type parameter that tells jsPsych which plugin to use. The value of type is similar to the plugin name, but starts with jsPsych and is written in camel case rather than with dashes. So to use the html-keyboard-response plugin, we need to write jsPsychHtmlKeyboardResponse as the trial type. var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; Next, we push the welcome trial to the timeline, which adds it to the end of the array. timeline . push ( welcome ); Finally, we tell jsPsych to run the experiment by calling the jsPsych.run() function and passing in the array that defines the experiment timeline. jsPsych . run ( timeline ); After each step in the tutorial you can view the complete code up to that point by clicking on the expandable box below. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 2: Display welcome message"},{"location":"tutorials/rt-task/#part-3-show-instructions","text":"We can use the same basic structure from part 2 to create a new html-keyboard-response trial that shows instructions to the participant. The only difference in this trial is that we will use HTML formatting to control how the instructions display and we will add a two second gap after the trial using the post_trial_gap parameter. The trial definition looks like this: var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; Tip In JavaScript there are three different ways to define a string . You can use single quotes ' , double quotes \" , or backticks ` . Using backticks has two advantages over the other approaches, especially when you are creating long strings with HTML. You can extend the string across multiple lines and you can use template strings to easily incorporate variables. Notice that the HTML includes <img> tags to display the images that the participant will be responding to. You'll need to download these image files. Right-click on each image below and select Save image as... . Put the images in a folder called img in the experiment folder you created in part 1. Don't forget to add the trial to the timeline: timeline . push ( instructions ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 3: Show instructions"},{"location":"tutorials/rt-task/#part-4-displaying-stimuli-and-getting-responses","text":"Creating trials to show the stimuli is conceptually the same as creating a trial to show instructions, except that now we are displaying an image instead of text or html. This means we need to use a different plugin: image-keyboard-response . We need to start by loading this plugin by adding a <script> tag to the document. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > For now, we will just show each image once. The path to the image file should be set as the stimulus parameter. We will also set the option for which keys the participant is allowed to use to respond ( choices ) so that only the 'f' and 'j' keys are valid responses. var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; As usual, we need to add the trials to the timeline. timeline . push ( blue_trial , orange_trial ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 4: Displaying stimuli and getting responses"},{"location":"tutorials/rt-task/#part-5-preloading-media","text":"Whenever we use media elements (images, audio, or video) in an experiment it is a good idea to preload them prior to needing them for a trial. By preloading media we ask the participant's browser to download the media ahead of needing it, so that when we do need to display or play it there is no lag from needing to download it. We are going to use the preload plugin to preload the two images. The media preloading section goes into a lot of detail about various options for preloading and different ways that you can use this plugin. Here we are simply going to give the plugin a list of the files that we want to be preloaded. First we need to add the preload plugin to our <head> section. < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > We'll put this trial at the very start of the experiment, so add this code before the welcome trial. var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; As always, add the trial to the timeline. timeline . push ( preload ); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define test trials */ var blue_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/blue.png' , choices : [ 'f' , 'j' ] }; var orange_trial = { type : jsPsychImageKeyboardResponse , stimulus : 'img/orange.png' , choices : [ 'f' , 'j' ] }; timeline . push ( blue_trial , orange_trial ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 5: Preloading media"},{"location":"tutorials/rt-task/#part-6-timeline-variables","text":"In the full experiment, we will want more than two trials. One way we could do this is to create many more objects that define trials and push them all onto the timeline, but there is a more efficient way: using timeline variables. The parameters for showing the blue and orange circle are very similar. The only difference is which image is displayed. Timeline variables allow us to define the procedure for showing the stimulus once, and then repeatedly use it with different variables. We'll see how, even in this relatively simple case, this can save us a lot of lines of code. To start, let's make an array that contains all the different trials we want to run in the test phase. There are only two for the experiment: blue trials and orange trials. var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; Instead of just showing the blue and orange circles, let's also set up the experiment to show a fixation cross (+) in between trials. We can define a trial to show the fixation cross for a fixed amount of time by using the trial_duration parameter of the html-keyboard-response plugin and setting the choices parameter to the special value \"NO_KEYS\" , which means that no responses will be accepted as a valid response and the trial will last however long the trial_duration parameter specifies. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; To show the circles, we'll set up another trial with the image-keyboard-response plugin, but we'll use the function jsPsych.timelineVariable() to indicate that we want jsPsych to substitute the value of the parameter in from the timeline variables. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] } To link the variables that we declared in the test_stimuli array with the call to jsPsych.timelineVariable() we need to create a new timeline and set the timeline_variables property: var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli } We have to add the test_procedure to the main timeline array, but the fixation and test trial do not need to be added to timeline because they already exist on the test_procedure timeline. timeline . push ( test_procedure ); What happens when the experiment reaches the test procedure? jsPsych will run the test_procedure timeline one time for each entry in the test_stimuli array (two times total, in this case). The first time through, jsPsych will substitute the timeline variables from the first array entry (blue image), and the second time through the second array entry will be used (orange image). Notice that the fixation trial occurs before both the orange and the blue circles, because the entire timeline of the test_procedure is repeated for each entry in the timeline_variables array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 6: Timeline variables"},{"location":"tutorials/rt-task/#part-7-parameters-for-timelines-with-timeline-variables","text":"Right now our experiment is a measly two trials long. Even worse is that the order of the stimuli is the same every time! When we use timeline variables, we get access to some methods to randomize the order and repeat the trials. To randomize the order, simply set randomize_order: true on the object with the timeline_variables : var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true }; We can also easily make the test phase longer by setting the repetitions parameter. This parameter controls how many times the experiment will loop through all of the entries in the timeline_variables array. For example, if we set repetitions: 5 , then the experiment will loop through the two entries in the timeline_variables 5 times, for a total of 10 test trials. var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; Info: Randomizing timeline variables In a timeline variables procedure, when randomize_order is true and repetitions is greater than 1, the trial order will be re-randomized on each repetition through the timeline_variables array. This means that there will be some constraints on the randomization of all trials in the procedure. For example, if a timeline_variables array contains one trial per stimulus, then the same stimulus could occur twice in a row (since it could be at the end of one repetition and the start of the next one), but it could not be repeated more than twice in a row, regardless of the number of repetitions . If you want to repeat your timeline_variables array but randomize across all trials, you could use the sample parameter with the fixed-repetitions option: this will combine all the repeitions of your timeline_variables array into one larger array, and then randomize the whole thing. You can read more about the randomization, repetition, and sampling options for timeline variables in the Timeline Variables documentation . The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : 1000 , }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 7: Parameters for timelines with timeline variables"},{"location":"tutorials/rt-task/#part-8-using-functions-to-generate-parameters","text":"One aspect of the experiment that could be improved is the duration of the fixation cross. As the experiment stands right now, the timing of the circles appearing is very predictable. We can change that by using a different value for the trial_duration parameter in the fixation trial for each trial. But how can we do that and keep the simple code structure we have now where we only have to define the fixation trial once? One option would be to add another timeline variable, like \"fixation_duration\" and use that to control the timing. But another option is to specify the trial_duration parameter as a function. If a parameter is a function, jsPsych will execute the function every time the trial runs. That means that if the function returns different results probabilistically, we can get a different parameter value every time the trial runs. To do that here, we'll use one of the built-in randomization methods in jsPsych's randomization module . jsPsych.randomization.sampleWithoutReplacement() takes an array of items to sample from and generates a new array of length N by sampling without replacement. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } } In the code above, we replaced the trial_duration: 1000 parameter in fixation with a function. Inside the function, we take a sample from the array [250, 500, 750, 1000, 1250, 1500, 1750, 2000] of size 1 (second parameter to jsPsych.randomization.sampleWithoutReplacement ). The return value from calling jsPsych.randomization.sampleWithoutReplacement is an array of length 1, so we add the [0] selection at the end to get the value out of the array. The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych (); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] } timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 8: Using functions to generate parameters"},{"location":"tutorials/rt-task/#part-10-displaying-the-data","text":"We have created a complete, if simple, experiment at this point, so let's take a look at the data being generated. jsPsych has a built-in function called jsPsych.data.displayData() that is useful for debugging your experiment. It will remove all of the information on the screen and replace it with the raw data collected so far. This isn't terribly useful when you are actually running an experiment, but it's nice for checking the data during development. We need the displayData function to execute when the experiment ends. One way to do this is to use the on_finish callback function . This function will automatically execute once all the trials in the experiment are finished. We can specify this function in the experiment settings when we initialize jsPsych with the initJsPsych method. var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" }, { stimulus : \"img/orange.png\" } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ] }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 10: Displaying the data"},{"location":"tutorials/rt-task/#part-11-tagging-trials-with-additional-data","text":"All trials in jsPsych can be tagged with additional arbitrary data. This data will get stored alongside the data that the plugin normally generates, which allows experimenters to record properties of a trial along with the data from the trial. When might you use this feature? In this experiment, it would be nice to tag each trial with a circle as a response trial, so that the resulting data can be easily filtered to look at only the critical trials. We can do that like this. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' } }; We also could tag the test trials with a property that indicates what the correct response should be (F for the blue circles, J for the orange). In our current code, we are using the timeline variables feature of jsPsych to choose which circle gets presented on a trial. Since we want to tag the trials differently based on which circle is presented, we need to add the tagging data to the test_stimuli array, and then use the jsPsych.timelineVariable() function to get the value and assign it to a property in the data of the trial. We start by adding a \"correct_response\" property and value to each object in the test_stimuli : var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; Now we can use timelineVariable() in the data parameter of the test trial to get the appropriate \"correct_response\" value for each trial. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; Another kind of tagging that would be useful is to mark each fixation trial as such, to make removing the data from fixation trials easier. var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 11: Tagging trials with additional data"},{"location":"tutorials/rt-task/#part-12-manipulating-data-during-the-experiment","text":"Now that the data from the test trials has a tag that describes the correct response, it would be easy to analyze the data after the fact and calculate whether the participant responded correctly. But, we can also do this in jsPsych as the experiment runs to save time later and enable a limited set of data analysis directly in the experiment code. To do this, we'll use the on_finish event of the test trial. We can assign a function to on_finish , and that function will receive an object containing the data generated by the trial. This object can be manipulated inside the function, and any changes made to the object will be stored in jsPsych's internal representation of the data. For this example, we'll determine whether the participant responded correctly, and add a new correct property to the data object. var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; The data.response value is a string representation of the key the participant pressed. We can compare this with the data.correct_response value, and assign this computed value to a new property data.correct . Info: The compareKeys function Here we are comparing the values of data.response and data.correct_response using a jsPsych function called jsPsych.pluginAPI.compareKeys . We're using this function because it allows us to compare keys in either a case sensitive or case insensitive way, depending on the case_sensitive_responses parameter in the experiment settings . The participant's key response will be recorded in a case-sensitive way in the data (e.g. 'f' or 'F'), but in most cases, we don't care if their response corresponds to an upper or lower case letter (which is why the case_sensitive_responses experiment setting is false by default). Using the jsPsych.pluginAPI.commpareKeys function here means that the response will be scored correctly, even if the participant holds down Shift or has Caps Lock on. This function is only relevant for keyboard responses; for other kinds of responses, such as button presses, you can simply compare the response and correct response values directly, e.g. data . correct = data . response === data . correct_response ; The complete code so far <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , randomize_order : true , repetitions : 5 }; timeline . push ( test_procedure ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"Part 12: Manipulating data during the experiment"},{"location":"tutorials/rt-task/#part-13-data-aggregation","text":"jsPsych provides a limited set of analysis functions to allow you to calculate things like mean response times for a selected set of trials. In this part, we'll use these functions to add a final trial to the experiment that tells the participant their accuracy and their mean response time for correct responses. We'll use the html-keyboard-response plugin. Because the text that we want to display changes based on the participant's performance in the experiment, we need to use a function for the stimulus parameter and return the desired text. Info: Dynamic parameters Using a function as the value of a 'normal' parameter (i.e. a parameter that isn't usually a function) provides lots of flexibility in jsPsych experiments, because it allows you to dynamically change the parameter's value based on the participant's earlier responses, and any other information that you don't know before the experiment has started. For more information and examples, see the dynamic parameter documentation page . Here's what the code looks like, and a description follows below. var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); To create the variable trials , we use jsPsych.data.get() which returns a jsPsych data collection containing all of the data from the experiment. We can then use .filter to select only the trials where task is 'response' (a benefit of tagging the trials in part 11). trials contains all of the data from the trials where a circle was shown. To get only the correct trials, we can use .filter() again to select only the trials from the trials data collection where the property correct is true . To calculate accuracy, we can use the .count() method to determine how many trials were correct and how many trials there were total. We also use Math.round() to avoid extra digits after the decimal. Finally, to calculate the mean response time on correct trials, we use the .select method on the correct_trials data collection to select only the 'rt' property of those trials. We can then use the .mean() method to find the mean of all the RT values.","title":"Part 13: Data aggregation"},{"location":"tutorials/rt-task/#the-final-code","text":"This code is available in the /examples folder in the jsPsych release download. It is called demo-simple-rt-task.html . <!DOCTYPE html> < html > < head > < title > My experiment </ title > < script src = \"https://unpkg.com/jspsych@7.3.0\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-html-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-image-keyboard-response@1.1.2\" ></ script > < script src = \"https://unpkg.com/@jspsych/plugin-preload@1.1.2\" ></ script > < link href = \"https://unpkg.com/jspsych@7.3.0/css/jspsych.css\" rel = \"stylesheet\" type = \"text/css\" /> </ head > < body ></ body > < script > /* initialize jsPsych */ var jsPsych = initJsPsych ({ on_finish : function () { jsPsych . data . displayData (); } }); /* create timeline */ var timeline = []; /* preload images */ var preload = { type : jsPsychPreload , images : [ 'img/blue.png' , 'img/orange.png' ] }; timeline . push ( preload ); /* define welcome message trial */ var welcome = { type : jsPsychHtmlKeyboardResponse , stimulus : \"Welcome to the experiment. Press any key to begin.\" }; timeline . push ( welcome ); /* define instructions trial */ var instructions = { type : jsPsychHtmlKeyboardResponse , stimulus : ` <p>In this experiment, a circle will appear in the center of the screen.</p><p>If the circle is <strong>blue</strong>, press the letter F on the keyboard as fast as you can.</p> <p>If the circle is <strong>orange</strong>, press the letter J as fast as you can.</p> <div style='width: 700px;'> <div style='float: left;'><img src='img/blue.png'></img> <p class='small'><strong>Press the F key</strong></p></div> <div style='float: right;'><img src='img/orange.png'></img> <p class='small'><strong>Press the J key</strong></p></div> </div> <p>Press any key to begin.</p> ` , post_trial_gap : 2000 }; timeline . push ( instructions ); /* define trial stimuli array for timeline variables */ var test_stimuli = [ { stimulus : \"img/blue.png\" , correct_response : 'f' }, { stimulus : \"img/orange.png\" , correct_response : 'j' } ]; /* define fixation and test trials */ var fixation = { type : jsPsychHtmlKeyboardResponse , stimulus : '<div style=\"font-size:60px;\">+</div>' , choices : \"NO_KEYS\" , trial_duration : function (){ return jsPsych . randomization . sampleWithoutReplacement ([ 250 , 500 , 750 , 1000 , 1250 , 1500 , 1750 , 2000 ], 1 )[ 0 ]; }, data : { task : 'fixation' } }; var test = { type : jsPsychImageKeyboardResponse , stimulus : jsPsych . timelineVariable ( 'stimulus' ), choices : [ 'f' , 'j' ], data : { task : 'response' , correct_response : jsPsych . timelineVariable ( 'correct_response' ) }, on_finish : function ( data ){ data . correct = jsPsych . pluginAPI . compareKeys ( data . response , data . correct_response ); } }; /* define test procedure */ var test_procedure = { timeline : [ fixation , test ], timeline_variables : test_stimuli , repetitions : 5 , randomize_order : true }; timeline . push ( test_procedure ); /* define debrief */ var debrief_block = { type : jsPsychHtmlKeyboardResponse , stimulus : function () { var trials = jsPsych . data . get (). filter ({ task : 'response' }); var correct_trials = trials . filter ({ correct : true }); var accuracy = Math . round ( correct_trials . count () / trials . count () * 100 ); var rt = Math . round ( correct_trials . select ( 'rt' ). mean ()); return `<p>You responded correctly on ${ accuracy } % of the trials.</p> <p>Your average response time was ${ rt } ms.</p> <p>Press any key to complete the experiment. Thank you!</p>` ; } }; timeline . push ( debrief_block ); /* start the experiment */ jsPsych . run ( timeline ); </ script > </ html >","title":"The final code"},{"location":"tutorials/video-tutorials/","text":"Video tutorials \u00b6 Warning Most of these videos are using version 6.x of jsPsych. Using version 7.x requires a few changes that are not covered in these videos. We recommend starting with the tutorials on this website to understand how to work with 7.x and then watching these videos for additional information. Much of the content covered in the videos still applies to 7.x , but you'll need a solid understanding of how to use 7.x in order to make use of the examples in the videos. YouTube Channel \u00b6 A variety of video tutorials are available on Josh de Leeuw's YouTube channel . Some tutorials walk through creating a basic version of an entire experiment, like the tutorial on creating a dichotic listening experiment aimed at new users. Others focus on specific features of jsPsych, like how to use functions as parameters to create experiments that change in response to participant input or how to create a new plugin . Workshops \u00b6 Moving Research Online (2020) . Recordings from a Summer 2020 workshop on conducting online research are available on the workshop's YouTube channel . Session 1 provides an overview of jsPsych suitable for brand new users. Session 3 covers some more advanced features of jsPsych. This workshop was funded by the National Science Foundation. babySTEP (2021) . The Centre for Comparative Psycholinguistics (CCP, University of Alberta Department of Linguistics) hosted a two-part jsPsych workshop in 2021 as part of their annual STEP program . Day 1 covered the basics of creating a jsPsych experiment, with an emphasis on audio stimuli. Day 2 was organized around pre-submitted questions. The video demonstrates how to create a more complex experiment involving reading a sentence and hearing different audio options for completing the sentences, and answers several questions about timing accuracy, recording participant generated audio, embedding jsPsych into course (or other) websites, and some (non-empirical) advice about attention checks.","title":"Video Tutorials"},{"location":"tutorials/video-tutorials/#video-tutorials","text":"Warning Most of these videos are using version 6.x of jsPsych. Using version 7.x requires a few changes that are not covered in these videos. We recommend starting with the tutorials on this website to understand how to work with 7.x and then watching these videos for additional information. Much of the content covered in the videos still applies to 7.x , but you'll need a solid understanding of how to use 7.x in order to make use of the examples in the videos.","title":"Video tutorials"},{"location":"tutorials/video-tutorials/#youtube-channel","text":"A variety of video tutorials are available on Josh de Leeuw's YouTube channel . Some tutorials walk through creating a basic version of an entire experiment, like the tutorial on creating a dichotic listening experiment aimed at new users. Others focus on specific features of jsPsych, like how to use functions as parameters to create experiments that change in response to participant input or how to create a new plugin .","title":"YouTube Channel"},{"location":"tutorials/video-tutorials/#workshops","text":"Moving Research Online (2020) . Recordings from a Summer 2020 workshop on conducting online research are available on the workshop's YouTube channel . Session 1 provides an overview of jsPsych suitable for brand new users. Session 3 covers some more advanced features of jsPsych. This workshop was funded by the National Science Foundation. babySTEP (2021) . The Centre for Comparative Psycholinguistics (CCP, University of Alberta Department of Linguistics) hosted a two-part jsPsych workshop in 2021 as part of their annual STEP program . Day 1 covered the basics of creating a jsPsych experiment, with an emphasis on audio stimuli. Day 2 was organized around pre-submitted questions. The video demonstrates how to create a more complex experiment involving reading a sentence and hearing different audio options for completing the sentences, and answers several questions about timing accuracy, recording participant generated audio, embedding jsPsych into course (or other) websites, and some (non-empirical) advice about attention checks.","title":"Workshops"}]}
\ No newline at end of file
diff --git a/7.3/sitemap.xml.gz b/7.3/sitemap.xml.gz
index 595be1e55b325d5b4e25cd64af2a922a6170a4ea..57db29fc5e0985b37c218dc079bd567f2d4baf4d 100644
GIT binary patch
delta 15
Wcmcb^eute+zMF$Xe9uO<Ys>&BV+85|

delta 15
Wcmcb^eute+zMF%iW%ow5Ys>&D>;+Z;