Table of Contents
  • Docs >
  • DistributionFunctions

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:

MULTIPLICATIVE_PARAM: drift_rate
ADDITIVE_PARAM: starting_value

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 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

holds initial value assigned to default_variable argument; ignored by function.

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

owner

component to which the Function has been assigned.

Type:

Component

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 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 Preferences for details).

Type:

PreferenceSet or specification dict : Function.classPreferences

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.

_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)

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)

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)

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

owner

component to which to assign the Function.

Type:

Component

name

specifies the name of the Function.

Type:

str : default see name

prefs

specifies the PreferenceSet for the Function (see prefs for details).

Type:

PreferenceSet or specification dict : default Function.classPreferences

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:

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

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

owner

component to which to assign the Function.

Type:

Component

name

specifies the name of the Function.

Type:

str : default see name

prefs

specifies the PreferenceSet for the Function (see prefs for details).

Type:

PreferenceSet or specification dict : default Function.classPreferences

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:

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

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

owner

component to which to assign the Function.

Type:

Component

name

specifies the name of the Function.

Type:

str : default see name

prefs

specifies the PreferenceSet for the Function (see prefs for details).

Type:

PreferenceSet or specification dict : default Function.classPreferences

_model_spec_generic_type_name = 'onnx::RandomNormal'

string describing this class’s generic type in universal model specification, if it exists and is different than the class name

_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 PreferenceSet for the Function (see prefs for 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

owner

component to which to assign the Function.

Type:

Component

name

specifies the name of the Function.

Type:

str : default see name

prefs

specifies the PreferenceSet for the Function (see prefs for details).

Type:

PreferenceSet or specification dict : default Function.classPreferences

_model_spec_generic_type_name = 'onnx::RandomUniform'

string describing this class’s generic type in universal model specification, if it exists and is different than the class 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:

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

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

owner

component to which to assign the Function.

Type:

Component

name

specifies the name of the Function.

Type:

str : default see name

prefs

specifies the PreferenceSet for the Function (see prefs for details).

Type:

PreferenceSet or specification dict : default Function.classPreferences

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: scale
ADDITIVE_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 PreferenceSet for the Function. If it is not specified, a default is assigned using classPreferences defined 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 PreferenceSet for the Function. If it is not specified, a default is assigned using classPreferences defined in __init__.py (see Preferences for details).