run a task via a series of states. More...

Detailed Description

run a task via a series of states.

stateMachine allows a set of 'states' to be run, with functions executed on entering state, within the state, and on exiting the state. States can be linked, so a 'middle' state can be run after a 'start' state. States can run in a loop (run() method) and use either real time as assesed using the clockFcn fHandle property or via tick time, where each update() to the stateMachine is a 'tick'. Tick time is useful when controlled via an external manager like the Psychophysics toolbox which uses display refresh as a natural tick timer.

╔════════════════════════════════════════════════════════════════════════════════════════════════╗
║                  ┌─────────┐                                       ┌─────────┐                 ║
║                  │ STATE 1 │                                       │ STATE 2 │                 ║
║       ┌──────────┴─────────┴───────────┐                ┌──────────┴─────────┴──────────┐      ║
║  ┌────┴────┐      ┌────────┐      ┌────┴───┐       ┌────┴────┐      ┌────────┐     ┌────┴───┐  ║
╚═▶│  ENTER  │─────▶│ WITHIN │─────▶│  EXIT  │══════▶│  ENTER  │─────▶│ WITHIN │────▶│  EXIT  │══╣
   └────┬────┘      └────────┘      └────┬───┘       └────┬────┘      └────────┘     └────┬───┘  ║
        │          ┌──────────┐          │                │          ┌──────────┐         │      ║
        └──────────┤TRANSITION├──────────┘                └──────────┤TRANSITION├─────────┘      ║
                   └─────╦────┘                                      └──────────┘                ║
                         ║                  ┌─────────┐                                          ║
                         ║                  │ STATE 3 │                                          ║
                         ║       ┌──────────┴─────────┴───────────┐                              ║
                         ║  ┌────┴────┐      ┌────────┐      ┌────┴───┐                          ║
                         ╚═▶│  ENTER  │─────▶│ WITHIN │─────▶│  EXIT  │══════════════════════════╝
                            └────┬────┘      └────────┘      └────┬───┘
                                 │          ┌──────────┐          │
                                 └──────────┤TRANSITION├──────────┘
                                            └──────────┘

States have 4 fundamental evaluation points: ENTER, WITHIN, TRANSITION and EXIT. Each evaluation point takes a cell array of functions to run. TRANSITION evaluation is used to allow logic to switch from a default transition path to an alternate. For example, you can imagine a default stimulus > incorrect transition, but if the subject answers correctly you can use the transition evaluation to switch instead to the correct state.

To run a demo, try the following:

>> sm = stateMachine;

>> runDemo(sm);

stateMachine::runDemo

function runDemo(in me)

runDemo runs a sample state machine session

stateMachine::stateMachine

function stateMachine(in varargin)

Class constructor.

To see how to run the stateMacine from a PTB loop, see runExperiment.runTask(); and check DefaultStateInfo.m and METHODS.md

Inheritance diagram for stateMachine:

Public Member Functions
function	stateMachine (in varargin)
	Class constructor. More...

function	addStates (in me, in newStates)
	Add new states to the state machine. More...

function	addState (in me, in newState)
	add a single State to the state machine More...

function	editStateByName (in me, in stateName, in varargin)

function	getState (in me, in stateName)
	getState retrieve a named state from the state list More...

function	update (in me)
	update the state machine, normally run via an external loop More...

function	forceTransition (in me, in stateName)
	forceTransition force the state machine into a new named state More...

function	start (in me)
	start the state machine More...

function	finish (in me)
	finish stop the state machine More...

function	run (in me)
	run automomously run the state machine More...

function	isStateName (in me, in stateName)
	Check whether a string is the name of a state. More...

function	evalExitFcn (in me, in value)
	evalExitFcn sets current state skipExit value More...

function	printCurrentTick (in me)
	printcurrentTick prints current (and total) ticks to command window More...

function	UUID (in me)
	UUID function to return current UUID via a method. More...

function	reset (in me)
	reset the object More...

function	runDemo (in me)
	runDemo runs a sample state machine session More...

function	warmUp (in me)
	warmup state machine More...

function set	skipExitStates (in me, in list)
	skip exit state functions: sets an N x 2 cell array More...

function	showLog (in me)
	show the log if present More...

Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor. More...

function get	fullName (in me)

function	initialiseSaveFile (in me, in path)
	Initialise Save Dir. More...

