# ExperimentHandler

## data ExperimentHandler

An ExperimentHandler keeps track of multiple loops and handlers. It is particularly useful for generating a single data file from an experiment with many different loops (e.g. interleaved staircases or loops within loops.

## Constructor

#### new ExperimentHandler(options)

Source:
  - data/ExperimentHandler.js, line 22

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Description
--- | --- | ---
`psychoJS` | module:core.PsychoJS | the PsychoJS instance
`name` | string | name of the experiment
`extraInfo` | Object | additional information, such as session name, participant name, etc.

### Extends

- PsychObject

### Members

#### (static, readonly) Environment :Symbol

Source:
  - data/ExperimentHandler.js, line 438

##### Properties:

Name | Type | Description
--- | --- | ---
`SERVER` | Symbol |
`LOCAL` | Symbol |

Experiment environment.

##### Type:

- Symbol

#### (static, readonly) SaveFormat :Symbol

Source:
  - data/ExperimentHandler.js, line 420

##### Properties:

Name | Type | Description
--- | --- | ---
`CSV` | Symbol | Results are saved to a .csv file
`DATABASE` | Symbol | Results are saved to a database

Experiment result format

##### Type:

- Symbol

#### _thisEntry

Source:
  - data/ExperimentHandler.js, line 43

Legacy experiment getters.

#### experimentEnded

Source:
  - data/ExperimentHandler.js, line 27

Getter for experimentEnded.

#### experimentEnded

Source:
  - data/ExperimentHandler.js, line 35

Setter for experimentEnded.

### Methods

#### (protected, static) _getLoopAttributes(loop)

Source:
  - data/ExperimentHandler.js, line 361

Get the attribute names and values for the current trial of a given loop.

Only info relating to the trial execution are returned.

##### Parameters:

Name | Type | Description
--- | --- | ---
`loop` | Object | the loop

#### addData(key, value)

Source:
  - data/ExperimentHandler.js, line 153

Add the key/value pair.

Multiple key/value pairs can be added to any given entry of the data file. There are considered part of the same entry until a call to `nextEntry` is made.

##### Parameters:

Name | Type | Description
--- | --- | ---
`key` | Object | the key
`value` | Object | the value

#### addLoop(loop)

Source:
  - data/ExperimentHandler.js, line 123

Add a loop.

The loop might be a `TrialHandler`, for instance.

Data from this loop will be included in the resulting data files.

##### Parameters:

Name | Type | Description
--- | --- | ---
`loop` | Object | the loop, e.g. an instance of TrialHandler or StairHandler

#### isEntryEmpty() → {boolean}

Source:
  - data/ExperimentHandler.js, line 110
To Do:
  - This really should be renamed: IsCurrentEntryNotEmpty

Whether or not the current entry (i.e. trial data) is empty.

Note: this is mostly useful at the end of an experiment, in order to ensure that the last entry is saved.

##### Returns:

whether or not the current entry is empty

Type
  boolean

#### nextEntry(snapshots)

Source:
  - data/ExperimentHandler.js, line 175

Inform this ExperimentHandler that the current trial has ended. Further calls to `addData` will be associated with the next trial.

##### Parameters:

Name | Type | Description
--- | --- | ---
`snapshots` | Object | Array.<Object> | undefined | array of loop snapshots

#### removeLoop(loop)

Source:
  - data/ExperimentHandler.js, line 135

Remove the given loop from the list of unfinished loops, e.g. when it has completed.

##### Parameters:

Name | Type | Description
--- | --- | ---
`loop` | Object | the loop, e.g. an instance of TrialHandler or StairHandler

#### (async) save(options)

Source:
  - data/ExperimentHandler.js, line 243

Save the results of the experiment.

- For an experiment running locally, the results are offered for immediate download.
- For an experiment running on the server, the results are uploaded to the server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | Object | ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`attributes` | Array.<Object> | <optional> |  | the attributes to be saved
`sync` | boolean | <optional> | `false` | whether or not to communicate with the server in a synchronous manner
`tag` | string | <optional> | `''` | an optional tag to add to the filename to which the data is saved (for CSV and XLSX saving options)
`clear` | boolean | <optional> | `false` | whether or not to clear all experiment results immediately after they are saved (this is useful when saving data in separate chunks, throughout an experiment)