topsConditions Class Reference

Overview

Traverses combinations of conditions and assigns them to objects.

topsConditions organizes sets of values for various parameters and computes all the combinations of parameter values. It can traverse conditions by number, and apply parameter values to various objects automatically. Since topsConditions is a topsRunnable subclass, it can control the flow of an experiment based on the traversal of conditions.

Each time a topsConditions object run()s, it will pick a new condition, which is a unique combination of parameter values. Each parameter may have some associated "assignments" which allow parameter values to be applied automatically to properties of other objects. The object may call its startFevalable and finishFevalable just before and after applying property assignments.

A topsConditions object has a state (i.e. the condition number) that trancends multiple calls to run(). Thus, it must be reset() to begin picking conditions from scratch. When pickingMethod runs out of conditions to pick, or when maxPicks is reached (whichever is first), an object sets isDone to true and invokes donePickingFevalable. If its caller is set to a topsRunnable object, it also sets isRunning to false for that object.

Inheritance diagram for topsConditions:

Properties and Events
Property	allParameters = struct([])
	struct array of parameter names, values and assignment targets More...
Property	nConditions
	possible number of values combinations from allParameters
Property	currentCondition = 0
	number of the currently picked condition, from 1 to nConditions
Property	previousConditions = []
	array of previously picked condition numbers More...
Property	currentValues = struct
	struct of all parameters and their current values More...
Property	maxPicks = inf
	maximum number of conditions to pick, regardless of pickingMethod. More...
Property	pickingMethod
	string describing how to pick the next condition More...
Property	customPickFevalable
	fevalable cell array for custom picking of condition numbers More...
Property	pickSequence
	array of condition numbers to be picked More...
Property	isDone = true
	true or false, whether all done picking conditions More...
Property	donePickingFevalable = {}
	optional fevalable cell array to invoke when isDone
Property	allSizes
	array of sizes for each parameter's values
Property	subscriptCoefficients
	coefficients to convert contion number to values indexes
Property	pickingMethodDetails = {}
	vasrargin details from the last call to setPickingMethod()
Properties and Events inherited from topsRunnable
Property	startFevalable = {}
	optional fevalable cell array to invoke just before running
Property	finishFevalable = {}
	optional fevalable cell array to invoke just after running
Property	isRunning = false
	true or false, whether this object is currently busy running
Property	caller
	topsRunnable that invoked run() on this object, or empty
Property	startString = 'start'
	string used for topsDataLog entry just before run()
Property	finishString = 'finish'
	string used for topsDataLog entry just after run()
Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object
Property	clockFunction =@topsClock
	clock function, to standardize

Methods
self	topsConditions (varargin)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
	addParameter (self, parameter, values)
	Add a parameter and set of values for condition formation. More...
	addAssignment (self, parameter, object, varargin)
	Add an assignment target for a parameter value. More...
	countConditions (self)
	Account for parameter-value combinations from allParameters.
	setCondition (self, n)
	Pick parameter values for the given condition number. More...
	setPickingMethod (self, pickingMethod, varargin)
	Choose how to pick new conditions. More...
	start (self)
	Log action and reset() as needed. More...
	reset (self)
	Clear previous conditions and begin picking from scratch. More...
	run (self)
	Pick a new condition and assign parameter values to targets.
	finish (self)
	Log action and call out as needed. More...
n	pickConditionNumber (self)
	Pick a condition number using pickingMethod. More...
Methods inherited from topsRunnable
self	topsRunnable (varargin)
	Constuct with name optional. More...
	run (self)
	Do flow control. More...
g	gui (self)
	Show heirarchy of topsRunnable[Composite] objects.
	start (self)
	Log action and prepare to do flow control. More...
	finish (self)
	Log, action and finish doing flow control. More...
	logAction (self, actionName, actionData)
	Log an event of interest with topsDataLog. More...
	logFeval (self, fevalName, fevalable)
	Log a function call with topsDataLog. More...
Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...
fig	gui (self)
	Open a GUI to view object details. More...
p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

Additional Inherited Members
Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...
static selector	cellContains (c, item)
	Does a cell array conatin an item? More...
static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...
static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...
static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Constructor

topsConditions()

self topsConditions

(

varargin

)

Constuct with name optional.

Parameters

name	optional name for this object

If name is provided, assigns name to this object.

Methods

gui()

fig gui

(

self

)

Open a GUI to view object details.

Opens a new GUI with components suitable for viewing objects of this class. Returns a topsFigure object which contains the GUI.

addParameter()

addParameter	(	self	,
		parameter	,
		values
	)

Add a parameter and set of values for condition formation.

Parameters

parameter	string field name of a parameter
values	cell array of posssible values for parameter

Adds the named parameter and its values call array to allParameters. If allParameters already contains a field named parameter, its values will be replaced but any assignments will remain in place.

The parameter-value combinations in allConditions will be updated immediately to reflect parameter and its set of values.

After a parameter is added with addParameter(), parameter assignments may be added with addAssignment().

addAssignment()

addAssignment	(	self	,
		parameter	,
		object	,
		varargin
	)

Add an assignment target for a parameter value.

Parameters

