Difference between revisions of "Plugins:sessionmodel2"

From Bcontrol
m
m
Line 122: Line 122:
  
 
===Points to note===
 
===Points to note===
# Helper vars are local to the training stages they are defined in
+
# Helper vars are local to the training stages they are defined in.
 
# Helper vars are really SoloParamHandles with the following additional properties: save_to_helper_vars_table set to true, stage_name (the training stage that owns the helper var), and initial_value
 
# Helper vars are really SoloParamHandles with the following additional properties: save_to_helper_vars_table set to true, stage_name (the training stage that owns the helper var), and initial_value
 
# Helper vars maintain a complete trial by trial history, that can be accessed using the get_history function
 
# Helper vars maintain a complete trial by trial history, that can be accessed using the get_history function
 
# If a helper var named X exists in training stage A, and the function CreateHelperVar(obj, 'X', 'value', 30) is called in training stage B, the helper var ownership will be changed to training stage B, but it will retain its previous value. However, if the function CreateHelperVar(obj, 'X', 'value', 30, 'force_init', true) is called in training stage B, the helper var X will now have a new value of 30, and its owner will now be stage B.
 
# If a helper var named X exists in training stage A, and the function CreateHelperVar(obj, 'X', 'value', 30) is called in training stage B, the helper var ownership will be changed to training stage B, but it will retain its previous value. However, if the function CreateHelperVar(obj, 'X', 'value', 30, 'force_init', true) is called in training stage B, the helper var X will now have a new value of 30, and its owner will now be stage B.
 
# Deleting a training stage will delete its associated helper vars as well.
 
# Deleting a training stage will delete its associated helper vars as well.
 +
# Helper vars are saved with settings and data, and retain their values across training sessions.

Revision as of 22:13, 23 February 2010

Introduction: What sessionmodel2 is and When You Would Use It

Sessionmodel2 is, in short, a plugin to coordinate within-session and across-session training automation, and upgrade from the previous SessionModel plugin.

First, a word about where sessionmodel2 fits in the Solo system.The sessionmodel2 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 behavioral 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).

Sessionmodel2 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 sessionmodel2 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, he/she allows the next trial to run.


Sessionmodel2 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 sessionmodel2

An abstract view of a sequence of training stages, as defined using sessionmodel2. 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.

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 1b: Make sure the following hack code (which will be unnecessary one day when this gets fixed) is called in your protocol:

   hackvar = 10; SoloFunctionAddVars('SessionModel', 'ro_args', 'hackvar');


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, f);

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' and 'next_trial' are probably the only calls you will ever make, unless you use EOD logic; 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!

SESSION AUTOMATOR WINDOW

Session Automator Window.jpg

Plugin Files

sessionmodel2.m
SessionDefinition.m
CreateHelperVar.m
ClearHelperVarsNotOwned.m
cdata.mat
training_stage_file_template.txt

Training Stage Files

Training stage files get loaded along with the settings file for a particular experimenter and ratname. The training stage file names have the format pipeline_<ProtocolName>_<experimenter>_<ratname>_yymmdd.m, and the directory containing the file gets automatically added to the MATLAB path when the file gets loaded using the Session Automator GUI. The GUI can be used to create as well as edit training stage files.

Helper Vars: What They Are And How They Work

You will often find yourself in a situation where you wish the protocol you're working with had some extra SoloParamHandles, e.g., to keep track of some analysis result as you go, to compare to something that happened the previous day, or some other factor. Helper vars are a way of creating your own variables in the SessionModel. Their values are saved with data and settings, and are loaded when you load data and settings. Thus a value from today, saved with the settings for tomorrow, will be available to you tomorrow.

Creating Helper Vars

Helper vars can be created in the 'Helper Vars' section of your training stage file using the CreateHelperVar function.

CREATEHELPERVAR Function to create helper vars
    This function is used to create helper vars, (normally in the helper
    vars section of the training stage file).
 
    Syntax: CreateHelperVar(obj, varname, varargin)
 
    'value', varval: Sets the helper var to varval if the helper var does
    not already exist. If this option is not specified, varval defaults to
    the empty matrix.
 
    'force_init', true: Forces the helper var to be set to the specified
    value. If this option is not specified, 'force_init' is assumed to be
    false.

Points to note

  1. Helper vars are local to the training stages they are defined in.
  2. Helper vars are really SoloParamHandles with the following additional properties: save_to_helper_vars_table set to true, stage_name (the training stage that owns the helper var), and initial_value
  3. Helper vars maintain a complete trial by trial history, that can be accessed using the get_history function
  4. If a helper var named X exists in training stage A, and the function CreateHelperVar(obj, 'X', 'value', 30) is called in training stage B, the helper var ownership will be changed to training stage B, but it will retain its previous value. However, if the function CreateHelperVar(obj, 'X', 'value', 30, 'force_init', true) is called in training stage B, the helper var X will now have a new value of 30, and its owner will now be stage B.
  5. Deleting a training stage will delete its associated helper vars as well.
  6. Helper vars are saved with settings and data, and retain their values across training sessions.