Type:	Package
Title:	Estimate Bayesian Multilevel Models for Compositional Data
Version:	1.3.2
Date:	2025-05-22
URL:	https://florale.github.io/multilevelcoda/, https://github.com/florale/multilevelcoda
BugReports:	https://github.com/florale/multilevelcoda/issues
Description:	Implement Bayesian multilevel modelling for compositional data. Compute multilevel compositional data and perform log-ratio transforms at between and within-person levels, fit Bayesian multilevel models for compositional predictors and outcomes, and run post-hoc analyses such as isotemporal substitution models. References: Le, Stanford, Dumuid, and Wiley (2025) <doi:10.1037/met0000750>, Le, Dumuid, Stanford, and Wiley (2024) <doi:10.48550/arXiv.2411.12407>.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
Depends:	R (≥ 4.0.0)
Imports:	stats, data.table (≥ 1.12.0), compositions, brms, bayestestR, extraoperators, ggplot2, foreach, future, doFuture, abind, graphics, shiny, shinystan, loo, bayesplot, emmeans, posterior, plotly, hrbrthemes, htmltools, bslib, DT, fs
Suggests:	testthat (≥ 3.0.0), covr, withr, knitr, rmarkdown, lme4, cmdstanr (≥ 0.5.0)
Config/testthat/edition:	3
Config/testthat/parallel:	true
Additional_repositories:	https://mc-stan.org/r-packages/
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-05-25 05:31:14 UTC; florale
Author:	Flora Le [aut, cre], Joshua F. Wiley [aut]
Maintainer:	Flora Le <floralebui@gmail.com>
Repository:	CRAN
Date/Publication:	2025-05-25 06:00:02 UTC

Extract Variance and Correlation Components

Description

Calculates the estimated standard deviations, correlations and covariances of the group-level terms of the brmsfit object in a brmcoda object.

Usage

## S3 method for class 'brmcoda'
VarCorr(x, ...)

Arguments

Value

A list of lists (one per grouping factor), each with three elements: a matrix containing the standard deviations, an array containing the correlation matrix, and an array containing the covariance matrix with variances on the diagonal.

See Also

VarCorr.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  VarCorr(m)
}

Extract Compositional Data from complr object.

Description

Extract amounts and compositions in conventional formats as data.frames, matrices, or arrays.

Usage

## S3 method for class 'complr'
as.data.frame(x, row.names = NULL, optional = TRUE, ...)

## S3 method for class 'complr'
as.matrix(x, ...)

Arguments

Bayes Factors from Marginal Likelihoods

Description

Compute Bayes factors from marginal likelihoods

Usage

## S3 method for class 'brmcoda'
bayes_factor(x1, x2, ...)

Arguments

See Also

bayes_factor.brmsfit

Fit Bayesian generalised (non-)linear multilevel compositional model via full Bayesian inference

Description

Fit a brm model with multilevel ILR coordinates

Usage

brmcoda(complr, formula, ...)

Arguments

Value

A brmcoda with two elements

Examples

if(requireNamespace("cmdstanr")){
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID")
  
  # inspects ILRs before passing to brmcoda
  names(cilr$between_logratio)
  names(cilr$within_logratio)
  names(cilr$logratio)
  
  # model with compositional predictor at between and within-person levels
  m1 <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                   wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  # model with compositional outcome
  m2 <- brmcoda(complr = cilr,
                formula = mvbind(ilr1, ilr2, ilr3, ilr4) ~ Stress + Female + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  }

Between-person Simple Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) at between level using a single reference composition (e.g., compositional mean at sample level). It is recommended that users run substitution model using the substitution function.

Usage

bsub(
  object,
  delta,
  basesub,
  summary = TRUE,
  ref = "grandmean",
  level = "between",
  weight = "equal",
  aorg = TRUE,
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){
cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

# model with compositional predictor at between and between-person levels
m <- brmcoda(complr = cilr, 
             formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 + 
                                wilr1 + wilr2 + wilr3 + wilr4 + Female + (1 | ID), 
             chain = 1, iter = 500,
             backend = "cmdstanr")
subm <- bsub(object = m, basesub = psub, delta = 5)
}