function	findAttributes (in me, in attrName, in attrValue)

function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical. More...

function	findPropertyDefault (in me, in propName)

function	clone (in me)

function	checkSuperclasses (in List)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore. More...

function	editProperties (in me, in properties)
	method to modify a set of properties More...

function	setProp (in me, in property, in value)

function	checkPaths (in me)
	checks the paths are valid More...

Static Public Member Functions
static function	plotLogs (in log, in tin)
	loadobj handler More...

Static Public Member Functions inherited from optickaCore
static function	makeArgs (in args)

static function	addDefaults (in args, in defs)
	Converts cell args to structure array. More...

static function	hasKey (in in, in key)
	add default options to arg input More...

Public Attributes
Property	stateList
	our main state list, stored as a structure More...

Property	timeDelta

Property	realTime

Property	clockFcn
	clock function to use (GetSecs from PTB is optimal…) More...

Property	skipExitStates

Property	tempNextState

Property	verbose
	verbose logging to command window? More...

Property	waitFcn
	pause function (WaitSecs from PTB is optimal…) More...

Property	fnTimers
	do we run timers for function evaluations? More...

Property	isRunning
	true or false, whether this object is currently busy running More...

Property	totalTicks
	total number of ticks, updated via runBriefly() and update() More...

Property	startTime
	time at start of stateMachine More...

Property	finalTime
	final time a finish More...

Property	finalTick
	final ticks at finish More...

Property	currentState
	current state More...

Property	currentName
	current state name More...

Property	currentUUID
	current state uuid More...

Property	currentIndex
	current state index More...

Property	currentTick
	ticks within the current state More...

Property	currentTime
	time within current state More...

Property	currentEntryTime
	time entered current state More...

Property	currentEntryFcn
	current entry function More...

Property	currentWithinFcn
	current within function More...

Property	currentTransitionFcn
	current transition function More...

Property	currentExitFcn
	current exit function More...

Property	nextTickOut
	number of ticks before next transition realTime = false More...

Property	nextTimeOut
	time before next transition when realTime = true More...

Property	stateListIndex
	Index with name and index number for each state. More...

Property	log
	run state information More...

Public Attributes inherited from optickaCore
Property	name
	object name More...

Property	comment
	comment More...

Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false More...

Property	dateStamp
	clock() dateStamp set on construction More...

Property	uuid
	universal ID More...

Property	paths
	storage of various paths More...

Property	fullName
	The fullName is the object name combined with its uuid and class name. More...

Protected Member Functions
function	transitionToStateWithName (in me, in nextName)
	transition to a named state More...

function	exitCurrentState (in me)
	clear current properties but leave currentIndex so it's checkable More...

function	enterStateAtIndex (in me, in thisIndex)
	enters a particular state More...

function	storeCurrentStateInfo (in me)
	clear current properties but leave currentIndex so it's checkable More...

Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)

function	addArgs (in me, in args)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties. More...

function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties. More...

function	toStructure (in me)
	set paths for object More...

function	getType (in me, in in)
	Converts properties to a structure. More...

function	salutation (in me, in in, in message, in override)
	Give a metaproperty return the likely property class. More...

function	LogOutput (in me, in in, in message, in override)
	Prints messages dependent on verbosity. More...

Protected Attributes
Property	fevalTime
	feval logging More...

Property	isFinishing
	should we run the finish function More...

Property	stateFields
	field names of allStates struct array, defining state behaviors More...

Property	stateDefaults
	default values of allStates struct array fields More...

Property	allowedProperties
	properties allowed during construction More...

Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object More...

Property	mversion
	Matlab version number, this is transient so it is not saved. More...

Property	className
	class name More...

Property	savePrefix
	save prefix generated from clock time More...

Constructor & Destructor Documentation

◆ stateMachine()

function stateMachine::stateMachine ( in varargin )

Class constructor.

More detailed description of what the constructor does.

Parameters

args	are passed as a structure of properties which is parsed.

Returns: instance of class.

Member Function Documentation

◆ addState()

function stateMachine::addState	(	in	me,
		in	newState
	)

add a single State to the state machine

Parameters

newState a state structure

Returns: newStateIndex an index to the state position in the state list

◆ addStates()

function stateMachine::addStates	(	in	me,
		in	newStates
	)

Add new states to the state machine.

Parameters

newStates a cell array with information defining a state.

