Plugins-distribui

From Bcontrol

From the help comments for Plugins/@distribui/DistributionInterface.m

% [x, y] = DistribInterface(obj, action, randvar_name, x, y)
%
% Puts up a GUI for getting a random number from some simple distributions.
% Can sample from the specified distribution by either calling a command or
% clicking a button.  The main actions are 'add' (create a new random var,
% and instantiate the SoloParamHandle that holds its value in the caller's
% workspace); 'get_new_sample' (sample from it) and 'get_soloparamhandles'
% (get all the SoloParamHandles that are part of the GUI for this var).
%
% EXAMPLE CALLS:
% --------------
%
%  To initialise a distribution, put up the GUI, and make a
%  SoloParamHandle, you would do:
%
%  [x, y] = DistribInterface(obj, 'add', 'myrandom', 10, 10, 'Style', ...
%                    'gaussian', 'Mu', 10, 'Sd', 3, 'Min', 0, 'Max', 20);
%
%       The above call will instantiate a SoloParamHandle named 'myrandom'
%       in your workspace; you will, by default, have read-write access to
%       it.
%
%
%  randvalue = DistribInterface(obj, 'get_new_sample', 'myrandom');
%
%
% PARAMETERS:
% -----------
%
% The first parameter, action, should be one of:
%
%  'add'     Make a GUI for a new random var. This action requires three
%            more PARAMETERS:
%
%              randvar_name    A string defining the name of the new var
%            
%              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:
%
%              'Style'    One of the three strings 'exponential',
%                        'gaussian', or 'uniform'. Default is 'exponential'
%              'Min'      By default 0; all samples are guaranteed >= Min
%              'Max'      By default 1; all samples are guaranteed <= Max
%              'Tau'      Scale of exponential shape; only relevant if
%                         Style=='exponential'. Default value is 1. Small
%                         positive values weight the distrib towards 'Min';
%                         large values make the distrib close to uniform;
%                         small negative values weight the distrib towards
%                         'Max'.
%              'Mu'       Mean of gaussian. Only relevant if Style=='gaussian' 
%              'Sd'       St. Dev. of gaussian. Only relevant if Style=='gaussian' 
%              'TooltipString'   Default is ''; Tooltip string for title of
%                         GUI.
%
%            This action, 'add', RETURNS:  x, y  next open position on
%                         current figure.
%
% 'set' randvar_name 'Style'|'Min'|'Max'|'Tau'|'Mu'|'Sd'   value
%        
%               The 'set' action allows setting the parameters for any of
%               the distributions that have been created. The next argument
%               after 'set' must be a string, the name of the distribution
%               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:
%                     DistribInterface(obj, 'set', 'myvar', 'Style', 'exponential');
%                 or
%                     DistribInterface(obj, 'set', 'myvar', 'Min',   0);
%               For comments on what the different settings are, see action='add'
%               above.
%
% 'get' randvar_name 'Style'|'Min'|'Max'|'Tau'|'Mu'|'Sd'  
%
%               The 'get' action returns the setting of the parameters for any of
%               the distributions that have been created. The next argument
%               after 'get' must be a string, the name of the distribution
%               that was created with 'add'; the next argument must also be
%               a string, as listed above.
%               Example call:
%                     myvarstyle = DistribInterface(obj, 'get', 'myvar', 'Style')
%
%
% 'get_new_sample'   Return a new sample from the distribution. This action requires one
%                more PARAMETER:
%
%              randvar_name    The name of the distrib to sample fromm, as
%                         passed when 'add' was called. 
%
%                and RETURNS a scalar, the sample. The GUI will be changed
%                to reflect the new sample value.
%
%
% 'get_current_sample'   Return the current sample, without changing it. This action requires one
%                more PARAMETER:
%
%              randvar_name    The name of the distrib to sample fromm, as
%                         passed when 'add' was called. 
%
%                and RETURNS a scalar, the sample. The GUI is not changed
%                as the value of the sample hasn't changed.
%
%
% 'get_soloparamhandles'   Return all SoloParamHandles associated with a
%                distribution. This action requires one more PARAMETER:
%
%              randvar_name    The name of the distrib to sample fromm, as
%                         passed when 'add' was called. 
%
%                and RETURNS a cell vector of SoloParamHandles.
%


% Written by Carlos Brody Aug 2007