stateMachine Class Reference

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

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

Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md

Inheritance diagram for stateMachine:

Public Member Functions
function	stateMachine (in varargin)
	Class constructor.
function	addStates (in me, in newStates)
	Add new states to the state machine.
function	addState (in me, in newState)
	add a single State to the state machine
function	editStateByName (in me, in stateName, in varargin)
function	getState (in me, in stateName)
	getState retrieve a named state from the state list
function	update (in me)
	update the state machine, normally run via an external loop
function	forceTransition (in me, in stateName)
	forceTransition force the state machine into a new named state
function	start (in me)
	start the state machine
function	finish (in me, in force)
	finish stop the state machine
function	run (in me)
	run automomously run the state machine
function	isStateName (in me, in stateName)
	Check whether a string is the name of a state.
function	evalExitFcn (in me, in value)
	evalExitFcn sets current state skipExit value
function	printCurrentTick (in me)
	printcurrentTick prints current (and total) ticks to command window
function	UUID (in me)
	UUID function to return current UUID via a method.
function	reset (in me)
	reset the object
function	runDemo (in me)
	runDemo runs a sample state machine session
function	warmUp (in me)
	warmup state machine
function set	skipExitStates (in me, in list)
	skip exit state functions: sets an N x 2 cell array
function	showLog (in me)
	show the log if present
Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.
function get	fullName (in me)
function	getALF (in me, in subject, in sessionPrefix, in lab, in create)
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.
function	findPropertyDefault (in me, in propName)
function	clone (in me)
	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.
function	checkSuperclasses (in List)
function	editProperties (in me, in properties)
	method to modify a set of properties
function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.
function	initialiseGlobals (in me, in doReset, in doOpen)
function	initialiseSaveFile (in me)
	Initialise Save prefix.
function	checkPaths (in me)
	checks the paths are valid

Static Public Member Functions
static function	plotLogs (in log, in tin)
	loadobj handler
Static Public Member Functions inherited from optickaCore
static function	makeArgs (in args)
	Converts cell args to structure array.
static function	addDefaults (in args, in defs)
	add default options to arg input
static function	hasKey (in in, in key)
	check if a struct / object has a propery / field
static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.

Public Attributes
Property	stateList
	our state list, stored as a structure
Property	realTime
Property	timeDelta
Property	clockFcn
	clock function to use (GetSecs from PTB is optimal…)
Property	skipExitStates
Property	tempNextState
Property	verbose
	verbose logging to command window?
Property	waitFcn
	pause function (WaitSecs from PTB is optimal…)
Property	fnTimers
	do we run timers for function evaluations?
Property	logSize
	size of the log arrays to preallocate
Property	isRunning
	true or false, whether this object is currently busy running
Property	totalTicks
	total number of ticks, updated via runBriefly() and update()
Property	startTime
	time at start of stateMachine
Property	finalTime
	final time a finish
Property	finalTick
	final ticks at finish
Property	currentState
	current state
Property	currentName
	current state name
Property	currentUUID
	current state uuid
Property	currentIndex
	current state index
Property	currentTick
	ticks within the current state
Property	currentTime
	time within current state
Property	currentEntryTime
	time entered current state
Property	currentEntryFcn
	current entry function
Property	currentWithinFcn
	current within function
Property	currentTransitionFcn
	current transition function
Property	currentExitFcn
	current exit function
Property	nextTickOut
	number of ticks before next transition when realTime = false
Property	nextTimeOut
	time before next transition when realTime = true
Property	stateListIndex
	Index with name and index number for each state.
Property	log
	run state information
Public Attributes inherited from optickaCore
Property	name
	object name
Property	comment
	comment
Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false
Property	dateStamp
	clock() dateStamp set on construction
Property	uuid
	universal ID
Property	paths
	storage of various paths
Property	fullName
	The fullName is the object name combined with its uuid and class name.

Protected Member Functions
function	transitionToStateWithName (in me, in nextName)
	transition to a named state
function	exitCurrentState (in me)
	exit current state
function	enterStateAtIndex (in me, in thisIndex)
	enters a particular state
function	initialiseLog (in me, in n)
	initialise the log arrays to improve performance
function	finaliseLog (in me)
	clear up log arrays
Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	addArgs (in me, in args)
function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	getFonts (in me)
	set paths for object
function	toStructure (in me)
	Converts properties to a structure.
function	getType (in me, in in)
function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.
function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.

Protected Attributes
Property	nStates
	number of states
Property	thisN
	current state number
Property	isFinishing
	should we run the finish function
Property	stateFields
	field names of allStates struct array, defining state behaviors
Property	stateDefaults
	default values of allStates struct array fields
Property	allowedProperties
	properties allowed during construction
Property	logFields
Property	logValues
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object
Property	mversion
	Matlab version number, this is transient so it is not saved.
Property	sansFont
	sans font
Property	monoFont
	monoFont
Property	className
	class name
Property	savePrefix
	save prefix generated from clock time
Property	fullName_
	cached full name

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

exit current state

Parameters

return

finaliseLog()

function stateMachine::finaliseLog ( in  me )

protected

clear up log arrays

Parameters

return

finish()

function stateMachine::finish	(	in	me,
		in	force
	)

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

initialiseLog()

function stateMachine::initialiseLog ( in  me, in  n  )

protected

initialise the log arrays to improve performance

Parameters

n	number of entries

Returns

isStateName()

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

Check whether a string is the name of a state.

Parameters

stateName

a 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

return

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

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

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

logFields

Property stateMachine::logFields

protected

logSize

Property stateMachine::logSize

size of the log arrays to preallocate

logValues

Property stateMachine::logValues

protected

nextTickOut

Property stateMachine::nextTickOut

number of ticks before next transition when realTime = false

nextTimeOut

Property stateMachine::nextTimeOut

time before next transition when realTime = true

nStates

Property stateMachine::nStates

protected

number of states

realTime

Property stateMachine::realTime

use real time (true, using @clockFcn) or ticks (false) to mark state time. Real time is more accurate / robust against unexpected delays. Ticks uses timeDelta per tick and a tick timer (each update 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 in the external update may cause drift.

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

thisN

Property stateMachine::thisN

protected

current state number

timeDelta

Property stateMachine::timeDelta

timedelta for time > ticks calculation, assume 0.1ms (1e-4) by default can set to IFI of display. This sets the "resolution" when realTime == false

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