parameter	one of the field names of allParameters
object	an object to receive values of parameter
varargin	arguments to pass to substruct() which specify a property or element of object.

Adds the specified property or element of object as an assignment target for the given property. During run() or setCondition(), the new value of property will be automatically assigned to the target. A property may have multiple assignment targets, each added with addAssignment().

varargin will be passed to Matlab's built-in substruct to specify an arbitrary reference into object–the reference could be to one of object's properties, a sub-element or sub-field of a property, an element of object if it's an array, and so on.

For example, to specify the 'data' property of object, you would use the following to specify a "dot" reference to the "data" field:

addAssignment( ..., '.', 'data');

If parameter is not one of fields of allParameters, does nothing.

setCondition()

setCondition	(	self	,
		n
	)

Pick parameter values for the given condition number.

Parameters

n	the number of the condition to set, from 1 through nConditions

Sets currentCondition to the given n, appends n to the history in previousConditions, and assigns appropriate values to the fields of currentValues. Adds the new currentCondition and currentValues to topsDataLog.

setPickingMethod()

setPickingMethod	(	self	,
		pickingMethod	,
		varargin
	)

Choose how to pick new conditions.

Parameters

pickingMethod

string describing how to pick conditions. @varargin additional arguments specific to each pickingMehtod, described below.

setPickingMethod() determines how run() will choose a new conditon number and traverse parameter values. pickingMethod describes the general approach and varargin may supply some details.

The valid values for pickingMethod are:

• 'coin-toss' uniform random picks without replacement and no specific limit on the number of picks
• 'shuffled' uniform shuffling of conditions, spread out over some number of complete sets. varargin may contain the number of sets to shuffle together, the default is 1.
• 'sequential' non-random, systematic progression through conditions, finishing after some number of complete sets. varargin may contain the number of sets to shuffle together, the default is 1.
• 'custom' user-supplied customPickFevalable determines each condition. varargin should contain an fevalable cell array. The function should expect this topsConditions object as the first argument. Any additional arguments will be passed to the function starting at the second place. The function should pick a new condition number, from 1 through nConditions, and return it. The function may set isDone to indicate that picking is all done.

If pickingMethod is not one of the valid values above, defaults to 'coin-toss'.

start()

start

(

self

)

Log action and reset() as needed.

Extends the start() method of topsRunnable to also reset() condition picking as needed.

reset()

reset

(

self

)

Clear previous conditions and begin picking from scratch.

Clears out the currentCondition and currentValues, and erases the histor of condition numbers stored in previousConditions. Calls setPickingMethod() with the current pickingMethod, to generate a fresh pickSequence as necessary. Sets isDone to false.

run() and start() automatically call reset() when isDone is true, to prepare for future run() calls.

finish()

finish

(

self

)

Log action and call out as needed.

Extends the finish() method of topsRunnable to also invoke donePickingFevalable and tell caller to stop running, when condition picking is over.

pickConditionNumber()

n pickConditionNumber

(

self

)

Pick a condition number using pickingMethod.

Returns a new condition number picked using the pickingMethod and other details specified with setPickingMethod(). If the picking method has reached its natural conclusion, or the total number of picks is greated than maxPicks, sets isDone to true.

Properties and Events

allParameters

Property allParameters = struct([])

struct array of parameter names, values and assignment targets

Each field name of allParameters is the name of an arbitrary parameter. Each field contains another struct with the fields:

• values cell array of possible values for the parameter
• assignments struct array of objects and substruct()-style references used to assign parameter values to each object.

Users should call addParameter() and addAssignment() instead of manipulating allParameters directly.

previousConditions

Property previousConditions = []

array of previously picked condition numbers

Keeps track of the history of conditions that were picked, including currentCondition. reset() empties out previousConditions.

currentValues

Property currentValues = struct

struct of all parameters and their current values

Each field name of currentValues is one of the parameter names from allParameters. Each field contains the value of that parameter that corresponds to the condition number in currentCOndition.

maxPicks

Property maxPicks = inf

maximum number of conditions to pick, regardless of pickingMethod.

pickingMethod

Property pickingMethod

string describing how to pick the next condition

pickingMethod is the string name of a method for picking the next condition. See setPickingMethod() for a description of valid pickingMethods.

Users should call setPickingMethod() instead of accessing the pickingMethod property directly.

customPickFevalable

Property customPickFevalable

fevalable cell array for custom picking of condition numbers

When pickingMethod is 'custom', run() invokes customPickFevalable to pick the next condition number. See setPickingMethod() for a description of customPickFevalable.

Users should call setPickingMethod() instead of accessing customPickFevalable directly.

pickSequence

Property pickSequence

array of condition numbers to be picked

When pickingMethod is 'shuffled' or 'sequential', setPickingMethod() precomputes pickSequence with complete sets of condition numbers.

Users should call setPickingMethod() instead of accessing pickSequence directly.

isDone

Property isDone = true

true or false, whether all done picking conditions

When pickingMethond runs out of conditions to pick, or when maxPicks is reached (whichever is first) sets isDone to true.

If isDone is true when run() is called, first calls reset() to prepare for future running.

---

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

• topsConditions.m