# 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 2-item 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 step-wise 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: Function (type) DriftDiffusionAnalytical (analytic) DriftDiffusionIntegrator (path integration)) 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 step-wise 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 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 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

## Class Reference¶

class psyneulink.library.components.mechanisms.processing.integrator.ddm.DDM_OUTPUT
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.

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.
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.
RESPONSE_TIME : float

Corresponds to the 2nd item of the DDM’s value.

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 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 process.
• integration mode: None.

Corresponds to the 3rd item of the DDM’s value.

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 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: None.

Corresponds to the 4th item of the DDM’s value.

RT_CORRECT_MEAN : floa

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 5th item of the DDM’s value.

RT_CORRECT_VARIANCE : float

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 6th item of the DDM’s value.

RT_CORRECT_SKEW : float

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 7th item of the DDM’s value.

RT_INCORRECT_MEAN : float

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 5th item of the DDM’s value.

RT_INCORRECT_VARIANCE : float

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 6th item of the DDM’s value.

RT_INCORRECT_SKEW : float

(only applicable if function is DriftDiffusionAnalytical)

Corresponds to the 7th item of the DDM’s value.

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 step-wise 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 or run methods; also serves as a template to specify the length of the variable for its function, and the primary OutputState of the DDM (see Input  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; see prefs 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 an integration_type of DIFFUSION, then numerical step-wise 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 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.

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

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 using classPreferences 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 Mechanism’s function plot – Matplotlib window of the Mechanism’s function plotting dynamically over time with specified parameters towards a specified threshold Matplotlib window