Between-person Average Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) at between level using cluster mean (e.g., compositional mean at individual level) as reference composition. It is recommended that users run substitution model using the substitution function.

Usage

bsubmargins(
  object,
  delta,
  basesub,
  summary = TRUE,
  ref = "clustermean",
  level = "between",
  weight = "proportional",
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){
cilr <- complr(data = mcompd[ID %in% 1:10, .SD[1:3], by = ID], sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

m <- brmcoda(complr = cilr, 
             formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 + wilr1 + 
                                wilr2 + wilr3 + wilr4 + Female + (1 | ID), 
             chains = 1, iter = 500,
             backend = "cmdstanr")
             
subm <- bsubmargins(object = m, basesub = psub, delta = 5)
}

Build Base Pairwise Substitution

Description

Make a data set of all possible pairwise substitution of a composition which can be used as the base for substitution models.

Usage

build.basesub(parts, comparison = NULL)

Arguments

Value

A data table of all possible pairwise substitution.

Examples

ps1 <- build.basesub(parts = c("TST", "WAKE", "MVPA", "LPA", "SB"))
print(ps1)

ps2 <- build.basesub(c("WAKE", "MVPA", "LPA", "SB"), comparison = "one-to-all")
print(ps2)

Reference Grid for substitution model.

Description

Build a dataset for fitted.brmcoda used in substitution model

Usage

build.rg(object, ref, level, weight, fill = FALSE)

Arguments

Value

A reference grid consisting of a combination of covariates in brmcoda

Build Sequential Binary Partition

Description

Build a default sequential binary partition for complr object. The default sequential binary partition is a pivot balance that allows the effect of this first balance coordinate to be interpreted as the change in the prediction for the dependent variable when that given part increases while all remaining parts decrease by a common proportion.

Usage

build.sbp(parts)

Arguments

Value

A matrix sequential binary partition.

Examples

sbp1 <- build.sbp(parts = c("TST", "WAKE", "MVPA", "LPA", "SB"))
print(sbp1)

sbp2 <- build.sbp(c("WAKE", "MVPA", "LPA", "SB"))
print(sbp2)

Model Coefficients

Description

Extract model coefficients, which are the sum of population-level effects and corresponding group-level effects of the brmsfit object in a brmcoda object.

Usage

## S3 method for class 'brmcoda'
coef(object, ...)

Arguments

Value

A list of 3D arrays (one per grouping factor). If summary is TRUE, the 1st dimension contains the factor levels, the 2nd dimension contains the summary statistics (see posterior_summary), and the 3rd dimension contains the group-level effects. If summary is FALSE, the 1st dimension contains the posterior draws, the 2nd dimension contains the factor levels, and the 3rd dimension contains the group-level effects.

See Also

coef.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  ## extract population and group-level coefficients separately
  fixef(m)
  ranef(m)
  
  ## extract combined coefficients
  coef(m)
}

Indices from a (dataset of) Multilevel Composition(s) (deprecated.)

Description

Indices from a (dataset of) Multilevel Composition(s) (deprecated.)

Usage

compilr(...)

Arguments

Value

A complr object with at least the following elements.

See Also

complr

Indices from a (dataset of) Multilevel Composition(s)

Description

Compute sets of compositions and log ratio transformation for multilevel compositional data

Usage

complr(data, parts, sbp = NULL, total = 1, idvar = NULL, transform = "ilr")

Arguments

Details

The ilr-transform maps the D-part compositional data from the simplex into non-overlapping subgroups in the (D-1)-dimension Euclidean space isometrically by using an orthonormal basis, thereby preserving the compositional properties and yielding a full-rank covariance matrix. ilr transformation should be preferred. However, the alr and clr are alternatives. The alr-transform maps a D-part composition in the Aitchison-simplex non-isometrically to a (D-1)-dimension Euclidian vectors, commonly treating the last part as the common denominator of the others. alr transformation does not rely on distance which breaks the constraint of compositional data. clr-transform maps a D-part composition in the Aitchison-simplex isometrically to a D-dimensional Euclidian vector subspace. clr transformation is not injetive, resulting in singular covariance matrices.

Value

A complr object with at least the following elements.

Examples

cilr <- complr(data = mcompd,
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                idvar = "ID", total = 1440)
str(cilr)

