From 01e8fe097146c1b1676155bbc547792a3bcbff23 Mon Sep 17 00:00:00 2001 From: Emily de la Rua <59304861+edelarua@users.noreply.github.com> Date: Wed, 4 Sep 2024 10:48:58 -0400 Subject: [PATCH 01/12] Fix URLs (#1298) Fixes #1297 --- vignettes/tables.Rmd | 2 +- vignettes/tern.Rmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/vignettes/tables.Rmd b/vignettes/tables.Rmd index fe199c4844..9feba45514 100644 --- a/vignettes/tables.Rmd +++ b/vignettes/tables.Rmd @@ -27,7 +27,7 @@ knitr::opts_chunk$set( The `tern` R package provides functions to create common analyses from clinical trials in `R`. The core functionality for tabulation is built on the more general purpose `rtables` package. -New users should first begin by reading the ["Introduction to tern"](https://insightsengineering.github.io/tern/main/articles/tern.html) and ["Introduction to `rtables`"](https://insightsengineering.github.io/rtables/main/articles/introduction.html) vignettes. +New users should first begin by reading the ["Introduction to tern"](https://insightsengineering.github.io/tern/main/articles/tern.html) and ["Introduction to `rtables`"](https://insightsengineering.github.io/rtables/latest-tag/articles/introduction.html) vignettes. The packages used in this vignette are: diff --git a/vignettes/tern.Rmd b/vignettes/tern.Rmd index 83013d8f79..0920bff77d 100644 --- a/vignettes/tern.Rmd +++ b/vignettes/tern.Rmd @@ -32,7 +32,7 @@ The `tern` R package contains analytical functions for creating tables and graph The main focus is on the clinical trial reporting tables but the graphs related to the clinical trials are also valuable. The core functionality for tabulation is built on top of the more general purpose `rtables` package. -[**It is strongly recommended that you start by reading the "Introduction to `rtables`" vignette to get familiar with the concept of `rtables`.**](https://insightsengineering.github.io/rtables/main/articles/introduction.html) +[**It is strongly recommended that you start by reading the "Introduction to `rtables`" vignette to get familiar with the concept of `rtables`.**](https://insightsengineering.github.io/rtables/latest-tag/articles/introduction.html) --------- From f598c3da7a1c668a70d61c0ad48dd8b6b6a06681 Mon Sep 17 00:00:00 2001 From: edelarua Date: Wed, 4 Sep 2024 14:50:07 +0000 Subject: [PATCH 02/12] [skip actions] Bump version to 0.9.5.9017 --- DESCRIPTION | 4 ++-- NEWS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a26c60d196..cfe90fd1c6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9016 -Date: 2024-08-28 +Version: 0.9.5.9017 +Date: 2024-09-04 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"), diff --git a/NEWS.md b/NEWS.md index c7f82ba72a..e63b36871d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9016 +# tern 0.9.5.9017 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. From 03d8639fb12ca8334b16879424d712c6e90e9b49 Mon Sep 17 00:00:00 2001 From: Emily de la Rua <59304861+edelarua@users.noreply.github.com> Date: Thu, 5 Sep 2024 10:19:09 -0400 Subject: [PATCH 03/12] Add warning for missing p-value in `tabulate_rsp_subgroups()` output (#1296) Fixes #1289 --- NEWS.md | 2 +- R/argument_convention.R | 2 +- R/response_subgroups.R | 8 ++++++++ man/argument_convention.Rd | 2 +- man/d_rsp_subgroups_colvars.Rd | 2 +- man/extract_rsp_subgroups.Rd | 2 +- man/h_response_subgroups.Rd | 2 +- tests/testthat/test-response_subgroups.R | 21 +++++++++++++++++++++ 8 files changed, 35 insertions(+), 6 deletions(-) diff --git a/NEWS.md b/NEWS.md index e63b36871d..01cd53d85d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,7 @@ * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. * Added the `.formats` argument to `tabulate_rsp_subgroups` and `tabulate_survival_subgroups` to allow users to specify formats. * Added the `riskdiff` argument to `tabulate_rsp_subgroups` and `tabulate_survival_subgroups` to allow users to add a risk difference table column, and function `control_riskdiff` to specify settings for the risk difference column. +* Added warning to `tabulate_rsp_subgroups` when `pval` statistic is selected but `df` has not been correctly generated to add p-values to the output table. ### Bug Fixes * Fixed a bug in `a_surv_time` that threw an error when split only has `"is_event"`. @@ -15,7 +16,6 @@ * Fixed bug in `decorate_grob` that did not handle well empty strings or `NULL` values for title and footers. * Fixed bug in `g_km` that caused an error when multiple records in the data had estimates at max time. - ### Miscellaneous * Began deprecation of the confusing functions `summary_formats` and `summary_labels`. diff --git a/R/argument_convention.R b/R/argument_convention.R index bc6a7220d8..34c92b7786 100644 --- a/R/argument_convention.R +++ b/R/argument_convention.R @@ -43,7 +43,7 @@ #' for more information. #' @param lyt (`PreDataTableLayouts`)\cr layout that analyses will be added to. #' @param method (`string` or `NULL`)\cr specifies the test used to calculate the p-value for the difference between -#' two proportions. For options, see [s_test_proportion_diff()]. Default is `NULL` so no test is performed. +#' two proportions. For options, see [test_proportion_diff()]. Default is `NULL` so no test is performed. #' @param na.rm (`flag`)\cr whether `NA` values should be removed from `x` prior to analysis. #' @param na_str (`string`)\cr string used to replace all `NA` or empty values in the output. #' @param nested (`flag`)\cr whether this layout instruction should be applied within the existing layout structure _if diff --git a/R/response_subgroups.R b/R/response_subgroups.R index 3f4cdb474d..c24606c58e 100644 --- a/R/response_subgroups.R +++ b/R/response_subgroups.R @@ -220,6 +220,14 @@ tabulate_rsp_subgroups <- function(lyt, )) { checkmate::assert_list(riskdiff, null.ok = TRUE) checkmate::assert_true(all(c("n_tot", "or", "ci") %in% vars)) + if ("pval" %in% vars && !"pval" %in% names(df$or)) { + warning( + 'The "pval" statistic has been selected but is not present in "df" so it will not be included in the output ', + 'table. To include the "pval" statistic, please specify a p-value test when generating "df" via ', + 'the "method" argument to `extract_rsp_subgroups()`. If method = "cmh", strata must also be specified via the ', + '"variables" argument to `extract_rsp_subgroups()`.' + ) + } # Create "ci" column from "lcl" and "ucl" df$or$ci <- combine_vectors(df$or$lcl, df$or$ucl) diff --git a/man/argument_convention.Rd b/man/argument_convention.Rd index 8f50bec33e..7b13f98616 100644 --- a/man/argument_convention.Rd +++ b/man/argument_convention.Rd @@ -70,7 +70,7 @@ for more information.} \item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} \item{method}{(\code{string} or \code{NULL})\cr specifies the test used to calculate the p-value for the difference between -two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} +two proportions. For options, see \code{\link[=test_proportion_diff]{test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} \item{na.rm}{(\code{flag})\cr whether \code{NA} values should be removed from \code{x} prior to analysis.} diff --git a/man/d_rsp_subgroups_colvars.Rd b/man/d_rsp_subgroups_colvars.Rd index ca9f5af0b4..f16cb0ccc7 100644 --- a/man/d_rsp_subgroups_colvars.Rd +++ b/man/d_rsp_subgroups_colvars.Rd @@ -12,7 +12,7 @@ d_rsp_subgroups_colvars(vars, conf_level = NULL, method = NULL) \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} \item{method}{(\code{string} or \code{NULL})\cr specifies the test used to calculate the p-value for the difference between -two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} +two proportions. For options, see \code{\link[=test_proportion_diff]{test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} } \value{ A \code{list} of variables to tabulate and their labels. diff --git a/man/extract_rsp_subgroups.Rd b/man/extract_rsp_subgroups.Rd index 37e5239dbc..538de425d6 100644 --- a/man/extract_rsp_subgroups.Rd +++ b/man/extract_rsp_subgroups.Rd @@ -25,7 +25,7 @@ levels that belong to it in the character vectors that are elements of the list. \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} \item{method}{(\code{string} or \code{NULL})\cr specifies the test used to calculate the p-value for the difference between -two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} +two proportions. For options, see \code{\link[=test_proportion_diff]{test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} \item{label_all}{(\code{string})\cr label for the total population analysis.} } diff --git a/man/h_response_subgroups.Rd b/man/h_response_subgroups.Rd index 517a602c94..2e07f2da13 100644 --- a/man/h_response_subgroups.Rd +++ b/man/h_response_subgroups.Rd @@ -48,7 +48,7 @@ levels that belong to it in the character vectors that are elements of the list. \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} \item{method}{(\code{string} or \code{NULL})\cr specifies the test used to calculate the p-value for the difference between -two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} +two proportions. For options, see \code{\link[=test_proportion_diff]{test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} } \value{ \itemize{ diff --git a/tests/testthat/test-response_subgroups.R b/tests/testthat/test-response_subgroups.R index 3d8a9ed812..7422d7c64e 100644 --- a/tests/testthat/test-response_subgroups.R +++ b/tests/testthat/test-response_subgroups.R @@ -307,3 +307,24 @@ testthat::test_that("tabulate_rsp_subgroups riskdiff argument works as expected" res <- testthat::expect_silent(result) testthat::expect_snapshot(res) }) + +testthat::test_that("tabulate_rsp_subgroups pval statistic warning works as expected", { + adrs <- adrs_200 + + df <- extract_rsp_subgroups( + variables = list(rsp = "rsp", arm = "ARM", subgroups = c("SEX", "STRATA2")), + data = adrs, + method = NULL, + conf_level = 0.95 + ) + + # warning when no pval in df + expect_warning( + basic_table() %>% + tabulate_rsp_subgroups( + df = df, + vars = c("n", "prop", "n_tot", "or", "ci", "pval") + ), + "please specify a p-value test" + ) +}) From 716a2900b7ceb19a01055f73ab3832abd2823fef Mon Sep 17 00:00:00 2001 From: edelarua Date: Thu, 5 Sep 2024 14:20:25 +0000 Subject: [PATCH 04/12] [skip actions] Bump version to 0.9.5.9018 --- DESCRIPTION | 4 ++-- NEWS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index cfe90fd1c6..ab8d790a13 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9017 -Date: 2024-09-04 +Version: 0.9.5.9018 +Date: 2024-09-05 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"), diff --git a/NEWS.md b/NEWS.md index 01cd53d85d..abf0852771 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9017 +# tern 0.9.5.9018 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. From 6b41d95e0507388b04e536c4d86744dea30a3c9c Mon Sep 17 00:00:00 2001 From: Emily de la Rua <59304861+edelarua@users.noreply.github.com> Date: Thu, 5 Sep 2024 10:53:40 -0400 Subject: [PATCH 05/12] Add `n_rate` statistic to `estimate_incidence_rate()` (#1295) Fixes #1294 --- NEWS.md | 1 + R/incidence_rate.R | 12 +++++++--- R/utils_default_stats_formats_labels.R | 2 +- man/incidence_rate.Rd | 3 ++- .../_snaps/estimate_incidence_rate.md | 17 +++++++++++++ tests/testthat/test-estimate_incidence_rate.R | 24 +++++++++++++++++++ 6 files changed, 54 insertions(+), 5 deletions(-) diff --git a/NEWS.md b/NEWS.md index abf0852771..f730e23c73 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,7 @@ * Added the `.formats` argument to `tabulate_rsp_subgroups` and `tabulate_survival_subgroups` to allow users to specify formats. * Added the `riskdiff` argument to `tabulate_rsp_subgroups` and `tabulate_survival_subgroups` to allow users to add a risk difference table column, and function `control_riskdiff` to specify settings for the risk difference column. * Added warning to `tabulate_rsp_subgroups` when `pval` statistic is selected but `df` has not been correctly generated to add p-values to the output table. +* Added `n_rate` statistic as a non-default option to `estimate_incidence_rate` which returns both number of events observed and estimated incidence rate. ### Bug Fixes * Fixed a bug in `a_surv_time` that threw an error when split only has `"is_event"`. diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 7c86c448e9..2fda506e3b 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -33,6 +33,7 @@ NULL #' - `n_events`: Total number of events observed. #' - `rate`: Estimated incidence rate. #' - `rate_ci`: Confidence interval for the incidence rate. +#' - `n_rate`: Total number of events observed & estimated incidence rate. #' #' @keywords internal s_incidence_rate <- function(df, @@ -77,7 +78,11 @@ s_incidence_rate <- function(df, 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", num_pt_year, "patient-years")), - rate_ci = formatters::with_label(result$rate_ci, f_conf_level(conf_level)) + rate_ci = formatters::with_label(result$rate_ci, f_conf_level(conf_level)), + n_rate = formatters::with_label( + c(n_events, result$rate), + paste("Number of adverse events observed (AE rate per", num_pt_year, "patient-years)") + ) ) } @@ -94,7 +99,8 @@ a_incidence_rate <- make_afun( "person_years" = "xx.x", "n_events" = "xx", "rate" = "xx.xx", - "rate_ci" = "(xx.xx, xx.xx)" + "rate_ci" = "(xx.xx, xx.xx)", + "n_rate" = "xx (xx.x)" ) ) @@ -142,7 +148,7 @@ estimate_incidence_rate <- function(lyt, ..., show_labels = "hidden", table_names = vars, - .stats = NULL, + .stats = c("person_years", "n_events", "rate", "rate_ci"), .formats = NULL, .labels = NULL, .indent_mods = NULL) { diff --git a/R/utils_default_stats_formats_labels.R b/R/utils_default_stats_formats_labels.R index 824f946061..34cc8937a1 100644 --- a/R/utils_default_stats_formats_labels.R +++ b/R/utils_default_stats_formats_labels.R @@ -382,7 +382,7 @@ tern_default_stats <- list( count_patients_with_flags = c("n", "count", "count_fraction", "count_fraction_fixed_dp", "n_blq"), count_values = c("n", "count", "count_fraction", "count_fraction_fixed_dp", "n_blq"), coxph_pairwise = c("pvalue", "hr", "hr_ci", "n_tot", "n_tot_events"), - estimate_incidence_rate = c("person_years", "n_events", "rate", "rate_ci"), + estimate_incidence_rate = c("person_years", "n_events", "rate", "rate_ci", "n_rate"), estimate_multinomial_response = c("n_prop", "prop_ci"), estimate_odds_ratio = c("or_ci", "n_tot"), estimate_proportion = c("n_prop", "prop_ci"), diff --git a/man/incidence_rate.Rd b/man/incidence_rate.Rd index d0d0c4d337..33f5f7e63e 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -17,7 +17,7 @@ estimate_incidence_rate( ..., show_labels = "hidden", table_names = vars, - .stats = NULL, + .stats = c("person_years", "n_events", "rate", "rate_ci"), .formats = NULL, .labels = NULL, .indent_mods = NULL @@ -102,6 +102,7 @@ the statistics from \code{s_incidence_rate()} to the table layout. \item \code{n_events}: Total number of events observed. \item \code{rate}: Estimated incidence rate. \item \code{rate_ci}: Confidence interval for the incidence rate. +\item \code{n_rate}: Total number of events observed & estimated incidence rate. } } diff --git a/tests/testthat/_snaps/estimate_incidence_rate.md b/tests/testthat/_snaps/estimate_incidence_rate.md index ba28293ec4..7133820dea 100644 --- a/tests/testthat/_snaps/estimate_incidence_rate.md +++ b/tests/testthat/_snaps/estimate_incidence_rate.md @@ -101,6 +101,11 @@ attr(,"label") [1] "90% CI" + $n_rate + [1] 4.00000 44.15823 + attr(,"label") + [1] "Number of adverse events observed (AE rate per 100 patient-years)" + # estimate_incidence_rate works as expected with healthy input @@ -115,3 +120,15 @@ AE rate per 100 patient-years 26.20 57.23 90% CI (5.06, 135.73) (22.14, 147.94) +# estimate_incidence_rate `n_rate` statistic works as expected + + Code + res + Output + A B + (N=3) (N=3) + ————————————————————————————————————————————————————————————————————————————————————— + Number of adverse events observed 1 3 + AE rate per 100 patient-years 2.18 4.77 + Number of adverse events observed (AE rate per 100 patient-years) 1 (2.2) 3 (4.8) + diff --git a/tests/testthat/test-estimate_incidence_rate.R b/tests/testthat/test-estimate_incidence_rate.R index f83173e1a2..2befdfa96f 100644 --- a/tests/testthat/test-estimate_incidence_rate.R +++ b/tests/testthat/test-estimate_incidence_rate.R @@ -109,3 +109,27 @@ testthat::test_that("estimate_incidence_rate works as expected with healthy inpu res <- testthat::expect_silent(result) testthat::expect_snapshot(res) }) + +testthat::test_that("estimate_incidence_rate `n_rate` statistic works as expected", { + df <- data.frame( + USUBJID = as.character(seq(6)), + CNSR = c(0, 1, 1, 0, 0, 0), + AVAL = c(10.1, 20.4, 15.3, 20.8, 18.7, 23.4), + ARM = factor(c("A", "A", "A", "B", "B", "B")) + ) %>% + dplyr::mutate(is_event = CNSR == 0) %>% + dplyr::mutate(n_events = as.integer(is_event)) + + result <- basic_table() %>% + split_cols_by("ARM") %>% + add_colcounts() %>% + estimate_incidence_rate( + vars = "AVAL", + n_events = "n_events", + .stats = c("n_events", "rate", "n_rate") + ) %>% + build_table(df) + + res <- testthat::expect_silent(result) + testthat::expect_snapshot(res) +}) From f9fb46785694c1535050ac6ade252b2193079808 Mon Sep 17 00:00:00 2001 From: edelarua Date: Thu, 5 Sep 2024 14:54:48 +0000 Subject: [PATCH 06/12] [skip actions] Bump version to 0.9.5.9019 --- DESCRIPTION | 2 +- NEWS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index ab8d790a13..d954b64410 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9018 +Version: 0.9.5.9019 Date: 2024-09-05 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), diff --git a/NEWS.md b/NEWS.md index f730e23c73..433e27619b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9018 +# tern 0.9.5.9019 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. From b2d1dbcde55b3775ceac7d6c041b5dc3f7df6dc9 Mon Sep 17 00:00:00 2001 From: Emily de la Rua <59304861+edelarua@users.noreply.github.com> Date: Thu, 5 Sep 2024 15:47:52 -0400 Subject: [PATCH 07/12] Improve analyze/summarize function documentation (#1283) Fixes #1130 --- NEWS.md | 1 + R/abnormal.R | 33 +- R/abnormal_by_baseline.R | 41 ++- R/abnormal_by_marked.R | 30 +- R/abnormal_by_worst_grade.R | 29 +- R/abnormal_by_worst_grade_worsen.R | 26 +- R/analyze_colvars_functions.R | 2 +- R/analyze_functions.R | 4 +- R/analyze_variables.R | 10 +- R/analyze_vars_in_cols.R | 27 +- R/compare_variables.R | 17 +- R/count_cumulative.R | 12 +- R/count_missed_doses.R | 15 +- R/count_occurrences.R | 17 +- R/count_occurrences_by_grade.R | 18 +- R/count_patients_events_in_cols.R | 12 +- R/count_patients_with_event.R | 9 +- R/count_patients_with_flags.R | 9 +- R/count_values.R | 21 +- R/estimate_multinomial_rsp.R | 7 +- R/estimate_proportion.R | 22 +- R/incidence_rate.R | 18 +- R/odds_ratio.R | 24 +- R/prop_diff.R | 9 +- R/prop_diff_test.R | 5 +- R/response_biomarkers_subgroups.R | 8 +- R/response_subgroups.R | 9 +- R/summarize_ancova.R | 18 +- R/summarize_change.R | 12 +- R/summarize_colvars.R | 14 +- R/summarize_functions.R | 1 - R/summarize_num_patients.R | 34 +- R/summarize_patients_exposure_in_cols.R | 19 +- R/survival_biomarkers_subgroups.R | 8 +- R/survival_coxph_pairwise.R | 23 +- R/survival_duration_subgroups.R | 7 +- R/survival_time.R | 6 +- R/survival_timepoint.R | 12 +- man/abnormal.Rd | 33 +- man/abnormal_by_baseline.Rd | 41 ++- man/abnormal_by_marked.Rd | 30 +- man/abnormal_by_worst_grade.Rd | 29 +- man/abnormal_by_worst_grade_worsen.Rd | 28 +- man/analyze_colvars_functions.Rd | 2 +- man/analyze_functions.Rd | 4 +- man/analyze_variables.Rd | 10 +- man/analyze_vars_in_cols.Rd | 28 +- man/compare_variables.Rd | 17 +- man/count_cumulative.Rd | 12 +- man/count_missed_doses.Rd | 16 +- man/count_occurrences.Rd | 17 +- man/count_occurrences_by_grade.Rd | 18 +- man/count_patients_events_in_cols.Rd | 12 +- man/count_patients_with_event.Rd | 9 +- man/count_patients_with_flags.Rd | 9 +- man/{count_values_funs.Rd => count_values.Rd} | 328 +++++++++--------- man/estimate_multinomial_rsp.Rd | 259 +++++++------- ..._proportions.Rd => estimate_proportion.Rd} | 13 +- man/extract_survival_subgroups.Rd | 7 +- man/h_incidence_rate.Rd | 8 +- man/h_proportions.Rd | 2 +- man/h_survival_duration_subgroups.Rd | 7 +- man/incidence_rate.Rd | 8 +- man/odds_ratio.Rd | 26 +- man/prop_diff.Rd | 8 +- man/prop_diff_test.Rd | 5 +- man/response_biomarkers_subgroups.Rd | 8 +- man/response_subgroups.Rd | 9 +- man/summarize_ancova.Rd | 18 +- man/summarize_change.Rd | 12 +- man/summarize_colvars.Rd | 14 +- man/summarize_functions.Rd | 1 - man/summarize_num_patients.Rd | 32 +- man/summarize_patients_exposure_in_cols.Rd | 19 +- man/survival_biomarkers_subgroups.Rd | 8 +- man/survival_coxph_pairwise.Rd | 39 ++- man/survival_duration_subgroups.Rd | 7 +- man/survival_time.Rd | 6 +- man/survival_timepoint.Rd | 12 +- 79 files changed, 1102 insertions(+), 658 deletions(-) rename man/{count_values_funs.Rd => count_values.Rd} (92%) rename man/{estimate_proportions.Rd => estimate_proportion.Rd} (91%) diff --git a/NEWS.md b/NEWS.md index 433e27619b..582bb5ee11 100644 --- a/NEWS.md +++ b/NEWS.md @@ -19,6 +19,7 @@ ### Miscellaneous * Began deprecation of the confusing functions `summary_formats` and `summary_labels`. +* Enhanced general descriptions of analyze and summarize functions throughout package documentation. # tern 0.9.5 diff --git a/R/abnormal.R b/R/abnormal.R index f8f86c0a61..05ccbcada9 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -1,13 +1,21 @@ -#' Patient counts with abnormal range values +#' Count patients with abnormal range values #' #' @description `r lifecycle::badge("stable")` #' -#' Primary analysis variable `.var` indicates the abnormal range result (`character` or `factor`) -#' and additional analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or -#' `factor`). For each direction specified in `abnormal` (e.g. high or low) count patients in the -#' numerator and denominator as follows: -#' * `num` : The number of patients with this abnormality recorded while on treatment. -#' * `denom`: The number of patients with at least one post-baseline assessment. +#' The analyze function [count_abnormal()] creates a layout element to count patients with abnormal analysis range +#' values in each direction. +#' +#' This function analyzes primary analysis variable `var` which indicates abnormal range results. +#' Additional analysis variables that can be supplied as a list via the `variables` parameter are +#' `id` (defaults to `USUBJID`), a variable to indicate unique subject identifiers, and `baseline` +#' (defaults to `BNRIND`), a variable to indicate baseline reference ranges. +#' +#' For each direction specified via the `abnormal` parameter (e.g. High or Low), a fraction of +#' patient counts is returned, with numerator and denominator calculated as follows: +#' * `num`: The number of patients with this abnormality recorded while on treatment. +#' * `denom`: The total number of patients with at least one post-baseline assessment. +#' +#' This function assumes that `df` has been filtered to only include post-baseline records. #' #' @inheritParams argument_convention #' @param abnormal (named `list`)\cr list identifying the abnormal range level(s) in `var`. Defaults to @@ -19,11 +27,12 @@ #' to see available statistics for this function. #' #' @note -#' * `count_abnormal()` only works with a single variable containing multiple abnormal levels. -#' * `df` should be filtered to include only post-baseline records. -#' * the denominator includes patients that might have other abnormal levels at baseline, -#' and patients with missing baseline. Patients with these abnormalities at -#' baseline can be optionally excluded from numerator and denominator. +#' * `count_abnormal()` only considers a single variable that contains multiple abnormal levels. +#' * `df` should be filtered to only include post-baseline records. +#' * The denominator includes patients that may have other abnormal levels at baseline, +#' and patients missing baseline records. Patients with these abnormalities at +#' baseline can be optionally excluded from numerator and denominator via the +#' `exclude_base_abn` parameter. #' #' @name abnormal #' @include formatting_functions.R diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index f49b9855fb..4ac5c10f4a 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -1,20 +1,31 @@ -#' Patient counts with abnormal range values by baseline status +#' Count patients with abnormal analysis range values by baseline status #' #' @description `r lifecycle::badge("stable")` #' -#' Primary analysis variable `.var` indicates the abnormal range result (`character` or `factor`), and additional -#' analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or `factor`). For each -#' direction specified in `abnormal` (e.g. high or low) we condition on baseline range result and count -#' patients in the numerator and denominator as follows: -#' * `Not ` -#' * `denom`: the number of patients without abnormality at baseline (excluding those with missing baseline) -#' * `num`: the number of patients in `denom` who also have at least one abnormality post-baseline -#' * `` -#' * `denom`: the number of patients with abnormality at baseline -#' * `num`: the number of patients in `denom` who also have at least one abnormality post-baseline +#' The analyze function [count_abnormal_by_baseline()] creates a layout element to count patients with abnormal +#' analysis range values, categorized by baseline status. +#' +#' This function analyzes primary analysis variable `var` which indicates abnormal range results. Additional +#' analysis variables that can be supplied as a list via the `variables` parameter are `id` (defaults to +#' `USUBJID`), a variable to indicate unique subject identifiers, and `baseline` (defaults to `BNRIND`), a +#' variable to indicate baseline reference ranges. +#' +#' For each direction specified via the `abnormal` parameter (e.g. High or Low), we condition on baseline +#' range result and count patients in the numerator and denominator as follows for each of the following +#' categories: +#' * `Not ` +#' * `num`: The number of patients without abnormality at baseline (excluding those with missing baseline) +#' and with at least one abnormality post-baseline. +#' * `denom`: The number of patients without abnormality at baseline (excluding those with missing baseline). +#' * `` +#' * `num`: The number of patients with abnormality as baseline and at least one abnormality post-baseline. +#' * `denom`: The number of patients with abnormality at baseline. #' * `Total` -#' * `denom`: the number of patients with at least one valid measurement post-baseline -#' * `num`: the number of patients in `denom` who also have at least one abnormality post-baseline +#' * `num`: The number of patients with at least one post-baseline record and at least one abnormality +#' post-baseline. +#' * `denom`: The number of patients with at least one post-baseline record. +#' +#' This function assumes that `df` has been filtered to only include post-baseline records. #' #' @inheritParams argument_convention #' @param abnormal (`character`)\cr values identifying the abnormal range level(s) in `.var`. @@ -23,8 +34,8 @@ #' #' @note #' * `df` should be filtered to include only post-baseline records. -#' * If the baseline variable or analysis variable contains `NA`, it is expected that `NA` has been -#' conveyed to `na_level` appropriately beforehand with [df_explicit_na()] or [explicit_na()]. +#' * If the baseline variable or analysis variable contains `NA` records, it is expected that `df` has been +#' pre-processed using [df_explicit_na()] or [explicit_na()]. #' #' @seealso Relevant description function [d_count_abnormal_by_baseline()]. #' diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index f8ac354424..d9eae8989f 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -2,14 +2,28 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Primary analysis variable `.var` indicates whether single, replicated or last marked laboratory -#' abnormality was observed (`factor`). Additional analysis variables are `id` (`character` or `factor`) -#' and `direction` (`factor`) indicating the direction of the abnormality. Denominator is number of -#' patients with at least one valid measurement during the analysis. -#' * For `Single, not last` and `Last or replicated`: Numerator is number of patients -#' with `Single, not last` and `Last or replicated` levels, respectively. -#' * For `Any`: Numerator is the number of patients with either single or -#' replicated marked abnormalities. +#' The analyze function [count_abnormal_by_marked()] creates a layout element to count patients with marked laboratory +#' abnormalities for each direction of abnormality, categorized by parameter value. +#' +#' This function analyzes primary analysis variable `var` which indicates whether a single, replicated, +#' or last marked laboratory abnormality was observed. Levels of `var` to include for each marked lab +#' abnormality (`single` and `last_replicated`) can be supplied via the `category` parameter. Additional +#' analysis variables that can be supplied as a list via the `variables` parameter are `id` (defaults +#' to `USUBJID`), a variable to indicate unique subject identifiers, `param` (defaults to `PARAM`), a +#' variable to indicate parameter values, and `direction` (defaults to `abn_dir`), a variable to indicate +#' abnormality directions. +#' +#' For each combination of `param` and `direction` levels, marked lab abnormality counts are calculated +#' as follows: +#' * `Single, not last` & `Last or replicated`: The number of patients with `Single, not last` +#' and `Last or replicated` values, respectively. +#' * `Any`: The number of patients with either single or replicated marked abnormalities. +#' +#' Fractions are calculated by dividing the above counts by the number of patients with at least one +#' valid measurement recorded during the analysis. +#' +#' Prior to using this function in your table layout you must use [rtables::split_rows_by()] to create two +#' row splits, one on variable `param` and one on variable `direction`. #' #' @inheritParams argument_convention #' @param category (`list`)\cr a list with different marked category names for single diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 4db59bd619..cb0376358d 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -1,20 +1,31 @@ -#' Patient counts with the most extreme post-baseline toxicity grade per direction of abnormality +#' Count patients by most extreme post-baseline toxicity grade per direction of abnormality #' #' @description `r lifecycle::badge("stable")` #' -#' Primary analysis variable `.var` indicates the toxicity grade (`factor`), and additional -#' analysis variables are `id` (`character` or `factor`), `param` (`factor`) and `grade_dir` (`factor`). -#' The pre-processing steps are crucial when using this function. -#' For a certain direction (e.g. high or low) this function counts -#' patients in the denominator as number of patients with at least one valid measurement during treatment, -#' and patients in the numerator as follows: -#' * `1` to `4`: Numerator is number of patients with worst grades 1-4 respectively; -#' * `Any`: Numerator is number of patients with at least one abnormality, which means grade is different from 0. +#' The analyze function [count_abnormal_by_worst_grade()] creates a layout element to count patients by highest (worst) +#' analysis toxicity grade post-baseline for each direction, categorized by parameter value. +#' +#' This function analyzes primary analysis variable `var` which indicates toxicity grades. Additional +#' analysis variables that can be supplied as a list via the `variables` parameter are `id` (defaults to +#' `USUBJID`), a variable to indicate unique subject identifiers, `param` (defaults to `PARAM`), a variable +#' to indicate parameter values, and `grade_dir` (defaults to `GRADE_DIR`), a variable to indicate directions +#' (e.g. High or Low) for each toxicity grade supplied in `var`. +#' +#' For each combination of `param` and `grade_dir` levels, patient counts by worst +#' grade are calculated as follows: +#' * `1` to `4`: The number of patients with worst grades 1-4, respectively. +#' * `Any`: The number of patients with at least one abnormality (i.e. grade is not 0). +#' +#' Fractions are calculated by dividing the above counts by the number of patients with at least one +#' valid measurement recorded during treatment. #' #' Pre-processing is crucial when using this function and can be done automatically using the #' [h_adlb_abnormal_by_worst_grade()] helper function. See the description of this function for details on the #' necessary pre-processing steps. #' +#' Prior to using this function in your table layout you must use [rtables::split_rows_by()] to create two row +#' splits, one on variable `param` and one on variable `grade_dir`. +#' #' @inheritParams argument_convention #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("abnormal_by_worst_grade")` #' to see available statistics for this function. diff --git a/R/abnormal_by_worst_grade_worsen.R b/R/abnormal_by_worst_grade_worsen.R index 87bcba02f4..ae1d8c60db 100644 --- a/R/abnormal_by_worst_grade_worsen.R +++ b/R/abnormal_by_worst_grade_worsen.R @@ -1,8 +1,27 @@ -#' Patient counts for laboratory events (worsen from baseline) by highest grade post-baseline +#' Count patients with toxicity grades that have worsened from baseline by highest grade post-baseline #' #' @description `r lifecycle::badge("stable")` #' -#' Patient count and fraction for laboratory events (worsen from baseline) shift table. +#' The analyze function [count_abnormal_lab_worsen_by_baseline()] creates a layout element to count patients with +#' analysis toxicity grades which have worsened from baseline, categorized by highest (worst) grade post-baseline. +#' +#' This function analyzes primary analysis variable `var` which indicates analysis toxicity grades. Additional +#' analysis variables that can be supplied as a list via the `variables` parameter are `id` (defaults to `USUBJID`), +#' a variable to indicate unique subject identifiers, `baseline_var` (defaults to `BTOXGR`), a variable to indicate +#' baseline toxicity grades, and `direction_var` (defaults to `GRADDIR`), a variable to indicate toxicity grade +#' directions of interest to include (e.g. `"H"` (high), `"L"` (low), or `"B"` (both)). +#' +#' For the direction(s) specified in `direction_var`, patient counts by worst grade for patients who have +#' worsened from baseline are calculated as follows: +#' * `1` to `4`: The number of patients who have worsened from their baseline grades with worst +#' grades 1-4, respectively. +#' * `Any`: The total number of patients who have worsened from their baseline grades. +#' +#' Fractions are calculated by dividing the above counts by the number of patients who's analysis toxicity grades +#' have worsened from baseline toxicity grades during treatment. +#' +#' Prior to using this function in your table layout you must use [rtables::split_rows_by()] to create a row +#' split on variable `direction_var`. #' #' @inheritParams argument_convention #' @param variables (named `list` of `string`)\cr list of additional analysis variables including: @@ -12,7 +31,8 @@ #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("abnormal_by_worst_grade_worsen")` #' to see all available statistics. #' -#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()] +#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()] which are used within +#' [s_count_abnormal_lab_worsen_by_baseline()] to process input data. #' #' @name abnormal_by_worst_grade_worsen #' @order 1 diff --git a/R/analyze_colvars_functions.R b/R/analyze_colvars_functions.R index 06822d5df0..1edd382169 100644 --- a/R/analyze_colvars_functions.R +++ b/R/analyze_colvars_functions.R @@ -1,4 +1,4 @@ -#' Analyze functions on columns +#' Analyze functions in columns #' #' @description #' These functions are wrappers of [rtables::analyze_colvars()] which apply corresponding `tern` diff --git a/R/analyze_functions.R b/R/analyze_functions.R index beef6efa6c..c5427c1300 100644 --- a/R/analyze_functions.R +++ b/R/analyze_functions.R @@ -6,6 +6,7 @@ #' to add an analysis to a given table layout: #' #' * [analyze_num_patients()] +#' * [analyze_vars()] #' * [compare_vars()] #' * [count_abnormal()] #' * [count_abnormal_by_baseline()] @@ -32,14 +33,13 @@ #' leverage `analyze_colvars` to have the context split in rows and the analysis #' methods in columns. #' * [summarize_change()] -#' * [analyze_vars()] #' * [surv_time()] #' * [surv_timepoint()] #' * [test_proportion_diff()] #' #' @seealso -#' * [summarize_functions] for functions which are wrappers for [rtables::summarize_row_groups()]. #' * [analyze_colvars_functions] for functions that are wrappers for [rtables::analyze_colvars()]. +#' * [summarize_functions] for functions which are wrappers for [rtables::summarize_row_groups()]. #' #' @name analyze_functions NULL diff --git a/R/analyze_variables.R b/R/analyze_variables.R index 88a47d6e40..6f6a212131 100644 --- a/R/analyze_variables.R +++ b/R/analyze_variables.R @@ -32,11 +32,11 @@ control_analyze_vars <- function(conf_level = 0.95, #' #' @description `r lifecycle::badge("stable")` #' -#' The analyze function [analyze_vars()] generates a summary of one or more variables, using the S3 generic function -#' [s_summary()] to calculate a list of summary statistics. A list of all available statistics for numeric -#' variables can be viewed by running `get_stats("analyze_vars_numeric")` and for non-numeric variables by running -#' `get_stats("analyze_vars_counts")`. Use the `.stats` parameter to specify the statistics to include in your output -#' summary table. +#' The analyze function [analyze_vars()] creates a layout element to summarize one or more variables, using the S3 +#' generic function [s_summary()] to calculate a list of summary statistics. A list of all available statistics for +#' numeric variables can be viewed by running `get_stats("analyze_vars_numeric")` and for non-numeric variables by +#' running `get_stats("analyze_vars_counts")`. Use the `.stats` parameter to specify the statistics to include in your +#' output summary table. #' #' @details #' **Automatic digit formatting:** The number of digits to display can be automatically determined from the analyzed diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 4414c414b1..42bfb3ba24 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -1,10 +1,12 @@ -#' Summarize numeric variables in columns +#' Analyze numeric variables in columns #' #' @description `r lifecycle::badge("experimental")` #' -#' Layout-creating function which can be used for creating column-wise summary tables. -#' This function sets the analysis methods as column labels and is a wrapper for -#' [rtables::analyze_colvars()]. It was designed principally for PK tables. +#' The layout-creating function [analyze_vars_in_cols()] creates a layout element to generate a column-wise +#' analysis table. +#' +#' This function sets the analysis methods as column labels and is a wrapper for [rtables::analyze_colvars()]. +#' It was designed principally for PK tables. #' #' @inheritParams argument_convention #' @inheritParams rtables::analyze_colvars @@ -35,16 +37,13 @@ #' Adding this function to an `rtable` layout will summarize the given variables, arrange the output #' in columns, and add it to the table layout. #' -#' @note This is an experimental implementation of [rtables::summarize_row_groups()] and -#' [rtables::analyze_colvars()] that may be subjected to changes as `rtables` extends its -#' support to more complex analysis pipelines on the column space. For the same reasons, -#' we encourage to read the examples carefully and file issues for cases that differ from -#' them. -#' -#' Here `labelstr` behaves differently than usual. If it is not defined (default as `NULL`), -#' row labels are assigned automatically to the split values in case of `rtables::analyze_colvars` -#' (`do_summarize_row_groups = FALSE`, the default), and to the group label for -#' `do_summarize_row_groups = TRUE`. +#' @note +#' * This is an experimental implementation of [rtables::summarize_row_groups()] and [rtables::analyze_colvars()] +#' that may be subjected to changes as `rtables` extends its support to more complex analysis pipelines in the +#' column space. We encourage users to read the examples carefully and file issues for different use cases. +#' * In this function, `labelstr` behaves atypically. If `labelstr = NULL` (the default), row labels are assigned +#' automatically as the split values if `do_summarize_row_groups = FALSE` (the default), and as the group label +#' if `do_summarize_row_groups = TRUE`. #' #' @seealso [analyze_vars()], [rtables::analyze_colvars()]. #' diff --git a/R/compare_variables.R b/R/compare_variables.R index 20bcef620d..3e9eb2ba9d 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -2,12 +2,21 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Comparison with a reference group for different `x` objects. +#' The analyze function [compare_vars()] creates a layout element to summarize and compare one or more variables, using +#' the S3 generic function [s_summary()] to calculate a list of summary statistics. A list of all available statistics +#' for numeric variables can be viewed by running `get_stats("analyze_vars_numeric", add_pval = TRUE)` and for +#' non-numeric variables by running `get_stats("analyze_vars_counts", add_pval = TRUE)`. Use the `.stats` parameter to +#' specify the statistics to include in your output summary table. +#' +#' Prior to using this function in your table layout you must use [rtables::split_cols_by()] to create a column +#' split on the variable to be used in comparisons, and specify a reference group via the `ref_group` parameter. +#' Comparisons can be performed for each group (column) against the specified reference group by including the p-value +#' statistic. #' #' @inheritParams argument_convention -#' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("analyze_vars_numeric")` to see -#' statistics available for numeric variables, and `get_stats("analyze_vars_counts")` for statistics available -#' for non-numeric variables. +#' @param .stats (`character`)\cr statistics to select for the table. Run +#' `get_stats("analyze_vars_numeric", add_pval = TRUE)` to see statistics available for numeric variables, and +#' `get_stats("analyze_vars_counts", add_pval = TRUE)` for statistics available for non-numeric variables. #' #' @note #' * For factor variables, `denom` for factor proportions can only be `n` since the purpose is to compare proportions diff --git a/R/count_cumulative.R b/R/count_cumulative.R index b1485847d6..8a73996fb4 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -1,9 +1,15 @@ -#' Cumulative counts with thresholds +#' Cumulative counts of numeric variable by thresholds #' #' @description `r lifecycle::badge("stable")` #' -#' Summarize cumulative counts of a `numeric` vector that is less than, less or equal to, -#' greater than, or greater or equal to user-specific thresholds. +#' The analyze function [count_cumulative()] creates a layout element to calculate cumulative counts of values in a +#' numeric variable that are less than, less or equal to, greater than, or greater or equal to user-specified +#' threshold values. +#' +#' This function analyzes numeric variable `vars` against the threshold values supplied to the `thresholds` +#' argument as a numeric vector. Whether counts should include the threshold values, and whether to count +#' values lower or higher than the threshold values can be set via the `include_eq` and `lower_tail` +#' parameters, respectively. #' #' @inheritParams h_count_cumulative #' @inheritParams argument_convention diff --git a/R/count_missed_doses.R b/R/count_missed_doses.R index 73026ed841..64eb2587c0 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -1,9 +1,13 @@ -#' Count missed doses +#' Count number of patients with missed doses by thresholds #' #' @description `r lifecycle::badge("stable")` #' -#' These are specific functions to count patients with missed doses. The difference to [count_cumulative()] is -#' mainly the special labels. +#' The analyze function creates a layout element to calculate cumulative counts of patients with number of missed +#' doses at least equal to user-specified threshold values. +#' +#' This function analyzes numeric variable `vars`, a variable with numbers of missed doses, +#' against the threshold values supplied to the `thresholds` argument as a numeric vector. This function +#' assumes that every row of the given data frame corresponds to a unique patient. #' #' @inheritParams s_count_cumulative #' @inheritParams argument_convention @@ -11,7 +15,10 @@ #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("count_missed_doses")` #' to see available statistics for this function. #' -#' @seealso Relevant description function [d_count_missed_doses()]. +#' @seealso +#' * Relevant description function [d_count_missed_doses()] which generates labels for [count_missed_doses()]. +#' * Similar analyze function [count_cumulative()] which more generally counts cumulative values and has more +#' options for threshold handling, but uses different labels. #' #' @name count_missed_doses #' @order 1 diff --git a/R/count_occurrences.R b/R/count_occurrences.R index a019296c2d..454457e906 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -1,11 +1,18 @@ -#' Occurrence counts +#' Count occurrences #' #' @description `r lifecycle::badge("stable")` #' -#' Functions for analyzing frequencies and fractions of occurrences for patients with occurrence -#' data. Primary analysis variables are the dictionary terms. All occurrences are counted for total -#' counts. Multiple occurrences within patient at the lowest term level displayed in the table are -#' counted only once. +#' The analyze function [count_occurrences()] creates a layout element to calculate occurrence counts for patients. +#' +#' This function analyzes the variable(s) supplied to `vars` and returns a table of occurrence counts for +#' each unique value (or level) of the variable(s). This variable (or variables) must be +#' non-numeric. The `id` variable is used to indicate unique subject identifiers (defaults to `USUBJID`). +#' +#' If there are multiple occurrences of the same value recorded for a patient, the value is only counted once. +#' +#' The summarize function [summarize_occurrences()] performs the same function as [count_occurrences()] except it +#' creates content rows, not data rows, to summarize the current table row/column context and operates on the level of +#' the latest row split or the root of the table if no row splits have occurred. #' #' @inheritParams argument_convention #' @param drop (`flag`)\cr whether non-appearing occurrence levels should be dropped from the resulting table. diff --git a/R/count_occurrences_by_grade.R b/R/count_occurrences_by_grade.R index 69d4afb03d..d9284a9bf2 100644 --- a/R/count_occurrences_by_grade.R +++ b/R/count_occurrences_by_grade.R @@ -1,10 +1,20 @@ -#' Occurrence counts by grade +#' Count occurrences by grade #' #' @description `r lifecycle::badge("stable")` #' -#' Functions for analyzing frequencies and fractions of occurrences by grade for patients -#' with occurrence data. Multiple occurrences within one individual are counted once at the -#' greatest intensity/highest grade level. +#' The analyze function [count_occurrences_by_grade()] creates a layout element to calculate occurrence counts by grade. +#' +#' This function analyzes primary analysis variable `var` which indicates toxicity grades. The `id` variable +#' is used to indicate unique subject identifiers (defaults to `USUBJID`). The user can also supply a list of +#' custom groups of grades to analyze via the `grade_groups` parameter. The `remove_single` argument will +#' remove single grades from the analysis so that *only* grade groups are analyzed. +#' +#' If there are multiple grades recorded for one patient only the highest grade level is counted. +#' +#' The summarize function [summarize_occurrences_by_grade()] performs the same function as +#' [count_occurrences_by_grade()] except it creates content rows, not data rows, to summarize the current table +#' row/column context and operates on the level of the latest row split or the root of the table if no row splits have +#' occurred. #' #' @inheritParams argument_convention #' @param grade_groups (named `list` of `character`)\cr list containing groupings of grades. diff --git a/R/count_patients_events_in_cols.R b/R/count_patients_events_in_cols.R index 394fe3af7b..f7c47d40ba 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -1,9 +1,15 @@ -#' Count patients and events in columns +#' Count patient events in columns #' #' @description `r lifecycle::badge("stable")` #' -#' Counting the number of unique patients and the total number of all and specific events -#' when a column table layout is required. +#' The summarize function [summarize_patients_events_in_cols()] creates a layout element to summarize patient +#' event counts in columns. +#' +#' This function analyzes the elements (events) supplied via the `filters_list` parameter and returns a row +#' with counts of number of patients for each event as well as the total numbers of patients and events. +#' The `id` variable is used to indicate unique subject identifiers (defaults to `USUBJID`). +#' +#' If there are multiple occurrences of the same event recorded for a patient, the event is only counted once. #' #' @inheritParams argument_convention #' @param filters_list (named `list` of `character`)\cr list where each element in this list describes one diff --git a/R/count_patients_with_event.R b/R/count_patients_with_event.R index ab14fdca17..0c00ff28ec 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -2,7 +2,14 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' The primary analysis variable `.var` denotes the unique patient identifier. +#' The analyze function [count_patients_with_event()] creates a layout element to calculate patient counts for a +#' user-specified set of events. +#' +#' This function analyzes primary analysis variable `vars` which indicates unique subject identifiers. Events +#' are defined by the user as a named vector via the `filters` argument, where each name corresponds to a +#' variable and each value is the value(s) that that variable takes for the event. +#' +#' If there are multiple records with the same event recorded for a patient, only one occurrence is counted. #' #' @inheritParams argument_convention #' @param filters (`character`)\cr a character vector specifying the column names and flag variables diff --git a/R/count_patients_with_flags.R b/R/count_patients_with_flags.R index 08cb4853ab..f14dcb259f 100644 --- a/R/count_patients_with_flags.R +++ b/R/count_patients_with_flags.R @@ -2,7 +2,14 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' The primary analysis variable `.var` denotes the unique patient identifier. +#' The analyze function [count_patients_with_flags()] creates a layout element to calculate counts of patients for +#' which user-specified flags are present. +#' +#' This function analyzes primary analysis variable `var` which indicates unique subject identifiers. Flags +#' variables to analyze are specified by the user via the `flag_variables` argument, and must either take value +#' `TRUE` (flag present) or `FALSE` (flag absent) for each record. +#' +#' If there are multiple records with the same flag present for a patient, only one occurrence is counted. #' #' @inheritParams argument_convention #' @param flag_variables (`character`)\cr a vector specifying the names of `logical` variables from analysis dataset diff --git a/R/count_values.R b/R/count_values.R index 4e3b91447d..961ea77f70 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -2,7 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' We can count the occurrence of specific values in a variable of interest. +#' The analyze function [count_values()] creates a layout element to calculate counts of specific values within a +#' variable of interest. +#' +#' This function analyzes one or more variables of interest supplied as a vector to `vars`. Values to +#' count for variable(s) in `vars` can be given as a vector via the `values` argument. One row of +#' counts will be generated for each variable. #' #' @inheritParams argument_convention #' @param values (`character`)\cr specific values that should be counted. @@ -15,11 +20,11 @@ #' * For `count_values()`, variable labels are shown when there is more than one element in `vars`, #' otherwise they are hidden. #' -#' @name count_values_funs +#' @name count_values #' @order 1 NULL -#' @describeIn count_values_funs S3 generic function to count values. +#' @describeIn count_values S3 generic function to count values. #' #' @inheritParams s_summary.logical #' @@ -36,7 +41,7 @@ s_count_values <- function(x, UseMethod("s_count_values", x) } -#' @describeIn count_values_funs Method for `character` class. +#' @describeIn count_values Method for `character` class. #' #' @method s_count_values character #' @@ -61,7 +66,7 @@ s_count_values.character <- function(x, s_summary(is_in_values, ...) } -#' @describeIn count_values_funs Method for `factor` class. This makes an automatic +#' @describeIn count_values Method for `factor` class. This makes an automatic #' conversion to `character` and then forwards to the method for characters. #' #' @method s_count_values factor @@ -77,7 +82,7 @@ s_count_values.factor <- function(x, s_count_values(as.character(x), values = as.character(values), ...) } -#' @describeIn count_values_funs Method for `logical` class. +#' @describeIn count_values Method for `logical` class. #' #' @method s_count_values logical #' @@ -91,7 +96,7 @@ s_count_values.logical <- function(x, values = TRUE, ...) { s_count_values(as.character(x), values = as.character(values), ...) } -#' @describeIn count_values_funs Formatted analysis function which is used as `afun` +#' @describeIn count_values Formatted analysis function which is used as `afun` #' in `count_values()`. #' #' @return @@ -107,7 +112,7 @@ a_count_values <- make_afun( .formats = c(count_fraction = "xx (xx.xx%)", count = "xx") ) -#' @describeIn count_values_funs Layout-creating function which can take statistics function arguments +#' @describeIn count_values Layout-creating function which can take statistics function arguments #' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @return diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index cd11ba5982..58bab1cad5 100644 --- a/R/estimate_multinomial_rsp.R +++ b/R/estimate_multinomial_rsp.R @@ -1,9 +1,10 @@ -#' Estimation of proportions per level of factor +#' Estimate proportions of each level of a variable #' #' @description `r lifecycle::badge("stable")` #' -#' Estimate the proportion along with confidence interval of a proportion -#' regarding the level of a factor. +#' The analyze & summarize function [estimate_multinomial_response()] creates a layout element to estimate the +#' proportion and proportion confidence interval for each level of a factor variable. The primary analysis variable, +#' `var`, should be a factor variable, the values of which will be used as labels within the output table. #' #' @inheritParams argument_convention #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("estimate_multinomial_response")` diff --git a/R/estimate_proportion.R b/R/estimate_proportion.R index 614406618d..ebe785a7d1 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -1,8 +1,12 @@ -#' Estimation of proportions +#' Proportion estimation #' #' @description `r lifecycle::badge("stable")` #' -#' Estimate the proportion of responders within a studied population. +#' The analyze function [estimate_proportion()] creates a layout element to estimate the proportion of responders +#' within a studied population. The primary analysis variable, `vars`, indicates whether a response has occurred for +#' each record. See the `method` parameter for options of methods to use when constructing the confidence interval of +#' the proportion. Additionally, a stratification variable can be supplied via the `strata` element of the `variables` +#' argument. #' #' @inheritParams prop_strat_wilson #' @inheritParams argument_convention @@ -15,11 +19,11 @@ #' #' @seealso [h_proportions] #' -#' @name estimate_proportions +#' @name estimate_proportion #' @order 1 NULL -#' @describeIn estimate_proportions Statistics function estimating a +#' @describeIn estimate_proportion Statistics function estimating a #' proportion along with its confidence interval. #' #' @param df (`logical` or `data.frame`)\cr if only a logical vector is used, @@ -128,7 +132,7 @@ s_proportion <- function(df, ) } -#' @describeIn estimate_proportions Formatted analysis function which is used as `afun` +#' @describeIn estimate_proportion Formatted analysis function which is used as `afun` #' in `estimate_proportion()`. #' #' @return @@ -140,7 +144,7 @@ a_proportion <- make_afun( .formats = c(n_prop = "xx (xx.x%)", prop_ci = "(xx.x, xx.x)") ) -#' @describeIn estimate_proportions Layout-creating function which can take statistics function arguments +#' @describeIn estimate_proportion Layout-creating function which can take statistics function arguments #' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @return @@ -152,7 +156,7 @@ a_proportion <- make_afun( #' dta_test <- data.frame( #' USUBJID = paste0("S", 1:12), #' ARM = rep(LETTERS[1:3], each = 4), -#' AVAL = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0)) +#' AVAL = rep(LETTERS[1:3], each = 4) #' ) #' #' basic_table() %>% @@ -214,11 +218,11 @@ estimate_proportion <- function(lyt, #' Functions to calculate different proportion confidence intervals for use in [estimate_proportion()]. #' #' @inheritParams argument_convention -#' @inheritParams estimate_proportions +#' @inheritParams estimate_proportion #' #' @return Confidence interval of a proportion. #' -#' @seealso [estimate_proportions], descriptive function [d_proportion()], +#' @seealso [estimate_proportion], descriptive function [d_proportion()], #' and helper functions [strata_normal_quantile()] and [update_weights_strat_wilson()]. #' #' @name h_proportions diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 2fda506e3b..08c295470b 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -1,9 +1,11 @@ -#' Incidence rate +#' Incidence rate estimation #' #' @description `r lifecycle::badge("stable")` #' -#' Estimate the event rate adjusted for person-years at risk, otherwise known -#' as incidence rate. Primary analysis variable is the person-years at risk. +#' The analyze function [estimate_incidence_rate()] creates a layout element to estimate an event rate adjusted for +#' person-years at risk, otherwise known as incidence rate. The primary analysis variable specified via `vars` is +#' the person-years at risk. In addition to this variable, the `n_events` variable for number of events observed (where +#' a value of 1 means an event was observed and 0 means that no event was observed) must also be specified. #' #' @inheritParams argument_convention #' @param control (`list`)\cr parameters for estimation details, specified by using @@ -178,17 +180,9 @@ estimate_incidence_rate <- function(lyt, #' #' @description `r lifecycle::badge("stable")` #' -#' @param control (`list`)\cr parameters for estimation details, specified by using -#' the helper function [control_incidence_rate()]. Possible parameter options are: -#' * `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. -#' * `input_time_unit`: (`string`)\cr `day`, `week`, `month`, or `year` (default) -#' indicating time unit for data input. -#' * `num_pt_year`: (`numeric`)\cr time unit for desired output (in person-years). +#' @inheritParams incidence_rate #' @param person_years (`numeric(1)`)\cr total person-years at risk. #' @param alpha (`numeric(1)`)\cr two-sided alpha-level for confidence interval. -#' @param n_events (`integer(1)`)\cr number of events observed. #' #' @return Estimated incidence rate, `rate`, and associated confidence interval, `rate_ci`. #' diff --git a/R/odds_ratio.R b/R/odds_ratio.R index b6468224fd..2f4a38d2fe 100644 --- a/R/odds_ratio.R +++ b/R/odds_ratio.R @@ -2,23 +2,25 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Compares bivariate responses between two groups in terms of odds ratios -#' along with a confidence interval. +#' The analyze function [estimate_odds_ratio()] creates a layout element to compare bivariate responses between +#' two groups by estimating an odds ratio and its confidence interval. +#' +#' The primary analysis variable specified by `vars` is the group variable. Additional variables can be included in the +#' analysis via the `variables` argument, which accepts `arm`, an arm variable, and `strata`, a stratification variable. +#' If more than two arm levels are present, they can be combined into two groups using the `groups_list` argument. #' #' @inheritParams split_cols_by_groups #' @inheritParams argument_convention #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("estimate_odds_ratio")` #' to see available statistics for this function. #' -#' @details This function uses either logistic regression for unstratified -#' analyses, or conditional logistic regression for stratified analyses. -#' The Wald confidence interval with the specified confidence level is -#' calculated. -#' -#' @note For stratified analyses, there is currently no implementation for conditional -#' likelihood confidence intervals, therefore the likelihood confidence interval is not -#' yet available as an option. Besides, when `rsp` contains only responders or non-responders, -#' then the result values will be `NA`, because no odds ratio estimation is possible. +#' @note +#' * This function uses logistic regression for unstratified analyses, and conditional logistic regression for +#' stratified analyses. The Wald confidence interval is calculated with the specified confidence level. +#' * For stratified analyses, there is currently no implementation for conditional likelihood confidence intervals, +#' therefore the likelihood confidence interval is not available as an option. +#' * When `vars` contains only responders or non-responders no odds ratio estimation is possible so the returned +#' values will be `NA`. #' #' @seealso Relevant helper function [h_odds_ratio()]. #' diff --git a/R/prop_diff.R b/R/prop_diff.R index ffbf1b1a70..ea5078f873 100644 --- a/R/prop_diff.R +++ b/R/prop_diff.R @@ -1,7 +1,14 @@ -#' Proportion difference +#' Proportion difference estimation #' #' @description `r lifecycle::badge("stable")` #' +#' The analysis function [estimate_proportion_diff()] creates a layout element to estimate the difference in proportion +#' of responders within a studied population. The primary analysis variable, `vars`, is a logical variable indicating +#' whether a response has occurred for each record. See the `method` parameter for options of methods to use when +#' constructing the confidence interval of the proportion difference. A stratification variable can be supplied via the +#' `strata` element of the `variables` argument. +#' +#' #' @inheritParams prop_diff_strat_nc #' @inheritParams argument_convention #' @param method (`string`)\cr the method used for the confidence interval estimation. diff --git a/R/prop_diff_test.R b/R/prop_diff_test.R index 359d386935..86188e673d 100644 --- a/R/prop_diff_test.R +++ b/R/prop_diff_test.R @@ -2,7 +2,10 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Various tests were implemented to test the difference between two proportions. +#' The analyze function [test_proportion_diff()] creates a layout element to test the difference between two +#' proportions. The primary analysis variable, `vars`, indicates whether a response has occurred for each record. See +#' the `method` parameter for options of methods to use to calculate the p-value. Additionally, a stratification +#' variable can be supplied via the `strata` element of the `variables` argument. #' #' @inheritParams argument_convention #' @param method (`string`)\cr one of `chisq`, `cmh`, `fisher`, or `schouten`; specifies the test used diff --git a/R/response_biomarkers_subgroups.R b/R/response_biomarkers_subgroups.R index 630b749b57..360432998b 100644 --- a/R/response_biomarkers_subgroups.R +++ b/R/response_biomarkers_subgroups.R @@ -2,8 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Tabulate the estimated effects of multiple continuous biomarker variables -#' on a binary response endpoint across population subgroups. +#' The [tabulate_rsp_biomarkers()] function creates a layout element to tabulate the estimated biomarker effects on a +#' binary response endpoint across subgroups, returning statistics including response rate and odds ratio for each +#' population subgroup. The table is created from `df`, a list of data frames returned by [extract_rsp_biomarkers()], +#' with the statistics to include specified via the `vars` parameter. +#' +#' A forest plot can be created from the resulting table using the [g_forest()] function. #' #' @inheritParams argument_convention #' @param df (`data.frame`)\cr containing all analysis variables, as returned by diff --git a/R/response_subgroups.R b/R/response_subgroups.R index c24606c58e..c7c61d4b94 100644 --- a/R/response_subgroups.R +++ b/R/response_subgroups.R @@ -2,7 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Tabulate statistics such as response rate and odds ratio for population subgroups. +#' The [tabulate_rsp_subgroups()] function creates a layout element to tabulate binary response by subgroup, returning +#' statistics including response rate and odds ratio for each population subgroup. The table is created from `df`, a +#' list of data frames returned by [extract_rsp_subgroups()], with the statistics to include specified via the `vars` +#' parameter. +#' +#' A forest plot can be created from the resulting table using the [g_forest()] function. #' #' @inheritParams extract_rsp_subgroups #' @inheritParams argument_convention @@ -164,7 +169,7 @@ a_response_subgroups <- function(.formats = list( #' summarizing binary response by subgroup. This function is a wrapper for [rtables::analyze_colvars()] #' and [rtables::summarize_row_groups()]. #' -#' @param df (`list`)\cr of data frames containing all analysis variables. List should be +#' @param df (`list`)\cr a list of data frames containing all analysis variables. List should be #' created using [extract_rsp_subgroups()]. #' @param vars (`character`)\cr the names of statistics to be reported among: #' * `n`: Total number of observations per group. diff --git a/R/summarize_ancova.R b/R/summarize_ancova.R index 2ccc523c36..9b2dc6d80a 100644 --- a/R/summarize_ancova.R +++ b/R/summarize_ancova.R @@ -1,14 +1,22 @@ -#' Summary for analysis of covariance (ANCOVA). +#' Summarize analysis of covariance (ANCOVA) results #' #' @description `r lifecycle::badge("stable")` #' -#' Summarize results of ANCOVA. This can be used to analyze multiple endpoints and/or -#' multiple timepoints within the same response variable `.var`. +#' The analyze function [summarize_ancova()] creates a layout element to summarize ANCOVA results. +#' +#' This function can be used to analyze multiple endpoints and/or multiple timepoints within the response variable(s) +#' specified as `vars`. +#' +#' Additional variables for the analysis, namely an arm (grouping) variable and covariate variables, can be defined +#' via the `variables` argument. See below for more details on how to specify `variables`. An interaction term can +#' be implemented in the model if needed. The interaction variable that should interact with the arm variable is +#' specified via the `interaction_term` parameter, and the specific value of `interaction_term` for which to extract +#' the ANCOVA results via the `interaction_y` parameter. #' #' @inheritParams h_ancova #' @inheritParams argument_convention -#' @param interaction_y (`string` or `flag`)\cr a selected item inside of the interaction_item column which will be used -#' to select the specific ANCOVA results. if the interaction is not needed, the default option is `FALSE`. +#' @param interaction_y (`string` or `flag`)\cr a selected item inside of the `interaction_item` variable which will be +#' used to select the specific ANCOVA results. if the interaction is not needed, the default option is `FALSE`. #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("summarize_ancova")` #' to see available statistics for this function. #' diff --git a/R/summarize_change.R b/R/summarize_change.R index 5bee62edb1..fe55a19e68 100644 --- a/R/summarize_change.R +++ b/R/summarize_change.R @@ -1,10 +1,14 @@ -#' Summarize the change from baseline or absolute baseline values +#' Summarize change from baseline values or absolute baseline values #' #' @description `r lifecycle::badge("stable")` #' -#' The primary analysis variable `.var` indicates the numerical change from baseline results, -#' and additional required secondary analysis variables are `value` and `baseline_flag`. -#' Depending on the baseline flag, either the absolute baseline values (at baseline) +#' The analyze function [summarize_change()] creates a layout element to summarize the change from baseline or absolute +#' baseline values. The primary analysis variable `vars` indicates the numerical change from baseline results. +#' +#' Required secondary analysis variables `value` and `baseline_flag` can be supplied to the function via +#' the `variables` argument. The `value` element should be the name of the analysis value variable, and the +#' `baseline_flag` element should be the name of the flag variable that indicates whether or not records contain +#' baseline values. Depending on the baseline flag given, either the absolute baseline values (at baseline) #' or the change from baseline values (post-baseline) are then summarized. #' #' @inheritParams argument_convention diff --git a/R/summarize_colvars.R b/R/summarize_colvars.R index 876d3f45ee..581539a8bc 100644 --- a/R/summarize_colvars.R +++ b/R/summarize_colvars.R @@ -2,14 +2,16 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' This analyze function uses the S3 generic function [s_summary()] to summarize different variables -#' that are arranged in columns. Additional standard formatting arguments are available. It is a -#' minimal wrapper for [rtables::analyze_colvars()]. The latter function is meant to add different -#' analysis methods for each column variables as different rows. To have the analysis methods as -#' column labels, please refer to [analyze_vars_in_cols()]. +#' The analyze function [summarize_colvars()] uses the statistics function [s_summary()] to analyze variables that are +#' arranged in columns. The variables to analyze should be specified in the table layout via column splits (see +#' [split_cols_by()] and [split_cols_by_multivar()]) prior to using [summarize_colvars()]. +#' +#' The function is a minimal wrapper for [rtables::analyze_colvars()], a function typically used to apply different +#' analysis methods in rows for each column variable. To use the analysis methods as column labels, please refer to +#' the [analyze_vars_in_cols()] function. #' #' @inheritParams argument_convention -#' @param ... arguments passed to `s_summary()`. +#' @param ... arguments passed to [s_summary()]. #' @param .indent_mods (named `vector` of `integer`)\cr indent modifiers for the labels. Each element of the vector #' should be a name-value pair with name corresponding to a statistic specified in `.stats` and value the indentation #' for that statistic's row label. diff --git a/R/summarize_functions.R b/R/summarize_functions.R index 890fc1619f..ed25ceaef1 100644 --- a/R/summarize_functions.R +++ b/R/summarize_functions.R @@ -12,7 +12,6 @@ #' * [summarize_occurrences_by_grade()] #' * [summarize_patients_events_in_cols()] #' * [summarize_patients_exposure_in_cols()] -#' * [tabulate_rsp_subgroups()] #' #' Additionally, the [summarize_coxreg()] function utilizes [`rtables::summarize_row_groups()`] #' (in combination with several other `rtables` functions like [rtables::analyze_colvars()]) to diff --git a/R/summarize_num_patients.R b/R/summarize_num_patients.R index 50b006ca37..d7deb2f4b7 100644 --- a/R/summarize_num_patients.R +++ b/R/summarize_num_patients.R @@ -1,12 +1,22 @@ -#' Number of patients +#' Count number of patients #' #' @description `r lifecycle::badge("stable")` #' -#' Count the number of unique and non-unique patients in a column (variable). +#' The analyze function [analyze_num_patients()] creates a layout element to count total numbers of unique or +#' non-unique patients. The primary analysis variable `vars` is used to uniquely identify patients. +#' +#' The `count_by` variable can be used to identify non-unique patients such that the number of patients with a unique +#' combination of values in `vars` and `count_by` will be returned instead as the `nonunique` statistic. The `required` +#' variable can be used to specify a variable required to be non-missing for the record to be included in the counts. +#' +#' The summarize function [summarize_num_patients()] performs the same function as [analyze_num_patients()] except it +#' creates content rows, not data rows, to summarize the current table row/column context and operates on the level of +#' the latest row split or the root of the table if no row splits have occurred. #' #' @inheritParams argument_convention -#' @param count_by (`vector`)\cr optional vector of any type to be combined with `x` when counting `nonunique` -#' records. +#' @param required (`character` or `NULL`)\cr name of a variable that is required to be non-missing. +#' @param count_by (`character` or `NULL`)\cr name of a variable to be combined with `vars` when counting +#' `nonunique` records. #' @param unique_count_suffix (`flag`)\cr whether the `"(n)"` suffix should be added to `unique_count` labels. #' Defaults to `TRUE`. #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("summarize_num_patients")` @@ -69,8 +79,6 @@ s_num_patients <- function(x, labelstr, .N_col, count_by = NULL, unique_count_su #' in a column (variable), the corresponding percentage taken with respect to the total number of #' patients, and the number of non-unique patients in the column. #' -#' @param required (`character` or `NULL`)\cr optional, name of a variable that is required to be non-missing. -#' #' @return #' * `s_num_patients_content()` returns the same values as `s_num_patients()`. #' @@ -136,6 +144,16 @@ c_num_patients <- make_afun( #' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing #' the statistics from `s_num_patients_content()` to the table layout. #' +#' @examples +#' # summarize_num_patients +#' tbl <- basic_table() %>% +#' split_cols_by("ARM") %>% +#' split_rows_by("SEX") %>% +#' summarize_num_patients("USUBJID", .stats = "unique_count") %>% +#' build_table(df) +#' +#' tbl +#' #' @export #' @order 3 summarize_num_patients <- function(lyt, @@ -209,9 +227,11 @@ summarize_num_patients <- function(lyt, #' df <- data.frame( #' USUBJID = as.character(c(1, 2, 1, 4, NA, 6, 6, 8, 9)), #' ARM = c("A", "A", "A", "A", "A", "B", "B", "B", "B"), -#' AGE = c(10, 15, 10, 17, 8, 11, 11, 19, 17) +#' AGE = c(10, 15, 10, 17, 8, 11, 11, 19, 17), +#' SEX = c("M", "M", "M", "F", "F", "F", "M", "F", "M") #' ) #' +#' # analyze_num_patients #' tbl <- basic_table() %>% #' split_cols_by("ARM") %>% #' add_colcounts() %>% diff --git a/R/summarize_patients_exposure_in_cols.R b/R/summarize_patients_exposure_in_cols.R index 632653b784..44d7f66bf6 100644 --- a/R/summarize_patients_exposure_in_cols.R +++ b/R/summarize_patients_exposure_in_cols.R @@ -1,9 +1,22 @@ -#' Count patients and sum exposure across all patients in columns +#' Count number of patients and sum exposure across all patients in columns #' #' @description `r lifecycle::badge("stable")` #' -#' Counting the number of patients and summing analysis value (i.e exposure values) across all patients -#' when a column table layout is required. +#' The analyze function [analyze_patients_exposure_in_cols()] creates a layout element to count total numbers of +#' patients and sum an analysis value (i.e. exposure) across all patients in columns. +#' +#' The primary analysis variable `ex_var` is the exposure variable used to calculate the `sum_exposure` statistic. The +#' `id` variable is used to uniquely identify patients in the data such that only unique patients are counted in the +#' `n_patients` statistic, and the `var` variable is used to create a row split if needed. The percentage returned as +#' part of the `n_patients` statistic is the proportion of all records that correspond to a unique patient. +#' +#' The summarize function [summarize_patients_exposure_in_cols()] performs the same function as +#' [analyze_patients_exposure_in_cols()] except it creates content rows, not data rows, to summarize the current table +#' row/column context and operates on the level of the latest row split or the root of the table if no row splits have +#' occurred. +#' +#' If a column split has not yet been performed in the table, `col_split` must be set to `TRUE` for the first call of +#' [analyze_patients_exposure_in_cols()] or [summarize_patients_exposure_in_cols()]. #' #' @inheritParams argument_convention #' @param ex_var (`string`)\cr name of the variable in `df` containing exposure values. diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index 3a6eec6691..c527f0209e 100644 --- a/R/survival_biomarkers_subgroups.R +++ b/R/survival_biomarkers_subgroups.R @@ -2,8 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Tabulate the estimated effects of multiple continuous biomarker variables -#' across population subgroups. +#' The [tabulate_survival_biomarkers()] function creates a layout element to tabulate the estimated effects of multiple +#' continuous biomarker variables on survival across subgroups, returning statistics including median survival time and +#' hazard ratio for each population subgroup. The table is created from `df`, a list of data frames returned by +#' [extract_survival_biomarkers()], with the statistics to include specified via the `vars` parameter. +#' +#' A forest plot can be created from the resulting table using the [g_forest()] function. #' #' @inheritParams fit_coxreg_multivar #' @inheritParams survival_duration_subgroups diff --git a/R/survival_coxph_pairwise.R b/R/survival_coxph_pairwise.R index 4703a305f5..4495962290 100644 --- a/R/survival_coxph_pairwise.R +++ b/R/survival_coxph_pairwise.R @@ -1,8 +1,12 @@ -#' Pairwise Cox-PH model +#' Analyze a pairwise Cox-PH model #' #' @description `r lifecycle::badge("stable")` #' -#' Summarize p-value, HR and CIs from stratified or unstratified Cox-PH model. +#' The analyze function [coxph_pairwise()] creates a layout element to analyze a pairwise Cox-PH model. +#' +#' This function can return statistics including p-value, hazard ratio (HR), and HR confidence intervals from both +#' stratified and unstratified Cox-PH models. The variable(s) to be analyzed is specified via the `vars` argument and +#' any stratification factors via the `strata` argument. #' #' @inheritParams argument_convention #' @inheritParams s_surv_time @@ -10,10 +14,11 @@ #' @param strat `r lifecycle::badge("deprecated")` Please use the `strata` argument instead. #' @param control (`list`)\cr parameters for comparison details, specified by using the helper function #' [control_coxph()]. Some possible parameter options are: -#' * `pval_method` (`string`)\cr p-value method for testing hazard ratio = 1. Default method is `"log-rank"` which -#' comes from [survival::survdiff()], can also be set to `"wald"` or `"likelihood"` (from [survival::coxph()]). +#' * `pval_method` (`string`)\cr p-value method for testing the null hypothesis that hazard ratio = 1. Default +#' method is `"log-rank"` which comes from [survival::survdiff()], can also be set to `"wald"` or `"likelihood"` +#' (from [survival::coxph()]). #' * `ties` (`string`)\cr specifying the method for tie handling. Default is `"efron"`, -#' can also be set to `"breslow"` or `"exact"`. See more in [survival::coxph()] +#' can also be set to `"breslow"` or `"exact"`. See more in [survival::coxph()]. #' * `conf_level` (`proportion`)\cr confidence level of the interval for HR. #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("coxph_pairwise")` #' to see available statistics for this function. @@ -22,11 +27,11 @@ #' @order 1 NULL -#' @describeIn survival_coxph_pairwise Statistics function which analyzes HR, CIs of HR and p-value of a `coxph` model. +#' @describeIn survival_coxph_pairwise Statistics function which analyzes HR, CIs of HR, and p-value of a Cox-PH model. #' #' @return #' * `s_coxph_pairwise()` returns the statistics: -#' * `pvalue`: p-value to test HR = 1. +#' * `pvalue`: p-value to test the null hypothesis that hazard ratio = 1. #' * `hr`: Hazard ratio. #' * `hr_ci`: Confidence interval for hazard ratio. #' * `n_tot`: Total number of observations. @@ -173,6 +178,8 @@ a_coxph_pairwise <- make_afun( #' @order 2 coxph_pairwise <- function(lyt, vars, + strata = NULL, + control = control_coxph(), na_str = default_na_str(), nested = TRUE, ..., @@ -183,7 +190,7 @@ coxph_pairwise <- function(lyt, .formats = NULL, .labels = NULL, .indent_mods = NULL) { - extra_args <- list(...) + extra_args <- list(strata = strata, control = control, ...) afun <- make_afun( a_coxph_pairwise, diff --git a/R/survival_duration_subgroups.R b/R/survival_duration_subgroups.R index 06277defe0..90fc9b2376 100644 --- a/R/survival_duration_subgroups.R +++ b/R/survival_duration_subgroups.R @@ -2,7 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Tabulate statistics such as median survival time and hazard ratio for population subgroups. +#' The [tabulate_survival_subgroups()] function creates a layout element to tabulate survival duration by subgroup, +#' returning statistics including median survival time and hazard ratio for each population subgroup. The table is +#' created from `df`, a list of data frames returned by [extract_survival_subgroups()], with the statistics to include +#' specified via the `vars` parameter. +#' +#' A forest plot can be created from the resulting table using the [g_forest()] function. #' #' @inheritParams argument_convention #' @inheritParams survival_coxph_pairwise diff --git a/R/survival_time.R b/R/survival_time.R index a277264033..fd13f0ce73 100644 --- a/R/survival_time.R +++ b/R/survival_time.R @@ -2,8 +2,10 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Summarize median survival time and CIs, percentiles of survival times, survival -#' time range of censored/event patients. +#' The analyze function [surv_time()] creates a layout element to analyze survival time by calculating survival time +#' median, median confidence interval, quantiles, and range (for all, censored, or event patients). The primary +#' analysis variable `vars` is the time variable and the secondary analysis variable `is_event` indicates whether or +#' not an event has occurred. #' #' @inheritParams argument_convention #' @param control (`list`)\cr parameters for comparison details, specified by using the helper function diff --git a/R/survival_timepoint.R b/R/survival_timepoint.R index 586a2b5410..021e8f2e6d 100644 --- a/R/survival_timepoint.R +++ b/R/survival_timepoint.R @@ -2,7 +2,12 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Summarize patients' survival rate and difference of survival rates between groups at a time point. +#' The analyze function [surv_timepoint()] creates a layout element to analyze patient survival rates and difference +#' of survival rates between groups at a given time point. The primary analysis variable `vars` is the time variable. +#' Other required inputs are `time_point`, the numeric time point of interest, and `is_event`, a variable that +#' indicates whether or not an event has occurred. The `method` argument is used to specify whether you want to analyze +#' survival estimations (`"surv"`), difference in survival with the control (`"surv_diff"`), or both of these +#' (`"both"`). #' #' @inheritParams argument_convention #' @inheritParams s_surv_time @@ -12,9 +17,8 @@ #' * `conf_level` (`proportion`)\cr confidence level of the interval for survival rate. #' * `conf_type` (`string`)\cr confidence interval type. Options are "plain" (default), "log", "log-log", #' see more in [survival::survfit()]. Note option "none" is no longer supported. -#' * `time_point` (`numeric(1)`)\cr survival time point of interest. -#' @param method (`string`)\cr `surv` (survival estimations), -#' `surv_diff` (difference in survival with the control), or `both`. +#' @param method (`string`)\cr `"surv"` (survival estimations), `"surv_diff"` (difference in survival with the +#' control), or `"both"`. #' @param table_names_suffix (`string`)\cr optional suffix for the `table_names` used for the `rtables` to #' avoid warnings from duplicate table names. #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("surv_timepoint")` diff --git a/man/abnormal.Rd b/man/abnormal.Rd index 056f278f32..092d1f1a42 100644 --- a/man/abnormal.Rd +++ b/man/abnormal.Rd @@ -5,7 +5,7 @@ \alias{count_abnormal} \alias{s_count_abnormal} \alias{a_count_abnormal} -\title{Patient counts with abnormal range values} +\title{Count patients with abnormal range values} \usage{ count_abnormal( lyt, @@ -96,14 +96,22 @@ the statistics from \code{s_count_abnormal()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Primary analysis variable \code{.var} indicates the abnormal range result (\code{character} or \code{factor}) -and additional analysis variables are \code{id} (\code{character} or \code{factor}) and \code{baseline} (\code{character} or -\code{factor}). For each direction specified in \code{abnormal} (e.g. high or low) count patients in the -numerator and denominator as follows: +The analyze function \code{\link[=count_abnormal]{count_abnormal()}} creates a layout element to count patients with abnormal analysis range +values in each direction. + +This function analyzes primary analysis variable \code{var} which indicates abnormal range results. +Additional analysis variables that can be supplied as a list via the \code{variables} parameter are +\code{id} (defaults to \code{USUBJID}), a variable to indicate unique subject identifiers, and \code{baseline} +(defaults to \code{BNRIND}), a variable to indicate baseline reference ranges. + +For each direction specified via the \code{abnormal} parameter (e.g. High or Low), a fraction of +patient counts is returned, with numerator and denominator calculated as follows: \itemize{ -\item \code{num} : The number of patients with this abnormality recorded while on treatment. -\item \code{denom}: The number of patients with at least one post-baseline assessment. +\item \code{num}: The number of patients with this abnormality recorded while on treatment. +\item \code{denom}: The total number of patients with at least one post-baseline assessment. } + +This function assumes that \code{df} has been filtered to only include post-baseline records. } \section{Functions}{ \itemize{ @@ -118,11 +126,12 @@ for a single \code{abnormal} level. }} \note{ \itemize{ -\item \code{count_abnormal()} only works with a single variable containing multiple abnormal levels. -\item \code{df} should be filtered to include only post-baseline records. -\item the denominator includes patients that might have other abnormal levels at baseline, -and patients with missing baseline. Patients with these abnormalities at -baseline can be optionally excluded from numerator and denominator. +\item \code{count_abnormal()} only considers a single variable that contains multiple abnormal levels. +\item \code{df} should be filtered to only include post-baseline records. +\item The denominator includes patients that may have other abnormal levels at baseline, +and patients missing baseline records. Patients with these abnormalities at +baseline can be optionally excluded from numerator and denominator via the +\code{exclude_base_abn} parameter. } } \examples{ diff --git a/man/abnormal_by_baseline.Rd b/man/abnormal_by_baseline.Rd index f5fd8f9e6a..e8bbac47c2 100644 --- a/man/abnormal_by_baseline.Rd +++ b/man/abnormal_by_baseline.Rd @@ -5,7 +5,7 @@ \alias{count_abnormal_by_baseline} \alias{s_count_abnormal_by_baseline} \alias{a_count_abnormal_by_baseline} -\title{Patient counts with abnormal range values by baseline status} +\title{Count patients with abnormal analysis range values by baseline status} \usage{ count_abnormal_by_baseline( lyt, @@ -92,27 +92,38 @@ the statistics from \code{s_count_abnormal_by_baseline()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Primary analysis variable \code{.var} indicates the abnormal range result (\code{character} or \code{factor}), and additional -analysis variables are \code{id} (\code{character} or \code{factor}) and \code{baseline} (\code{character} or \code{factor}). For each -direction specified in \code{abnormal} (e.g. high or low) we condition on baseline range result and count -patients in the numerator and denominator as follows: +The analyze function \code{\link[=count_abnormal_by_baseline]{count_abnormal_by_baseline()}} creates a layout element to count patients with abnormal +analysis range values, categorized by baseline status. + +This function analyzes primary analysis variable \code{var} which indicates abnormal range results. Additional +analysis variables that can be supplied as a list via the \code{variables} parameter are \code{id} (defaults to +\code{USUBJID}), a variable to indicate unique subject identifiers, and \code{baseline} (defaults to \code{BNRIND}), a +variable to indicate baseline reference ranges. + +For each direction specified via the \code{abnormal} parameter (e.g. High or Low), we condition on baseline +range result and count patients in the numerator and denominator as follows for each of the following +categories: \itemize{ -\item \verb{Not } +\item \verb{Not } \itemize{ -\item \code{denom}: the number of patients without abnormality at baseline (excluding those with missing baseline) -\item \code{num}: the number of patients in \code{denom} who also have at least one abnormality post-baseline +\item \code{num}: The number of patients without abnormality at baseline (excluding those with missing baseline) +and with at least one abnormality post-baseline. +\item \code{denom}: The number of patients without abnormality at baseline (excluding those with missing baseline). } -\item \verb{} +\item \verb{} \itemize{ -\item \code{denom}: the number of patients with abnormality at baseline -\item \code{num}: the number of patients in \code{denom} who also have at least one abnormality post-baseline +\item \code{num}: The number of patients with abnormality as baseline and at least one abnormality post-baseline. +\item \code{denom}: The number of patients with abnormality at baseline. } \item \code{Total} \itemize{ -\item \code{denom}: the number of patients with at least one valid measurement post-baseline -\item \code{num}: the number of patients in \code{denom} who also have at least one abnormality post-baseline +\item \code{num}: The number of patients with at least one post-baseline record and at least one abnormality +post-baseline. +\item \code{denom}: The number of patients with at least one post-baseline record. } } + +This function assumes that \code{df} has been filtered to only include post-baseline records. } \section{Functions}{ \itemize{ @@ -128,8 +139,8 @@ in \code{count_abnormal_by_baseline()}. \note{ \itemize{ \item \code{df} should be filtered to include only post-baseline records. -\item If the baseline variable or analysis variable contains \code{NA}, it is expected that \code{NA} has been -conveyed to \code{na_level} appropriately beforehand with \code{\link[=df_explicit_na]{df_explicit_na()}} or \code{\link[=explicit_na]{explicit_na()}}. +\item If the baseline variable or analysis variable contains \code{NA} records, it is expected that \code{df} has been +pre-processed using \code{\link[=df_explicit_na]{df_explicit_na()}} or \code{\link[=explicit_na]{explicit_na()}}. } } \examples{ diff --git a/man/abnormal_by_marked.Rd b/man/abnormal_by_marked.Rd index 8a8200d41a..946a162c67 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -91,16 +91,30 @@ the statistics from \code{s_count_abnormal_by_marked()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Primary analysis variable \code{.var} indicates whether single, replicated or last marked laboratory -abnormality was observed (\code{factor}). Additional analysis variables are \code{id} (\code{character} or \code{factor}) -and \code{direction} (\code{factor}) indicating the direction of the abnormality. Denominator is number of -patients with at least one valid measurement during the analysis. +The analyze function \code{\link[=count_abnormal_by_marked]{count_abnormal_by_marked()}} creates a layout element to count patients with marked laboratory +abnormalities for each direction of abnormality, categorized by parameter value. + +This function analyzes primary analysis variable \code{var} which indicates whether a single, replicated, +or last marked laboratory abnormality was observed. Levels of \code{var} to include for each marked lab +abnormality (\code{single} and \code{last_replicated}) can be supplied via the \code{category} parameter. Additional +analysis variables that can be supplied as a list via the \code{variables} parameter are \code{id} (defaults +to \code{USUBJID}), a variable to indicate unique subject identifiers, \code{param} (defaults to \code{PARAM}), a +variable to indicate parameter values, and \code{direction} (defaults to \code{abn_dir}), a variable to indicate +abnormality directions. + +For each combination of \code{param} and \code{direction} levels, marked lab abnormality counts are calculated +as follows: \itemize{ -\item For \verb{Single, not last} and \verb{Last or replicated}: Numerator is number of patients -with \verb{Single, not last} and \verb{Last or replicated} levels, respectively. -\item For \code{Any}: Numerator is the number of patients with either single or -replicated marked abnormalities. +\item \verb{Single, not last} & \verb{Last or replicated}: The number of patients with \verb{Single, not last} +and \verb{Last or replicated} values, respectively. +\item \code{Any}: The number of patients with either single or replicated marked abnormalities. } + +Fractions are calculated by dividing the above counts by the number of patients with at least one +valid measurement recorded during the analysis. + +Prior to using this function in your table layout you must use \code{\link[rtables:split_rows_by]{rtables::split_rows_by()}} to create two +row splits, one on variable \code{param} and one on variable \code{direction}. } \section{Functions}{ \itemize{ diff --git a/man/abnormal_by_worst_grade.Rd b/man/abnormal_by_worst_grade.Rd index 3be54e8425..2f17eabe1b 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -5,7 +5,7 @@ \alias{count_abnormal_by_worst_grade} \alias{s_count_abnormal_by_worst_grade} \alias{a_count_abnormal_by_worst_grade} -\title{Patient counts with the most extreme post-baseline toxicity grade per direction of abnormality} +\title{Count patients by most extreme post-baseline toxicity grade per direction of abnormality} \usage{ count_abnormal_by_worst_grade( lyt, @@ -85,20 +85,31 @@ the statistics from \code{s_count_abnormal_by_worst_grade()} to the table layout \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Primary analysis variable \code{.var} indicates the toxicity grade (\code{factor}), and additional -analysis variables are \code{id} (\code{character} or \code{factor}), \code{param} (\code{factor}) and \code{grade_dir} (\code{factor}). -The pre-processing steps are crucial when using this function. -For a certain direction (e.g. high or low) this function counts -patients in the denominator as number of patients with at least one valid measurement during treatment, -and patients in the numerator as follows: +The analyze function \code{\link[=count_abnormal_by_worst_grade]{count_abnormal_by_worst_grade()}} creates a layout element to count patients by highest (worst) +analysis toxicity grade post-baseline for each direction, categorized by parameter value. + +This function analyzes primary analysis variable \code{var} which indicates toxicity grades. Additional +analysis variables that can be supplied as a list via the \code{variables} parameter are \code{id} (defaults to +\code{USUBJID}), a variable to indicate unique subject identifiers, \code{param} (defaults to \code{PARAM}), a variable +to indicate parameter values, and \code{grade_dir} (defaults to \code{GRADE_DIR}), a variable to indicate directions +(e.g. High or Low) for each toxicity grade supplied in \code{var}. + +For each combination of \code{param} and \code{grade_dir} levels, patient counts by worst +grade are calculated as follows: \itemize{ -\item \code{1} to \code{4}: Numerator is number of patients with worst grades 1-4 respectively; -\item \code{Any}: Numerator is number of patients with at least one abnormality, which means grade is different from 0. +\item \code{1} to \code{4}: The number of patients with worst grades 1-4, respectively. +\item \code{Any}: The number of patients with at least one abnormality (i.e. grade is not 0). } +Fractions are calculated by dividing the above counts by the number of patients with at least one +valid measurement recorded during treatment. + Pre-processing is crucial when using this function and can be done automatically using the \code{\link[=h_adlb_abnormal_by_worst_grade]{h_adlb_abnormal_by_worst_grade()}} helper function. See the description of this function for details on the necessary pre-processing steps. + +Prior to using this function in your table layout you must use \code{\link[rtables:split_rows_by]{rtables::split_rows_by()}} to create two row +splits, one on variable \code{param} and one on variable \code{grade_dir}. } \section{Functions}{ \itemize{ diff --git a/man/abnormal_by_worst_grade_worsen.Rd b/man/abnormal_by_worst_grade_worsen.Rd index c09bb546fb..27dfcd987e 100644 --- a/man/abnormal_by_worst_grade_worsen.Rd +++ b/man/abnormal_by_worst_grade_worsen.Rd @@ -5,7 +5,7 @@ \alias{count_abnormal_lab_worsen_by_baseline} \alias{s_count_abnormal_lab_worsen_by_baseline} \alias{a_count_abnormal_lab_worsen_by_baseline} -\title{Patient counts for laboratory events (worsen from baseline) by highest grade post-baseline} +\title{Count patients with toxicity grades that have worsened from baseline by highest grade post-baseline} \usage{ count_abnormal_lab_worsen_by_baseline( lyt, @@ -91,7 +91,28 @@ formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Patient count and fraction for laboratory events (worsen from baseline) shift table. +The analyze function \code{\link[=count_abnormal_lab_worsen_by_baseline]{count_abnormal_lab_worsen_by_baseline()}} creates a layout element to count patients with +analysis toxicity grades which have worsened from baseline, categorized by highest (worst) grade post-baseline. + +This function analyzes primary analysis variable \code{var} which indicates analysis toxicity grades. Additional +analysis variables that can be supplied as a list via the \code{variables} parameter are \code{id} (defaults to \code{USUBJID}), +a variable to indicate unique subject identifiers, \code{baseline_var} (defaults to \code{BTOXGR}), a variable to indicate +baseline toxicity grades, and \code{direction_var} (defaults to \code{GRADDIR}), a variable to indicate toxicity grade +directions of interest to include (e.g. \code{"H"} (high), \code{"L"} (low), or \code{"B"} (both)). + +For the direction(s) specified in \code{direction_var}, patient counts by worst grade for patients who have +worsened from baseline are calculated as follows: +\itemize{ +\item \code{1} to \code{4}: The number of patients who have worsened from their baseline grades with worst +grades 1-4, respectively. +\item \code{Any}: The total number of patients who have worsened from their baseline grades. +} + +Fractions are calculated by dividing the above counts by the number of patients who's analysis toxicity grades +have worsened from baseline toxicity grades during treatment. + +Prior to using this function in your table layout you must use \code{\link[rtables:split_rows_by]{rtables::split_rows_by()}} to create a row +split on variable \code{direction_var}. } \section{Functions}{ \itemize{ @@ -144,6 +165,7 @@ basic_table() \%>\% } \seealso{ -Relevant helper functions \code{\link[=h_adlb_worsen]{h_adlb_worsen()}} and \code{\link[=h_worsen_counter]{h_worsen_counter()}} +Relevant helper functions \code{\link[=h_adlb_worsen]{h_adlb_worsen()}} and \code{\link[=h_worsen_counter]{h_worsen_counter()}} which are used within +\code{\link[=s_count_abnormal_lab_worsen_by_baseline]{s_count_abnormal_lab_worsen_by_baseline()}} to process input data. } \keyword{internal} diff --git a/man/analyze_colvars_functions.Rd b/man/analyze_colvars_functions.Rd index a81fd648ea..3af0847f43 100644 --- a/man/analyze_colvars_functions.Rd +++ b/man/analyze_colvars_functions.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/analyze_colvars_functions.R \name{analyze_colvars_functions} \alias{analyze_colvars_functions} -\title{Analyze functions on columns} +\title{Analyze functions in columns} \description{ These functions are wrappers of \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}} which apply corresponding \code{tern} statistics functions to add an analysis to a given table layout. In particular, these functions diff --git a/man/analyze_functions.Rd b/man/analyze_functions.Rd index f8f7c471a9..1037b3eae2 100644 --- a/man/analyze_functions.Rd +++ b/man/analyze_functions.Rd @@ -8,6 +8,7 @@ These functions are wrappers of \code{\link[rtables:analyze]{rtables::analyze()} to add an analysis to a given table layout: \itemize{ \item \code{\link[=analyze_num_patients]{analyze_num_patients()}} +\item \code{\link[=analyze_vars]{analyze_vars()}} \item \code{\link[=compare_vars]{compare_vars()}} \item \code{\link[=count_abnormal]{count_abnormal()}} \item \code{\link[=count_abnormal_by_baseline]{count_abnormal_by_baseline()}} @@ -34,7 +35,6 @@ variables that are split into different columns. In comparison, \link{analyze_co leverage \code{analyze_colvars} to have the context split in rows and the analysis methods in columns. \item \code{\link[=summarize_change]{summarize_change()}} -\item \code{\link[=analyze_vars]{analyze_vars()}} \item \code{\link[=surv_time]{surv_time()}} \item \code{\link[=surv_timepoint]{surv_timepoint()}} \item \code{\link[=test_proportion_diff]{test_proportion_diff()}} @@ -42,7 +42,7 @@ methods in columns. } \seealso{ \itemize{ -\item \link{summarize_functions} for functions which are wrappers for \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. \item \link{analyze_colvars_functions} for functions that are wrappers for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. +\item \link{summarize_functions} for functions which are wrappers for \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. } } diff --git a/man/analyze_variables.Rd b/man/analyze_variables.Rd index b665269800..1c7056ed49 100644 --- a/man/analyze_variables.Rd +++ b/man/analyze_variables.Rd @@ -234,11 +234,11 @@ denominator is zero. Note that \code{NA}s in \code{x} are never counted or leadi \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -The analyze function \code{\link[=analyze_vars]{analyze_vars()}} generates a summary of one or more variables, using the S3 generic function -\code{\link[=s_summary]{s_summary()}} to calculate a list of summary statistics. A list of all available statistics for numeric -variables can be viewed by running \code{get_stats("analyze_vars_numeric")} and for non-numeric variables by running -\code{get_stats("analyze_vars_counts")}. Use the \code{.stats} parameter to specify the statistics to include in your output -summary table. +The analyze function \code{\link[=analyze_vars]{analyze_vars()}} creates a layout element to summarize one or more variables, using the S3 +generic function \code{\link[=s_summary]{s_summary()}} to calculate a list of summary statistics. A list of all available statistics for +numeric variables can be viewed by running \code{get_stats("analyze_vars_numeric")} and for non-numeric variables by +running \code{get_stats("analyze_vars_counts")}. Use the \code{.stats} parameter to specify the statistics to include in your +output summary table. } \details{ \strong{Automatic digit formatting:} The number of digits to display can be automatically determined from the analyzed diff --git a/man/analyze_vars_in_cols.Rd b/man/analyze_vars_in_cols.Rd index 954b70bc38..0754596dbe 100644 --- a/man/analyze_vars_in_cols.Rd +++ b/man/analyze_vars_in_cols.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/analyze_vars_in_cols.R \name{analyze_vars_in_cols} \alias{analyze_vars_in_cols} -\title{Summarize numeric variables in columns} +\title{Analyze numeric variables in columns} \usage{ analyze_vars_in_cols( lyt, @@ -85,21 +85,21 @@ in columns, and add it to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -Layout-creating function which can be used for creating column-wise summary tables. -This function sets the analysis methods as column labels and is a wrapper for -\code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. It was designed principally for PK tables. +The layout-creating function \code{\link[=analyze_vars_in_cols]{analyze_vars_in_cols()}} creates a layout element to generate a column-wise +analysis table. + +This function sets the analysis methods as column labels and is a wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. +It was designed principally for PK tables. } \note{ -This is an experimental implementation of \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}} and -\code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}} that may be subjected to changes as \code{rtables} extends its -support to more complex analysis pipelines on the column space. For the same reasons, -we encourage to read the examples carefully and file issues for cases that differ from -them. - -Here \code{labelstr} behaves differently than usual. If it is not defined (default as \code{NULL}), -row labels are assigned automatically to the split values in case of \code{rtables::analyze_colvars} -(\code{do_summarize_row_groups = FALSE}, the default), and to the group label for -\code{do_summarize_row_groups = TRUE}. +\itemize{ +\item This is an experimental implementation of \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}} and \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}} +that may be subjected to changes as \code{rtables} extends its support to more complex analysis pipelines in the +column space. We encourage users to read the examples carefully and file issues for different use cases. +\item In this function, \code{labelstr} behaves atypically. If \code{labelstr = NULL} (the default), row labels are assigned +automatically as the split values if \code{do_summarize_row_groups = FALSE} (the default), and as the group label +if \code{do_summarize_row_groups = TRUE}. +} } \examples{ library(dplyr) diff --git a/man/compare_variables.Rd b/man/compare_variables.Rd index 18403de801..7fc9cce246 100644 --- a/man/compare_variables.Rd +++ b/man/compare_variables.Rd @@ -71,9 +71,9 @@ times, to avoid warnings from \code{rtables}.} \item{section_div}{(\code{string})\cr string which should be repeated as a section divider after each group defined by this split instruction, or \code{NA_character_} (the default) for no section divider.} -\item{.stats}{(\code{character})\cr statistics to select for the table. Run \code{get_stats("analyze_vars_numeric")} to see -statistics available for numeric variables, and \code{get_stats("analyze_vars_counts")} for statistics available -for non-numeric variables.} +\item{.stats}{(\code{character})\cr statistics to select for the table. Run +\code{get_stats("analyze_vars_numeric", add_pval = TRUE)} to see statistics available for numeric variables, and +\code{get_stats("analyze_vars_counts", add_pval = TRUE)} for statistics available for non-numeric variables.} \item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics. See Details in \code{analyze_vars} for more information on the \code{"auto"} setting.} @@ -113,7 +113,16 @@ the statistics from \code{s_compare()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Comparison with a reference group for different \code{x} objects. +The analyze function \code{\link[=compare_vars]{compare_vars()}} creates a layout element to summarize and compare one or more variables, using +the S3 generic function \code{\link[=s_summary]{s_summary()}} to calculate a list of summary statistics. A list of all available statistics +for numeric variables can be viewed by running \code{get_stats("analyze_vars_numeric", add_pval = TRUE)} and for +non-numeric variables by running \code{get_stats("analyze_vars_counts", add_pval = TRUE)}. Use the \code{.stats} parameter to +specify the statistics to include in your output summary table. + +Prior to using this function in your table layout you must use \code{\link[rtables:split_cols_by]{rtables::split_cols_by()}} to create a column +split on the variable to be used in comparisons, and specify a reference group via the \code{ref_group} parameter. +Comparisons can be performed for each group (column) against the specified reference group by including the p-value +statistic. } \section{Functions}{ \itemize{ diff --git a/man/count_cumulative.Rd b/man/count_cumulative.Rd index d19d8b2e4f..9df33c91f2 100644 --- a/man/count_cumulative.Rd +++ b/man/count_cumulative.Rd @@ -4,7 +4,7 @@ \alias{count_cumulative} \alias{s_count_cumulative} \alias{a_count_cumulative} -\title{Cumulative counts with thresholds} +\title{Cumulative counts of numeric variable by thresholds} \usage{ count_cumulative( lyt, @@ -104,8 +104,14 @@ component, each component containing a vector for the count and fraction. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Summarize cumulative counts of a \code{numeric} vector that is less than, less or equal to, -greater than, or greater or equal to user-specific thresholds. +The analyze function \code{\link[=count_cumulative]{count_cumulative()}} creates a layout element to calculate cumulative counts of values in a +numeric variable that are less than, less or equal to, greater than, or greater or equal to user-specified +threshold values. + +This function analyzes numeric variable \code{vars} against the threshold values supplied to the \code{thresholds} +argument as a numeric vector. Whether counts should include the threshold values, and whether to count +values lower or higher than the threshold values can be set via the \code{include_eq} and \code{lower_tail} +parameters, respectively. } \section{Functions}{ \itemize{ diff --git a/man/count_missed_doses.Rd b/man/count_missed_doses.Rd index d3847b94d6..1af24614a6 100644 --- a/man/count_missed_doses.Rd +++ b/man/count_missed_doses.Rd @@ -5,7 +5,7 @@ \alias{s_count_nonmissing} \alias{s_count_missed_doses} \alias{a_count_missed_doses} -\title{Count missed doses} +\title{Count number of patients with missed doses by thresholds} \usage{ count_missed_doses( lyt, @@ -89,8 +89,12 @@ the statistics from \code{s_count_missed_doses()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -These are specific functions to count patients with missed doses. The difference to \code{\link[=count_cumulative]{count_cumulative()}} is -mainly the special labels. +The analyze function creates a layout element to calculate cumulative counts of patients with number of missed +doses at least equal to user-specified threshold values. + +This function analyzes numeric variable \code{vars}, a variable with numbers of missed doses, +against the threshold values supplied to the \code{thresholds} argument as a numeric vector. This function +assumes that every row of the given data frame corresponds to a unique patient. } \section{Functions}{ \itemize{ @@ -125,6 +129,10 @@ basic_table() \%>\% } \seealso{ -Relevant description function \code{\link[=d_count_missed_doses]{d_count_missed_doses()}}. +\itemize{ +\item Relevant description function \code{\link[=d_count_missed_doses]{d_count_missed_doses()}} which generates labels for \code{\link[=count_missed_doses]{count_missed_doses()}}. +\item Similar analyze function \code{\link[=count_cumulative]{count_cumulative()}} which more generally counts cumulative values and has more +options for threshold handling, but uses different labels. +} } \keyword{internal} diff --git a/man/count_occurrences.Rd b/man/count_occurrences.Rd index b6466a405c..60d8037613 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -5,7 +5,7 @@ \alias{summarize_occurrences} \alias{s_count_occurrences} \alias{a_count_occurrences} -\title{Occurrence counts} +\title{Count occurrences} \usage{ count_occurrences( lyt, @@ -154,10 +154,17 @@ containing the statistics from \code{s_count_occurrences()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Functions for analyzing frequencies and fractions of occurrences for patients with occurrence -data. Primary analysis variables are the dictionary terms. All occurrences are counted for total -counts. Multiple occurrences within patient at the lowest term level displayed in the table are -counted only once. +The analyze function \code{\link[=count_occurrences]{count_occurrences()}} creates a layout element to calculate occurrence counts for patients. + +This function analyzes the variable(s) supplied to \code{vars} and returns a table of occurrence counts for +each unique value (or level) of the variable(s). This variable (or variables) must be +non-numeric. The \code{id} variable is used to indicate unique subject identifiers (defaults to \code{USUBJID}). + +If there are multiple occurrences of the same value recorded for a patient, the value is only counted once. + +The summarize function \code{\link[=summarize_occurrences]{summarize_occurrences()}} performs the same function as \code{\link[=count_occurrences]{count_occurrences()}} except it +creates content rows, not data rows, to summarize the current table row/column context and operates on the level of +the latest row split or the root of the table if no row splits have occurred. } \section{Functions}{ \itemize{ diff --git a/man/count_occurrences_by_grade.Rd b/man/count_occurrences_by_grade.Rd index 6db00d4b31..a3946ad05a 100644 --- a/man/count_occurrences_by_grade.Rd +++ b/man/count_occurrences_by_grade.Rd @@ -5,7 +5,7 @@ \alias{summarize_occurrences_by_grade} \alias{s_count_occurrences_by_grade} \alias{a_count_occurrences_by_grade} -\title{Occurrence counts by grade} +\title{Count occurrences by grade} \usage{ count_occurrences_by_grade( lyt, @@ -146,9 +146,19 @@ grade level grouping. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Functions for analyzing frequencies and fractions of occurrences by grade for patients -with occurrence data. Multiple occurrences within one individual are counted once at the -greatest intensity/highest grade level. +The analyze function \code{\link[=count_occurrences_by_grade]{count_occurrences_by_grade()}} creates a layout element to calculate occurrence counts by grade. + +This function analyzes primary analysis variable \code{var} which indicates toxicity grades. The \code{id} variable +is used to indicate unique subject identifiers (defaults to \code{USUBJID}). The user can also supply a list of +custom groups of grades to analyze via the \code{grade_groups} parameter. The \code{remove_single} argument will +remove single grades from the analysis so that \emph{only} grade groups are analyzed. + +If there are multiple grades recorded for one patient only the highest grade level is counted. + +The summarize function \code{\link[=summarize_occurrences_by_grade]{summarize_occurrences_by_grade()}} performs the same function as +\code{\link[=count_occurrences_by_grade]{count_occurrences_by_grade()}} except it creates content rows, not data rows, to summarize the current table +row/column context and operates on the level of the latest row split or the root of the table if no row splits have +occurred. } \section{Functions}{ \itemize{ diff --git a/man/count_patients_events_in_cols.Rd b/man/count_patients_events_in_cols.Rd index 8dace3d843..48879b8b25 100644 --- a/man/count_patients_events_in_cols.Rd +++ b/man/count_patients_events_in_cols.Rd @@ -4,7 +4,7 @@ \alias{count_patients_events_in_cols} \alias{summarize_patients_events_in_cols} \alias{s_count_patients_and_multiple_events} -\title{Count patients and events in columns} +\title{Count patient events in columns} \usage{ summarize_patients_events_in_cols( lyt, @@ -82,8 +82,14 @@ i.e. events, fulfilling the filter condition. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Counting the number of unique patients and the total number of all and specific events -when a column table layout is required. +The summarize function \code{\link[=summarize_patients_events_in_cols]{summarize_patients_events_in_cols()}} creates a layout element to summarize patient +event counts in columns. + +This function analyzes the elements (events) supplied via the \code{filters_list} parameter and returns a row +with counts of number of patients for each event as well as the total numbers of patients and events. +The \code{id} variable is used to indicate unique subject identifiers (defaults to \code{USUBJID}). + +If there are multiple occurrences of the same event recorded for a patient, the event is only counted once. } \section{Functions}{ \itemize{ diff --git a/man/count_patients_with_event.Rd b/man/count_patients_with_event.Rd index 86d33ae76e..206b0783f4 100644 --- a/man/count_patients_with_event.Rd +++ b/man/count_patients_with_event.Rd @@ -111,7 +111,14 @@ the statistics from \code{s_count_patients_with_event()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -The primary analysis variable \code{.var} denotes the unique patient identifier. +The analyze function \code{\link[=count_patients_with_event]{count_patients_with_event()}} creates a layout element to calculate patient counts for a +user-specified set of events. + +This function analyzes primary analysis variable \code{vars} which indicates unique subject identifiers. Events +are defined by the user as a named vector via the \code{filters} argument, where each name corresponds to a +variable and each value is the value(s) that that variable takes for the event. + +If there are multiple records with the same event recorded for a patient, only one occurrence is counted. } \section{Functions}{ \itemize{ diff --git a/man/count_patients_with_flags.Rd b/man/count_patients_with_flags.Rd index 553afc2adb..f435aaa7ee 100644 --- a/man/count_patients_with_flags.Rd +++ b/man/count_patients_with_flags.Rd @@ -118,7 +118,14 @@ flag as a list of statistics \code{n}, \code{count}, \code{count_fraction}, and \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -The primary analysis variable \code{.var} denotes the unique patient identifier. +The analyze function \code{\link[=count_patients_with_flags]{count_patients_with_flags()}} creates a layout element to calculate counts of patients for +which user-specified flags are present. + +This function analyzes primary analysis variable \code{var} which indicates unique subject identifiers. Flags +variables to analyze are specified by the user via the \code{flag_variables} argument, and must either take value +\code{TRUE} (flag present) or \code{FALSE} (flag absent) for each record. + +If there are multiple records with the same flag present for a patient, only one occurrence is counted. } \section{Functions}{ \itemize{ diff --git a/man/count_values_funs.Rd b/man/count_values.Rd similarity index 92% rename from man/count_values_funs.Rd rename to man/count_values.Rd index 4dc9f8479c..9965125593 100644 --- a/man/count_values_funs.Rd +++ b/man/count_values.Rd @@ -1,162 +1,166 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/count_values.R -\name{count_values_funs} -\alias{count_values_funs} -\alias{count_values} -\alias{s_count_values} -\alias{s_count_values.character} -\alias{s_count_values.factor} -\alias{s_count_values.logical} -\alias{a_count_values} -\title{Count specific values} -\usage{ -count_values( - lyt, - vars, - values, - na_str = default_na_str(), - nested = TRUE, - ..., - table_names = vars, - .stats = "count_fraction", - .formats = NULL, - .labels = c(count_fraction = paste(values, collapse = ", ")), - .indent_mods = NULL -) - -s_count_values( - x, - values, - na.rm = TRUE, - .N_col, - .N_row, - denom = c("n", "N_row", "N_col") -) - -\method{s_count_values}{character}(x, values = "Y", na.rm = TRUE, ...) - -\method{s_count_values}{factor}(x, values = "Y", ...) - -\method{s_count_values}{logical}(x, values = TRUE, ...) - -a_count_values( - x, - values, - na.rm = TRUE, - .N_col, - .N_row, - denom = c("n", "N_row", "N_col") -) -} -\arguments{ -\item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} - -\item{vars}{(\code{character})\cr variable names for the primary analysis variable to be iterated over.} - -\item{values}{(\code{character})\cr specific values that should be counted.} - -\item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} - -\item{nested}{(\code{flag})\cr whether this layout instruction should be applied within the existing layout structure _if -possible (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split. -underneath analyses, which is not allowed.} - -\item{...}{additional arguments for the lower level functions.} - -\item{table_names}{(\code{character})\cr this can be customized in the case that the same \code{vars} are analyzed multiple -times, to avoid warnings from \code{rtables}.} - -\item{.stats}{(\code{character})\cr statistics to select for the table. Run \code{get_stats("count_values")} -to see available statistics for this function.} - -\item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics. See Details in \code{analyze_vars} for more -information on the \code{"auto"} setting.} - -\item{.labels}{(named \code{character})\cr labels for the statistics (without indent).} - -\item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels. Defaults to 0, which corresponds to the -unmodified default behavior. Can be negative.} - -\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} - -\item{na.rm}{(\code{flag})\cr whether \code{NA} values should be removed from \code{x} prior to analysis.} - -\item{.N_col}{(\code{integer(1)})\cr column-wise N (column count) for the full column being analyzed that is typically -passed by \code{rtables}.} - -\item{.N_row}{(\code{integer(1)})\cr row-wise N (row group count) for the group of observations being analyzed -(i.e. with no column-based subsetting) that is typically passed by \code{rtables}.} - -\item{denom}{(\code{string})\cr choice of denominator for proportion. Options are: -\itemize{ -\item \code{n}: number of values in this row and column intersection. -\item \code{N_row}: total number of values in this row across columns. -\item \code{N_col}: total number of values in this column across rows. -}} -} -\value{ -\itemize{ -\item \code{count_values()} returns a layout object suitable for passing to further layouting functions, -or to \code{\link[rtables:build_table]{rtables::build_table()}}. Adding this function to an \code{rtable} layout will add formatted rows containing -the statistics from \code{s_count_values()} to the table layout. -} - -\itemize{ -\item \code{s_count_values()} returns output of \code{\link[=s_summary]{s_summary()}} for specified values of a non-numeric variable. -} - -\itemize{ -\item \code{a_count_values()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. -} -} -\description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} - -We can count the occurrence of specific values in a variable of interest. -} -\section{Functions}{ -\itemize{ -\item \code{count_values()}: Layout-creating function which can take statistics function arguments -and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. - -\item \code{s_count_values()}: S3 generic function to count values. - -\item \code{s_count_values(character)}: Method for \code{character} class. - -\item \code{s_count_values(factor)}: Method for \code{factor} class. This makes an automatic -conversion to \code{character} and then forwards to the method for characters. - -\item \code{s_count_values(logical)}: Method for \code{logical} class. - -\item \code{a_count_values()}: Formatted analysis function which is used as \code{afun} -in \code{count_values()}. - -}} -\note{ -\itemize{ -\item For \code{factor} variables, \code{s_count_values} checks whether \code{values} are all included in the levels of \code{x} -and fails otherwise. -\item For \code{count_values()}, variable labels are shown when there is more than one element in \code{vars}, -otherwise they are hidden. -} -} -\examples{ -# `count_values` -basic_table() \%>\% - count_values("Species", values = "setosa") \%>\% - build_table(iris) - -# `s_count_values.character` -s_count_values(x = c("a", "b", "a"), values = "a") -s_count_values(x = c("a", "b", "a", NA, NA), values = "b", na.rm = FALSE) - -# `s_count_values.factor` -s_count_values(x = factor(c("a", "b", "a")), values = "a") - -# `s_count_values.logical` -s_count_values(x = c(TRUE, FALSE, TRUE)) - -# `a_count_values` -a_count_values(x = factor(c("a", "b", "a")), values = "a", .N_col = 10, .N_row = 10) - -} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/count_values.R +\name{count_values} +\alias{count_values} +\alias{s_count_values} +\alias{s_count_values.character} +\alias{s_count_values.factor} +\alias{s_count_values.logical} +\alias{a_count_values} +\title{Count specific values} +\usage{ +count_values( + lyt, + vars, + values, + na_str = default_na_str(), + nested = TRUE, + ..., + table_names = vars, + .stats = "count_fraction", + .formats = NULL, + .labels = c(count_fraction = paste(values, collapse = ", ")), + .indent_mods = NULL +) + +s_count_values( + x, + values, + na.rm = TRUE, + .N_col, + .N_row, + denom = c("n", "N_row", "N_col") +) + +\method{s_count_values}{character}(x, values = "Y", na.rm = TRUE, ...) + +\method{s_count_values}{factor}(x, values = "Y", ...) + +\method{s_count_values}{logical}(x, values = TRUE, ...) + +a_count_values( + x, + values, + na.rm = TRUE, + .N_col, + .N_row, + denom = c("n", "N_row", "N_col") +) +} +\arguments{ +\item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} + +\item{vars}{(\code{character})\cr variable names for the primary analysis variable to be iterated over.} + +\item{values}{(\code{character})\cr specific values that should be counted.} + +\item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} + +\item{nested}{(\code{flag})\cr whether this layout instruction should be applied within the existing layout structure _if +possible (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split. +underneath analyses, which is not allowed.} + +\item{...}{additional arguments for the lower level functions.} + +\item{table_names}{(\code{character})\cr this can be customized in the case that the same \code{vars} are analyzed multiple +times, to avoid warnings from \code{rtables}.} + +\item{.stats}{(\code{character})\cr statistics to select for the table. Run \code{get_stats("count_values")} +to see available statistics for this function.} + +\item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics. See Details in \code{analyze_vars} for more +information on the \code{"auto"} setting.} + +\item{.labels}{(named \code{character})\cr labels for the statistics (without indent).} + +\item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels. Defaults to 0, which corresponds to the +unmodified default behavior. Can be negative.} + +\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} + +\item{na.rm}{(\code{flag})\cr whether \code{NA} values should be removed from \code{x} prior to analysis.} + +\item{.N_col}{(\code{integer(1)})\cr column-wise N (column count) for the full column being analyzed that is typically +passed by \code{rtables}.} + +\item{.N_row}{(\code{integer(1)})\cr row-wise N (row group count) for the group of observations being analyzed +(i.e. with no column-based subsetting) that is typically passed by \code{rtables}.} + +\item{denom}{(\code{string})\cr choice of denominator for proportion. Options are: +\itemize{ +\item \code{n}: number of values in this row and column intersection. +\item \code{N_row}: total number of values in this row across columns. +\item \code{N_col}: total number of values in this column across rows. +}} +} +\value{ +\itemize{ +\item \code{count_values()} returns a layout object suitable for passing to further layouting functions, +or to \code{\link[rtables:build_table]{rtables::build_table()}}. Adding this function to an \code{rtable} layout will add formatted rows containing +the statistics from \code{s_count_values()} to the table layout. +} + +\itemize{ +\item \code{s_count_values()} returns output of \code{\link[=s_summary]{s_summary()}} for specified values of a non-numeric variable. +} + +\itemize{ +\item \code{a_count_values()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +The analyze function \code{\link[=count_values]{count_values()}} creates a layout element to calculate counts of specific values within a +variable of interest. + +This function analyzes one or more variables of interest supplied as a vector to \code{vars}. Values to +count for variable(s) in \code{vars} can be given as a vector via the \code{values} argument. One row of +counts will be generated for each variable. +} +\section{Functions}{ +\itemize{ +\item \code{count_values()}: Layout-creating function which can take statistics function arguments +and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. + +\item \code{s_count_values()}: S3 generic function to count values. + +\item \code{s_count_values(character)}: Method for \code{character} class. + +\item \code{s_count_values(factor)}: Method for \code{factor} class. This makes an automatic +conversion to \code{character} and then forwards to the method for characters. + +\item \code{s_count_values(logical)}: Method for \code{logical} class. + +\item \code{a_count_values()}: Formatted analysis function which is used as \code{afun} +in \code{count_values()}. + +}} +\note{ +\itemize{ +\item For \code{factor} variables, \code{s_count_values} checks whether \code{values} are all included in the levels of \code{x} +and fails otherwise. +\item For \code{count_values()}, variable labels are shown when there is more than one element in \code{vars}, +otherwise they are hidden. +} +} +\examples{ +# `count_values` +basic_table() \%>\% + count_values("Species", values = "setosa") \%>\% + build_table(iris) + +# `s_count_values.character` +s_count_values(x = c("a", "b", "a"), values = "a") +s_count_values(x = c("a", "b", "a", NA, NA), values = "b", na.rm = FALSE) + +# `s_count_values.factor` +s_count_values(x = factor(c("a", "b", "a")), values = "a") + +# `s_count_values.logical` +s_count_values(x = c(TRUE, FALSE, TRUE)) + +# `a_count_values` +a_count_values(x = factor(c("a", "b", "a")), values = "a", .N_col = 10, .N_row = 10) + +} diff --git a/man/estimate_multinomial_rsp.Rd b/man/estimate_multinomial_rsp.Rd index 50b6ab1439..6b687737cb 100644 --- a/man/estimate_multinomial_rsp.Rd +++ b/man/estimate_multinomial_rsp.Rd @@ -1,129 +1,130 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/estimate_multinomial_rsp.R -\name{estimate_multinomial_rsp} -\alias{estimate_multinomial_rsp} -\alias{estimate_multinomial_response} -\alias{s_length_proportion} -\alias{a_length_proportion} -\title{Estimation of proportions per level of factor} -\usage{ -estimate_multinomial_response( - lyt, - var, - na_str = default_na_str(), - nested = TRUE, - ..., - show_labels = "hidden", - table_names = var, - .stats = "prop_ci", - .formats = NULL, - .labels = NULL, - .indent_mods = NULL -) - -s_length_proportion(x, .N_col, ...) - -a_length_proportion(x, .N_col, ...) -} -\arguments{ -\item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} - -\item{var}{(\code{string})\cr single variable name that is passed by \code{rtables} when requested -by a statistics function.} - -\item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} - -\item{nested}{(\code{flag})\cr whether this layout instruction should be applied within the existing layout structure _if -possible (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split. -underneath analyses, which is not allowed.} - -\item{...}{additional arguments for the lower level functions.} - -\item{show_labels}{(\code{string})\cr label visibility: one of "default", "visible" and "hidden".} - -\item{table_names}{(\code{character})\cr this can be customized in the case that the same \code{vars} are analyzed multiple -times, to avoid warnings from \code{rtables}.} - -\item{.stats}{(\code{character})\cr statistics to select for the table. Run \code{get_stats("estimate_multinomial_response")} -to see available statistics for this function.} - -\item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics. See Details in \code{analyze_vars} for more -information on the \code{"auto"} setting.} - -\item{.labels}{(named \code{character})\cr labels for the statistics (without indent).} - -\item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels. Defaults to 0, which corresponds to the -unmodified default behavior. Can be negative.} - -\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} - -\item{.N_col}{(\code{integer(1)})\cr column-wise N (column count) for the full column being analyzed that is typically -passed by \code{rtables}.} -} -\value{ -\itemize{ -\item \code{estimate_multinomial_response()} returns a layout object suitable for passing to further layouting functions, -or to \code{\link[rtables:build_table]{rtables::build_table()}}. Adding this function to an \code{rtable} layout will add formatted rows containing -the statistics from \code{s_length_proportion()} to the table layout. -} - -\itemize{ -\item \code{s_length_proportion()} returns statistics from \code{\link[=s_proportion]{s_proportion()}}. -} - -\itemize{ -\item \code{a_length_proportion()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. -} -} -\description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} - -Estimate the proportion along with confidence interval of a proportion -regarding the level of a factor. -} -\section{Functions}{ -\itemize{ -\item \code{estimate_multinomial_response()}: Layout-creating function which can take statistics function arguments -and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}} and -\code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. - -\item \code{s_length_proportion()}: Statistics function which feeds the length of \code{x} as number -of successes, and \code{.N_col} as total number of successes and failures into \code{\link[=s_proportion]{s_proportion()}}. - -\item \code{a_length_proportion()}: Formatted analysis function which is used as \code{afun} -in \code{estimate_multinomial_response()}. - -}} -\examples{ -library(dplyr) - -# Use of the layout creating function. -dta_test <- data.frame( - USUBJID = paste0("S", 1:12), - ARM = factor(rep(LETTERS[1:3], each = 4)), - AVAL = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0)) -) \%>\% mutate( - AVALC = factor(AVAL, - levels = c(0, 1), - labels = c("Complete Response (CR)", "Partial Response (PR)") - ) -) - -lyt <- basic_table() \%>\% - split_cols_by("ARM") \%>\% - estimate_multinomial_response(var = "AVALC") - -tbl <- build_table(lyt, dta_test) - -tbl - -s_length_proportion(rep("CR", 10), .N_col = 100) -s_length_proportion(factor(character(0)), .N_col = 100) - -a_length_proportion(rep("CR", 10), .N_col = 100) -a_length_proportion(factor(character(0)), .N_col = 100) - -} -\seealso{ -Relevant description function \code{\link[=d_onco_rsp_label]{d_onco_rsp_label()}}. -} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/estimate_multinomial_rsp.R +\name{estimate_multinomial_rsp} +\alias{estimate_multinomial_rsp} +\alias{estimate_multinomial_response} +\alias{s_length_proportion} +\alias{a_length_proportion} +\title{Estimate proportions of each level of a variable} +\usage{ +estimate_multinomial_response( + lyt, + var, + na_str = default_na_str(), + nested = TRUE, + ..., + show_labels = "hidden", + table_names = var, + .stats = "prop_ci", + .formats = NULL, + .labels = NULL, + .indent_mods = NULL +) + +s_length_proportion(x, .N_col, ...) + +a_length_proportion(x, .N_col, ...) +} +\arguments{ +\item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} + +\item{var}{(\code{string})\cr single variable name that is passed by \code{rtables} when requested +by a statistics function.} + +\item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} + +\item{nested}{(\code{flag})\cr whether this layout instruction should be applied within the existing layout structure _if +possible (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split. +underneath analyses, which is not allowed.} + +\item{...}{additional arguments for the lower level functions.} + +\item{show_labels}{(\code{string})\cr label visibility: one of "default", "visible" and "hidden".} + +\item{table_names}{(\code{character})\cr this can be customized in the case that the same \code{vars} are analyzed multiple +times, to avoid warnings from \code{rtables}.} + +\item{.stats}{(\code{character})\cr statistics to select for the table. Run \code{get_stats("estimate_multinomial_response")} +to see available statistics for this function.} + +\item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics. See Details in \code{analyze_vars} for more +information on the \code{"auto"} setting.} + +\item{.labels}{(named \code{character})\cr labels for the statistics (without indent).} + +\item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels. Defaults to 0, which corresponds to the +unmodified default behavior. Can be negative.} + +\item{x}{(\code{numeric})\cr vector of numbers we want to analyze.} + +\item{.N_col}{(\code{integer(1)})\cr column-wise N (column count) for the full column being analyzed that is typically +passed by \code{rtables}.} +} +\value{ +\itemize{ +\item \code{estimate_multinomial_response()} returns a layout object suitable for passing to further layouting functions, +or to \code{\link[rtables:build_table]{rtables::build_table()}}. Adding this function to an \code{rtable} layout will add formatted rows containing +the statistics from \code{s_length_proportion()} to the table layout. +} + +\itemize{ +\item \code{s_length_proportion()} returns statistics from \code{\link[=s_proportion]{s_proportion()}}. +} + +\itemize{ +\item \code{a_length_proportion()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +The analyze & summarize function \code{\link[=estimate_multinomial_response]{estimate_multinomial_response()}} creates a layout element to estimate the +proportion and proportion confidence interval for each level of a factor variable. The primary analysis variable, +\code{var}, should be a factor variable, the values of which will be used as labels within the output table. +} +\section{Functions}{ +\itemize{ +\item \code{estimate_multinomial_response()}: Layout-creating function which can take statistics function arguments +and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}} and +\code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. + +\item \code{s_length_proportion()}: Statistics function which feeds the length of \code{x} as number +of successes, and \code{.N_col} as total number of successes and failures into \code{\link[=s_proportion]{s_proportion()}}. + +\item \code{a_length_proportion()}: Formatted analysis function which is used as \code{afun} +in \code{estimate_multinomial_response()}. + +}} +\examples{ +library(dplyr) + +# Use of the layout creating function. +dta_test <- data.frame( + USUBJID = paste0("S", 1:12), + ARM = factor(rep(LETTERS[1:3], each = 4)), + AVAL = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0)) +) \%>\% mutate( + AVALC = factor(AVAL, + levels = c(0, 1), + labels = c("Complete Response (CR)", "Partial Response (PR)") + ) +) + +lyt <- basic_table() \%>\% + split_cols_by("ARM") \%>\% + estimate_multinomial_response(var = "AVALC") + +tbl <- build_table(lyt, dta_test) + +tbl + +s_length_proportion(rep("CR", 10), .N_col = 100) +s_length_proportion(factor(character(0)), .N_col = 100) + +a_length_proportion(rep("CR", 10), .N_col = 100) +a_length_proportion(factor(character(0)), .N_col = 100) + +} +\seealso{ +Relevant description function \code{\link[=d_onco_rsp_label]{d_onco_rsp_label()}}. +} diff --git a/man/estimate_proportions.Rd b/man/estimate_proportion.Rd similarity index 91% rename from man/estimate_proportions.Rd rename to man/estimate_proportion.Rd index 1131246692..7cc67cc094 100644 --- a/man/estimate_proportions.Rd +++ b/man/estimate_proportion.Rd @@ -1,11 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/estimate_proportion.R -\name{estimate_proportions} -\alias{estimate_proportions} +\name{estimate_proportion} \alias{estimate_proportion} \alias{s_proportion} \alias{a_proportion} -\title{Estimation of proportions} +\title{Proportion estimation} \usage{ estimate_proportion( lyt, @@ -127,7 +126,11 @@ given variable. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Estimate the proportion of responders within a studied population. +The analyze function \code{\link[=estimate_proportion]{estimate_proportion()}} creates a layout element to estimate the proportion of responders +within a studied population. The primary analysis variable, \code{vars}, indicates whether a response has occurred for +each record. See the \code{method} parameter for options of methods to use when constructing the confidence interval of +the proportion. Additionally, a stratification variable can be supplied via the \code{strata} element of the \code{variables} +argument. } \section{Functions}{ \itemize{ @@ -145,7 +148,7 @@ in \code{estimate_proportion()}. dta_test <- data.frame( USUBJID = paste0("S", 1:12), ARM = rep(LETTERS[1:3], each = 4), - AVAL = c(A = c(1, 1, 1, 1), B = c(0, 0, 1, 1), C = c(0, 0, 0, 0)) + AVAL = rep(LETTERS[1:3], each = 4) ) basic_table() \%>\% diff --git a/man/extract_survival_subgroups.Rd b/man/extract_survival_subgroups.Rd index af70127446..86f73e6d53 100644 --- a/man/extract_survival_subgroups.Rd +++ b/man/extract_survival_subgroups.Rd @@ -24,10 +24,11 @@ levels that belong to it in the character vectors that are elements of the list. \item{control}{(\code{list})\cr parameters for comparison details, specified by using the helper function \code{\link[=control_coxph]{control_coxph()}}. Some possible parameter options are: \itemize{ -\item \code{pval_method} (\code{string})\cr p-value method for testing hazard ratio = 1. Default method is \code{"log-rank"} which -comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} (from \code{\link[survival:coxph]{survival::coxph()}}). +\item \code{pval_method} (\code{string})\cr p-value method for testing the null hypothesis that hazard ratio = 1. Default +method is \code{"log-rank"} which comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} +(from \code{\link[survival:coxph]{survival::coxph()}}). \item \code{ties} (\code{string})\cr specifying the method for tie handling. Default is \code{"efron"}, -can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}} +can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}}. \item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. }} diff --git a/man/h_incidence_rate.Rd b/man/h_incidence_rate.Rd index 08d974419d..b1689f54c0 100644 --- a/man/h_incidence_rate.Rd +++ b/man/h_incidence_rate.Rd @@ -28,12 +28,12 @@ h_incidence_rate(person_years, n_events, control = control_incidence_rate()) \item{control}{(\code{list})\cr parameters for estimation details, specified by using the helper function \code{\link[=control_incidence_rate]{control_incidence_rate()}}. Possible parameter options are: \itemize{ -\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} +\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{input_time_unit}: (\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{num_pt_year}: (\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/h_proportions.Rd b/man/h_proportions.Rd index 5753aeed9e..d9859bd65a 100644 --- a/man/h_proportions.Rd +++ b/man/h_proportions.Rd @@ -119,6 +119,6 @@ prop_jeffreys(rsp, conf_level = 0.95) \insertRef{Yan2010-jt}{tern} } \seealso{ -\link{estimate_proportions}, descriptive function \code{\link[=d_proportion]{d_proportion()}}, +\link{estimate_proportion}, descriptive function \code{\link[=d_proportion]{d_proportion()}}, and helper functions \code{\link[=strata_normal_quantile]{strata_normal_quantile()}} and \code{\link[=update_weights_strat_wilson]{update_weights_strat_wilson()}}. } diff --git a/man/h_survival_duration_subgroups.Rd b/man/h_survival_duration_subgroups.Rd index 8e5a9dcca8..76d0a41ec7 100644 --- a/man/h_survival_duration_subgroups.Rd +++ b/man/h_survival_duration_subgroups.Rd @@ -49,10 +49,11 @@ levels that belong to it in the character vectors that are elements of the list. \item{control}{(\code{list})\cr parameters for comparison details, specified by using the helper function \code{\link[=control_coxph]{control_coxph()}}. Some possible parameter options are: \itemize{ -\item \code{pval_method} (\code{string})\cr p-value method for testing hazard ratio = 1. Default method is \code{"log-rank"} which -comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} (from \code{\link[survival:coxph]{survival::coxph()}}). +\item \code{pval_method} (\code{string})\cr p-value method for testing the null hypothesis that hazard ratio = 1. Default +method is \code{"log-rank"} which comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} +(from \code{\link[survival:coxph]{survival::coxph()}}). \item \code{ties} (\code{string})\cr specifying the method for tie handling. Default is \code{"efron"}, -can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}} +can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}}. \item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. }} } diff --git a/man/incidence_rate.Rd b/man/incidence_rate.Rd index 33f5f7e63e..721023a5f8 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -5,7 +5,7 @@ \alias{estimate_incidence_rate} \alias{s_incidence_rate} \alias{a_incidence_rate} -\title{Incidence rate} +\title{Incidence rate estimation} \usage{ estimate_incidence_rate( lyt, @@ -113,8 +113,10 @@ the statistics from \code{s_incidence_rate()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Estimate the event rate adjusted for person-years at risk, otherwise known -as incidence rate. Primary analysis variable is the person-years at risk. +The analyze function \code{\link[=estimate_incidence_rate]{estimate_incidence_rate()}} creates a layout element to estimate an event rate adjusted for +person-years at risk, otherwise known as incidence rate. The primary analysis variable specified via \code{vars} is +the person-years at risk. In addition to this variable, the \code{n_events} variable for number of events observed (where +a value of 1 means an event was observed and 0 means that no event was observed) must also be specified. } \section{Functions}{ \itemize{ diff --git a/man/odds_ratio.Rd b/man/odds_ratio.Rd index 688fe31d98..478a18c562 100644 --- a/man/odds_ratio.Rd +++ b/man/odds_ratio.Rd @@ -112,14 +112,12 @@ the statistics from \code{s_odds_ratio()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Compares bivariate responses between two groups in terms of odds ratios -along with a confidence interval. -} -\details{ -This function uses either logistic regression for unstratified -analyses, or conditional logistic regression for stratified analyses. -The Wald confidence interval with the specified confidence level is -calculated. +The analyze function \code{\link[=estimate_odds_ratio]{estimate_odds_ratio()}} creates a layout element to compare bivariate responses between +two groups by estimating an odds ratio and its confidence interval. + +The primary analysis variable specified by \code{vars} is the group variable. Additional variables can be included in the +analysis via the \code{variables} argument, which accepts \code{arm}, an arm variable, and \code{strata}, a stratification variable. +If more than two arm levels are present, they can be combined into two groups using the \code{groups_list} argument. } \section{Functions}{ \itemize{ @@ -134,10 +132,14 @@ variable names must be passed if a stratified analysis is required. }} \note{ -For stratified analyses, there is currently no implementation for conditional -likelihood confidence intervals, therefore the likelihood confidence interval is not -yet available as an option. Besides, when \code{rsp} contains only responders or non-responders, -then the result values will be \code{NA}, because no odds ratio estimation is possible. +\itemize{ +\item This function uses logistic regression for unstratified analyses, and conditional logistic regression for +stratified analyses. The Wald confidence interval is calculated with the specified confidence level. +\item For stratified analyses, there is currently no implementation for conditional likelihood confidence intervals, +therefore the likelihood confidence interval is not available as an option. +\item When \code{vars} contains only responders or non-responders no odds ratio estimation is possible so the returned +values will be \code{NA}. +} } \examples{ set.seed(12) diff --git a/man/prop_diff.Rd b/man/prop_diff.Rd index be9c54e630..70b1e14056 100644 --- a/man/prop_diff.Rd +++ b/man/prop_diff.Rd @@ -5,7 +5,7 @@ \alias{estimate_proportion_diff} \alias{s_proportion_diff} \alias{a_proportion_diff} -\title{Proportion difference} +\title{Proportion difference estimation} \usage{ estimate_proportion_diff( lyt, @@ -117,6 +117,12 @@ the statistics from \code{s_proportion_diff()} to the table layout. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +The analysis function \code{\link[=estimate_proportion_diff]{estimate_proportion_diff()}} creates a layout element to estimate the difference in proportion +of responders within a studied population. The primary analysis variable, \code{vars}, is a logical variable indicating +whether a response has occurred for each record. See the \code{method} parameter for options of methods to use when +constructing the confidence interval of the proportion difference. A stratification variable can be supplied via the +\code{strata} element of the \code{variables} argument. } \section{Functions}{ \itemize{ diff --git a/man/prop_diff_test.Rd b/man/prop_diff_test.Rd index 316afaf755..e5c9b1055b 100644 --- a/man/prop_diff_test.Rd +++ b/man/prop_diff_test.Rd @@ -106,7 +106,10 @@ describing the method used. The p-value tests the null hypothesis that proportio \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Various tests were implemented to test the difference between two proportions. +The analyze function \code{\link[=test_proportion_diff]{test_proportion_diff()}} creates a layout element to test the difference between two +proportions. The primary analysis variable, \code{vars}, indicates whether a response has occurred for each record. See +the \code{method} parameter for options of methods to use to calculate the p-value. Additionally, a stratification +variable can be supplied via the \code{strata} element of the \code{variables} argument. } \section{Functions}{ \itemize{ diff --git a/man/response_biomarkers_subgroups.Rd b/man/response_biomarkers_subgroups.Rd index bd04b62ce7..7797d88928 100644 --- a/man/response_biomarkers_subgroups.Rd +++ b/man/response_biomarkers_subgroups.Rd @@ -38,8 +38,12 @@ An \code{rtables} table summarizing biomarker effects on binary response by subg \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Tabulate the estimated effects of multiple continuous biomarker variables -on a binary response endpoint across population subgroups. +The \code{\link[=tabulate_rsp_biomarkers]{tabulate_rsp_biomarkers()}} function creates a layout element to tabulate the estimated biomarker effects on a +binary response endpoint across subgroups, returning statistics including response rate and odds ratio for each +population subgroup. The table is created from \code{df}, a list of data frames returned by \code{\link[=extract_rsp_biomarkers]{extract_rsp_biomarkers()}}, +with the statistics to include specified via the \code{vars} parameter. + +A forest plot can be created from the resulting table using the \code{\link[=g_forest]{g_forest()}} function. } \details{ These functions create a layout starting from a data frame which contains diff --git a/man/response_subgroups.Rd b/man/response_subgroups.Rd index 501178cb59..dc208e9491 100644 --- a/man/response_subgroups.Rd +++ b/man/response_subgroups.Rd @@ -29,7 +29,7 @@ a_response_subgroups( \arguments{ \item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} -\item{df}{(\code{list})\cr of data frames containing all analysis variables. List should be +\item{df}{(\code{list})\cr a list of data frames containing all analysis variables. List should be created using \code{\link[=extract_rsp_subgroups]{extract_rsp_subgroups()}}.} \item{vars}{(\code{character})\cr the names of statistics to be reported among: @@ -70,7 +70,12 @@ An \code{rtables} table summarizing binary response by subgroup. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Tabulate statistics such as response rate and odds ratio for population subgroups. +The \code{\link[=tabulate_rsp_subgroups]{tabulate_rsp_subgroups()}} function creates a layout element to tabulate binary response by subgroup, returning +statistics including response rate and odds ratio for each population subgroup. The table is created from \code{df}, a +list of data frames returned by \code{\link[=extract_rsp_subgroups]{extract_rsp_subgroups()}}, with the statistics to include specified via the \code{vars} +parameter. + +A forest plot can be created from the resulting table using the \code{\link[=g_forest]{g_forest()}} function. } \details{ These functions create a layout starting from a data frame which contains diff --git a/man/summarize_ancova.Rd b/man/summarize_ancova.Rd index 2beabf72a7..57d4998298 100644 --- a/man/summarize_ancova.Rd +++ b/man/summarize_ancova.Rd @@ -4,7 +4,7 @@ \alias{summarize_ancova} \alias{s_ancova} \alias{a_ancova} -\title{Summary for analysis of covariance (ANCOVA).} +\title{Summarize analysis of covariance (ANCOVA) results} \usage{ summarize_ancova( lyt, @@ -64,8 +64,8 @@ interaction terms indicated by \code{"X1 * X2"}. \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} -\item{interaction_y}{(\code{string} or \code{flag})\cr a selected item inside of the interaction_item column which will be used -to select the specific ANCOVA results. if the interaction is not needed, the default option is \code{FALSE}.} +\item{interaction_y}{(\code{string} or \code{flag})\cr a selected item inside of the \code{interaction_item} variable which will be +used to select the specific ANCOVA results. if the interaction is not needed, the default option is \code{FALSE}.} \item{interaction_item}{(\code{string} or \code{NULL})\cr name of the variable that should have interactions with arm. if the interaction is not needed, the default option is \code{NULL}.} @@ -134,8 +134,16 @@ to the reference group. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Summarize results of ANCOVA. This can be used to analyze multiple endpoints and/or -multiple timepoints within the same response variable \code{.var}. +The analyze function \code{\link[=summarize_ancova]{summarize_ancova()}} creates a layout element to summarize ANCOVA results. + +This function can be used to analyze multiple endpoints and/or multiple timepoints within the response variable(s) +specified as \code{vars}. + +Additional variables for the analysis, namely an arm (grouping) variable and covariate variables, can be defined +via the \code{variables} argument. See below for more details on how to specify \code{variables}. An interaction term can +be implemented in the model if needed. The interaction variable that should interact with the arm variable is +specified via the \code{interaction_term} parameter, and the specific value of \code{interaction_term} for which to extract +the ANCOVA results via the \code{interaction_y} parameter. } \section{Functions}{ \itemize{ diff --git a/man/summarize_change.Rd b/man/summarize_change.Rd index 8f7c5bb74b..50197c5bf9 100644 --- a/man/summarize_change.Rd +++ b/man/summarize_change.Rd @@ -4,7 +4,7 @@ \alias{summarize_change} \alias{s_change_from_baseline} \alias{a_change_from_baseline} -\title{Summarize the change from baseline or absolute baseline values} +\title{Summarize change from baseline values or absolute baseline values} \usage{ summarize_change( lyt, @@ -78,9 +78,13 @@ the statistics from \code{s_change_from_baseline()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -The primary analysis variable \code{.var} indicates the numerical change from baseline results, -and additional required secondary analysis variables are \code{value} and \code{baseline_flag}. -Depending on the baseline flag, either the absolute baseline values (at baseline) +The analyze function \code{\link[=summarize_change]{summarize_change()}} creates a layout element to summarize the change from baseline or absolute +baseline values. The primary analysis variable \code{vars} indicates the numerical change from baseline results. + +Required secondary analysis variables \code{value} and \code{baseline_flag} can be supplied to the function via +the \code{variables} argument. The \code{value} element should be the name of the analysis value variable, and the +\code{baseline_flag} element should be the name of the flag variable that indicates whether or not records contain +baseline values. Depending on the baseline flag given, either the absolute baseline values (at baseline) or the change from baseline values (post-baseline) are then summarized. } \section{Functions}{ diff --git a/man/summarize_colvars.Rd b/man/summarize_colvars.Rd index b174992d7a..600c46583c 100644 --- a/man/summarize_colvars.Rd +++ b/man/summarize_colvars.Rd @@ -17,7 +17,7 @@ summarize_colvars( \arguments{ \item{lyt}{(\code{PreDataTableLayouts})\cr layout that analyses will be added to.} -\item{...}{arguments passed to \code{s_summary()}.} +\item{...}{arguments passed to \code{\link[=s_summary]{s_summary()}}.} \item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} @@ -40,11 +40,13 @@ in columns, and add it to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -This analyze function uses the S3 generic function \code{\link[=s_summary]{s_summary()}} to summarize different variables -that are arranged in columns. Additional standard formatting arguments are available. It is a -minimal wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. The latter function is meant to add different -analysis methods for each column variables as different rows. To have the analysis methods as -column labels, please refer to \code{\link[=analyze_vars_in_cols]{analyze_vars_in_cols()}}. +The analyze function \code{\link[=summarize_colvars]{summarize_colvars()}} uses the statistics function \code{\link[=s_summary]{s_summary()}} to analyze variables that are +arranged in columns. The variables to analyze should be specified in the table layout via column splits (see +\code{\link[=split_cols_by]{split_cols_by()}} and \code{\link[=split_cols_by_multivar]{split_cols_by_multivar()}}) prior to using \code{\link[=summarize_colvars]{summarize_colvars()}}. + +The function is a minimal wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}, a function typically used to apply different +analysis methods in rows for each column variable. To use the analysis methods as column labels, please refer to +the \code{\link[=analyze_vars_in_cols]{analyze_vars_in_cols()}} function. } \examples{ dta_test <- data.frame( diff --git a/man/summarize_functions.Rd b/man/summarize_functions.Rd index 22f5d9108b..580f8179ec 100644 --- a/man/summarize_functions.Rd +++ b/man/summarize_functions.Rd @@ -18,7 +18,6 @@ to add summary rows to a given table layout: \item \code{\link[=summarize_occurrences_by_grade]{summarize_occurrences_by_grade()}} \item \code{\link[=summarize_patients_events_in_cols]{summarize_patients_events_in_cols()}} \item \code{\link[=summarize_patients_exposure_in_cols]{summarize_patients_exposure_in_cols()}} -\item \code{\link[=tabulate_rsp_subgroups]{tabulate_rsp_subgroups()}} } Additionally, the \code{\link[=summarize_coxreg]{summarize_coxreg()}} function utilizes \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}} diff --git a/man/summarize_num_patients.Rd b/man/summarize_num_patients.Rd index 6b2f6dc51d..abf297d266 100644 --- a/man/summarize_num_patients.Rd +++ b/man/summarize_num_patients.Rd @@ -5,7 +5,7 @@ \alias{analyze_num_patients} \alias{s_num_patients} \alias{s_num_patients_content} -\title{Number of patients} +\title{Count number of patients} \usage{ analyze_num_patients( lyt, @@ -64,10 +64,10 @@ s_num_patients_content( \item{vars}{(\code{character})\cr variable names for the primary analysis variable to be iterated over.} -\item{required}{(\code{character} or \code{NULL})\cr optional, name of a variable that is required to be non-missing.} +\item{required}{(\code{character} or \code{NULL})\cr name of a variable that is required to be non-missing.} -\item{count_by}{(\code{vector})\cr optional vector of any type to be combined with \code{x} when counting \code{nonunique} -records.} +\item{count_by}{(\code{character} or \code{NULL})\cr name of a variable to be combined with \code{vars} when counting +\code{nonunique} records.} \item{unique_count_suffix}{(\code{flag})\cr whether the \code{"(n)"} suffix should be added to \code{unique_count} labels. Defaults to \code{TRUE}.} @@ -140,7 +140,16 @@ the statistics from \code{s_num_patients_content()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Count the number of unique and non-unique patients in a column (variable). +The analyze function \code{\link[=analyze_num_patients]{analyze_num_patients()}} creates a layout element to count total numbers of unique or +non-unique patients. The primary analysis variable \code{vars} is used to uniquely identify patients. + +The \code{count_by} variable can be used to identify non-unique patients such that the number of patients with a unique +combination of values in \code{vars} and \code{count_by} will be returned instead as the \code{nonunique} statistic. The \code{required} +variable can be used to specify a variable required to be non-missing for the record to be included in the counts. + +The summarize function \code{\link[=summarize_num_patients]{summarize_num_patients()}} performs the same function as \code{\link[=analyze_num_patients]{analyze_num_patients()}} except it +creates content rows, not data rows, to summarize the current table row/column context and operates on the level of +the latest row split or the root of the table if no row splits have occurred. } \details{ In general, functions that starts with \verb{analyze*} are expected to @@ -174,9 +183,11 @@ As opposed to \code{\link[=summarize_num_patients]{summarize_num_patients()}}, t df <- data.frame( USUBJID = as.character(c(1, 2, 1, 4, NA, 6, 6, 8, 9)), ARM = c("A", "A", "A", "A", "A", "B", "B", "B", "B"), - AGE = c(10, 15, 10, 17, 8, 11, 11, 19, 17) + AGE = c(10, 15, 10, 17, 8, 11, 11, 19, 17), + SEX = c("M", "M", "M", "F", "F", "F", "M", "F", "M") ) +# analyze_num_patients tbl <- basic_table() \%>\% split_cols_by("ARM") \%>\% add_colcounts() \%>\% @@ -185,6 +196,15 @@ tbl <- basic_table() \%>\% tbl +# summarize_num_patients +tbl <- basic_table() \%>\% + split_cols_by("ARM") \%>\% + split_rows_by("SEX") \%>\% + summarize_num_patients("USUBJID", .stats = "unique_count") \%>\% + build_table(df) + +tbl + # Use the statistics function to count number of unique and nonunique patients. s_num_patients(x = as.character(c(1, 1, 1, 2, 4, NA)), labelstr = "", .N_col = 6L) s_num_patients( diff --git a/man/summarize_patients_exposure_in_cols.Rd b/man/summarize_patients_exposure_in_cols.Rd index 7107235d87..a3c73d3b66 100644 --- a/man/summarize_patients_exposure_in_cols.Rd +++ b/man/summarize_patients_exposure_in_cols.Rd @@ -5,7 +5,7 @@ \alias{analyze_patients_exposure_in_cols} \alias{s_count_patients_sum_exposure} \alias{a_count_patients_sum_exposure} -\title{Count patients and sum exposure across all patients in columns} +\title{Count number of patients and sum exposure across all patients in columns} \usage{ analyze_patients_exposure_in_cols( lyt, @@ -132,8 +132,21 @@ columns, to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Counting the number of patients and summing analysis value (i.e exposure values) across all patients -when a column table layout is required. +The analyze function \code{\link[=analyze_patients_exposure_in_cols]{analyze_patients_exposure_in_cols()}} creates a layout element to count total numbers of +patients and sum an analysis value (i.e. exposure) across all patients in columns. + +The primary analysis variable \code{ex_var} is the exposure variable used to calculate the \code{sum_exposure} statistic. The +\code{id} variable is used to uniquely identify patients in the data such that only unique patients are counted in the +\code{n_patients} statistic, and the \code{var} variable is used to create a row split if needed. The percentage returned as +part of the \code{n_patients} statistic is the proportion of all records that correspond to a unique patient. + +The summarize function \code{\link[=summarize_patients_exposure_in_cols]{summarize_patients_exposure_in_cols()}} performs the same function as +\code{\link[=analyze_patients_exposure_in_cols]{analyze_patients_exposure_in_cols()}} except it creates content rows, not data rows, to summarize the current table +row/column context and operates on the level of the latest row split or the root of the table if no row splits have +occurred. + +If a column split has not yet been performed in the table, \code{col_split} must be set to \code{TRUE} for the first call of +\code{\link[=analyze_patients_exposure_in_cols]{analyze_patients_exposure_in_cols()}} or \code{\link[=summarize_patients_exposure_in_cols]{summarize_patients_exposure_in_cols()}}. } \section{Functions}{ \itemize{ diff --git a/man/survival_biomarkers_subgroups.Rd b/man/survival_biomarkers_subgroups.Rd index 430a924c6e..627441c01d 100644 --- a/man/survival_biomarkers_subgroups.Rd +++ b/man/survival_biomarkers_subgroups.Rd @@ -53,8 +53,12 @@ An \code{rtables} table summarizing biomarker effects on survival by subgroup. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Tabulate the estimated effects of multiple continuous biomarker variables -across population subgroups. +The \code{\link[=tabulate_survival_biomarkers]{tabulate_survival_biomarkers()}} function creates a layout element to tabulate the estimated effects of multiple +continuous biomarker variables on survival across subgroups, returning statistics including median survival time and +hazard ratio for each population subgroup. The table is created from \code{df}, a list of data frames returned by +\code{\link[=extract_survival_biomarkers]{extract_survival_biomarkers()}}, with the statistics to include specified via the \code{vars} parameter. + +A forest plot can be created from the resulting table using the \code{\link[=g_forest]{g_forest()}} function. } \details{ These functions create a layout starting from a data frame which contains diff --git a/man/survival_coxph_pairwise.Rd b/man/survival_coxph_pairwise.Rd index 0d00328d35..56231f2082 100644 --- a/man/survival_coxph_pairwise.Rd +++ b/man/survival_coxph_pairwise.Rd @@ -5,11 +5,13 @@ \alias{coxph_pairwise} \alias{s_coxph_pairwise} \alias{a_coxph_pairwise} -\title{Pairwise Cox-PH model} +\title{Analyze a pairwise Cox-PH model} \usage{ coxph_pairwise( lyt, vars, + strata = NULL, + control = control_coxph(), na_str = default_na_str(), nested = TRUE, ..., @@ -49,6 +51,19 @@ a_coxph_pairwise( \item{vars}{(\code{character})\cr variable names for the primary analysis variable to be iterated over.} +\item{strata}{(\code{character} or \code{NULL})\cr variable names indicating stratification factors.} + +\item{control}{(\code{list})\cr parameters for comparison details, specified by using the helper function +\code{\link[=control_coxph]{control_coxph()}}. Some possible parameter options are: +\itemize{ +\item \code{pval_method} (\code{string})\cr p-value method for testing the null hypothesis that hazard ratio = 1. Default +method is \code{"log-rank"} which comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} +(from \code{\link[survival:coxph]{survival::coxph()}}). +\item \code{ties} (\code{string})\cr specifying the method for tie handling. Default is \code{"efron"}, +can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}}. +\item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. +}} + \item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} \item{nested}{(\code{flag})\cr whether this layout instruction should be applied within the existing layout structure _if @@ -86,19 +101,7 @@ by a statistics function.} \item{is_event}{(\code{flag})\cr \code{TRUE} if event, \code{FALSE} if time to event is censored.} -\item{strata}{(\code{character} or \code{NULL})\cr variable names indicating stratification factors.} - \item{strat}{\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{strata} argument instead.} - -\item{control}{(\code{list})\cr parameters for comparison details, specified by using the helper function -\code{\link[=control_coxph]{control_coxph()}}. Some possible parameter options are: -\itemize{ -\item \code{pval_method} (\code{string})\cr p-value method for testing hazard ratio = 1. Default method is \code{"log-rank"} which -comes from \code{\link[survival:survdiff]{survival::survdiff()}}, can also be set to \code{"wald"} or \code{"likelihood"} (from \code{\link[survival:coxph]{survival::coxph()}}). -\item \code{ties} (\code{string})\cr specifying the method for tie handling. Default is \code{"efron"}, -can also be set to \code{"breslow"} or \code{"exact"}. See more in \code{\link[survival:coxph]{survival::coxph()}} -\item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. -}} } \value{ \itemize{ @@ -110,7 +113,7 @@ the statistics from \code{s_coxph_pairwise()} to the table layout. \itemize{ \item \code{s_coxph_pairwise()} returns the statistics: \itemize{ -\item \code{pvalue}: p-value to test HR = 1. +\item \code{pvalue}: p-value to test the null hypothesis that hazard ratio = 1. \item \code{hr}: Hazard ratio. \item \code{hr_ci}: Confidence interval for hazard ratio. \item \code{n_tot}: Total number of observations. @@ -125,14 +128,18 @@ the statistics from \code{s_coxph_pairwise()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Summarize p-value, HR and CIs from stratified or unstratified Cox-PH model. +The analyze function \code{\link[=coxph_pairwise]{coxph_pairwise()}} creates a layout element to analyze a pairwise Cox-PH model. + +This function can return statistics including p-value, hazard ratio (HR), and HR confidence intervals from both +stratified and unstratified Cox-PH models. The variable(s) to be analyzed is specified via the \code{vars} argument and +any stratification factors via the \code{strata} argument. } \section{Functions}{ \itemize{ \item \code{coxph_pairwise()}: Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. -\item \code{s_coxph_pairwise()}: Statistics function which analyzes HR, CIs of HR and p-value of a \code{coxph} model. +\item \code{s_coxph_pairwise()}: Statistics function which analyzes HR, CIs of HR, and p-value of a Cox-PH model. \item \code{a_coxph_pairwise()}: Formatted analysis function which is used as \code{afun} in \code{coxph_pairwise()}. diff --git a/man/survival_duration_subgroups.Rd b/man/survival_duration_subgroups.Rd index c77bacf080..9bd2e96c28 100644 --- a/man/survival_duration_subgroups.Rd +++ b/man/survival_duration_subgroups.Rd @@ -76,7 +76,12 @@ An \code{rtables} table summarizing survival by subgroup. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Tabulate statistics such as median survival time and hazard ratio for population subgroups. +The \code{\link[=tabulate_survival_subgroups]{tabulate_survival_subgroups()}} function creates a layout element to tabulate survival duration by subgroup, +returning statistics including median survival time and hazard ratio for each population subgroup. The table is +created from \code{df}, a list of data frames returned by \code{\link[=extract_survival_subgroups]{extract_survival_subgroups()}}, with the statistics to include +specified via the \code{vars} parameter. + +A forest plot can be created from the resulting table using the \code{\link[=g_forest]{g_forest()}} function. } \details{ These functions create a layout starting from a data frame which contains diff --git a/man/survival_time.Rd b/man/survival_time.Rd index fd8c9f393d..6b658b0e3d 100644 --- a/man/survival_time.Rd +++ b/man/survival_time.Rd @@ -125,8 +125,10 @@ the statistics from \code{s_surv_time()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Summarize median survival time and CIs, percentiles of survival times, survival -time range of censored/event patients. +The analyze function \code{\link[=surv_time]{surv_time()}} creates a layout element to analyze survival time by calculating survival time +median, median confidence interval, quantiles, and range (for all, censored, or event patients). The primary +analysis variable \code{vars} is the time variable and the secondary analysis variable \code{is_event} indicates whether or +not an event has occurred. } \section{Functions}{ \itemize{ diff --git a/man/survival_timepoint.Rd b/man/survival_timepoint.Rd index 41464fd789..e6cbeb22e2 100644 --- a/man/survival_timepoint.Rd +++ b/man/survival_timepoint.Rd @@ -85,11 +85,10 @@ a_surv_timepoint_diff( \item \code{conf_level} (\code{proportion})\cr confidence level of the interval for survival rate. \item \code{conf_type} (\code{string})\cr confidence interval type. Options are "plain" (default), "log", "log-log", see more in \code{\link[survival:survfit]{survival::survfit()}}. Note option "none" is no longer supported. -\item \code{time_point} (\code{numeric(1)})\cr survival time point of interest. }} -\item{method}{(\code{string})\cr \code{surv} (survival estimations), -\code{surv_diff} (difference in survival with the control), or \code{both}.} +\item{method}{(\code{string})\cr \code{"surv"} (survival estimations), \code{"surv_diff"} (difference in survival with the +control), or \code{"both"}.} \item{na_str}{(\code{string})\cr string used to replace all \code{NA} or empty values in the output.} @@ -165,7 +164,12 @@ the value of \code{method}. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Summarize patients' survival rate and difference of survival rates between groups at a time point. +The analyze function \code{\link[=surv_timepoint]{surv_timepoint()}} creates a layout element to analyze patient survival rates and difference +of survival rates between groups at a given time point. The primary analysis variable \code{vars} is the time variable. +Other required inputs are \code{time_point}, the numeric time point of interest, and \code{is_event}, a variable that +indicates whether or not an event has occurred. The \code{method} argument is used to specify whether you want to analyze +survival estimations (\code{"surv"}), difference in survival with the control (\code{"surv_diff"}), or both of these +(\code{"both"}). } \section{Functions}{ \itemize{ From 9ce659ddda45549bbd27892d9c5bdc831f68f0ea Mon Sep 17 00:00:00 2001 From: edelarua Date: Thu, 5 Sep 2024 19:49:07 +0000 Subject: [PATCH 08/12] [skip actions] Bump version to 0.9.5.9020 --- DESCRIPTION | 2 +- NEWS.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index d954b64410..bb68293602 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9019 +Version: 0.9.5.9020 Date: 2024-09-05 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), diff --git a/NEWS.md b/NEWS.md index 582bb5ee11..11daaa6079 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9019 +# tern 0.9.5.9020 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. From dfaa310e554b6f18bd36c6ecb822ec230b7f2d16 Mon Sep 17 00:00:00 2001 From: Emily de la Rua <59304861+edelarua@users.noreply.github.com> Date: Fri, 6 Sep 2024 17:39:39 -0400 Subject: [PATCH 09/12] Finalize deprecation of <0.9.4 arguments (#1304) Fixes #1303 --- NEWS.md | 1 + R/argument_convention.R | 4 ---- R/g_forest.R | 10 +++++----- R/g_lineplot.R | 16 +--------------- R/h_km.R | 2 +- R/h_response_biomarkers_subgroups.R | 4 ++-- R/h_response_subgroups.R | 2 +- R/h_survival_biomarkers_subgroups.R | 2 +- R/h_survival_duration_subgroups.R | 2 +- R/response_biomarkers_subgroups.R | 2 +- R/response_subgroups.R | 2 +- R/survival_biomarkers_subgroups.R | 2 +- R/survival_coxph_pairwise.R | 2 +- R/survival_duration_subgroups.R | 2 +- R/utils_default_stats_formats_labels.R | 4 ++-- man/argument_convention.Rd | 5 ----- man/control_lineplot_vars.Rd | 8 +------- tests/testthat/test-g_lineplot.R | 3 --- 18 files changed, 21 insertions(+), 52 deletions(-) diff --git a/NEWS.md b/NEWS.md index 11daaa6079..bd3afce96a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -20,6 +20,7 @@ ### Miscellaneous * Began deprecation of the confusing functions `summary_formats` and `summary_labels`. * Enhanced general descriptions of analyze and summarize functions throughout package documentation. +* Finalized deprecation of the `strata` and `cohort_id` arguments to `g_lineplot`. # tern 0.9.5 diff --git a/R/argument_convention.R b/R/argument_convention.R index 34c92b7786..e2b64b31c1 100644 --- a/R/argument_convention.R +++ b/R/argument_convention.R @@ -31,7 +31,6 @@ #' @param conf_level (`proportion`)\cr confidence level of the interval. #' @param data (`data.frame`)\cr the dataset containing the variables to summarize. #' @param df (`data.frame`)\cr data set containing all analysis variables. -#' @param draw (`flag`)\cr whether the plot should be drawn. #' @param groups_lists (named `list` of `list`)\cr optionally contains for each `subgroups` variable a #' list, which specifies the new group levels via the names and the #' levels that belong to it in the character vectors that are elements of the list. @@ -49,8 +48,6 @@ #' @param nested (`flag`)\cr whether this layout instruction should be applied within the existing layout structure _if #' possible (`TRUE`, the default) or as a new top-level element (`FALSE`). Ignored if it would nest a split. #' underneath analyses, which is not allowed. -#' @param newpage (`flag`)\cr whether the plot should be drawn on a new page. -#' Only considered if `draw = TRUE` is used. #' @param prune_zero_rows (`flag`)\cr whether to prune all zero rows. #' @param riskdiff (`flag`)\cr whether a risk difference column is present. When set to `TRUE`, [add_riskdiff()] must be #' used as `split_fun` in the prior column split of the table layout, specifying which columns should be compared. @@ -72,7 +69,6 @@ #' @param ylim (`numeric(2)`)\cr vector containing lower and upper limits for the y-axis, respectively. #' If `NULL` (default), the default scale range is used. #' -#' #' @details Although this function just returns `NULL` it has two uses, for #' the `tern` users it provides a documentation of arguments that are #' commonly and consistently used in the framework. For the developer it adds a diff --git a/R/g_forest.R b/R/g_forest.R index 35c2844f0e..b1709ea88e 100644 --- a/R/g_forest.R +++ b/R/g_forest.R @@ -182,19 +182,19 @@ g_forest <- function(tbl, # Deprecated argument warnings if (lifecycle::is_present(width_row_names)) { lifecycle::deprecate_warn( - "0.9.3", "g_forest(width_row_names)", "g_forest(lbl_col_padding)", + "0.9.4", "g_forest(width_row_names)", "g_forest(lbl_col_padding)", details = "The width of the row label column can be adjusted via the `lbl_col_padding` parameter." ) } if (lifecycle::is_present(width_forest)) { lifecycle::deprecate_warn( - "0.9.3", "g_forest(width_forest)", "g_forest(rel_width_forest)", + "0.9.4", "g_forest(width_forest)", "g_forest(rel_width_forest)", details = "Relative width of the forest plot (as a proportion) can be set via the `rel_width_forest` parameter." ) } if (lifecycle::is_present(gp)) { lifecycle::deprecate_warn( - "0.9.3", "g_forest(gp)", "g_forest(ggtheme)", + "0.9.4", "g_forest(gp)", "g_forest(ggtheme)", details = paste( "`g_forest` is now generated as a `ggplot` object.", "Additional display settings should be supplied via the `ggtheme` parameter." @@ -203,13 +203,13 @@ g_forest <- function(tbl, } if (lifecycle::is_present(draw)) { lifecycle::deprecate_warn( - "0.9.3", "g_forest(draw)", + "0.9.4", "g_forest(draw)", details = "`g_forest` now generates `ggplot` objects. This parameter has no effect." ) } if (lifecycle::is_present(newpage)) { lifecycle::deprecate_warn( - "0.9.3", "g_forest(newpage)", + "0.9.4", "g_forest(newpage)", details = "`g_forest` now generates `ggplot` objects. This parameter has no effect." ) } diff --git a/R/g_lineplot.R b/R/g_lineplot.R index a234e835b3..82589e18ed 100644 --- a/R/g_lineplot.R +++ b/R/g_lineplot.R @@ -548,9 +548,7 @@ h_format_row <- function(x, format, labels = NULL) { #' @param x (`string`)\cr x-variable name. #' @param y (`string`)\cr y-variable name. #' @param group_var (`string` or `NA`)\cr group variable name. -#' @param strata `r lifecycle::badge("deprecated")` use the `group_var` parameter instead. #' @param subject_var (`string` or `NA`)\cr subject variable name. -#' @param cohort_id `r lifecycle::badge("deprecated")` use the `subject_var` parameter instead. #' @param facet_var (`string` or `NA`)\cr faceting variable name. #' @param paramcd (`string` or `NA`)\cr parameter code variable name. #' @param y_unit (`string` or `NA`)\cr y-axis unit variable name. @@ -568,19 +566,7 @@ control_lineplot_vars <- function(x = "AVISIT", facet_var = NA, paramcd = "PARAMCD", y_unit = "AVALU", - subject_var = "USUBJID", - strata = lifecycle::deprecated(), - cohort_id = lifecycle::deprecated()) { - if (lifecycle::is_present(strata)) { - lifecycle::deprecate_warn("0.9.2", "control_lineplot_vars(strata)", "control_lineplot_vars(group_var)") - group_var <- strata - } - - if (lifecycle::is_present(cohort_id)) { - lifecycle::deprecate_warn("0.9.2", "control_lineplot_vars(cohort_id)", "control_lineplot_vars(subject_id)") - subject_id <- cohort_id - } - + subject_var = "USUBJID") { checkmate::assert_string(x) checkmate::assert_string(y) checkmate::assert_string(group_var, na.ok = TRUE, null.ok = TRUE) diff --git a/R/h_km.R b/R/h_km.R index e038f3fa5a..bc7dd6b06d 100644 --- a/R/h_km.R +++ b/R/h_km.R @@ -188,7 +188,7 @@ h_tbl_coxph_pairwise <- function(df, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_tbl_coxph_pairwise() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/h_response_biomarkers_subgroups.R b/R/h_response_biomarkers_subgroups.R index 43088f2200..706bf247c0 100644 --- a/R/h_response_biomarkers_subgroups.R +++ b/R/h_response_biomarkers_subgroups.R @@ -49,7 +49,7 @@ h_rsp_to_logistic_variables <- function(variables, biomarker) { if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_rsp_to_logistic_variables() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] @@ -106,7 +106,7 @@ h_logistic_mult_cont_df <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_logistic_mult_cont_df() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/h_response_subgroups.R b/R/h_response_subgroups.R index 173ef292c0..9d968fdf13 100644 --- a/R/h_response_subgroups.R +++ b/R/h_response_subgroups.R @@ -328,7 +328,7 @@ h_odds_ratio_subgroups_df <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_odds_ratio_subgroups_df() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/h_survival_biomarkers_subgroups.R b/R/h_survival_biomarkers_subgroups.R index 9f9de3f34d..cb5519b0c9 100644 --- a/R/h_survival_biomarkers_subgroups.R +++ b/R/h_survival_biomarkers_subgroups.R @@ -110,7 +110,7 @@ h_coxreg_mult_cont_df <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_coxreg_mult_cont_df() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/h_survival_duration_subgroups.R b/R/h_survival_duration_subgroups.R index 69ac0c62f0..fcc6680e9a 100644 --- a/R/h_survival_duration_subgroups.R +++ b/R/h_survival_duration_subgroups.R @@ -335,7 +335,7 @@ h_coxph_subgroups_df <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `h_coxph_subgroups_df() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/response_biomarkers_subgroups.R b/R/response_biomarkers_subgroups.R index 360432998b..b18ad598ae 100644 --- a/R/response_biomarkers_subgroups.R +++ b/R/response_biomarkers_subgroups.R @@ -195,7 +195,7 @@ extract_rsp_biomarkers <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `extract_rsp_biomarkers() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/response_subgroups.R b/R/response_subgroups.R index c7c61d4b94..d80924d4e4 100644 --- a/R/response_subgroups.R +++ b/R/response_subgroups.R @@ -99,7 +99,7 @@ extract_rsp_subgroups <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `extract_rsp_subgroups() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index c527f0209e..72cffb2334 100644 --- a/R/survival_biomarkers_subgroups.R +++ b/R/survival_biomarkers_subgroups.R @@ -116,7 +116,7 @@ extract_survival_biomarkers <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `extract_survival_biomarkers() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/survival_coxph_pairwise.R b/R/survival_coxph_pairwise.R index 4495962290..88ec24b68e 100644 --- a/R/survival_coxph_pairwise.R +++ b/R/survival_coxph_pairwise.R @@ -47,7 +47,7 @@ s_coxph_pairwise <- function(df, strat = lifecycle::deprecated(), control = control_coxph()) { if (lifecycle::is_present(strat)) { - lifecycle::deprecate_warn("0.9.3", "s_coxph_pairwise(strat)", "s_coxph_pairwise(strata)") + lifecycle::deprecate_warn("0.9.4", "s_coxph_pairwise(strat)", "s_coxph_pairwise(strata)") strata <- strat } diff --git a/R/survival_duration_subgroups.R b/R/survival_duration_subgroups.R index 90fc9b2376..eab7e46b9b 100644 --- a/R/survival_duration_subgroups.R +++ b/R/survival_duration_subgroups.R @@ -123,7 +123,7 @@ extract_survival_subgroups <- function(variables, if ("strat" %in% names(variables)) { warning( "Warning: the `strat` element name of the `variables` list argument to `extract_survival_subgroups() ", - "was deprecated in tern 0.9.3.\n ", + "was deprecated in tern 0.9.4.\n ", "Please use the name `strata` instead of `strat` in the `variables` argument." ) variables[["strata"]] <- variables[["strat"]] diff --git a/R/utils_default_stats_formats_labels.R b/R/utils_default_stats_formats_labels.R index 34cc8937a1..fc11ce3fed 100644 --- a/R/utils_default_stats_formats_labels.R +++ b/R/utils_default_stats_formats_labels.R @@ -514,7 +514,7 @@ tern_default_labels <- c( #' @export summary_formats <- function(type = "numeric", include_pval = FALSE) { lifecycle::deprecate_warn( - "0.9.5.9005", "summary_formats()", + "0.9.6", "summary_formats()", details = 'Use get_formats_from_stats(get_stats("analyze_vars_numeric", add_pval = include_pval)) instead' ) met_grp <- paste0(c("analyze_vars", type), collapse = "_") @@ -537,7 +537,7 @@ summary_formats <- function(type = "numeric", include_pval = FALSE) { #' @export summary_labels <- function(type = "numeric", include_pval = FALSE) { lifecycle::deprecate_warn( - "0.9.5.9005", "summary_formats()", + "0.9.6", "summary_formats()", details = 'Use get_labels_from_stats(get_stats("analyze_vars_numeric", add_pval = include_pval)) instead' ) met_grp <- paste0(c("analyze_vars", type), collapse = "_") diff --git a/man/argument_convention.Rd b/man/argument_convention.Rd index 7b13f98616..775937acba 100644 --- a/man/argument_convention.Rd +++ b/man/argument_convention.Rd @@ -51,8 +51,6 @@ that constitute the split. A custom label can be set for this level via the \cod \item{df}{(\code{data.frame})\cr data set containing all analysis variables.} -\item{draw}{(\code{flag})\cr whether the plot should be drawn.} - \item{groups_lists}{(named \code{list} of \code{list})\cr optionally contains for each \code{subgroups} variable a list, which specifies the new group levels via the names and the levels that belong to it in the character vectors that are elements of the list.} @@ -80,9 +78,6 @@ two proportions. For options, see \code{\link[=test_proportion_diff]{test_propor possible (\code{TRUE}, the default) or as a new top-level element (\code{FALSE}). Ignored if it would nest a split. underneath analyses, which is not allowed.} -\item{newpage}{(\code{flag})\cr whether the plot should be drawn on a new page. -Only considered if \code{draw = TRUE} is used.} - \item{prune_zero_rows}{(\code{flag})\cr whether to prune all zero rows.} \item{riskdiff}{(\code{flag})\cr whether a risk difference column is present. When set to \code{TRUE}, \code{\link[=add_riskdiff]{add_riskdiff()}} must be diff --git a/man/control_lineplot_vars.Rd b/man/control_lineplot_vars.Rd index cf52768f5e..33dd7b3838 100644 --- a/man/control_lineplot_vars.Rd +++ b/man/control_lineplot_vars.Rd @@ -11,9 +11,7 @@ control_lineplot_vars( facet_var = NA, paramcd = "PARAMCD", y_unit = "AVALU", - subject_var = "USUBJID", - strata = lifecycle::deprecated(), - cohort_id = lifecycle::deprecated() + subject_var = "USUBJID" ) } \arguments{ @@ -30,10 +28,6 @@ control_lineplot_vars( \item{y_unit}{(\code{string} or \code{NA})\cr y-axis unit variable name.} \item{subject_var}{(\code{string} or \code{NA})\cr subject variable name.} - -\item{strata}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} use the \code{group_var} parameter instead.} - -\item{cohort_id}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} use the \code{subject_var} parameter instead.} } \value{ A named character vector of variable names. diff --git a/tests/testthat/test-g_lineplot.R b/tests/testthat/test-g_lineplot.R index 15b2b264c4..4ef5d541f1 100644 --- a/tests/testthat/test-g_lineplot.R +++ b/tests/testthat/test-g_lineplot.R @@ -138,9 +138,6 @@ testthat::test_that("g_lineplot xticks, xlim, and ylim arguments work", { testthat::test_that("control_lineplot_vars works", { testthat::expect_silent(control_lineplot_vars(group_var = NA)) - - # Deprecation warnings work - lifecycle::expect_deprecated(lifecycle::expect_deprecated(control_lineplot_vars(strata = NA, cohort_id = NA))) }) testthat::test_that("g_lineplot works with no strata (group_var) and allows points when only one strata is provided", { From 12bfafc144ea2d78533c4f66272e48530fdaef89 Mon Sep 17 00:00:00 2001 From: edelarua Date: Fri, 6 Sep 2024 21:40:54 +0000 Subject: [PATCH 10/12] [skip actions] Bump version to 0.9.5.9021 --- DESCRIPTION | 4 ++-- NEWS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index bb68293602..ba1d80aae2 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9020 -Date: 2024-09-05 +Version: 0.9.5.9021 +Date: 2024-09-06 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"), diff --git a/NEWS.md b/NEWS.md index bd3afce96a..63d4ee5c43 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9020 +# tern 0.9.5.9021 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose. From 2ba7c7ef0e8fe6837f6d56f61591fa3da799a582 Mon Sep 17 00:00:00 2001 From: Davide Garolini Date: Mon, 9 Sep 2024 19:49:02 +0200 Subject: [PATCH 11/12] fix grob wrapping final (#1305) Fixes #1287 I hope this is a wrap (:D). @BFalquet could take a look if it works on your side? Result may be numerically different but this is the real solution to the issue. On another note, we need to consider uniforming `\\n` to `\n` if it happens. I now know it is not always assumed the same and we have mixed behavior around the packages. I will check this for {rtables}. I was able to break wrapping by doing this. --- NEWS.md | 1 + R/decorate_grob.R | 32 ++++++++++++++-- R/utils_rtables.R | 2 +- tests/testthat/test-decorate_grob.R | 59 +++++++++++++++++++++++++++++ 4 files changed, 89 insertions(+), 5 deletions(-) diff --git a/NEWS.md b/NEWS.md index 63d4ee5c43..f1a286f304 100644 --- a/NEWS.md +++ b/NEWS.md @@ -16,6 +16,7 @@ * Fixed bug for linear scaling factor (`scale` parameter) being applied to response but not to rate in `h_glm_count` while all distributions have logarithmic link function. * Fixed bug in `decorate_grob` that did not handle well empty strings or `NULL` values for title and footers. * Fixed bug in `g_km` that caused an error when multiple records in the data had estimates at max time. +* Fixed issue with wrong wrapping due to different `\n` and vector behavior that did not cope well with `split_string()`. ### Miscellaneous * Began deprecation of the confusing functions `summary_formats` and `summary_labels`. diff --git a/R/decorate_grob.R b/R/decorate_grob.R index 9251e3635b..a86eb0e6ef 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -306,7 +306,7 @@ split_text_grob <- function(text, name = NULL, gp = grid::gpar(), vp = NULL) { - text <- paste0(text, collapse = "\n") # necessary for c("", "a a") + text <- gsub("\\\\n", "\n", text) # fixing cases of mixed behavior (\n and \\n) if (!grid::is.unit(x)) x <- grid::unit(x, default.units) if (!grid::is.unit(y)) y <- grid::unit(y, default.units) @@ -316,8 +316,23 @@ split_text_grob <- function(text, if (grid::unitType(width) %in% c("sum", "min", "max")) width <- grid::convertUnit(width, default.units) if (length(gp) > 0) { # account for effect of gp on text width -> it was bugging when text was empty - width <- width * grid::convertWidth(grid::grobWidth(grid::textGrob(text)), "npc", valueOnly = TRUE) / - grid::convertWidth(grid::grobWidth(grid::textGrob(text, gp = gp)), "npc", valueOnly = TRUE) + horizontal_npc_width_no_gp <- grid::convertWidth( + grid::grobWidth( + grid::textGrob( + paste0(text, collapse = "\n") + ) + ), "npc", + valueOnly = TRUE + ) + horizontal_npc_width_with_gp <- grid::convertWidth(grid::grobWidth( + grid::textGrob( + paste0(text, collapse = "\n"), + gp = gp + ) + ), "npc", valueOnly = TRUE) + + # Adapting width to the input gpar (it is normalized so does not matter what is text) + width <- width * horizontal_npc_width_no_gp / horizontal_npc_width_with_gp } ## if it is a fixed unit then we do not need to recalculate when viewport resized @@ -326,8 +341,17 @@ split_text_grob <- function(text, attr(text, "fixed_text") <- paste(vapply(text, split_string, character(1), width = width), collapse = "\n") } + # Fix for split_string in case of residual \n (otherwise is counted as character) + text2 <- unlist( + strsplit( + paste0(text, collapse = "\n"), # for "" cases + "\n" + ) + ) + + # Final grid text with cat-friendly split_string grid::grid.text( - label = split_string(text, width), + label = split_string(text2, width), x = x, y = y, just = just, hjust = hjust, diff --git a/R/utils_rtables.R b/R/utils_rtables.R index 7d854d8f33..61dd4b5f3e 100644 --- a/R/utils_rtables.R +++ b/R/utils_rtables.R @@ -48,7 +48,7 @@ to_string_matrix <- function(x, widths = NULL, max_width = NULL, # Producing the matrix to test if (with_spaces) { - out <- strsplit(toString(tx, widths = widths, tf_wrap = tf_wrap, max_width = max_width, hsep = hsep), "\\n")[[1]] + out <- strsplit(toString(tx, widths = widths, tf_wrap = tf_wrap, max_width = max_width, hsep = hsep), "\n")[[1]] } else { out <- tx$strings } diff --git a/tests/testthat/test-decorate_grob.R b/tests/testthat/test-decorate_grob.R index 16b2f224a9..2b958fb37d 100644 --- a/tests/testthat/test-decorate_grob.R +++ b/tests/testthat/test-decorate_grob.R @@ -142,3 +142,62 @@ testthat::test_that("Edge cases work for titles and footers in split_text_grob", split_text_grob(c("", "a a")) ) }) + +testthat::test_that("Wrapping works consistently", { + # ggplot + g <- ggplot2::ggplot(iris) + + ggplot2::geom_point(aes(x = Sepal.Length, y = Sepal.Width)) + + # decoration text + eg_text <- c( + paste( # titles + rep("issues come in long pairs", 10), + collapse = " " + ), + c( # subtitles + "something\nwith\\n", "", "and such" + ) + ) + # example width (it is default for A4 with 1.5cm margin) + eg_width <- grid::unit(11.63, "inches") - grid::unit(1.5, "cm") + + # Main call to text grob split + out <- split_text_grob(eg_text, + x = 0, y = 1, + just = c("left", "top"), + width = eg_width, + vp = grid::viewport(layout.pos.row = 1, layout.pos.col = 1), + gp = grid::gpar() + ) + + # This is what (roughly w/o font correction from gpar) happens inside the split + eg_width <- grid::convertUnit(eg_width, "npc") + # Fix for split_string in case of residual \n (otherwise is counted as character) + text_fin <- split_string( # copied fnc (NOT formatters') + unlist( + strsplit( + paste0(gsub("\\\\n", "\n", eg_text), collapse = "\n"), # for "" cases + "\n" + ) + ), + eg_width + ) + + # number of characters + nchar_lab_extracted <- nchar(strsplit(out$label, "\n")[[1]]) + nchar_lab_test <- nchar(strsplit(text_fin, "\n")[[1]]) + exp_nchar_lab <- c(144, 114, 9, 4, 0, 0, 8) + + # Force informative error + if (!checkmate::check_set_equal(nchar_lab_extracted, exp_nchar_lab)) { + stop( + "width:", eg_width, + "\nnchar_out_label : ", paste(nchar_lab_extracted, collapse = " "), + "\nnchar_label_free : ", paste(nchar_lab_test, collapse = " ") + ) + } + + # Default passing tests + testthat::expect_equal(nchar_lab_extracted, nchar_lab_test) + testthat::expect_equal(nchar_lab_extracted, exp_nchar_lab) +}) From 03eac81da65d15b66bfbb5d2de8153725b1223a2 Mon Sep 17 00:00:00 2001 From: Melkiades Date: Mon, 9 Sep 2024 17:50:16 +0000 Subject: [PATCH 12/12] [skip actions] Bump version to 0.9.5.9022 --- DESCRIPTION | 4 ++-- NEWS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index ba1d80aae2..9396f1cba6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: tern Title: Create Common TLGs Used in Clinical Trials -Version: 0.9.5.9021 -Date: 2024-09-06 +Version: 0.9.5.9022 +Date: 2024-09-09 Authors@R: c( person("Joe", "Zhu", , "joe.zhu@roche.com", role = c("aut", "cre")), person("Daniel", "Sabanés Bové", , "daniel.sabanes_bove@roche.com", role = "aut"), diff --git a/NEWS.md b/NEWS.md index f1a286f304..6a0883b771 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# tern 0.9.5.9021 +# tern 0.9.5.9022 ### Enhancements * Added `errorbar_width` and `linetype` parameters to `g_lineplot`. * Reworking of `summarize_glm_count()` documentation and all its associated functions to better describe the results and the functions' purpose.