Fits a Beta-MPT model (Smith & Batchelder, 2010) based on a standard MPT model file (.eqn) and individual data table (.csv).
betaMPT(
eqnfile,
data,
restrictions,
covData,
transformedParameters,
corProbit = FALSE,
alpha = "dgamma(1, 0.1)T(1,)",
beta = "dgamma(1, 0.1)T(1,)",
n.iter = 20000,
n.adapt = 2000,
n.burnin = 2000,
n.thin = 5,
n.chains = 3,
dic = FALSE,
ppp = 0,
monitorIndividual = TRUE,
modelfilename,
parEstFile,
posteriorFile,
autojags = NULL,
...
)
a list of the class betaMPT
with the objects:
summary
: MPT tailored summary. Use summary(fittedModel)
mptInfo
: info about MPT model (eqn and data file etc.)
runjags
: the object returned from the MCMC sampler.
Note that the object fittedModel$runjags
is an
runjags object, whereas
fittedModel$runjags$mcmc
is a mcmc.list
as used by the coda package (mcmc)
The (relative or full) path to the file that specifies the MPT
model (standard .eqn syntax). Note that category labels must start with a
letter (different to multiTree) and match the column names of data
.
Alternatively, the EQN-equations can be provided within R as a character
value (cf. readEQN
). Note that the first line of an .eqn-file
is reserved for comments and always ignored.
The (relative or full) path to the .csv file with the data (comma separated; category labels in first row). Alternatively: a data frame or matrix (rows=individuals, columns = individual category frequencies, category labels as column names)
Specifies which parameters should be (a) constant (e.g.,
"a=b=.5"
) or (b) constrained to be identical (e.g., "Do=Dn"
)
or (c) treated as fixed effects (i.e., identical for all participants;
"a=b=FE"
). Either given as the path to a text file with restrictions
per row or as a list of restrictions, e.g., list("D1=D2","g=0.5")
.
Note that numbers in .eqn-equations (e.g., d*(1-g)*.50
) are directly
interpreted as equality constraints.
Data that contains covariates, for which correlations with
individual MPT parameters will be sampled. Either the path to a .csv file
(comma-separated: rows=individuals in the same order as data
; first
row must contain covariate labels). Alternatively: a data frame or matrix
(rows=individuals, columns = variables; covariate labels as column names).
Note that in betaMPT
, correlations are computed for discrete
variables that are coded numerically (in traitMPT
, this can be
suppressed by using predType="f"
)
list with parameter transformations that should
be computed based on the posterior samples of the group-level means (e.g.,
for testing parameter differences: list("diffD=Do-Dn")
), or path to
a text file containing one transformation per line. Transformations of
individual-level parameters can also be performed after fitting a model
using transformedParameters
.
whether to use probit-transformed MPT parameters to compute
correlations (probit-values of +Inf
are truncated to
max(5,max(probit))
; similarly for -Inf
). Default for
beta-MPT: MPT parameters are used on the probability scale [0,1].
Hyperprior for the shape parameters \(\alpha\) of the
group-level beta distributions (in JAGS syntax). Default: Truncated gamma
distributions for \(\alpha\) and \(\beta\) with shape 1 and rate 0.1
and truncated to be larger than 1 (see plotPrior). A named vector
can be used to specify separate hyperpriors for each MPT parameter (if
unnamed, the order of parameters is determined by the default order as
shown by readEQN
with paramOrder = TRUE
). Originally,
Smith and Batchelder (2008) used the "WinBUGS-zeros-trick" (available in
TreeBUGS if alpha="zero"
or beta="zero"
), which approximates
uniform priors on the group-level mean and SD (but often results
convergence issues).
Hyperprior for \(\beta\) of group-level distributions, see
alpha
.
Number of iterations per chain (including burnin samples). See
run.jags
for details.
number of adaption samples to adjust MCMC sampler in JAGS. The sampler will be more efficient if it is tuned well. However, MCMC sampling will still give correct results even if the warning appears: "Adaptation incomplete." (this just means that sampling efficiency could be better).
Number of samples for burnin (samples will not be stored and removed from n.iter)
Thinning rate.
number of MCMC chains (sampled in parallel).
whether to compute DIC using
extract.runjags
, which requires additional sampling.
Can also be computed and added after fitting the model by
fittedModel$summary$dic <- runjags::extract(fittedModel$runjags,
"dic")
. As an alternative information criterion, WAIC
can be
computed for fitted models.
number of samples to compute posterior predictive p-value (see
posteriorPredictive
)
whether to store MCMC samples of the MPT
parameters theta
at the individual level (i.e., the random effects).
If FALSE
, it is not possible to perform posterior-predictive checks.
name of the generated JAGS model file. Default is to write this information to the tempdir as required by CRAN standards.
Name of the file to with the estimates should be stored (e.g., "parEstFile.txt")
path to RData-file where to save the model including
MCMC posterior samples (an object named fittedModel
; e.g.,
posteriorFile="mcmc.RData"
)
JAGS first fits the MPT model as usual and then draws MCMC
samples repeatedly until convergence. For this, the function
autoextend.jags
is used with the arguments provided in
autojags
(this can be an empty list, in which case the defaults are
used). Possible arguments for autoextend.jags
are:
list(startburnin = 1000, startsample = 5000, adapt = 2000,
max.time="30m")
(the last of these arguments restricts sampling to 30
minutes, see autoextend.jags).
further arguments to be passed to the JAGS sampling function
(i.e., to run.jags
. Note that reproducible results
are obtained by setting a random seed before fitting a model (i.e.,
set.seed(12345)
).
Daniel W. Heck, Nina R. Arnold, Denis Arnold
Note that, in the Beta-MPT model, correlations of individual MPT
parameters with covariates are sampled. Hence, the covariates do not affect
the estimation of the actual Beta-MPT parameters. Therefore, the correlation
of covariates with the individual MPT parameters can equivalently be
performed after fitting the model using the sampled posterior parameter
values stored in betaMPT$mcmc
Heck, D. W., Arnold, N. R., & Arnold, D. (2018). TreeBUGS: An R package for hierarchical multinomial-processing-tree modeling. Behavior Research Methods, 50, 264–284. tools:::Rd_expr_doi("10.3758/s13428-017-0869-7")
Smith, J. B., & Batchelder, W. H. (2010). Beta-MPT: Multinomial processing tree models for addressing individual differences. Journal of Mathematical Psychology, 54, 167-183. tools:::Rd_expr_doi("10.1016/j.jmp.2009.06.007")
if (FALSE) {
# fit beta-MPT model for encoding condition (see ?arnold2013):
EQNfile <- system.file("MPTmodels/2htsm.eqn", package = "TreeBUGS")
d.encoding <- subset(arnold2013, group == "encoding", select = -(1:4))
fit <- betaMPT(EQNfile, d.encoding,
n.thin = 5,
restrictions = list("D1=D2=D3", "d1=d2", "a=g")
)
# convergence
plot(fit, parameter = "mean", type = "default")
summary(fit)
}
Run the code above in your browser using DataLab