Plugins-softpokestay

From the help file (In Matlab, >> help Plugins/@softpokestay/SoftPokeStayInterface )

% [x, y] = SoftPokeStayInterface(obj, action, softpokestay_name, x, y)
%
% Puts up a GUI for making a set of states for detecting when an animal 
% stays in a poke, while allowing brief excursions from the poke. You can
% define the maximum time the animal is outside the poke before the "in
% poke" state is considered terminated. This plugin also provides a simple
% call to add the necessary states to a @StateMachineAssembler you are
% constructing.
%
% QUICKSTART USAGE:
% -----------------
%
% To create a soft poke stay GUI, call
%
%   [x, y] = SoftPokeStayInterface(obj, 'add', sps_name, x, y)
%
% where sps_name is a string that will identify this soft poke stay
% section, and x and y are the pixel position in the current figure on
% which a the GUI for this soft poke stay section appears. By using
% different sps_name strings, you can have separate, different soft poke
% stay sections. The GUI will have NumeditParams for 'Duration' (how long
% the animal must keep its nose in the poke to exit successfully) and
% 'Grace' (how long the animal is allowed to hop out of the poke before a
% full exit is flagged).
%
% There are two ways to exit from SoftPokeStays: (a) "success", meaning
% that the animal kept its nose in the poke for Duration seconds (ignoring
% any exits from the poke less that Grace seconds long). (b) "abort",
% meaning that the animal left the poke for more than Grace seconds before
% Duration was up. (Of course, whether you interpret these two exits as
% "good" or "bad" or viceversa is up to you.)
%
% Then, to use the soft poke stay section, when constructing your
% StateMachine Assembler, call
%
%   sma = SoftPokeStayInterface(obj, 'add_sma_states', sps_name, sma, ... 
%        'success_exitstate', success_exitstate_name, ...
%        'abort_exitstate',   abort_exitstate_name,  'pokeid', pokeid);
%
% where sma is a @StateMachineAssembler object, sps_name is the string
% identifying this soft poke stay section, success_exitstate_name is a string
% identifying the state to jump to after the soft poke stay ended with a
% "success", abort_exitstate_name is a string identifying the state to jump
% to if the soft poke state ended with an "abort" (i.e. the animal was
% outside the poke for more than Grace seconds), and pokeid is one of 'C',
% 'R', or 'L'. 
%
% In the State Machine, to start the SoftPokeStay section, jump to the
% state named sps_name, where sps_name is any of the soft poke stays you
% created. All of the states in the soft poke stay section will be named
% sps_name; you will be jumping to the first of those states.
%
% *** NOTE THAT SOFT POKE STAY ASSUMES THAT THE ANIMAL'S NOSE IS **IN** THE
% POKE GIVEN BY POKEID WHEN THE SOFT POKE STAY SECTION STARTS.
%
%
% In addition to its basic functionality of timing when an animal leaves a
% poke while allowing for Grace periods, SoftPokeStayInterface can
% concurrently detect some events and produce some outputs. It can do three
% things:
%   1) You can ask it to pull a digital line high X seconds after starting
%      SoftPokeStay and keeep it high for Y seconds thereafter.
%   2) You can ask it to send a trigger signal to the Sound Machine X
%      seconds after starting SoftPokeStay. This trigger signal can be
%      either "start a sound" or "stop a sound."
%   3) You can ask it to send a trigger signal to the Sound Machine if and 
%      when an event that you choose occurs. E.g., "start sound 3 if a
%      mywave_In event occurs."
%
% Each of these three are independent of each other, and are independent of
% Grace period accounting and so on. The first two are different from the
% third: when the SoftPokeStay ends, it always pulls the digital line
% back down and stops the sound in (1) and (2) above. The outputs in (1)
% and (2) are therefore guaranteed to be stopped at the end of SoftPokeStay
% states. In contrast, The sound referred to in (3) above is affected only
% once, if and when its triggering event occurs within the SoftPokeStay
% states. It is therefore not guaranteed to be neither started nor stopped
% at the end of SoftPokeStay states. To use 1, 2, and 3, see parameters for
% 'add_sma_states' below.
%
%
% RESOURCE USAGE:
% ---------------
%
% Each soft poke stay section uses 4 scheduled waves.
%
%
% PARAMETERS:
% -----------
%
% The first parameter, action, should be one of:
%
%  'add'     Make a GUI for a new sps section. This action requires three
%            more PARAMETERS:
%
%              sps_name    A string defining the name of the soft poke stay
%            
%              x, y            x and y position, in pixels from bottom
%                              left of current figure, at which to start
%                              putting in the GUI elements.
%         
%            This action, 'add', also takes a number of OPTIONAL PARAMETERS:
%
%              'TooltipString'   Default is ''; Tooltip string for title of
%                         GUI.
%
%            This action, 'add', RETURNS:  x, y  next open position on
%                         current figure.
%
% 'set' sps_name 'Duration'|'Grace' value
%        
%               The 'set' action allows setting the parameters for any of
%               the soft poke stays that have been created. The next argument
%               after 'set' must be a string, the name of the soft poke stay
%               that was created with 'add'; the next argument must also be
%               a string, as listed above; and the last argument should be
%               the value the corresponding setting will be changed to.
%               Example calls:
%                     SoftPokeStayInterface(obj, 'set', 'mysps', 'Duration', 2);
%                 or
%                     SoftPokeStayInterface(obj, 'set', 'mysps', 'Grace',   0.025);
%
%
% 'get' sps_name 'Duration'|'Grace'  
%
%               The 'get' action returns the setting of the parameters for any of
%               the soft poke stays that have been created. The next argument
%               after 'get' must be a string, the name of the soft poke stay
%               that was created with 'add'; the next argument must also be
%               a string, as listed above.
%               Example call:
%                     myvarstyle = SoftPokeStayInterface(obj, 'get', 'mysps', 'Duration')
%
%
% 'close_all'   Deletes all SoloParamHandles that were created with
%               SoftPokeStayInterface.
%
%
% 'add_sma_states'  sps_name,  sma, {'success_exitstate_name', 'current_state+4'}, ...
%                  {'abort_exitstate_name', 'current_state+3'}, ...
%                  {'DOut' -1}, {'DOutStartTime', 1e6}, {'DOutOnTime', 1e6}, ...
%                  {'SoundOut', 0}, {'SoundStartTime', 1e6}, ...
%                  {'SoundTriggeringEvent', 'null'}, {'EventTriggeredSoundId' 0}, ...
%                  {'InitialSchedWaveTrig', 'null'}
%
%               The first argument after 'add_sma_states' must be a
%               string, sps_name, identifying the softpokestay section that
%               we are talking about; and the next must be a
%               @StateMachineAssembler object to which we are adding the
%               states. This call will return an updated sma. The defaults
%               for the name-value pairs 'success_exitstate_name' and
%               'abort_exitstate_name' are set to be the next state
%               immediately after the softpokestay states. You can specify
%               a different string for either or both.
%               'success_exitstate_name' will be jumped to if the animal
%               stays in the poke for at least Duration seconds, not
%               exiting for more than Grace seconds. 'abort_exitstate_name'
%               will be jumped to if the animal exited for more than Grace
%               seconds before Duration had elapsed. (Duration and Grace
%               are determined by the GUI, see above.)
%
%               The optional name-value pairs 'DOut', 'DOutStartTime', and
%               'DoutOnTime', identify a digital output signal that you
%               would like turned on DoutStartTime after entering the sps
%               states, and that should last a maximum of DoutOnTime (but
%               will be pulled low if the sps states end). (This is
%               typically used to deliver a certain amount of water.)
%                  Similarly, the optional name-value pairs 'SoundOut' and
%               'SoundOutStartTime' identify a sound you want turned on or
%               off SoundOutStartTime secs after the beginning of the sps
%               section. (SoundOut = +k means turn sound k on; SoundOut=-k
%               means turns sound k off.) At the end of the SoftPokeStay,
%               whether it ends in success or abort, the sound is turned
%               off (a -abs(k) signal is sent) before jumping to
%               success_exitstate_name or abort_exitstate_name. 
%                  Finally, you can have yet another sound turn on or off,
%               this one not based on time since the soft poke stay start,
%               but based on some event (e.g., 'mysched_wave_In'). The
%               optional parameter 'SoundTriggeringEvent' is used to
%               indicate what that event is; and  'EventTriggeredSoundId'
%               indicates the id of the sound. (Once again, +k means turn
%               sound k on, -k means turn it off.) This sound is NOT
%               guaranteed to be neither off nor on when the softpokestay
%               states end. 
%                  The optional name-value pair 'InitialSchedWaveTrig'
%               indicates a scheduled wave that you might like to trigger
%               simultaneously with starting the SoftPokeStay states.
%
% 
% EXAMPLES
% --------
%
% To give a rat water for 0.2 secs as soon as he poked into the Left poke,
% and to not have the state machine progress to another state until he's
% been out of the port for at least 2.5 secs, or 40 secs have elapsed,
% whichever comes first: 
%
% >> SoftPokeStayInterface(obj, 'add', 'soft_drinktime', x, y);
% >> SoftPokeStayInterface(obj, 'set', 'soft_drinktime', 'Duration', 40); 
% >> SoftPokeStayInterface(obj, 'set', 'soft_drinktime', 'Grace', 2.5);
%
% sma = SoftPokeStayInterface(obj, 'add_sma_states', 'soft_drinktime', ...
%   'pokeid', 'L', 'DOut', left1water, 'DOutStartTime', 0, 'DOutOnTime', 0.2);
%
%
%
% To give a rat water for 0.2 secs immediately after he pokes into the Left
% poke; and turn both sound A and sound B off 2 seconds afterwards; and not
% progress to the next state until he's been out of the port for at least
% 2.5 secs, or 40 secs have elapsed, whichever comes first: 
%
% >> SoftPokeStayInterface(obj, 'add', 'soft_drinktime', x, y);
% >> SoftPokeStayInterface(obj, 'set', 'soft_drinktime', 'Duration', 40); 
% >> SoftPokeStayInterface(obj, 'set', 'soft_drinktime', 'Grace', 2.5);
% 
% sma = add_scheduled_wave(sma, 'name', 'soundAoff', 'preamble', 2);
%
% sma = SoftPokeStayInterface(obj, 'add_sma_states', 'soft_drinktime', ...
%   'pokeid', 'L', ...
%   'DOut', left1water, 'DOutStartTime', 0, 'DOutOnTime', 0.2, ...
%   'SoundStartTime', 2, 'SoundOut', -B, ...
%   'InitialSchedWaveTrig', 'soundAoff', ...
%   'SoundTriggeringEvent', 'soundAoff_In', 'EventTriggeredSoundId', -A);
%
% sma = add_state(sma, 'self_timer', 0.0001, 'input_to_statechange',
%    {'Tup', 'current_state+1'}, 'output_actions', {'SoundOut', -A}); 
%      % this last is to guarantee that sound A gets turned off, in case the
%      % SoftPokeStay section ends before the 2 secs of the soundAoff
%      % scheduled wave have elapsed.