ddModel (version 0.2.9.0)

validate_ddm_parameters: Simulate Design-based Decision Diffusion Model (DDM) Trials

Description

Generates synthetic response time (RT) and choice data using a diffusion decision model (DDM) with specified parameters. The simulation allows for flexible parameter settings and time-domain controls.

Usage

validate_ddm_parameters(rt_model_r, parameters_r, debug = FALSE)
simulate_ddm_trials(
  rt_model_r,
  parameters_r,
  time_parameters_r = as.numeric(c()),
  n_trial = 1L,
  debug = FALSE
)

Value

A data.frame with the following columns:

rt

Simulated response times in seconds

response

Binary decision outcome (0 = lower boundary, 1 = upper boundary)

Arguments

rt_model_r

An S4 object of class ddm specifying the DDM configuration. Must contain slots for boundary separation, drift rate, and other DDM-relevant parameters.

parameters_r

A numeric vector of DDM parameters. Expected elements:

a

Boundary separation (threshold)

v

Drift rate (evidence accumulation speed)

t0

Non-decision time (encoding + motor response baseline)

z

Starting point (bias; must satisfy 0 < z < a)

d

(Optional) Difference in motor execution time between boundaries

sv

(Optional) Inter-trial variability in drift rate

st0

(Optional) Inter-trial variability in non-decision time

sz

(Optional) Inter-trial variability in starting point

debug

Logical. If TRUE, prints internal simulation states and timing diagnostics.

time_parameters_r

A numeric vector controlling simulation's temporal dynamics:

[1]

Minimum time (default: -0.5)

[2]

Maximum time (default: 0.5)

[3]

Time step for numerical integration (default: 0.01)

n_trial

Integer. Number of trials to simulate (default: 1).

Details

The core simulation is implemented in C++ via simulate_ddm_trials for high performance in large-scale experiments. A complementary R wrapper (.simulate_ddm_trials) provides additional functionality, such as random seed control and input validation.

The function validate_ddm_parameters checks whether the input parameter vector satisfies the constraints of the diffusion model.

References

Ratcliff, R., & McKoon, G. (2008). The diffusion decision model: Theory and data for two-choice decision tasks. Neural Computation, 20(4), 873-922.

See Also

ddm-class, setDDM, validate_ddm_parameters

Examples

# Basic simulation with default parameters
if (requireNamespace("ggdmcModel", quietly = TRUE)) {
  BuildModel <- getFromNamespace("BuildModel", "ggdmcModel")
  model <- ggdmcModel::BuildModel(
    p_map = list(
      a = "1", v = "1", z = "1", d = "1", sz = "1", sv = "1",
      t0 = "1", st0 = "1", s = "1", precision = "1"
    ),
    match_map = list(M = list(s1 = "r1", s2 = "r2")),
    factors = list(S = c("s1", "s2")),
    constants = c(d = 0, s = 1, st0 = 0, sv = 0, precision = 3),
    accumulators = c("r1", "r2"),
    type = "fastdm"
  )
}
sub_model <- setDDM(model)
p_vector <- c(a = 1, sz = 0.25, t0 = 0.15, v = 2.5, z = .38)
time_parameters <- c(t_min = -0.5, tmax = 0.5, dt = 0.01)

# Simulation with custom time parameters
sim_data <- simulate_ddm_trials(
  rt_model_r = sub_model,
  parameters_r = p_vector,
  time_parameters_r = time_parameters,
  n_trial = 32
)