Returns: newStateIndexes indexes to newly added states

◆ editStateByName()

function stateMachine::editStateByName	(	in	me,
		in	stateName,
		in	varargin
	)

Edit fields of an existing state.

Parameters

stateName	string name of an existing state in allStates
varargin	flexible number of field-value paris to edit the fields of the stateName state.

Assigns the given values to the given fields of the existing state that has the name stateName. varargin represents a flexible number of traling arguments passed to editStateByName(). The first argument in each pair should be one of the field names of the allStates struct, which include the default state fields described for addField() and the names of any sharedEntry or sharedExit fevalables. The second argument in each pair should be a value to assign to the named field.

Editing the name field of a state might cause the state machine to misbehave.

Returns the index into allStates of the stateName state. If stateName is not the name of an existing state, returns [].

◆ enterStateAtIndex()

function stateMachine::enterStateAtIndex	(	in	me,
		in	thisIndex
	)

protected

enters a particular state

Parameters

thisIndex,the index number of the state

Returns

◆ evalExitFcn()

function stateMachine::evalExitFcn	(	in	me,
		in	value
	)

evalExitFcn sets current state skipExit value

◆ exitCurrentState()

function stateMachine::exitCurrentState ( in me )

protected

clear current properties but leave currentIndex so it's checkable

Parameters

◆ finish()

function stateMachine::finish ( in me )

finish stop the state machine

◆ forceTransition()

function stateMachine::forceTransition	(	in	me,
		in	stateName
	)

forceTransition force the state machine into a new named state

Parameters

stateName name of the state to transition to

◆ getState()

function stateMachine::getState	(	in	me,
		in	stateName
	)

getState retrieve a named state from the state list

Parameters

stateName name of a particular state

Returns: state the individual state

◆ isStateName()

function stateMachine::isStateName	(	in	me,
		in	stateName
	)

Check whether a string is the name of a state.

Parameters

stateName state name

Returns: isState logical; index position in the state list

◆ plotLogs()

static function stateMachine::plotLogs	(	in	log,
		in	tin
	)

static

loadobj handler

plot timing logs

◆ printCurrentTick()

function stateMachine::printCurrentTick ( in me )

printcurrentTick prints current (and total) ticks to command window

◆ reset()

function stateMachine::reset ( in me )

reset the object

◆ run()

function stateMachine::run ( in me )

run automomously run the state machine

◆ runDemo()

function stateMachine::runDemo ( in me )

runDemo runs a sample state machine session

◆ showLog()

function stateMachine::showLog ( in me )

show the log if present

Parameters

◆ skipExitStates()

function set stateMachine::skipExitStates	(	in	me,
		in	list
	)

skip exit state functions: sets an N x 2 cell array

Parameters

list	Nx2 cell array list of strings to compare

Returns

◆ start()

function stateMachine::start ( in me )

start the state machine

◆ storeCurrentStateInfo()

function stateMachine::storeCurrentStateInfo ( in me )

protected

clear current properties but leave currentIndex so it's checkable

Parameters

◆ transitionToStateWithName()

function stateMachine::transitionToStateWithName	(	in	me,
		in	nextName
	)

protected

transition to a named state

Parameters

nextName the next state to switch to

Returns

◆ update()

function stateMachine::update ( in me )

update the state machine, normally run via an external loop

◆ UUID()

function stateMachine::UUID ( in me )

UUID function to return current UUID via a method.

◆ warmUp()

function stateMachine::warmUp ( in me )

warmup state machine

Member Data Documentation

◆ allowedProperties

Property stateMachine::allowedProperties

protected

properties allowed during construction

◆ clockFcn

Property stateMachine::clockFcn

clock function to use (GetSecs from PTB is optimal…)

◆ currentEntryFcn

Property stateMachine::currentEntryFcn

current entry function

◆ currentEntryTime

Property stateMachine::currentEntryTime

time entered current state

◆ currentExitFcn

Property stateMachine::currentExitFcn

current exit function

◆ currentIndex

Property stateMachine::currentIndex

current state index

◆ currentName

Property stateMachine::currentName

current state name

◆ currentState

Property stateMachine::currentState

current state

◆ currentTick

Property stateMachine::currentTick

ticks within the current state

◆ currentTime

Property stateMachine::currentTime

time within current state

◆ currentTransitionFcn

