DDM¶
Overview¶
The DDM Mechanism implements the “Drift Diffusion Model” (also know as the Diffusion Decision, Accumulation to Bound, Linear IntegratorFunction, and Wiener Process First Passage Time Model [REFS]). This corresponds to a continuous version of the sequential probability ratio test (SPRT [REF]), that is the statistically optimal procedure for two alternative forced choice (TAFC) decision making ([REF]).
The DDM Mechanism may be constructed with a choice of several functions that fall into to general categories: analytic solutions and path integration (see DDM Function Types below for more about these options.)
Creating a DDM Mechanism¶
A DDM Mechanism can be instantiated directly by calling its constructor, or by using the mechanism
command and
specifying DDM as its mech_spec argument. The model implementation is selected using the function
argument. The function selection can be simply the name of a DDM function:
>>> import psyneulink as pnl
>>> my_DDM = pnl.DDM(function=pnl.DriftDiffusionAnalytical)
or a call to the function with arguments specifying its parameters:
>>> my_DDM = pnl.DDM(function=pnl.DriftDiffusionAnalytical(drift_rate=0.2, threshold=1.0))
Structure¶
The DDM Mechanism implements a general form of the decision process.
Input¶
The input to the function
of a DDM Mechanism is always a scalar, irrespective of type of function that is used. Accordingly, the default InputState for a DDM takes a single scalar value as its input,
that represents the stimulus for the decision process. However, this can be configured using the input_format
argument of the DDM’s consructor, to accomodate use of the DDM with other Mechanisms that generate a stimulus array
(e.g., representing the stimuli associated with each of the two choices). By default, the input_format is
SCALAR. However, if it is specified as ARRAY, the DDM’s InputState is configured to accept a 1d 2item vector,
and to use Reduce
as its Function, which subtracts the 2nd element of the vector from the 1st, and provides this as
the input to the DDM’s function
. If ARRAY is specified, two Standard OutputStates are added to the DDM, that allow the result of the decision process to be represented
as an array corresponding to the input array (see below).
Output¶
The DDM Mechanism can generate two different types of results depending on which function is selected. When a function representing an analytic solution is selected, the mechanism generates a single estimation for the process. When the path integration function is selected, the mechanism carries out stepwise integration of the process; each execution of the mechanism computes one step. (see DDM Function Types and Execution for additional details).
The value
of the DDM Mechanism may have up to ten items. The first two of these are always assigned, and
are represented by the DDM Mechanism’s two default output_states
: DECISION_VARIABLE and RESPONSE_TIME. Other output_states
may be
automatically assigned, depending on the function
that has been assigned to the DDM, as shown in the
table below:
OutputStates: 


