Elaborate on model matrices

R/brm_data.R

@@ -51,8 +51,17 @@
 #'   In other words, set `level_baseline` to `NULL` if `role` is `"change"`,
 #'   and set `level_baseline` to a non-null value in `data[[time]]`
 #'   if `role` is `"response"`.
+#'
+#'   Note: `level_baseline` only applies to the post-processing that happens
+#'   in functions like [brm_marginal_draws()] downstream of the model.
+#'   It does not control the fixed effect parameterization in the
+#'   model matrix that `brms` derives from the formula from `brm_formula()`.
 #' @param level_control Character of length 1, Level of the `group` column
 #'   to indicate the control group.
+#'   `level_control` only applies to the post-processing that happens
+#'   in functions like [brm_marginal_draws()] downstream of the model.
+#'   It does not control the fixed effect parameterization in the
+#'   model matrix that `brms` derives from the formula from `brm_formula()`.
 #' @examples
 #' set.seed(0)
 #' data <- brm_simulate_simple()$data

R/brm_formula.R

@@ -2,6 +2,16 @@
 #' @export
 #' @family models
 #' @description Build a model formula for an MMRM.
+#' @section 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.
 #' @return An object of class `"brmsformula"` returned from
 #'   `brms::brmsformula()`. It contains the fixed effect parameterization,
 #'   correlation structure, and residual variance structure.
@@ -33,12 +43,24 @@
 #' )
 #' brm_formula(data)
 #' brm_formula(data = data, intercept = FALSE, effect_baseline = FALSE)
-#' brm_formula(
+#' formula <- brm_formula(
 #'   data = data,
 #'   intercept = FALSE,
 #'   effect_baseline = FALSE,
 #'   interaction_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)
 brm_formula <- function(
   data,
   intercept = TRUE,

R/brm_model.R

@@ -2,6 +2,7 @@
 #' @export
 #' @family models
 #' @description Fit a basic MMRM model using `brms`.
+#' @inheritSection brm_formula Parameterization
 #' @return A fitted model object from `brms`.
 #' @param data A tidy data frame with one row per patient per discrete
 #'   time point.
@@ -32,6 +33,17 @@
 #'   effect_baseline = FALSE,
 #'   interaction_baseline = FALSE
 #' )
+#' # 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)
 #' tmp <- utils::capture.output(
 #'   suppressMessages(
 #'     suppressWarnings(
@@ -45,7 +57,10 @@
 #'     )
 #'   )
 #' )
+#' # The output model is a brms model fit object.
 #' model
+#' # The `prior_summary()` function shows the full prior specification
+#' # which reflects the fully realized fixed effects parameterization.
 #' brms::prior_summary(model)
 #' }
 brm_model <- function(