Skip to contents

Estimate the Parameters of a drift_dm Model

Source: R/core_estimate.R
estimate_model.Rd

Find the 'best' parameter settings by fitting a drift_dm models' predicted probability density functions (PDFs) to the observed data stored within the respective object. The fitting procedure is done by minimizing the negative log-likelihood of the model.

Users have three options:

  • Estimate the parameters via Differential Evolution (Default)

  • Estimate the parameters via (bounded) Nelder-Mead

  • Use Differential Evolution followed by Nelder-Mead.

See also vignette("use_ddm_models", "dRiftDM")

Usage

estimate_model(
  drift_dm_obj,
  lower,
  upper,
  verbose = 0,
  use_de_optim = TRUE,
  use_nmkb = FALSE,
  seed = NULL,
  de_n_cores = 1,
  de_control = list(reltol = 1e-08, steptol = 50, itermax = 200, trace = FALSE),
  nmkb_control = list(tol = 1e-06)
)

Arguments

drift_dm_obj

an object inheriting from drift_dm

lower, upper

numeric vectors or lists, specifying the lower and upper bounds on each parameter to be optimized (see Details).

verbose

numeric, indicating the amount of information displayed. If 0, no information is displayed (default). If 1, basic information about the start of Differential Evolution or Nelder-Mead and the final estimation result is given. If 2, each evaluation of the log-likelihood function is shown. Note that verbose is independent of the information displayed by DEoptim::DEoptim.

use_de_optim

logical, indicating whether Differential Evolution via DEoptim::DEoptim should be used. Default is TRUE

use_nmkb

logical, indicating whether Nelder-Mead via dfoptim::nmkb should be used. Default is FALSE.

seed

a single numeric, providing a seed for the Differential Evolution algorithm

de_n_cores

a single numeric, indicating the number of cores to use. Run parallel::detectCores() to see how many cores are available on your machine. Note that it is generally not recommended to use all of your cores as this will drastically slow down your machine for any additional task.

de_control, nmkb_control

lists of additional control parameters passed to DEoptim::DEoptim and dfoptim::nmkb.

Value

the updated drift_dm_obj (with the estimated parameter values, log-likelihood, and probability density functions of the first passage time)

Details

Specifying lower/upper

the function estimate_model provides a flexible way of specifying the search space; identical to specifying the parameter simulation space in simulate_data.drift_dm.

Users have three options to specify the simulation space:

  • Plain numeric vectors (not very much recommended). In this case, lower/upper must be sorted in accordance with the parameters in the flex_prms_obj object that vary for at least one condition (call print(drift_dm_obj) and have a look at the Unique Parameters output)

  • Named numeric vectors. In this case lower/upper have to provide labels in accordance with the parameters that are considered "free" at least once across conditions.

  • The most flexible way is when lower/upper are lists. In this case, the list requires an entry called "default_values" which specifies the named or plain numeric vectors as above. If the list only contains this entry, then the behavior is as if lower/upper were already numeric vectors. However, the lower/upper lists can also provide entries labeled as specific conditions, which contain named (!) numeric vectors with parameter labels. This will modify the value for the upper/lower parameter space with respect to the specified parameters in the respective condition.

Details on Nelder-Mead and Differential Evolution

If both use_de_optim and use_nmkb are TRUE, then Nelder-Mead follows Differential Evolution. Note that Nelder-Mead requires a set of starting parameters for which either the parameter values of drift_dm_obj or the estimated parameter values by Differential Evolution are used.

Default settings will lead DEoptim::DEoptim to stop if the algorithm is unable to reduce the negative log-likelihood by a factor of reltol * (abs(val) + reltol)after steptol = 50 steps, with reltol = 1e-8 (or if the default itermax of 200 steps is reached). Similarly, dfoptim::nmkb will stop if the absolute difference of the log-likelihood between successive iterations is below tol = 1e-6.See DEoptim::DEoptim.control and the details of dfoptim::nmkb for further information.

See also

estimate_model_ids

Examples


# the example uses a simple model and the Nelder-Mead minimization
# routine to ensure that it runs in a couple of seconds.

# get a model and attach data to the model
my_model <- ratcliff_dm(t_max = 1.5, dx = .005, dt = .005)
obs_data(my_model) <- ratcliff_synth_data # this data set comes with dRiftDM


# set the search space
lower <- c(muc = 1, b = 0.2, non_dec = 0.1)
upper <- c(muc = 7, b = 1.0, non_dec = 0.6)

# then fit the data to the model using Nelder-Mead after setting some start
# values
coef(my_model) <- c(muc = 2, b = 0.5, non_dec = 0.4)
my_model <- estimate_model(
  drift_dm_obj = my_model, # (starting values are those set to the model)
  lower = lower, # lower and upper parameter ranges
  upper = upper,
  use_de_optim = FALSE, # don't use the default diff. evol. algorithm
  use_nmkb = TRUE # but Nelder-Mead (faster, but way less robust)
)

# show the result
print(my_model)
#> Class(es): ratcliff_dm, drift_dm
#> 
#> Current Parameter Matrix:
#>        muc     b non_dec
#> null 3.084 0.409   0.302
#> 
#> Unique Parameters:
#>      muc b non_dec
#> null   1 2       3
#> 
#> Deriving PDFs:
#>   solver: kfe
#>   values: sigma=1, t_max=1.5, dt=0.005, dx=0.005, nt=300, nx=400
#> 
#> Observed Data: 300 trials null