jspsych 6.3.0 → 7.1.1

package/docs/overview/callbacks.md

@@ -1,184 +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(jsPsych.pluginAPI.compareKeys(data.response, 'j')){
-      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_timeline_finish
-
-The `on_timeline_finish` callback can be declared in a timeline node. The callback will be triggered when the timeline ends during the experiment. If `timeline_variables`, `conditional_function`, `loop_function`, or `sample` options are used, this function will execute when all trials have finished. If a `loop_function` is used, then this `on_timeline_finish` function will be triggered before the loop function. If the `repetitions` option is used, this function will be triggered at the end of every repetition.
-
-#### Sample use
-```javascript
-var procedure = {
-	timeline: [trial1, trial2],
-	timeline_variables: [
-		{ stimulus: 'person-1.jpg' },
-		{ stimulus: 'person-2.jpg' },
-		{ stimulus: 'person-3.jpg' },
-		{ stimulus: 'person-4.jpg' }
-	],
-  on_timeline_finish: function() {
-    console.log('This timeline has finished.');
-  },
-  loop_function: function() {
-    console.log('This loop function will execute after on_timeline_finish.');
-    return false;
-  }
-}
-```
----
-
-## on_timeline_start
-
-The `on_timeline_start` callback can be declared in a timeline node. The callback will be triggered when the timeline starts during the experiment, including when `timeline_variables`, `loop_function`, or `sample` options are used. If a `conditional_function` is used, then the conditional function will execute first, and the `on_timeline_start` function will only execute if the conditional function returns `true`. If the `repetitions` option is used, this function will be triggered at the start of every repetition. 
-
-#### Sample use
-```javascript
-var procedure = {
-	timeline: [trial1, trial2],
-  conditional_function: function() {
-    console.log('This conditional function will execute first.')
-    return true;
-  },
-  on_timeline_start: function() {
-    console.log('This timeline has started');
-  }
-}
-```
----
-
-## on_trial_finish
-
-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(jsPsych.pluginAPI.compareKeys(data.response, 'j')){
-      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/dynamic-parameters.md

@@ -1,147 +0,0 @@
-# Dynamic parameters
-
-Most trial parameters can also be specified as functions. In a typical declaration of a jsPsych trial, parameters are known at the start of the experiment. This makes it impossible to alter the content of the trial based on the outcome of previous trials. However, **when functions are used as the parameter value, the function is evaluated right before the trial starts, and the return value of the function is used as the parameter value for that trial**. This enables dynamic updating of the parameter based on data that a subject has generated or any other information that you do not know in advance.
-
-## Examples
-
-### Providing Feedback
-
-Here is a sketch of how this functionality could be used to display feedback to a subject in the Flanker Task.
-
-```javascript
-
-var timeline = [];
-
-var trial = {
-  type: 'html-keyboard-response',
-  stimulus: '<<<<<',
-  choices: ['f','j'],
-  data: {
-    stimulus_type: 'congruent',
-    target_direction: 'left'
-  },
-  on_finish: function(data){
-    // Score the response as correct or incorrect.
-    if(jsPsych.pluginAPI.compareKeys(data.response, "f")){
-      data.correct = true;
-    } else {
-      data.correct = false; 
-    }
-  }
-}
-
-var feedback = {
-  type: 'html-keyboard-response',
-  stimulus: function(){
-    // The feedback stimulus is a dynamic parameter because we can't know in advance whether
-    // the stimulus should be 'correct' or 'incorrect'.
-    // Instead, this function will check the accuracy of the last response and use that information to set
-    // the stimulus value on each trial.
-    var last_trial_correct = jsPsych.data.get().last(1).values()[0].correct;
-    if(last_trial_correct){
-      return "<p>Correct!</p>"; // the parameter value has to be returned from the function
-    } else {
-      return "<p>Wrong.</p>"; // the parameter value has to be returned from the function
-    }
-  }
-}
-
-timeline.push(trial, feedback);
-
-```
-
-### Randomizing a parameter value
-
-Here's an example of using a dynamic parameter to randomize the inter-trial interval (ITI) duration. This time, the dynamic parameter is created using a named function instead of an anonymous function.
-
-```js
-var random_duration = function() {
-    var rand_dur = jsPsych.randomization.sampleWithoutReplacement([500,600,700,800],1)[0];
-    return rand_dur;
-}
-
-var trial = {
-    type: 'html-keyboard-response'
-    stimulus: '+',
-    post_trial_gap: random_duration  // if you use a named function for a dynamic parameter, then just use the function name (without parentheses after it)
-}
-```
-
-### Storing changing variables in the data
-
-The trial's `data` parameter can be also function, which is useful for when you want to save information to the data that can change during the experiment. For example, if you have a global variable called `current_difficulty` that tracks the difficulty level in an adaptive task, you can save the current value of this variable to the trial data like this:
-
-```js
-var current_difficulty; // value changes during the experiment
-
-var trial = {
-  type: 'survey-text',
-  questions: [{prompt: "Please enter your response."}]
-  data: function() { 
-    return {difficulty: current_difficulty}; 
-  }
-}
-```
-
-It's also possible to use a function for any of the _individual properties_ in the trial's `data` object, for instance if you want to combine static and dynamic information in the data:
-
-```js
-var trial = {
-  type: 'survey-text',
-  questions: [{prompt: "Please enter your response."}]
-  data: {
-    difficulty: function() { 
-      return current_difficulty; // the difficulty value changes during the experiment
-    },
-    task_part: 'recall', // this part of the data is always the same
-    block_number: 1
-  }
-}
-```
-
-### Nested Parameters
-
-Dyanmic parameters work the same way with nested parameters, which are parameters that contain one or more sets of other parameters. For instance, many survey-* plugins have a `questions` parameter that is a nested parameter: it is an array that contains the parameters for one or more questions on the page. To make the `questions` parameter dynamic, you can use a function that returns the array with all of the parameters for each question:
-
-```js
-var subject_id; // value is set during the experiment
-
-var trial = {
-  type: 'survey-text',
-  questions: function(){
-    var questions_array = [ 
-        {prompt: "Hi "+subject_id+"! What's your favorite city?", required: true, name: 'fav_city'},
-        {prompt: "What is your favorite fruit?", required: true, name: 'fav_fruit'},
-    ];
-    return questions_array;
-  }
-}
-```
-
-You can also use a function for any of the _individual parameters_ inside of a nested parameter.
-
-```js
-var trial = {
-  type: 'survey-text',
-  questions: [
-    { 
-      prompt: function() {  
-        // this question prompt is dynamic - the text that is shown 
-        // will change based on the participant's earlier response
-        var favorite_city = jsPsych.data.getLastTrialData().values()[0].response.fav_city;
-        var text = "Earlier you said your favorite city is "+favorite_city+". What do you like most about "+favorite_city+"?"
-        return text;
-      }, 
-      required: true,
-      rows: 40,
-      columns: 10
-    },
-    { prompt: "What is your favorite fruit?", required: true, name: 'fav_fruit' }
-  ]
-}
-```
-## When dynamic parameters can't be used
-
-Note that if the plugin *expects* the value of a given parameter to be a function, then this function *will not* be evaluated at the start of the trial. This is because some plugins allow the researcher to specify functions that should be called at some point during the trial. Some examples of this include the `stimulus` parameter in the canvas-* plugins, the `mistake_fn` parameter in the cloze plugin, and the `stim_function` parameter in the reconstruction plugin. If you want to check whether this is the case for a particular plugin and parameter, then the parameter's `type` in the `plugin.info` section of the plugin file. If the parameter type is `jsPsych.plugins.parameterType.FUNCTION`, then this parameter must be a function and it will not be executed before the trial starts. 
-
-Even though function evaluation doesn't work the same way with these parameters, the fact that the parameters are functions means that you can get the same dynamic functionality. These functions are typically evaluated at some point during the trial, so you still get updates to values within the function during the trial.

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
-  }
-});
-```