fit.emc {EMC2} | R Documentation |
General purpose function to estimate models specified in EMC2.
## S3 method for class 'emc'
fit(
emc,
stage = NULL,
iter = 1000,
stop_criteria = NULL,
report_time = TRUE,
p_accept = 0.8,
step_size = 100,
verbose = TRUE,
verboseProgress = FALSE,
fileName = NULL,
particles = NULL,
particle_factor = 50,
cores_per_chain = 1,
cores_for_chains = length(emc),
max_tries = 20,
n_blocks = 1,
...
)
fit(emc, ...)
emc |
An emc object created with |
stage |
A string. Indicates which stage to start the run from, either |
iter |
An integer. Indicates how many iterations to run in the sampling stage. |
stop_criteria |
A list. Defines the stopping criteria and for which types of parameters these should hold. See the details and examples section. |
report_time |
Boolean. If |
p_accept |
A double. The target acceptance probability of the MCMC process. This fine-tunes the width of the search space to obtain the desired acceptance probability. Defaults to .8 |
step_size |
An integer. After each step, the stopping requirements as specified
by |
verbose |
Logical. Whether to print messages between each step with the current status regarding the |
verboseProgress |
Logical. Whether to print a progress bar within each step or not.
Will print one progress bar for each chain and only if |
fileName |
A string. If specified, will auto-save emc object at this location on every iteration. |
particles |
An integer. How many particles to use, default is |
particle_factor |
An integer. |
cores_per_chain |
An integer. How many cores to use per chain. Parallelizes across
participant calculations. Only available on Linux or Mac OS. For Windows, only
parallelization across chains ( |
cores_for_chains |
An integer. How many cores to use across chains.
Defaults to the number of chains. The total number of cores used is equal to |
max_tries |
An integer. How many times should it try to meet the finish
conditions as specified by |
n_blocks |
An integer. Number of blocks. Will block the parameter chains such that they are updated in blocks. This can be helpful in extremely tough models with a large number of parameters. |
... |
Additional optional arguments |
stop_criteria
is either a list of lists with names of the stages,
or a single list in which case its assumed to be for the sample stage
(see examples).
The potential stop criteria to be set are:
selection
(character vector): For which parameters the stop_criteria
should hold
mean_gd
(numeric): The mean Gelman-Rubin diagnostic across all parameters in the selection
max_gd
(numeric): The max Gelman-Rubin diagnostic across all parameters in the selection
min_unique
(integer): The minimum number of unique samples in the MCMC chains across all parameters in the selection
min_es
(integer): The minimum number of effective samples across all parameters in the selection
omit_mpsrf
(Boolean): Whether to include the multivariate point-scale reduction factor in the Gelman-Rubin diagnostic. Default is FALSE
.
iter
(integer): The number of MCMC samples to collect.
The estimation is performed using particle-metropolis within-Gibbs sampling. For sampling details see:
Gunawan, D., Hawkins, G. E., Tran, M.-N., Kohn, R., & Brown, S. (2020). New estimation approaches for the hierarchical linear ballistic accumulator model. Journal of Mathematical Psychology ,96, 102368. doi.org/10.1016/j.jmp.2020.102368
Stevenson, N., Donzallaz, M. C., Innes, R. J., Forstmann, B., Matzke, D., & Heathcote, A. (2024). EMC2: An R Package for cognitive models of choice. doi.org/10.31234/osf.io/2e4dq
An emc object
## Not run:
# First define a design
design_DDMaE <- design(data = forstmann,model=DDM,
formula =list(v~0+S,a~E, t0~1, s~1, Z~1, sv~1, SZ~1),
constants=c(s=log(1)))
# Then make the emc object, we've omitted a prior here for brevity so default priors will be used.
emc_forstmann <- make_emc(forstmann, design)
# With the emc object we can start sampling by simply calling fit
emc_forstmann <- fit(emc_forstmann, fileName = "intermediate_save_location.RData")
# For particularly hard models it pays off to increase the ``particle_factor``
# and, although to a lesser extent, lower ``p_accept``.
emc_forstmann <- fit(emc_forstmann, particle_factor = 100, p_accept = .6)
# Example of how to use the stop_criteria:
emc_forstmann <- fit(emc_forstmann, stop_criteria = list(mean_gd = 1.1, max_gd = 1.5,
selection = c('alpha', 'sigma2'), omit_mpsrf = TRUE, min_es = 1000))
# In this case the stop_criteria are set for the sample stage, which will be
# run until the mean_gd < 1.1, the max_gd < 1.5 (omitting the multivariate psrf)
# and the effective sample size > 1000,
# for both the individual-subject parameters ("alpha")
# and the group-level variance parameters.
# For the unspecified stages in the ``stop_criteria`` the default values
# are assumed which are found in Stevenson et al. 2024 <doi.org/10.31234/osf.io/2e4dq>
# Alternatively, you can also specify the stop_criteria for specific stages by creating a
# nested list
emc_forstmann <- fit(emc_forstmann, stop_criteria = list("burn" = list(mean_gd = 1.1, max_gd = 1.5,
selection = c('alpha')), "adapt" = list(min_unique = 100)))
## End(Not run)