jspsych 6.2.0 → 7.1.0

package/docs/overview/callbacks.md

@@ -1,140 +0,0 @@
-# Event-related callback functions
-
-jsPsych offers the ability to call arbitrary functions in response to certain events occurring, like the end of a trial or when new data is saved. This page summarizes the different opportunities for callback functions and how to specify them.
-
----
-
-## on_close
-
-The `on_close` callback can be declared in the `jsPsych.init` method. The callback triggers when the user leaves the page, but before any content on the page is removed from the browser's memory. This can be used, for example, to save data as the user is leaving the page.
-
-#### Sample use
-```javascript
-jsPsych.init({
-  timeline: exp,
-  on_close: function(){
-    var data = jsPsych.data.get().json();
-    save_data_to_server(data);
-  }
-});
-```
-
----
-
-## on_data_update
-
-The `on_data_update` callback can be declared in the `jsPsych.init` method. The callback triggers at the end of a data update cycle. This happens after every trial, after the on_finish (trial) and on_trial_finish events execute, allowing you to modify the data in those callbacks, and then use this callback to store the data. The function will be passed a single argument, which contains the data that was written.
-
-#### Sample use
-```javascript
-jsPsych.init({
-  timeline: exp,
-  on_data_update: function(data) {
-    console.log('Just added new data. The contents of the data are: '+JSON.stringify(data));
-  }
-});
-```
----
-
-## on_finish (trial)
-
-The `on_finish` callback can be added to any trial. The callback will trigger whenever the trial ends. The callback function will be passed a single argument, containing the data object from the trial. This data object is *editable*. Any changes made in the on_finish function will be stored in the internal data collection.
-
-#### Sample use
-```javascript
-var trial = {
-  type: 'image-keyboard-response',
-  stimulus: 'imgA.png',
-  on_finish: function(data) {
-    if(data.key_press == 85){
-      data.correct = true;
-    } else {
-      data.correct = false;
-    }
-  }
-};
-```
----
-
-## on_finish (experiment)
-
-The `on_finish` callback can be declared in the `jsPsych.init` method. The callback will trigger once all trials in the experiment have been run. The method will be passed a single argument, containing all of the data generated in the experiment.
-
-#### Sample use
-```javascript
-jsPsych.init({
-  timeline: exp,
-  on_finish: function(data) {
-    console.log('The experiment is over! Here is all the data: '+JSON.stringify(data));
-  }
-});
-```
----
-
-## on_load
-
-The `on_load` callback can be added to any trial. The callback will trigger once the trial has completed loading. For most plugins, this will occur once the display has been initially updated but before any user interactions or timed events (e.g., animations) have occurred.
-
-#### Sample use
-```javascript
-var trial = {
-  type: 'image-keyboard-response',
-  stimulus: 'imgA.png',
-  on_load: function() {
-    console.log('The trial just finished loading.');
-  }
-};
-```
----
-
-## on_start (trial)
-
-The `on_start` callback can be added to any trial. The callback will trigger right before the trial begins. The callback function will be passed a single argument, containing the trial object. If any of the parameters of the trial are functions or timeline variables, these will be evaluated before `on_start` is called, and the trial object will contain the evaluated value. The trial object is modifiable, and any changes made will affect the trial.
-
-#### Sample use
-```javascript
-var trial = {
-  type: 'image-keyboard-response',
-  stimulus: 'imgA.png',
-  on_start: function(trial) {
-    console.log('The trial is about to start.');
-    trial.stimulus = 'imgB.png'; // this will change what stimulus is displayed in the trial
-  }
-};
-```
-
----
-
-## on_trial_finish
-
-The `on_trial_finish` callback can be declared in the `jsPsych.init` method. The callback will trigger at the end of every trial in the experiment. If you want a callback to trigger only for the end of certain trials, use the [`on_finish`](#onfinishtrial) callback on the trial object. The callback function will be passed a single argument, containing the data object from the trial.
-
-#### Sample use
-```javascript
-jsPsych.init({
-  timeline: exp,
-  on_trial_finish: function(data) {
-    console.log('A trial just ended.');
-    console.log(JSON.stringify(data));
-  }
-});
-```
----
-
-## on_trial_start
-
-The `on_trial_start` callback can be declared in the `jsPsych.init` method. The callback will trigger at the start of every trial in the experiment. The function receives a single argument: a modifiable copy of the trial object that will be used to run the next trial. Changes can be made to this object to alter the parameters of the upcoming trial.
-
-#### Sample use
-
-```javascript
-var current_score = 0; // a variable that is updated throughout the experiment to keep track of the current score.
-
-jsPsych.init({
-  timeline: exp,
-  on_trial_start: function(trial) {
-    trial.data.score_at_start_of_trial = current_score;
-    console.log('A trial just started.');
-  }
-});
-```

package/docs/overview/data.md

@@ -1,281 +0,0 @@
-## Data in jsPsych: permanent and non-permanent data.
-
-There are two very different kinds of data storage: data stored in **memory** and data stored **permanently**. Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a server. Data stored in memory exists only as long the browser window running jsPsych is open.
-
-jsPsych has many features for interacting with data stored in memory, but few for permanent data storage. This is a deliberate choice, as there are dozens of ways that data could be stored permanently. jsPsych does not lock you into one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and the second half of this page contains a few suggestions on how to accomplish permanent data storage.
-
-## Storing data in jsPsych's data structure
-
-jsPsych has a centralized collection of data that is built as the experiment runs. Each trial adds to the collection, and you can access the data with various functions, including `jsPsych.data.get()`, which returns the entire set of data.
-
-In most cases, data collection will be automatic and hidden. Plugins save data on their own so it is not uncommon to have the only interaction with the data be at the end of the experiment when it is time to save it in a permanent manner (see sections below about how to do this). However, there are some situations in which you may want to interact with the data; in particular, you may want to store additional data that the plugins are not recording, like a subject identifier or condition assignment. You may also want to add data on a trial by trial basis. For example, in a Stroop paradigm you would want to label which trials are congruent and which are incongruent. These scenarios are explored below.
-
-### Adding data to all trials
-
-Often it is useful to add a piece of data to *all* of the trials in the experiment. For example, appending the subject ID to each trial. This can be done  with the `jsPsych.data.addProperties()` function. Here is an example:
-
-```javascript
-// generate a random subject ID with 15 characters
-var subject_id = jsPsych.randomization.randomID(15);
-
-// pick a random condition for the subject at the start of the experiment
-var condition_assignment = jsPsych.randomization.sampleWithoutReplacement(['conditionA', 'conditionB', 'conditionC'], 1)[0];
-
-// record the condition assignment in the jsPsych data
-// this adds a property called 'subject' and a property called 'condition' to every trial
-jsPsych.data.addProperties({
-  subject: subject_id,
-  condition: condition_assignment
-});
-```
-
-### Adding data to a particular trial or set of trials
-
-Data can be added to a particular trial by setting the `data` parameter for the trial. The `data` parameter is an object of key-value pairs, and each pair is added to the data for that trial.
-
-```js
-var trial = {
-  type: 'image-keyboard-response',
-  stimulus: 'imgA.jpg',
-  data: { image_type: 'A' }
-}
-```
-
-Data declared in this way is also saved in the trials on any nested timelines:
-
-```js
-var block = {
-  type: 'image-keyboard-response',
-  data: { image_type: 'A' },
-  timeline: [
-    {stimulus: 'imgA1.jpg'},
-    {stimulus: 'imgA2.jpg'}
-  ]
-}
-```
-
-The data object for a trial can also be updated in the `on_finish` event handler. You can override properties or add new ones. This is particularly useful for cases where the value depends on something that happened during the trial.
-
-```js
-var trial = {
-  type: 'image-keyboard-response',
-  stimulus: 'imgA.jpg',
-  on_finish: function(data){
-    if(data.key_press == 65){
-      data.correct = true;
-    } else {
-      data.correct = false;
-    }
-  }
-}
-```
-
-## 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).
-
-Here are some examples of data collection manipulation.
-
-All data generated by the image-keyboard-response plugin:
-```js
-var data = jsPsych.data.get().filter({trial_type: 'image-keyboard-response'});
-```
-
-All data generated by the categorize-image plugin with a correct response:
-```js
-var data = jsPsych.data.get().filter({trial_type: 'categorize-image', correct: true});
-```
-
-All data with a response time between 100 and 500ms:
-```js
-var data = jsPsych.data.get().filterCustom(function(x){ return x.rt >= 100 && x.rt <=500 });
-```
-
-Applying filters consecutively to get all trials from a particular plugin with a response time above 100ms:
-```js
-var data = jsPsych.data.get().filter({trial_type: 'image-keyboard-response'}).filterCustom(function(x){ return x.rt > 100; });
-```
-
-Getting the data from the last n trials:
-```js
-var n = 3;
-var data = jsPsych.data.get().last(n);
-```
-
-Getting the data from the last n trials with a correct response:
-```js
-var n = 3;
-var data = jsPsych.data.get().filter({correct: true}).last(n);
-```
-
-Getting the data from the first n trials:
-```js
-var n = 3;
-var data = jsPsych.data.get().first(n);
-```
-
-Counting the number of trials in a data collection:
-```js
-var count = jsPsych.data.get().filter({correct: true}).count();
-```
-
-Selecting all of the response times from a data collection:
-```js
-var response_times = jsPsych.data.get().select('rt');
-```
-
-Calculating various descriptive statistics on the response times in a data collection:
-
-```js
-jsPsych.data.get().select('rt').mean();
-jsPsych.data.get().select('rt').sum();
-jsPsych.data.get().select('rt').min();
-jsPsych.data.get().select('rt').max();
-jsPsych.data.get().select('rt').variance();
-jsPsych.data.get().select('rt').sd();
-jsPsych.data.get().select('rt').median();
-jsPsych.data.get().select('rt').count();
-```
-
-## Storing data permanently as a file
-
-This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server. **This method will only work if you are running on a web server with PHP installed, or a local server with PHP (e.g., [XAMPP](https://www.apachefriends.org/index.html)).**
-
-This method uses a simple PHP script to write files to the server:
-
-```php
-<?php
-$post_data = json_decode(file_get_contents('php://input'), true); 
-// the directory "data" must be writable by the server
-$name = "data/".$post_data['filename'].".csv"; 
-$data = $post_data['filedata'];
-// write the file to disk
-file_put_contents($name, $data);
-?>
-```
-
-The `file_put_contents($filename, $data)` method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission to that directory. In the above example, the directory `data/` is used to store files.
-
-To use the PHP script, the JavaScript that runs jsPsych needs to send the `filename` and `filedata` information. This is done through an [AJAX](http://www.w3schools.com/xml/ajax_intro.asp) call.
-
-```javascript
-function saveData(name, data){
-  var xhr = new XMLHttpRequest();
-  xhr.open('POST', 'write_data.php'); // 'write_data.php' is the path to the php file described above.
-  xhr.setRequestHeader('Content-Type', 'application/json');
-  xhr.send(JSON.stringify({filename: name, filedata: data}));
-}
-
-// call the saveData function after the experiment is over
-jsPsych.init({
-   // code to define the experiment structure would go here...
-   on_finish: function(){ saveData("experiment_data", jsPsych.data.get().csv()); }
-});
-```
-
-To use this in an actual experiment, it would be important to tie the filename to some unique identifier like a subject number. Otherwise the file may be overwritten by collecting new data.
-
-Note that, depending on file permissions, storing the CSV files this way may make them publicly accessible. One fix is to store the CSV files outside the web directory on the server. This requires changing the path in the PHP script above from `/data` to a non-accessible folder. You should only use this solution if you have access to more than just the web directory on your server.
-
-## Storing data permanently in a MySQL database
-
-The ideal solution for storing data generated by jsPsych is to write it to a database.
-
-There are dozens of database options. MySQL is one of the most popular [relational databases](http://en.wikipedia.org/wiki/Relational_database), is free to use, and relatively easy [to install](https://www.google.com/search?q=how+to+install+mysql). This code will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code. If you are trying to run on a local machine, you'll need to install a local server environment like [XAMPP](https://www.apachefriends.org/index.html).
-
-You'll need two PHP scripts. The first is a configuration file for your database. Save it as `database_config.php` on your server. Within this file are configuration options for the database. You'll need to change these according to how you have configured your MySQL installation.
-
-```php
-<?php
-  $servername = "localhost";
-  $port = 3306;
-  $username = "username";
-  $password = "password";
-  $dbname = "database";
-  $table = "tablename";
-?>
-```
-
-The second PHP file will write data to the database. This script reads the database to discover what columns are in the table, and then only allows data to be entered in that matches those columns. This is a security feature. Save this file as `write_data.php` on your server.
-
-```php
-<?php
-
-// this path should point to your configuration file.
-include('database_config.php');
-
-$data_array = json_decode(file_get_contents('php://input'), true);
-
-try {
-  $conn = new PDO("mysql:host=$servername;port=$port;dbname=$dbname", $username, $password);
-  $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
-  // First stage is to get all column names from the table and store
-  // them in $col_names array.
-  $stmt = $conn->prepare("SHOW COLUMNS FROM `$table`");
-  $stmt->execute();
-  $col_names = array();
-  while($row = $stmt->fetchColumn()) {
-    $col_names[] = $row;
-  }
-  // Second stage is to create prepared SQL statement using the column
-  // names as a guide to what values might be in the JSON.
-  // If a value is missing from a particular trial, then NULL is inserted
-  $sql = "INSERT INTO $table VALUES(";
-  for($i = 0; $i < count($col_names); $i++){
-    $name = $col_names[$i];
-    $sql .= ":$name";
-    if($i != count($col_names)-1){
-      $sql .= ", ";
-    }
-  }
-  $sql .= ");";
-  $insertstmt = $conn->prepare($sql);
-  for($i=0; $i < count($data_array); $i++){
-    for($j = 0; $j < count($col_names); $j++){
-      $colname = $col_names[$j];
-      if(!isset($data_array[$i][$colname])){
-        $insertstmt->bindValue(":$colname", null, PDO::PARAM_NULL);
-      } else {
-        $insertstmt->bindValue(":$colname", $data_array[$i][$colname]);
-      }
-    }
-    $insertstmt->execute();
-  }
-  echo '{"success": true}';
-} catch(PDOException $e) {
-  echo '{"success": false, "message": ' . $e->getMessage();
-}
-$conn = null;
-?>
-```
-
-To send the data, we use an AJAX request in JavaScript.
-```JavaScript
-function saveData() {
-  var xhr = new XMLHttpRequest();
-  xhr.open('POST', 'write_data.php'); // change 'write_data.php' to point to php script.
-  xhr.setRequestHeader('Content-Type', 'application/json');
-  xhr.onload = function() {
-    if(xhr.status == 200){
-      var response = JSON.parse(xhr.responseText);
-      console.log(response.success);
-    }
-  };
-  xhr.send(jsPsych.data.get().json());
-}
-```
-
-You can call the `saveData()` function using the `on_finish` handler for the experiment, or by using the `call-function` plugin.
-
-```javascript
-// with on_finish handler
-jsPsych.init({
-  on_finish: saveData
-});
-
-// with call-function plugin
-timeline.push({
-  type: 'call-function',
-  func: saveData
-});
-```

package/docs/overview/exclude-browser.md

@@ -1,32 +0,0 @@
-# Exclude Participants Based on Browser Features
-
-Online subjects will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. jsPsych makes this straightforward. Simply specify certain exclusion criteria in the `jsPsych.init` method call. If a subject's browser doesn't meet the criteria the experiment will not start and the subject will see a message explaining the problem. For size restrictions the subject will see a message that displays the current size of their browser window and the minimum size needed to start the experiment, giving the subject an opportunity to enlarge the browser window to continue.
-
-Current exclusion options:
-* Minimum browser width & height
-* Support for the WebAudio API
-
-## Examples
-
-#### Exclude browsers that are not at least 800x600 pixels
-
-```javascript
-jsPsych.init({
-  timeline: exp,
-  exclusions: {
-    min_width: 800,
-    min_height: 600
-  }
-});
-```
-
-#### Exclude browsers that do not have access to the WebAudio API
-
-```javascript
-jsPsych.init({
-  timeline: exp,
-  exclusions: {
-    audio: true
-  }
-});
-```

package/docs/overview/experiment-options.md

@@ -1,121 +0,0 @@
-# Experiment-wide settings
-
-There are several options that can be set when calling `jsPsych.init()` to launch the experiment.
-
-Options are specified in the object passed to `jsPsych.init`. For example, to specify a set of images to preload and the default inter-trial interval the object would contain:
-
-```js
-jsPsych.init({
-    timeline: [...],
-    preload_images: ['img1.png', 'img2.png'],
-    default_iti: 500
-});
-```
-
-## Controlling where jsPsych renders on the page
-
-By default, jsPsych will render the experiment in the `<body>` element of a page. It is possible to display the experiment in a different element (e.g., a `<div>`) by specifying the `display_element` parameter. 
-
-```html
-<body>
-    <div id="jspsych-target"></div>
-</body>
-<script>
-    
-    // ... //
-
-    jsPsych.init({
-        timeline: [...],
-        display_element: 'jspsych-target'
-    })
-</script>
-```
-
-This option is useful if the experiment needs to be rendered on a page with other content (e.g., a demo version of the experiment with annotation text), or if additional control over the display element is desired. Custom CSS rules can be applied to position, size, scale, etc. the display element.
-
-## Experiment events
-
-Several experiment-wide events can trigger functions. This is documented in more detail on the [event-related callback functions page](callbacks.md). The events that trigger functions are:
-
-* `on_finish`: Called at the end of the experiment.
-* `on_trial_start`: Called at the beginning of every trial.
-* `on_trial_finish`: Called at the end of every trial.
-* `on_data_update`: Called whenever new data is added to the jsPsych data object.
-* `on_interaction_data_update`: Called whenever new interaction data (e.g., the subject enters or exits fullscreen mode) is added.
-* `on_close`: Called right before the page closes, such as when a subject closes the experiment early.
-
-## Specify exclusion criteria
-
-Exclusion criteria can be specified based on features of the user's web browser, such as the display size and whether certain features are reported. See the page on [excluding subjects based on browser features](exclude-browser.md).
-
-## Display a progress bar
-
-An automatic or manually updated progress bar can be displayed at the top of the screen. By default, the text next to the progress bar is "Completion Progress", but this text can be changed with the `message_progress_bar` parameter in `jsPsych.init`. See the [progress bar page](progress-bar.md) for more details.
-
-## Preload media elements
-
-Images, audio files, and movies can be preloaded to reduce latency during the experiment. In many cases, this preloading is automatic. In certain situations, such as using a custom plugin, using [timeline variables](timeline.md#timeline-variables), or using [functions to determine which stimulus to show](trial.md#dynamic-parameters), it is necessary to provide jsPsych with a list of media elements to preload. The [media preloading](media-preloading.md) page describes this process in detail.
-
-## Choose the method for playing audio files
-
-Specifying the `use_webaudio` parameter in `jsPsych.init()` allows you to choose whether to use the WebAudio API or HTML5 audio for playing audio files during your experiment. By default, jsPsych uses the WebAudio API to play audio files. Among other features, the WebAudio API allows for more precise measurement of response times relative to the onset of the audio. 
-
-However, loading files through the WebAudio API causes errors when running an experiment offline (i.e., by double-clicking on the HTML file, rather than hosting it on a web server). This is due to the [cross-origin security policy](https://security.stackexchange.com/a/190321) implemented by web browsers. For this reason, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline, and automatically uses HTML5 audio to prevent errors, even when `use_webaudio` has been explicitly set to `true`. For more information, see the section [Cross-origin requests (CORS) and safe mode](running-experiments.md#cross-origin-requests-cors-and-safe-mode) on the Running Experiments page.
-
-```js
-jsPsych.init({
-    timeline: [...],
-    use_webaudio: false
-});
-```
-
-## Set the default intertrial interval
-
-By default the next trial in a timeline will begin immediately after the conclusion of the previous trial. An experiment-wide delay can be specified using the `default_iti` parameter to `jsPsych.init()`.
-
-```js
-jsPsych.init({
-    timeline: [...],
-    default_iti: 500
-});
-```
-
-This parameter is specified in milliseconds. A blank screen will display between each trial for the duration of the ITI.
-
-## Specify the maximum width of the experiment
-
-The experiment will, by default, take up 100% of the display element. Usually the display element is the `<body>`, and the experiment is the full width of the screen. (This can be overridden by specifying the `display_element` parameter described above).
-
-Specifying the `experiment_width` parameter will set a maximum width for the display. The parameter is specified in pixels.
-
-```js
-jsPsych.init({
-    timeline: [...],
-    experiment_width: 750
-});
-```
-
-## Specify a minimum valid response time
-
-By default, jsPsych will treat any keyboard response time as valid. However, it's possible to specify a minimum valid response time (in ms) for key presses. Any key press that is less than this value will be treated as invalid and ignored. Note that this parameter only applies to _keyboard responses_, and not to other response types such as buttons and sliders. The default value is 0.
-
-```js
-// ignore any keyboard responses that are less than 100 ms
-jsPsych.init({
-    timeline: [...],
-    minimum_valid_rt: 100
-});
-```
-
-## Override 'safe mode' when running experiments offline
-
-By default, jsPsych switches to a 'safe mode' when it detects that the webpage is running offline (via the `file://` protocol) in order to prevent certain errors. Specifically, in safe mode, HTML5 audio is used to play audio files (even when `use_webaudio` has been explicitly set to `true`) and video preloading is disabled (both automatic and manual preloading). For more information, see the [Cross-origin requests (CORS) and safe mode](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page.
-
-It's possible to override this safe mode feature by setting the `override_safe_mode` parameter to `true` in `jsPsych.init`. This is something you might do if you've disabled certain security settings in your browser for testing purposes. This parameter has no effect when your experiment is running online (on a server), because it will be using the `http://` or `https://` protocol, which does not trigger safe mode. 
-
-```js
-jsPsych.init({
-    timeline: [...],
-    override_safe_mode: true
-});
-```

package/docs/overview/fullscreen.md

@@ -1,36 +0,0 @@
-# Fullscreen Experiments
-
-You can run your experiment in fullscreen mode by using the jspsych-fullscreen plugin.
-
-```javascript
-var timeline = [];
-
-timeline.push({
-  type: 'fullscreen',
-  fullscreen_mode: true
-});
-
-timeline.push({
-  type: 'html-keyboard-response',
-  stimulus: 'This trial will be in fullscreen mode.'
-});
-
-// exit fullscreen mode
-timeline.push({
-  type: 'fullscreen',
-  fullscreen_mode: false
-});
-
-timeline.push({
-  type: 'html-keyboard-response',
-  stimulus: 'This trial will NOT be in fullscreen mode.'
-});
-
-jsPsych.init({
-  timeline: timeline
-});
-```
-
-For security reasons, web browsers require that users initiate an action to launch fullscreen mode. The fullscreen plugin displays a button that the user must click to change the display to fullscreen.
-
-Safari does not support keyboard input when the browser is in fullscreen mode. Therefore, the function will not launch fullscreen mode on Safari. The experiment will ignore any trials using the fullscreen plugin in Safari.