Block-based variable randomisation manager. More...

Detailed Description

Block-based variable randomisation manager.

This class takes one or more variables, each with an array of values and randomly interleves them into a randomised variable list each of which has a unique index number.

This example creates an angle varible that is randomised over 5 different values and will be applied to the first 3 stimuli; in addition, the fourth stimulus will have the value offset by 45°:

ts = taskSequence('nBlocks',10);
ts.nVar(1).name = 'angle';
ts.nVar(1).values = [ -90, -45, 0, 45, 90 ];
ts.nVar(1).stimulus = [1, 2, 3];
ts.nVar(1).offsetstimulus = 4;
ts.nVar(1).offsetvalue = 45
ts.randomiseTask;
ts.showLog;

Todo:: integrate carryoverCounterbalance() as an alternative to block randomisation...

Inheritance diagram for taskSequence:

Public Member Functions
function	taskSequence (in varargin)
	Class constructor.

function	initialiseGenerator (in me)
	set up the random number generator

function	resetRandom (in me)
	Reset the random number generator.

function	randomiseTask (in me)
	Do the main randomisation.

function	initialise (in me, in randomise)
	Initialise the variables and task together.

function	backup (in me)
	Initialise the properties used to track the run.

function	updateTask (in me, in thisResponse, in runTime, in info)
	update the task with a response

function	updateStaircase (in me, in thisResponse, in n)

function	findRun (in me, in index)

function	rewindTask (in me)
	this steps back one run

function	resetRun (in me)
	re-randomise within the current block

function set	nVar (in me, in invalue)

function get	nVars (in me)

function get	minTrials (in me)

function get	nRuns (in me)

function get	nFrames (in me)

function	showLog (in me)

function	showTable (in me)
	showTable

function	build_gui (in heightin)

function	getMeta (in me)
	get a meta matrix compatible with VS parsed data, unwrapping cell arrays

function	getLabels (in me)
	get the labels for the variables

function	validate (in me)
	validate the taskSequence is ok

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	cellStruct (in in)
	make a matrix from a cell array

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	nVar
	set method for the nVar structure

Property	blockVar

Property	trialVar

Property	nBlocks
	number of repeated blocks to present

Property	staircase

Property	randomise
	whether to randomise nVar (true) or run sequentially (false)

Property	addBlank
	insert a blank condition in each block?

Property	realTime
	do we follow real time or just number of ticks to get to a known time

Property	randomSeed

Property	randomGenerator
	mersenne twister default, see MATLAB docs for other options

Property	verbose
	verbose or not

Property	fps
	used for dynamically estimating total number of frames

Property	trialTime
	time stimulus trial is shown

Property	isTime
	inter stimulus trial time

Property	ibTime
	inter block time

Property	startIndex
	original index before any resetRun()s

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

◆ taskSequence()

taskSequence::taskSequence ( in varargin )

Class constructor.

Initialises the class sending any parameters to parseArgs.

Parameters

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

Returns: instance of the class.

Member Function Documentation

◆ backup()

taskSequence::backup ( in me )

Initialise the properties used to track the run.

Initialise the properties used to track the run. These are dynamic props.

◆ build_gui()

function taskSequence::build_gui ( in heightin )

◆ cellStruct()

taskSequence::cellStruct ( in in )

static

make a matrix from a cell array

◆ findRun()

function taskSequence::findRun	(	in	me,
		in	index
	)

◆ getLabels()

taskSequence::getLabels ( in me )

get the labels for the variables

◆ getMeta()

taskSequence::getMeta ( in me )

get a meta matrix compatible with VS parsed data, unwrapping cell arrays

Generates a table with the randomised stimulus values

◆ initialise()

taskSequence::initialise	(	in	me,
		in	randomise
	)

Initialise the variables and task together.

Parameters

randomise [default=false] do we force randomiseTask to be run

◆ initialiseGenerator()

taskSequence::initialiseGenerator ( in me )

set up the random number generator

◆ minTrials()

