# jsPsych.data

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

---
## jsPsych.data.dataAsCSV

```
jsPsych.data.dataAsCSV(append_data)
```

### Parameters

Parameter | Type | Description
----------|------|------------
append_data | object | Object of `key: value` pairs. Each key will become a column in the CSV file, whose rows are all filled in with the specified value.

### 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
```javascript
var csvString = jsPsych.data.dataAsCSV();
```

#### Appending a column with a subject ID
```javascript
var subjectID = 14;
var csvString = jsPsych.data.dataAsCSV({subject: subjectID});
```


---
## 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
```javascript
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

```javascript
var alldata = jsPsych.data.getData();
```

---
## jsPsych.data.getLastChunkData

```
jsPsych.data.getLastChunkData()
```

### Parameters

None.

### Return value

Returns an array containing all of the data generated in the same chunk 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 lastchunkdata = jsPsych.data.getLastChunkData();
```

---
## jsPsych.data.getLastTrialData

```
jsPsych.data.getLastTrialData()
```

### Parameters

None.

### 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.getTrialsFromChunk

```
jsPsych.data.getTrialsFromChunk(chunk_id)
```

### Parameters

Parameter | Type | Description
----------|------|------------
chunk_id | string | The id of the chunk to get data from. 

### Return value

Returns an array containing all of the data generated in a specified chunk. 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 chunk.

### Example

```javascript

var current_chunk_id = jsPsych.currentChunkID();

var data_from_current_chunk = jsPsych.data.getTrialsFromChunk(current_chunk_id);

```

---
## 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

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

#### Compute average RT over whole experiment

```javascript
// 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.localSave

```
jsPsych.data.localSave(filename, format, append_data)
```

### Parameters

Parameter | Type | Description
----------|------|------------
filename | string | Filename of locally saved file
format | string | Specifies either `'csv'` or `'json'` format
append_data | object | Object of `key: value` pairs. Each key will become a column in the CSV file (or property of each trial object if saving in JSON format), whose rows are all filled in with the specified value.

### 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', {subject: 12});
```

---
## 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.

### Return value

Returns nothing.

### Description 

This is the only method available for storing data in jsPsych's data container. All plugins that write data do so using this method. It is not intended to be used outside of a plugin.

### Examples

```javascript

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

jsPsych.data.write(trial_data);

```