jsPsych.data

The jsPsych.data module contains functions for interacting with the data generated by jsPsych plugins.


jsPsych.data.addDataToLastTrial

jsPsych.data.addDataToLastTrial(data)

Parameters

Parameter Type Description
data object Object of key: value pairs to add to the data from the last trial.

Return value

Returns nothing.

Description

This method appends data to the data recorded by the last trial. It's particularly useful when combined with the on_finish event handler for a trial, as shown in the example below.

Examples

Evaluate a response and add to data

var trial = {
    type: 'single-stim',
    stimulus: 'img/happy_face_1.jpg',
    choices: [89,78], // Y or N
    prompt: '<p class="center-content">Have you seen this face before? Y or N.</p>',
    on_finish: function(trial_data){
        // let's imagine that the correct answer is NO
        var correct = (trial_data.key_press == 78);
        jsPsych.data.addDataToLastTrial({correct: correct});
    }
}

jsPsych.data.addProperties

jsPsych.data.addProperties(properties)

Parameters

Parameter Type Description
properties object Object of key: value pairs to add to the data.

Return value

Returns nothing.

Description

This method appends a set of properties to every trial in the data object, including trials that have already occurred and trials that have yet to occur. You can use this to record things like the subject ID or condition assignment.

Examples

Assigning a subject ID

jsPsych.data.addProperties({subject: 1});

jsPsych.init({
    timeline: exp
})

jsPsych.data.dataAsCSV

jsPsych.data.dataAsCSV()

Return value

Returns a string in CSV format

Description

Generate a CSV formatted string containing all of the data generated in the experiment.

Examples

Basic example

var csvString = jsPsych.data.dataAsCSV();

jsPsych.data.dataAsJSON

jsPsych.data.dataAsJSON()

Return value

Returns a string in JSON format

Description

Generate a JSON formatted string containing all of the data generated in the experiment.

Examples

Basic example

var jsonString = jsPsych.data.dataAsJSON();

jsPsych.data.displayData

jsPsych.data.displayData(format)

Parameters

Parameter Type Description
format string Specifies whether to display the data in 'csv' or 'json' format.

Return value

Returns nothing.

Description

Outputs all of the data collected in the experiment to the screen in either JSON or CSV format. This is a useful method for quick debugging when developing an experiment.

Examples

Using the on_finish callback function to show data at the end of the experiment

jsPsych.init({
    experiment_structure: exp,
    on_finish: function() {
        jsPsych.data.displayData('csv');
    }
})

jsPsych.data.getData

jsPsych.data.getData()

Parameters

None.

Return value

Returns an array containing all of the data generated in the experiment. Each element of the array contains the data for a single trial. Each trial's data is stored as an object in key: value format.

Description

Gets all of the data generated by the experiment.

Example

var alldata = jsPsych.data.getData();

jsPsych.data.getDataByTimelineNode

jsPsych.data.getDataByTimelineNode(node_id)

Parameters

Parameter Type Description
node_id string The id of the TimelineNodes to get data from.

Return value

Returns an array containing all of the data generated in a specified TimelineNode. Each element of the array contains the data for a single trial. Each trial's data is stored as an object in key: value format.

Description

Get all the data generated by a specified TimelineNode.

Example


var current_node_id = jsPsych.currentTimelineNodeID();

var data_from_current_node = jsPsych.data.getDataByTimelineNode(current_node_id);


jsPsych.data.getDataByTrialIndex

jsPsych.data.getDataByTrialIndex(trial_index)

Parameters

Parameter Type Description
trial_index numeric The global trial index of the trial

Return value

Returns an array containing all of the data for a particular trial. Trials are automatically indexed by a global

Description

Gets all the data generated from a specific trial.

Examples

Basic example

var first_trial_data = jsPsych.data.getDataByTrialIndex(0);
var second_trial_data = jsPsych.data.getDataByTrialIndex(1);

jsPsych.data.getLastTimelineData

jsPsych.data.getLastTimelineData()

