multilevelcoda (version 1.3.1)

substitution: 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,
  basesub,
  summary = TRUE,
  ref = c("grandmean", "clustermean"),
  level = c("between", "within", "aggregate"),
  weight = c("equal", "proportional"),
  scale = c("response", "linear"),
  cores = NULL,
  ...
)

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.

Mean

Posterior means.

CI_low and CI_high

95% credible intervals.

Delta

Amount substituted across compositional parts.

From

Compositional part that is substituted from.

To

Compositional parts that is substituted to.

Level

Level where changes in composition takes place.

Reference

Either grandmean, clustermean, or users.

Arguments

object

A fitted brmcoda object.

delta

A integer, numeric value or vector indicating the amount of substituted change between compositional parts.

basesub

A base substitution. Can be a data.frame or data.table of the base possible substitution of compositional parts, which can be computed using function build.basesub. If "one-to-all", all possible one-to-remaining reallocations are estimated. If NULL, all possible one-to-one reallocations are estimated.

summary

A logical value. Should the estimate at each level of the reference grid (FALSE) or their average (TRUE) be returned? Default is TRUE. Only applicable for model with covariates in addition to the isometric log-ratio coordinates (i.e., adjusted model).

ref

Either a character value or vector or a dataset. Can be "grandmean" and/or "clustermean", or a data.frame or data.table of user's specified reference grid consisting of combinations of covariates over which predictions are made. User's specified reference grid is only possible for simple substitution. Single level models are default to "grandmean".

level

A character string or vector. Should the estimate of multilevel models focus on the "between" and/or "within" or "aggregate" variance? Single-level models are default to "aggregate".

weight

A character value specifying the weight to use in calculation of the reference composition. If "equal", give equal weight to units (e.g., individuals). If "proportional", weights in proportion to the frequencies of units being averaged (e.g., observations across individuals). Default to "equal" for ref = "grandmean" and "proportional" for ref = "clustermean".

scale

Either "response" or "linear". If "response", results are returned on the scale of the response variable. If "linear", results are returned on the scale of the linear predictor term, that is without applying the inverse link function or other transformations.

cores

Number of cores to use when executing the chains in parallel, we recommend setting the mc.cores option to be as many processors as the hardware and RAM allow (up to the number of compositional parts). For non-Windows OS in non-interactive R sessions, forking is used instead of PSOCK clusters.

...

currently ignored.

Examples

# \donttest{
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", "within"))
  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"))

}# }