runExperiment Class Reference

The main experiment manager. More...

Detailed Description

The main experiment manager.

RUNEXPERIMENT accepts a variable sequence « taskSequence », stimulus set « metaStimulus » and for behavioural tasks a « stateMachine » state machine file, and runs the stimuli based on the task objects passed. This class uses the fundamental configuration of the screen (calibration, size etc. via « screenManager »), and manages communication to a DAQ systems using digital I/O and communication over a TCP/UDP client⇄server socket (via «dataConnection»). It also interfaces with hardware like eyetrackers

There are 2 main experiment types: 1) MOC (method of constants) tasks – uses stimuli and task objects directly to run standard randomised variable tasks. See optickatest.m for an example. Does not use the «stateMachine». 2) Behavioural tasks that use state machines for control logic. These tasks still use stimuli and task objects to provide stimuli and variable lists, but use a state machine to control the task structure.

Stimuli should be «metaStimulus» class, so for example:

myStim = metaStimulus;
myStim{1} = gratingStimulus('mask',true,'sf',1);
task = taskSequence; % this creates randomised variable lists
task.nVar = struct('name','angle','stimulus',1,'values',[-90 0 90]);
myExp = runExperiment('stimuli', myStim,'task', task);
runMOC(myExp); % run method of constants type experiment

will run a minimal experiment showing a 1c/d circularly masked grating.

Todo:

refactor checkKey(): can we use a config for keyboard commands?

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

Inheritance diagram for runExperiment:

Public Member Functions
function	runExperiment (in varargin)
function	runMOC (in me, in tS)
function	runTask (in me)
function	runTests (in me, in test)
function	initialise (in me, in config)
function	checkTaskEnded (in me)
function	checkScreenError (in me)
function	showTimingLog (in me, in h)
function	updateFixationTarget (in me, in useStimuli, in varargin)
function	updateExclusionZones (in me, in useStimuli, in radius)
function	updateConditionalFixationTarget (in me, in stimulus, in variable, in value, in varargin)
function	keyOverride (in me)
	when running allow keyboard override, so we can edit/debug things within the loop!
function set	verbose (in me, in value)
function set	stimuli (in me, in in)
function	randomiseTrainingList (in me)
function	setStrobeValue (in me, in value)
function	doStrobe (in me, in value)
function	doSyncTime (in me)
function	needEyeSample (in me, in value)
	set needSample if eyeManager getSample on current flip?
function	needFlip (in me, in value, in trackervalue)
function	getTaskIndex (in me, in index)
function	logRun (in me, in tag)
	print run info to command window
function	updateTask (in me, in result)
function	updateStaircaseAfterState (in me, in result, in state)
function	updateNextState (in me, in type)
function	updateVariables (in me, in index, in override, in update)
function	deleteRunLog (in me)
	deletes the run logs
function	refreshScreen (in me)
	refresh the screen values stored in the object
function	needFlipTracker (in me, in value)
function	enableFlip (in me)
function	disableFlip (in me)
function	noop (in me)
function	configureTouchScreen (in me, in s)
function	configureEyetracker (in me, in s)
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	plotEyeLogs (in tS)
	manage key commands during task loop
static function	loadobj (in in)
	loadobj To be backwards compatible to older saved protocols, we have to parse structures / objects specifically during object load
static function	rebuild ()
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	sessionData
Property	stimuli
	a metaStimulus class instance holding our stimulus objects
Property	task
	a taskSequence class instance determining our stimulus variables
Property	screen
	a screenManager class instance managing the PTB Screen
Property	stateInfoFile
	filename for a stateMachine state info file
Property	userFunctionsFile
	user functions file that can be passed to the state machine
Property	strobe
Property	reward
	what reward device to use
Property	eyetracker
	which eyetracker to use
Property	touch
Property	control
Property	keyboardDevice
Property	logFrames
	log all frame times?
Property	debug
	enable debugging? (poorer temporal fidelity)
Property	verbose
	verbose logging to command window?
Property	screenSettings
	structure for screenManager on initialisation and info from opticka
Property	uiCommand
	this lets the opticka UI leave commands to runExperiment