calr <- complr(data = mcompd, sbp = sbp,
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                idvar = "ID",
                transform = "alr")
str(calr)

cclr <- complr(data = mcompd, sbp = sbp,
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                idvar = "ID",
                 transform = "clr")
str(cclr)

cilr_wide <- complr(data = mcompd[!duplicated(ID)], sbp = sbp,
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"))
str(cilr_wide)

Constructor function for substitution class.

Description

Constructor function for substitution class.

Usage

create_substitution(
  between_simple_sub,
  within_simple_sub,
  simple_sub,
  between_avg_sub,
  within_avg_sub,
  avg_sub,
  delta,
  ref,
  level,
  weight,
  parts,
  aorg
)

Arguments

Value

An object of class substitution

See Also

substitution

Extract Diagnostic Quantities from brmsfit Models in brmcoda

Description

Extract Diagnostic Quantities from brmsfit Models in brmcoda

Usage

## S3 method for class 'brmcoda'
log_posterior(object, ...)

## S3 method for class 'brmcoda'
nuts_params(object, ...)

## S3 method for class 'brmcoda'
rhat(x, ...)

## S3 method for class 'brmcoda'
neff_ratio(object, ...)

Arguments

Value

The exact form of the output depends on the method.

See Also

log_posterior.brmsfit

nuts_params.brmsfit

rhat.brmsfit

neff_ratio.brmsfit

Index brmcoda objects

Description

Index brmcoda objects

Usage

## S3 method for class 'brmcoda'
variables(x, ...)

## S3 method for class 'brmcoda'
nvariables(x, ...)

## S3 method for class 'brmcoda'
niterations(x)

## S3 method for class 'brmcoda'
nchains(x)

## S3 method for class 'brmcoda'
ndraws(x)

Arguments

See Also

variables.brmsfit

nvariables.brmsfit

niterations.brmsfit

nchains.brmsfit

ndraws.brmsfit

Expected Values of the Posterior Predictive Distribution

Description

Compute posterior draws of the expected value of the posterior predictive distribution of a brmsfit model in the brmcoda object. Can be performed for the data used to fit the model (posterior predictive checks) or for new data. By definition, these predictions have smaller variance than the posterior predictions performed by the predict.brmcoda method. This is because only the uncertainty in the expected value of the posterior predictive distribution is incorporated in the draws computed by fitted while the residual error is ignored there. However, the estimated means of both methods averaged across draws should be very similar.

Usage

## S3 method for class 'brmcoda'
fitted(object, scale = c("linear", "response"), summary = TRUE, ...)

Arguments

Value

An array of predicted mean response values. If summary = FALSE the output resembles those of posterior_epred.brmsfit.

If summary = TRUE the output depends on the family: For categorical and ordinal families, the output is an N x E x C array, where N is the number of observations, E is the number of summary statistics, and C is the number of categories. For all other families, the output is an N x E matrix. The number of summary statistics E is equal to 2 + length(probs): The Estimate column contains point estimates (either mean or median depending on argument robust), while the Est.Error column contains uncertainty estimates (either standard deviation or median absolute deviation depending on argument robust). The remaining columns starting with Q contain quantile estimates as specified via argument probs.

In multivariate models, an additional dimension is added to the output which indexes along the different response variables.

See Also

fitted.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  ## compute composition and ilr coordinates
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                 idvar = "ID", total = 1440)
  
  ## fit a model
  m1 <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                  wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  ## compute expected predictions
  epred <- fitted(m1)
  head(epred)
  
  ## fit a model with compositional outcome
  m2 <- brmcoda(complr = cilr,
                formula = mvbind(ilr1, ilr2, ilr3, ilr4) ~ Stress + Female + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  ## expected predictions on compositional scale
  epredcomp <- fitted(m2, scale = "response")
  head(epredcomp)
}

Population-Level Estimates

Description

Extract the population-level ('fixed') effects from the brmsfit object in a brmcoda object.

Usage

## S3 method for class 'brmcoda'
fixef(object, ...)

Arguments

Value

If summary is TRUE, a matrix returned by posterior_summary for the population-level effects. If summary is FALSE, a matrix with one row per posterior draw and one column per population-level effect.

