First steps with Tower of Psych (tops) and Snow-Dots (dots)

Welcome to our tutorial!

Load the code base with ToolboxToolbox

To get all the classes and functions from tops-dots added to your path, it is most convenient to have ToolboxToolbox installed and type, at startup:

%tbUse('Lab_Matlab_Control')

Note: the above code should be run from the console directly as it currently doesn't work with Live Scripts.

Classes in tops-dots

Almost all objects in tops-dots are classes. A class is a self-contained object which has two types of associated functionalities:

properties
methods

Properties are variables (i.e. data containers) attached to the class instance, whereas methods are functions attached to the class instance.

To illustrate these notions, we will work with an example task class, which we can create (instantiate) in the following way:

my_task = topsTreeNodeTaskSaccade;

To list the class' properties, simply look at the object:

my_task
my_task = 
  topsTreeNodeTaskSaccade with properties:

                  settings: [1x1 struct]
                    timing: [1x1 struct]
      independentVariables: [1x1 struct]
           trialDataFields: {'RT'  'correct'  'fixationOn'  'fixationStart'  'targetOn'  'targetOff'  'fixationOff'  'choiceTime'  'feedbackOn'}
                  drawable: [1x1 struct]
                  readable: [1x1 struct]
                    taskID: -1
                taskTypeID: -1
                 trialData: [1x1 struct]
                trialCount: 0
           trialIterations: 1
      trialIterationMethod: 'random'
    randomizeWhenRepeating: 1
              trialIndices: []
             statusStrings: {}
              stateMachine: []
            completedTrial: 0
                iterations: Inf
            iterationCount: 0
           iterationMethod: 'sequential'
                  nodeData: []
                   helpers: [1x1 struct]
            inheritHelpers: 'all'
               helperTypes: {'drawable'  'playable'  'readable'  'writable'  'general'}
                  children: {}
            startFevalable: {@run  [1x1 topsCallList]}
           finishFevalable: {@run  [1x1 topsCallList]}
                 isRunning: 0
                    caller: []
               startString: 'start'
              finishString: 'finish'
                      name: 'topsTreeNodeTask'
             clockFunction: @mglGetSecs

Classes are close relatives of structs. For instance, it is very easy to create a struct that will contain all the properties of a class:

struct(my_task)
Warning: Calling STRUCT on an object prevents the object from hiding its implementation details and should thus be avoided. Use DISP or DISPLAY to see the visible public details of an object. See 'help struct' for more information.
ans = 
                  settings: [1x1 struct]
                    timing: [1x1 struct]
      independentVariables: [1x1 struct]
           trialDataFields: {'RT'  'correct'  'fixationOn'  'fixationStart'  'targetOn'  'targetOff'  'fixationOff'  'choiceTime'  'feedbackOn'}
                  drawable: [1x1 struct]
                  readable: [1x1 struct]
                    taskID: -1
                taskTypeID: -1
                 trialData: [1x1 struct]
                trialCount: 0
           trialIterations: 1
      trialIterationMethod: 'random'
    randomizeWhenRepeating: 1
              trialIndices: []
             statusStrings: {}
              stateMachine: []
            completedTrial: 0
                iterations: Inf
            iterationCount: 0
           iterationMethod: 'sequential'
                  nodeData: []
                   helpers: [1x1 struct]
            inheritHelpers: 'all'
               helperTypes: {'drawable'  'playable'  'readable'  'writable'  'general'}
                  children: {}
            startFevalable: {@run  [1x1 topsCallList]}
           finishFevalable: {@run  [1x1 topsCallList]}
                 isRunning: 0
                    caller: []
               startString: 'start'
              finishString: 'finish'
                      name: 'topsTreeNodeTask'
             clockFunction: @mglGetSecs

To list the methods of a class instance, you have several options which are slightly different. The clearest one is to open the file where the class is defined:

% uncomment next line to open task file in MATLAB editor
% edit topsTreeNodeTaskSaccade

The above command should open the MATLAB editor. From there, if you click on the "Go To" button in the menu, you will see a list of functions appear, each of these functions is a method!

Another way to get a glance at a task object is to call the help function on it:

help(my_task)
--- help for topsTreeNodeTaskSaccade ---

  @class topsTreeNodeTaskSaccade
 
  Visually and Memory guided saccade tasks
 
  For standard configurations, call:
   topsTreeNodeTaskSaccade.getStandardConfiguration
 
  Otherwise:
   1. Create an instance directly:
         task = topsTreeNodeTaskSaccade();
 
   2. Set properties. These are required:
         task.drawables.screenEnsemble
         task.helpers.readers.theObject
      Others can use defaults
 
   3. Add this as a child to another topsTreeNode
 
  5/28/18 created by jig

    Reference page for topsTreeNodeTaskSaccade

At the bottom of the console output that this command generates, a hyperlink "Reference page for topsTreeNodeTaskSaccade" appears. Clicking on it should make a help window for the object pop up. This help page will contain lists of all the properties and methods available for this object. However, these lists will also include properties and methods from parent classes. For more on this topic, see the next section.

Class inheritance

The top line of the 'topsTreeNodeTaskSaccade.m' file that we opened earlier reads "classdef topsTreeNodeTaskSaccade < topsTreeNodeTask". Because of this, we say that the topsTreeNodeTaskSaccade class inherits from the topsTreeNodeTask class. This entails that all the properties and methods from topsTreeNodeTask (called the superclass) are also properties and methods of any topsTreeNodeTaskSaccade object, unless they are re-defined in the child class. Whenever a method from the superclass is re-defined in a class, we say that it is overloaded. An example of this can be seen with the finishTask() method. As an exercise, try to see the difference between the methods topsTreeNodeTask.finishTask() and topsTreeNodeTaskSaccade.finishTask().

Task classes

In tops-dots, any experimental task should be defined as a class that inherits from 'topsTreeNodeTask'. We have already seen an instance of such task class earlier, this was our 'my_task' object.

General info

Tower of Psych (tops) handles the 'TreeNode' structure on which any of our experimental tasks rely. On the other hand, Snow-Dots (dots) handles the interface to all the graphics, sound and input devices. Currently, whenever snow-dots functionalities are needed in a task (which fundamentally is a tops object), helpers are used.