From 66b5e3381d8995c5fd7b070aff715b2a513e76ae Mon Sep 17 00:00:00 2001 From: wlandau Date: Thu, 11 Jul 2024 13:13:55 -0400 Subject: [PATCH 1/4] Start #119 --- DESCRIPTION | 2 +- NEWS.md | 3 +- R/brm_archetype_successive_cells.R | 2 +- R/brm_data.R | 45 +++++++++++---------------- R/brm_data_change.R | 14 +++------ R/brm_formula.R | 2 -- R/brm_formula_sigma.R | 2 -- R/brm_marginal_data.R | 1 - R/brm_marginal_draws.R | 42 ++++++++++++++++--------- R/brm_marginal_draws_average.R | 25 +++------------ R/brm_marginal_probabilities.R | 1 - R/brm_marginal_summaries.R | 1 - R/brm_model.R | 1 - R/brm_plot_compare.R | 1 - R/brm_plot_draws.R | 1 - R/brm_simulate_outline.R | 5 ++- R/brm_simulate_simple.R | 1 - R/brm_transform_marginal.R | 1 - man/brm_archetype_successive_cells.Rd | 2 +- man/brm_data.Rd | 25 ++++++++------- man/brm_data_change.Rd | 6 ++-- man/brm_formula.Rd | 1 - man/brm_formula_sigma.Rd | 1 - man/brm_marginal_data.Rd | 1 - man/brm_marginal_draws.Rd | 34 +++++++++++++++----- man/brm_marginal_draws_average.Rd | 27 +++------------- man/brm_marginal_probabilities.Rd | 1 - man/brm_marginal_summaries.Rd | 1 - man/brm_model.Rd | 1 - man/brm_plot_compare.Rd | 1 - man/brm_plot_draws.Rd | 1 - man/brm_simulate_outline.Rd | 4 +-- man/brm_transform_marginal.Rd | 1 - 33 files changed, 110 insertions(+), 147 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f0ecfa88..68de3cc2 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: brms.mmrm Title: Bayesian MMRMs using 'brms' -Version: 1.0.1.9006 +Version: 1.0.1.9007 Authors@R: c( person( given = c("William", "Michael"), diff --git a/NEWS.md b/NEWS.md index d2d1a403..d9e20ff0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# brms.mmrm 1.0.1.9006 (development) +# brms.mmrm 1.0.1.9007 (development) * Add `brm_marginal_grid()`. * Show posterior samples of `sigma` in `brm_marginal_draws()` and `brm_marginal_summaries()`. @@ -10,6 +10,7 @@ * Take defaults `data` and `formula` from the above in `brm_marginal_draws()`. * Set the default value of `effect_size` to `attr(formula, "brm_allow_effect_size")`. * Remove defaults from some arguments to `brm_data()` and document examples. +* Deprecate the `role` argument of `brm_data()` in favor of `reference_time` (#119). # brms.mmrm 1.0.1 diff --git a/R/brm_archetype_successive_cells.R b/R/brm_archetype_successive_cells.R index 16e52a0a..3f7294d4 100644 --- a/R/brm_archetype_successive_cells.R +++ b/R/brm_archetype_successive_cells.R @@ -25,7 +25,7 @@ #' #' For group A, `beta_1` is the time 1 intercept, `beta_2` represents #' time 2 minus time 1, and `beta_3` represents time 3 minus time 2. -#' `beta_4`, `beta_5`, and `beta_6` represent the analogous roles. +#' `beta_4`, `beta_5`, and `beta_6` behave analogously for group B. #' @section Nuisance variables: #' In the presence of covariate adjustment, functions like #' [brm_archetype_successive_cells()] convert nuisance factors into binary diff --git a/R/brm_data.R b/R/brm_data.R index 5e59b35d..1f8aa0bb 100644 --- a/R/brm_data.R +++ b/R/brm_data.R @@ -29,9 +29,6 @@ #' Example possibilities from clinical trial datasets include #' `"CHG"` and `"AVAL"`. #' The `outcome` column in the data should be a numeric vector. -#' @param 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). #' @param baseline Character of length 1, #' name of the baseline response variable (for example, `"BASE"` #' in many clinical trial datasets). @@ -91,17 +88,22 @@ #' model matrix that `brms` derives from the formula from `brm_formula()`. #' @param reference_time Atomic value of length 1 or `NULL`, #' level of the `time` column to indicate the baseline time point. -#' This value must be `NULL` if the outcome -#' variable is already change from baseline. If the outcome -#' is raw response, then `reference_time` may or may not be `NULL`. -#' [brm_marginal_draws()] and downstream functions calculate posterior -#' inference on change from baseline if and only if -#' `reference_time` is not `NULL`. +#' Leave as `NULL` if there is no baseline or baseline is not included +#' in `data[[time]]`. +#' +#' If `reference_time` is not `NULL`, then [brm_marginal_draws()] will +#' calculate change from baseline, and it will calculate treatment +#' differences as differences between change-from-baseline values. +#' If `reference_time` is not `NULL`, then [brm_marginal_draws()] will +#' not calculate change from baseline, and it will calculate treatment +#' differences as differences between response values. #' #' 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 mapping in the #' model matrix that `brms` derives from the formula from `brm_formula()`. +#' @param role Deprecated as unnecessary on 2024-07-11 (version 1.0.1.9007). +#' Use `reference_time` to supply a baseline time point value if it exists. #' @param level_baseline Deprecated on 2024-01-11 (version 0.2.0.9002). #' Use `reference_time` instead. #' @param level_control Deprecated on 2024-01-11 (version 0.2.0.9002). @@ -114,7 +116,6 @@ #' brm_data( #' data = data, #' outcome = "col_response", -#' role = "response", #' group = "col_group", #' time = "col_time", #' patient = "col_patient", @@ -124,7 +125,6 @@ brm_data <- function( data, outcome, - role = "change", baseline = NULL, group, subgroup = NULL, @@ -135,10 +135,18 @@ brm_data <- function( reference_group, reference_subgroup = NULL, reference_time = NULL, + role = NULL, level_baseline = NULL, level_control = NULL ) { assert(is.data.frame(data), message = "data arg must be a data frame.") + if (!is.null(role)) { + brm_deprecate( + "The 'role' argument was deprecated as unnecessary on 2024-07-11 ", + "(version 1.0.1.9007). Use reference_time to specify a baseline ", + "time value if it exists." + ) + } if (!is.null(level_control)) { brm_deprecate( "level_control was deprecated on 2024-01-11 (version 0.2.0.9002). ", @@ -158,7 +166,6 @@ brm_data <- function( out <- brm_data_new( data = data, brm_outcome = as.character(outcome), - brm_role = as.character(role), brm_baseline = baseline, brm_group = as.character(group), brm_subgroup = subgroup, @@ -177,7 +184,6 @@ brm_data <- function( brm_data_new <- function( data, brm_outcome = NULL, - brm_role = NULL, brm_baseline = NULL, brm_group = NULL, brm_subgroup = NULL, @@ -193,7 +199,6 @@ brm_data_new <- function( structure( out, brm_outcome = brm_outcome, - brm_role = brm_role, brm_baseline = brm_baseline, brm_group = brm_group, brm_subgroup = brm_subgroup, @@ -220,7 +225,6 @@ brm_data_validate <- function(data) { #' @export brm_data_validate.default <- function(data) { outcome <- attr(data, "brm_outcome") - role <- attr(data, "brm_role") baseline <- attr(data, "brm_baseline") group <- attr(data, "brm_group") subgroup <- attr(data, "brm_subgroup") @@ -237,7 +241,6 @@ brm_data_validate.default <- function(data) { message = "please use brm_data() to preprocess your data" ) assert_chr(outcome, "outcome of data must be a nonempty character string") - assert_chr(role, "role of data must be a nonempty character string") assert_chr( baseline %|||% "x", "baseline must NULL or a nonempty character string" @@ -266,10 +269,6 @@ brm_data_validate.default <- function(data) { "in the data" ) ) - assert( - role %in% c("response", "change"), - message = "role must be either \"response\" or \"change\"" - ) assert_col(outcome, data) assert_col(baseline, data) assert_col(group, data) @@ -369,12 +368,6 @@ brm_data_validate.default <- function(data) { ) ) } - if (role == "change") { - assert( - is.null(reference_time), - message = "reference_time must be NULL if role is \"change\"." - ) - } } brm_data_fill <- function(data) { diff --git a/R/brm_data_change.R b/R/brm_data_change.R index 56e52cc8..6ec08d77 100644 --- a/R/brm_data_change.R +++ b/R/brm_data_change.R @@ -14,7 +14,8 @@ #' change from baseline will be missing if either the post-baseline response #' is missing or the baseline response is missing. #' @param data A classed `tibble` (e.g. from [brm_data()]) with raw response -#' as the outcome variable (role = `"response"` in [brm_data()]). +#' as the outcome variable and no baseline time point stored in the +#' attributes. #' @param name_change Character of length 1, name of the new outcome column #' for change from baseline. #' @param name_baseline Character of length 1, name of the new column for @@ -24,7 +25,6 @@ #' data <- brm_data( #' data = dplyr::rename(brm_simulate_simple()$data, y_values = response), #' outcome = "y_values", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", @@ -32,13 +32,11 @@ #' reference_time = "time_1" #' ) #' data -#' attr(data, "brm_role") #' attr(data, "brm_outcome") #' attr(data, "brm_baseline") #' attr(data, "brm_reference_time") #' changed <- brm_data_change(data = data, name_change = "delta") #' changed -#' attr(changed, "brm_role") #' attr(changed, "brm_outcome") #' attr(changed, "brm_baseline") #' attr(data, "brm_reference_time") @@ -55,11 +53,10 @@ brm_data_change <- function( ) ) assert( - attr(data, "brm_role") == "response", + !is.null(attr(data, "brm_reference_time")), message = paste( - "outcome variable must be raw response", - "(not change from baseline)", - "in the data supplied to brm_data_change()." + "In brm_data_change(), a baseline time point needs to exist.", + "It needs to have already been specified through brm_data()." ) ) assert_chr(name_change) @@ -101,7 +98,6 @@ brm_data_change <- function( brm_data( data = out, outcome = name_change, - role = "change", baseline = name_baseline, group = attr(data, "brm_group"), subgroup = attr(data, "brm_subgroup"), diff --git a/R/brm_formula.R b/R/brm_formula.R index 1d6a004e..52e12217 100644 --- a/R/brm_formula.R +++ b/R/brm_formula.R @@ -187,7 +187,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", @@ -371,7 +370,6 @@ brm_formula.default <- function( brm_formula_validate_correlation(correlation) brm_formula_sigma_validate(sigma) name_outcome <- attr(data, "brm_outcome") - name_role <- attr(data, "brm_role") name_baseline <- attr(data, "brm_baseline") name_group <- attr(data, "brm_group") name_subgroup <- attr(data, "brm_subgroup") diff --git a/R/brm_formula_sigma.R b/R/brm_formula_sigma.R index dcfe019a..7070ca21 100644 --- a/R/brm_formula_sigma.R +++ b/R/brm_formula_sigma.R @@ -76,7 +76,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", @@ -150,7 +149,6 @@ brm_formula_sigma <- function( baseline_time || covariates allow_effect_size <- !exclude_effect_size - name_role <- attr(data, "brm_role") name_baseline <- attr(data, "brm_baseline") name_group <- attr(data, "brm_group") name_subgroup <- attr(data, "brm_subgroup") diff --git a/R/brm_marginal_data.R b/R/brm_marginal_data.R index 29432ffc..4f6e62c6 100644 --- a/R/brm_marginal_data.R +++ b/R/brm_marginal_data.R @@ -34,7 +34,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_marginal_draws.R b/R/brm_marginal_draws.R index 52d5ffc4..dda16732 100644 --- a/R/brm_marginal_draws.R +++ b/R/brm_marginal_draws.R @@ -2,6 +2,16 @@ #' @export #' @family marginals #' @description Get marginal posterior draws from a fitted MMRM. +#' @section Baseline: +#' The returned values from [brm_marginal_draws()] +#' depend on whether a baseline time point +#' was declared through the `reference_time` argument of [brm_data()]. +#' If `reference_time` was not `NULL`, then [brm_marginal_draws()] will +#' calculate change from baseline, and it will calculate treatment +#' differences as differences between change-from-baseline values. +#' If `reference_time` was not `NULL`, then [brm_marginal_draws()] will +#' not calculate change from baseline, and it will calculate treatment +#' differences as differences between response values. #' @inheritSection brm_data Separation string #' @return A named list of tibbles of MCMC draws of the marginal posterior #' distribution of each treatment group and time point. These marginals @@ -19,15 +29,21 @@ #' not `NULL` (i.e. if a baseline value for the time variable #' was identified). #' * `difference_group`: treatment effect: -#' the `difference_time` at each active group minus the `difference_time` -#' at the control group (`reference_group`). -#' If `reference_time` was `NULL` in [brm_data()] (i.e. no baseline -#' time point), then treatment group -#' is instead the difference between `response` at each active group minus -#' the `response` at the control group. +#' These samples depend on the values of `reference_group` and +#' `reference_time` which were originally declared in [brm_data()]. +#' `reference_group` is the control group, and `reference_time` +#' is baseline. If baseline was originally given (via `reference_time` +#' in [brm_data()]), +#' then `difference_time` is the change-from-baseline value of +#' each active group minus that of the control group. +#' Otherwise, if baseline is omitted (i.e. `reference_time = NULL` +#' (default) in [brm_data()]), then `difference_time` is the +#' raw response at each active group minus that of the control group. #' * `difference_subgroup`: subgroup differences: the `difference_group` #' at each subgroup level minus the `difference_group` at the subgroup -#' reference level (`reference_subgroup`). +#' reference level (`reference_subgroup`). Only reported if a subgroup +#' analysis was specified through the appropriate arguments to +#' [brm_data()] and [brm_formula()]. #' * `effect`: effect size, defined as the treatment difference #' divided by the residual standard deviation. Omitted if #' the `effect_size` argument is `FALSE` or if the @@ -71,7 +87,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", @@ -143,7 +158,6 @@ brm_marginal_draws <- function( brm_data_validate(data) brm_formula_validate(formula) brm_model_validate(model) - role <- attr(data, "brm_role") base <- attr(data, "brm_base") group <- attr(data, "brm_group") subgroup <- attr(data, "brm_subgroup") @@ -161,7 +175,7 @@ brm_marginal_draws <- function( reference_subgroup <- attr(data, "brm_reference_subgroup") reference_time <- attr(data, "brm_reference_time") has_subgroup <- brm_has_subgroup(data = data, formula = formula) - has_baseline <- identical(role, "response") && !is.null(reference_time) + has_baseline <- !is.null(reference_time) if (effect_size && !attr(formula, "brm_allow_effect_size")) { effect_size <- FALSE brm_warn( @@ -197,7 +211,7 @@ brm_marginal_draws <- function( draws_response <- tibble::as_tibble(as.matrix(draws_beta) %*% t(transform)) draws_response <- dplyr::bind_cols(draws_response, index_mcmc) draws_response <- posterior::as_draws_df(draws_response) - if (has_baseline) { # baseline + if (has_baseline) { # baseline exists, subgroup exists if (has_subgroup) { draws_difference_time <- subtract_reference_time_subroup( draws = draws_response, @@ -220,7 +234,7 @@ brm_marginal_draws <- function( levels_time = setdiff(levels_time, reference_time), reference_subgroup = reference_subgroup ) - } else { # role is "response", no subgroup + } else { # baseline exists, no subgroup draws_difference_time <- subtract_reference_time( draws = draws_response, levels_group = levels_group, @@ -234,7 +248,7 @@ brm_marginal_draws <- function( reference_group = reference_group ) } - } else { # baseline does not exist + } else { # baseline does not exist, subgroup exists if (has_subgroup) { draws_difference_group <- subtract_reference_group_subgroup( draws = draws_response, @@ -250,7 +264,7 @@ brm_marginal_draws <- function( levels_time = levels_time, reference_subgroup = reference_subgroup ) - } else { # role is "change", no subgroup + } else { # baseline does not exist, no subgroup draws_difference_group <- subtract_reference_group( draws = draws_response, levels_group = levels_group, diff --git a/R/brm_marginal_draws_average.R b/R/brm_marginal_draws_average.R index cae894af..64d49f75 100644 --- a/R/brm_marginal_draws_average.R +++ b/R/brm_marginal_draws_average.R @@ -7,26 +7,10 @@ #' @return A named list of tibbles of MCMC draws of the marginal posterior #' distribution of each treatment group and time point #' (or group-by-subgroup-by-time, if applicable). -#' In each tibble, there is 1 row per posterior sample sand one column for -#' each type of marginal distribution (i.e. each combination of treatment -#' group and discrete time point. The specific `tibble`s in the returned -#' list are described below: -#' * `response`: on the scale of the response variable. -#' * `difference_time`: change from baseline: the -#' `response` at a particular time minus the `response` at baseline -#' (`reference_time`). -#' Only returned if the `role` argument of [brm_data()] was -#' `"response"`. (If `role` is `"change"`, then `response` already -#' represents change from baseline.) -#' * `difference_group`: treatment effect: the -#' the `difference_time` at each active group minus the `difference_time` -#' at the control group (`reference_group`). -#' If `role` is `"change"`, then treatment group -#' is instead the difference between `response` at each active group minus -#' the `response` at the control group. -#' * `difference_subgroup`: subgroup differences: the `difference_group` -#' at each subgroup level minus the `difference_group` at the subgroup -#' reference level (`reference_subgroup`). +#' See [brm_marginal_draws()] for the full details of the return value. +#' The only difference is that [brm_marginal_draws_average()] returns +#' a single pseudo-time-point to represent the average across +#' multiple real time points. #' @inheritParams brm_marginal_draws #' @param draws List of posterior draws from [brm_marginal_draws()]. #' @param times Character vector of discrete time point levels @@ -44,7 +28,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_marginal_probabilities.R b/R/brm_marginal_probabilities.R index 4a2bfd07..5a71749e 100644 --- a/R/brm_marginal_probabilities.R +++ b/R/brm_marginal_probabilities.R @@ -31,7 +31,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_marginal_summaries.R b/R/brm_marginal_summaries.R index fd240bf6..d066bbae 100644 --- a/R/brm_marginal_summaries.R +++ b/R/brm_marginal_summaries.R @@ -36,7 +36,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_model.R b/R/brm_model.R index c85bced5..d4d1139f 100644 --- a/R/brm_model.R +++ b/R/brm_model.R @@ -24,7 +24,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_plot_compare.R b/R/brm_plot_compare.R index 93b20411..25a64924 100644 --- a/R/brm_plot_compare.R +++ b/R/brm_plot_compare.R @@ -47,7 +47,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_plot_draws.R b/R/brm_plot_draws.R index f5cd1440..dab2ba44 100644 --- a/R/brm_plot_draws.R +++ b/R/brm_plot_draws.R @@ -23,7 +23,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/R/brm_simulate_outline.R b/R/brm_simulate_outline.R index bba52e03..d5dadc21 100644 --- a/R/brm_simulate_outline.R +++ b/R/brm_simulate_outline.R @@ -2,8 +2,8 @@ #' @export #' @family simulation #' @description Begin creating a simulated dataset. -#' @return A data frame from [brm_data()] with attributes to define roles -#' for various columns in the dataset. The data frame has one row per +#' @return A classed data frame from [brm_data()]. +#' The data frame has one row per #' patient per time point and the following columns: #' * `group`: integer index of the treatment group. #' * `patient`: integer index of the patient. @@ -84,7 +84,6 @@ brm_simulate_outline <- function( data <- brm_data( data = data, outcome = "response", - role = "response", baseline = NULL, group = "group", subgroup = if_any(is.null(n_subgroup), NULL, "subgroup"), diff --git a/R/brm_simulate_simple.R b/R/brm_simulate_simple.R index cb536219..af48010c 100644 --- a/R/brm_simulate_simple.R +++ b/R/brm_simulate_simple.R @@ -95,7 +95,6 @@ brm_simulate_simple <- function( data <- brm_data( data = data, outcome = "response", - role = "response", baseline = NULL, group = "group", time = "time", diff --git a/R/brm_transform_marginal.R b/R/brm_transform_marginal.R index 23bb6056..6eaaad6a 100644 --- a/R/brm_transform_marginal.R +++ b/R/brm_transform_marginal.R @@ -57,7 +57,6 @@ #' data <- brm_data( #' data = brm_simulate_simple()$data, #' outcome = "response", -#' role = "response", #' group = "group", #' time = "time", #' patient = "patient", diff --git a/man/brm_archetype_successive_cells.Rd b/man/brm_archetype_successive_cells.Rd index 330a29e1..c414c536 100644 --- a/man/brm_archetype_successive_cells.Rd +++ b/man/brm_archetype_successive_cells.Rd @@ -111,7 +111,7 @@ which express the marginal means \code{mu_gt} as follows: For group A, \code{beta_1} is the time 1 intercept, \code{beta_2} represents time 2 minus time 1, and \code{beta_3} represents time 3 minus time 2. -\code{beta_4}, \code{beta_5}, and \code{beta_6} represent the analogous roles. +\code{beta_4}, \code{beta_5}, and \code{beta_6} behave analogously for group B. } \section{Nuisance variables}{ diff --git a/man/brm_data.Rd b/man/brm_data.Rd index 2b5c7651..999912e1 100644 --- a/man/brm_data.Rd +++ b/man/brm_data.Rd @@ -7,7 +7,6 @@ brm_data( data, outcome, - role = "change", baseline = NULL, group, subgroup = NULL, @@ -18,6 +17,7 @@ brm_data( reference_group, reference_subgroup = NULL, reference_time = NULL, + role = NULL, level_baseline = NULL, level_control = NULL ) @@ -31,10 +31,6 @@ Example possibilities from clinical trial datasets include \code{"CHG"} and \code{"AVAL"}. The \code{outcome} column in the data should be a numeric vector.} -\item{role}{Character of length 1. Either \code{"response"} if \code{outcome} -is the raw response variable (e.g. AVAL) or \code{"change"} if \code{outcome} -is change from baseline (e.g. CHG).} - \item{baseline}{Character of length 1, name of the baseline response variable (for example, \code{"BASE"} in many clinical trial datasets). @@ -103,18 +99,24 @@ model matrix that \code{brms} derives from the formula from \code{brm_formula()} \item{reference_time}{Atomic value of length 1 or \code{NULL}, level of the \code{time} column to indicate the baseline time point. -This value must be \code{NULL} if the outcome -variable is already change from baseline. If the outcome -is raw response, then \code{reference_time} may or may not be \code{NULL}. -\code{\link[=brm_marginal_draws]{brm_marginal_draws()}} and downstream functions calculate posterior -inference on change from baseline if and only if -\code{reference_time} is not \code{NULL}. +Leave as \code{NULL} if there is no baseline or baseline is not included +in \code{data[[time]]}. + +If \code{reference_time} is not \code{NULL}, then \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} will +calculate change from baseline, and it will calculate treatment +differences as differences between change-from-baseline values. +If \code{reference_time} is not \code{NULL}, then \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} will +not calculate change from baseline, and it will calculate treatment +differences as differences between response values. Note: \code{reference_time} only applies to the post-processing that happens in functions like \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} downstream of the model. It does not control the fixed effect mapping in the model matrix that \code{brms} derives from the formula from \code{brm_formula()}.} +\item{role}{Deprecated as unnecessary on 2024-07-11 (version 1.0.1.9007). +Use \code{reference_time} to supply a baseline time point value if it exists.} + \item{level_baseline}{Deprecated on 2024-01-11 (version 0.2.0.9002). Use \code{reference_time} instead.} @@ -163,7 +165,6 @@ data brm_data( data = data, outcome = "col_response", - role = "response", group = "col_group", time = "col_time", patient = "col_patient", diff --git a/man/brm_data_change.Rd b/man/brm_data_change.Rd index 81545ea2..bae89eed 100644 --- a/man/brm_data_change.Rd +++ b/man/brm_data_change.Rd @@ -8,7 +8,8 @@ brm_data_change(data, name_change = "change", name_baseline = "baseline") } \arguments{ \item{data}{A classed \code{tibble} (e.g. from \code{\link[=brm_data]{brm_data()}}) with raw response -as the outcome variable (role = \code{"response"} in \code{\link[=brm_data]{brm_data()}}).} +as the outcome variable and no baseline time point stored in the +attributes.} \item{name_change}{Character of length 1, name of the new outcome column for change from baseline.} @@ -37,7 +38,6 @@ set.seed(0) data <- brm_data( data = dplyr::rename(brm_simulate_simple()$data, y_values = response), outcome = "y_values", - role = "response", group = "group", time = "time", patient = "patient", @@ -45,13 +45,11 @@ data <- brm_data( reference_time = "time_1" ) data -attr(data, "brm_role") attr(data, "brm_outcome") attr(data, "brm_baseline") attr(data, "brm_reference_time") changed <- brm_data_change(data = data, name_change = "delta") changed -attr(changed, "brm_role") attr(changed, "brm_outcome") attr(changed, "brm_baseline") attr(data, "brm_reference_time") diff --git a/man/brm_formula.Rd b/man/brm_formula.Rd index 0869a7a3..1d2acfe3 100644 --- a/man/brm_formula.Rd +++ b/man/brm_formula.Rd @@ -281,7 +281,6 @@ set.seed(0) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_formula_sigma.Rd b/man/brm_formula_sigma.Rd index cd00aab7..dc9d9046 100644 --- a/man/brm_formula_sigma.Rd +++ b/man/brm_formula_sigma.Rd @@ -121,7 +121,6 @@ set.seed(0) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_marginal_data.Rd b/man/brm_marginal_data.Rd index 9bea05fb..a3090fea 100644 --- a/man/brm_marginal_data.Rd +++ b/man/brm_marginal_data.Rd @@ -55,7 +55,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_marginal_draws.Rd b/man/brm_marginal_draws.Rd index 5a73d237..263da592 100644 --- a/man/brm_marginal_draws.Rd +++ b/man/brm_marginal_draws.Rd @@ -80,15 +80,21 @@ Only returned if the \code{reference_time} argument of \code{\link[=brm_data]{br not \code{NULL} (i.e. if a baseline value for the time variable was identified). \item \code{difference_group}: treatment effect: -the \code{difference_time} at each active group minus the \code{difference_time} -at the control group (\code{reference_group}). -If \code{reference_time} was \code{NULL} in \code{\link[=brm_data]{brm_data()}} (i.e. no baseline -time point), then treatment group -is instead the difference between \code{response} at each active group minus -the \code{response} at the control group. +These samples depend on the values of \code{reference_group} and +\code{reference_time} which were originally declared in \code{\link[=brm_data]{brm_data()}}. +\code{reference_group} is the control group, and \code{reference_time} +is baseline. If baseline was originally given (via \code{reference_time} +in \code{\link[=brm_data]{brm_data()}}), +then \code{difference_time} is the change-from-baseline value of +each active group minus that of the control group. +Otherwise, if baseline is omitted (i.e. \code{reference_time = NULL} +(default) in \code{\link[=brm_data]{brm_data()}}), then \code{difference_time} is the +raw response at each active group minus that of the control group. \item \code{difference_subgroup}: subgroup differences: the \code{difference_group} at each subgroup level minus the \code{difference_group} at the subgroup -reference level (\code{reference_subgroup}). +reference level (\code{reference_subgroup}). Only reported if a subgroup +analysis was specified through the appropriate arguments to +\code{\link[=brm_data]{brm_data()}} and \code{\link[=brm_formula]{brm_formula()}}. \item \code{effect}: effect size, defined as the treatment difference divided by the residual standard deviation. Omitted if the \code{effect_size} argument is \code{FALSE} or if the @@ -102,6 +108,19 @@ the \code{effect_size} argument is \code{FALSE} or if the \description{ Get marginal posterior draws from a fitted MMRM. } +\section{Baseline}{ + +The returned values from \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} +depend on whether a baseline time point +was declared through the \code{reference_time} argument of \code{\link[=brm_data]{brm_data()}}. +If \code{reference_time} was not \code{NULL}, then \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} will +calculate change from baseline, and it will calculate treatment +differences as differences between change-from-baseline values. +If \code{reference_time} was not \code{NULL}, then \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} will +not calculate change from baseline, and it will calculate treatment +differences as differences between response values. +} + \section{Separation string}{ Post-processing in \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} names each of the @@ -118,7 +137,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_marginal_draws_average.Rd b/man/brm_marginal_draws_average.Rd index ac7f271a..2bf055cb 100644 --- a/man/brm_marginal_draws_average.Rd +++ b/man/brm_marginal_draws_average.Rd @@ -27,28 +27,10 @@ after the label and time points are sanitized.} A named list of tibbles of MCMC draws of the marginal posterior distribution of each treatment group and time point (or group-by-subgroup-by-time, if applicable). -In each tibble, there is 1 row per posterior sample sand one column for -each type of marginal distribution (i.e. each combination of treatment -group and discrete time point. The specific \code{tibble}s in the returned -list are described below: -\itemize{ -\item \code{response}: on the scale of the response variable. -\item \code{difference_time}: change from baseline: the -\code{response} at a particular time minus the \code{response} at baseline -(\code{reference_time}). -Only returned if the \code{role} argument of \code{\link[=brm_data]{brm_data()}} was -\code{"response"}. (If \code{role} is \code{"change"}, then \code{response} already -represents change from baseline.) -\item \code{difference_group}: treatment effect: the -the \code{difference_time} at each active group minus the \code{difference_time} -at the control group (\code{reference_group}). -If \code{role} is \code{"change"}, then treatment group -is instead the difference between \code{response} at each active group minus -the \code{response} at the control group. -\item \code{difference_subgroup}: subgroup differences: the \code{difference_group} -at each subgroup level minus the \code{difference_group} at the subgroup -reference level (\code{reference_subgroup}). -} +See \code{\link[=brm_marginal_draws]{brm_marginal_draws()}} for the full details of the return value. +The only difference is that \code{\link[=brm_marginal_draws_average]{brm_marginal_draws_average()}} returns +a single pseudo-time-point to represent the average across +multiple real time points. } \description{ Simple un-weighted arithmetic mean of @@ -70,7 +52,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_marginal_probabilities.Rd b/man/brm_marginal_probabilities.Rd index 3660fc67..c1985098 100644 --- a/man/brm_marginal_probabilities.Rd +++ b/man/brm_marginal_probabilities.Rd @@ -45,7 +45,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_marginal_summaries.Rd b/man/brm_marginal_summaries.Rd index f331face..f051e2ca 100644 --- a/man/brm_marginal_summaries.Rd +++ b/man/brm_marginal_summaries.Rd @@ -50,7 +50,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_model.Rd b/man/brm_model.Rd index cce7089e..4bbb4066 100644 --- a/man/brm_model.Rd +++ b/man/brm_model.Rd @@ -59,7 +59,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_plot_compare.Rd b/man/brm_plot_compare.Rd index 6c33952f..56aedbf7 100644 --- a/man/brm_plot_compare.Rd +++ b/man/brm_plot_compare.Rd @@ -70,7 +70,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_plot_draws.Rd b/man/brm_plot_draws.Rd index 8d5b524a..b312f18b 100644 --- a/man/brm_plot_draws.Rd +++ b/man/brm_plot_draws.Rd @@ -36,7 +36,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/man/brm_simulate_outline.Rd b/man/brm_simulate_outline.Rd index 52fa1945..2eb07ef7 100644 --- a/man/brm_simulate_outline.Rd +++ b/man/brm_simulate_outline.Rd @@ -43,8 +43,8 @@ outcomes that are missing. Missing outcomes of this type are independent and uniformly distributed across the data.} } \value{ -A data frame from \code{\link[=brm_data]{brm_data()}} with attributes to define roles -for various columns in the dataset. The data frame has one row per +A classed data frame from \code{\link[=brm_data]{brm_data()}}. +The data frame has one row per patient per time point and the following columns: \itemize{ \item \code{group}: integer index of the treatment group. diff --git a/man/brm_transform_marginal.Rd b/man/brm_transform_marginal.Rd index c080fbd0..ba24deaf 100644 --- a/man/brm_transform_marginal.Rd +++ b/man/brm_transform_marginal.Rd @@ -84,7 +84,6 @@ set.seed(0L) data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", From 2504f94bd2cf1b950f4da5004751fd2eaadea9f1 Mon Sep 17 00:00:00 2001 From: wlandau Date: Thu, 11 Jul 2024 13:19:16 -0400 Subject: [PATCH 2/4] Remove role attribute from vignettes --- vignettes/archetypes.Rmd | 1 - vignettes/archetypes.Rmd.source | 1 - vignettes/bcva.Rmd | 1 - vignettes/bcva.Rmd.source | 1 - vignettes/fev1.Rmd | 1 - vignettes/fev1.Rmd.source | 1 - vignettes/subgroup.Rmd | 2 -- vignettes/subgroup.Rmd.source | 1 - vignettes/usage.Rmd | 12 +++++------- vignettes/usage.Rmd.source | 11 +++++------ 10 files changed, 10 insertions(+), 22 deletions(-) diff --git a/vignettes/archetypes.Rmd b/vignettes/archetypes.Rmd index a2e66fec..fad3122b 100644 --- a/vignettes/archetypes.Rmd +++ b/vignettes/archetypes.Rmd @@ -35,7 +35,6 @@ data(fev_data, package = "mmrm") data <- fev_data |> brm_data( outcome = "FEV1", - role = "response", group = "ARMCD", time = "AVISIT", patient = "USUBJID", diff --git a/vignettes/archetypes.Rmd.source b/vignettes/archetypes.Rmd.source index 43895fcb..a154d0eb 100644 --- a/vignettes/archetypes.Rmd.source +++ b/vignettes/archetypes.Rmd.source @@ -44,7 +44,6 @@ data(fev_data, package = "mmrm") data <- fev_data |> brm_data( outcome = "FEV1", - role = "response", group = "ARMCD", time = "AVISIT", patient = "USUBJID", diff --git a/vignettes/bcva.Rmd b/vignettes/bcva.Rmd index bfe023a4..1d96369e 100644 --- a/vignettes/bcva.Rmd +++ b/vignettes/bcva.Rmd @@ -88,7 +88,6 @@ The rest of the pre-processing steps create factors for the study arm and visit + mutate(AVISIT = gsub("VIS0*", "VIS", as.character(AVISIT))) |> + brm_data( + outcome = "BCVA_CHG", -+ role = "change", + group = "ARMCD", + time = "AVISIT", + patient = "USUBJID", diff --git a/vignettes/bcva.Rmd.source b/vignettes/bcva.Rmd.source index 7ce26d02..c5c301eb 100644 --- a/vignettes/bcva.Rmd.source +++ b/vignettes/bcva.Rmd.source @@ -100,7 +100,6 @@ bcva_data <- bcva_data |> mutate(AVISIT = gsub("VIS0*", "VIS", as.character(AVISIT))) |> brm_data( outcome = "BCVA_CHG", - role = "change", group = "ARMCD", time = "AVISIT", patient = "USUBJID", diff --git a/vignettes/fev1.Rmd b/vignettes/fev1.Rmd index 3c2a7dfd..8911dd88 100644 --- a/vignettes/fev1.Rmd +++ b/vignettes/fev1.Rmd @@ -100,7 +100,6 @@ The rest of the pre-processing steps create factors for the study arm and visit > fev_data <- brm_data( + data = fev_data, + outcome = "FEV1_CHG", -+ role = "change", + group = "ARMCD", + time = "AVISIT", + patient = "USUBJID", diff --git a/vignettes/fev1.Rmd.source b/vignettes/fev1.Rmd.source index 331e07f2..dea85627 100644 --- a/vignettes/fev1.Rmd.source +++ b/vignettes/fev1.Rmd.source @@ -111,7 +111,6 @@ The rest of the pre-processing steps create factors for the study arm and visit fev_data <- brm_data( data = fev_data, outcome = "FEV1_CHG", - role = "change", group = "ARMCD", time = "AVISIT", patient = "USUBJID", diff --git a/vignettes/subgroup.Rmd b/vignettes/subgroup.Rmd index c510db71..773a35fa 100644 --- a/vignettes/subgroup.Rmd +++ b/vignettes/subgroup.Rmd @@ -88,7 +88,6 @@ When you create the special classed dataset for `brms.mmrm` using `brm_data()`, data <- brm_data( data = raw_data, outcome = "response", - role = "response", baseline = NULL, group = "group", subgroup = "subgroup", @@ -108,7 +107,6 @@ str(data) #> $ missing : logi [1:900] FALSE FALSE FALSE FALSE FALSE FALSE ... #> $ response: num [1:900] 1.263 -0.326 1.33 1.272 0.415 ... #> - attr(*, "brm_outcome")= chr "response" -#> - attr(*, "brm_role")= chr "response" #> - attr(*, "brm_group")= chr "group" #> - attr(*, "brm_subgroup")= chr "subgroup" #> - attr(*, "brm_time")= chr "time" diff --git a/vignettes/subgroup.Rmd.source b/vignettes/subgroup.Rmd.source index 841587f3..dcba82d1 100644 --- a/vignettes/subgroup.Rmd.source +++ b/vignettes/subgroup.Rmd.source @@ -62,7 +62,6 @@ When you create the special classed dataset for `brms.mmrm` using `brm_data()`, data <- brm_data( data = raw_data, outcome = "response", - role = "response", baseline = NULL, group = "group", subgroup = "subgroup", diff --git a/vignettes/usage.Rmd b/vignettes/usage.Rmd index 7470411a..ef9759ff 100644 --- a/vignettes/usage.Rmd +++ b/vignettes/usage.Rmd @@ -71,7 +71,6 @@ Next, create a special classed dataset that the package will recognize. The clas data <- brm_data( data = raw_data, outcome = "response", - role = "response", group = "group", patient = "patient", time = "time", @@ -99,13 +98,12 @@ data class(data) #> [1] "brms_mmrm_data" "tbl_df" "tbl" "data.frame" -roles <- attributes(data) -roles$row.names <- NULL -str(roles) +attributes <- attributes(data) +attributes$row.names <- NULL +str(attributes) #> List of 10 #> $ names : chr [1:7] "patient" "time" "response" "group" ... #> $ brm_outcome : chr "response" -#> $ brm_role : chr "response" #> $ brm_group : chr "group" #> $ brm_time : chr "time" #> $ brm_patient : chr "patient" @@ -381,8 +379,8 @@ model$brms.mmrm_formula Regardless of the choice of fixed effects formula, `brms.mmrm` performs inference on the marginal distributions at each treatment group and time point of the mean of the following quantities: 1. Response. -2. Change from baseline, if you set `role` to `"change"` in `brm_data()`. -3. Treatment difference, in terms of change from baseline. +2. Change from baseline. Only reported if you originally declared a baseline time point with the `reference_time` argument of `brm_data()`. +3. Treatment difference. If you declared a baseline in (2), then treatment difference is calculated in terms of change from baseline. Otherwise, it is calculated in terms of raw response. 4. Effect size: treatment difference divided by the residual standard deviation. To derive posterior draws of these marginals, use the `brm_marginal_draws()` function. diff --git a/vignettes/usage.Rmd.source b/vignettes/usage.Rmd.source index 97375df6..cab8dae1 100644 --- a/vignettes/usage.Rmd.source +++ b/vignettes/usage.Rmd.source @@ -61,7 +61,6 @@ Next, create a special classed dataset that the package will recognize. The clas data <- brm_data( data = raw_data, outcome = "response", - role = "response", group = "group", patient = "patient", time = "time", @@ -74,9 +73,9 @@ data class(data) -roles <- attributes(data) -roles$row.names <- NULL -str(roles) +attributes <- attributes(data) +attributes$row.names <- NULL +str(attributes) ``` # Formula @@ -183,8 +182,8 @@ model$brms.mmrm_formula Regardless of the choice of fixed effects formula, `brms.mmrm` performs inference on the marginal distributions at each treatment group and time point of the mean of the following quantities: 1. Response. -2. Change from baseline, if you set `role` to `"change"` in `brm_data()`. -3. Treatment difference, in terms of change from baseline. +2. Change from baseline. Only reported if you originally declared a baseline time point with the `reference_time` argument of `brm_data()`. +3. Treatment difference. If you declared a baseline in (2), then treatment difference is calculated in terms of change from baseline. Otherwise, it is calculated in terms of raw response. 4. Effect size: treatment difference divided by the residual standard deviation. To derive posterior draws of these marginals, use the `brm_marginal_draws()` function. From f58b5504dbd75252332270ef011bedb1756636a5 Mon Sep 17 00:00:00 2001 From: wlandau Date: Thu, 11 Jul 2024 13:22:42 -0400 Subject: [PATCH 3/4] update a test --- tests/testthat/test-brm_data.R | 78 ++++++++++++++++++++++++++-------- 1 file changed, 61 insertions(+), 17 deletions(-) diff --git a/tests/testthat/test-brm_data.R b/tests/testthat/test-brm_data.R index 06be6e84..cbbb6b10 100644 --- a/tests/testthat/test-brm_data.R +++ b/tests/testthat/test-brm_data.R @@ -16,7 +16,6 @@ test_that("brm_data() response", { out <- brm_data( data = data, outcome = "col_response", - role = "response", group = "col_group", time = "col_time", patient = "col_patient", @@ -61,7 +60,6 @@ test_that("brm_data() response", { expect_equal(out$col_patient, out$col_factor2) expect_equal(out$col_patient, out$col_factor3) expect_equal(attr(out, "brm_outcome"), "col_response") - expect_equal(attr(out, "brm_role"), "response") expect_equal(attr(out, "brm_group"), "col_group") expect_null(attr(out, "brm_subgroup")) expect_equal(attr(out, "brm_time"), "col_time") @@ -95,7 +93,6 @@ test_that("brm_data() response with subgroup", { brm_data( data = data, outcome = "col_response", - role = "response", group = "col_group", subgroup = "col_subgroup", time = "col_time", @@ -110,7 +107,6 @@ test_that("brm_data() response with subgroup", { out <- brm_data( data = data, outcome = "col_response", - role = "response", group = "col_group", subgroup = "col_subgroup", time = "col_time", @@ -184,7 +180,6 @@ test_that("brm_data() response with subgroup", { expect_equal(out$col_patient, out$col_factor2) expect_equal(out$col_patient, out$col_factor3) expect_equal(attr(out, "brm_outcome"), "col_response") - expect_equal(attr(out, "brm_role"), "response") expect_equal(attr(out, "brm_group"), "col_group") expect_equal(attr(out, "brm_subgroup"), "col_subgroup") expect_equal(attr(out, "brm_time"), "col_time") @@ -214,7 +209,6 @@ test_that("brm_data() change", { out <- brm_data( data = data, outcome = "col_response", - role = "change", group = "col_group", time = "col_time", patient = "col_patient", @@ -254,7 +248,6 @@ test_that("brm_data() change", { sort(c(data$col_response)) ) expect_equal(attr(out, "brm_outcome"), "col_response") - expect_equal(attr(out, "brm_role"), "change") expect_equal(attr(out, "brm_group"), "col_group") expect_equal(attr(out, "brm_time"), "col_time") expect_equal(attr(out, "brm_patient"), "col_patient") @@ -264,7 +257,7 @@ test_that("brm_data() change", { expect_null(attr(out, "brm_reference_time")) }) -test_that("brm_data() bad role", { +test_that("brm_data() bad reference_time", { set.seed(0) sim <- brm_simulate_simple() data <- tibble::as_tibble(sim$data) @@ -277,17 +270,28 @@ test_that("brm_data() bad role", { expect_error( brm_data( data = data, - outcome = "response", - role = "nope", + outcome = "col_response", group = "col_group", time = "col_time", patient = "col_patient", covariates = c("col_factor2", "col_factor3"), - reference_group = "group 1", - reference_time = "time 1" + reference_group = "group_1", + reference_time = "time_nope" ), class = "brm_error" ) + expect_silent( + brm_data( + data = data, + outcome = "col_response", + group = "col_group", + time = "col_time", + patient = "col_patient", + covariates = c("col_factor2", "col_factor3"), + reference_group = "group_1", + reference_time = "time_1" + ) + ) }) test_that("brm_data() bad group", { @@ -304,7 +308,6 @@ test_that("brm_data() bad group", { brm_data( data = data, outcome = "col_response", - role = "response", group = "nope", time = "col_time", patient = "col_patient", @@ -330,7 +333,6 @@ test_that("brm_data() levels", { brm_data( data = data, outcome = "col_response", - role = "response", group = "nope", time = "col_time", patient = "col_patient", @@ -357,7 +359,6 @@ test_that("brm_data() deprecate level_control", { brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -374,7 +375,6 @@ test_that("brm_data() deprecate level_baseline", { brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -397,7 +397,6 @@ test_that("brm_data() ordered factor contrasts", { out <- brm_data( data = data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -409,3 +408,48 @@ test_that("brm_data() ordered factor contrasts", { sort(c("(Intercept)", "time2", "time3", "time4")) ) }) + +test_that("deprecate role argument", { + set.seed(0) + sim <- brm_simulate_simple() + data <- tibble::as_tibble(sim$data) + for (field in c("group", "time", "patient")) { + data[[field]] <- gsub("_", " ", data[[field]]) + } + data$group <- as.factor(data$group) + data$factor1 <- data$patient + data$factor2 <- data$patient + data$factor3 <- data$patient + colnames(data) <- paste0("col_", colnames(data)) + data <- data[- c(2L, 3L), ] + data <- data[sample.int(n = nrow(data)), ] + data$col_missing <- FALSE + expect_warning( + out <- brm_data( + data = data, + outcome = "col_response", + role = "response", + group = "col_group", + time = "col_time", + patient = "col_patient", + covariates = c("col_factor2", "col_factor3"), + reference_group = "group 1", + reference_time = "time 1", + missing = "col_missing" + ), + class = "brm_deprecate" + ) + expect_silent( + out <- brm_data( + data = data, + outcome = "col_response", + group = "col_group", + time = "col_time", + patient = "col_patient", + covariates = c("col_factor2", "col_factor3"), + reference_group = "group 1", + reference_time = "time 1", + missing = "col_missing" + ) + ) +}) From 3fe397afbf1da2b11883239b66d1e3acd322bc32 Mon Sep 17 00:00:00 2001 From: wlandau Date: Thu, 11 Jul 2024 13:38:37 -0400 Subject: [PATCH 4/4] Update tests --- tests/testthat/test-brm_data_change.R | 8 -------- tests/testthat/test-brm_formula.R | 9 --------- tests/testthat/test-brm_formula_deprecated.R | 8 -------- tests/testthat/test-brm_formula_sigma.R | 5 ----- tests/testthat/test-brm_marginal_data.R | 2 -- tests/testthat/test-brm_marginal_draws.R | 3 --- tests/testthat/test-brm_marginal_draws_average.R | 1 - tests/testthat/test-brm_marginal_grid.R | 2 -- tests/testthat/test-brm_marginal_probabilities.R | 2 -- tests/testthat/test-brm_marginal_summaries.R | 2 -- tests/testthat/test-brm_model.R | 1 - tests/testthat/test-brm_plot_compare.R | 1 - tests/testthat/test-brm_plot_draws.R | 1 - tests/testthat/test-brm_transform_marginal.R | 4 ---- tests/testthat/test-utils_data.R | 2 -- 15 files changed, 51 deletions(-) diff --git a/tests/testthat/test-brm_data_change.R b/tests/testthat/test-brm_data_change.R index e997cf20..dd539135 100644 --- a/tests/testthat/test-brm_data_change.R +++ b/tests/testthat/test-brm_data_change.R @@ -5,7 +5,6 @@ test_that("brm_data_change()", { data <- brm_data( data = data, outcome = "y_values", - role = "response", group = "group", time = "time", missing = "missing", @@ -13,7 +12,6 @@ test_that("brm_data_change()", { reference_group = "group_1", reference_time = "time_1" ) - expect_equal(attr(data, "brm_role"), "response") expect_equal(attr(data, "brm_outcome"), "y_values") expect_null(attr(data, "brm_baseline")) expect_equal(attr(data, "brm_reference_time"), "time_1") @@ -29,7 +27,6 @@ test_that("brm_data_change()", { sub2 <- changed[changed$time == time, ] expect_true(all(sub2$missing == base$missing | sub1$missing)) } - expect_equal(attr(changed, "brm_role"), "change") expect_equal(attr(changed, "brm_outcome"), "delta") expect_equal(attr(changed, "brm_baseline"), "base") expect_null(attr(changed, "brm_reference_time")) @@ -54,14 +51,12 @@ test_that("brm_data_change()", { data <- brm_data( data = dplyr::rename(brm_simulate_simple()$data, y_values = response), outcome = "y_values", - role = "response", group = "group", time = "time", patient = "patient", reference_group = "group_1", reference_time = "time_1" ) - expect_equal(attr(data, "brm_role"), "response") expect_equal(attr(data, "brm_outcome"), "y_values") expect_null(attr(data, "brm_baseline")) expect_equal(attr(data, "brm_reference_time"), "time_1") @@ -70,7 +65,6 @@ test_that("brm_data_change()", { name_change = "delta", name_baseline = "base" ) - expect_equal(attr(changed, "brm_role"), "change") expect_equal(attr(changed, "brm_outcome"), "delta") expect_equal(attr(changed, "brm_baseline"), "base") expect_null(attr(changed, "brm_reference_time")) @@ -95,14 +89,12 @@ test_that("brm_data_change() assertions", { data <- brm_data( data = dplyr::rename(brm_simulate_simple()$data, y_values = response), outcome = "y_values", - role = "response", group = "group", time = "time", patient = "patient", reference_group = "group_1", reference_time = "time_1" ) - expect_equal(attr(data, "brm_role"), "response") expect_equal(attr(data, "brm_outcome"), "y_values") expect_null(attr(data, "brm_baseline")) expect_equal(attr(data, "brm_reference_time"), "time_1") diff --git a/tests/testthat/test-brm_formula.R b/tests/testthat/test-brm_formula.R index 62a5adb0..9a81ad56 100644 --- a/tests/testthat/test-brm_formula.R +++ b/tests/testthat/test-brm_formula.R @@ -8,7 +8,6 @@ test_that("brm_formula() with default names and all non-subgroup terms", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -66,7 +65,6 @@ test_that("brm_formula() same with homogeneous variance", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -116,7 +114,6 @@ test_that("brm_formula() different correlation structures", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -269,7 +266,6 @@ test_that("brm_formula() with default names and all terms", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", subgroup = "subgroup", time = "AVISIT", @@ -323,7 +319,6 @@ test_that("brm_formula() with all user-supplied columns, all non-sub terms", { a = c(1, 2) ), outcome = "y", - role = "change", group = "g", time = "t", baseline = "b", @@ -364,7 +359,6 @@ test_that("brm_formula() with one user-supplied column, all non-sub terms", { a = c(1, 2) ), outcome = "y", - role = "change", group = "g", time = "t", baseline = "b", @@ -405,7 +399,6 @@ test_that("brm_formula() omitting covariates", { a = c(1, 2) ), outcome = "y", - role = "change", group = "g", time = "t", baseline = "b", @@ -448,7 +441,6 @@ test_that("brm_formula() with all user-supplied columns, all terms", { a = c(1, 2) ), outcome = "y", - role = "change", group = "g", subgroup = "s", time = "t", @@ -500,7 +492,6 @@ test_that("brm_formula() with individual terms", { SUBGROUP = c("x", "y") ), outcome = "CHG", - role = "change", group = "GROUP", subgroup = "SUBGROUP", time = "TIME", diff --git a/tests/testthat/test-brm_formula_deprecated.R b/tests/testthat/test-brm_formula_deprecated.R index 6c3b7985..82f11dec 100644 --- a/tests/testthat/test-brm_formula_deprecated.R +++ b/tests/testthat/test-brm_formula_deprecated.R @@ -8,7 +8,6 @@ test_that("brm_formula() with default names and all terms", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -57,7 +56,6 @@ test_that("brm_formula() with all user-supplied columns and all terms", { a = c(1, 2) ), outcome = "y", - role = "change", group = "g", time = "t", baseline = "b", @@ -102,7 +100,6 @@ test_that("brm_formula() without intercept", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -149,7 +146,6 @@ test_that("brm_formula() without group effect", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -196,7 +192,6 @@ test_that("brm_formula() without time effect", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -243,7 +238,6 @@ test_that("brm_formula() without baseline effect", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -290,7 +284,6 @@ test_that("brm_formula() without baseline interaction", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -337,7 +330,6 @@ test_that("brm_formula() without group interaction", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", diff --git a/tests/testthat/test-brm_formula_sigma.R b/tests/testthat/test-brm_formula_sigma.R index 373615bb..d78bcb42 100644 --- a/tests/testthat/test-brm_formula_sigma.R +++ b/tests/testthat/test-brm_formula_sigma.R @@ -8,7 +8,6 @@ test_that("brm_formula_sigma() with default names and all non-subgroup terms", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -57,7 +56,6 @@ test_that("brm_formula_sigma() same with homogeneous variance", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", time = "AVISIT", baseline = "baseline", @@ -91,7 +89,6 @@ test_that("brm_formula_sigma() with default names and terms", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", subgroup = "subgroup", time = "AVISIT", @@ -118,7 +115,6 @@ test_that("brm_formula_sigma() with default names and terms, subgroup", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", subgroup = "subgroup", time = "AVISIT", @@ -149,7 +145,6 @@ test_that("brm_formula_sigma() brm_allow_effect_size", { USUBJID = c("x", "y") ), outcome = "CHG", - role = "change", group = "TRT01P", subgroup = "subgroup", time = "AVISIT", diff --git a/tests/testthat/test-brm_marginal_data.R b/tests/testthat/test-brm_marginal_data.R index 4cb0a016..5fb58aa3 100644 --- a/tests/testthat/test-brm_marginal_data.R +++ b/tests/testthat/test-brm_marginal_data.R @@ -3,7 +3,6 @@ test_that("brm_marginal_data()", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -56,7 +55,6 @@ test_that("brm_marginal_data() subgroup", { tibble::tibble(subgroup = c("subgroup_1", "subgroup_2")) ), outcome = "response", - role = "response", group = "group", subgroup = "subgroup", time = "time", diff --git a/tests/testthat/test-brm_marginal_draws.R b/tests/testthat/test-brm_marginal_draws.R index c2f3c411..743b95fb 100644 --- a/tests/testthat/test-brm_marginal_draws.R +++ b/tests/testthat/test-brm_marginal_draws.R @@ -4,7 +4,6 @@ test_that("brm_marginal_draws() on response, no subgroup", { data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -139,7 +138,6 @@ test_that("brm_marginal_draws() on response without baseline", { data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -340,7 +338,6 @@ test_that("brm_marginal_draws() on change, homogeneous var, no subgroup", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "change", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_marginal_draws_average.R b/tests/testthat/test-brm_marginal_draws_average.R index 266df189..1568cb7b 100644 --- a/tests/testthat/test-brm_marginal_draws_average.R +++ b/tests/testthat/test-brm_marginal_draws_average.R @@ -4,7 +4,6 @@ test_that("brm_marginal_draws_average() non-subgroup", { data <- brm_data( data = brm_simulate_simple()$data, outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_marginal_grid.R b/tests/testthat/test-brm_marginal_grid.R index 6482a568..014c5ce2 100644 --- a/tests/testthat/test-brm_marginal_grid.R +++ b/tests/testthat/test-brm_marginal_grid.R @@ -4,7 +4,6 @@ test_that("brm_marginal_grid() non-subgroup", { data <- brm_data( data = fev_data, outcome = "FEV1", - role = "response", group = "ARMCD", time = "AVISIT", patient = "USUBJID", @@ -45,7 +44,6 @@ test_that("brm_marginal_grid() subgroup", { data <- brm_data( data = fev_data, outcome = "FEV1", - role = "response", group = "ARMCD", subgroup = "SEX", time = "AVISIT", diff --git a/tests/testthat/test-brm_marginal_probabilities.R b/tests/testthat/test-brm_marginal_probabilities.R index 8010c194..aed15fac 100644 --- a/tests/testthat/test-brm_marginal_probabilities.R +++ b/tests/testthat/test-brm_marginal_probabilities.R @@ -4,7 +4,6 @@ test_that("brm_marginal_probabilities() on response", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -70,7 +69,6 @@ test_that("brm_marginal_probabilities() on change and multiple probs", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "change", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_marginal_summaries.R b/tests/testthat/test-brm_marginal_summaries.R index 06e07167..954fef1e 100644 --- a/tests/testthat/test-brm_marginal_summaries.R +++ b/tests/testthat/test-brm_marginal_summaries.R @@ -4,7 +4,6 @@ test_that("brm_marginal_summaries() on response", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", @@ -269,7 +268,6 @@ test_that("brm_marginal_summaries() on change", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "change", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_model.R b/tests/testthat/test-brm_model.R index fa227a89..358d7d52 100644 --- a/tests/testthat/test-brm_model.R +++ b/tests/testthat/test-brm_model.R @@ -4,7 +4,6 @@ test_that("brm_model() runs", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_plot_compare.R b/tests/testthat/test-brm_plot_compare.R index 454bc99c..22e88e6b 100644 --- a/tests/testthat/test-brm_plot_compare.R +++ b/tests/testthat/test-brm_plot_compare.R @@ -4,7 +4,6 @@ test_that("brm_plot_compare() without subgroup", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_plot_draws.R b/tests/testthat/test-brm_plot_draws.R index e63ad1c0..8f8aea7b 100644 --- a/tests/testthat/test-brm_plot_draws.R +++ b/tests/testthat/test-brm_plot_draws.R @@ -4,7 +4,6 @@ test_that("brm_plot_draws() without subgroup", { data <- brm_data( data = tibble::as_tibble(brm_simulate_simple()$data), outcome = "response", - role = "response", group = "group", time = "time", patient = "patient", diff --git a/tests/testthat/test-brm_transform_marginal.R b/tests/testthat/test-brm_transform_marginal.R index 0e8588b8..be99f9d0 100644 --- a/tests/testthat/test-brm_transform_marginal.R +++ b/tests/testthat/test-brm_transform_marginal.R @@ -10,7 +10,6 @@ test_that("brm_transform_marginal(), response, non-subgroup", { data <- brm_data( data = raw_data, outcome = "FEV1", - role = "response", group = "ARMCD", time = "AVISIT", patient = "USUBJID", @@ -89,7 +88,6 @@ test_that("brm_transform_marginal(), change, non-subgroup", { data <- brm_data( data = raw_data, outcome = "FEV1_CHG", - role = "change", group = "ARMCD", time = "AVISIT", patient = "USUBJID", @@ -174,7 +172,6 @@ test_that("brm_transform_marginal(), change, subgroup, global", { data <- brm_data( data = raw_data, outcome = "FEV1_CHG", - role = "change", group = "ARMCD", subgroup = "SEX", time = "AVISIT", @@ -282,7 +279,6 @@ test_that("brm_transform_marginal(), change, subgroup, local", { data <- brm_data( data = raw_data, outcome = "FEV1_CHG", - role = "change", group = "ARMCD", subgroup = "SEX", time = "AVISIT", diff --git a/tests/testthat/test-utils_data.R b/tests/testthat/test-utils_data.R index d06f4e3f..94c03552 100644 --- a/tests/testthat/test-utils_data.R +++ b/tests/testthat/test-utils_data.R @@ -30,7 +30,6 @@ test_that("brm_has_subgroup() on regular data", { SUBGROUP = c("x", "y") ), outcome = "CHG", - role = "change", group = "GROUP", subgroup = "SUBGROUP", time = "TIME", @@ -124,7 +123,6 @@ test_that("brm_has_nuisance() on regular data", { FACTOR = c("x", "y") ), outcome = "CHG", - role = "change", group = "GROUP", subgroup = "SUBGROUP", time = "TIME",