See Also

fixef.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  ## fit a model
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  ## extract population-Level coefficients
  fixef(m)
}

Helper functions used only internally to estimate substitution model

Description

Helper functions used only internally to estimate substitution model

Checks if argument is a brmcoda object

Description

Checks if argument is a brmcoda object

Usage

is.brmcoda(x)

Arguments

Checks if argument is a complr object

Description

Checks if argument is a complr object

Usage

is.complr(x)

Arguments

Checks if argument is a substitution object

Description

Checks if argument is a substitution object

Usage

is.substitution(x)

Arguments

Interface to shinystan

Description

Provide an interface to shinystan for models fitted with brms

Usage

## S3 method for class 'brmcoda'
launch_shinystan(object, ...)

Arguments

Value

An S4 shinystan object

See Also

launch_shinystan

Efficient approximate leave-one-out cross-validation (LOO)

Description

Perform approximate leave-one-out cross-validation based on the posterior likelihood using the loo package. For more details see loo.

Usage

## S3 method for class 'brmcoda'
loo(x, ...)

Arguments

Value

If just one object is provided, an object of class loo. If multiple objects are provided, an object of class loolist.

See Also

loo.brmsfit

MCMC Plots Implemented in bayesplot

Description

Call MCMC plotting functions implemented in the bayesplot package.

Usage

## S3 method for class 'brmcoda'
mcmc_plot(object, ...)

Arguments

Value

A ggplot object that can be further customized using the ggplot2 package.

See Also

mcmc_plot.brmsfit

Examples

## Not run: 
cilr <- complr(data = mcompd, sbp = sbp,
        parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID")

# model with compositional predictor at between and within-person levels
fit <- brmcoda(complr = cilr,
               formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                 wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
               chain = 1, iter = 500)
mcmc_plot(fit)

## End(Not run)

Multilevel Compositional Data

Description

A simulated dataset containing multiple days of compositional data.

Usage

mcompd

Format

A data table containing 10 variables.

ID

A unique identifier for each individual

Time

Recurrence time of repeated measures by individual

Stress

Self report stress measures on a 0 to 10 scale — repeated measure

TST

Total Sleep Time (minutes) — repeated measure

WAKE

Wake time while in bed, trying to sleep (minutes) — repeated measure

MVPA

Moderate to Vigorous Physical Activity (minutes) — repeated measure

LPA

Light Physical Activity (minutes) — repeated measure

SB

Sedentary Behavior (minutes) — repeated measure

Age

Age in years — baseline measure only

Female

Binary: whether participants identified as female (1) or not (0) — baseline measure only

Mean amounts and mean compositions presented in a complr object.

Description

Mean amounts and mean compositions presented in a complr object.

Usage

## S3 method for class 'complr'
mean(x, weight = c("equal", "proportional"), ...)

Arguments

Examples

cilr <- complr(data = mcompd, sbp = sbp, 
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), 
                idvar = "ID")
mean(cilr)

Extracting the Model Frame from a Formula or Fit from brmcoda object

Description

Extracting the Model Frame from a Formula or Fit from brmcoda object

Usage

## S3 method for class 'brmcoda'
model.frame(formula, ...)

Arguments

multilevelcoda Simulation Study Results

Description

Provide the full results for a simulation study testing the performance of multilevelcoda

Usage

multilevelcoda_sim()

Value

An S4 shiny object

Extract Number of Observations from brmcoda object

Description

Extract Number of Observations from brmcoda object

Usage

## S3 method for class 'brmcoda'
nobs(object, ...)

Arguments

Create a matrix of output plots from a brmcoda's brmsfit object

Description

A pairs method that is customized for MCMC output.

Usage

## S3 method for class 'brmcoda'
pairs(x, ...)

Arguments

See Also

pairs.brmsfit

Examples

