# TrialHandler

## data. TrialHandler

A Trial Handler handles the importing and sequencing of conditions.

## Constructor

#### new TrialHandler(options)

Source:
  - data/TrialHandler.js, line 22
To Do:
  - extraInfo is not taken into account, we use the expInfo of the ExperimentHandler instead

##### Parameters:

Name | Type | Description
--- | --- | ---

`options`

Object

the handler options

###### Properties

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`psychoJS` | module:core.PsychoJS |  |  | the PsychoJS instance
`trialList` | Array.<Object> | String | <optional> | `[undefined]` | if it is a string, we treat it as the name of a condition resource
`nReps` | number |  |  | number of repetitions
`method` | module:data.TrialHandler.Method |  |  | the trial method
`extraInfo` | Object |  |  | additional information to be stored alongside the trial data, e.g. session ID, participant ID, etc.
`seed` | number |  |  | seed for the random number generator
`autoLog` | boolean | <optional> | `false` | whether or not to log

### Extends

- PsychObject

### Members

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

Source:
  - data/TrialHandler.js, line 719

##### Properties:

Name | Type | Description
--- | --- | ---
`SEQUENTIAL` | Symbol | Conditions are presented in the order they are given.
`RANDOM` | Symbol | Conditions are shuffled within each repeat.
`FULL_RANDOM` | Symbol | Conditions are fully randomised across all repeats.
`FULLRANDOM` | Symbol | Same as above, but named to reflect PsychoPy boileplate.

TrialHandler method

##### Type:

- Symbol

#### experimentHandler

Source:
  - data/TrialHandler.js, line 27

Getter for experimentHandler.

#### experimentHandler

Source:
  - data/TrialHandler.js, line 35

Setter for experimentHandler.

#### finished

Source:
  - data/TrialHandler.js, line 331

Getter for the finished attribute.

#### finished

Source:
  - data/TrialHandler.js, line 341

Setter for the finished attribute.

### Methods

#### (static) fromSnapshot(snapshot)

Source:
  - data/TrialHandler.js, line 290

Set the internal state of the snapshot's trial handler from the snapshot.

##### Parameters:

Name | Type | Description
--- | --- | ---
`snapshot` | Snapshot | the snapshot from which to update the current internal state of the snapshot's trial handler

#### (static) importConditions(serverManager, resourceName, selectionopt) → {Object}

Source:
  - data/TrialHandler.js, line 497

Import a list of conditions from a .xls, .xlsx, .odp, or .csv resource.

The output is suitable as an input to 'TrialHandler', 'trialTypes' or 'MultiStairHandler' as a 'conditions' list.

The resource should contain one row per type of trial needed and one column for each parameter that defines the trial type. The first row should give parameter names, which should:

- be unique
- begin with a letter (upper or lower case)
- contain no spaces or other punctuation (underscores are permitted)

Note that we only consider the first worksheet for .xls, .xlsx and .odp resource.

'selection' is used to select a subset of condition indices to be used It can be a single integer, an array of indices, or a string to be parsed, e.g.: 5 [1,2,3,10] '1,5,10' '1:2:5' '5:' '-5:-2, 9, 11:5:22'

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`serverManager` | module:core.ServerManager |  |  | the server manager
`resourceName` | String |  |  | the name of the resource containing the list of conditions, which must have been registered with the server manager.
`selection` | Object | <optional> | `null` | the selection

##### Throws:

Throws an exception if importing the conditions failed.

Type
  Object

##### Returns:

the parsed conditions as an array of 'object as map'

Type
  Object

#### (protected) _prepareSequence()

Source:
  - data/TrialHandler.js, line 661

Prepare the sequence of trials.

The returned sequence is a matrix (an array of arrays) of trial indices with nStim columns and nReps rows. Note that this is the transpose of the matrix return by PsychoPY.

Example: with 3 trial and 5 repetitions, we get:

- sequential: [[0 1 2] [0 1 2] [0 1 2] [0 1 2] [0 1 2]]

