brm_formula {brms.mmrm}

Model formula

Description

Build a model formula for an MMRM.

Usage

brm_formula(
  data,
  intercept = TRUE,
  baseline = !is.null(attr(data, "brm_baseline")),
  baseline_subgroup = !is.null(attr(data, "brm_baseline")) && !is.null(attr(data,
    "brm_subgroup")),
  baseline_subgroup_time = !is.null(attr(data, "brm_baseline")) && !is.null(attr(data,
    "brm_subgroup")),
  baseline_time = !is.null(attr(data, "brm_baseline")),
  group = TRUE,
  group_subgroup = !is.null(attr(data, "brm_subgroup")),
  group_subgroup_time = !is.null(attr(data, "brm_subgroup")),
  group_time = TRUE,
  subgroup = !is.null(attr(data, "brm_subgroup")),
  subgroup_time = !is.null(attr(data, "brm_subgroup")),
  time = TRUE,
  correlation = "unstructured",
  effect_baseline = NULL,
  effect_group = NULL,
  effect_time = NULL,
  interaction_baseline = NULL,
  interaction_group = NULL
)

Arguments

data

A classed data frame from brm_data().

intercept

Logical of length 1. TRUE (default) to include an intercept, FALSE to omit.

baseline

Logical of length 1. TRUE to include an additive effect for baseline response, FALSE to omit. Default is TRUE if brm_data() previously declared a baseline variable in the dataset.

baseline_subgroup

Logical of length 1. TRUE to include baseline-by-subgroup interaction, FALSE to omit. Default is TRUE if brm_data() previously declared baseline and subgroup variables in the dataset.

baseline_subgroup_time

Logical of length 1. TRUE to include baseline-by-subgroup-by-time interaction, FALSE to omit. Default is TRUE if brm_data() previously declared baseline and subgroup variables in the dataset.

baseline_time

Logical of length 1. TRUE to include baseline-by-time interaction, FALSE to omit. Default is TRUE if brm_data() previously declared a baseline variable in the dataset.

group

Logical of length 1. TRUE (default) to include additive effects for treatment groups, FALSE to omit.

group_subgroup

Logical of length 1. TRUE to include group-by-subgroup interaction, FALSE to omit. Default is TRUE if brm_data() previously declared a subgroup variable in the dataset.

group_subgroup_time

Logical of length 1. TRUE to include group-by-subgroup-by-time interaction, FALSE to omit. Default is TRUE if brm_data() previously declared a subgroup variable in the dataset.

group_time

Logical of length 1. TRUE (default) to include group-by-time interaction, FALSE to omit.

subgroup

Logical of length 1. TRUE to include additive fixed effects for subgroup levels, FALSE to omit. Default is TRUE if brm_data() previously declared a subgroup variable in the dataset.

subgroup_time

Logical of length 1. TRUE to include subgroup-by-time interaction, FALSE to omit. Default is TRUE if brm_data() previously declared a subgroup variable in the dataset.

time

Logical of length 1. TRUE (default) to include a additive effect for discrete time, FALSE to omit.

correlation

Character of length 1, name of the correlation structure. Only "unstructured" is currently supported.

effect_baseline

Deprecated on 2024-01-16 (version 0.0.2.9002). Use baseline instead.

effect_group

Deprecated on 2024-01-16 (version 0.0.2.9002). Use group instead.

effect_time

Deprecated on 2024-01-16 (version 0.0.2.9002). Use time instead.

interaction_baseline

Deprecated on 2024-01-16 (version 0.0.2.9002). Use baseline_time instead.

interaction_group

Deprecated on 2024-01-16 (version 0.0.2.9002). Use group_time instead.

Details

brm_formula() builds an R formula for an MMRM based on the details in the data and your choice of parameterization. Customize your parameterization by toggling on or off the various TRUE/FALSE arguments of brm_formula(), such as intercept, baseline, and group_time. All plausible additive effects, two-way interactions, and three-way interactions can be specified. The following interactions are not supported:

• Any interactions with the concomitant covariates you specified in the covariates argument of brm_data().

• Any interactions which include baseline response and treatment group together. Rationale: in a randomized controlled experiment, baseline and treatment group assignment should be uncorrelated.

Value

An object of class "brmsformula" returned from brms::brmsformula(). It contains the fixed effect parameterization, correlation structure, and residual variance structure.

Parameterization

The formula is not the only factor that determines the fixed effect parameterization. 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.

See Also

Other models: brm_model()

Examples

set.seed(0)
data <- brm_data(
  data = brm_simulate_simple()$data,
  outcome = "response",
  role = "response",
  group = "group",
  time = "time",
  patient = "patient",
  reference_group = "group_1",
  reference_time = "time_1"
)
brm_formula(data)
brm_formula(data = data, intercept = FALSE, baseline = FALSE)
formula <- brm_formula(
  data = data,
  intercept = FALSE,
  baseline = FALSE,
  group = FALSE
)
formula
# Optional: set the contrast option, which determines the model matrix.
options(contrasts = c(unordered = "contr.SAS", ordered = "contr.poly"))
# See the fixed effect parameterization you get from the data:
head(brms::make_standata(formula = formula, data = data)$X)
# Specify a different contrast method to use an alternative
# parameterization 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)