Property	isRunning
	return if runExperiment is running (true) or not (false)
Property	benchmark
	flip as fast as possible?
Property	drawFixation
	draw simple fixation cross during trial for MOC tasks?
Property	visualDebug
	shows the info text and position grid during stimulus presentation
Property	stimList
	used to select single stimulus in training mode
Property	thisStim
	which stimulus is selected?
Property	tS
	tS is the runtime settings structure, saved here as a backup
Property	askForComments
	ask for comments?
Property	photoDiode
Property	diaryMode
	turn diary on for runTask, saved to the same folder as the data
Property	optickaVersion
	opticka version, passed on first use by opticka
Property	logStateTimers
	do we record times for every function run by state machine?
Property	comments
	do we ask for comments for runMOC
Property	stimulus
	our old stimulus structure used to be a simple cell, now we use metaStimulus
Property	audioDevice
	audio device
Property	subjectName
	DEPRECATED.
Property	researcherName
	DEPRECATED.
Property	lastXPosition
	keep track of several task values during runTask()
Property	lastYPosition
Property	lastXExclusion
Property	lastYExclusion
Property	lastSize
Property	lastIndex
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.

Additional Inherited Members
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 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

runExperiment()

runExperiment::runExperiment

(

in

varargin

)

runExperiment CONSTRUCTOR

Parameters

varargin

can be passed as a structure or name,arg pairs

Returns

instance of the class.

Member Function Documentation

checkScreenError()

runExperiment::checkScreenError

(

in

me

)

check if screenManager is in a good state

checkTaskEnded()

runExperiment::checkTaskEnded

(

in

me

)

Check if stateMachine has finished, set me.stopTask true

configureEyetracker()

runExperiment::configureEyetracker	(	in	me,
		in	s
	)

Configures (calibration etc.) the eyetracker.

Parameters

s	screen object

configureTouchScreen()

function runExperiment::configureTouchScreen	(	in	me,
		in	s
	)

deleteRunLog()

runExperiment::deleteRunLog

(

in

me

)

deletes the run logs

Parameters

disableFlip()

function runExperiment::disableFlip

(

in

me

)

doStrobe()

runExperiment::doStrobe	(	in	me,
		in	value
	)

set I/O strobe to trigger on NEXT FLIP

Parameters

value

true or false

doSyncTime()

runExperiment::doSyncTime

(

in

me

)

send SYNCTIME message to eyetracker after flip

enableFlip()

runExperiment::enableFlip

(

in

me

)

Enable screen flipping for main [and optionally tracker screen]

Parameters

value	- true/false for subject screen
trackervalue	- 0=disable flip, 1=enable + don't clear, 2= enable + clear, 3=force, 4=force first frame then switch to 1

getTaskIndex()

runExperiment::getTaskIndex	(	in	me,
		in	index
	)

This method gets the unique value of the current trial from taskSequence. This is useful for sending to the eyetracker or I/O devices to label which variable value is being shown.

Parameters

the	index to a particular trial

Returns

the unique variable number

initialise()

runExperiment::initialise	(	in	me,
		in	config
	)

Prepares run for the local machine

Parameters

config

[nostimuli | noscreen | notask] allows excluding screen / task initialisation

keyOverride()

runExperiment::keyOverride

(

in

me

)

when running allow keyboard override, so we can edit/debug things within the loop!

loadobj()

static function runExperiment::loadobj ( in  in )

static

loadobj To be backwards compatible to older saved protocols, we have to parse structures / objects specifically during object load

Parameters

in	input object/structure

logRun()

runExperiment::logRun	(	in	me,
		in	tag
	)

print run info to command window

Parameters

tag	what name to give this log printout

needEyeSample()

runExperiment::needEyeSample	(	in	me,
		in	value
	)

set needSample if eyeManager getSample on current flip?

Parameters

value

needFlip()

disableFlip deprecated for runExperiment::needFlip	(	in	me,
		in	value,
		in	trackervalue
	)

Enable screen flip

Disable screen flip

needFlipTracker()

runExperiment::needFlipTracker	(	in	me,
		in	value
	)

Enables/disable the flip for the tracker display window

