View source for Plugins:sessionmodel2

== 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, an upgrade from the previous [[Plugins:SessionModel|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.

== The Framework: How sessionmodel2 works ==
[[Image:Sessionflow.gif|frame|right|Logical view of a training stage]]

Let’s work with a simple training example. <br/>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:
#	Count the number of recentmost consecutive “hits”
#	When this number goes above a decided threshold, she moves to the next training step.
#	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:<br/>
#	'''''An algorithm defining the training stage:''''' Count the number of recentmost consecutive “hits”
#	'''''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
#	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 ===
[[Image:Abstract_ts.gif|frame|left|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.
<br style="clear:both;"/>

== Installing the sessionmodel2 plugin ==
'''Step 1:''' Inherit from 'sessionmodel2' in the 'class' statement at the top of your protocol constructor file.
      obj = '''class'''(obj, mfilename, '''sessionmodel2''');


'''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 maximum of 5 input parameters. They are:
* <tt>obj</tt> : Object handle of the protocol making the call
* <tt>action</tt> : A string specifying what function this particular call requests from SessionDefinition
''('<tt>init</tt>' and '<tt>next_trial</tt>' are probably the only calls you will ever make, unless you use EOD logic; all other 'actions' are invoked by SessionDefinition calling itself)''
* <tt>x,y</tt> : x & y coordinates on the parent protocol window where the next GUI element is to be placed
* <tt>f</tt> : Figure handle to the parent protocol figure


... and that should be it! 

Happy automating!

==SESSION AUTOMATOR WINDOW==
[[Image:Session_Automator_Window.jpg]]

==Plugin Files==

<pre>
Plugins/@sessionmodel2/sessionmodel2.m
Plugins/@sessionmodel2/SessionDefinition.m
Plugins/@sessionmodel2/CreateHelperVar.m
Plugins/@sessionmodel2/ClearHelperVarsNotOwned.m
Plugins/@sessionmodel2/sessionmodel2_cdata.mat
Plugins/@sessionmodel2/training_stage_file_template.txt
</pre>

==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.

<pre>
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.
</pre>

===Points to note===
# 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 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.
# 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.

==SessionDefinition==
SessionDefinition.m is the M file that will be called for most purposes. The file contains both mutator and accessor functionality for a wide variety of tasks.

<pre>
SESSIONDEFINITION Function to automate training stages
    Creates the interface that allows an individual protocol to automate
    its progression. Its role is to allow the experimenter to load/save
    training stages in an executable M file and to view or edit these in a
    separate window that shows up as part of the training protocol.
 
    The sessionmodel2 plugin uses the SessionModel class defined in
    ExperPort/HandleParam/@SessionModel. Inspired by the original
    sessionmodel plugin, it has been rewritten to allow training stages to
    be stored in an executable M file, and to have helper vars store a
    trial-by-trial history whose size is equal to n_done_trials.
 
    A more complete documentation will be located at:
    http://brodylab.princeton.edu/bcontrol/index.php/Plugins:sessionmodel2
 
    Syntax: VARARGOUT = SESSIONDEFINITION(OBJ, ACTION, VARARGIN)
 
    OBJ - The protocol object
 
    ACTION - Action string, which can take one of many values, as described
    in the examples section
 
    Common Example calls for end users
 
    SessionDefinition(obj, 'init', x, y, figure_handle): This creates the
    'Session Ctrl' and the 'SAVE DATA AND SETTINGS' buttons on the figure
    specified by figure_handle, at the x and y coordinates passed. It also
    initializes the GUI for the Session Automator Window and loads the most
    recent training stage file available in the Main_Data_Directory (e.g.
    /ratter/SoloData/Settings/<Experimenter>/<ratname>) that is not meant
    for later than the current day, and adds the containing directory to
    the MATLAB path. The entry will be removed from the path when the
    plugin is closed. If no training stage file is available, the plugin
    does not load a training stage file at this stage.
 
    SessionDefinition(obj, 'next_trial'): This call normally goes into the
    prepare_next_trial section of the protocol. Everytime this call is
    executed, a push_history command is executed on all existing helper
    vars, and the HELPER_VARS section and STAGE_ALGORITHM section of the
    active stage in the loaded training stage file are executed, provided
    that training stage has not been marked as deactivated. If it has been
    marked as deactivated, the call will make the next non-deactivated training
    stage active and execute it. After this execution, the COMPLETION_TEST
    section of the active stage in the loaded training stage file is
    evaluated. If the completion test evaluates to true, the next stage
    that is not marked as deactivated in the session automator window is
    activated, and will be called when SessionDefintion(obj, 'next_trial')
    is called again.
 
    SessionDefinition(obj, 'eod_save'): Runs the EOD Logic of the active
    training stage, provided it has not been marked as deactivated. After
    executing the EOD Logic (if available), this section saves the settings
    file and training stage file for the **following day**, and the data for
    the **current day**, and commits these files to the CVS respository.
 
    SessionDefinition(obj, 'run_eod_logic_without_saving'): Runs the EOD
    logic of the active training stage, provided it has not been marked as
    deactivated. Unlike the eod_save action, this action will not save any
    data, settings, or training stage files.
 
    SessionDefinition(obj, 'load_stagefile', absolute_file_path): This call loads
    the training stage file pointed to by absolute_file_path. If the file does not
    exist, the function throws an error. In order to be loaded, the file
    need not have access to the protocol object. This property can be
    utilized if the only reason for calling this function is editing the
    training stage file. However, if the training stage file loaded does
    not have access to the protocol object, a call to
    SessionDefinition(obj,
    ['next_trial'/'eod_save'/'run_eod_logic_without_saving']) will throw an
    error.
 
    SessionDefinition(obj, 'jump_to_stage', <stage_name/stage_number>):
    Activates the stage specified by stage_name/stage_number.
 
    filepath = SessionDefinition(obj, 'save_current_training_stage_file',
    <absolute_file_path>): Saves the current training stage file. If
    absolute_file_path is specified (which has to be an M file), the
    currently loaded training stage file is saved to absolute_file_path. If
    it is not specified, it is saved with today's date to
    <Main_Data_Directory>/Settings/<experimenter>/<ratname>/pipeline_<Proto
    colName>_<experimenter>_<ratname>_<yymmdd>*.m. The function also
    returns a string to the file path to which the file was saved. It
    returns an empty string if the file wasn't saved.
 
    SessionDefinition(obj, 'mark_deactivated', stagelist): In case the user
    would like to skip selected training stages. stagelist can be a cell
    array containing both numbers and strings, or it can be a numeric
    vector containing only numbers. If an element of stagelist is a string,
    it will be interpreted as stage name, otherwise it will be interpreted
    as stage number.
 
    SessionDefinition(obj, 'mark_not_deactivated', stagelist): Works just like
    SessionDefinition(obj, 'mark_deactivated', stagelist), but forces
    execution of the specified stage(s) if they are in the sequence.
 
    helper_vars = SessionDefinition(obj, 'get_helper_var_details'): Returns
    a structure containing the fields 'var_name', 'stage_name',
    'initial_value', 'current_value', and 'history' for every helper var
    available. If no helper vars exist, the function returns an empty structure.
 
    OTHER EXAMPLES
    SessionDefinition(obj, 'reinit_helper_vars'): Reinitializes all helper
    vars, but preserves their histories.
 
    SessionDefinition(obj, 'reinit_helper_vars', helper_var_name_list):
    helper_var_name_list is either a string, or a cell array of strings.
    This call reinitializes all helper vars in helper_var_name_list, but
    preserves their histories.
 
    SessionDefinition(obj, 'caller_instantiate_helper_vars'): Instantiates
    all helper vars as SoloParamHandles in the workspace of the caller of
    SessionDefinition.
 
    SessionDefinition(obj, 'caller_instantiate_helper_vars',
    helper_var_name_list): helper_var_name_list is either a string, or a
    cell array of strings. This call instantiates all helper vars in
    helper_var_name_list in the workspace of the caller of
    SessionDefinition.
 
    SessionDefinition(obj, 'refresh_lbxTrainingStages'): Refreshes the
    listbox displaying training stages in the session automator window.
 
    SessionDefinition(obj, 'refresh_lbxParameters'): Refreshes the
    parameters listbox, using the string in the editParameterSearchString
    field as a regular expression filter.
 
    stagelist = SessionDefinition(obj, 'get_stagelist'): Returns the names
    of all training stages in the currently loaded training stage file as a
    cell array. If no training stage file has been loaded, the call returns
    an empty cell array.
 
    loadtime_datenum = SessionDefinition(obj,
    'get_current_stagefile_load_time'): Returns the date and time of
    loading the currently loaded training stage file in the datenum format.
    If no training stage file is loaded, the function returns NaN.
 
    parameterlist = SessionDefinition(obj, 'get_parameter_list): Returns a
    sorted cell array containing a list of parameter names available to the
    protocol.
 
    active_stage = SessionDefinition(obj, 'get_active_stage_details'):
    Returns the stage name and stage number of the currently active stage
    as structure with fields 'name' and 'number'. If no training stages
    exist, the function call returns the value NaN for stage number and an
    empty string for stage name.
 
    stage_file_path = SessionDefinition(obj, 'get_current_stagefile'):
    Returns the path to the currently loaded training stage file. If no
    file has been loaded, the function returns an empty string.
 
    SessionDefinition(obj, 'save_settings_only', {'commit', false}): Saves
    only the settings file for the **NEXT DAY**.
 
    SessionDefinition(obj, 'save_data_only', {'commit', false}): Saves only
    the data file for the **CURRENT DAY**.
 
    SessionDefinition(obj, 'get_previous_active_stage_details'): Returns a
    structure with fields 'name' and 'number' for the previously active
    stage.
 
    Author: Sundeep Tuteja
            sundeeptuteja [at] gmail [dot] com
</pre>

==Known Bugs==

==Changelog==

==Author==
If you have any questions or suggestions, please contact the author of sessionmodel2: Sundeep Tuteja (sundeeptuteja [at] gmail [dot] com)