Simulate Trajectories/Traces of a Model

Simulates single trajectories/traces of a model (i.e., evidence accumulation processes) using forward Euler.

Might come in handy when exploring the model's behavior or when creating figures (see also plot.traces_dm_list)

Usage

simulate_traces(object, k, ...)

# S3 method for class 'drift_dm'
simulate_traces(
  object,
  k,
  ...,
  conds = NULL,
  add_x = FALSE,
  sigma = NULL,
  seed = NULL,
  unpack = FALSE
)

# S3 method for class 'fits_ids_dm'
simulate_traces(object, k, ...)

# S3 method for class 'traces_dm_list'
print(x, ..., round_digits = drift_dm_default_rounding(), print_steps = 5)

# S3 method for class 'traces_dm'
print(
  x,
  ...,
  round_digits = drift_dm_default_rounding(),
  print_steps = 5,
  print_k = 4
)

Arguments

object: an object of type drift_dm or fits_ids_dm (see load_fits_ids).
k: numeric, the number of traces to simulate per condition. Can be a named numeric vector, to specify different number of traces per condition.
...: additional arguments passed forward to the respective method.
conds: optional character vector, conditions for which traces shall be simulated. If NULL, then traces for all conditions are simulated.
add_x: logical, indicating whether traces should contain a variable starting point. If TRUE, samples from x_fun (see comp_vals) are added to each trace. Default is FALSE.
sigma: optional numeric, providing a value >= 0 for the diffusion constant "sigma" to temporally override prms_solve. Useful for exploring the model without noise.
seed: optional numerical, a seed for reproducible sampling
unpack: logical, indicating if the traces shall be "unpacked" (see also unpack_traces and the return value below).
x: an object of type traces_dm_list or traces_dm, resulting from a call to simulate_traces.
round_digits: integer, indicating the number of decimal places (round) to be used when printing out the traces (default is 3).
print_steps: integer, indicating the number of steps to show when printing out traces (default is 5).
print_k: integer, indicating how many traces shall be shown when printing out traces (default is 4).

Value

simulate_traces() returns either a list of type traces_dm_list, or directly the plain traces as matrices across conditions (if unpack = TRUE). If the model has only one condition (and unpack = TRUE), then the matrix of traces for this one condition is directly returned.

The returned list has as many entries as conditions requested. For example, if only one condition is requested via the conds argument, then the list is of length 1 (if unpack = FALSE). If conds is set to NULL (default), then the list will have as many entries as conditions specified in the supplied object (see also conds). If unpack = FALSE, the list contains an additional attribute with the time space.

Each matrix of traces has k rows and nt + 1 columns, stored as an array of size (k, nt + 1). Note that nt is the number of steps in the discretization of time; see drift_dm. If unpack = FALSE, the array is of type traces_dm. It contains some additional attributes about the time space, the drift rate, the boundary, and the added starting values.

The print methods print.traces_dm_list() and print.traces_dm() each invisibly return the supplied object x.

Details

simulate_traces() is a generic function, applicable to objects of type drift_dm or fits_ids_dm (see load_fits_ids).

For drift_dm objects, simulate_traces() performs the simulation on the parameter values currently set (see coef.drift_dm()).

For fits_ids_dm objects, simulate_traces() first extracts the model and all parameter values for all IDs (see coef.fits_ids_dm()). Subsequently, simulations are based on the averaged parameter values.

The algorithm for simulating traces is forward euler. See Richteretal.2023;textualdRiftDM and Ulrichetal.2015;textualdRiftDM (Appendix A) for more information.

Note

Evidence values with traces beyond the boundary of the model are set to NA before passing them back.

The reason why simulate_traces passes back an object of type traces_dm_list (instead of simply a list of arrays) is to provide a plot.traces_dm_list and print.traces_dm_list function.

Users can unpack the traces even after calling simulate_traces() using unpack_traces().

Examples

# get a pre-built model to demonstrate the function
my_model <- dmc_dm()
some_traces <- simulate_traces(my_model, k = 1, seed = 1)
print(some_traces)
#> Class(es): traces_dm_list
#> 
#> Time space:
#> 0.000, 0.001, 0.002, 0.003 ... 3.000 
#> 
#> Condition: comp 
#> ~>  0.000, -0.009,  0.007, -0.009 ...  0.618 
#> 
#> Condition: incomp 
#> ~>  0.000,  0.009,  0.048,  0.020 ...  0.632 

# a method is also available for fits_ids_dm objects
# (see estimate_model_ids)
# get an exemplary fits_ids_dm object
fits <- get_example_fits_ids()
some_traces <- simulate_traces(fits, k = 1, seed = 1)
print(some_traces)
#> Class(es): traces_dm_list
#> 
#> Time space:
#> 0.000, 0.002, 0.004, 0.006 ... 1.500 
#> 
#> Condition: comp 
#> ~>  0.000, -0.007,  0.021,  0.004 ...  0.500 
#> 
#> Condition: incomp 
#> ~>  0.000, -0.038, -0.093, -0.061 ...  0.492 

# we can also print only the traces of one condition
print(some_traces$comp)
#> ~>  0.000, -0.007,  0.021,  0.004 ...  0.500