HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 19:20:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

update docs for data summary changes #227

Browse Source
This commit is contained in:
Josh de Leeuw 2017-06-16 21:26:32 -04:00
parent 31e2ef0f17
commit 085b53e691
3 changed files with 315 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

498
docs/markdown_docs/core_library/jspsych-data.md
View File

@ -2,46 +2,6 @@
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
```javascript
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
@ -66,13 +26,9 @@ This method appends a set of properties to every trial in the data object, inclu
### Examples
#### Assigning a subject ID
#### Assigning a subject ID and condition code
```javascript
jsPsych.data.addProperties({subject: 1});
jsPsych.init({
timeline: exp
})
jsPsych.data.addProperties({subject: 1, condition: 'control'});
```
@ -110,7 +66,7 @@ jsPsych.init({
```
---
## jsPsych.data.getData
## jsPsych.data.get
```
jsPsych.data.get()
@ -122,83 +78,23 @@ 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.
Returns the data collection of all data generated by the experiment.
### 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.
This function is the standard starting point for accessing the data generated by the experiment. It returns a DataCollection object, which has
several methods that can be used to further filter, aggregate, and view the data. These methods are described under the DataCollection section
on this page.
### Example
```javascript
// select all trials
jsPsych.data.get();
var all_data = jsPsych.data.get();
// 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'}]);
// get csv representation of data and log to console
console.log(all_data.csv());
```
---
## 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
```javascript
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
```javascript
var jsonString = jsPsych.data.getDataAsJSON();
```
---
## jsPsych.data.getDataByTimelineNode
@ -215,11 +111,11 @@ 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.
Returns a DataCollection of all of the data generated in a specified TimelineNode.
### Description
Get all the data generated by a specified TimelineNode.
Get all the data generated by a specified Timeline.
### Example
@ -244,11 +140,11 @@ 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.
Returns a DataCollection object with all of the interaction events.
### 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:
jsPsych automatically records a few different kinds of user interaction events. `blur` events occur when the user clicks on another window or tab during the experiment, indicating that they are no longer interacting with the experiment. `focus` events occur when the user clicks on the experiment window after having clicked somewhere else first (i.e., generated a `blur` event). `fullscreenenter` and `fullscreenexit` events are triggered by the browser entering and exiting fullscreen mode. However, `fullscreenenter` events only occur when the script switches the browser to fullscreen mode, e.g., with the jspsych-fullscreen plugin. Manually entering fullscreen mode does not trigger this event. `fullscreenexit` events occur whether the user manually exits fullscreen mode or the script exits fullscreen mode. This method returns the DataCollection containing all interaction events. This is useful for tracking whether the participant completed the task without diverting attention to other windows. Events are in the form:
```javascript
{
@ -261,7 +157,9 @@ Gets a list of interaction events. Useful for tracking whether the participant c
### Example
```javascript
var interactiondata = jsPsych.data.getInteractionData();
var interaction_data = jsPsych.data.getInteractionData();
// log data to console in json format
console.log(interaction_data.json());
```
@ -274,15 +172,15 @@ 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.
Returns a DataCollection.
### Description
Gets all of the data generated in the same chunk as the last trial.
Gets all of the data generated in the same timeline as the last trial.
### Example
```
```js
var lasttimelinedata = jsPsych.data.getLastTimelineData();
```
@ -295,11 +193,11 @@ jsPsych.data.getLastTrialData()
### Return value
Returns an object in `key: value` format containing the data from the last trial.
Returns a DataCollection
### Description
Gets the data generated by the last trial.
Gets the data collection containing all data generated by the last trial.
### Example
@ -339,70 +237,6 @@ 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'
```javascript
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](http://caniuse.com/#search=createObjectURL), though adoption rates are increasing rapidly. It will work on the most recent versions of Chrome, Firefox, Safari, and Internet Explorer.
### Example
```javascript
jsPsych.data.localSave('mydata.csv', 'csv');
```
---
## jsPsych.data.urlVariables
@ -431,7 +265,6 @@ console.log(urlvar.condition) // logs "test"
```
---
## jsPsych.data.write
@ -467,3 +300,290 @@ var trial_data = {
jsPsych.data.write(trial_data);
```
---
## DataCollection
All data is stored in the DataCollection object. Using methods like `jsPsych.data.get()` and `jsPsych.data.getLastTrialData()` return DataCollections containing
the experiment data. This is a list of all of the methods that are available to call on a DataCollection object.
#### .addToAll()
Adds a set of properties to all items in the DataCollection. Similar to `jsPsych.data.addProperties()`, except that it can be applied to a subset of the whole DataCollection by filtering down to a smaller DataCollection first.
```js
jsPsych.data.get().addToAll({subject_id: 123, condition: 'control'});
```
#### .addToLast()
Adds a set of properties to the last trial in the DataCollection.
```js
jsPsych.data.get().addToLast({success: true});
```
#### .count()
Counts the number of trials in the DataCollection.
```js
jsPsych.data.get().count()
```
#### .csv()
Generates a CSV string representing all of the data in the DataCollection.
```js
console.log(jsPsych.data.get().csv());
```
#### .filter()
Returns a subset of the DataCollection based on the filter. The filter is an object, and trials are only kept in the returned DataCollection if they contain the key: value pair(s) in the filter object. For example, the code below selects all of the trials with a correct response.
```js
var correct_trials = jsPsych.data.get().filter({correct: true});
```
The object can have multiple key: value pairs, and the trials must match all of them in order to be included in the returned collection.
```js
// keep only correct trials from the practice phase
var correct_practice_trials = jsPsych.data.get().filter({correct:true, phase: 'practice'});
```
The filter can also be an array of objects. In this case each object in the array acts as an OR filter. As long as the trial has all the key: value pairs of one of the objects in the array, it will appear in the returned collection.
```js
// select trials from block 1 and block 5.
var trials = jsPsych.data.get().filter([{block: 1}, {block:5}]);
```
The filter method returns a DataCollection object, so methods can be chained onto a single statement.
```js
// count the number of correct trials in block 1
var block_1_correct = jsPsych.data.get().filter({block:1, correct:true}).count();
```
#### .filterCustom()
This method is similar to the `.filter()` method, except that it accepts a function as the filter. The function is passed a single argument, containing the data for a trial. If the function returns `true` the trial is included in the returned DataCollection.
```js
// count the number of trials with a response time greater than 2000ms.
var too_long = jsPsych.data.get().filterCustom(function(trial){
return trial.rt > 2000;
}).count()
```
#### .first() / .last()
Returns a DataCollection containing the first/last *n* trials.
```js
var first_trial = jsPsych.data.get().first(1);
var last_trial_with_correct_response = jsPsych.data.get().filter({correct: true}).last(1);
var last_10_trials = jsPsych.data.get().last(10);
```
#### .ignore()
Returns a DataCollection with all instances of a particular key removed from the dataset.
```js
// log a csv file that does not contain the internal_node_id values for each trial
console.log(jsPsych.data.get().ignore('internal_node_id').csv());
```
#### .join()
Appends one DataCollection onto another and returns the combined collection.
```js
// get a DataCollection with all trials that are either correct or
// have a response time greater than 200ms.
var dc1 = jsPsych.data.get().filter({correct: true});
var dc2 = jsPsych.data.get().filterCustom(function(trial){ return trial.rt > 200});
var data = dc1.join(dc2);
```
#### .json()
Generates a JSON string representing all of the data in the DataCollection.
```js
console.log(jsPsych.data.get().json());
```
#### .localSave()
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](http://caniuse.com/#search=createObjectURL), though adoption rates are increasing rapidly. It will work on the most recent versions of Chrome, Firefox, and Internet Explorer. Safari has partial support. The file will render, but it will display in the browser window and will require using the Save As option manually.
```javascript
// first argument is the filename, second is the format.
// the format can be either 'csv' or 'json'.
jsPsych.data.get().localSave('mydata.csv', 'csv');
```
#### .push()
Add a new entry to the DataCollection. This method is mostly used internally, and you shouldn't need to call it under normal circumstances.
```js
var data = {correct: true, rt: 500}
jsPsych.data.get().push(data);
```
#### .readOnly()
Creates a copy of the DataCollection so that any modification of the values in the DataCollection will not affect the original.
```js
// this line edits the rt property of the first trial
jsPsych.data.get().first(1).values()[0].rt = 100;
// readOnly creates a copy that can be modified without affecting the original
jsPsych.data.get().first(1).values()[0].rt
// outputs 100
jsPsych.data.get().readOnly().first(1).values()[0].rt = 200
jsPsych.data.get().first(1).values()[0].rt
// still outputs 100
```
#### .select()
Returns a DataColumn object (see documentation below) of a single property from a DataCollection object.
```js
var rt_data = jsPsych.data.get().select('rt');
rt_data.mean()
```
#### .uniqueNames()
Generates an array of all the unique key names in the set of trials contained in the DataCollection. This is especially useful when setting up a relational database (e.g., MySQL) where the column names need to be specified in advance.
```js
console.log(jsPsych.data.get().uniqueNames());
```
#### .values()
Returns the raw data array associated with the DataCollection. This array is modifiable, so changes to the array and values of objects in the array will change the DataCollection.
```js
var raw_data = jsPsych.data.get().values();
// was response in first trial correct?
if(raw_data[0].correct){
console.log('correct!');
} else {
console.log('incorrect.');
}
```
---
## DataColumn
DataColumn objects represent all the values of a single property in a DataCollection. They are generated by using the `.select()` method on a DataCollection. Once a DataColumn is generated, the following methods can be used.
#### .all()
Checks if all values in the DataColumn return `true` when passed to a function. The function takes a single argument, which represents one value from the DataColumn.
```js
// check if all the response times in the practice phase were under 1000ms
jsPsych.data.get().filter({phase: 'practice'}).select('correct').all(function(x) { return x < 1000; });
```
#### .count()
Counts the number of values in the DataColumn.
```js
// count how many response times there are
jsPsych.data.get().select('rt').count();
```
#### .frequencies()
Counts the number of occurrences of each unique value in the DataColumn. Returns this value as an object, where each key is a unique value and the value of each key is the number of occurrences of that key.
```js
// get frequencies of correct and incorrect responses
jsPsych.data.get().select('correct').frequencies();
```
#### .max() / .min()
Returns the maximum or minimum value in a DataColumn.
```js
jsPsych.data.get().select('rt').max();
jsPsych.data.get().select('rt').min();
```
#### .mean()
Returns the average of all the values in a DataColumn.
```js
jsPsych.data.get().select('rt').mean();
```
#### .median()
Returns the median of all the values in a DataColumn.
```js
jsPsych.data.get().select('rt').median();
```
#### .sd()
Returns the standard deviation of the values in a DataColumn.
```js
jsPsych.data.get().select('rt').sd();
```
#### .subset()
Filters the DataColumn to include only values that return `true` when passed through the specified function.
```js
// below results will be less than 200.
jsPsych.data.get().select('rt').subset(function(x){ return x < 200; }).max();
```
#### .sum()
Returns the sum of the values in a DataColumn.
```js
jsPsych.data.get().select('rt').sum();
```
#### .values
The raw array of values in the DataColumn.
```js
// note that this is not a function call.
jsPsych.data.get().select('rt').values;
```
#### .variance()
Returns the variance of the values in a DataColumn.
```js
jsPsych.data.get().select('rt').variance();
```

11
docs/markdown_docs/core_library/overview.md
View File

@ -23,21 +23,18 @@ Every jsPsych experiment utilizes the core library (contained in the `jspsych.js
### [Data module](jspsych-data.md)
* [jsPsych.data.addDataToLastTrial](jspsych-data.md#jspsychdataadddatatolasttrial)
* [jsPsych.data.addProperties](jspsych-data.md#jspsychdataaddproperties)
* [jsPsych.data.displayData](jspsych-data.md#jspsychdatadisplaydata)
* [jsPsych.data.getData](jspsych-data.md#jspsychdatagetdata)
* [jsPsych.data.getDataAsCSV](jspsych-data.md#jspsychdatagetdataascsv)
* [jsPsych.data.getDataAsJSON](jspsych-data.md#jspsychdatagetdataasjson)
* [jsPsych.data.get](jspsych-data.md#jspsychdataget)
* [jsPsych.data.getDataByTimelineNode](jspsych-data.md#jspsychdatagetdatabytimelinenode)
* [jsPsych.data.getInteractionData](jspsych-data.md#jspsychdatagetinteractiondata)
* [jsPsych.data.getLastTimelineData](jspsych-data.md#jspsychdatagetlasttimelinedata)
* [jsPsych.data.getLastTrialData](jspsych-data.md#jspsychdatagetlasttrialdata)
* [jsPsych.data.getURLVariable](jspsych-data.md#jspsychdatageturlvariable)
* [jsPsych.data.ignore](jspsych-data.md#jspsychdataignore)
* [jsPsych.data.localSave](jspsych-data.md#jspsychdatalocalsave)
* [jsPsych.data.write](jspsych-data.md#jspsychdatawrite)
* [jsPsych.data.urlVariables](jspsych-data.md#jspsychdataurlvariables)
* [jsPsych.data.write](jspsych-data.md#jspsychdatawrite)
* [DataCollection](jspsych-data.md#datacollection)
* [DataColumn](jspsych-data.md#datacolumn)
### [Turk module](jspsych-turk.md)

4
docs/markdown_docs/features/data.md
View File

@ -2,7 +2,7 @@
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 and 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.
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
@ -75,7 +75,7 @@ All data with a response time between 100 and 500ms:
var data = jsPsych.data.get().filterCustom(function(x){ return x.rt >= 100 && x.rt <=500 });
```
Applying filters consecutively:
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: 'single-stim'}).filterCustom(function(x){ return x.rt > 100; });
```