DECISION_VARIABLE  X  X 
RESPONSE_TIME  X  X 
PROBABILITY_UPPER_THRESHOLD  X  
PROBABILITY_LOWER_THRESHOLD  X  
RT_CORRECT_MEAN  X  
RT_CORRECT_VARIANCE  X  
RT_CORRECT_SKEW  X  
RT_INCORRECT_MEAN  X  
RT_INCORRECT_VARIANCE  X  
RT_INCORRECT_SKEW  X 
The output_states
assigned to a DDM can be customized by specifying a list of the desired DDM
Standard OutputStates in the output_states argument of its constructor, or the
OUTPUT_STATES entry of an OutputState specification dictionary. This can
include two additional Standard OutputStates for the DDM  DECISION_VARIABLE_ARRAY
and SELECTED_INPUT_ARRAY
,
that are available if the ARRAY option is specified in its input_format argument (see Input). As with
any Mechanism, customized OutputStates can also be created and assigned.
DDM Function Types¶
Analytic Solutions¶
The Drift Diffusion Model Functions that calculate analytic solutions
[Bogacz et al (2006), Srivastava et al. (2016)] is DriftDiffusionAnalytical
function
, the mechanism generates a single estimate of the outcome for the decision process (see
Execution for details). In addition to DECISION_VARIABLE and
RESPONSE_TIME, the Function returns an accuracy value (represented in the
PROBABILITY_UPPER_THRESHOLD OutputState), and an error rate value (in the PROBABILITY_LOWER_THRESHOLD
OutputState, and moments (mean, variance, and skew) for conditional (correctpositive or incorrect
egative) response time distributions.
These are; the mean RT for correct responses (RT_CORRECT_MEAN, the RT variance for correct responses
(RT_CORRECT_VARIANCE, the RT skew for correct responses (RT_CORRECT_SKEW,
the mean RT for incorrect responses (RT_INCORRECT_MEAN, the RT variance for incorrect
responses (RT_INCORRECT_VARIANCE, the RT skew for incorrect responses
(RT_INCORRECT_SKEW.
An example that illustrate all of the parameters is shown below:
DriftDiffusionAnalytical Function:
>>> my_DDM_DriftDiffusionAnalytical = pnl.DDM(
... function=pnl.DriftDiffusionAnalytical(
... drift_rate=0.08928,
... starting_point=0.5,
... threshold=0.2645,
... noise=0.5,
... t0=0.15
... ),
... name='my_DDM_DriftDiffusionAnalytical'
... )
Path Integration¶
The Drift Diffusion Model Function that calculates a path integration is DriftDiffusionIntegrator. The DDM Mechanism uses the Euler method to carry out numerical stepwise integration of the decision process (see Execution below). In this mode, only the DECISION_VARIABLE and RESPONSE_TIME are available.
IntegratorFunction
Function:
>>> my_DDM_path_integrator = pnl.DDM(
... function=pnl.DriftDiffusionIntegrator(
... noise=0.5,
... initializer=1.0,
... starting_point=2.0,
... rate=3.0
... ),
... name='my_DDM_path_integrator'
... )
Execution¶
When a DDM Mechanism is executed, it computes the decision process either analytically or by
numerical stepwise integration of its path. The method used is determined by its function
(see DDM Function Types). The DDM’s function
always returns values for the DECISION_VARIABLE and RESPONSE_TIME, and assigns these as the first two items of its value
attribute, irrespective of its function.
When an analytic function is selected, the same set of values is returned for every execution.
The returned values are determined entirely by the set of parameters passed to its function
.
When the path integration, function is selected, a single step of integration is conducted each time the Mechanism is executed. The returned values accumulate on every execution.
The analytic functions return a final positon and time of the model, along with other statistics, where as the path integration function returns intermediate position and time values. The two types of functions can be thought of as happening on different time scales: trial (analytic) and time step (path integration).
References
 Bogacz, R., Brown, E., Moehlis, J., Holmes, P., & Cohen, J. D. (2006). The physics of optimal decision making: A formal analysis of models of performance in twoalternative forcedchoice tasks. Psychological Review, 113(4), 700765. http://dx.doi.org/10.1037/0033295X.113.4.700
 Srivastava, V., Holmes, P., Simen., P. (2016). Explicit moments of decision times for single and doublethreshold driftdiffusion processes, Journal of Mathematical Psychology, 75, 96109, ISSN 00222496, https://doi.org/10.1016/j.jmp.2016.03.005. (http://www.sciencedirect.com/science/article/pii/S0022249616000341)
Class Reference¶

class
psyneulink.library.components.mechanisms.processing.integrator.ddm.
DDM_OUTPUT
¶ Standard OutputStates for DDM:
 DECISION_VARIABLE : float
 analytic mode: the value of the threshold crossed by the decision variable on the
current TRIAL (which is either the value of the DDM
function
’s threshold attribute or its negative);  integration mode: the value of the decision variable at the current TIME_STEP of execution.
Corresponds to the 1st item of the DDM’s
value
. analytic mode: the value of the threshold crossed by the decision variable on the
current TRIAL (which is either the value of the DDM
 DECISION_VARIABLE_ARRAY : 1d nparray
Note
This is available only if input_format is specified as ARRAY in the DDM Mechanism’s constructor (see Input).
 analytic mode: two element array, with the decision variable (1st item of the DDM’s
value
) as the 1st element if the decision process crossed the upper threshold, and the 2nd element if it is closer to the lower threshold; the other element is set to 0.  integration mode: the value of the decision variable at the current TIME_STEP of execution, assigned to the 1st element if the decision variable is closer to the upper threshold, and to the 2nd element if it is closer to the lower threshold; the other element is set to 0.
 analytic mode: two element array, with the decision variable (1st item of the DDM’s
 SELECTED_INPUT_ARRAY : 1d nparray
Note
This is available only if input_format is specified as ARRAY in the DDM Mechanism’s constructor (see Input).
 analytic mode: two element array, with one (“selected”) element – determined by the
outcome of the decision process – set to the value of the corresponding element in the stimulus array (i.e.,
the DDM’s input_state
variable
). The “selected” element is the 1st one if the decision process resulted in crossing the upper threshold, and the 2nd if it crossed the lower threshold; the other element is set to 0.  integration mode: the value of the element in the stimulus array based on the
decision variable (1st item of the DDM’s
value
) at the current TIME_STEP of execution: it is assigned to the 1st element if the decision variable is closer to the upper threshold, and to the 2nd element if the decision variable is closer to the lower threshold; the other element is set to 0.
 analytic mode: two element array, with one (“selected”) element – determined by the
outcome of the decision process – set to the value of the corresponding element in the stimulus array (i.e.,
the DDM’s input_state
 RESPONSE_TIME : float
 analytic mode: mean time (in seconds) for the decision variable to reach the positive
or negative value of the DDM
function
’s threshold attribute as estimated by the analytic solution calculated by thefunction
);  integration mode: the number of
TIME_STEP
that have occurred since the DDM began to execute in the currentTRIAL
or, if it has reached the positive or negative value of the DDMfunction
’s threshold attribute, theTIME_STEP
at which that occurred.
Corresponds to the 2nd item of the DDM’s
value
. analytic mode: mean time (in seconds) for the decision variable to reach the positive
or negative value of the DDM
 PROBABILITY_UPPER_THRESHOLD : float
 analytic mode: the probability of the decision variable reaching the positive value of
the DDM
function
’s threshold attribute as estimated by the analytic solution calculated by thefunction
; often, by convention, the positive (upper) threshold is associated with the correct response, in which case PROBABILITY_UPPER_THRESHOLD corresponds to the accuracy of the decision process.  integration mode:
None
.
Corresponds to the 3rd item of the DDM’s
value
. analytic mode: the probability of the decision variable reaching the positive value of
the DDM
 PROBABILITY_LOWER_THRESHOLD : float
 analytic mode: the probability of the decision variable reaching the negative value of
the DDM
function
’s threshold attribute as estimated by the analytic solution calculate by thefunction
); often, by convention, the negative (lower) threshold is associated with an error response, in which case PROBABILITY_LOWER_THRESHOLD corresponds to the error rate of the decision process;  integration mode:
None
.
Corresponds to the 4th item of the DDM’s
value
. analytic mode: the probability of the decision variable reaching the negative value of
the DDM
 RT_CORRECT_MEAN : floa
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the mean reaction time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 5th item of the DDM’s
value
. analytic mode: the mean reaction time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
 RT_CORRECT_VARIANCE : float
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the variance of reaction time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 6th item of the DDM’s
value
. analytic mode: the variance of reaction time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
 RT_CORRECT_SKEW : float
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the skew of decision time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 7th item of the DDM’s
value
. analytic mode: the skew of decision time (in seconds) for responses in which the decision
variable reached the positive value of the DDM
 RT_INCORRECT_MEAN : float
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the mean reaction time (in seconds) for responses in which the decision
variable reached the negative value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 5th item of the DDM’s
value
. analytic mode: the mean reaction time (in seconds) for responses in which the decision
variable reached the negative value of the DDM
 RT_INCORRECT_VARIANCE : float
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the variance of reaction time (in seconds) for responses in which the decision
variable reached the negative value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 6th item of the DDM’s
value
. analytic mode: the variance of reaction time (in seconds) for responses in which the decision
variable reached the negative value of the DDM
 RT_INCORRECT_SKEW : float
(only applicable if
function
isDriftDiffusionAnalytical
) analytic mode: the skew of decision time (in seconds) for responses in which the decision
variable reached the negative value of the DDM
function
’s threshold attribute as estimated by closed form analytic solutions from Srivastava et al. (https://arxiv.org/abs/1601.06420)  integration mode:
None
.
Corresponds to the 7th item of the DDM’s
value
. analytic mode: the skew of decision time (in seconds) for responses in which the decision
variable reached the negative value of the DDM

class
psyneulink.library.components.mechanisms.processing.integrator.ddm.
DDM
(default_variable=None, size=None, function=DriftDiffusionAnalytical, params=None, name=None, prefs=None)¶ Implement a Drift Diffusion Process, either by calculating an analytic solution or carrying out stepwise numerical integration.
Parameters:  default_variable (value, list or np.ndarray : default FUNCTION_PARAMS[STARTING_POINT]) – the input to the Mechanism used if none is provided in a call to its
execute
orrun
methods; also serves as a template to specify the length of thevariable
for itsfunction
, and theprimary OutputState
of the DDM (seeInput
<DDM_Creation>` for how an input with a length of greater than 1 is handled).  size (int, list or np.ndarray of ints) –
specifies the
default_variable
as array(s) of zeros if default_variable is not passed as an argument; if default_variable is specified, it takes precedence over the specification of size. As an example, the following mechanisms are equivalent:T1 = TransferMechanism(size = [3, 2]) T2 = TransferMechanism(default_variable = [[0, 0, 0], [0, 0]])
 function (IntegratorFunction : default DriftDiffusionAnalytical) – specifies the function to use to execute the decision process; determines the mode of
execution (see
function
and DDM Function Types for additional information).  params (Dict[param keyword: param value] : default None) – a dictionary that can be used to specify parameters of the Mechanism, parameters of its
function
, and/or a custom function and its parameters (see Mechanism for specification of a params dict).  name (str : default see
name
) – specifies the name of the DDM.  prefs (PreferenceSet or specification dict : default Mechanism.classPreferences) – specifies the
PreferenceSet
for the DDM; seeprefs
for details.

variable
¶ value : default FUNCTION_PARAMS[STARTING_POINT] – the input to Mechanism’s execute method. Serves as the “stimulus” component of the
function
’s drift_rate parameter.

function
¶ IntegratorFunction : default DriftDiffusionAnalytical – the function used to execute the decision process; determines the mode of execution. If it is DriftDiffusionAnalytical, an analytic solution is calculated (note: the latter requires that the MatLab engine is installed); if it is an
IntegratorFunction
Function with anintegration_type
of DIFFUSION, then numerical stepwise integration is carried out. See DDM Function Types and Execution for additional information.

value
¶ 2d np.array[array(float64),array(float64),array(float64),array(float64)] – result of executing DDM
function
; has six items, that are assigned based on thefunction
attribute. The first two items are always assigned the values of DECISION_VARIABLE and RESPONSE_TIME (though their interpretation depends on thefunction
and corresponding mode of of operation). See DDM Function Types, Execution, and DDM Standard OutputStates for additional information about other values that can be reported and their interpretation.

output_states
¶ ContentAddressableList[OutputState] – list of the DDM’s OutputStates. There are always two OutputStates, DECISION_VARIABLE and RESPONSE_TIME; additional ones may be included based on the
function
and/or any specifications made in the output_states argument of the DDM’s constructor (see DDM Standard OutputStates).

output_values
¶ List[array(float64),array(float64),array(float64),array(float64)] – each item is the
value
. The first two items are always thevalue
s of the DECISION_VARIABLE and RESPONSE_TIME OutputStates; additional ones may be included, based on thefunction
and any specifications made in the output_states argument of the DDM’s constructor (see DDM Standard OutputStates).

name
¶ str – the name of the DDM; if it is not specified in the name argument of the constructor, a default is assigned by MechanismRegistry (see Naming for conventions used for default and duplicate names).

prefs
¶ PreferenceSet or specification dict – the
PreferenceSet
for the DDM; if it is not specified in the prefs argument of the constructor, a default is assigned usingclassPreferences
defined in __init__.py (see PreferenceSet for details).

plot
(stimulus=1.0, threshold=10.0)¶ Generate a dynamic plot of the DDM integrating over time towards a threshold.
Note
The plot method is only available when the DriftDiffusionIntegrator function is in use. The plot method does not represent the results of this DDM mechanism in particular, and does not affect the current state of this mechanism’s DriftDiffusionIntegrator. The plot method is only meant to visualize a possible path of a DDM mechanism with these function parameters.
Parameters:  stimulus (float: default 1.0) – specify a stimulus value for the AdaptiveIntegrator function
 threshold (float: default 10.0) – specify the threshold at which the DDM will stop integrating
Returns: Mechanism’s function plot – Matplotlib window of the Mechanism’s function plotting dynamically over time with specified parameters towards a specified threshold
Return type: Matplotlib window
 default_variable (value, list or np.ndarray : default FUNCTION_PARAMS[STARTING_POINT]) – the input to the Mechanism used if none is provided in a call to its