Parameters

trackervalue

- 0=disable flip, 1=enable + don't clear, 2= enable + clear, 3=force, 4=force first frame then switch to 1

noop()

runExperiment::noop

(

in

me

)

no operation, tests method call overhead

plotEyeLogs()

static function runExperiment::plotEyeLogs ( in  tS )

static

manage key commands during task loop

Parameters

args	input structure

randomiseTrainingList()

runExperiment::randomiseTrainingList

(

in

me

)

For single stimulus presentation, randomise stimulus choice

rebuild()

static function runExperiment::rebuild ( )

static

refreshScreen()

runExperiment::refreshScreen

(

in

me

)

refresh the screen values stored in the object

Parameters

runMOC()

runExperiment::runMOC	(	in	me,
		in	tS
	)

runMOC uses built-in loop for experiment control and runs a methods-of-constants (MOC) experiment with the settings passed to it (stimuli,task and screen). This is different to the runTask method as it doesn't use a stateMachine for experimental logic, just a minimal deterministic trial+block loop.

Todo:

currently we can only record eye positions with the eyelink, add other tracker support

Parameters

me	required class object
tS	structure with some options to pass

runTask()

runExperiment::runTask

(

in

me

)

runTask runs a state machine (behaviourally) driven task.

Uses a StateInfo.m file to control the behavioural paradigm. The state machine controls the logic of the experiment, and this method manages the display loop.

runTests()

runExperiment::runTests	(	in	me,
		in	test
	)

Tests the hardware interfaces

Parameters

test	- marker | reward | audio | eyetracker

setStrobeValue()

runExperiment::setStrobeValue	(	in	me,
		in	value
	)

Set strobe value

Parameters

value

the value to set the I/O system

showTimingLog()

runExperiment::showTimingLog	(	in	me,
		in	h
	)

Prints out the frame time plots from a run

stimuli()

function set runExperiment::stimuli	(	in	me,
		in	in
	)

updateConditionalFixationTarget()

runExperiment::updateConditionalFixationTarget	(	in	me,
		in	stimulus,
		in	variable,
		in	value,
		in	varargin
	)

Checks the variable value of a stimulus (e.g. its angle) and then sets a fixation target based on that value, so you can use multiple test stimuli and set the target to one of them in a forced choice paradigm that matches the variable value

Parameters

stimulus	which stimulus or stimuli to check
variable	which variable to check
value	which value to check for
varargin	additional parameters to set the fixation window

updateExclusionZones()

runExperiment::updateExclusionZones	(	in	me,
		in	useStimuli,
		in	radius
	)

Updates eyetracker with current stimuli tagged for exclusion using metaStimulus.exclusionChoice

Parameters

useStimuli	use the metaStimulus parameters
radius	of the exclusion zone

updateFixationTarget()

runExperiment::updateFixationTarget	(	in	me,
		in	useStimuli,
		in	varargin
	)

Sometimes you want the fixation to follow the position of a particular stimulus. We can 'tag' the stimulus using metaStimulus.fixationChoice and then use this method to get the current position and update the eyetracker fixation window[s] to match the stimuli we tagged.

Parameters

useStimuli	do we use the current stimuli positions or the last known positions that are stored in me.stimuli.last[X|Y]Position. If this is a number we force it to the specific stimuli.
varargin	the rest of the parameters normally passed to eyeTracker.updateFixationValues: inittime,fixtime,radius,strict

updateNextState()

runExperiment::updateNextState	(	in	me,
		in	type
	)

taskSequence can generate a trial factor, and we can set these to the name of a state in the stateMachine. This means we can choose a state based on the trial factor in taskSequence. This sets stateMacine.tempNextState to override the state table next field.

Parameters

type	- whether to use 'trial' [default] or 'block' factor

updateStaircaseAfterState()

runExperiment::updateStaircaseAfterState	(	in	me,
		in	result,
		in	state
	)

Updates taskSequence with current info and the result for that trial running the taskSequence.updateTask function

Parameters

result

an integer result, e.g. 1 = correct or -1 = breakfix

updateTask()

runExperiment::updateTask	(	in	me,
		in	result
	)

