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. Its structure is the backbone of the dRiftDM package and every child of the drift_dm class must have the attributes of the parent class. Typically, users will not want to create an object of drift_dm alone, as its use is very limited. Rather, they will want an object of one of its child classes. See vignette("use_ddm_models", "dRiftDM") for more information on how to create/use/modify child classes.

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 function, which are document 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 additionally contain...

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

  • ... the PDFs of the first passage time; can be addressed via drift_dm_obj$pdfs.

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 vignette("use_ddm_models", "dRiftDM") and vignette("use_ddm_models", "dRiftDM") for more information.

See also

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

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