diff --git a/NEWS.md b/NEWS.md index b68adbc086..b133884c35 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ # tern 0.8.3.9000 +### Miscellaneous +* Began deprecation of `time_unit_input` and `time_unit_output` arguments and replaced them with the `input_time_unit` and `n_pt_years_rate`, respectively, in `control_incidence_rate`. + +# tern 0.8.3 + ### Enhancements * Added explicit zero counts to `g_km` plot "at risk" annotation tables. * Added a flag for total level split in `analyze_patients_exposure_in_cols`. @@ -18,7 +23,7 @@ * Remove examples for unexported functions. * Export functions `has_count_in_cols`, `has_counts_difference`, `combine_counts`, `h_tab_rsp_one_biomarker`, `arrange_grobs`, `a_count_patients_sum_exposure`, `a_coxreg`, `groups_list_to_df`, `forest_viewport`. * Updated `README` to include installation instructions for CRAN. -* Began deprecation of `indent_mod` argument and replace it with the `.indent_mods` argument in `summarize_num_patients` and `analyze_num_patients`. +* Began deprecation of `indent_mod` argument and replaced it with the `.indent_mods` argument in `summarize_num_patients` and `analyze_num_patients`. # tern 0.8.2 diff --git a/R/control_incidence_rate.R b/R/control_incidence_rate.R index 0ac949cf92..a7d737c0cd 100644 --- a/R/control_incidence_rate.R +++ b/R/control_incidence_rate.R @@ -6,11 +6,13 @@ #' internally to specify details in `s_incidence_rate()`. #' #' @inheritParams argument_convention -#' @param time_unit_input (`string`)\cr `day`, `month`, or `year` (default) -#' indicating time unit for data input. -#' @param time_unit_output (`numeric`)\cr time unit for desired output (in person-years). #' @param conf_type (`string`)\cr `normal` (default), `normal_log`, `exact`, or `byar` #' for confidence interval type. +#' @param input_time_unit (`string`)\cr `day`, `week`, `month`, or `year` (default) +#' indicating time unit for data input. +#' @param num_pt_year (`numeric`)\cr number of patient-years to use when calculating AE rate. +#' @param time_unit_input `r lifecycle::badge("deprecated")` Please use the `input_time_unit` argument instead. +#' @param time_unit_output `r lifecycle::badge("deprecated")` Please use the `num_pt_year` argument instead. #' #' @return A list of components with the same names as the arguments. #' @@ -22,17 +24,32 @@ #' @export control_incidence_rate <- function(conf_level = 0.95, conf_type = c("normal", "normal_log", "exact", "byar"), - time_unit_input = c("year", "day", "week", "month"), - time_unit_output = 1) { + input_time_unit = c("year", "day", "week", "month"), + num_pt_year = 100, + time_unit_input = lifecycle::deprecated(), + time_unit_output = lifecycle::deprecated()) { + if (lifecycle::is_present(time_unit_input)) { + lifecycle::deprecate_warn( + "0.8.3", "control_incidence_rate(time_unit_input)", "control_incidence_rate(input_time_unit)" + ) + input_time_unit <- time_unit_input + } + if (lifecycle::is_present(time_unit_output)) { + lifecycle::deprecate_warn( + "0.8.3", "control_incidence_rate(time_unit_output)", "control_incidence_rate(num_pt_year)" + ) + num_pt_year <- time_unit_output + } + conf_type <- match.arg(conf_type) - time_unit_input <- match.arg(time_unit_input) - checkmate::assert_number(time_unit_output) + input_time_unit <- match.arg(input_time_unit) + checkmate::assert_number(num_pt_year) assert_proportion_value(conf_level) list( conf_level = conf_level, conf_type = conf_type, - time_unit_input = time_unit_input, - time_unit_output = time_unit_output + input_time_unit = input_time_unit, + num_pt_year = num_pt_year ) } diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 69d2fe3dd2..2f18955570 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -11,9 +11,9 @@ #' * `conf_level` (`proportion`)\cr confidence level for the estimated incidence rate. #' * `conf_type` (`string`)\cr `normal` (default), `normal_log`, `exact`, or `byar` #' for confidence interval type. -#' * `time_unit_input` (`string`)\cr `day`, `week`, `month`, or `year` (default) +#' * `input_time_unit` (`string`)\cr `day`, `week`, `month`, or `year` (default) #' indicating time unit for data input. -#' * `time_unit_output` (`numeric`)\cr time unit for desired output (in person-years). +#' * `num_pt_year` (`numeric`)\cr time unit for desired output (in person-years). #' @param person_years (`numeric`)\cr total person-years at risk. #' @param alpha (`numeric`)\cr two-sided alpha-level for confidence interval. #' @param n_events (`integer`)\cr number of events observed. @@ -68,14 +68,14 @@ s_incidence_rate <- function(df, checkmate::assert_integer(df[[n_events]], any.missing = FALSE) } - time_unit_input <- control$time_unit_input - time_unit_output <- control$time_unit_output + input_time_unit <- control$input_time_unit + num_pt_year <- control$num_pt_year conf_level <- control$conf_level person_years <- sum(df[[.var]], na.rm = TRUE) * ( - 1 * (time_unit_input == "year") + - 1 / 12 * (time_unit_input == "month") + - 1 / 52.14 * (time_unit_input == "week") + - 1 / 365.24 * (time_unit_input == "day") + 1 * (input_time_unit == "year") + + 1 / 12 * (input_time_unit == "month") + + 1 / 52.14 * (input_time_unit == "week") + + 1 / 365.24 * (input_time_unit == "day") ) n_events <- sum(df[[n_events]], na.rm = TRUE) @@ -87,7 +87,7 @@ s_incidence_rate <- function(df, list( person_years = formatters::with_label(person_years, "Total patient-years at risk"), n_events = formatters::with_label(n_events, "Number of adverse events observed"), - rate = formatters::with_label(result$rate, paste("AE rate per", time_unit_output, "patient-years")), + rate = formatters::with_label(result$rate, paste("AE rate per", num_pt_year, "patient-years")), rate_ci = formatters::with_label(result$rate_ci, f_conf_level(conf_level)) ) } @@ -126,8 +126,8 @@ a_incidence_rate <- make_afun( #' vars = "AVAL", #' n_events = "n_events", #' control = control_incidence_rate( -#' time_unit_input = "month", -#' time_unit_output = 100 +#' input_time_unit = "month", +#' num_pt_year = 100 #' ) #' ) %>% #' build_table(df) @@ -169,9 +169,9 @@ estimate_incidence_rate <- function(lyt, #' * `conf_level`: (`proportion`)\cr confidence level for the estimated incidence rate. #' * `conf_type`: (`string`)\cr `normal` (default), `normal_log`, `exact`, or `byar` #' for confidence interval type. -#' * `time_unit_input`: (`string`)\cr `day`, `week`, `month`, or `year` (default) +#' * `input_time_unit`: (`string`)\cr `day`, `week`, `month`, or `year` (default) #' indicating time unit for data input. -#' * `time_unit_output`: (`numeric`)\cr time unit for desired output (in person-years). +#' * `num_pt_year`: (`numeric`)\cr time unit for desired output (in person-years). #' @param person_years (`numeric`)\cr total person-years at risk. #' @param alpha (`numeric`)\cr two-sided alpha-level for confidence interval. #' @param n_events (`integer`)\cr number of events observed. @@ -290,9 +290,9 @@ h_incidence_rate <- function(person_years, byar = h_incidence_rate_byar(person_years, n_events, alpha) ) - time_unit_output <- control$time_unit_output + num_pt_year <- control$num_pt_year list( - rate = est$rate * time_unit_output, - rate_ci = est$rate_ci * time_unit_output + rate = est$rate * num_pt_year, + rate_ci = est$rate_ci * num_pt_year ) } diff --git a/man/control_incidence_rate.Rd b/man/control_incidence_rate.Rd index 62afac7e6a..06fdb4d0d7 100644 --- a/man/control_incidence_rate.Rd +++ b/man/control_incidence_rate.Rd @@ -7,8 +7,10 @@ control_incidence_rate( conf_level = 0.95, conf_type = c("normal", "normal_log", "exact", "byar"), - time_unit_input = c("year", "day", "week", "month"), - time_unit_output = 1 + input_time_unit = c("year", "day", "week", "month"), + num_pt_year = 100, + time_unit_input = lifecycle::deprecated(), + time_unit_output = lifecycle::deprecated() ) } \arguments{ @@ -17,10 +19,14 @@ control_incidence_rate( \item{conf_type}{(\code{string})\cr \code{normal} (default), \code{normal_log}, \code{exact}, or \code{byar} for confidence interval type.} -\item{time_unit_input}{(\code{string})\cr \code{day}, \code{month}, or \code{year} (default) +\item{input_time_unit}{(\code{string})\cr \code{day}, \code{week}, \code{month}, or \code{year} (default) indicating time unit for data input.} -\item{time_unit_output}{(\code{numeric})\cr time unit for desired output (in person-years).} +\item{num_pt_year}{(\code{numeric})\cr number of patient-years to use when calculating AE rate.} + +\item{time_unit_input}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use the \code{input_time_unit} argument instead.} + +\item{time_unit_output}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use the \code{num_pt_year} argument instead.} } \value{ A list of components with the same names as the arguments. diff --git a/man/h_incidence_rate.Rd b/man/h_incidence_rate.Rd index 1b385b5374..b51681e00c 100644 --- a/man/h_incidence_rate.Rd +++ b/man/h_incidence_rate.Rd @@ -31,9 +31,9 @@ the helper function \code{\link[=control_incidence_rate]{control_incidence_rate( \item \code{conf_level}: (\code{proportion})\cr confidence level for the estimated incidence rate. \item \code{conf_type}: (\code{string})\cr \code{normal} (default), \code{normal_log}, \code{exact}, or \code{byar} for confidence interval type. -\item \code{time_unit_input}: (\code{string})\cr \code{day}, \code{week}, \code{month}, or \code{year} (default) +\item \code{input_time_unit}: (\code{string})\cr \code{day}, \code{week}, \code{month}, or \code{year} (default) indicating time unit for data input. -\item \code{time_unit_output}: (\code{numeric})\cr time unit for desired output (in person-years). +\item \code{num_pt_year}: (\code{numeric})\cr time unit for desired output (in person-years). }} } \value{ diff --git a/man/incidence_rate.Rd b/man/incidence_rate.Rd index c3c6160de7..0c5dd5d0ce 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -51,9 +51,9 @@ the helper function \code{\link[=control_incidence_rate]{control_incidence_rate( \item \code{conf_level} (\code{proportion})\cr confidence level for the estimated incidence rate. \item \code{conf_type} (\code{string})\cr \code{normal} (default), \code{normal_log}, \code{exact}, or \code{byar} for confidence interval type. -\item \code{time_unit_input} (\code{string})\cr \code{day}, \code{week}, \code{month}, or \code{year} (default) +\item \code{input_time_unit} (\code{string})\cr \code{day}, \code{week}, \code{month}, or \code{year} (default) indicating time unit for data input. -\item \code{time_unit_output} (\code{numeric})\cr time unit for desired output (in person-years). +\item \code{num_pt_year} (\code{numeric})\cr time unit for desired output (in person-years). }} \item{lyt}{(\code{layout})\cr input layout where analyses will be added to.} @@ -138,8 +138,8 @@ basic_table() \%>\% vars = "AVAL", n_events = "n_events", control = control_incidence_rate( - time_unit_input = "month", - time_unit_output = 100 + input_time_unit = "month", + num_pt_year = 100 ) ) \%>\% build_table(df) diff --git a/tests/testthat/test-estimate_incidence_rate.R b/tests/testthat/test-estimate_incidence_rate.R index 2576a03181..f83173e1a2 100644 --- a/tests/testthat/test-estimate_incidence_rate.R +++ b/tests/testthat/test-estimate_incidence_rate.R @@ -2,8 +2,8 @@ testthat::test_that("control_incidence_rate works with customized parameters", { result <- control_incidence_rate( conf_level = 0.9, conf_type = "exact", - time_unit_input = "month", - time_unit_output = 100 + input_time_unit = "month", + num_pt_year = 100 ) res <- testthat::expect_silent(result) @@ -13,8 +13,8 @@ testthat::test_that("control_incidence_rate works with customized parameters", { testthat::test_that("control_incidence_rate fails with wrong input", { testthat::expect_error(control_incidence_rate(conf_level = 1.1)) testthat::expect_error(control_incidence_rate(conf_type = "wald")) - testthat::expect_error(control_incidence_rate(time_unit_input = "decade")) - testthat::expect_error(control_incidence_rate(time_unit_output = "one")) + testthat::expect_error(control_incidence_rate(input_time_unit = "decade")) + testthat::expect_error(control_incidence_rate(num_pt_year = "one")) }) testthat::test_that("h_incidence_rate_normal works as expected with healthy input", { @@ -49,7 +49,7 @@ testthat::test_that("h_incidence_rate works as expected with healthy input", { result <- h_incidence_rate( 200, 2, - control_incidence_rate(conf_level = 0.9, conf_type = "normal_log", time_unit_output = 100) + control_incidence_rate(conf_level = 0.9, conf_type = "normal_log", num_pt_year = 100) ) res <- testthat::expect_silent(result) @@ -72,8 +72,8 @@ testthat::test_that("s_incidence_rate works as expected with healthy input", { control = control_incidence_rate( conf_level = 0.9, conf_type = "normal_log", - time_unit_input = "month", - time_unit_output = 100 + input_time_unit = "month", + num_pt_year = 100 ) ) @@ -100,8 +100,8 @@ testthat::test_that("estimate_incidence_rate works as expected with healthy inpu control = control_incidence_rate( conf_level = 0.9, conf_type = "normal_log", - time_unit_input = "month", - time_unit_output = 100 + input_time_unit = "month", + num_pt_year = 100 ) ) %>% build_table(df)