Return value

Returns an array containing all of the data generated in the same timeline as the last trial. Each element of the array contains the data for a single trial. Each trial's data is stored as an object in key: value format.

Description

Gets all of the data generated in the same chunk as the last trial.

Example

var lasttimelinedata = jsPsych.data.getLastTimelineData();

jsPsych.data.getLastTrialData

jsPsych.data.getLastTrialData()

Return value

Returns an object in key: value format containing the data from the last trial.

Description

Gets the data generated by the last trial.

Example

var lasttrialdata = jsPsych.data.getLastTrialData();

jsPsych.data.getTrialsOfType

jsPsych.data.getTrialsOfType(type)

Parameters

Parameter Type Description
type string Which plugin to get trial data from.

Return value

Returns an array containing all of the data generated by a particular plugin. Each element of the array contains the data for a single trial. Each trial's data is stored as an object in key: value format.

Description

Gets all the data generated by trials from a particular plugin.

Examples

Basic example

var all_xab_trials = jsPsych.data.getTrialsOfType('xab');

Compute average RT over whole experiment

// this example shows how this method could be used to display data
// to the subject, by finding all trials of type 'single-stim' and
// calculating the average response time.

var debrief_block = {
  type: "text",
  text: function() {
    return "<p>Your average response time was <strong>" +
           getAverageResponseTime() + "ms</strong>. Press " +
           "any key to complete the experiment. Thank you!</p>";
  }
};

function getAverageResponseTime() {

  var trials = jsPsych.data.getTrialsOfType('single-stim');

  var sum_rt = 0;
  var valid_trial_count = 0;
  for (var i = 0; i < trials.length; i++) {
    if (trials[i].rt > -1) {
      sum_rt += trials[i].rt;
      valid_trial_count++;
    }
  }
  return Math.floor(sum_rt / valid_trial_count);
}

jsPsych.data.getURLVariable

jsPsych.data.getURLVariable(var_name)

Parameters

Parameter Type Description
var_name string Which variable to get the value of.

Return value

Returns the value of a variable passed in through the query string.

Description

For extracting a particular variable passed in through a URL query string.

Examples


// if the URL of the page is: experiment.html?subject=1234&condition=test

console.log(jsPsych.data.getURLVariable('subject')) // logs "1234"
console.log(jsPsych.data.getURLVariable('condition')) // logs "test"


jsPsych.data.localSave

jsPsych.data.localSave(filename, format)

Parameters

Parameter Type Description
filename string Filename of locally saved file
format string Specifies either 'csv' or 'json' format

Return value

Returns nothing.

Description

Saves a CSV or JSON file on the computer running the experiment. If conducting an online experiment, this will download the file onto the subject's computer, and is therefore not a recommended data storage solution for online data collection.

Warning: This function relies on features which are currently not supported by all major web browsers, though adoption rates are increasing rapidly. It will work on the most recent versions of Chrome, Firefox, Safari, and Internet Explorer.

Example

jsPsych.data.localSave('mydata.csv', 'csv');

jsPsych.data.urlVariables

jsPsych.data.urlVariables()

Return value

Returns an object (associative array) of the variables in the URL query string.

Description

For extracting variables passed in through a URL query string.

Examples


// if the URL of the page is: experiment.html?subject=1234&condition=test

var urlvar = jsPsych.data.urlVariables();
console.log(urlvar.subject) // logs "1234"
console.log(urlvar.condition) // logs "test"


jsPsych.data.write

jsPsych.data.write(data_object)

Parameters

Parameter Type Description
data_object object Object of key: value pairs to store in jsPsych's data storage as a trial.

Return value

Returns nothing.

Description

This method is used by jsPsych.finishTrial for writing data. You should probably not use it to add data. Instead use jsPsych.data.addProperties.

Examples


// don't use this! data should only be written once per trial. use jsPsych.finishTrial to save data.

var trial_data = {
    correct: true,
    rt: 487
}

jsPsych.data.write(trial_data);