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
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))
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
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 step-wise integration of the process; each
execution of the mechanism computes one step. (see DDM Function Types and Execution for additional details).
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.
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
DDM Function Types
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:
>>> my_DDM_BogaczEtAl = pnl.DDM(
NavarroAndFuss Function (requires MATLAB engine):
>>> my_DDM_NavarroAndFuss = pnl.DDM(
The Drift Diffusion Model Function that calculates a path integration is DriftDiffusionIntegrator. The DDM Mechanism uses the Euler method to
carry out numerical step-wise integration of the decision process (see Execution below). In this
mode, only the DECISION_VARIABLE and RESPONSE_TIME are available.
>>> my_DDM_path_integrator = pnl.DDM(
When a DDM Mechanism is executed, it computes the decision process either analytically or by
numerical step-wise 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
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).
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
- integration mode: the value of the decision variable at the current TIME_STEP of
Corresponds to the 1st item of the DDM’s
- 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 the
- integration mode: the number of
TIME_STEP that have occurred since the DDM began
to execute in the current
TRIAL or, if it has reached the positive or negative value of the DDM
function’s threshold attribute, the
TIME_STEP at which that occurred.
Corresponds to the 2nd item of the DDM’s
- PROBABILITY_UPPER_THRESHOLD : float
- analytic mode: the probability of the decision variable reaching the positive value of
function’s threshold attribute as estimated by the analytic solution calculated by the
function; 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
- integration mode:
Corresponds to the 3rd item of the DDM’s
- PROBABILITY_LOWER_THRESHOLD : float
- analytic mode: the probability of the decision variable reaching the negative value of
function’s threshold attribute as estimated by the analytic solution calculate by the
function); 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:
Corresponds to the 4th item of the DDM’s
- RT_CORRECT_MEAN : float
(only applicable if
Corresponds to the 5th item of the DDM’s
- RT_CORRECT_VARIANCE : float
(only applicable if
Corresponds to the 6th item of the DDM’s
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 step-wise numerical integration.
- 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
run methods; also serves as a template to specify the length of the
variable for its
function, and the
primary OutputState of the
Input <DDM_Creation>` for how an input with a length of greater than 1 is handled).
- size (int, list or np.ndarray of ints) –
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
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; see
prefs for details.
value : default FUNCTION_PARAMS[STARTING_POINT] – the input to Mechanism’s execute method. Serves as the “stimulus” component of the
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
Integrator Function with an
integration_type of DIFFUSION,
then numerical step-wise integration is carried out. See DDM Function Types and
Execution for additional information.
2d np.array[array(float64),array(float64),array(float64),array(float64)] – result of executing DDM
function; has six items, that are assigned based on the
function attribute. The first two items are always assigned the values of DECISION_VARIABLE and RESPONSE_TIME (though their interpretation depends on the
function 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.
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).
List[array(float64),array(float64),array(float64),array(float64)] – each item is the
value. The first two items are always the
values of the
DECISION_VARIABLE and RESPONSE_TIME OutputStates; additional
ones may be included, based on the
function and any specifications made in the
output_states argument of the DDM’s constructor (see DDM Standard OutputStates).
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).
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 using
classPreferences defined in __init__.py (see PreferenceSet for details).
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