brm_marginal_draws: MCMC draws from the marginal posterior of an MMRM
In brms.mmrm: Bayesian MMRMs using 'brms'

brm_marginal_draws

R Documentation

MCMC draws from the marginal posterior of an MMRM

Description

Get marginal posterior draws from a fitted MMRM.

Usage

brm_marginal_draws(
  model,
  data = model$brms.mmrm_data,
  formula = model$brms.mmrm_formula,
  transform = brms.mmrm::brm_transform_marginal(data = data, formula = formula,
    average_within_subgroup = average_within_subgroup),
  effect_size = attr(formula, "brm_allow_effect_size"),
  average_within_subgroup = NULL,
  use_subgroup = NULL,
  control = NULL,
  baseline = NULL
)

Arguments

`model`	A fitted model object from `brm_model()`.
`data`	A classed data frame from `brm_data()`, or an informative prior archetype from a function like `brm_archetype_successive_cells()`.
`formula`	An object of class `"brmsformula"` from `brm_formula()` or `brms::brmsformula()`. Should include the full mapping of the model, including fixed effects, residual correlation, and heterogeneity in the discrete-time-specific residual variance components.
`transform`	Matrix with one row per marginal mean and one column per model parameter. `brm_marginal_draws()` uses this matrix to map posterior draws of model parameters to posterior draws of marginal means using matrix multiplication. Please use `brm_transform_marginal()` to compute this matrix and then modify only if necessary. See the methods vignettes for details on this matrix, as well as how `brms.mmrm` computes marginal means more generally.
`effect_size`	Logical, `TRUE` to derive posterior samples of effect size (treatment effect divided by residual standard deviation). `FALSE` to omit. `brms.mmrm` does not support effect size when baseline or covariates are included in the `brm_formula_sigma()` formula. If `effect_size` is `TRUE` in this case, then `brm_marginal_draws()` will automatically omit effect size and throw an informative warning.
`average_within_subgroup`	`TRUE`, `FALSE`, or `NULL` to control whether nuisance parameters are averaged within subgroup levels in `brm_transform_marginal()`. Ignored if the `transform` argument is manually supplied by the user. See the help page of `brm_transform_marginal()` for details on the `average_within_subgroup` argument.
`use_subgroup`	Deprecated. No longer used. `brm_marginal_draws()` no longer marginalizes over the subgroup declared in `brm_data()`. To marginalize over the subgroup, declare that variable in `covariates` instead.
`control`	Deprecated. Set the control group level in `brm_data()`.
`baseline`	Deprecated. Set the control group level in `brm_data()`.

Value

A named list of tibbles of MCMC draws of the marginal posterior distribution of each treatment group and time point. These marginals are also subgroup-specific if brm_formula() included fixed effects that use the subgroup variable originally declared in brm_data(). In each tibble, there is 1 row per posterior sample and one column for each type of marginal distribution (i.e. each combination of treatment group and discrete time point. The specific tibbles in the returned list are described below:

response: on the scale of the response variable.
difference_time: change from baseline: the response at a particular time minus the response at baseline (reference_time). Only returned if the reference_time argument of brm_data() was not NULL (i.e. if a baseline value for the time variable was identified).
difference_group: treatment effect: These samples depend on the values of reference_group and reference_time which were originally declared in brm_data(). reference_group is the control group, and reference_time is baseline. If baseline was originally given (via reference_time in brm_data()), then difference_time is the change-from-baseline value of each active group minus that of the control group. Otherwise, if baseline is omitted (i.e. reference_time = NULL (default) in brm_data()), then difference_time is the raw response at each active group minus that of the control group.
difference_subgroup: subgroup differences: the difference_group at each subgroup level minus the difference_group at the subgroup reference level (reference_subgroup). Only reported if a subgroup analysis was specified through the appropriate arguments to brm_data() and brm_formula().
effect: effect size, defined as the treatment difference divided by the residual standard deviation. Omitted if the effect_size argument is FALSE or if the brm_formula_sigma() includes baseline or covariates.
sigma: posterior draws of linear-scale marginal standard deviations of residuals. Omitted if the effect_size argument is FALSE or if the brm_formula_sigma() includes baseline or covariates.

Baseline

The returned values from brm_marginal_draws() depend on whether a baseline time point was declared through the reference_time argument of brm_data(). If reference_time was not NULL, then brm_marginal_draws() will calculate change from baseline, and it will calculate treatment differences as differences between change-from-baseline values. If reference_time was not NULL, then brm_marginal_draws() will not calculate change from baseline, and it will calculate treatment differences as differences between response values.

Separation string

Post-processing in brm_marginal_draws() names each of the group-by-time marginal means with the delimiting character string from Sys.getenv("BRM_SEP", unset = "|"). Neither the column names nor element names of the group and time variables can contain this string. To set a custom string yourself, use Sys.setenv(BRM_SEP = "YOUR_CUSTOM_STRING").

Examples

if (identical(Sys.getenv("BRM_EXAMPLES", unset = ""), "true")) {
set.seed(0L)
data <- brm_data(
  data = brm_simulate_simple()$data,
  outcome = "response",
  group = "group",
  time = "time",
  patient = "patient",
  reference_group = "group_1",
  reference_time = "time_1"
)
formula <- brm_formula(
  data = data,
  baseline = FALSE,
  baseline_time = FALSE
)
tmp <- utils::capture.output(
  suppressMessages(
    suppressWarnings(
      model <- brm_model(
        data = data,
        formula = formula,
        chains = 1,
        iter = 100,
        refresh = 0
      )
    )
  )
)
brm_marginal_draws(data = data, formula = formula, model = model)
}

brms.mmrm documentation built on Oct. 3, 2024, 1:08 a.m.