DistributionFunctions

Overview

Functions that return one or more samples from a distribution.

class psyneulink.core.components.functions.distributionfunctions.NormalDist(mean=0.0, standard_deviation=1.0, params=None, owner=None, prefs=None)

Return a random sample from a normal distribution using numpy.random.normal;

Modulatory Parameters:

MULTIPLICATIVE_PARAM: standard_deviation
ADDITIVE_PARAM: mean

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 PreferenceSet for the Function (see prefs for details).
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; if it is 0.0, returns mean.

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

Componentcomponent 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 PreferenceSet for the Function (see prefs for details).

class psyneulink.core.components.functions.distributionfunctions.UniformToNormalDist(mean=0.0, standard_deviation=1.0, params=None, owner=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:

MULTIPLICATIVE_PARAM: standard_deviation
ADDITIVE_PARAM: mean

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 PreferenceSet for the Function (see prefs for details).
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

Componentcomponent 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 PreferenceSet for the Function (see prefs for details).

class psyneulink.core.components.functions.distributionfunctions.ExponentialDist(beta=1.0, 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 PreferenceSet for the Function (see prefs for details).
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

Componentcomponent 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 PreferenceSet for the Function (see prefs for details).

class psyneulink.core.components.functions.distributionfunctions.UniformDist(low=0.0, high=1.0, 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 PreferenceSet for the Function (see prefs for details).
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

Componentcomponent 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 PreferenceSet for the Function (see prefs for details).

class psyneulink.core.components.functions.distributionfunctions.GammaDist(scale=1.0, dist_shape=1.0, params=None, owner=None, prefs=None)

Return a random sample from a gamma distribution using numpy.random.gamma

Modulatory Parameters:

MULTIPLICATIVE_PARAM: scale
ADDITIVE_PARAM: dist_shape

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 PreferenceSet for the Function (see prefs for details).
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

Componentcomponent 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 PreferenceSet for the Function (see prefs for details).

class psyneulink.core.components.functions.distributionfunctions.WaldDist(default_variable=None, scale=1.0, mean=1.0, params=None, owner=None, prefs: <function is_pref_set at 0x112721488> = 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: scale
ADDITIVE_PARAM: mean

scale : float : default 1.0
Scale parameter of the Wald distribution. Should be greater than zero.
mean : float : default 1.0
Mean of the Wald distribution. Should be greater than or equal to 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.
prefs : PreferenceSet or specification dict : default Function.classPreferences
the PreferenceSet for the Function. If it is not specified, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).
scale : float : default 1.0
Scale parameter of the Wald distribution. Should be greater than zero.
mean : float : default 1.0
Mean of the Wald distribution. Should be greater than or equal to 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.
prefs : PreferenceSet or specification dict : default Function.classPreferences
the PreferenceSet for the Function. If it is not specified, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).
class psyneulink.core.components.functions.distributionfunctions.DriftDiffusionAnalytical(default_variable=None, drift_rate=1.0, threshold=1.0, starting_point=0.0, t0=0.2 noise=0.5, params=None, owner=None, prefs=None)

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:

MULTIPLICATIVE_PARAM: drift_rate
ADDITIVE_PARAM: starting_point

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_point (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.
  • t0 (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 PreferenceSet for the Function (see prefs for 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

number or 1d array – holds initial value assigned to default_variable argument; ignored by function.

drift_rate

float or 1d array – determines the drift component of the drift diffusion process.

threshold

float or 1d array – determines the threshold (boundary) of the drift diffusion process (i.e., at which the integration process is assumed to terminate).

starting_point

float or 1d array – determines the initial value of the decision variable for the drift diffusion process.

noise

float or 1d array – determines the diffusion component of the drift diffusion process (used to specify the variance of a Gaussian random process).

t0

float or 1d array – determines the assumed non-decision time to determine the response time returned by the solution.

bias

float or 1d array – normalized starting point: (starting_point + threshold) / (2 * threshold)

owner

Componentcomponent to which the Function has been assigned.

name

str – 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).

prefs

PreferenceSet or specification dict : Function.classPreferences – the PreferenceSet for function; if it is not specified in the prefs argument of the Function’s constructor, a default is assigned using classPreferences defined in __init__.py (see PreferenceSet for details).

shenhav_et_al_compat_mode

Get the 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 chages 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, execution_id=None, params=None, context=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)

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 threshold is:

\(\frac{1}{A} - \frac{E}{A} - 2\frac{A}{c^2}ED\);

and the derivative of 1/RR with respect to the drift_rate is:

\(-\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 threshold and drift_rate.
Return type:List[float, float)