These 3*5 = 15 trials will be returned by the TrialHandler generator

- with method = 'sequential' in the order: 0, 1, 2, 0, 1, 2, 0, 1, 2, 0, 1, 2, 0, 1, 2
- with method = 'random' in the order (amongst others): 2, 1, 0, 0, 2, 1, 0, 1, 2, 0, 1, 2, 1, 2, 0
- with method = 'fullRandom' in the order (amongst others): 2, 0, 0, 1, 0, 2, 1, 2, 0, 1, 1, 1, 2, 0, 2

#### (protected) _prepareTrialList() → {void}

Source:
  - data/TrialHandler.js, line 601

Prepare the trial list.

##### Returns:

Type
  void

#### addData(key, value)

Source:
  - data/TrialHandler.js, line 456

Add a key/value pair to data about the current trial held by the experiment handler

##### Parameters:

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

#### forEach(callback)

Source:
  - data/TrialHandler.js, line 178

Execute the callback for each trial in the sequence.

##### Parameters:

Name | Type | Description
--- | --- | ---
`callback` |  |

#### getAttributes() → {Array.string}

Source:
  - data/TrialHandler.js, line 379

Get the attributes of the trials.

Note: we assume that all trials in the trialList share the same attributes and consequently consider only the attributes of the first trial.

##### Returns:

the attributes

Type
  Array.string

#### getCurrentTrial() → {Object}

Source:
  - data/TrialHandler.js, line 400

Get the current trial.

##### Returns:

the current trial

Type
  Object

#### getEarlierTrial(nopt) → {Object|undefined}

Source:
  - data/TrialHandler.js, line 445

Get the nth previous trial.

Note: this is useful for comparisons in n-back tasks.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`n` | number | <optional> | `-1` | increment

##### Returns:

the past trial or undefined if attempting to go prior to the first trial.

Type
  Object | undefined

#### getFutureTrial(nopt) → {Object|undefined}

Source:
  - data/TrialHandler.js, line 428

Get the nth future or past trial, without advancing through the trial list.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`n` | number | <optional> | `1` | increment

##### Returns:

the future trial (if n is positive) or past trial (if n is negative) or undefined if attempting to go beyond the last trial.

Type
  Object | undefined

#### getSnapshot() → {Snapshot}

Source:
  - data/TrialHandler.js, line 217

Get a snapshot of the current internal state of the trial handler (e.g. current trial number, number of trial remaining).

This is typically used in the LoopBegin function, in order to capture the current state of a TrialHandler

##### Returns:

- a snapshot of the current internal state.

Type
  Snapshot

#### getTrial(index) → {Object|undefined}

Source:
  - data/TrialHandler.js, line 411

Get the nth trial.

##### Parameters:

Name | Type | Default | Description
--- | --- | --- | ---
`index` | number | `0` | the trial index

##### Returns:

the requested trial or undefined if attempting to go beyond the last trial.

Type
  Object | undefined

#### getTrialIndex() → {number}

Source:
  - data/TrialHandler.js, line 356

Get the trial index.

##### Returns:

the current trial index

Type
  number

#### next()

Source:
  - data/TrialHandler.js, line 112

Helps go through each trial in the sequence one by one, mirrors PsychoPy.

#### setSeed(seed, log)

Source:
  - data/TrialHandler.js, line 270

Setter for the seed attribute.

##### Parameters:

Name | Type | Description
--- | --- | ---
`seed` | boolean | the seed value
`log` | boolean | whether or not to log the change of seed

#### setTrialIndex(index)

Source:
  - data/TrialHandler.js, line 366

Set the trial index.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number | the new trial index

#### Symbol.iterator()

Source:
  - data/TrialHandler.js, line 128

Iterator over the trial sequence.

This makes it possible to iterate over all trials.

##### Example

    let handler = new TrialHandler({nReps: 5});
    for (const thisTrial of handler) { console.log(thisTrial); }