SessionModel

Introduction: What SessionModel is and When You Would Use It

SessionModel is, in short, a plugin to coordinate within-session and across-session training automation.

First, a word about where SessionModel fits in the Solo system.The SessionModel module is at uppermost layer - the 'Plugins' layer - of the Solo training software system; you could successfully use the Solo system to write and run protocols without ever using this module.

When, then, would you use this module?

Suppose you have written a behavioural protocol using the Solo system. You have painstakingly determined the training steps required to teach naïve animals the task of interest. This probably involves a sequence of training stages at each level of which, you would monitor the animals’ performance and decide whether to move to the next training step. Individual animals learn at different rates so you would adapt the progression of training steps to each animal’s performance. All of this would be done manually with the trainer observing each animal’s performance and accordingly adjusting the training parameters (SoloParamHandles).

SessionModel formalizes this sequence of training stages into a framework which can be programmed and so allows the progression of training to occur automatically (ie without manual intervention).

It allows the user to:

• Create a sequence of separate training stages
• Define what happens within any given training stage
• Determine performance criteria for changing parameter values (e.g. if animal does “badly”, make task “easier”)
• Determine performance criteria for moving to the next stage (e.g. animal “has learnt” where reward is received; now start pairing CS with reward, or alternating between blocks of trials with different task contingencies)
• Execute special instructions at the end of each session to set up the automation for the next day’s session

Automating a session has practical as well as scientific advantages: many more animals can be simultaneously trained, new protocols could be tested, the trainer is free to do other experiments, and it removes subjective intervention (which could differ between animals) on the part of the trainer.

This section must end with a caveat: Eventually, the trainer is not going to be monitoring an automated session as it happens. Unless the proper analysis tools are in place, she will not know whether the training is progressing as intended or whether a parameter has (unintentionally) been changed to an undesirable value. Such things can go unnoticed for days. See the section “Good Charioteer: Tips for Smoother Daily Automation” for some ideas on how to monitor complex protocols for several animals day after day without risking your sanity.

The Framework: How SessionModel works

Logical view of a training stage

Let’s work with a simple training example.
The goal is to acquaint a rat with a water port. In each trial of the session, we will dispense some water from this port, and we will monitor whether the rat licked (hit) the water port or not (miss). We will say that if a rat has licked for five consecutive trials, he is “acquainted” with the port; we can move on.

A training stage: as seen by trainer

The figure to the right shows what the trainer would be doing when monitoring the rat:

1. Count the number of recentmost consecutive “hits”
2. When this number goes above a decided threshold, she moves to the next training step.
3. If the number has not achieved threshold, she allows the next trial to run.

This would happen after every trial until the rat has become acquainted with the port; thereafter, a fresh set of rules is applied, one applicable to the next training stage.

Formally, this training stage consists of the following steps:

1. An algorithm defining the training stage: Count the number of recentmost consecutive “hits”
2. A test for when the stage has met its goal:When this number goes above a decided threshold, she moves to the next training step
3. If the number has not achieved threshold, she allows the next trial to run.

SessionModel is the framework which does the above automatically. It runs at the end of every trial, executing the algorithm for the current training stage and at the same time, testing to see if criteria for stage completion have been met. If they have, it moves to the next training stage (if any); if not, it stays at the same training stage.

The difference is that instead of describing a training stage in the English language (as in the example above), we describe it in Matlab Solo code, the language in which protocols are written.

A training stage: as seen by SessionModel

An abstract view of a sequence of training stages, as defined using SessionModel. Notice the order and that each stage is composed of, at minimum, a training algorithm and a completion test.

