Plugins-antibias

From Bcontrol

From the help file (i.e., in Matlab, type "help @antibias/AntibiasSection"):

% [x, y] = AntibiasSection(obj, action, [arg1], [arg2], [arg3])    
%
% Section that calculates biases and calculates probability of choosing a stimulus
% given the previous history. 
%
%    Antibias assumes that trials are of two classes, Left desired answer
% and Right desired answer, and that their outcome is either Correct or
% Incorrect. Given the history of previous trial classes, and the history
% of previous corrects/incorrects, Antibias makes a local estimate of
% fraction correct for each class, combines that with a prior probability
% of making the next trial Left, and produces a recommended probability
% for choosing the next trial as Left. Antibias will tend to make the
% class with the smaller frac correct the one with the higher probability.
% The strength of that tendency is quantified by a parameter, beta. 
%   (See probabilistic_trial_selector.m for details on the math of how the
% tendency is generated.)
%
% Local estimates of fraction correct are computed using an exponential
% kernel, most recent trial the most strongly weighted. The tau of this
% kernel is a GUI parameter. Two different estimates are computed: one for
% use in computing Left probability and Right probability; and a second
% simply for GUI display purposes. The two estimates can have different
% taus for their kernels.
%
% GUI DISPLAY: When initialized, this plugin will put up two panels and a
% title. In each panel, there is a slider that controls the tau of the
% recent-trials exponential kernel. One panel will display the percent
% corrects for Right and Left, as computed with its kernel. The second panel
% will display the a posteriori probabilities of making the next trial a
% "Left" trial or making the next trial a "Right" trial. This second panel
% has its own tau slider, and it also has a GUI parameter, beta, that
% controls how strongly the history matters. If beta=0, history doesn't
% matter, and the a priori LeftProbability dominates. If beta=Inf, then
% history matters above all: the next trial will be of the type with lowest
% fraction correct, for sure.
%
% See the bottom of this help file for examples of usage.
%
% arg1, arg2, arg3 are optional and their meaning depends on action (see
% below).
%
% PARAMETERS:
% -----------
%
% obj      Default object argument.
%
% action   One of:
%
%     'init'        To initialise the plugin and set up the GUI for it. This
%                   action requires two more arguments: The bottom left
%        x y        position (in units of pixels) of where to start placing
%                   the GUI elements of this plugin. 
%
%     'update'      This call will recompute both local estimates of
%                   fraction correct, and will recompute the recommended 
%        LeftProb,  p(Left). This action requires three more arguments:
%        HitHist,   LProb, a scalar b/w 0 and 1; HitHist, a vector of 1s
%        SidesHist  and 0s and of length n_done_trials where 1 represents
%                   correct and 0 represents incorrect, first element
%                   corresponds to first trial; and SidesHist, a vector of
%                   'l's and 'r's and of length n_done_trials where 'l'
%                   represents 'left', 'r' represents 'right' first element
%                   corresponds to first trial.
%
%     'get_posterior_probs'  Returns a vector with two components, 
%                   [p(Left) p(Right)].
% 
% 
%     'update_biashitfrac'   This call will recompute the local estimate of fraction
%                   Left correct and fraction Right correct used for
%        LeftProb,  antibiasing, and will also recompute the recommended
%        HitHist,   Left probability. This action    
%        SidesHist, requires three more arguments: LProb, a scalar b/w 0
%                   and 1; HitHist, a vector of 1s and 0s and of length
%                   n_done_trials where 1 represents correct and 0
%                   represents incorrect, first element corresponds to
%                   first trial; and SidesHist, a vector of 'l's and 'r's
%                   and of length n_done_trials where 'l' represents
%                   'left', 'r' represents 'right' first element
%                   corresponds to first trial.
% 
%     'update_hitfrac'  This call is not related to computing the posterior
%                   Left probability, but will recompute only the local estimate
%        HitHist,   of fraction correct that is not used for antibiasing.
%        SidesHist  This action requires two more arguments: HitHist, a
%                   vector of 1s and 0s and of length n_done_trials where 1
%                   represents correct and 0 represents incorrect, first
%                   element corresponds to first trial; and SidesHist, a vector of
%                   'l's and 'r's and of length n_done_trials where 'l'
%                   represents 'left', 'r' represents 'right' first element
%                   corresponds to first trial.
%
%     'reinit'      Delete all of this section's GUIs and data,
%                   and reinit, at the same position on the same
%                   figure as the original section GUI was placed.
%
%
% x, y     Relevant to action = 'init'; they indicate the initial
%          position to place the GUI at, in the current figure window
%
% RETURNS:
% --------
%
% if action == 'init' :
%
% [x1, y1, w, h]   When action == 'init', Antibias will put up GUIs and take
%          up a certain amount of space of the figure that was current when
%          AntiBiasSection(obj, 'init', x, y) was called. On return, [x1 y1]
%          will be the top left corner of the space used; [x y] (as passed
%          to Antibias in the init call) will be the bottom left corner;
%          [x+w y1] will be the top right; and [x+w y] will be the bottom
%          right. h = y1-y. All these are in units of pixels.
%
%
% if action == 'get_posterior_probs' :
%
% [L R]     When action == 'get_posterior_probs', a two-component vector is
%           returned, with p(Left) and p(Right).  If beta=0, then p(Left)
%           will be the same as the last LeftProb that was passed in.
%
%
% USAGE:
% ------
%
% To use this plugin, the typical calls would be:
%
% 'init' : On initializing your protocol, call 
%    AntibiasSection(obj, 'init', x, y);
%
% 'update' : After a trial is completed, call
%    AntibiasSection(obj, 'update', LeftProb, HitHist, SidesHist)
%
% 'get_posterior_probs' : After a trial is completed, and when you are
%       deciding what kind of trial to make the next trial, get the plugins
%       opinion on whether the next trial should be Left or Right by calling
%    AntibiasSection(obj, 'get_posterior_probs')
%
% See PARAMETERS section above for the documentation of each of these calls.
%