Fit Measurement Models using BRMS

Fit a Bayesian multilevel measurement model. Currently implemented are the two-parameter mixture model by Zhang and Luck (2008), the three-parameter mixture model by Bays et al (2009), and three different versions of the Interference Measurement Model (Oberauer et al., 2017). This is a wrapper function for brms::brm, which is used to estimate the model.

Usage

fit_model(
  formula,
  data,
  model,
  prior = NULL,
  chains = 4,
  parallel = getOption("bmm.parallel", FALSE),
  sort_data = getOption("bmm.sort_data", "check"),
  silent = getOption("bmm.silent", 1),
  ...
)

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 bmmmodel object for required argurments.
model: A description of the model to be fitted. This is a call to a bmmmodel 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 get_model_prior() for more help. Not necessary for the default model fitting, but you can provide prior constraints to model parameters
chains: Numeric. Number of Markov chains (defaults to 4)
parallel: Logical; If TRUE, the number of cores on your machine will be detected and brms will fit max(chains, cores) number of chains (specified by the chain argument) in parallel using the parallel package
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), fit_model() 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 viabmm_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.
...: Further arguments passed to brms::brm() or Stan. See the description of brms::brm() for more details

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.

Details

The following models are supported:

IMMabc(resp_err, nt_features, setsize, regex)
IMMbsc(resp_err, nt_features, nt_distances, setsize, regex)
IMMfull(resp_err, nt_features, nt_distances, setsize, regex)
mixture2p(resp_err)
mixture3p(resp_err, nt_features, setsize, regex)
sdmSimple(resp_err)

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

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

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) {
# generate artificial data from the Signal Discrimination Model
dat <- data.frame(y=rsdm(n=2000))

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

# fit the model
fit <- fit_model(formula = ff,
                 data = dat,
                 model = sdmSimple(resp_err = "y"),
                 parallel=T,
                 iter=500,
                 backend='cmdstanr')
}