In Matlab terms, each training stage has the following components (there are more pieces than you saw in the previous section but don't worry, the logic is still the same):

• “Training Stage”: Matlab code that evaluates at the end of every trial.
• “Completion Test”: A boolean expression that, when true, will move to the next training stage
• “Vars”: Helper SoloParamHandle variables defined for the training stage (eg the “hit counter” from our example above)
• “End-of-Day Logic”: A piece of code that evaluates only at the end of each session (NOT at the end of each trial). Its purpose is to set up parameter values for the next training session.

The figure on the left shows an abstract view of training stages as defined in Matlab. Notice that the training stages have an order and that each training stage is composed of the pieces listed above.

To add:

• TS eval'ed in stages. Status: (Complete), (Active), ().

Installing the SessionModel plugin

Step 1: Inherit from 'sessionmodel' in the 'class' statement at the top of your protocol constructor file.

     obj = class(obj, mfilename, sessionmodel);

Step 2: Invoke SessionDefinition after defining all your other SoloParamHandles (ie after you have set up all supporting .m files for your protocol).

     SessionDefinition(obj, 'init', x,y,value(myfig));

SessionDefinition takes a max of 5 input parameters. They are:

• obj : Object handle of the protocol making the call
• action : A string specifying what function this particular call requests from SessionDefinition

('init' is probably the only call you will ever make; all other 'actions' are invoked by SessionDefinition calling itself)

• x,y : x & y coordinates on the parent protocol window where the next GUI element is to be placed
• f : Figure handle to the parent protocol figure

... and that should be it!

Happy automating!

The Session Automator window and basic How-To's

Adding SessionDefinition to your protocol will cause an additional window to be added to your view: the SessionDefinition window. This section will familiarize you with the aspects of the Session Automator window.

Load your protocol to which you installed SessionModel. Here is what you should see:

1. In your main protocol window, a dropdown box labelled “Session Control”. Its position will depend on where in your constructor you initialized SessionDefinition; if you did it at the very end, the dropdown box should be in the upper-right corner of your GUI controls.
2. Select the “view” option in the “Session Control” dropdown box. A new window should pop up (see figure below).

It has three sections:

1. “Parameters” (top-left): This textbox displays all the protocol parameters that SessionModel has access to for session automation.
   Parameters are referenced as a combination of the SoloFunction to which they belong and their names. e.g. If you want to reference the variable “tone_length” in the file “ChordSection.m”, you would use the name “ChordSection_tone_length” (note the underscore connecting the function name and parameter name). However, if a variable has been declared global (using DeclareGlobal), it does not need to be prefixed with its variable name (e.g. n_done_trials)
2. “Training Stages” (top-right): This section allows you to manipulate/view training stages as a whole. Using this section, you can:
   • Load/save a set of training stages from/to a file (see “Defining Stages in Files”)
   • View the sequence of training stages (Grey listbox) and select one for manipulation
   • Add (+) or Remove (-) a training stage
   • Update (U) a component of a training stage
     • Note: One component of a training stage may be edited at a time. Use the orange buttons at the bottom to show a specific part of a training stage. Make your changes and then click the U button. The update will only be made to the particular piece of the selected training stage. If you edit using the textbox and don't update using the 'U' button, your changes will not be saved!
   • Delete all training stages (FLUSH)
   • Change which stage is the currently active one (“Change Active Stage”).
3. “Stage-specific components” (bottom-half):
   This section allows you to view/edit different pieces of a training stage (algorithm, completion test, end-of-day logic, etc.,). The big white textbox shows information pertaining to the stage selected in the “Training Stages” listbox. By clicking the respective button below the textbox, you will see corresponding training stage information fill the textbox.

Defining Training Stages: A Demo

This section will show code for how to:

• set values for variables
• use if/else statements to evaluate trial-by-trial performance and change parameters
• write a completion test
• use helper variables
• (Subsection): What the training stages file looks like
• (Subsection): Gradually coalescing training stages into a huge mega-file.
• jump stages

How End-of-Day Logic works

• Flowchart showing evaluation of active eod ts and saving of settings file
• how to jump back stages in eod_logic.

The good charioteer: Tips on running many animals every day and keeping your sanity

• Keeping succinct, informative notes
• Using a 'behaviour dashboard' to make sure that all is well