estimate_model_ids: Fit Multiple Individuals and Save Results

In dRiftDM: Estimating (Time-Dependent) Drift Diffusion Models

Fit Multiple Individuals and Save Results

Description

Provides a wrapper around estimate_model to fit multiple individuals. Each individual will be stored in a folder. This folder will also contain a file drift_dm_fit_info.rds, containing the main arguments of the function call. One call to this function is considered a "fit procedure". Fit procedures can be loaded via load_fits_ids.

Usage

estimate_model_ids(
  drift_dm_obj,
  obs_data_ids,
  lower,
  upper,
  fit_procedure_name,
  fit_path,
  fit_dir = "drift_dm_fits",
  folder_name = fit_procedure_name,
  seed = NULL,
  force_refit = FALSE,
  progress = 2,
  start_vals = NULL,
  ...
)

Arguments

drift_dm_obj	an object inheriting from drift_dm that will be estimated for each individual in obs_data_ids.
obs_data_ids	data.frame, see obs_data. An additional column ID necessary, to identify a single individual.
lower, upper	numeric vectors or lists, providing the parameter space, see estimate_model.
fit_procedure_name	character, providing a name of the fitting procedure. This name will be stored in drift_dm_fit_info.rds to identify the fitting procedure, see also load_fits_ids.
fit_path	character, a path, pointing to the location where all fits shall be stored (i.e., fit_dir will be created in this location). From the user perspective, the path will likely be identical to the current working directory.
fit_dir	character, a directory where (multiple) fitting procedures can be stored. If the directory does not exist yet, it will be created via base::create.dir(fit_dir, recursive = TRUE) in the location provided by fit_path. Default is "drift_dm_fits".
folder_name	character, a folder name for storing all the individual model fits. This variable should just state the name, and should not be a path. Per default folder_name is identical to fit_procedure_name.
seed	numeric, a seed to make the fitting procedure reproducable (only relevant for differential evolution, see estimate_model). Default is NULL which means no seed.
force_refit	logical, if TRUE each individual of a fitting routine will be fitted once more. Default is FALSE which indicates that saved files
progress	numerical, indicating if and how progress shall be displayed. If 0, no progress is shown. If 1, the currently fitted individual is printed out. If 2, a progressbar is shown. Default is 2.
start_vals	optional data.frame, providing values to be set before calling estimate_model. Can be used to control the starting values for each individual when calling Nelder-Mead. Note that this will only have an effect if DEoptim is not used (i.e., when setting use_de_optim = FALSE; see estimate_model). The data.frame must provide a column ID whose entries match the ID column in obs_data_ids, as well as a column for each parameter of the model matching with coef(drift_dm_obj, select_unique = TRUE).
...	additional arguments passed down to estimate_model.

Details

Examples and more information can also be found in vignette("dRiftDM", "dRiftDM").

When developing the fitting routine we had three levels of files/folders in mind:

• In a directory/folder named fit_dir multiple fitting routines can be stored (default is "drift_dm_fits")

• Each fitting routine has its own folder with a name as given by folder_name (e.g., "ulrich_flanker", "ulrich_simon", ...)

• Within each folder, a file called drift_dm_fit_info.rds contains the main information about the function call. That is, the time when last modifying/calling a fitting routine, the lower and upper parameter boundaries, the drift_dm_object that was fitted to each individual, the original data set obs_data_ids, and the identifier fit_procedure_name. In the same folder each individual has its own ⁠<individual>.rds⁠ file containing the modified drift_dm_object.

Value

nothing (NULL; invisibly)

See Also

load_fits_ids

Examples

# We'll provide a somewhat unrealistic example, trimmed for speed.
# In practice, users likely employ more complex models and more individuals.
# However, a more realistic example would take minutes (and maybe even hours)
# and is therefore not suitable for an example.

# Fit the Ratcliff model to synthetic data --------------------------------
# get the model (pre-built by dRiftDM)
model <- ratcliff_dm(t_max = 2.0, dx = .005, dt = .005)

# define an upper and lower boundary for the parameter space
lower <- c(muc = 1, b = 0.2, non_dec = 0.1)
upper <- c(muc = 7, b = 1.0, non_dec = 0.6)

# simulate synthetic data for demonstration purpose
synth_data_prms <- simulate_data(
  model,
  n = 100, k = 2, lower = lower, upper = upper, seed = 1
)
synth_data <- synth_data_prms$synth_data

# finally, call the fit procedure. To increase speed, we'll use the
# Nelder-Mead minimization routine. Note: We'll save the fits in tempdir()
# to avoid writing to a user's file directory without explicit permission.
estimate_model_ids(
  drift_dm_obj = model, # which model (the Ratcliff model)
  obs_data_ids = synth_data, # which data (the synthetic data set)
  lower = lower, # the lower and upper parameter/search space
  upper = upper,
  fit_procedure_name = "example", # a label for the fit procedure
  fit_path = tempdir(), # temporary directory (replace, e.g., with getwd())
  use_nmkb = TRUE, # use Nelder-Mead (fast, but less robust)
  use_de_optim = FALSE # and not differential evolution
)

dRiftDM documentation built on April 3, 2025, 7:48 p.m.