Updates taskSequence with current info and the result for that trial running the taskSequence.updateTask function

Parameters

result

an integer result, e.g. 1 = correct or -1 = breakfix

updateVariables()

runExperiment::updateVariables	(	in	me,
		in	index,
		in	override,
		in	update
	)

Updates the stimulus objects with the current variable set from taskSequence()

Parameters

index	a single value of which the overall trial number is
override	[true] - forces updating even if it is the same trial
update	[false] - do we also run taskSequence.updateTask() as well?

verbose()

function set runExperiment::verbose	(	in	me,
		in	value
	)

Member Data Documentation

askForComments

Property runExperiment::askForComments

ask for comments?

audioDevice

Property runExperiment::audioDevice

audio device

benchmark

Property runExperiment::benchmark

flip as fast as possible?

comments

Property runExperiment::comments

do we ask for comments for runMOC

control

Property runExperiment::control

use control commands to start / stop recording device = intan | plexon | none port = tcp port

debug

Property runExperiment::debug

enable debugging? (poorer temporal fidelity)

diaryMode

Property runExperiment::diaryMode

turn diary on for runTask, saved to the same folder as the data

drawFixation

Property runExperiment::drawFixation

draw simple fixation cross during trial for MOC tasks?

eyetracker

Property runExperiment::eyetracker

which eyetracker to use

isRunning

Property runExperiment::isRunning

return if runExperiment is running (true) or not (false)

keyboardDevice

Property runExperiment::keyboardDevice

Keyboard device, use -1 for all keyboards (slower) or [] for default

lastIndex

Property runExperiment::lastIndex

lastSize

Property runExperiment::lastSize

lastXExclusion

Property runExperiment::lastXExclusion

lastXPosition

Property runExperiment::lastXPosition

keep track of several task values during runTask()

lastYExclusion

Property runExperiment::lastYExclusion

lastYPosition

Property runExperiment::lastYPosition

logFrames

Property runExperiment::logFrames

log all frame times?

logStateTimers

Property runExperiment::logStateTimers

do we record times for every function run by state machine?

optickaVersion

Property runExperiment::optickaVersion

opticka version, passed on first use by opticka

photoDiode

Property runExperiment::photoDiode

show a white square in the top-right corner to trigger a photodiode attached to screen for MOC task. For stateMachine tasks you need to pass in the drawing command for this to take effect.

researcherName

Property runExperiment::researcherName

DEPRECATED.

reward

Property runExperiment::reward

what reward device to use

screen

Property runExperiment::screen

a screenManager class instance managing the PTB Screen

screenSettings

Property runExperiment::screenSettings

structure for screenManager on initialisation and info from opticka

sessionData

Property runExperiment::sessionData

stateInfoFile

Property runExperiment::stateInfoFile

filename for a stateMachine state info file

stimList

Property runExperiment::stimList

used to select single stimulus in training mode

stimuli

set runExperiment::stimuli

a metaStimulus class instance holding our stimulus objects

Migrate to use a metaStimulus object to manage stimulus objects

stimulus

Property runExperiment::stimulus

our old stimulus structure used to be a simple cell, now we use metaStimulus

strobe

Property runExperiment::strobe

what strobe device to use device = '' | display++ | datapixx | labjackt | labjack | nirsmart optional port = not needed for most of the interfaces optional config = plain | plexon style strobe default stim OFF strobe value

subjectName

Property runExperiment::subjectName

DEPRECATED.

task

Property runExperiment::task

a taskSequence class instance determining our stimulus variables

thisStim

Property runExperiment::thisStim

which stimulus is selected?

touch

Property runExperiment::touch

tS

Property runExperiment::tS

tS is the runtime settings structure, saved here as a backup

uiCommand

Property runExperiment::uiCommand

this lets the opticka UI leave commands to runExperiment

userFunctionsFile

Property runExperiment::userFunctionsFile

user functions file that can be passed to the state machine

verbose

set runExperiment::verbose

verbose logging to command window?

Let us cascase verbosity to other classes

visualDebug

Property runExperiment::visualDebug

shows the info text and position grid during stimulus presentation

---

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

• runExperiment.m