In the most simple scenario, the following steps are required:

- Define path to existing MPT model file in .eqn format (cf. multiTree; Moshagen, 2010)
- Define path to data set with individual frequencies (.csv file: comma separated, rows=persons, columns=labeled categories)
- Call one of the fitting functions
`betaMPT`

or`traitMPT`

(examples below) - Check convergence of MCMC chains
- Summarize and plot results

In the following, these steps are explained in more detail. Note that TreeBUGS requires a recent version of the software JAGS (https://mcmc-jags.sourceforge.io/).

The model needs to be passed in the standard .eqn file format (e.g., as in multiTree; Moshagen, 2010). As an example, consider the most simple two-high-threshold model (2HTM), each line defines a single processing path containing tree label, category label, and model equations:

```
#####Title: 2HTM
Target Hit Do
Target Hit (1-Do)*g
Target Miss (1-Do)*(1-g)
Lure FA (1-Dn)*g
Lure CR (1-Dn)*(1-g)
Lure CR Dn
```

Note that category labels (e.g., hit, miss,…) must start with a
letter (different to multiTree or HMMTree) and match the column names of
. The model equations require the multiplication sign `*`

and
parameters should not be summarized, e.g., by `a^2*(1-a)`

. As
an input for TreeBUGS, the model file (e.g., `"2htm.txt"`

)
needs to be saved in the current working directory. Otherwise, the
relative or absolute path to the file must be specified (e.g.,
`models/2htm.txt`

). To check how TreeBUGS interprets a given
.eqn-file, use:

```
readEQN(file = "pathToFile.eqn", # relative or absolute path
restrictions = list("Dn=Do"), # equality constraints
paramOrder = TRUE) # show parameter order
```

Equality restrictions on the MPT parameters can either be provided in a list:

`= list("Dn=Do", "g=0.5") restrictions `

or by a path to a text file on the hard drive (e.g.,
`restrictions="pathToFile.txt"`

) that contains the equality
constraints, one per row:

```
Dn=Do
g=0.5
```

Data can be loaded from a comma-separated text file (.csv) in the following format:

```
Hit, Miss, FA, CR
20, 10, 5, 25
13, 7, 9, 21
15, 5, 6, 14
.....
```

Note that the first line contains the category labels, which must
match the category labels from the .eqn-file. The remaining rows contain
individual frequencies. Similarly as for the .eqn file, the path to the
data file can either be specified as `data_ind.csv`

if it is
in the current working directory, or as an relative or absolute path
(e.g., `"C:/models/data_ind.csv"`

).

When using TreeBUGS within R, a data.frame or matrix with appropriate column names that match the category labels can be provided.

An hierarchical **Beta-MPT model** is fitted with the
following code:

```
# load the package:
library(TreeBUGS)
# fit the model:
<- betaMPT(
fitHierarchicalMPT eqnfile="2htm.txt", # .eqn file
data="data_ind.csv", # individual data
restrictions=list("Dn=Do"), # parameter restrictions (or path to file)
### optional MCMC input:
n.iter = 20000, # number of iterations
n.burnin = 5000, # number of burnin samples that are removed
n.thin = 5, # thinning rate of removing samples
n.chains = 3 # number of MCMC chains (run in parallel)
)
```

A latent-trait model is fitted similarly by replacing
`betaMPT`

by `traitMPT`

.

The functions `betaMPT`

and `traitMPT`

return a
list that includes the original samples from the MCMC sampler for
convergence checks. The MCMC samples are stored in
`fittedModel$runjags$mcmc`

as an `mcmc.list`

object (see the package for an overview of convergence diagniostics).
TreeBUGS provides a handy wrapper to access the most important plotting
functions:

```
# Default: Traceplot and density
plot(fitHierarchicalMPT, # fitted model
parameter ="mean" # which parameter to plot
)# further arguments are passed to ?plot.mcmc.list
# Auto-correlation plots:
plot(fitHierarchicalMPT, parameter = "mean", type = "acf")
# Gelman-Rubin plots:
plot(fitHierarchicalMPT, parameter = "mean", type = "gelman")
```

See and for further convergence statistics and plots. Note that inferences from the model can be invalid if the Markov-Chain Monte-Carlo (MCMC) sampler did not converge!

TreeBUGS produces an MPT-tailored summary of parameter estimates and convergence statistics:

- Information about the parameter posterior distribution: Mean, SD, Median, 2.5% and 97.5% quantiles
- Convergence: \(\hat R\)-Statistic (should be close to 1.00 for all parameters, e.g., \(\hat R < 1.05\)) and number of effective samples when accounting for auto-correlation (should be large)

To obtain the summary after fitting the model, simply use:

`summary(fitHierarchicalMPT)`

The following functions allow to plot parameter estimates, distributions, goodness of fit, and raw frequencies:

```
plotParam(fitHierarchicalMPT, # estimated parameters
includeIndividual=TRUE # whether to plot individual estimates
)plotDistribution(fitHierarchicalMPT) # estimated hierarchical parameter distribution
plotFit(fitHierarchicalMPT) # observed vs. predicted mean frequencies
plotFit(fitHierarchicalMPT, stat = "cov") # observed vs. predicted covariance
plotFreq(fitHierarchicalMPT) # individual and mean raw frequencies per tree
plotPriorPost(fitHierarchicalMPT) # comparison of prior/posterior (group level parameters)
```

Parameter estimates (posterior mean, median, SD) can be extracted and saved to a file by using:

```
# matrix for further use within R:
<- getParam(fitHierarchicalMPT, parameter="theta",
tt stat="mean")
tt
# save complete summary of individual estimates to file:
getParam(fitHierarchicalMPT, parameter = "theta",
stat = "summary", file = "parameter.csv")
```

Erdfelder, E., Auer, T.-S., Hilbig, B. E., Assfalg, A., Moshagen, M., & Nadarevic, L. (2009). Multinomial processing tree models: A review of the literature. Journal of Psychology, 217, 108–124. https://doi.org/10.1027/0044-3409.217.3.108

Heck, D. W., & Wagenmakers, E. J. (2016). Adjusted priors for Bayes factors involving reparameterized order constraints. Journal of Mathematical Psychology, 73, 110–116. https://doi.org/10.1016/j.jmp.2016.05.004

Klauer, K. C. (2010). Hierarchical multinomial processing tree models: A latent-trait approach. Psychometrika, 75, 70–98. https://doi.org/10.1007/s11336-009-9141-0

Matzke, D., Dolan, C. V., Batchelder, W. H., & Wagenmakers, E.-J. (2015). Bayesian estimation of multinomial processing tree models with heterogeneity in participants and items. Psychometrika, 80, 205–235. https://doi.org/10.1007/s11336-013-9374-9

Moshagen, M. (2010). multiTree: A computer program for the analysis of multinomial processing tree models. Behavior Research Methods, 42, 42–54. https://doi.org/10.3758/BRM.42.1.42

Smith, J. B., & Batchelder, W. H. (2010). Beta-MPT: Multinomial processing tree models for addressing individual differences. Journal of Mathematical Psychology, 54, 167–183. https://doi.org/10.1016/j.jmp.2009.06.007