11 KiB
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.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(filters)
Parameters
| Parameter | Type | Description |
|---|---|---|
| filters | array of objects | Set of filters used to select subset of data. |
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
Selects some or all of the data generated in the experiment. Each filter is an object with properties and values that must be matched. If an object has more than one property, the filter is an AND filter. Each separate object is treated as an OR filter. See below for examples. If filters is undefined, then all the data is returned.
Example
// select all trials
jsPsych.data.getData();
// select all single-stim trials
jsPsych.data.getData([{trial_type: 'single-stim'}]);
// select all single-stim trials where key_press == 81
jsPsych.data.getData([{trial_type: 'single-stim', key_press: 81}]);
// select trials where trial_type is either single-stim or single-audio.
jsPsych.data.getData([{trial_type: 'single-stim'}, {trial_type: 'single-audio'}]);
jsPsych.data.getDataAsCSV
jsPsych.data.getDataAsCSV(filters)
Parameters
| Parameter | Type | Description |
|---|---|---|
| filters | array of objects | Set of filters used to select subset of data. |
Return value
Returns a string in CSV format
Description
Generate a CSV formatted string containing data from the experiment. See jsPsych.data.getData for a description of how the filters work.
Examples
Basic example
var csvString = jsPsych.data.getDataAsCSV();
jsPsych.data.getDataAsJSON
jsPsych.data.getDataAsJSON()
Parameters
| Parameter | Type | Description |
|---|---|---|
| filters | array of objects | Set of filters used to select subset of data. |
Return value
Returns a string in JSON format
Description
Generate a JSON formatted string containing data generated in the experiment. See jsPsych.data.getData for a description of how the filters work.
Examples
Basic example
var jsonString = jsPsych.data.getDataAsJSON();
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.getInteractionData
jsPsych.data.getInteractionData()
Parameters
None.
Return value
Returns an array containing events where the participant selected another window other than the experiment (blur), reselected the experiment window (focus), entered full screen mode, or exited full screen mode.
Description
Gets a list of interaction events. Useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form:
{
type: 'focus' or 'blur' or 'fullscreenenter' or 'fullscreenexit',
trial: 10, // the trial number when the event happened
time: 13042 // total time elapsed since the start of the experiment
}
Example
var interactiondata = jsPsych.data.getInteractionData();
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.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.ignore
jsPsych.data.ignore(properties)
Parameters
| Parameter | Type | Description |
|---|---|---|
| properties | array | Array of properties to ignore. |
Return value
Returns nothing.
Description
This method will permanently delete all instances of a particular property in the data. For example, if you do not want to record the stimulus parameter when using the single-stim plugin, you can use this method to delete all instances of stimulus from the data. You can call this method at any time during the experiment. All previous instances of the property will be deleted, and no future instances will be recorded.
If you need access to a property during the experiment, but do not want to record it in the data file, then call this method immediately before saving the data at the end of the experiment.
Note: If you use this method to remove internal_node_id from the data, some methods in jsPsych.data will no longer work properly.
Examples
Remove all instances of 'stimulus' and 'time_elapsed'
jsPsych.data.ignore(['stimulus', 'time_elapsed']);
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);