Description of protocol control¶

Here, it is described as to how to abstract your stimulus-response sequence (i.e. protocol) during acquisition.

In case of behavioral tasks, in particular, the description of protocol-control is paired with the description of Behavioral model for a subject in the tasks section.

Currently, it does not belong anywhere in the tree of entities for the sake of simplicity in notation.

Contents

Overview
Unitary stimulus control
- StimulusState
- ApparatusState
Sequence-type stimulus description
Context-dependent stimulus sequence

Overview ¶

You can choose a suitable class from the two options:

Sequencer: describe as a sequence of StimulusBlock objects.
StateMachine: describe in terms of transitions of MachineState.
- input can be Event, including the “timeout” event.

Typically, if the next state of the protocol depends on some on-line contexts (e.g. responses from the subject), then the use of StateMachine would be appropriate.

Variable parameters, such as stimulus strengths and durations, may be represented in terms of variable.

Unitary stimulus control ¶

StimulusState ¶

class StimulusState¶

StimulusState represents a state of stimulus output during a certain period of time, and comprises the basis of protocol specification.

mode¶

the mode of the output. May be one of the followings:

Mode	Related properties	Description
“constant”	`amplitude`	a constant (rectangular) output
“rect-wave”	`amplitude`, `frequency`, `offset`	a sine-wave output with a certain frequency
“sine-wave”	`amplitude`, `frequency`, `offset`	a rectangular-wave output with a certain frequency

Note

In cases where e.g. amplitude changes over time during a StimulusBlock: the output values is supposed to be represented by an expression.

amplitude¶

an optional (but recommended) property except for the “ramp” mode, representing the height of the output, in terms of the corresponding Quality instance.

For the wave-type modes, this indicates the peak-to-peak amplitude: the output range from offset - amplitude/2 to offset + amplitude/2.

This property will be ignored for the “ramp” mode.

pulse¶

an optional property for describing a pulse-like output, in terms of the corresponding Quality instance.

If this property is set, it is assumed that the output only lasts for pulse long.

offset¶

an optional (but recommended) property for the wave-type modes, representing the offset (center) of the wave, in terms of the corresponding Quality instance.

This property will be ignored for the non wave-type modes.

frequency¶

an optional (but recommended) property for the wave-type modes, representing the frequency of the wave, in terms of the corresponding Quality instance.

This property will be ignored for the non wave-type modes.

During manipulation of apparatus in the behavioral setup, in particular, it is easier for a human being to understand if the state of control is written not by the voltage/current outputs but by the actions executed by the apparatus.

ApparatusState is used in such cases where it is simpler to describe the outputs in terms of apparatus actions.

class ApparatusState¶: this is a sort of Restriction, describing the controls over the apparatus of interest. The predicate part is ontologically defined through amorphys-control.

TODO

some example ApparatusState

Sequence-type stimulus description ¶

Sequencer ¶

class Sequencer¶

Sequencer consists of blocks of StimulusBlock, and it is probably useful when the acquisition involves a fixed protocol of stimulus trains (possibly with variable parameters) while recording the responses from the subject.

type¶: a required string property. It must hold the value "sequencer".

description¶: a required string property, for a human-readable description of what this Sequencer class is for.

run-by: an optional (but recommended) Program instance, indicating the program that runs this sequence.

sequence¶: a required array of StimulusBlock describing the stimulus sequence.

StimulusBlock ¶

class StimulusBlock¶

StimulusBlock specifies a certain period during the stimulus sequence where the states of output stimuli stays constant.

It can hold a mapping of StimulusGeneration instances as channels.

description¶: a required string property, for a human-readable description of what takes place during this StimulusBlock.

duration¶: a required property holding a temporal Quality, representing the duration of this StimulusBlock.

output¶: an optional mapping from a stimulus identifier to a corresponding StimulusGeneration, indicating what stimulus is generated during this StimulusBlock.

Caution

Unlike the case of MachineState, this property is memory-less i.e. if no StimulusGeneration instance is specified for a channel during this StimulusBlock, this channel is assumed to output nothing (e.g. 0 V or GND) during the block, no matter how you specified during the previous block.

StimulusGeneration ¶

class StimulusGeneration¶

StimulusGeneration represents a certain state of output from a channel.

channel¶: a required Signal property that holds where the output comes out of.

state¶: a required property consisting of a StimulusState or a ApparatusState, describing the output.

Context-dependent stimulus sequence ¶

StateMachine ¶

class StateMachine¶

This class is used when the output stimulus sequence depends on input signals e.g. the state of behavior of the subject.

type¶: a required string property. It must hold the value "state-machine".

description¶: a required string property, for a human-readable description of what this StateMachine class is for.

run-by: an optional (but recommended) Program instance, indicating the program that runs this state machine.

initial¶: the initial, entry State for this state machine when it is reset. Normally, this property holds a reference to one of the states in states.

states¶: a required mapping from the names to their corresponding MachineState instances.

MachineState ¶

class MachineState¶

The MachineState class represents the state for a StateMachine.

description¶: a required string property, for a human-readable description of what this MachineState class stands for.

transitions¶: a required array of MachineStateTransition objects, each describing a mapping between an incoming event and its corresponding state transition during this state.

timeout¶: an optional temporal Quality, describing when the timeout occurs for this state.

on-start: an optional array of StimulusState or ApparatusState objects, describing what stimulus is turned on/off upon start of this state.

on-end: an optional array of StimulusState or ApparatusState objects, describing what stimulus is turned on/off upon end of this state.

Caution

Unlike the case of StimulusBlock, on-start and on-end has persisting effects i.e. once you set a StimulusState inside a MachineState, the output state will not be cleared unless you explicitly do so.

MachineStateTransition ¶

class MachineStateTransition¶

MachineStateTransition represents a mapping between an incoming event and its corresponding target state.

source¶

a required property hondling a Event or the string "$timeout", representing the event input required for this state transition to occur.

Note that the string "$timeout" refers to the state-timeout event.

target¶

a required property hondling a MachineState or the string "$terminate", representing the next, target state of this state transition.

Note that the string "$terminate" refers to the termination of the state machine.