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

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.

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 function);
  • 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 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 : float

(only applicable if function is NavarroAndFuss)

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

RT_CORRECT_VARIANCE : float

(only applicable if function is NavarroAndFuss)

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

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