brm_marginal_draws {brms.mmrm}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:

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").

See Also

Other marginals: brm_marginal_data(), brm_marginal_draws_average(), brm_marginal_grid(), brm_marginal_probabilities(), brm_marginal_summaries()

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)
}

[Package brms.mmrm version 1.1.0 Index]