mirror of
https://github.com/jspsych/jsPsych.git
synced 2025-05-10 11:10:54 +00:00
forgot to stage stuff in the last commit; here it is!
This commit is contained in:
Josh de Leeuw
parent
b8bbcd2f01
commit
e6bfbd8c72
@ -1,43 +0,0 @@
|
||||
# Contributing to jsPsych
|
||||
|
||||
Contributions to jsPsych are welcome! All of the code is managed through the GitHub repository.
|
||||
|
||||
## Steps for modifying the code
|
||||
|
||||
#### Discuss the proposed change
|
||||
|
||||
If you have a specific modification in mind -- for instance, a new feature or bug fix -- please open a [new issue via GitHub](https://github.com/jspsych/jsPsych/issues/new). Describe the proposed change and what functionality it adds to the library and/or what problem it solves. If you are interested in adding a new plugin to the library, it helps if you post an example of the plugin in use and describe the different use cases of the plugin (for more guidance, see the "Writing new plugins" section below).
|
||||
|
||||
If you are thinking about proposing a change but not at the point where you have a specific modification to the code base in mind, then it might be helpful to discuss the issue first on [GitHub Discussions](https://github.com/jspsych/jsPsych/discussions). Discussion posts can be useful for sharing code and getting feedback before requesting a change to the library.
|
||||
|
||||
#### Fork the library and modify the code
|
||||
|
||||
To make changes to the code, you should fork the jsPsych library via GitHub and make modifications on your fork. You may find it useful to make modifications on branches, so that you can keep your proposed changes separate from any other unrelated changes you might want to make on your fork.
|
||||
|
||||
#### Submit a pull request
|
||||
|
||||
Once your modification is complete, submit a pull request to merge your changes into the `master` branch of the main repository. Pull requests will be reviewed by the project team.
|
||||
|
||||
## Writing new plugins
|
||||
|
||||
New plugins are welcome additions to the library. Plugins can be distributed independently of the main library or added to the GitHub repository via a pull request, following the process described above. If you want to add your plugin to the main library then there are a few guidelines to follow.
|
||||
|
||||
#### Make the plugin as general as possible
|
||||
|
||||
Plugins are most useful when they are flexible. Avoid fixing the value of parameters that could be variables. This is especially important for any text that displays on the screen in order to facilitate use in multiple languages.
|
||||
|
||||
#### Use the jsPsych.pluginAPI module when appropriate
|
||||
|
||||
The [pluginAPI module](../core_library/jspsych-pluginAPI.md) contains functions relevant to plugin development. Avoid duplicating the functions defined within the library in your plugin, and instead use the pluginAPI whenever possible. If you have a suggestion for improving pluginAPI methods, then go ahead and submit a pull request to modify it directly.
|
||||
|
||||
#### Document your plugin
|
||||
|
||||
When submitting a pull request to add your plugin, make sure to include a documentation page in the same style as the other docs pages. Documentation files exist in the `docs` directory.
|
||||
|
||||
#### Include an example file
|
||||
|
||||
Write a short example HTML file to include in the `examples` directory. This should demonstrate the basic use cases of the plugin as clearly as possible.
|
||||
|
||||
#### Include a testing file
|
||||
|
||||
Automated code testing for jsPsych is implemented with [Jest](https://facebook.github.io/jest/). To run the tests, install Node and npm. Run `npm install` in the root jsPsych directory. Then run `npm test`. Plugins should have a testing file that validates the behavior of all the plugin parameters. See the `/tests/plugins` directory for examples.
|
||||
@ -1,25 +1,7 @@
|
||||
# License
|
||||
|
||||
jsPsych is licensed under the MIT license.
|
||||
jsPsych is [licensed](https://github.com/jspsych/jsPsych/blob/main/license.txt) under the MIT license.
|
||||
|
||||
>The MIT License (MIT)
|
||||
>
|
||||
>Copyright (c) 2019 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.
|
||||
```
|
||||
--8<-- "license.txt"
|
||||
```
|
||||
@ -1,7 +0,0 @@
|
||||
# Support
|
||||
|
||||
For questions about jsPsych the preferred method of support is via [GitHub Discussions](https://github.com/jspsych/jsPsych/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.
|
||||
|
||||
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](https://github.com/jspsych/jsPsych/issues/new) on the GitHub site. And if you have a suggestion for fixing the problem, feel free to propose a modification by following the steps in the [Contribuitng to jsPsych](contributing.md) page.
|
||||
|
||||
Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to [josh.deleeuw@gmail.com](mailto:josh.deleeuw@gmail.com).
|
||||
15
docs/developers/configuration.md
Normal file
15
docs/developers/configuration.md
Normal file
@ -0,0 +1,15 @@
|
||||
# Configuring the jsPsych development environment
|
||||
|
||||
|
||||
|
||||
## Testing
|
||||
|
||||
Automated code testing for jsPsych is implemented with [Jest](https://jestjs.io/).
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
44
docs/developers/contributing.md
Normal file
44
docs/developers/contributing.md
Normal file
@ -0,0 +1,44 @@
|
||||
# Contributing to jsPsych
|
||||
|
||||
jsPsych is open source project with [numerous contributors](https://github.com/jspsych/jsPsych/graphs/contributors). The project is currently managed by the core team of Josh de Leeuw ([@jodeleeuw](https://github.com/jodeleeuw)), Becky Gilbert ([@becky-gilbert](https://github.com/becky-gilbert)), and Björn Luchterhandt ([@bjoluc](https://github.com/bjoluc)). 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](https://github.com/jspsych/jsPsych). There you can:
|
||||
|
||||
* Use [discussions](https://github.com/jspsych/jsPsych/discussions) to propose ideas for development and seek feedback on contributions, such as a new plugin.
|
||||
* Use [issues](https://github.com/jspsych/jsPsych/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](https://github.com/jspsych/jsPsych/pulls) with modifications to the codebase. Pull requests will be reviewed by one or more members of the core team.
|
||||
|
||||
## Guidelines for contibuting
|
||||
|
||||
### Contributing to the codebase
|
||||
|
||||
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](https://jestjs.io/) 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](/developers/configuring.md#testing) 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](https://github.com/jspsych/jsPsych/blob/main/docs/plugins/list-of-plugins.md) as well as the [mkdocs configuration file](https://github.com/jspsych/jsPsych/blob/main/mkdocs.yml) 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](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) to generate new releases and their corresponding release notes. [This is a good overview of changesets](https://github.com/atlassian/changesets/blob/main/docs/adding-a-changeset.md) 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](https://github.com/jspsych/jsPsych/blob/main/contributors.md). And thanks!
|
||||
|
||||
|
||||
### Contributing to the documentation
|
||||
|
||||
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](https://github.com/jspsych/jsPsych/tree/main/docs) of the repository. The documentation is built using [MkDocs](https://www.mkdocs.org/) and themed using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). 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](https://www.mkdocs.org/user-guide/installation/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/#installation). 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`
|
||||
|
||||
If you are developing a new plugin or extension there are two different repositories that you can contribute to: [`jspsych`](https://github.com/jspsych/jsPsych) or [`jspsych-contrib`](https://github.com/jspsych/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](https://github.com/jspsych/jsPsych/discussions/new) 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](https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-template-ts) or using our [JavaScript template](https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-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).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,44 +1,4 @@
|
||||
# Extensions
|
||||
|
||||
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
|
||||
|
||||
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 `jsPsych.init()`.
|
||||
|
||||
```html
|
||||
<head>
|
||||
<script src="jspsych/jspsych.js"></script>
|
||||
<script src="jspsych/extensions/some-extension.js"></script>
|
||||
</head>
|
||||
```
|
||||
|
||||
```js
|
||||
jsPsych.init({
|
||||
timeline: [...],
|
||||
extensions: [
|
||||
{type: 'some-extension', 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:
|
||||
|
||||
```js
|
||||
var trial = {
|
||||
extensions: [
|
||||
{type: 'some-extension', params: {...} }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## List of Extensions
|
||||
|
||||
Extension | Description
|
||||
------ | -----------
|
||||
[jspsych‑ext‑webgazer.js](../extensions/jspsych-ext-webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library.
|
||||
|
||||
## Writing an Extension
|
||||
# Extension development
|
||||
|
||||
To create a new extension you must create an object that supports a few event callbacks. A barebones extension file looks like this:
|
||||
|
||||
12
docs/extensions/list-of-extensions.md
Normal file
12
docs/extensions/list-of-extensions.md
Normal file
@ -0,0 +1,12 @@
|
||||
# List of Plugins
|
||||
|
||||
These are the extensions that are included in the jsPsych release.
|
||||
|
||||
Additional extensions may be available in the [community contributions repository](https://github.com/jspsych/jspsych-contrib).
|
||||
|
||||
For an overview of what extensions are and how they work, see our [extensions overview](/overview/extensions.md).
|
||||
|
||||
|
||||
Extension | Description
|
||||
------ | -----------
|
||||
[jspsych‑ext‑webgazer](../extensions/jspsych-ext-webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library.
|
||||
@ -72,7 +72,7 @@ var trial = {
|
||||
|
||||
## Aggregating and manipulating jsPsych data
|
||||
|
||||
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](../core_library/jspsych-data.md).
|
||||
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](/reference/jspsych-data.md).
|
||||
|
||||
Here are some examples of data collection manipulation.
|
||||
|
||||
|
||||
43
docs/overview/extensions.md
Normal file
43
docs/overview/extensions.md
Normal file
@ -0,0 +1,43 @@
|
||||
# Extensions
|
||||
|
||||
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
|
||||
|
||||
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 `jsPsych.init()`.
|
||||
|
||||
```html
|
||||
<head>
|
||||
<script src="jspsych/jspsych.js"></script>
|
||||
<script src="jspsych/extensions/some-extension.js"></script>
|
||||
</head>
|
||||
```
|
||||
|
||||
```js
|
||||
jsPsych.init({
|
||||
timeline: [...],
|
||||
extensions: [
|
||||
{type: 'some-extension', 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:
|
||||
|
||||
```js
|
||||
var trial = {
|
||||
extensions: [
|
||||
{type: 'some-extension', params: {...} }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## List of Extensions
|
||||
|
||||
Extension | Description
|
||||
------ | -----------
|
||||
[jspsych‑ext‑webgazer.js](../extensions/jspsych-ext-webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library.
|
||||
|
||||
## Writing an Extension
|
||||
|
||||
See our [developer's guide for extensions](/developers/extension-development.md) for information about how to create a new extension.
|
||||
@ -4,7 +4,7 @@ A common use of jsPsych is to build an online experiment and find subjects using
|
||||
|
||||
## The jsPsych.turk module
|
||||
|
||||
The [jsPsych.turk](../core_library/jspsych-turk.md) module contains functions that are relevant for experiments running on Mechanical Turk.
|
||||
The [jsPsych.turk](/reference/jspsych-turk.md) module contains functions that are relevant for experiments running on Mechanical Turk.
|
||||
|
||||
## Creating an advertisement page
|
||||
|
||||
|
||||
@ -234,87 +234,4 @@ In addition to the data collected by a plugin, there is a default set of data th
|
||||
|
||||
## Creating a new plugin
|
||||
|
||||
You can add new kinds of tasks to jsPsych by creating new plugins, or modifying existing plugins. A task can be virtually any kind of activity. If it can be implemented in JavaScript, then it almost certainly can be turned into a jsPsych plugin.
|
||||
|
||||
### What's in a plugin file?
|
||||
|
||||
Plugin files follow a specific template. Adherence to the template is what allows jsPsych to run a plugin without knowing anything about what the plugin is doing. What makes plugins so flexible is that the template imposes very few requirements on the code. Here's what an empty plugin template looks like:
|
||||
|
||||
```js
|
||||
jsPsych.plugins['plugin-name'] = (function(){
|
||||
|
||||
var plugin = {};
|
||||
|
||||
plugin.info = {
|
||||
name: 'plugin-name',
|
||||
parameters: {
|
||||
}
|
||||
}
|
||||
|
||||
plugin.trial = function(display_element, trial){
|
||||
jsPsych.finishTrial();
|
||||
}
|
||||
|
||||
return plugin;
|
||||
|
||||
})();
|
||||
```
|
||||
|
||||
This plugin will work! It defines a plugin called 'plugin-name', and it does absolutely nothing. However, it won't break the experiment, and jsPsych will understand that this is a valid plugin.
|
||||
|
||||
Let's examine it in more detail.
|
||||
|
||||
The overall structure of the plugin is defined using a module JavaScript design pattern. This pattern uses a technique called an anonymous closure. This is why the first line has `(function(){` and the last line is `})();`. The details aren't important, but if you want to learn more about it, [this is a nice overview](http://www.adequatelygood.com/JavaScript-Module-Pattern-In-Depth.html). The reason this pattern is useful is because it allows for persistent state and private scope. In other words, the plugin is isolated and can't be altered by other plugins.
|
||||
|
||||
The module, created by the `(function(){` `})();` expressions, contains an object called `plugin`. The `plugin` object has two properties: `info` and `trial`. The `plugin` object is returned at the end of the module, which is what assigns the defined properties of `plugin` to `jsPsych['plugin-name']`.
|
||||
|
||||
#### plugin.info
|
||||
|
||||
The plugin's `info` property is an object that contains all of the available parameters for the plugin. Each parameter name is a property, and the value is an object that includes a description of the parameter, the value's type (string, integer, etc.), and the default value. See some of the plugin files in the jsPsych plugins folder for examples.
|
||||
|
||||
jsPsych allows most [plugin parameters to be dynamic](dynamic-parameters.md), 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.
|
||||
|
||||
#### plugin.trial
|
||||
|
||||
The plugin's `trial` property is a function that runs a single trial. There are two parameters that are passed into the trial method. The first, `display_element`, is the DOM element where jsPsych content is being rendered. This parameter will be an `HTMLElement`. Generally, you don't need to worry about this parameter being in the correct format, and can assume that it is an `HMTLElement` and use methods of that class. The second, `trial`, is an object containing all of the parameters specified in the corresponding TimelineNode. If you have specified all of your parameters in `plugin.info`, along with default values for each one, then the `trial` object will contain the default values for any parameters that were not specified in the trial's definition.
|
||||
|
||||
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.
|
||||
|
||||
Of course, there are other things that you will probably want the plugin to do inside the `plugin.trial` function, besides just end. Here are some examples:
|
||||
|
||||
### Changing the content of the display
|
||||
|
||||
There are a few ways to change the content of the display. The `display_element` parameter of the trial method contains the DOM element for displaying content, so you can use various JavaScript methods for interaction with the display element. A common one is to change the `innerHTML`.
|
||||
|
||||
```javascript
|
||||
var html_content = '<p>This is the first paragraph</p>';
|
||||
html_content += '<p>This is the second paragraph</p>';
|
||||
|
||||
display_element.innerHTML = html_content;
|
||||
```
|
||||
|
||||
jsPsych doesn't clear the display before or after each trial, so it is often appropriate to use `innerHTML` to clear the display at the end of a trial:
|
||||
|
||||
```javascript
|
||||
// clear the display
|
||||
display_element.innerHTML = '';
|
||||
```
|
||||
|
||||
### Writing data
|
||||
|
||||
Plugins exist to collect data, so saving data is obviously a crucial thing to do. You can pass an object of data as the parameter to `jsPsych.finishTrial()`:
|
||||
|
||||
```javascript
|
||||
var data = {
|
||||
correct: true,
|
||||
rt: 350
|
||||
}
|
||||
|
||||
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 by the jsPsych library.
|
||||
|
||||
### The plugin template
|
||||
|
||||
An empty plugin template is included in the `plugins/template` folder.
|
||||
See our [developer's guide for plugins](/developers/plugin-development.md) for information about how to create a new plugin.
|
||||
@ -1,6 +1,6 @@
|
||||
# Record browser interactions
|
||||
|
||||
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()](../core_library/jspsych-data.md#jspsychdatagetinteractiondata).
|
||||
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()](/reference/jspsych-data.md#jspsychdatagetinteractiondata).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -30,7 +30,7 @@ To prevent these errors, jsPsych uses a 'safe mode' when it detects that the HTM
|
||||
* **Web Audio is disabled** (even if `use_webaudio` is set to `true` in `jsPsych.init`). 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 `jsPsych.init`.
|
||||
* **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 [`jsPsych.init`](../core_library/jspsych-core.md#jspsychinit), 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 `jsPsych.init` settings when you move the experiment online.
|
||||
This safe mode feature is controlled by the `override_safe_mode` parameter in [`jsPsych.init`](/reference/jspsych.md#jspsychinit), 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 `jsPsych.init` settings when you move the experiment online.
|
||||
|
||||
It's possible to override jsPsych's safe mode by setting `override_safe_mode` to `true` in `jsPsych.init`. One reason you might do this is if you've disabled web security features in your browser (see [here](https://alfilatov.com/posts/run-chrome-without-cors/) and [here](https://stackoverflow.com/questions/4819060/allow-google-chrome-to-use-xmlhttprequest-to-load-a-url-from-a-local-file) 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.
|
||||
|
||||
@ -44,18 +44,18 @@ It is important to test your experiment to ensure that any media files are prelo
|
||||
|
||||
### Permanent data storage
|
||||
|
||||
As explained in the [Data Storage, Aggregation, and Manipulation](data.md#data-in-jspsych-permanent-and-non-permanent-data) 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`](../core_library/jspsych-data.md#localsave)), displaying it in the webpage at the end of the experiment (using [`jsPsych.data.displayData`](../core_library/jspsych-data.md#jspsychdatadisplaydata)), or printing it to the browser's console (using [`console.log`](https://www.w3schools.com/jsref/met_console_log.asp)).
|
||||
As explained in the [Data Storage, Aggregation, and Manipulation](data.md#data-in-jspsych-permanent-and-non-permanent-data) 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`](/reference/jspsych-data.md#localsave)), displaying it in the webpage at the end of the experiment (using [`jsPsych.data.displayData`](/reference/jspsych-data.md#jspsychdatadisplaydata)), or printing it to the browser's console (using [`console.log`](https://www.w3schools.com/jsref/met_console_log.asp)).
|
||||
|
||||
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](../core_library/jspsych-randomization.md#jspsychrandomizationsamplewithoutreplacement) instead of counterbalancing version assignment:
|
||||
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](/reference/jspsych-randomization.md#jspsychrandomizationsamplewithoutreplacement) instead of counterbalancing version assignment:
|
||||
|
||||
```js
|
||||
var versions = [1,2];
|
||||
var random_version = jsPsych.randomization.sampleWithoutReplacement(versions,1)[0];
|
||||
```
|
||||
|
||||
And use [URL query parameters](../core_library/jspsych-data.md#jspsychdatageturlvariable) to pass in variables like session number and difficulty level:
|
||||
And use [URL query parameters](/reference/jspsych-data.md#jspsychdatageturlvariable) to pass in variables like session number and difficulty level:
|
||||
|
||||
```js
|
||||
// add the variables onto the end of the URL that appears in the browser when you open the file
|
||||
@ -88,11 +88,11 @@ Some options for running your jsPsych experiment online include:
|
||||
|
||||
### Recruiting Participants
|
||||
|
||||
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](../core_library/jspsych-data.md#jspsychdatageturlvariable). 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.
|
||||
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](/reference/jspsych-data.md#jspsychdatageturlvariable). 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](https://www.prolific.co/): An online labor market designed specifically for web-based research.
|
||||
* [Amazon Mechanical Turk (MTurk)](https://www.mturk.com/): 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](../core_library/jspsych-turk.md). Information about integrating with Prolific can be found in the researcher support section of their website.
|
||||
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](/reference/jspsych-turk.md). Information about integrating with Prolific can be found in the researcher support section of their website.
|
||||
|
||||
@ -1,6 +1,10 @@
|
||||
# List of Plugins
|
||||
|
||||
These are the plugins that are included in the jsPsych release. If you don't see a plugin that will work for your needs, you can post on [GitHub Discussions](https://github.com/jspsych/jsPsych/discussions) to see if anyone else in the community has an unofficial plugin to share or to get help creating a new plugin. You can also view the [documentation on creating a new plugin](/overview/plugins/#creating-a-new-plugin) or [watch a video tutorial on creating a new plugin](https://www.youtube.com/watch?v=XQcsFwAmbiw&list=PLnfo1lBY1P2Mf_o6rV5wiqqn92Mw3UTGh&index=4).
|
||||
These are the plugins that are included in the jsPsych release.
|
||||
|
||||
Additional plugins may be available in the [community contributions repository](https://github.com/jspsych/jspsych-contrib).
|
||||
|
||||
For an overview of what plugins are and how they work, see our [plugins overview](/overview/plugins.md).
|
||||
|
||||
Plugin | Description
|
||||
------ | -----------
|
||||
|
||||
9
docs/support/support.md
Normal file
9
docs/support/support.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Support
|
||||
|
||||
For questions about jsPsych the preferred method of support is [GitHub Discussions](https://github.com/jspsych/jsPsych/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&A 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](https://github.com/jspsych/jsPsych/issues/new) on GitHub.
|
||||
|
||||
If you have a suggestion for fixing the problem, feel free to [contribute to the project](/developers/contributing.md)!
|
||||
|
||||
Inquiries for paid consultation to develop experiments using jsPsych or to create new custom jsPsych features can be sent to [josh.deleeuw@gmail.com](mailto:josh.deleeuw@gmail.com).
|
||||
@ -367,7 +367,7 @@ This installs the core jsPsych package. Plugins and extensions are installed sep
|
||||
|
||||
### Step 2: Import the JsPsych class and create a new instance
|
||||
|
||||
We create a new instance of `JsPsych`. The instance can be configured via [a variety of options](/core_library/jspsych-core/#jspsychinit), passed as an object to the constructor.
|
||||
We create a new instance of `JsPsych`. The instance can be configured via [a variety of options](/reference/jspsych.md#jspsychinit), passed as an object to the constructor.
|
||||
|
||||
```js
|
||||
import {JsPsych} from 'jspsych';
|
||||
|
||||
@ -54,7 +54,7 @@ Next, we push the welcome trial to the timeline, which adds it to the end of the
|
||||
timeline.push(welcome);
|
||||
```
|
||||
|
||||
Finally, we tell jsPsych to run the experiment by calling the [jsPsych.init() function](../core_library/jspsych-core.md#jspsychinit) and passing in the array that defines the experiment timeline.
|
||||
Finally, we tell jsPsych to run the experiment by calling the [jsPsych.init() function](/reference/jspsych.md#jspsychinit) and passing in the array that defines the experiment timeline.
|
||||
|
||||
```javascript
|
||||
jsPsych.init({
|
||||
@ -662,7 +662,7 @@ var test_procedure = {
|
||||
|
||||
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](/core_library/jspsych-randomization.md). `jsPsych.randomization.sampleWithoutReplacement()` takes an array of items to sample from and generates a new array of length *N* by sampling without replacement.
|
||||
To do that here, we'll use one of the built-in randomization methods in [jsPsych's randomization module](/reference/jspsych-randomization.md). `jsPsych.randomization.sampleWithoutReplacement()` takes an array of items to sample from and generates a new array of length *N* by sampling without replacement.
|
||||
|
||||
```javascript
|
||||
var fixation = {
|
||||
@ -771,7 +771,7 @@ In the code above, we replaced the `trial_duration: 1000` parameter in `fixation
|
||||
|
||||
## Part 10: Displaying the data
|
||||
|
||||
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()`](/core_library/jspsych-data.md#jspsychdatadisplaydata) 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 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()`](/reference/jspsych-data.md#jspsychdatadisplaydata) 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](/overview/callbacks.md#on_finish-experiment). This function will automatically execute once all the trials in the experiment are finished. We can specify a function to call in the `init` method.
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2014-2018 Joshua R. de Leeuw
|
||||
Copyright (c) 2014-2021 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
|
||||
|
||||
15
mkdocs.yml
15
mkdocs.yml
@ -28,6 +28,7 @@ markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed
|
||||
- pymdownx.details
|
||||
- pymdownx.snippets
|
||||
repo_url: 'https://github.com/jspsych/jsPsych'
|
||||
repo_name: 'jspsych/jspsych'
|
||||
docs_dir: docs
|
||||
@ -40,6 +41,7 @@ nav:
|
||||
- Overview:
|
||||
- 'Creating an Experiment: The Timeline': 'overview/timeline.md'
|
||||
- 'Plugins': 'overview/plugins.md'
|
||||
- 'Extensions': 'overview/extensions.md'
|
||||
- 'Dynamic Parameters': 'overview/dynamic-parameters.md'
|
||||
- 'Controlling Visual Appearance': 'overview/style.md'
|
||||
- 'Data Storage, Aggregation, and Manipulation': 'overview/data.md'
|
||||
@ -112,10 +114,15 @@ nav:
|
||||
- 'jspsych-webgazer-init-camera': 'plugins/jspsych-webgazer-init-camera.md'
|
||||
- 'jspsych-webgazer-validate': 'plugins/jspsych-webgazer-validate.md'
|
||||
- Extensions:
|
||||
- 'Extensions': 'extensions/extensions.md'
|
||||
- 'jspsych-ext-webgazer.js': 'extensions/jspsych-ext-webgazer.md'
|
||||
- 'List of Extensions': 'extensions/list-of-extensions.md'
|
||||
- 'jspsych-ext-webgazer': 'extensions/jspsych-ext-webgazer.md'
|
||||
- Developers:
|
||||
- 'Configuration': 'developers/configuration.md'
|
||||
- 'Contributing to jsPsych': 'developers/contributing.md'
|
||||
- 'Plugin Development': 'developers/plugin-development.md'
|
||||
- 'Extension Development': 'developers/extension-development.md'
|
||||
- Support:
|
||||
- 'Getting Help': 'support/support.md'
|
||||
- About:
|
||||
- 'About jsPsych': 'about/about.md'
|
||||
- 'Getting Help': 'about/support.md'
|
||||
- 'Contributing to jsPsych': 'about/contributing.md'
|
||||
- 'License': 'about/license.md'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user