Overview
A tree-like way to organize an experiment.
topsTreeNode gives you a uniform, tree-like framework for organizing the different components of an experiment. All levels of organization–trials, sets of trials, tasks, paradigmns, whole experiments–can be represented by interconnected topsTreeNode objects, as one large tree.
Every node may have other topsTreeNode objects as "children". You start an experiment by calling run() on the topmost node. It invokes a "start" function and then calls run() each of its child nodes. Each child does the same, invoking its own "start" function and then invoking run() on each of its children.
This flow of "start" and run() continues until it reaches the bottom of the tree where there is a node that has no children. The bottom nodes might be topsRunnable objects of any type, not just topsTreeNode.
Then it's back up the tree. On the way up, each child may invoke its "finish" function before passing control back to the node above it. Once a higher node finishes calling run() all of its children, it may invoke its own "finish" function, and so one, until the flow reaches the topmost node again. At that point the experiment is done.
topsTreeNode only treats the structure of an experiment. The details have to be defined elsewhere, as in specific "start" and "finish" functions, and with bottom nodes of various topsRunnable subclasses.
Many psychophysics experiments use a tree structure implicitly, along with a similar down-then-up flow of behavior. topsTreeNode makes the stucture and flow explicit, which offers some advantages:
- You can extend your task structure arbitrarily, without running out of vocabulary words or hard-coded concepts like "task" "block", "subblock", "trial", "intertrial", etc.
- You can visualize the structure of your experiment using the topsTreeNode.gui() method.
Properties and Events | |
| Property | iterations = 1 |
| number of times to run through this node's children | |
| Property | iterationCount = 0 |
| count of iterations while running | |
| Property | iterationMethod = 'sequential' |
| how to run through this node's children–'sequential' or 'random' order | |
| Property | nodeData = [] |
| For any node-specific data. | |
| Property | helpers = struct() |
| The helpers. | |
| Property | inheritHelpers = 'all' |
| Flag indicating whether to inherit all helpers from parent. | |
| Property | helperTypes = {'drawable', 'targets', 'playable', 'readable', 'writable', 'message', 'general'} |
| List of helper types. | |
 Properties and Events inherited from topsRunnableComposite | |
| Property | children = {} |
| cell array of topsRunnable (or subclass) objects | |
| 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 | topsTreeNode (varargin) |
| Constuct with name optional. More... | |
| child | newChildNode (self, varargin) |
| Create a new topsTreeNode child and add it beneath this node. More... | |
| addChild (self, child) | |
| Add a child and process inheritance. | |
| abort (self) | |
| Convenient routine to abort running self and children. | |
| addCall (self, tag, fevalable, name, theObject) | |
| Add fevalable to the start/finish fevalable call list. It's a. More... | |
| theHelpers | addHelpers (self, constructor, varargin) |
| Add helper(s) to the node. More... | |
| helper | getHelperByClassName (self, name) |
| Find a helper of the named class. | |
| helper | getControlHelper (self) |
| Get the control helper (see topsTreeNodeTopNode) | |
| run (self) | |
| Recursively run(), starting with this node. More... | |
| Methods inherited from topsRunnableComposite | |
| self | topsRunnableComposite (varargin) |
| Constuct with name optional. More... | |
| fig | gui (self) |
| Open a GUI to view object details. More... | |
| addChild (self, child) | |
| Add a child beneath this object. More... | |
| removeChild (self, child) | |
| Remove a child beneath this object. More... | |
| selector | isChild (self, child) |
| Check if child is there. | |
| 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
◆ topsTreeNode()
| self topsTreeNode | ( | varargin | ) |
Constuct with name optional.
- Parameters
-
name optional name for this object
If name is provided, assigns name to this object.
Methods
◆ newChildNode()
| child newChildNode | ( | self | , |
| varargin | |||
| ) |
Create a new topsTreeNode child and add it beneath this node.
- Parameters
-
name optional name for the new child node
Returns a new topsTreeNode which is a child of this node.
◆ addCall()
| addCall | ( | self | , |
| tag | , | ||
| fevalable | , | ||
| name | , | ||
| theObject | |||
| ) |
Add fevalable to the start/finish fevalable call list. It's a.
little bit complicated because you can optionally send in an object to use as the first argument of the fevalabe. This is useful for "binding" helper objects to particular nodes. See topsTaskHelper for examples. 'tag' ... 'start' or 'finish' fevalable ... a cell array that is sent to feval name ... string name (default is the current time, to ensure uniqueness theObject ... optional argument that can be sent as the first argument to the function to feval
◆ addHelpers()
| theHelpers addHelpers | ( | self | , |
| constructor | , | ||
| varargin | |||
| ) |
Add helper(s) to the node.
Call with no arguments to add default helpers for the given node, based on properties named in the 'helperTypes' list Otherwise call with the name of the constructor and args, which are sent to topsTaskHelper.makeHelpers
◆ run()
| run | ( | self | ) |
Recursively run(), starting with this node.
Begin traversing the tree with this node as the topmost node. The sequence of events should go like this:
- This node executes its startFevalable
- This node does zero or more "iterations":
- This node calls run() on each of its children, in an order determined by this node's iterationMethod. Each child then performs the same sequence of actions as this node.
- This node executes its finishFevalable
Note that the sequence of events is recursive. Thus, the behavior of run() depends on this node as well as its children, their children, etc.
Also note that the recursion happens in the middle of the sequence of events. Thus, startFevalables will tend to happen first, with higher node starting before their children. Then finishFevalables will tend to happen last, with children finishing before higher nodes.
The documentation for this class was generated from the following file:
- topsTreeNode.m
