diff --git a/DESCRIPTION b/DESCRIPTION index f367bd43..41845a26 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: simtrial Type: Package Title: Clinical Trial Simulation -Version: 0.3.2.12 +Version: 0.3.2.13 Authors@R: c( person("Keaven", "Anderson", email = "keaven_anderson@merck.com", role = c("aut")), person("Yilong", "Zhang", email = "elong0527@gmail.com", role = c("aut")), diff --git a/NAMESPACE b/NAMESPACE index b7e8b84f..4f6b6de3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,7 +1,5 @@ # Generated by roxygen2: do not edit by hand -S3method(rmst,default) -S3method(rmst,formula) export(counting_process) export(create_cutting) export(create_cutting_test) diff --git a/R/rmst.R b/R/rmst.R index ce27abea..71413e46 100644 --- a/R/rmst.R +++ b/R/rmst.R @@ -18,9 +18,6 @@ #' RMST difference of 2 arms #' -#' @param x Either a time-to-event dataset (see argument `data`) or a formula -#' that indicates the TTE, event, and group variables (in that exact order; -#' see Details below). #' @param data A time-to-event dataset with a column `tte` indicating the #' survival time and a column of `event` indicating whether it is #' event or censor. @@ -28,12 +25,16 @@ #' @param var_label_tte Column name of the TTE variable. #' @param var_label_event Column name of the event variable. #' @param var_label_group Column name of the grouping variable. +#' @param formula (default: `NULL`) A formula that indicates the TTE, event, and +#' group variables (in that exact order; see Details below). This is an +#' alternative to specifying the variables as strings. If a formula is +#' provided, the values passed to `var_label_tte`, `var_label_event`, and +#' `var_label_group` are ignored. #' @param reference A group label indicating the reference group. #' @param alpha Type I error. -#' @param ... Currently unused (required for S3 generic function) #' #' @details -#' The formula interface is provided as a convenience to easily specify the TTE, +#' The argument `formula` is provided as a convenience to easily specify the TTE, #' event, and grouping variables. Note however that only the order of the three #' variables is actually used by the underlying function. Any functions applied #' in the formula are ignored, and thus should only be used for documenting your @@ -50,7 +51,7 @@ #' @examples #' data(ex1_delayed_effect) #' rmst( -#' x = ex1_delayed_effect, +#' data = ex1_delayed_effect, #' var_label_tte = "month", #' var_label_event = "evntd", #' var_label_group = "trt", @@ -62,16 +63,16 @@ #' library("survival") #' #' rmst( -#' Surv(month | evntd) ~ trt, #' data = ex1_delayed_effect, +#' formula = Surv(month | evntd) ~ trt, #' tau = 10, #' reference = "0" #' ) #' #' # alternative #' rmst( -#' ~ Surv(month, evntd, trt), #' data = ex1_delayed_effect, +#' formula = ~ Surv(month, evntd, trt), #' tau = 10, #' reference = "0" #' ) @@ -79,30 +80,36 @@ #' # This example doesn't make statistical sense, but demonstrates that only the #' # order of the 3 variables actually matters #' rmst( -#' month ~ evntd + trt, #' data = ex1_delayed_effect, +#' formula = month ~ evntd + trt, #' tau = 10, #' reference = "0" #' ) -rmst <- function(x, ...) { - UseMethod("rmst") -} - -#' @rdname rmst -#' @export -rmst.default <- function( - x, +rmst <- function( + data, tau = 10, var_label_tte = "tte", var_label_event = "event", var_label_group = "treatment", + formula = NULL, reference = "control", - alpha = 0.05, - ...) { + alpha = 0.05) { + stopifnot(is.data.frame(data)) + + if (!is.null(formula)) { + variables <- colnames(stats::get_all_vars(formula = formula, data = data)) + if (length(variables) != 3) { + stop("The formula interface requires exactly 3 variables specified") + } + var_label_tte <- variables[1] + var_label_event <- variables[2] + var_label_group <- variables[3] + } + res <- rmst_two_arm( - time_var = x[[var_label_tte]], - event_var = x[[var_label_event]], - group_var = x[[var_label_group]], + time_var = data[[var_label_tte]], + event_var = data[[var_label_event]], + group_var = data[[var_label_group]], trunc_time = tau, reference = reference, alpha = alpha @@ -348,27 +355,3 @@ rmst_single_arm <- function( return(ans) } - -#' @rdname rmst -#' @export -rmst.formula <- function(x, data, tau = 10, reference = "control", - alpha = 0.05, ...) { - stopifnot(is.data.frame(data)) - - variables <- colnames(stats::get_all_vars(formula = x, data = data)) - if (length(variables) != 3) { - stop("The formula interface requires exactly 3 variables specified") - } - - ans <- rmst.default( - x = data, - tau = tau, - var_label_tte = variables[1], - var_label_event = variables[2], - var_label_group = variables[3], - reference = reference, - alpha = alpha - ) - - return(ans) -} diff --git a/man/rmst.Rd b/man/rmst.Rd index c6a794ba..d6099705 100644 --- a/man/rmst.Rd +++ b/man/rmst.Rd @@ -2,31 +2,23 @@ % Please edit documentation in R/rmst.R \name{rmst} \alias{rmst} -\alias{rmst.default} -\alias{rmst.formula} \title{RMST difference of 2 arms} \usage{ -rmst(x, ...) - -\method{rmst}{default}( - x, +rmst( + data, tau = 10, var_label_tte = "tte", var_label_event = "event", var_label_group = "treatment", + formula = NULL, reference = "control", - alpha = 0.05, - ... + alpha = 0.05 ) - -\method{rmst}{formula}(x, data, tau = 10, reference = "control", alpha = 0.05, ...) } \arguments{ -\item{x}{Either a time-to-event dataset (see argument \code{data}) or a formula -that indicates the TTE, event, and group variables (in that exact order; -see Details below).} - -\item{...}{Currently unused (required for S3 generic function)} +\item{data}{A time-to-event dataset with a column \code{tte} indicating the +survival time and a column of \code{event} indicating whether it is +event or censor.} \item{tau}{RMST analysis time.} @@ -36,13 +28,15 @@ see Details below).} \item{var_label_group}{Column name of the grouping variable.} +\item{formula}{(default: \code{NULL}) A formula that indicates the TTE, event, and +group variables (in that exact order; see Details below). This is an +alternative to specifying the variables as strings. If a formula is +provided, the values passed to \code{var_label_tte}, \code{var_label_event}, and +\code{var_label_group} are ignored.} + \item{reference}{A group label indicating the reference group.} \item{alpha}{Type I error.} - -\item{data}{A time-to-event dataset with a column \code{tte} indicating the -survival time and a column of \code{event} indicating whether it is -event or censor.} } \value{ The z statistics. @@ -51,7 +45,7 @@ The z statistics. RMST difference of 2 arms } \details{ -The formula interface is provided as a convenience to easily specify the TTE, +The argument \code{formula} is provided as a convenience to easily specify the TTE, event, and grouping variables. Note however that only the order of the three variables is actually used by the underlying function. Any functions applied in the formula are ignored, and thus should only be used for documenting your @@ -64,7 +58,7 @@ since these will also be ignored. \examples{ data(ex1_delayed_effect) rmst( - x = ex1_delayed_effect, + data = ex1_delayed_effect, var_label_tte = "month", var_label_event = "evntd", var_label_group = "trt", @@ -76,16 +70,16 @@ rmst( library("survival") rmst( - Surv(month | evntd) ~ trt, data = ex1_delayed_effect, + formula = Surv(month | evntd) ~ trt, tau = 10, reference = "0" ) # alternative rmst( - ~ Surv(month, evntd, trt), data = ex1_delayed_effect, + formula = ~ Surv(month, evntd, trt), tau = 10, reference = "0" ) @@ -93,8 +87,8 @@ rmst( # This example doesn't make statistical sense, but demonstrates that only the # order of the 3 variables actually matters rmst( - month ~ evntd + trt, data = ex1_delayed_effect, + formula = month ~ evntd + trt, tau = 10, reference = "0" ) diff --git a/tests/testthat/test-unvalidated-rmst.R b/tests/testthat/test-unvalidated-rmst.R index e2f34eab..25c8426d 100644 --- a/tests/testthat/test-unvalidated-rmst.R +++ b/tests/testthat/test-unvalidated-rmst.R @@ -1,7 +1,7 @@ test_that("rmst() snapshot test", { - data(ex1_delayed_effect) + data("ex1_delayed_effect") observed <- rmst( - ex1_delayed_effect, + data = ex1_delayed_effect, var_label_tte = "month", var_label_event = "evntd", var_label_group = "trt", @@ -18,10 +18,10 @@ test_that("rmst() snapshot test", { }) test_that("formula method matches default method", { - data(ex1_delayed_effect) + data("ex1_delayed_effect") rmst_default <- rmst( - ex1_delayed_effect, + data = ex1_delayed_effect, var_label_tte = "month", var_label_event = "evntd", var_label_group = "trt", @@ -30,26 +30,48 @@ test_that("formula method matches default method", { ) rmst_formula_1 <- rmst( - month ~ evntd + trt, data = ex1_delayed_effect, + formula = month ~ evntd + trt, tau = 10, reference = "0" ) expect_equal(rmst_formula_1, rmst_default) rmst_formula_2 <- rmst( - survival::Surv(month | evntd) ~ trt, data = ex1_delayed_effect, + formula = survival::Surv(month | evntd) ~ trt, tau = 10, reference = "0" ) expect_equal(rmst_formula_2, rmst_default) rmst_formula_3 <- rmst( - ~ survival::Surv(month, evntd, trt), data = ex1_delayed_effect, + formula = ~ survival::Surv(month, evntd, trt), tau = 10, reference = "0" ) expect_equal(rmst_formula_3, rmst_default) }) + +test_that("default and formula methods of rmst are pipeable", { + data("ex1_delayed_effect") + + rmst_default <- ex1_delayed_effect |> + rmst( + var_label_tte = "month", + var_label_event = "evntd", + var_label_group = "trt", + tau = 10, + reference = "0" + ) + + rmst_formula_1 <- ex1_delayed_effect |> + rmst( + formula = month ~ evntd + trt, + tau = 10, + reference = "0" + ) + + expect_equal(rmst_formula_1, rmst_default) +})