In this vignette, we discuss how to use `multilevelcoda`

to specify multilevel models where compositional data are used as
predictors.

The following table outlines the packages used and a brief description of their purpose.

Package | Purpose |
---|---|

`multilevelcoda` |
calculate between and within composition variables, calculate substitutions and plots |

`brms` |
fit Bayesian multilevel models using Stan as a backend |

`bayestestR` |
compute Bayes factors used to compare models |

`doFuture` |
parallel processing to speed up run times |

```
library(multilevelcoda)
#>
#> Attaching package: 'multilevelcoda'
#> The following objects are masked _by_ '.GlobalEnv':
#>
#> psub, sbp
library(brms)
#> Loading required package: Rcpp
#> Loading 'brms' package (version 2.21.0). Useful instructions
#> can be found by typing help('brms'). A more detailed introduction
#> to the package is available through vignette('brms_overview').
#>
#> Attaching package: 'brms'
#> The following object is masked from 'package:stats':
#>
#> ar
library(bayestestR)
library(doFuture)
#> Loading required package: foreach
#> Loading required package: future
options(digits = 3) # reduce number of digits shown
```

For the examples, we make use of three built in datasets:

Dataset | Purpose |
---|---|

`mcompd` |
compositional sleep and wake variables and additional predictors/outcomes (simulated) |

`sbp` |
a pre-specified sequential binary partition, used in calculating compositional predictors |

`psub` |
all possible pairwise substitutions between compositional variables, used for substitution analyses |

The following table shows a few rows of data from
`mcompd`

.

ID | Time | Stress | TST | WAKE | MVPA | LPA | SB | Age | Female |
---|---|---|---|---|---|---|---|---|---|

185 | 1 | 4 | 542 | 99 | 297 | 460 | 41 | 30 | 0 |

185 | 2 | 7 | 458 | 49 | 117 | 653 | 162 | 30 | 0 |

185 | 3 | 3 | 271 | 41 | 489 | 625 | 15 | 30 | 0 |

184 | 12 | 2 | 286 | 53 | 107 | 906 | 89 | 22 | 1 |

184 | 13 | 1 | 281 | 19 | 403 | 611 | 126 | 22 | 1 |

184 | 14 | 0 | 397 | 26 | 40 | 587 | 390 | 22 | 1 |

The following table shows the sequential binary partition being used
in `sbp`

. Columns correspond to the composition variables
(TST, WAKE, MVPA, LPA, SB). Rows correspond to distinct ILR
coordinates.

TST | WAKE | MVPA | LPA | SB |
---|---|---|---|---|

1 | 1 | -1 | -1 | -1 |

1 | -1 | 0 | 0 | 0 |

0 | 0 | 1 | -1 | -1 |

0 | 0 | 0 | 1 | -1 |

The following table shows how all the possible binary substitutions contrasts are setup. Time substitutions work by taking time from the -1 variable and adding time to the +1 variable.

TST | WAKE | MVPA | LPA | SB |
---|---|---|---|---|

1 | -1 | 0 | 0 | 0 |

1 | 0 | -1 | 0 | 0 |

1 | 0 | 0 | -1 | 0 |

1 | 0 | 0 | 0 | -1 |

-1 | 1 | 0 | 0 | 0 |

0 | 1 | -1 | 0 | 0 |

0 | 1 | 0 | -1 | 0 |

0 | 1 | 0 | 0 | -1 |

-1 | 0 | 1 | 0 | 0 |

0 | -1 | 1 | 0 | 0 |

0 | 0 | 1 | -1 | 0 |

0 | 0 | 1 | 0 | -1 |

-1 | 0 | 0 | 1 | 0 |

0 | -1 | 0 | 1 | 0 |

0 | 0 | -1 | 1 | 0 |

0 | 0 | 0 | 1 | -1 |

-1 | 0 | 0 | 0 | 1 |

0 | -1 | 0 | 0 | 1 |

0 | 0 | -1 | 0 | 1 |

0 | 0 | 0 | -1 | 1 |

Compositional data are often expressed as a set of isometric log
ratio (ILR) coordinates in regression models. We can use the
`complr()`

function to calculate both between- and
within-level ILR coordinates for use in subsequent models as
predictors.

*Notes: complr() also calculates total ILR
coordinates to be used as outcomes (or predictors) in models, if the
decomposition into a between- and within-level ILR coordinates was not
desired.*

The `complr()`

function for multilevel data requires four
arguments:

Argument | Description |
---|