## Not run: 
cilr <- complr(data = mcompd, sbp = sbp,
        parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID")

# model with compositional predictor at between and within-person levels
fit <- brmcoda(complr = cilr,
               formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                 wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
               chain = 1, iter = 500)
pairs(fit)

## End(Not run)

Estimate pivot balance coordinates

Description

Estimate pivot balance coordinates

Usage

pivot_coord(object, summary = TRUE, method = c("rotate", "refit"), ...)

Arguments

Value

A list of brmcoda for each pivot balance coordinate.

Examples

if(requireNamespace("cmdstanr")){
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID",
                 total = 1440)
  
  # inspects ILRs before passing to brmcoda
  names(cilr$between_logratio)
  names(cilr$within_logratio)
  names(cilr$logratio)
  
  # model with compositional predictor at between and within-person levels
  m <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                   wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  m_pivot_coord <- pivot_coord(m)
  summary(m_pivot_coord)
  }

Estimate pivot balance coordinates by refitting model.

Description

Estimate pivot balance coordinates by refitting model.

Usage

pivot_coord_refit(object, ...)

Arguments

Value

A list of brmcoda for each pivot balance coordinate.

Examples

if(requireNamespace("cmdstanr")){
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID",
                 total = 1440)
  
  m <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                   wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  m_pivot_coord_refit <- pivot_coord_refit(m)
  summary(m_pivot_coord_refit)
  }

Estimate pivot balance coordinates by rotating sequential binary partition.

Description

Estimate pivot balance coordinates by rotating sequential binary partition.

Usage

pivot_coord_rotate(object, summary = TRUE, ...)

Arguments

Value

A list of brmcoda for each pivot balance coordinate.

Examples

if(requireNamespace("cmdstanr")){
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID",
                 total = 1440)
  
  m <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                   wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  m_pivot_coord_rotate <- pivot_coord_rotate(m)
  summary(m_pivot_coord_rotate)
  
  m_pivot_coord_raw <-  pivot_coord_rotate(m, summary = FALSE)
  posterior::summarise_draws(posterior::as_draws_array(m_pivot_coord_raw$output))
  }

Trace and Density Plots for MCMC Draws plot

Description

Make a plot of brmcoda model results.

Usage

## S3 method for class 'brmcoda'
plot(x, ...)

Arguments

Value

An invisible list of gtable objects.

See Also

plot.brmsfit

Examples

## Not run: 
cilr <- complr(data = mcompd, sbp = sbp,
        parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID")

# model with compositional predictor at between and within-person levels
fit <- brmcoda(complr = cilr,
               formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                 wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
               chain = 1, iter = 500)
plot(fit)

## End(Not run)

Substitution Plot

Description

Make a plot of substitution model results.

Usage

## S3 method for class 'substitution'
plot(x, to, ref, level, ...)

Arguments

Value

A ggplot graph object showing the estimated difference in outcome when each pair of compositional variables are substituted for a specific time.

Posterior Predictive Checks for brmcoda Objects

Description

Perform posterior predictive checks with the help of the bayesplot package.

Usage

## S3 method for class 'brmcoda'
pp_check(object, ...)

Arguments

See Also

pp_check.brmsfit

Draws from the Posterior Predictive Distribution

Description

Compute posterior draws of the posterior predictive distribution of a brmsfit model in the brmcoda object. Can be performed for the data used to fit the model (posterior predictive checks) or for new data. By definition, these draws have higher variance than draws of the expected value of the posterior predictive distribution computed by fitted.brmcoda. This is because the residual error is incorporated in posterior_predict. However, the estimated means of both methods averaged across draws should be very similar.

Usage

## S3 method for class 'brmcoda'
predict(object, scale = c("linear", "response"), summary = TRUE, ...)

Arguments

Value

An array of predicted response values. If summary = FALSE the output resembles those of posterior_predict.brmsfit.

If summary = TRUE the output depends on the family: For categorical and ordinal families, the output is an N x C matrix, where N is the number of observations, C is the number of categories, and the values are predicted category probabilities. For all other families, the output is a N x E matrix where E = 2 + length(probs) is the number of summary statistics: The Estimate column contains point estimates (either mean or median depending on argument robust), while the Est.Error column contains uncertainty estimates (either standard deviation or median absolute deviation depending on argument robust). The remaining columns starting with Q contain quantile estimates as specified via argument probs.

See Also

predict.brmsfit

Examples

if(requireNamespace("cmdstanr")){
  ## fit a model
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                 idvar = "ID", total = 1440)
  
  m1 <- brmcoda(complr = cilr,
                formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                  wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  ## predicted responses
  pred <- predict(m1)
  head(pred)
  
  ## fit a model with compositional outcome
  m2 <- brmcoda(complr = cilr,
                formula = mvbind(ilr1, ilr2, ilr3, ilr4) ~ Stress + Female + (1 | ID),
                chain = 1, iter = 500,
                backend = "cmdstanr")
  
  ## predicted responses on compositional scale
  predcomp <- predict(m2, scale = "linear")
  head(predcomp)
}

Print a Summary for a fitted brmsfit model in a brmcoda object

Description

Print a Summary for a fitted brmsfit model in a brmcoda object

Usage

## S3 method for class 'brmcoda'
print(x, ...)

Arguments

See Also

summary.brmcoda

Examples

if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
 print(m)
}

