jspsych 6.3.0 → 7.1.1

package/docs/overview/media-preloading.md

@@ -1,369 +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. You can preload files at any point in your experiment using the [jsPsych `preload` plugin](../plugins/jspsych-preload.md). Preloading files means that the subject's browser will download the files and store them in local memory on the subject's computer. This is important because displaying or playing a media 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.
-
-!!! 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](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page contains more information about this.
-
-## Automatic Preloading
-
-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.init`. 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`.
-
-```javascript
-// the "auto_preload: true" setting tells the plugin to automatically find 
-// stimuli to preload based the main experiment timeline (used in jsPsych.init)
-var preload = {
-	type: 'preload',
-	auto_preload: true 
-}
-
-// this image file can be automatically preloaded 
-var image_trial = {
-	type: 'image-keyboard-response',
-	stimulus: 'img/file1.png'
-}
-
-// the sound file can be automatically preloaded 
-var sound_trial = {
-	type: 'audio-keyboard-response',
-	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: 'video',
-	stimulus: ['video/sample_video.mp4']
-}
-
-jsPsych.init({
-	timeline: [preload, image_trial, sound_trial, video_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 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.
-
-```javascript
-// this image file cannot be automatically preloaded because it is embedded in 
-// an HTML string
-var image_trial = {
-	type: 'html-keyboard-response',
-	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: 'audio-keyboard-response',
-	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: 'video',
-			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: 'preload',
-	images: images,
-	audio: audio,
-	video: video
-}
-
-jsPsych.init({
-	timeline: [preload, image_trial, sound_trial, video_trials],
-});
-
-```
-
-## Combining automatic and manual preloading
-
-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. 
-
-```javascript
-// this file can be preloaded automatically
-var image_trial = {
-	type: 'image-keyboard-response',
-	stimulus: 'img/file1.png'
-}
-
-// this file can be preloaded automatically
-var sound_trial = {
-	type: 'audio-keyboard-response',
-	stimulus: 'audio/hello.mp3'
-}
-
-// these files must be preloaded manually
-var video_trials = {
-	timeline: [
-		{
-			type: 'video',
-			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: 'preload',
-	auto_preload: true, // automatically preload the image and audio files
-	video: video // manually preload the videos used with timeline variables
-}
-
-jsPsych.init({
-	timeline: [preload, image_trial, sound_trial, video_trials],
-});
-
-```
-
-## Preloading in batches
-
-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. 
-
-```javascript
-// these image files in these trial blocks can be automatically preloaded
-var block_1 = {
-	timeline: [
-		{
-			type: 'image-keyboard-response',
-			stimulus: 'img/file1.png'
-		},
-		{
-			type: 'image-keyboard-response',
-			stimulus: 'img/file2.png'
-		}
-	]
-}
-
-var block_2 = {
-	timeline: [
-		{
-			type: 'image-keyboard-response',
-			stimulus: 'img/file3.png'
-		},
-		{
-			type: 'image-keyboard-response',
-			stimulus: 'img/file4.png'
-		}
-	]
-}
-
-var preload_1 = {
-	type: 'preload',
-	trials: block_1 // automatically preload just the images from block_1 trials
-}
-
-var preload_2 = {
-	type: 'preload',
-	trials: block_2 // automatically preload just the images from block_2 trials
-}
-
-jsPsych.init({
-	// add each preload trial onto the timeline before the appropriate trial block
-	timeline: [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.
-
-```javascript
-// 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: 'preload',
-	images: images_block_1
-}
-
-// preload trial for preloading the block 2 stimuli
-var preload_2 = {
-	type: 'preload',
-	images: images_block_2
-}
-
-jsPsych.init({
-	// add each preload trial to the timeline before the appropriate trial block
-	timeline: [preload_1, block_1, preload_2, block_2], 
-});
-
-```
-
-## Preloading progress bar
-
-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.
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	auto_preload: true
-	show_progress_bar: false // hide progress bar
-}
-```
-
-## Loading time limits
-
-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. 
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	auto_preload: true
-	max_load_time: 60000 // 1 minute
-}
-```
-
-## Loading and error messages
-
-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. 
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	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). 
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	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. 
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	auto_preload: true,
-	// show details of any file loading errors and/or loading time out
-	show_detailed_errors: true 
-}
-```
-
-## Options for handling errors
-
-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.
-
-```javascript
-var preload_trial = {
-	type: 'preload',
-	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: 'call-function',
-    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: 'html-keyboard-response',
-	stimulus: 'The experiment failed to load. Please contact the researcher.',
-	choices: jsPsych.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.init({
-	timeline: [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.
-
-```javascript
-var file_load_count = 0;
-var file_error_count = 0;
-
-var preload_trial = {
-    type: 'preload',
-    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.

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.