brm_model: Fit an MMRM.
In brms.mmrm: Bayesian MMRMs using 'brms'

brm_model

R Documentation

Fit an MMRM.

Description

Fit an MMRM model using brms.

Usage

brm_model(
  data,
  formula,
  ...,
  prior = NULL,
  family = brms::brmsfamily(family = "gaussian"),
  imputed = NULL
)

Arguments

`data`	A classed data frame from `brm_data()`, or an informative prior archetype from a function like `brm_archetype_successive_cells()`. Unless you supplied `model_missing_outcomes = TRUE` in `brm_formula()`, `brm_model()` automatically rows with missing outcomes just prior to fitting the model with `brms::brm()`. The `brms.mmrm_data` attribute in the output object is always the version of the data prior to removing these rows. See the `data` element of the returned `brms` object for the final data actually supplied to the model. If you supply a non-`NULL` value for the `imputed` argument, then the `data` argument is ignored and the MMRM is fit successively to each dataset in `imputed` using `brms::brm_multiple()`. Posterior draws are combined automatically for downstream post-processing unless you set `combine = FALSE` in `brm_model()`.
`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.
`...`	Arguments to `brms::brm()` or `brms::brm_multiple()` other than `data`, `formula`, `prior`, and `family`.
`prior`	Either `NULL` for default priors or a `"brmsprior"` object from `brms::prior()`.
`family`	A `brms` family object generated by `brms::brmsfamily()`. Must fit a continuous outcome variable and have the identity link.
`imputed`	Either `NULL` (default), list of datasets generated with multiple imputation, or a `"mids"` object from the `mice` package. The `rbmi` package may offer a more appropriate method for imputation for MMRMs than `mice`. It is your responsibility to choose an imputation method appropriate for the data and model. If not `NULL`, then the MMRM is fit successively to each dataset in `imputed` using `brms::brm_multiple()`. Posterior draws are combined automatically for downstream post-processing unless you set `combine = FALSE` in `brm_model()`, so everything at the level of `brm_marginal_draws()` will be exactly the same as a non-imputation workflow. Even if you supply `imputed`, please also supply the original non-imputed dataset in the `data` argument to help with downstream post-processing.

Value

A fitted model object from brms, with new list elements brms.mmrm_data and brms.mmrm_formula to capture the data and formula supplied to brm_model(). See the explanation of the data argument for how the data is handled and how it relates to the data returned in the brms.mmrm_data attribute.

Parameterization

For a formula on a brm_data() dataset, the formula is not the only factor that determines the fixed effect mapping. The ordering of the categorical variables in the data, as well as the contrast option in R, affect the construction of the model matrix. To see the model matrix that will ultimately be used in brm_model(), run brms::make_standata() and examine the X element of the returned list. See the examples below for a demonstration.

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
)
# Optional: set the contrast option, which determines the model matrix.
options(contrasts = c(unordered = "contr.SAS", ordered = "contr.poly"))
# See the fixed effect mapping you get from the data:
head(brms::make_standata(formula = formula, data = data)$X)
# Specify a different contrast method to use an alternative
# mapping when fitting the model with brm_model():
options(
  contrasts = c(unordered = "contr.treatment", ordered = "contr.poly")
)
# different model matrix than before:
head(brms::make_standata(formula = formula, data = data)$X)
tmp <- utils::capture.output(
  suppressMessages(
    suppressWarnings(
      model <- brm_model(
        data = data,
        formula = formula,
        chains = 1,
        iter = 100,
        refresh = 0
      )
    )
  )
)
# The output is a brms model fit object with added list
# elements "brms.mmrm_data" and "brms.mmrm_formula" to track the dataset
# and formula used to fit the model.
model$brms.mmrm_data
model$brms.mmrm_formula
# Otherwise, the fitted model object acts exactly like a brms fitted model.
suppressWarnings(print(model))
brms::prior_summary(model)
}

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