Print a Summary for a complr object

Description

Print a Summary for a complr object

Usage

## S3 method for class 'complr'
print(x, ...)

Arguments

See Also

summary.complr

Examples

cilr <- complr(data = mcompd, sbp = sbp, 
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), 
                idvar = "ID")
print(cilr)

Print a Summary for a substitution object

Description

Print a Summary for a substitution object

Usage

## S3 method for class 'substitution'
print(x, ...)

Arguments

See Also

summary.substitution

Examples

if(requireNamespace("cmdstanr")){
  ## fit a model with compositional predictor at between and between-person levels
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  subm <- substitution(object = m, delta = 5)
  print(subm)
}

Summary for a complr object

Description

Summary for a complr object

Usage

## S3 method for class 'summary.complr'
print(x, ...)

Arguments

See Also

summary.complr

Examples

cilr <- complr(data = mcompd, sbp = sbp, 
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), 
                idvar = "ID")
print(cilr)

Extract Priors of a brmsfit from a brmcoda object

Description

Compute Bayes factors from marginal likelihoods

Usage

## S3 method for class 'brmcoda'
prior_summary(object, ...)

Arguments

See Also

prior_summary.brmsfit

Possible Pairwise Substitutions

Description

A dataset containing possible pairwise subsitutions.

Usage

psub

Format

A data table containing 5 variables.

TST

first compositional variable

WAKE

second compositional variable

MVPA

third compositional variable

LPA

fourth compositional variable

SB

fifth compositional variable

Group-Level Estimates

Description

Extract the group-level ('random') effects of each level of the brmsfit object in a brmcoda object.

Usage

## S3 method for class 'brmcoda'
ranef(object, ...)

Arguments

Value

A list of 3D arrays (one per grouping factor). If summary is TRUE, the 1st dimension contains the factor levels, the 2nd dimension contains the summary statistics (see posterior_summary), and the 3rd dimension contains the group-level effects. If summary is FALSE, the 1st dimension contains the posterior draws, the 2nd dimension contains the factor levels, and the 3rd dimension contains the group-level effects.

See Also

ranef.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  ## extract group-level coefficients
  ranef(m)
}

Posterior Draws of Residuals/Predictive Errors

Description

Compute posterior draws of residuals/predictive errors

Usage

## S3 method for class 'brmcoda'
residuals(object, ...)

Arguments

Value

An array of predictive error/residual draws. If summary = FALSE the output resembles those of predictive_error.brmsfit. If summary = TRUE the output is an N x E matrix, where N is the number of observations and E denotes the summary statistics computed from the draws.

See Also

residuals.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  ## extract residuals
  res <- residuals(m)
  head(res)
}

Sequential Binary Partition

Description

A matrix of sequential binary partition.

Usage

sbp

Format

A matrix with 5 columns and 4 rows.

TST

first compositional variable

WAKE

second compositional variable

MVPA

third compositional variable

LPA

fourth compositional variable

SB

fifth compositional variable

multilevelcoda Simulation Study results

Description

A list of 4 components

Usage

sim

Format

A list with 5 columns and 4 rows.

brmcoda_tab

Simulation results for brmcoda() for tables

sub_tab

Simulation results for substitution() for tables

brmcoda_plot

Simulation results for brmcoda() for graphs

sub_plot

Simulation results for substitution() for graphs

