DDM¶
Overview¶
The DDM Mechanism implements the “Drift Diffusion Model” (also know as the Diffusion Decision, Accumulation to Bound, Linear Integrator, 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.BogaczEtAl)
or a call to the function with arguments specifying its parameters:
>>> my_DDM = pnl.DDM(function=pnl.BogaczEtAl(drift_rate=0.2, threshold=1.0))
Structure¶
The DDM Mechanism implements a general form of the decision process. A DDM Mechanism has a single InputState, the
value
of which is assigned to the input specified by its execute
or run
methods, which represents the stimulus for the process. That parameter, along with all
of the others for the DDM, must be assigned as parameters of the DDM’s function
(see examples under
DDM Function Types below, and individual Functions for additional details).
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 six 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. The other output_states
may be
assigned depending on (1) whether the selected function produces those quantities and (2) customization.
Function  Type  Output States  
DECISION_VARIABLE  RESPONSE_TIME  PROBABILITY_UPPER_THRESHOLD  PROBABILITY_LOWER_THRESHOLD  RT_CORRECT_MEAN  RT_CORRECT_VARIANCE  
BogaczEtAl  Analytic  X  X  X  X  
NavarroAndFuss  Analytic  X  X  X  X  X  X 
DriftDiffusionIntegrator  Path Integration  X  X 
The set of output_states
assigned can be customized by selecting ones from the DDM’s set of
Standard OutputStates), and specifying these in the output_states argument of its
constructor. Some OutputStates, or elements of value
, represent slightly different quantities
depending on the function in which they are computed. See Standard OutputStates for more
details.
DDM Function Types¶
Analytic Solutions¶
The two Drift Diffusion Model Functions that calculate analytic solutions are BogaczEtAl
and NavarroAndFuss. When one of these functions is specified as the DDM Mechanism’s
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, both Functions return an accuracy value (represented in the PROBABILITY_UPPER_THRESHOLD OutputState), and an error rate value (in the PROBABILITY_LOWER_THRESHOLD OutputState; the NavarroAndFuss Function also returns expected values for mean correct response time (RT_CORRECT_MEAN and variance of correct response times (RT_CORRECT_VARIANCE.
Examples for each, that illustrate all of their parameters, are shown below:
BogaczEtAl Function:
>>> my_DDM_BogaczEtAl = pnl.DDM(
... function=pnl.BogaczEtAl(
... drift_rate=0.08928,
... starting_point=0.5,
... threshold=0.2645,
... noise=0.5,
... t0=0.15
... ),
... name='my_DDM_BogaczEtAl'
... )
NavarroAndFuss Function (requires MATLAB engine):
>>> my_DDM_NavarroAndFuss = pnl.DDM(
... function=pnl.NavarroAndFuss(
... drift_rate=0.08928,
... starting_point=0.5,
... threshold=0.2645,
... noise=0.5,
... t0=0.15
... ),
... name='my_DDM_NavarroAndFuss'
... )
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.
Integrator Function:
>>> my_DDM_path_integrator = pnl.DDM(
... function=pnl.DriftDiffusionIntegrator(
... noise=0.5,
... initializer=1.0,
... t0=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).
Class Reference¶

class
psyneulink.library.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
 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 : float
(only applicable if
function
isNavarroAndFuss
) analytic mode: the mean 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 theNavarroAndFuss
analytic solution;  integration mode:
None
.
Corresponds to the 5th item of the DDM’s
value
. analytic mode: the mean decision 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
isNavarroAndFuss
) analytic mode: the variance of the decision time for responses in which the decision
variable reached the positive value of the DDM
function
’s threshold attribute as estimated by theNavarroAndFuss
analytic solution;  integration mode:
None
.
Corresponds to the 6th item of the DDM’s
value
. analytic mode: the variance of the decision time for responses in which the decision
variable reached the positive value of the DDM

class
psyneulink.library.mechanisms.processing.integrator.ddm.
DDM
(default_variable=None, size=None, function=BogaczEtAl, 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 BogaczEtAl) – 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 BogaczEtAl – the function used to execute the decision process; determines the mode of execution. If it is BogaczEtAl or NavarroAndFuss, an analytic solution is calculated (note: the latter requires that the MatLab engine is installed); if it is an
Integrator
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: plot is only available integration mode (with the Integrator function).
Parameters: 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