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
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:
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.
Source:

Methods

(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:
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(trialList)

Prepare the trial list.
Parameters:
Name Type Description
trialList Array.<Object> | String a list of trials, or the name of a condition resource
Source:

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:

forEach(callback)

Execute the callback for each trial in the sequence.
Parameters:
Name Type Description
callback
Source:

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:
Returns:
the attributes
Type
Array.string

getCurrentTrial() → {Object}

Get the current trial.
Source:
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:
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:
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:
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:
Returns:
the requested trial or undefined if attempting to go beyond the last trial.
Type
Object | undefined

getTrialIndex() → {number}

Get the trial index.
Source:
Returns:
the current trial index
Type
number

setTrialIndex(index)

Set the trial index.
Parameters:
Name Type Description
index number the new trial index
Source:

Symbol.iterator()

Iterator over the trial sequence.

This makes it possible to iterate over all trials.

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