Simple Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) using a aggregate reference composition (e.g., compositional mean at sample level, not seperated by between- and within effects). It is recommended that users run substitution model using the substitution function.

Usage

sub(
  object,
  delta,
  basesub,
  ref = "grandmean",
  level = "aggregate",
  weight = "equal",
  aorg = TRUE,
  summary = TRUE,
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){

cilr <- complr(data = mcompd, sbp = sbp, 
                parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

# model with compositional predictor at between and within-person levels
m <- brmcoda(complr = cilr, 
             formula = Stress ~ ilr1 + ilr2 + ilr3 + ilr4 + (1 | ID), 
             chain = 1, iter = 500,
             backend = "cmdstanr")
             
subm <- sub(object = m, basesub = psub, delta = 5)
}

Average Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) using cluster mean (e.g., compositional mean at individual level) as reference composition. It is recommended that users run substitution model using the substitution function.

Usage

submargins(
  object,
  delta,
  basesub,
  summary = TRUE,
  ref = "clustermean",
  level = "aggregate",
  weight = "proportional",
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){

cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

# model with compositional predictor at between and within-person levels
m <- brmcoda(complr = cilr, 
             formula = Stress ~ ilr1 + ilr2 + ilr3 + ilr4 + (1 | ID), 
             chain = 1, iter = 500,
             backend = "cmdstanr")
                     
subm <- submargins(object = m, basesub = psub, delta = 5)
}

Multilevel Compositional Substitution Analysis

Description

Estimate the difference in an outcome when compositional parts are substituted for specific unit(s). The substitution output encapsulates the substitution results for all compositional parts present in the brmcoda object.

Usage

substitution(
  object,
  delta,
  ref = c("grandmean", "clustermean"),
  level = c("between", "within", "aggregate"),
  basesub,
  aorg = TRUE,
  summary = TRUE,
  weight = c("equal", "proportional"),
  scale = c("response", "linear"),
  comparison = NULL,
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

Examples

if(requireNamespace("cmdstanr")){
  cilr <- complr(data = mcompd, sbp = sbp,
                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                 idvar = "ID", total = 1440)

  # model with compositional predictor at between and within-person levels
  fit1 <- brmcoda(complr = cilr,
                  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                     wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
                  chain = 1, iter = 500, backend = "cmdstanr")
                  
  # one to one reallocation at between and within-person levels
  sub1 <- substitution(object = fit1, delta = 5, level = c("between"))
  summary(sub1)
  
  # one to all reallocation at between and within-person levels
  sub2 <- substitution(object = fit1, delta = 5, level = c("between", "within"), 
                       basesub = "one-to-all")
  summary(sub2) 
  
  # model with compositional predictor at aggregate level of variance
  fit2 <- brmcoda(complr = cilr,
                  formula = Stress ~ ilr1 + ilr2 + ilr3 + ilr4 + (1 | ID),
                  chain = 1, iter = 500, backend = "cmdstanr")
  sub3 <- substitution(object = fit2, delta = 5, level = c("aggregate"))

}

Create a Summary of a fitted brmsfit model in a brmcoda object

Description

Create a Summary of a fitted brmsfit model in a brmcoda object

Usage

## S3 method for class 'brmcoda'
summary(object, ...)

Arguments

Examples

if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                                 idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  summary(m)
}

Create a Summary of a complr object

Description

Create a Summary of a complr object

Usage

## S3 method for class 'complr'
summary(object, weight = c("equal", "proportional"), ...)

Arguments

Examples

cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), 
               idvar = "ID")
summary(cilr)
cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"))
summary(cilr)

Create a Summary of a fitted brmsfit model from a pivot_coord object

Description

Create a Summary of a fitted brmsfit model from a pivot_coord object

Usage

## S3 method for class 'pivot_coord'
summary(object, digits = 2, ...)

Arguments

Value

A data table of results.

Examples

if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                                 parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                                 idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  m_pb <- pivot_coord(m)
  summary(m_pb)
}

Create a Summary of a Substitution Model represented by a substitution object

Description

Create a Summary of a Substitution Model represented by a substitution object

Usage

## S3 method for class 'substitution'
summary(object, delta, to, from, ref, level, digits = 2, ...)

Arguments

Value

A summary of substitution object.

Examples

