# trial_impl

Trial controls the running of trials and sets of trials.

# add_stimulus_event

    some_trial add_stimulus_event name slot start end value...

Add a stimulus clamping event named `name` to the trial sequence of `some_trial`. The stimulus will be clamped to the input of the model with the name `slot`, which should be a conventional name (e.g., orthographic) that abstracts away from particular trials and models. The elements in `value` (which may be macro variable names preceded by $) will be interpreted via the representation associated with that input slot to be converted to the representation for the corresponding input layer. Add `start` as a starting trigger event for this clamping event; add `end` as an ending trigger event for this clamping event. Both `start` and `end` are with the syntax described at `add_stimulus_start_condition`.

The onset and offset of the clamping are given by `start` and `end` which are of the format `event+delay` where `delay` is a number (or $macro variable indicating the amount of time to elapse after `event` for this to occur (+0 may be omitted); `event` may be `BEGIN`, `END`, `obsname`, or `ename/start` or `ename/end`, where `obsname` is the name of an observer, or `ename` is the `name` of another stimulus event added to the trial.

# add_stimulus_event

    some_trial add_stimulus_event_only name

Add a stimulus clamping event named `name` to the trial sequence of `some_trial`, without setting any of the properties of this event.

# set_description

    some_trial set_description blah...

Associate a description `blah` with `some_trial`.

# set_stimulus_event_slot

    some_trial set_stimulus_event_slot name slot

Identify the slot name that determines which layer and representation are used for clamping the event `name` of `some_trial` to be `slot`. The stimulus will be clamped to the input of the model with the name `slot`, which should be a conventional name (e.g., orthographic) that abstracts away from particular trials and models.

# set_stimulus_event_value

    some_trial set_stimulus_event_value name value...

Set the list of values that are used for clamping event `name` of `some_trial` to be `value`. The elements in `value` will be interpreted via the representation associated with the prevailing input slot to be converted to the representation for the corresponding input layer.

# remove_stimulus_event

    some_trial remove_stimulus_event name

Remove a stimulus clamping event named `name` from the trial sequence of `some_trial`.

# add_stimulus_start_condition

    some_trial add_stimulus_start_condition eventname starttime

Indicate that `starttime` is one of the possible trigger times for the clamping event `eventname` of `some_trial` to onset; events always start when the first such time is reached. The format of `starttime` is `event+delay` where `delay` is a number (or $macro variable) indicating the amount of time to elapse after `event` for this to occur (+0 may be omitted). `event` may be literally `BEGIN` or `END`; the name of an observer; or `ename/start` or `ename/end`, where `ename` is the `name` of another stimulus event added to the trial.

# add_stimulus_end_condition

    some_trial add_stimulus_end_condition eventname endtime

Indicate that `endtime` is one of the possible trigger times for the event `eventname` of `some_trial` to offset; events always start when the first such time is reached. The format of `endtime` is as for `starttime` above.

# remove_stimulus_start_condition

    some_trial remove_stimulus_start_condition eventname starttime

Remove the onset tigger `starttime` for the event `eventname` of `some_trial`.

# remove_stimulus_end_condition

    some_trial remove_stimulus_end_condition eventname endtime

Remove the offset condition `endtime` for the event `eventname` of `some_trial`.

# set_end_condition

    some_trial set_end_condition terminationtime

Indicate that the trial `some_trial` ends when the termination time/event `terminationtime` is reached. The format of `terminationtime` is as for `startime` of `add_stimulus_start_condition`.

# remove_end_condtion

    some_trial remove_end_condition terminationtime

Delete `terminationtime` from the list of times at which `some_trial` will end.

# details

    some_trial details

Emit an extensive description of events and end conditions.

# default_observer

    some_trial default_observer

Return the dflog_observer that is managed by `some_trial` and whose settings (by default) record the content of any macro variables and the time that each observer mentioned in the trial description (first) becomes true.

# set_cap

    some_trial set_cap timeout

Establish a special `timeout` termination condition for `some_trial`. `timeout` is a number (without leading `+` symbol). Layers will not be advanced beyond this time, and once all layers reach timeout, NAN (interpreted as timeout) will be recorded as the time of all observers that have been false throughout (unless overridden by `set_cap_validity`).

# event_pattern

    some_trial event_pattern name

Return the pattern object that is used for clamping the event `name` during the trial `some_trial`.

# response

    some_trial response name

Return a string pattern that represents the state of the observer `name` when it (first) becomes true during `some_trial`. Only valid for observers named as a time/event for clamping start/end or trial end.

# response_time

    some_trial response_time name

Return a strength pattern that represents the time at which the observer `name` when it (first) becomes true during `some_trial`. Only valid for observers named as a time/event for clamping start/end or trial end.

# run_set

    some_trial run_set df_stimset

For each row in the dataframe/stimulus_set `df_stimset`, run `some_trial` with local macro variables with the names of the columns of the `df_stimset` set to the corresponding values on the row. The `default_observer` is set up and enabled with appropriate trigger before the run, and this process is reversed after the run.

# run_set_multiple

    some_trial run_set_multiple spec num df_stimset

As `run_set` except that each row is used multiple times, the number of which is set by `num`, and the ordering of which is set by `spec`. A `spec` of `ABAB` indicates that the whole set should be run through before the next of the `num` repetitions, whereas `AABB` indicates that that each row should be run `num` times before proceeding to the next row.

# set_cap_validity

    some_trial set_cap_validity 0

Indicate that when the cap timeout is reached, the time, not NAN (timeout), should be recorded as response_time for observers that have no become true.

    some_trial set_cap_validity 1

Revert to the normal behaviour of the cap, where NAN (timeout) is recorded.