DistributionFunctions¶
Overview¶
Functions that return one or more samples from a distribution.
- class psyneulink.core.components.functions.distributionfunctions.DistributionFunction(default_variable, params, owner=None, name=None, prefs=None, context=None, **kwargs)¶
- class psyneulink.core.components.functions.distributionfunctions.DriftDiffusionAnalytical(default_variable=None, drift_rate=None, starting_value=None, threshold=None, noise=None, non_decision_time=None, params=None, owner=None, prefs=None, shenhav_et_al_compat_mode=False)¶
Return terminal value of decision variable, mean accuracy, and mean response time computed analytically for the drift diffusion process as described in Bogacz et al (2006).
Modulatory Parameters:
- Parameters
default_variable (number, list or array : default class_defaults.variable) – specifies a template for decision variable(s); if it is list or array, a separate solution is computed independently for each element.
drift_rate (float, list or 1d array : default 1.0) – specifies the drift_rate of the drift diffusion process. If it is a list or array, it must be the same length as default_variable.
threshold (float, list or 1d array : default 1.0) – specifies the threshold (boundary) of the drift diffusion process. If it is a list or array, it must be the same length as default_variable.
starting_value (float, list or 1d array : default 1.0) – specifies the initial value of the decision variable for the drift diffusion process. If it is a list or array, it must be the same length as default_variable.
noise (float, list or 1d array : default 0.0) – specifies the noise term (corresponding to the diffusion component) of the drift diffusion process. If it is a float, it must be a number from 0 to 1. If it is a list or array, it must be the same length as default_variable and all elements must be floats from 0 to 1.
non_decision_time (float, list or 1d array : default 0.2) – specifies the non-decision time for solution. If it is a float, it must be a number from 0 to 1. If it is a list or array, it must be the same length as default_variable and all elements must be floats from 0 to 1.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).shenhav_et_al_compat_mode (bool : default False) – whether Shenhav et al. compatibility mode is set. See shenhav_et_al_compat_mode property.
- variable¶
holds initial value assigned to
default_variableargument; ignored byfunction.- Type
number or 1d array
- drift_rate¶
determines the drift component of the drift diffusion process.
- Type
float or 1d array
- threshold¶
determines the threshold (boundary) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).
- Type
float or 1d array
- starting_value¶
determines the initial value of the decision variable for the drift diffusion process.
- Type
float or 1d array
- noise¶
determines the diffusion component of the drift diffusion process (used to specify the variance of a Gaussian random process).
- Type
float or 1d array
- non_decision_time¶
determines the assumed non-decision time to determine the response time returned by the solution.
- Type
float or 1d array
- bias¶
normalized starting point: (
starting_value+threshold) / (2 *threshold)- Type
float or 1d array
- name¶
the name of the Function; if it is not specified in the name argument of the constructor, a default is assigned by FunctionRegistry (see Naming for conventions used for default and duplicate names).
- Type
str
- prefs¶
the
PreferenceSetfor function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned usingclassPreferencesdefined in __init__.py (see Preferences for details).- Type
PreferenceSet or specification dict : Function.classPreferences
- property shenhav_et_al_compat_mode¶
Get whether the function is set to Shenhav et al. compatibility mode. This mode allows the analytic computations of mean error rate and reaction time to match exactly the computations made in the MATLAB DDM code (Matlab/ddmSimFRG.m). These compatibility changes should only effect edges cases that involve the following cases:
Floating point overflows and underflows are ignored when computing mean RT and mean ER
Exponential expressions used in cacluating mean RT and mean ER are bounded by 1e-12 to 1e12.
Decision time is not permitted to be negative and will be set to 0 in these cases. Thus RT will be RT = non-decision-time in these cases.
- Returns
Shenhav et al. compatible mode setting
- Return type
(bool)
- _function(variable=None, context=None, params=None)¶
Return: terminal value of decision variable (equal to threshold), mean accuracy (error rate; ER) and mean response time (RT)
- Parameters
variable (2d array) – ignored.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Returns
Decision variable, mean ER, mean RT
- Return type
(float, float, float)
- static _compute_conditional_rt_moments(drift_rate, noise, threshold, starting_value, non_decision_time)¶
This is a helper function for computing the conditional decison time moments for the DDM. It is based completely off of MatlabDDMFunctionsddm_metrics_cond_Mat.m.
- Parameters
drift_rate – The drift rate of the DDM
noise – The diffusion rate.
threshold – The symmetric threshold of the DDM
starting_value – The initial condition.
non_decision_time – The non decision time.
- Returns
A dictionary containing the following key value pairs: mean_rt_plus: The mean RT of positive responses. mean_rt_minus: The mean RT of negative responses. var_rt_plus: The variance of RT of positive responses. var_rt_minus: The variance of RT of negative responses. skew_rt_plus: The skew of RT of positive responses. skew_rt_minus: The skew of RT of negative responses.
- derivative(output, input)¶
Calculate the derivative of \(\frac{1}{reward rate}\) with respect to the threshold (output arg) and drift_rate (input arg). Reward rate (\(RR\)) is assumed to be:
\(RR = delay_{ITI} + \frac{Z}{A} + ED\);
the derivative of \(\frac{1}{RR}\) with respect to the
thresholdis:\(\frac{1}{A} - \frac{E}{A} - 2\frac{A}{c^2}ED\);
and the derivative of 1/RR with respect to the
drift_rateis:\(-\frac{Z}{A^2} + \frac{Z}{A^2}E - \frac{2Z}{c^2}ED\)
where:
A =
drift_rate,Z =
threshold,c =
noise,E = \(e^{-2\frac{ZA}{c^2}}\),
D = \(delay_{ITI} + delay_{penalty} - \frac{Z}{A}\),
\(delay_{ITI}\) is the intertrial interval and \(delay_{penalty}\) is a penalty delay.
- Returns
derivatives – of \(\frac{1}{RR}\) with respect to
thresholdanddrift_rate.- Return type
List[float, float)
- class psyneulink.core.components.functions.distributionfunctions.ExponentialDist(default_variable=None, beta=None, seed=None, params=None, owner=None, prefs=None)¶
Return a random sample from a exponential distribution using numpy.random.exponential
Modulatory Parameters:
MULTIPLICATIVE_PARAM:beta- Parameters
beta (float : default 1.0) – The scale parameter of the exponential distribution
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).
- beta¶
The scale parameter of the exponential distribution
- Type
float : default 1.0
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- params¶
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Type
Dict[param keyword: param value] : default None
- name¶
specifies the name of the Function.
- Type
str : default see
name
- class psyneulink.core.components.functions.distributionfunctions.GammaDist(default_variable=None, scale=None, dist_shape=None, seed=None, params=None, owner=None, prefs=None)¶
Return a random sample from a gamma distribution using numpy.random.gamma
Modulatory Parameters:
- Parameters
scale (float : default 1.0) – The scale of the gamma distribution. Should be greater than zero.
dist_shape (float : default 1.0) – The shape of the gamma distribution. Should be greater than zero.
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).
- scale¶
The scale of the gamma distribution. Should be greater than zero.
- Type
float : default 1.0
- dist_shape¶
The shape of the gamma distribution. Should be greater than zero.
- Type
float : default 1.0
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- params¶
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Type
Dict[param keyword: param value] : default None
- name¶
specifies the name of the Function.
- Type
str : default see
name
- class psyneulink.core.components.functions.distributionfunctions.NormalDist(default_variable=None, mean=None, standard_deviation=None, params=None, owner=None, seed=None, prefs=None)¶
Return a random sample from a normal distribution using numpy.random.normal;
Modulatory Parameters:
- Parameters
mean (float : default 0.0) – The mean or center of the normal distribution
standard_deviation (float : default 1.0) – Standard deviation of the normal distribution. Must be > 0.0
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).
- mean¶
The mean or center of the normal distribution.
- Type
float : default 0.0
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- standard_deviation¶
Standard deviation of the normal distribution; if it is 0.0, returns
mean.- Type
float : default 1.0
- params¶
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Type
Dict[param keyword: param value] : default None
- name¶
specifies the name of the Function.
- Type
str : default see
name
- prefs¶
specifies the
PreferenceSetfor the Function (seeprefsfor details).- Type
PreferenceSet or specification dict : default Function.classPreferences
- _validate_params(request_set, target_set=None, context=None)¶
Validate params and assign validated values to targets,
This performs top-level type validation of params
This can be overridden by a subclass to perform more detailed checking (e.g., range, recursive, etc.) It is called only if the parameter_validation attribute is
True(which it is by default)- IMPLEMENTATION NOTES:
future versions should add recursive and content (e.g., range) checking
should method return validated param set?
- Parameters
validated (dict (target_set) - repository of params that have been) –
validated –
- Return none
- class psyneulink.core.components.functions.distributionfunctions.UniformDist(default_variable=None, low=None, high=None, seed=None, params=None, owner=None, prefs=None)¶
Return a random sample from a uniform distribution using numpy.random.uniform
- Parameters
low (float : default 0.0) – Lower bound of the uniform distribution
high (float : default 1.0) – Upper bound of the uniform distribution
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).
- low¶
Lower bound of the uniform distribution
- Type
float : default 0.0
- high¶
Upper bound of the uniform distribution
- Type
float : default 1.0
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- params¶
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Type
Dict[param keyword: param value] : default None
- name¶
specifies the name of the Function.
- Type
str : default see
name
- class psyneulink.core.components.functions.distributionfunctions.UniformToNormalDist(default_variable=None, mean=None, standard_deviation=None, params=None, owner=None, seed=None, prefs=None)¶
Return a random sample from a normal distribution using first np.random.rand(1) to generate a sample from a uniform distribution, and then converting that sample to a sample from a normal distribution with the following equation:
\[normal\_sample = \sqrt{2} \cdot standard\_dev \cdot scipy.special.erfinv(2 \cdot uniform\_sample - 1) + mean\]The uniform –> normal conversion allows for a more direct comparison with MATLAB scripts.
Note
This function requires SciPy.
(https://github.com/jonasrauber/randn-matlab-python)
Modulatory Parameters:
- Parameters
mean (float : default 0.0) – The mean or center of the normal distribution
standard_deviation (float : default 1.0) – Standard deviation of the normal distribution
params (Dict[param keyword: param value] : default None) – a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
owner (Component) – component to which to assign the Function.
name (str : default see
name) – specifies the name of the Function.prefs (PreferenceSet or specification dict : default Function.classPreferences) – specifies the
PreferenceSetfor the Function (seeprefsfor details).
- mean¶
The mean or center of the normal distribution
- Type
float : default 0.0
- standard_deviation¶
Standard deviation of the normal distribution
- Type
float : default 1.0
- params¶
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- Type
Dict[param keyword: param value] : default None
- random_state¶
private pseudorandom number generator
- Type
numpy.RandomState
- name¶
specifies the name of the Function.
- Type
str : default see
name
- class psyneulink.core.components.functions.distributionfunctions.WaldDist(default_variable=None, scale=None, mean=None, seed=None, params=None, owner=None, prefs=None)¶
WaldDist( scale=1.0, mean=1.0, params=None, owner=None, prefs=None )
Return a random sample from a Wald distribution using numpy.random.wald
Modulatory Parameters:
MULTIPLICATIVE_PARAM:scaleADDITIVE_PARAM:mean- scalefloatdefault 1.0
Scale parameter of the Wald distribution. Should be greater than zero.
- meanfloatdefault 1.0
Mean of the Wald distribution. Should be greater than or equal to zero.
- paramsDict[param keyword: param value]default None
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- ownerComponent
component to which to assign the Function.
- prefsPreferenceSet or specification dictdefault Function.classPreferences
the
PreferenceSetfor the Function. If it is not specified, a default is assigned usingclassPreferencesdefined in __init__.py (see Preferences for details).
- random_statenumpy.RandomState
private pseudorandom number generator
- scalefloatdefault 1.0
Scale parameter of the Wald distribution. Should be greater than zero.
- meanfloatdefault 1.0
Mean of the Wald distribution. Should be greater than or equal to zero.
- paramsDict[param keyword: param value]default None
a parameter dictionary that specifies the parameters for the function. Values specified for parameters in the dictionary override any assigned to those parameters in arguments of the constructor.
- ownerComponent
component to which to assign the Function.
- prefsPreferenceSet or specification dictdefault Function.classPreferences
the
PreferenceSetfor the Function. If it is not specified, a default is assigned usingclassPreferencesdefined in __init__.py (see Preferences for details).