Skip to contents

Create a drift_dm object

Source: R/core_dm.R, R/formatting_drift_dm.R
drift_dm.Rd

This function creates an object of type drift_dm, which serves as the parent class for all further created drift diffusion models (all of which have a child class label, e.g., dmc_dm). The objects created by drift_dm() are the backbone of the dRiftDM package. For a list of all pre-built models, see vignette("dRiftDM", "dRiftDM").

Usage

drift_dm(
  prms_model,
  conds,
  subclass,
  instr = NULL,
  obs_data = NULL,
  sigma = 1,
  t_max = 3,
  dt = 0.001,
  dx = 0.001,
  solver = "kfe",
  mu_fun = NULL,
  mu_int_fun = NULL,
  x_fun = NULL,
  b_fun = NULL,
  dt_b_fun = NULL,
  nt_fun = NULL,
  b_coding = NULL
)

# S3 method for class 'drift_dm'
print(x, ..., round_digits = drift_dm_default_rounding())

Arguments

prms_model

a named numeric vector of the model parameters. The names indicate the model's parameters, and the numeric entries provide the current parameter values.

conds

a character vector, giving the names of the model's conditions. values within conds will be used when addressing the data and when deriving the model's predictions.

subclass

a character string, with a name for the newly created diffusion model (e.g., dmc_dm). This will be the child class.

instr

an optional character string, providing "instructions" for the underlying flex_prms object.

obs_data

an optional data.frame, providing a data set (see obs_data() for more information).

sigma

the diffusion constant. Default is 1.

t_max

the maximum of the time space. Default is set 3 (seconds).

dt, dx

the step size of the time and evidence space discretization, respectively. Default is set to .001 (which refers to seconds for dt). Note that these values are set conservatively per default. In many cases, users can increase the discretization.

solver

a character string, specifying which approach to use for deriving the first passage time. Default is kfe, which provides access to the numerical discretization of the Kolmogorov Forward Equation.

mu_fun, mu_int_fun, x_fun, b_fun, dt_b_fun, nt_fun

Optional custom functions defining the components of a diffusion model. See comp_funs(). If an argument is NULL, dRiftDM falls back to the respective default functions, which are documented in comp_funs().

b_coding

an optional list, specifying how boundaries are coded. See b_coding(). Default refers to accuracy coding.

x

an object of type drift_dm

...

additional parameters

round_digits

integer, controls the number of digits shown for print.drift_dm(). Default is 3.

Value

For drift_dm(), a list with the parent class label "drift_dm" and the child class label <subclass>. The list contains the following entries:

  • An instance of the class flex_prms for controlling the model parameters. Provides information about the number of parameters, conditions etc.

  • Parameters used for deriving the model predictions, prms_solve, containing the diffusion constant (sigma), the maximum of the time space (t_max), the evidence and space discretization (dt and dx, respectively), and the resulting number of steps for the time and evidence space discretization (nt and nx, respectively).

  • A character string solver, indicating the method for deriving the model predictions.

  • A list of functions called comp_funs, providing the components of the diffusion model (i.e., mu_fun, mu_int_fun, x_fun, b_fun, dt_b_fun, nt_fun). These functions are called in the depths of the package and will determine the behavior of the model

If (optional) observed data were passed via obs_data(), the list will contain an entry obs_data. This is a (nested) list with stored response times for the upper and lower boundary and with respect to each condition.

If the model has been evaluated (see re_evaluate_model()), the list will contain...

  • ... the log likelihood; can be addressed via logLik.drift_dm().

  • ... the PDFs of the first passage time; can be addressed via pdfs().

Finally, if arbitrary R objects were passed via ddm_opts(), to access these objects when evaluating the component functions, the list will contain an entry ddm_opts.

Every model also has the attribute b_coding, which summarizes how the boundaries are labeled.

For print.drift_dm(), the supplied drift_dm object x (invisible return).

Details

To modify the entries of a model users can use the replacement methods and the modify_flex_prms() method (see also vignette("dRiftDM", "dRiftDM") and vignette("customize_ddms", "dRiftDM")).

See also

conds(), flex_prms(), prms_solve(), solver(), obs_data(), comp_funs(), b_coding(), coef(), pdfs()

Examples

# Plain call, with default component functions -----------------------------
# create parameter and condition vectors
prms <- c(muc = 4, b = 0.5)
conds <- c("one", "two")

# then call the backbone function (note that we don't provide any component
# functions, so dRiftDM uses the default functions as documented in
# comp_funs())
my_model <- drift_dm(prms_model = prms, conds = conds, subclass = "example")
print(my_model)
#> Class(es): example, drift_dm
#> 
#> Current Parameter Matrix:
#>     muc   b
#> one   4 0.5
#> two   4 0.5
#> 
#> Unique Parameters:
#>     muc b
#> one   1 2
#> two   1 2
#> 
#> Deriving PDFs:
#>   solver: kfe
#>   values: sigma=1, t_max=3, dt=0.001, dx=0.001, nt=3000, nx=2000
#> 
#> Observed Data: NULL