brm_archetype_cells: Cell means archetype
In brms.mmrm: Bayesian MMRMs using 'brms'

brm_archetype_cells

R Documentation

Cell means archetype

Description

Create an informative prior archetype for cell means.

Usage

brm_archetype_cells(
  data,
  intercept = FALSE,
  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")),
  covariates = TRUE,
  clda = FALSE,
  prefix_interest = "x_",
  prefix_nuisance = "nuisance_"
)

Arguments

`data`	A classed data frame from `brm_data()`, or an informative prior archetype from a function like `brm_archetype_successive_cells()`.
`intercept`	`TRUE` to make one of the parameters an intercept, `FALSE` otherwise. If `TRUE`, then the interpretation of the parameters in the "Details" section will change, and you are responsible for manually calling `summary()` on the archetype and interpreting the parameters according to the output. In addition, you are responsible for setting an appropriate prior on the intercept. In normal usage, `brms` looks for a model parameter called `"Intercept"` and uses the data to set the prior to help the MCMC runs smoothly. If `intercept = TRUE` for informative prior archetypes, the intercept will be called something else, and `brms` cannot auto-generate a sensible default prior.
`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. Ignored for informative prior archetypes. For informative prior archetypes, this option should be set in functions like `brm_archetype_successive_cells()` rather than in `brm_formula()` in order to make sure columns are appropriately centered and the underlying model matrix has full rank.
`baseline_subgroup`	Logical of length 1.
`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. Ignored for informative prior archetypes. For informative prior archetypes, this option should be set in functions like `brm_archetype_successive_cells()` rather than in `brm_formula()` in order to make sure columns are appropriately centered and the underlying model matrix has full rank.
`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. Ignored for informative prior archetypes. For informative prior archetypes, this option should be set in functions like `brm_archetype_successive_cells()` rather than in `brm_formula()` in order to make sure columns are appropriately centered and the underlying model matrix has full rank.
`covariates`	Logical of length 1. `TRUE` (default) to include any additive covariates declared with the `covariates` argument of `brm_data()`, `FALSE` to omit. For informative prior archetypes, this option is set in functions like `brm_archetype_successive_cells()` rather than in `brm_formula()` in order to make sure columns are appropriately centered and the underlying model matrix has full rank.
`clda`	`TRUE` to opt into constrained longitudinal data analysis (cLDA), `FALSE` otherwise. To use cLDA, `reference_time` must have been non-`NULL` in the call to `brm_data()` used to construct the data. Some archetypes cannot support cLDA (e.g. `brm_archetype_average_cells()` and `brm_archetype_average_effects()`). In cLDA, the fixed effects parameterization is restricted such that all treatment groups are pooled at baseline. (If you supplied a `subgroup` variable in `brm_data()`, then this constraint is applied separately within each subgroup variable.) cLDA may result in more precise estimates when the `time` variable has a baseline level and the baseline outcomes are recorded before randomization in a clinical trial.
`prefix_interest`	Character string to prepend to the new columns of generated fixed effects of interest (relating to group, subgroup, and/or time). In rare cases, you may need to set a non-default prefix to prevent name conflicts with existing columns in the data, or rename the columns in your data. `prefix_interest` must not be the same value as `prefix_nuisance`.
`prefix_nuisance`	Same as `prefix_interest`, but relating to generated fixed effects NOT of interest (not relating to group, subgroup, or time). Must not be the same value as `prefix_interest`.

Details

In this archetype, each fixed effect is a cell mean: the group mean for a given value of treatment group and discrete time (and subgroup level, if applicable).

Value

A special classed tibble with data tailored to the successive differences archetype. The dataset is augmented with extra columns with the "archetype_" prefix, as well as special attributes to tell downstream functions like brm_formula() what to do with the object.

Prior labeling for `brm_archetype_cells()`

Within each treatment group, each model parameter is a cell mean, and the labeling scheme in brm_prior_label() and brm_prior_archetype() translate easily. For example, brm_prior_label(code = "normal(1.2, 5)", group = "B", time = "VISIT2") declares a normal(1.2, 5) prior on the cell mean of treatment group B at discrete time point VISIT2. To confirm that you set the prior correctly, compare the brms prior with the output of summary(your_archetype). See the examples for details.

Nuisance variables

In the presence of covariate adjustment, functions like brm_archetype_successive_cells() convert nuisance factors into binary dummy variables, then center all those dummy variables and any continuous nuisance variables at their means in the data. This ensures that the main model coefficients of interest are not implicitly conditional on a subset of the data. In other words, preprocessing nuisance variables this way preserves the interpretations of the fixed effects of interest, and it ensures informative priors can be specified correctly.

Prior labeling

Informative prior archetypes use a labeling scheme to assign priors to fixed effects. How it works:

1. First, assign the prior of each parameter a collection
  of labels from the data. This can be done manually or with
  successive calls to [brm_prior_label()].
2. Supply the labeling scheme to [brm_prior_archetype()].
  [brm_prior_archetype()] uses attributes of the archetype
  to map labeled priors to their rightful parameters in the model.

For informative prior archetypes, this process is much more convenient and robust than manually calling brms::set_prior(). However, it requires an understanding of how the labels of the priors map to parameters in the model. This mapping varies from archetype to archetype, and it is documented in the help pages of archetype-specific functions such as brm_archetype_successive_cells().

Examples

set.seed(0L)
data <- brm_simulate_outline(
  n_group = 2,
  n_patient = 100,
  n_time = 4,
  rate_dropout = 0,
  rate_lapse = 0
) |>
  dplyr::mutate(response = rnorm(n = dplyr::n())) |>
  brm_data_change() |>
  brm_simulate_continuous(names = c("biomarker1", "biomarker2")) |>
  brm_simulate_categorical(
    names = c("status1", "status2"),
    levels = c("present", "absent")
  )
dplyr::select(
  data,
  group,
  time,
  patient,
  starts_with("biomarker"),
  starts_with("status")
)
archetype <- brm_archetype_cells(data)
archetype
summary(archetype)
formula <- brm_formula(archetype)
formula
prior <- brm_prior_label(
  code = "normal(1, 2.2)",
  group = "group_1",
  time = "time_2"
) |>
  brm_prior_label("normal(1, 3.3)", group = "group_1", time = "time_3") |>
  brm_prior_label("normal(1, 4.4)", group = "group_1", time = "time_4") |>
  brm_prior_label("normal(2, 2.2)", group = "group_2", time = "time_2") |>
  brm_prior_label("normal(2, 3.3)", group = "group_2", time = "time_3") |>
  brm_prior_label("normal(2, 4.4)", group = "group_2", time = "time_4") |>
  brm_prior_archetype(archetype)
prior
class(prior)
if (identical(Sys.getenv("BRM_EXAMPLES", unset = ""), "true")) {
tmp <- utils::capture.output(
  suppressMessages(
    suppressWarnings(
      model <- brm_model(
        data = archetype,
        formula = formula,
        prior = prior,
        chains = 1,
        iter = 100,
        refresh = 0
      )
    )
  )
)
suppressWarnings(print(model))
brms::prior_summary(model)
draws <- brm_marginal_draws(
  data = archetype,
  formula = formula,
  model = model
)
summaries_model <- brm_marginal_summaries(draws)
summaries_data <- brm_marginal_data(data)
brm_plot_compare(model = summaries_model, data = summaries_data)
}

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