Property stateMachine::currentTransitionFcn

current transition function

◆ currentUUID

Property stateMachine::currentUUID

current state uuid

◆ currentWithinFcn

Property stateMachine::currentWithinFcn

current within function

◆ fevalTime

Property stateMachine::fevalTime

protected

feval logging

◆ finalTick

Property stateMachine::finalTick

final ticks at finish

◆ finalTime

Property stateMachine::finalTime

final time a finish

◆ fnTimers

Property stateMachine::fnTimers

do we run timers for function evaluations?

◆ isFinishing

Property stateMachine::isFinishing

protected

should we run the finish function

◆ isRunning

Property stateMachine::isRunning

true or false, whether this object is currently busy running

◆ log

Property stateMachine::log

run state information

◆ nextTickOut

Property stateMachine::nextTickOut

number of ticks before next transition realTime = false

◆ nextTimeOut

Property stateMachine::nextTimeOut

time before next transition when realTime = true

◆ realTime

Property stateMachine::realTime

use real time (true) or ticks (false) to mark state time. Real time is more accurate, and robust against unexpected delays. Ticks uses timeDelta per tick and a tick timer (each loop is 1 tick) for time measurement. This is simpler, can be controlled by an external driver that deals with timing, and without supervision but delays may accumulate vs real timer.

◆ skipExitStates

Property stateMachine::skipExitStates

N x 2 cell array of strings to compare, list to skip the current -> next state's exit functions; for example skipExitStates = {'fixate',{'incorrect','breakfix'}}; means that if the currentstate is 'fixate' and the next state is either incorrect OR breakfix, then skip the FIXATE exit state. Add multiple rows for skipping multiple state's exit states.

◆ startTime

Property stateMachine::startTime

time at start of stateMachine

◆ stateDefaults

Property stateMachine::stateDefaults

protected

default values of allStates struct array fields

◆ stateFields

Property stateMachine::stateFields

protected

field names of allStates struct array, defining state behaviors

◆ stateList

Property stateMachine::stateList

our main state list, stored as a structure

◆ stateListIndex

Property stateMachine::stateListIndex

Index with name and index number for each state.

◆ tempNextState

Property stateMachine::tempNextState

for a state transition you can override the next state, but this is reset on the transition, so you need logic at runtime to set this value each time. This can be used in an experiment where you set this when you are in state A, and based on a probability you can transition to state B or state C for example. See taskSequence.trialVar and runExperiment.updateNextState for the tools to use this.

◆ timeDelta

Property stateMachine::timeDelta

timedelta for time > ticks calculation, assume 1e-3 by default can set to IFI of display.

◆ totalTicks

Property stateMachine::totalTicks

total number of ticks, updated via runBriefly() and update()

◆ verbose

Property stateMachine::verbose

verbose logging to command window?

◆ waitFcn

Property stateMachine::waitFcn

pause function (WaitSecs from PTB is optimal…)

The documentation for this class was generated from the following file:

stateMachine.m

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ stateMachine()

Member Function Documentation

◆ addState()

◆ addStates()

◆ editStateByName()

◆ enterStateAtIndex()

◆ evalExitFcn()

◆ exitCurrentState()

◆ finish()

◆ forceTransition()

◆ getState()

◆ isStateName()

◆ plotLogs()

◆ printCurrentTick()

◆ reset()

◆ run()

◆ runDemo()

◆ showLog()

◆ skipExitStates()

◆ start()

◆ storeCurrentStateInfo()

◆ transitionToStateWithName()

◆ update()

◆ UUID()

◆ warmUp()

Member Data Documentation

◆ allowedProperties

◆ clockFcn

◆ currentEntryFcn

◆ currentEntryTime

◆ currentExitFcn

◆ currentIndex

◆ currentName

◆ currentState

◆ currentTick

◆ currentTime

◆ currentTransitionFcn

◆ currentUUID

◆ currentWithinFcn

◆ fevalTime

◆ finalTick

◆ finalTime

◆ fnTimers

◆ isFinishing

◆ isRunning

◆ log

◆ nextTickOut

◆ nextTimeOut

◆ realTime

◆ skipExitStates

◆ startTime

◆ stateDefaults

◆ stateFields

◆ stateList

◆ stateListIndex

◆ tempNextState

◆ timeDelta

◆ totalTicks

◆ verbose

◆ waitFcn