TrialHandler

data. TrialHandler

A Trial Handler handles the importing and sequencing of conditions.

Constructor

new TrialHandler(options)

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

Getter for experimentHandler.

experimentHandler

Source:

Setter for experimentHandler.

finished

Source:

Getter for the finished attribute.

finished

Source:

Setter for the finished attribute.

Methods

(static) fromSnapshot(snapshot)

Source:

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:

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:

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:

Prepare the trial list.

Returns:
Type
void

addData(key, value)

Source:

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:

Execute the callback for each trial in the sequence.

Parameters:
Name Type Description
callback

getAttributes() → {Array.string}

Source:

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:

Get the current trial.

Returns:

the current trial

Type
Object

getEarlierTrial(nopt) → {Object|undefined}

Source:

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:

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:

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:

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:

Get the trial index.

Returns:

the current trial index

Type
number

next()

Source:

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

setSeed(seed, log)

Source:

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:

Set the trial index.

Parameters:
Name Type Description
index number

the new trial index

Symbol.iterator()

Source:

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); }