# JSDoc: Class: TrialHandler

# Class: TrialHandler

## data.TrialHandler(options)

A Trial Handler handles the importing and sequencing of conditions.

## Constructor

#### new TrialHandler(options)

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

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

### Extends

- PsychObject

### Members

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

TrialHandler method

##### Type:

- Symbol

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

Source:
  - data/TrialHandler.js, line 743

#### finished

Getter for the finished attribute.

Source:
  - data/TrialHandler.js, line 345

#### finished

Setter for the finished attribute.

Source:
  - data/TrialHandler.js, line 355

### Methods

#### (static) fromSnapshot(snapshot)

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

Source:
  - data/TrialHandler.js, line 304

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

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

Source:
  - data/TrialHandler.js, line 519

##### 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) _prepareTrialList() → {void}

Prepare the trial list.

Source:
  - data/TrialHandler.js, line 624

##### Returns:

Type
  void

#### addData(key, value)

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

Source:
  - data/TrialHandler.js, line 476

#### forEach(callback)

Execute the callback for each trial in the sequence.

##### Parameters:

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

Source:
  - data/TrialHandler.js, line 189

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

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.

Source:
  - data/TrialHandler.js, line 395

##### Returns:

the attributes

Type
  Array.string

#### getCurrentTrial() → {Object}

Get the current trial.

Source:
  - data/TrialHandler.js, line 417

##### Returns:

the current trial

Type
  Object

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

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

Source:
  - data/TrialHandler.js, line 464

##### Returns:

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

Type
  Object | undefined

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

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

##### Parameters:

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

Source:
  - data/TrialHandler.js, line 446

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

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

Source:
  - data/TrialHandler.js, line 229

##### Returns:

- a snapshot of the current internal state.

Type
  Snapshot

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

Get the nth trial.

##### Parameters:

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

Source:
  - data/TrialHandler.js, line 428

##### Returns:

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

Type
  Object | undefined

#### getTrialIndex() → {number}

Get the trial index.

Source:
  - data/TrialHandler.js, line 371

##### Returns:

the current trial index

Type
  number

#### next()

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

Source:
  - data/TrialHandler.js, line 123

#### setSeed(seed, log)

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

Source:
  - data/TrialHandler.js, line 282

#### setTrialIndex(index)

Set the trial index.

##### Parameters:

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

Source:
  - data/TrialHandler.js, line 381

#### Symbol.iterator()

Iterator over the trial sequence.

This makes it possible to iterate over all trials.

Source:
  - data/TrialHandler.js, line 139

##### Example

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