Skip to contents

Create a dataset to analyze with an MMRM.

Usage

brm_data(
  data,
  outcome = "CHG",
  role = "change",
  baseline = NULL,
  group = "TRT01P",
  subgroup = NULL,
  time = "AVISIT",
  patient = "USUBJID",
  covariates = character(0L),
  missing = NULL,
  reference_group = "Placebo",
  level_control = NULL,
  reference_subgroup = NULL,
  reference_time = NULL,
  level_baseline = NULL
)

Arguments

data

Data frame or tibble with longitudinal data.

outcome

Character of length 1, name of the outcome variable.

role

Character of length 1. Either "response" if outcome is the raw response variable (e.g. AVAL) or "change" if outcome is change from baseline (e.g. CHG).

baseline

Character of length 1, name of the baseline response variable. Only relevant if the response variable is change from baseline. Supply NULL to ignore or omit.

group

Character of length 1, name of the treatment group variable. Must point to a character vector in the data. Factors are converted to characters.

subgroup

Character of length 1, optional name of the a discrete subgroup variable. Set to NULL to omit the subgroup (default).

time

Character of length 1, name of the discrete time variable. Must point to a character vector in the data. Factors are converted to characters.

patient

Character of length 1, name of the patient ID variable.

covariates

Character vector of names of other covariates.

missing

Character of length 1, name of an optional variable in a simulated dataset to indicate which outcome values should be missing. Set to NULL to omit.

reference_group

Character of length 1, Level of the group column to indicate the control group. reference_group 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().

level_control

Deprecated on 2024-01-11 (version 0.2.0.9002). Use reference_group instead.

reference_subgroup

Character of length 1, level of the subgroup column to use as a reference for pairwise differences in when computing marginal means 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().

reference_time

Character of length 1 or NULL, level of the time column to indicate the baseline time point. This value should not be present in the data if the outcome variable is change from baseline, but it must be in the data if the outcome variable is the raw response so that brms.mmrm can produce model-based marginal estimates of change from baseline. In other words, set reference_time to NULL if role is "change", and set reference_time to a non-null value in data[[time]] if role is "response".

Note: reference_time 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().

level_baseline

Deprecated on 2024-01-11 (version 0.2.0.9002). Use reference_time instead.

Value

A classed tibble with attributes which denote features of the data such as the treatment group and discrete time variables.

Preprocessing

The preprocessing steps in brm_data() are as follows:

  • Perform basic assertions to make sure the data and other arguments are properly formatted.

  • Convert the group and time columns to character vectors.

  • Sanitize the levels of the group and time columns using make.names(unique = FALSE, allow_ = TRUE) to ensure agreement between the data and the output of brms.

  • For each implicitly missing outcome observation, add explicit row with the outcome variable equal to NA_real_.

  • Arrange the rows of the data by group, then patient, then discrete time.

  • Select only the columns of the data relevant to an MMRM analysis.

Separation string

Post-processing in brm_marginal_draws() names each of the group-by-time marginal means with the delimiting character string from Sys.getenv("BRM_SEP", unset = "|"). Neither the column names nor element names of the group and time variables can contain this string. To set a custom string yourself, use Sys.setenv(BRM_SEP = "YOUR_CUSTOM_STRING").

See also

Other data: brm_data_change()

Examples

set.seed(0)
data <- brm_simulate_simple()$data
colnames(data) <- paste0("col_", colnames(data))
data
#> # A tibble: 800 × 4
#>    col_response col_group col_time col_patient
#>           <dbl> <chr>     <chr>    <chr>      
#>  1        1.47  group_1   time_1   patient_001
#>  2        3.10  group_1   time_2   patient_001
#>  3        2.22  group_1   time_3   patient_001
#>  4        0.215 group_1   time_4   patient_001
#>  5        1.03  group_1   time_1   patient_002
#>  6        2.28  group_1   time_2   patient_002
#>  7        2.36  group_1   time_3   patient_002
#>  8        2.33  group_1   time_4   patient_002
#>  9        0.128 group_1   time_1   patient_003
#> 10        1.89  group_1   time_2   patient_003
#> # ℹ 790 more rows
brm_data(
  data = data,
  outcome = "col_response",
  role = "response",
  group = "col_group",
  time = "col_time",
  patient = "col_patient",
  reference_group = "group_1",
  reference_time = "time_1"
)
#> # A tibble: 800 × 4
#>    col_response col_group col_time col_patient
#>           <dbl> <chr>     <chr>    <chr>      
#>  1        1.47  group_1   time_1   patient_001
#>  2        3.10  group_1   time_2   patient_001
#>  3        2.22  group_1   time_3   patient_001
#>  4        0.215 group_1   time_4   patient_001
#>  5        1.03  group_1   time_1   patient_002
#>  6        2.28  group_1   time_2   patient_002
#>  7        2.36  group_1   time_3   patient_002
#>  8        2.33  group_1   time_4   patient_002
#>  9        0.128 group_1   time_1   patient_003
#> 10        1.89  group_1   time_2   patient_003
#> # ℹ 790 more rows