Fit Bayesian Measurement Models

Fit a Bayesian measurement model using brms as a backend interface to Stan.

Usage

bmm(
  formula,
  data,
  model,
  prior = NULL,
  sort_data = getOption("bmm.sort_data", "check"),
  silent = getOption("bmm.silent", 1),
  backend = getOption("brms.backend", NULL),
  file = NULL,
  file_compress = TRUE,
  file_refit = getOption("bmm.file_refit", FALSE),
  ...
)

fit_model(
  formula,
  data,
  model,
  prior = NULL,
  sort_data = getOption("bmm.sort_data", "check"),
  silent = getOption("bmm.silent", 1),
  backend = getOption("brms.backend", NULL),
  ...
)

Arguments

formula: An object of class bmmformula. A symbolic description of the model to be fitted.
data: An object of class data.frame, containing data of all variables used in the model. The names of the variables must match the variable names passed to the bmmodel object for required argurments.
model: A description of the model to be fitted. This is a call to a bmmodel such as mixture3p() function. Every model function has a number of required arguments which need to be specified within the function call. Call supported_models() to see the list of supported models and their required arguments
prior: One or more brmsprior objects created by brms::set_prior() or related functions and combined using the c method or the + operator. See also default_prior() for more help. Not necessary for the default model fitting, but you can provide prior constraints to model parameters
sort_data: Logical. If TRUE, the data will be sorted by the predictor variables for faster sampling. If FALSE, the data will not be sorted, but sampling will be slower. If "check" (the default), bmm() will check if the data is sorted, and ask you via a console prompt if it should be sorted. You can set the default value for this option using global options(bmm.sort_data = TRUE/FALSE/"check")) or via bmm_options(sort_data)
silent: Verbosity level between 0 and 2. If 1 (the default), most of the informational messages of compiler and sampler are suppressed. If 2, even more messages are suppressed. The actual sampling progress is still printed. Set refresh = 0 to turn this off as well. If using backend = "rstan" you can also set open_progress = FALSE to prevent opening additional progress bars.
backend: Character. The backend to use for fitting the model. Can be "rstan" or "cmdstanr". If NULL (the default), "cmdstanr" will be used if the cmdstanr package is installed, otherwise "rstan" will be used. You can set the default backend using global options(brms.backend = "rstan"/"cmdstanr")
file: Either NULL or a character string. If a string, the fitted model object is saved via saveRDS in a file named after the string. The .rds extension is added automatically. If the file already exists, bmm will load and return the saved model object. Unless you specify the file_refit argument as well, the existing files won't be overwritten, you have to manually remove the file in order to refit and save the model under an existing file name. The file name is stored in the bmmfit object for later usage. If the directory of the file does not exist, it will be created.
file_compress: Logical or a character string, specifying one of the compression algorithms supported by saveRDS when saving the fitted model object.
file_refit: Logical or character string. Modifies when the fit stored via the file argument is re-used. Can be set globally for the current R session via the "bmm.file_refit" option (see options). If TRUE or "always", the model is fitted again. If FALSE or "never" (the default), the model saved under the name specified in file will be re-used. If "on_change", the saved model is re-used only if the Stan code, the Stan data, the factor levels of the model variables and the algorithm are unchanged; otherwise the model is fitted again. Because that comparison needs the Stan code and data of the current call, "on_change" runs the full bmm configuration pipeline, standata() and stancode() even when the cached fit is returned: about 0.4 s rather than 0.02 s for an sdm model of oberauer_lin_2017, much cheaper than compiling and sampling, but not free. Only the four things listed above are compared, so sampler settings do not force a refit – in particular control = list(adapt_delta = ), iter, warmup, chains, seed, init and save_pars. Raising adapt_delta after divergent transitions, or rerunning with save_pars(all = TRUE) for loo(), therefore returns the cached fit unchanged; delete the file or pass file_refit = "always" for those. Because the row order of the data reaches the Stan data, "on_change" is most predictable with sort_data fixed to TRUE or FALSE (globally via options(bmm.sort_data = )): under the default "check", answering the interactive prompt differently than last time forces a refit.
...: Further arguments passed to brms::brm() or Stan. See the description of brms::brm() for more details. Unless control names a step_size (stepsize for the rstan backend), bmm adds the starting step size set in bmm_options() to it; the other entries of control are kept.

Value

An object of class brmsfit which contains the posterior draws along with many other useful information about the model. Use methods(class = "brmsfit") for an overview on available methods.

Supported Models

The following models are supported:

cswald(rt, response, links, version)
ddm(rt, response, links)
ezdm(mean_rt, var_rt, n_upper, n_trials, links, version)
imm(resp_error, nt_features, nt_distances, set_size, regex, version)
m3(resp_cats, num_options, choice_rule, version)
mixture2p(resp_error)
mixture3p(resp_error, nt_features, set_size, regex)
sdm(resp_error, version)
sdt_mafc(response, n_trials, m, dist, links)
sdt_ranking(response, m, dist, links)
sdt_yn(response, stimulus, n_trials, dist, links)

Type ?modelname to get information about a specific model, e.g. ?imm

bmmformula syntax

see this online article for a detailed description of the syntax and how it differs from the syntax for brmsformula

Default priors, Stan code and Stan data

For more information about the default priors in bmm and about who to extract the Stan code and data generated by bmm and brms, see the online article.

Miscellaneous

Type help(package=bmm) for a full list of available help topics.

fit_model() is a deprecated alias for bmm().

References

Frischkorn, G. T., & Popov, V. (2023). A tutorial for estimating mixture models for visual working memory tasks in brms: Introducing the Bayesian Measurement Modeling (bmm) package for R. https://doi.org/10.31234/osf.io/umt57

Examples

if (FALSE) { # isTRUE(Sys.getenv("BMM_EXAMPLES"))
# generate artificial data from the Signal Discrimination Model
dat <- data.frame(y = rsdm(2000))

# define formula
ff <- bmmformula(c ~ 1, kappa ~ 1)

# fit the model
fit <- bmm(
  formula = ff,
  data = dat,
  model = sdm(resp_error = "y"),
  cores = 4,
  backend = "cmdstanr"
)
}