brm_transform_marginal {brms.mmrm}

Marginal mean transformation

Description

Transformation from model parameters to marginal means.

Usage

brm_transform_marginal(
  data,
  formula,
  average_within_subgroup = NULL,
  prefix = "b_"
)

Arguments

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.

average_within_subgroup

TRUE to average concomitant covariates proportionally within subgroup levels, FALSE to average these covariates across the whole dataset. If average_within_subgroup is NULL (default), and if the model has a subgroup and nuisance variables, then brm_transform_marginal() prints and informative message (once per session) and sets average_within_subgroup to FALSE. If you see this message, please read https://openpharma.github.io/brms.mmrm/articles/inference.html, decide whether to set average_within_subgroup to TRUE or FALSE in brm_transform_marginal(), and then manually supply the output of brm_transform_marginal() to the transform argument of brm_marginal_draws().

To create marginal means, brms.mmrm conditions the nuisance covariates on their averages across the whole dataset (average_within_subgroup = FALSE or NULL in brm_transform_marginal()). This may be reasonable in some cases, and it mitigates the kind of hidden confounding between the subgroup and other variables which may otherwise cause Simpson's paradox. However, for subgroup-specific marginal means, it may not be realistic to condition on a single point estimate for all levels of the reference grid (for example, if the subgroup is female vs male, but all marginal means condition on a single overall observed pregnancy rate of 5%). In these situations, it may be appropriate to instead condition on subgroup-specific averages of nuisance variables (average_within_subgroup = TRUE in brm_transform_marginal()). But if you do this, it is your responsibility to investigate and understand the hidden interactions and confounding in your dataset. For more information, please visit https://openpharma.github.io/brms.mmrm/articles/inference.html and https://cran.r-project.org/package=emmeans/vignettes/interactions.html.

prefix

Character of length 1, prefix to add to the model matrix ("X") from brms::make_standata() in order to reconstruct the brms model parameter names. This argument should only be modified for testing purposes.

Details

The matrix from brm_transform_marginal() is passed to the transform_marginal argument of brm_marginal_draws(), and it transforms posterior draws of model parameters to posterior draws of marginal means. You may customize the output of brm_transform_marginal() before passing it to brm_marginal_draws(). However, please do not modify the dimensions, row names, or column names.

Value

A matrix to transform model parameters (columns) into marginal means (rows).

Examples

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
)
transform <- brm_transform_marginal(data = data, formula = formula)
equations <- summary(transform)
print(equations)
summary(transform, message = FALSE)
class(transform)
print(transform)