---
title: "TreeBUGS: Advanced MPT Modeling"
author: "Daniel W. Heck, Nina R. Arnold, & Denis Arnold"
date: "`r Sys.Date()`"
number_section: true
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TreeBUGS: Advanced MPT Modeling}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
  
## Advanced MPT Modeling

### A) Including Continuous Covariates

It is possible to sample and estimate correlations of continuous covariates (e.g., age) with the individual MPT parameters. Note that this does not influence the model estimates - the estimated MPT parameters are only used repeatedly to compute a correlation. In contrast, in the latent-trait MPT model, variables can also be included as predictors to account for interindividual variance in MPT parameters, which influences the parameter estimates:
$$\theta_{is} = \Phi(\mu_s + \delta_i + \gamma_i X_i)$$

The following arguments are used to specify the desired covariance structure:

* `covData`: Either a data frame or the path to a .csv data file (columns separated by commas `,`) hat contains the covariates
* Rows: The order of individuals must be identical to the order in the frequency data (`data`)
* Columns: Covariates must habe column names different from the parameters
* TreeBUGS automatically samples all correlations of the theta parameters with the (continuous) covariates in `covData`.
* `corProbit`: whether to correlate MPT parameters on the probability scale (default for beta MPT) or on the latent probit scale (default for latent-trait MPT)
* `predStructure`: Which MPT parameters are predicted by which variables (only for latent-trait MPT)? Either a list or path to a text file in which the assignment of MPT parameters to covariates is coded as follows:
* Syntax: `list("MPT parameter(s) ; covariate label(s)")`
* For instance: `list("Do Dn ; IQ",  "g ; age extraversion")` 
* Multiple combinations are included by separate entries in the list or by separate lines in the text file (redundant combinations are removed automatically)
* No correlations are sampled for variables that serve as predictor

Overall, the code could look like this:

```{r, eval=F}
fitMPT <- traitMPT(
  eqnfile = "2htm.txt",
  data = "data_ind.csv",
  restrictions = list("Dn=Do", "g=.5"),
  covData = "data_covariates.csv",
  corProbit = TRUE,
  predStructure = list("Do ; IQ"), # IQ as predictor for Do=Dn
  ...
)
```

After fitting the model, the results are summarized by `summary(fitMPT)`.



### B) Including Discrete Factors in a Latent-Trait MPT Model

In the latent-trait model, it is possible to include discrete factors as predictor variables, similar as in the general linear model formulation of an ANOVA. Compared to continuous covariates only the following changes:

* New argument `predType`, which is a character vector that assignes each column in `covData` a specific type (i.e., how it is used in `predStructure`). Specifically, predictor variables can be set as
* continuous (`"c"`)
* discrete fixed effect (`"f"`)
* discrete random effect (`"r"`)
* `covData` can have columns with character or factor variables (numeric columns can be specified as factors using `predType`)
* By default, character variables in `covData` are included as fixed effects
* The order of `predType` has to match the column order of `covData`

Note that the same parameter covariance structure is assumed in each group. Given that this assumtion holds, it might result in more reliable parameter estimates than specifying a separate MPT tree for each condition (and thus assuming a separate parameter covariance matrix in each group). An example might be: 

```{r, eval = FALSE}
fitMPT <- traitMPT(
  eqnfile = "2htm.txt",
  data = "data_ind.csv",
  covData = "data_covariates.csv",
  predStructure = list(
    "Do ; factor1",
    "Dn ; factor2"
  ), # discrete factors
  predType = c("c", "c", "f", "r")
)
```

Estimated group estimates for each parameter can be obtained by 

```{r, eval=F}
getGroupMeans(fitMPT)
```


Multiple factors can in principle be included, but currently it is not possible to include interactions. For an introduction to Bayesian ANOVA, see Rouder et al. (2012).


### C) Sampling Transformed Parameters

The argument `transformedParameters` allows to sample parameters that result as some determinstic function of the estimated MPT parameters. This is helpful to test differences between two core MPT parameters or obtain reparameterized versions of the parameters (e.g., for testing order constraints). For instance, the difference between two MPT parameters can be computed using

```{r, eval=FALSE}
transformedParameters <- list(
  "deltaG = G_1-G_2", # difference of parameters
  "G1_larger = G_1>G_2"
) # Bayesian p-value / testing order constraints
```

If the parameters are different, the 95% posterior interval of the parameter `deltaG` should exclude zero. 

Transformed parameters are also helpful if the model contains reparameterizations of order constraints. For instance, if $a<b$ is replaced by $a = s_a * b$ (the standard procedure in multiTree), the EQN file includes the parameters `b` and  `s_a`, but the interest is in `a`, which can be obtained by `transformedParameters = list("a = s_a * b")` . However, note that the priors need to be adjusted in case of such reparameterizations (Heck & Wagenmakers, 2016).

Note the following about the correct specification of transformed parameters:

* transformed parameters require new, unique labels left of the equality sign `=` 
* parameters on the right hand must match with the MPT parameters in the .eqn-file
* transformed parameters are computed and monitored on the group-level only
* to obtain transformed parameters on the individual level, the MCMC samples can be obtained by `fitMPT$runjags$mcmc`


### D) Generate Simulated Data Sets

Simulated data sets are in general useful to check the robustness of the estimators and the sample size requirements. TreeBUGS includes functions to generate data sets of individual frequencies for both the Beta-MPT and the latent-trait MPT model. 

```{r, eval=FALSE}
# beta-MPT
genBeta <- genBetaMPT(
  N = 100, # number of participants
  numItems = c(Target = 250, Lure = 250), # number of responses per tree
  eqnfile = "2htm.eqn", # path to MPT file
  mean = c(Do = .7, Dn = .7, g = .5), # true group-level parameters
  sd = c(Do = .1, Dn = .1, g = .05)
) # SD of individual parameters

# latent-trait MPT
genTrait <- genTraitMPT(
  N = 100, # number of participants
  numItems = c(Target = 250, Lure = 250), # number of responses per tree
  eqnfile = "2htm.eqn", # path to MPT file
  mean = c(Do = .7, Dn = .7, g = .5), # true group-level parameters
  sigma = c(Do = .25, Dn = .25, g = .05), # SD of latent (!) individual parameters
  rho = diag(3)
) # correlation matrix. here: no correlation
```

The resulting data sets contain both the generated frequencies (`genTrait$data`) and the data-generating group and individual parameters (`genTrait$parameters`)