Controlling Behavioural Tasks using State Machines

Any experiment can be thought of as a series of states (delay period, initiate fixation, present stimulus, give subject feedback, post-trial timeout, etc.) and conditions for switching between these states. State Machines are a widely used control system for these types of scenarios. The important definition of a state machine is:

1. The state machine must be in exactly one of a finite number of states at any given time. States run for a defined amount of time by default before switching to a next state.
2. The state machine can also change from one state to another based on rules; the conditional change from one state to another is called a transition. A function controls the transition (transitionFcn), returning a different state name that forces a transition to this new state.
3. Functions can run when we enter (enterFcn), are within (withinFcn), or exit (exitFcn) a state.

Opticka defines all of this in a StateInfo.m file that specifies function arrays and assigns them to a state list. The Opticka GUI visualises the state table and lists out each function array.

For example this cell array identifies two functions which draw and animate our stims stimulus object. The @() identifies these as MATLAB function handles:

{ @()draw(stims); @()animate(stims); }

Opticka has many core functions that can run during state machine traversal. You can additionally write your own functions and store them in a userFunctions.m class file.

As an example, the DefaultStateInfo.m file defines several experiment states (prefix, fixate, stimulus, incorrect, breakfix, correct, timeout) and how the task switches between them (either with a timer or transitioned using an eyetracker):

The same state flow shown as an ASCII diagram:

                                                       ┌───────────────────┐
                                                       │      prefix       │
  ┌──────────────────────────────────────────────────▶ │    hide(stims)    │ ◀┐
  │                                                    └───────────────────┘  │
  │                                                      │                    │
  │                                                      ▼                    │
  │                         ┌───────────┐  inFixFcn:   ┌───────────────────┐  │
  │                         │ incorrect │  incorrect   │      fixate       │  │
  │                         │           │ ◀─────────── │   show(stims,2)   │  │
  │ reward!                 └───────────┘              └───────────────────┘  │
  │                           │                          │ inFixFcn:          │
  │                           │                          │ stimulus           │
  │                           │                          ▼                    │
┌─────────┐  maintainFixFcn:  │                        ┌───────────────────┐  │
│ correct │  correct          │                        │     stimulus      │  │
│         │ ◀─────────────────┼─────────────────────── │ show(stims,[1 2]) │  │
└─────────┘                   │                        └───────────────────┘  │
                              │                          │ maintainFixFcn:    │
                              │                          │ breakfix           │
                              │                          ▼                    │
                              │                        ┌───────────────────┐  │
                              │                        │     breakfix      │  │
                              │                        └───────────────────┘  │
                              │                          │                    │
                              │                          ▼                    │
                              │                        ┌───────────────────┐  │
                              │                        │      timeout      │  │
                              └──────────────────────▶ │      tS.tOut      │ ─┘
                                                       └───────────────────┘

State info files, being plain .m files, should be edited in the MATLAB editor (the GUI has an edit button that opens the file in the editor for you).

State Table Format

The state machine is defined as a cell array with 8 columns:

stateInfoTmp = {
'name'  'next'  'time'  'entryFcn'  'withinFcn'  'transitionFcn'  'exitFcn' 'HED';
...rows for each state...
};

Example: fixate state definition

fixEntryFcn = { @()show(stims, 2); @()draw(stims) };
fixFcn      = { @()draw(stims); @()drawPhotoDiodeSquare(s, [0 0 0]) };
inFixFcn    = { @()testSearchHoldFixation(eT, 'stimulus', 'breakfix') };
fixExitFcn  = { @()updateFixationValues(eT, [], [], [], tS.stimulusFixTime);
                @()show(stims); @()trackerMessage(eT, 'END_FIX') };

Standard States

Most Opticka protocols use a common set of standard states. You can add, remove, or rename states as needed for your paradigm.

Protocol-specific states

Some protocols add custom states:

The tS Structure

The tS structure is created in the state info file and holds all the settings and constants used throughout the experiment. Common fields include:

Conditional Function Assembly

State info files often conditionally assemble function arrays based on tS settings. This allows a single state file to support multiple experimental modes.

includeErrors pattern

When tS.includeErrors is true, errors advance the task sequence. When false, resetRun(task) is called instead, randomising within the current block:

exitFcn = { @()updatePlot(bR,me); @()updateVariables(me); @()update(stims);
            @()resetAll(eT); @()plot(bR,1) };

if tS.includeErrors
    incExitFcn  = [ { @()logRun(me,'INCORRECT'); @()updateTask(me,tS.INCORRECT) }; exitFcn ];
    breakExitFcn = [ { @()logRun(me,'BREAK_FIX'); @()updateTask(me,tS.BREAKFIX) }; exitFcn ];
else
    incExitFcn  = [ { @()logRun(me,'INCORRECT'); @()resetRun(task) }; exitFcn ];
    breakExitFcn = [ { @()logRun(me,'BREAK_FIX'); @()resetRun(task) }; exitFcn ];
end

useTask pattern

When tS.useTask is true, check if the task has ended after each trial:

if tS.useTask || task.nBlocks > 0
    correctExitFcn = [ correctExitFcn; {@()checkTaskEnded(me)} ];
    incExitFcn     = [ incExitFcn;     {@()checkTaskEnded(me)} ];
    breakExitFcn   = [ breakExitFcn;   {@()checkTaskEnded(me)} ];
end

Dynamic next-state pattern

Use trialVar or blockVar to dynamically choose the next state:

% In tS setup:
task.trialVar.values = {'stimulus', 'catch'};
task.trialVar.probability = [0.8 0.2];

% In fixate transition:
@()updateNextState(me, 'trial')
@()testSearchHoldFixation(eT, sM.tempNextState, 'incorrect')

skipExitStates

When the task ends (all blocks complete), the state machine loops back from correct/incorrect/breakfix to prefix. But we don’t want the exit functions (which update the task) to run again. skipExitStates prevents this:

sM.skipExitStates = { ...
    'correct',   'prefix'; ...
    'incorrect', 'prefix'; ...
    'breakfix',  'prefix' ...
};

When transitioning from any of these states to prefix, the exit functions are skipped.

see METHODS for more details.