function get taskSequence::minTrials ( in me )

◆ nFrames()

function get taskSequence::nFrames ( in me )

◆ nRuns()

function get taskSequence::nRuns ( in me )

◆ nVar()

function set taskSequence::nVar	(	in	me,
		in	invalue
	)

◆ nVars()

function get taskSequence::nVars ( in me )

◆ randomiseTask()

taskSequence::randomiseTask ( in me )

Do the main randomisation.

This method will take the parameters in nVar, blockVar and trialVar and perform the randomisation and balancing.

◆ resetRandom()

taskSequence::resetRandom ( in me )

Reset the random number generator.

reset the random number generator

◆ resetRun()

taskSequence::resetRun ( in me )

re-randomise within the current block

If the subject got a trial wrong, we want to try to show a different trial within the same block. This adds some randomisation if a run needs to be rerun for a subject and you do not want the same stimulus repeatedly until there is a correct response. Note the limitation is if this is the last trial in a block, the randomisation cannot do anything.

Returns: success did we manage to randomise?; message details of the swapped trials

◆ rewindTask()

taskSequence::rewindTask ( in me )

this steps back one run

◆ showLog()

function taskSequence::showLog ( in me )

◆ showTable()

taskSequence::showTable ( in me )

showTable

Generates a table with the randomised stimulus values

◆ updateStaircase()

function taskSequence::updateStaircase	(	in	me,
		in	thisResponse,
		in	n
	)

◆ updateTask()

taskSequence::updateTask	(	in	me,
		in	thisResponse,
		in	runTime,
		in	info
	)

update the task with a response

This method allows us to update the task with a response, and will track when the task is finished: setting taskFinished==true

◆ validate()

taskSequence::validate ( in me )

validate the taskSequence is ok

Check we have a minimal task structure

Member Data Documentation

◆ addBlank

Property taskSequence::addBlank

insert a blank condition in each block?

◆ blockVar

Property taskSequence::blockVar

independent block level identifying factor, for example blockVar.values={'A','B'} + blockVar.probability = [0.6 0.4]; will assign A and B to blocks with a 60:40 probability.

◆ fps

Property taskSequence::fps

used for dynamically estimating total number of frames

◆ ibTime

Property taskSequence::ibTime

inter block time

◆ isTime

Property taskSequence::isTime

inter stimulus trial time

◆ nBlocks

Property taskSequence::nBlocks

number of repeated blocks to present

◆ nVar

set taskSequence::nVar

set method for the nVar structure

structure holding each independant stimulus variable name = name of the stimulus variable values = the values as a numerical or cell array stimulus = which stimulus to apply to? offsetstimulus = an offset can be applied to other stimuli offsetvalue = the value offset, e.g. 90 for angle will add 90 to any random angle value e.g. nVar(1) = struct('name','contrast','stimulus',[1 2],'values',[0 0.1 0.2],'offsetstimulus',[3],'offsetvalue',[0.1])

Check we have a minimal nVar structure and deals new values appropriately.

◆ randomGenerator

Property taskSequence::randomGenerator

mersenne twister default, see MATLAB docs for other options

◆ randomise

Property taskSequence::randomise

whether to randomise nVar (true) or run sequentially (false)

◆ randomSeed

Property taskSequence::randomSeed

random seed value, we can use this to set the RNG to a known state default is empty to use the unique current date+time

◆ realTime

Property taskSequence::realTime

do we follow real time or just number of ticks to get to a known time

◆ staircase

Property taskSequence::staircase

◆ startIndex

Property taskSequence::startIndex

original index before any resetRun()s

◆ trialTime

Property taskSequence::trialTime

time stimulus trial is shown

◆ trialVar

Property taskSequence::trialVar

independent trial level identifying factor trialVar.values={'YES','NO'} + trialVar.probability = [0.5 0.5]; will assign YES and NO to trials with a 50:50 probability.

◆ verbose

Property taskSequence::verbose

verbose or not

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

taskSequence.m