jspsych 6.2.0 → 7.1.0

package/docs/overview/media-preloading.md

@@ -1,91 +0,0 @@
-# Media Preloading
-
-If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. Preloading files means that the subject's browser will download all of the files and store them in local memory on the subject's computer. This is important because loading a file is much faster if it is already in memory on the subject'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 subject'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.
-
-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](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page contains more information about this.
-
-## Automatic Preloading
-
-jsPsych will automatically preload audio, video, and image files that are used as parameters for the standard set of plugins.
-
-```javascript
-// the image file img/file1.png is
-// automatically preloaded before the experiment begins
-var trial = {
-	type: 'image-keyboard-response',
-	stimulus: 'img/file1.png'
-}
-
-// the sound file is also preloaded automatically
-var sound_trial = {
-	type: 'audio-keyboard-response',
-	stimulus: 'audio/hello.mp3'
-}
-
-// the video file is preloaded automatically (as long as the experiment is running on a server)
-var video_trial = {
-	type: 'video',
-	stimulus: ['video/sample_video.mp4']
-}
-
-jsPsych.init({
-	timeline: [trial]
-});
-```
-
-## Manual preloading
-
-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 audio, video, or images, or you are using timeline variables), then you can manually specify the files to preload.
-
-You can specify an array of image files (`preload_images`) and an array of audio files (`preload_audio`) for preloading in the `jsPsych.init()` method. These files will load before the experiment starts.
-
-```javascript
-// this trial will not preload the images, because the image file is being used
-// in an HTML string
-var trial = {
-	type: 'html-keyboard-response',
-	stimulus: '<img src="img/file1.png"></img>',
-}
-
-var audio_trial = {
-	type: 'audio-keyboard-response',
-	stimulus: function() { return 'audio/foo.mp3' }
-}
-
-var video_timline = {
-	timeline: [
-		{
-			type: 'video',
-			stimulus: jsPsych.timelineVariable('video')
-		}
-	],
-	timeline_variables: [
-		{video: ['video/1.mp4']},
-		{video: ['video/2.mp4']}
-	]
-}
-
-// an array of paths to images that need to be loaded
-var images = ['img/file1.png'];
-var audio = ['audio/foo.mp3'];
-var video = ['video/1.mp4', 'video/2.mp4'];
-
-jsPsych.init({
-	timeline: [trial],
-	preload_audio: audio,
-	preload_images: images,
-	preload_video: video
-});
-
-```
-
-## Preloading progress bar
-
-By default, jsPsych will display a small progress bar while files are being preloaded. This progress bar represents all files that are being automatically preloaded or preloaded from the `preload_audio`, `preload_video`, and `preload_images` arrays. You may wish to turn this off if you are only loading a small number of files, as it will 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_preload_progress_bar` parameter in `jsPsych.init()`
-
-```javascript
-jsPsych.init({
-	timeline: timeline,
-	show_preload_progress_bar: false // hide preload progress bar
-});
-```

package/docs/overview/mturk.md

@@ -1,77 +0,0 @@
-# Integrating with Mechanical Turk
-
-A common use of jsPsych is to build an online experiment and find subjects using [Mechanical Turk](http://www.mturk.com/). Once an experiment is available through a web server and data is being [saved on the server](data.md), 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
-
-The [jsPsych.turk](../core_library/jspsych-turk.md) module contains functions that are relevant for experiments running on Mechanical Turk.
-
-## Creating an advertisement page
-
-When potential subjects 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 subjects 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:
-
-```html
-<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
-
-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 subjects 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.
-
-```javascript
-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
-
-If you are running a HIT on Mechanical Turk using the ExternalQuestion template, then you'll need to provide a way for subjects 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. Subjects 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:
-
-```html
-<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 subjects and the codes that they entered in the Mechanical Turk GUI. You can then approve or reject work using the Mechanical Turk website.
-
-## Limitations
-
-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](http://www.psiturk.org). jsPsych and PsiTurk complement each other nicely, and there is [an example of combining the two platforms](https://psiturk.org/ee/W4v3TPAsiD6FUVY8PDyajH) on PsiTurk's experiment exchange.

package/docs/overview/progress-bar.md

@@ -1,110 +0,0 @@
-# Automatic Progress Bar
-
-jsPsych can show a progress bar at the top of the experiment page indicating the subject'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:
-
-![Progressbar Screenshot](/img/progress_bar.png)
-
-To show the progress bar, set the `show_progress_bar` option in `jsPsych.init` to `true`:
-
-```javascript
-jsPsych.init({
-	timeline: exp,
-	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 subject. 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
-
-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.
-
-```js
-var trial = {
-	type: 'html-keyboard-response',
-	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()`.
-
-```js
-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 `jsPsych.init()` to `false`.
-
-```js
-jsPsych.init({
-	timeline: exp,
-	show_progress_bar: true,
-	auto_update_progress_bar: false
-});
-```
-
-Here's a complete example showing how to use these functions and `jsPsych.init()` settings to manually update the progress bar:
-
-```js
-var n_trials = 5;
-
-var start = {
-    type: 'html-keyboard-response',
-    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: 'html-keyboard-response',
-    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: 'html-keyboard-response',
-    stimulus: 'Done!'
-};
-
-jsPsych.init({
-    timeline: [start, trials, done],
-    show_progress_bar: true,
-    auto_update_progress_bar: false
-});
-```
-
-## Custom 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 `jsPsych.init`.
-
-```js
-// support for different spoken languages
-jsPsych.init({
-    timeline: [...],
-    show_progress_bar: true,
-    message_progress_bar: 'Porcentaje completo'
-});
-```
-
-```js
-// no message
-jsPsych.init({
-    timeline: [...],
-    show_progress_bar: true,
-    message_progress_bar: ''
-});
-```

package/docs/overview/record-browser-interactions.md

@@ -1,23 +0,0 @@
-# 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).
-
-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.
-
-```javascript
-{
-  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 jsPsych.init() method, that is called whenever one of these events occurs
-
-```javascript
-jsPsych.init({
-  on_interaction_data_update: function(data) {
-    console.log(JSON.stringify(data))
-  }
-});
-```

package/docs/overview/running-experiments.md

@@ -1,95 +0,0 @@
-# Running Experiments
-
-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.
-
-
-
-## Offline
-
-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
-
-Web browsers have a security policy called [cross-origin resource sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) 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](https://security.stackexchange.com/questions/190266/why-chrome-blocks-ajax-locally/190321#190321). If your experiment uses these features, then [CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/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 `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 preloading via plugins, and manual preloading via `preload_video` in `jsPsych.init`). 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.
-
-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. 
-
-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
-
-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](media-preloading.md) 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](https://developers.google.com/web/tools/chrome-devtools/network) 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 [`jsPsych.init`](../core_library/jspsych-core.md#jspsychinit) so that participants with slow/unreliable internet connections will be able to take part in your experiment.
-
-### 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)). 
-
-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:
-
-```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:
-
-```js
-// 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
-
-### Hosting the Experiment and Saving the Data
-
-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](https://www.cognition.run/) - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. 
-* [JATOS](https://www.jatos.org/Whats-JATOS.html) - 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](https://pavlovia.org/) - 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](https://psiturk.org/) - 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](https://languagelearninglab.gitbook.io/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](https://www.digitalocean.com/community/tutorial_collections/how-to-install-lamp)/[LEMP](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mysql-php-lemp-stack-on-ubuntu-20-04) (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include [Flask](https://flask.palletsprojects.com/) (Python) and [Node.js](https://nodejs.org/) (JavaScript).
-
-### 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.
-
-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.