superstats.simulation.cognitive#

Cognitive-model simulators.

superstats.simulation.cognitive.sample_cdm(v_angle, v_length, a, tau, sigma=1.0, dt=0.001, max_steps=10000)[source]#

Sample from the Circular Diffusion Model (CDM).

Simulates a 2D diffusion process starting from the origin, with a constant drift specified in polar form, evolving until it crosses a circular boundary of radius a. The crossing point determines the response angle and the number of steps determines the response time. On each trial the drift vector has length v_length and points in direction v_angle; the two Cartesian components diffuse independently with noise SD sigma until the squared radius reaches a ** 2.

Parameters:
v_anglenp.ndarray of shape (num_trials,)

Direction of the drift vector (in radians) for each trial.

v_lengthnp.ndarray of shape (num_trials,)

Magnitude of the drift vector for each trial. The Cartesian drift components are v_length * cos(v_angle) and v_length * sin(v_angle).

anp.ndarray of shape (num_trials,)

Radius of the circular decision boundary for each trial.

taunp.ndarray of shape (num_trials,)

Non-decision times for each trial.

sigmafloat, optional, default: 1.0

Diffusion noise standard deviation, shared by both Cartesian components. Fixed (not estimated per trial) for identifiability, since the boundary radius a and drift set the overall scale.

dtfloat, optional, default: 0.001

Time step size.

max_stepsint, optional, default: 10000

Maximum number of diffusion steps per trial before timing out.

Returns:
datadict of np.ndarray

Named decision data. “response_time” contains response times (or -5.0 on timeout) and “choice” contains response angles in radians (or -5.0 on timeout). Each array has shape (num_trials,).

Parameters:
Return type:

dict[str, ndarray]

superstats.simulation.cognitive.sample_ddm(v, a, tau, bias, sigma=1.0, dt=0.001, max_steps=10000)[source]#

Sample from the Diffusion Decision Model (DDM) for decision making.

This function simulates decision processes using the DDM, where evidence accumulates over time with drift rate v, boundary separation a, and noise. The simulation stops when a boundary is reached or max_steps is exceeded.

Parameters:
vnp.ndarray of shape (num_steps,)

Drift rates for each trial.

anp.ndarray of shape (num_steps,)

Boundary separation for each trial; decision boundaries are at 0 (lower) and a (upper).

taunp.ndarray of shape (num_steps,)

Non-decision times for each trial.

biasnp.ndarray of shape (num_steps,)

Starting point, as a fraction of a (i.e. the initial evidence is bias * a). 0.5 starts at the midpoint between the two boundaries; values > 0.5 start closer to the upper boundary, values < 0.5 closer to the lower one. Must lie in (0, 1).

sigmafloat, optional, default: 1.0

Diffusion noise standard deviation.

dtfloat, optional, default: 0.001

Time step size.

max_stepsint, optional, default: 10000

Maximum number of diffusion steps per trial before timing out.

Returns:
datadict of np.ndarray

Named decision data. “response_time” contains response times (or -1.0 on timeout) and “choice” contains choices (1.0 for the upper boundary, 0.0 for the lower boundary, -1.0 on timeout). Each array has shape (num_steps,).

Parameters:
Return type:

dict[str, ndarray]

superstats.simulation.cognitive.sample_rdm(v_base, v_diff, a_base, tau, bias, sigma_diff, num_accumulators=2, correct_idx=None, sigma_base=1.0, dt=0.001, max_steps=10000)[source]#

Sample from the Racing Diffusion Model (RDM).

Simulates num_accumulators independent diffusion accumulators racing from a starting point of 0 toward their own threshold; the first to cross wins and determines the response and response time. On each trial, the accumulator at index correct_idx[i] is treated as the correct/target accumulator: it receives a drift advantage of v_diff, a bias-scaled threshold, and noise scaled by sigma_diff. All other accumulators on that trial share the disadvantaged drift, an unscaled threshold, and noise fixed at sigma_base.

Parameters:
v_basenp.ndarray of shape (num_trials,)

Base drift rate shared by all accumulators before the correct/incorrect adjustment.

v_diffnp.ndarray of shape (num_trials,)

Drift rate difference between the correct and incorrect accumulators. The correct accumulator gets v_base + v_diff / 2; all other accumulators get v_base - v_diff / 2.

a_basenp.ndarray of shape (num_trials,)

Base threshold distance from the origin for each trial.

taunp.ndarray of shape (num_trials,)

Non-decision times for each trial.

biasnp.ndarray of shape (num_trials,)

Threshold scaling factor in [0, 1] for the correct/target accumulator: its threshold is a_base * bias. All other accumulators use the unscaled threshold a_base.

sigma_diffnp.ndarray of shape (num_trials,)

Noise scaling factor in [0, +inf) for the correct/target accumulator: its noise SD is sigma_base * sigma_diff. All other accumulators always use sigma_base directly.

num_accumulatorsint

Number of racing accumulators per trial (fixed across trials).

correct_idxnp.ndarray of shape (num_trials,), optional

Index (into 0 .. num_accumulators - 1) of the correct/target accumulator for each trial. If left empty, accumulator 0 is treated as correct on every trial.

sigma_basefloat, optional, default: 1.0

Diffusion noise standard deviation of the non-correct accumulators. Fixed (not estimated per trial) for identifiability.

dtfloat, optional, default: 0.001

Time step size.

max_stepsint, optional, default: 10000

Maximum number of diffusion steps per trial before timing out.

Returns:
datadict of np.ndarray

Named decision data. “response_time” contains response times (or -1.0 on timeout) and “choice” contains the index of the winning accumulator (or -1.0 on timeout). Each array has shape (num_trials,).

Parameters:
Return type:

dict[str, ndarray]

Modules

cdm

Circular Diffusion Model simulator.

ddm

Diffusion Decision Model simulator.

rdm

Racing Diffusion Model simulator.