if(requireNamespace("cmdstanr")){
  ## fit a model with compositional predictor at between and between-person levels
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  subm <- substitution(object = m, delta = 5)
  summary(subm)
}

Update brmcoda models

Description

This method allows for updating an existing brmcoda object.

Usage

## S3 method for class 'brmcoda'
update(object, formula. = NULL, newdata = NULL, newcomplr = NULL, ...)

Arguments

Value

A brmcoda with two elements

See Also

brmcoda

Examples

if(requireNamespace("cmdstanr")){

# model with compositional predictor at between and within-person levels
fit <- brmcoda(complr = complr(data = mcompd, sbp = sbp, 
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), 
                               idvar = "ID"), 
              formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
                                 wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID), 
              chain = 1, iter = 500,
              backend = "cmdstanr")

# removing the effect of wilr1
fit1 <- update(fit, formula. = ~ . - wilr1)

# using only a subset
fit2 <- update(fit, newdata = mcompd[ID != 1])
}

Update complr

Description

This method allows for updating an existing complr object.

Usage

## S3 method for class 'complr'
update(object, newdata, ...)

Arguments

Value

A complr object with at least the following elements.

See Also

complr

Examples

cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID")

# update with new data
newdat <- mcompd[ID != 1] # excluding ID 1
cilr1 <- update(object = cilr, newdata = newdat)

Variance of compositions presented in a complr object.

Description

Variance of compositions presented in a complr object.

Usage

## S3 method for class 'complr'
var(x, weight = c("equal", "proportional"), ...)

Arguments

Covariance and Correlation Matrix of Population-Level Effects

Description

Get a point estimate of the covariance or correlation matrix of population-level parameters of the brmsfit object in a brmcoda object.

Usage

## S3 method for class 'brmcoda'
vcov(object, ...)

Arguments

Value

covariance or correlation matrix of population-level parameters

See Also

vcov.brmsfit

Examples

## fit a model
if(requireNamespace("cmdstanr")){
  m <- brmcoda(complr = complr(data = mcompd, sbp = sbp,
                               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"),
                               idvar = "ID", total = 1440),
  formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 +
    wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID),
  chain = 1, iter = 500,
  backend = "cmdstanr")
  
  vcov(m)
}

Within-person Simple Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) at within level using a single reference composition (e.g., compositional mean at sample level). It is recommended that users run substitution model using the substitution function.

Usage

wsub(
  object,
  basesub,
  delta,
  ref = "grandmean",
  level = "within",
  weight = "equal",
  aorg = TRUE,
  summary = TRUE,
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){

cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

# model with compositional predictor at between and within-person levels
m <- brmcoda(complr = cilr, 
             formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 + 
                                wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID), 
             chain = 1, iter = 500,
             backend = "cmdstanr")
             
subm <- wsub(object = m, basesub = psub, delta = 60)
}

Within-person Average Substitution

Description

This function is an alias of substitution to estimates the the difference in an outcome when compositional parts are substituted for specific unit(s) at within level using cluster mean (e.g., compositional mean at individual level) as reference composition. It is recommended that users run substitution model using the substitution function.

Usage

wsubmargins(
  object,
  delta,
  basesub,
  summary = TRUE,
  ref = "clustermean",
  level = "within",
  weight = "proportional",
  scale = c("response", "linear"),
  comparison = "one-to-one",
  cores = NULL,
  ...
)

Arguments

Value

A list containing the results of multilevel compositional substitution model. The first six lists contain the results of the substitution estimation for a compositional part.

See Also

substitution

Examples

if(requireNamespace("cmdstanr")){

cilr <- complr(data = mcompd, sbp = sbp, 
               parts = c("TST", "WAKE", "MVPA", "LPA", "SB"), idvar = "ID", total = 1440)

# model with compositional predictor at between and within-person levels
m <- brmcoda(complr = cilr, 
             formula = Stress ~ bilr1 + bilr2 + bilr3 + bilr4 + 
                                wilr1 + wilr2 + wilr3 + wilr4 + (1 | ID), 
             chain = 1, iter = 500,
             backend = "cmdstanr")
                     
subm <- wsubmargins(object = m, basesub = psub, delta = 5)
}