diff --git a/NAMESPACE b/NAMESPACE index 66d25d0cd9..bf8555234c 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -9,11 +9,8 @@ S3method(a_summary,factor) S3method(a_summary,logical) S3method(a_summary,numeric) S3method(as.rtable,data.frame) -S3method(drawDetails,dynamicSplitText) S3method(h_coxreg_inter_effect,factor) S3method(h_coxreg_inter_effect,numeric) -S3method(heightDetails,decoratedGrob) -S3method(heightDetails,dynamicSplitText) S3method(s_compare,character) S3method(s_compare,factor) S3method(s_compare,logical) @@ -30,10 +27,6 @@ S3method(tidy,coxreg.univar) S3method(tidy,glm) S3method(tidy,step) S3method(tidy,summary.coxph) -S3method(validDetails,decoratedGrob) -S3method(validDetails,dynamicSplitText) -S3method(widthDetails,decoratedGrob) -S3method(widthDetails,dynamicSplitText) export(CombinationFunction) export(a_compare) export(a_count_occurrences) diff --git a/R/abnormal.R b/R/abnormal.R index 17c31badec..d9ca3984b7 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -6,20 +6,20 @@ #' 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: -#' \describe{ -#' \item{num}{the number of patients with this abnormality recorded while on treatment.} -#' \item{denom}{the number of patients with at least one post-baseline assessment.} -#' } -#' Note, the denominator includes patients that might have other abnormal levels at baseline, -#' and patients with missing baseline. Note, optionally patients with this abnormality at -#' baseline can be excluded from numerator and denominator. -#' -#' @details Note that `df` should be filtered to include only post-baseline records. +#' * `num` : The number of patients with this abnormality recorded while on treatment. +#' * `denom`: The number of patients with at least one post-baseline assessment. #' #' @inheritParams argument_convention -#' @param abnormal (`named list`)\cr identifying the abnormal range level(s) in `var`. Default to -#' `list(Low = "LOW", High = "HIGH")` but you can also group different levels into the name list, -#' for example, `abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))` +#' @param abnormal (named `list`)\cr list identifying the abnormal range level(s) in `var`. Defaults to +#' `list(Low = "LOW", High = "HIGH")` but you can also group different levels into the named list, +#' for example, `abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))`. +#' +#' @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. #' #' @name abnormal #' @include formats.R @@ -29,8 +29,9 @@ NULL #' for a single `abnormal` level. #' @param exclude_base_abn (`flag`)\cr whether to exclude subjects with baseline abnormality #' from numerator and denominator. -#' @return [s_count_abnormal()] returns the statistic `fraction` which is a -#' vector with `num` and `denom` counts of patients. +#' +#' @return +#' * `s_count_abnormal()` returns the statistic `fraction` which is a vector with `num` and `denom` counts of patients. #' #' @examples #' library(dplyr) @@ -105,10 +106,10 @@ s_count_abnormal <- function(df, result } -#' @describeIn abnormal Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn abnormal Formatted analysis function which is used as `afun` in `count_abnormal()`. #' -#' @return [a_count_abnormal()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @return +#' * `a_count_abnormal()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_abnormal @@ -124,10 +125,14 @@ a_count_abnormal <- make_afun( .formats = c(fraction = format_fraction) ) -#' @describeIn abnormal Layout creating function which can be used for creating tables, which can take -#' statistics function arguments and additional format arguments (see below). Note that it only -#' works with a single variable but multiple abnormal levels. -#' @return [count_abnormal()] can be used with multiple abnormal levels and modifies the layout. +#' @describeIn abnormal Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `count_abnormal()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_abnormal()` to the table layout. +#' #' @export #' @examples #' # Layout creating function. diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index 7afdd6e0d9..a01dd733b5 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -2,11 +2,8 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' @details -#' Note that `df` should be filtered to include only post-baseline records. -#' -#' 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 +#' 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 ` @@ -21,10 +18,15 @@ #' #' @inheritParams argument_convention #' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`. +#' +#' @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()]. +#' #' @seealso Relevant description function [d_count_abnormal_by_baseline()]. #' #' @name abnormal_by_baseline -#' @include formats.R NULL #' Description Function for [s_count_abnormal_by_baseline()] @@ -34,6 +36,7 @@ NULL #' Description function that produces the labels for [s_count_abnormal_by_baseline()]. #' #' @inheritParams abnormal_by_baseline +#' @return Abnormal category labels for [s_count_abnormal_by_baseline()]. #' #' @examples #' d_count_abnormal_by_baseline("LOW") @@ -52,14 +55,14 @@ d_count_abnormal_by_baseline <- function(abnormal) { ) } -#' @describeIn abnormal_by_baseline For a single `abnormal` level, produce a statistic `fraction` which is -#' a named list with 3 elements: `not_abnormal`, `abnormal` and `total`. -#' Each element contains a vector with `num` and `denom` counts of patients. -#' Please note that 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()`. +#' @describeIn abnormal_by_baseline Statistics function for a single `abnormal` level. #' #' @param na_level (`string`)\cr the explicit `na_level` argument you used in the pre-processing steps (maybe with -#' `df_explicit_na()`). The default is `""`. +#' [df_explicit_na()]). The default is `""`. +#' +#' @return +#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labeled elements: +#' `not_abnormal`, `abnormal`, and `total`. Each element contains a vector with `num` and `denom` patient counts. #' #' @examples #' df <- data.frame( @@ -138,10 +141,11 @@ s_count_abnormal_by_baseline <- function(df, )) } -#' @describeIn abnormal_by_baseline Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn abnormal_by_baseline Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_baseline()`. #' -#' @return [a_count_abnormal_by_baseline()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @return +#' * `a_count_abnormal_by_baseline()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_abnormal_by_baseline @@ -158,10 +162,13 @@ a_count_abnormal_by_baseline <- make_afun( .formats = c(fraction = format_fraction) ) -#' @describeIn abnormal_by_baseline Layout creating function which can be used for creating tables, which can take -#' statistics function arguments and additional format arguments (see below). +#' @describeIn abnormal_by_baseline Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' -#' @inheritParams argument_convention +#' @return +#' * `count_abnormal_by_baseline()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_abnormal_by_baseline()` to the table layout. #' #' @examples #' # Layout creating function. diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index f888e61a8f..58ccd7b2b3 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -2,33 +2,31 @@ #' #' @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` indicating -#' the direction of the abnormality (factor). -#' Denominator is number of patients with at least one valid measurement during +#' 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. #' -#' @details Note that `Single, not last` and `Last or replicated` levels are -#' mutually exclusive. If a patient has abnormalities that meet both the `Single, not last` -#' and `Last or replicated` criteria, then the patient will be counted only under the `Last or replicated` category. -#' #' @inheritParams argument_convention #' @param category (`list`)\cr with different marked category names for single #' and last or replicated. #' +#' @note `Single, not last` and `Last or replicated` levels are mutually exclusive. If a patient has +#' abnormalities that meet both the `Single, not last` and `Last or replicated` criteria, then the +#' patient will be counted only under the `Last or replicated` category. +#' #' @name abnormal_by_marked NULL -#' @describeIn abnormal_by_marked Statistics function which returns -#' the counts and fractions of patients with `Single, not last`, `Last or replicated` and `Any` -#' marked laboratory abnormalities for a single `abnormal` level. +#' @describeIn abnormal_by_marked Statistics function for patients with marked lab abnormalities. #' -#' @return [s_count_abnormal_by_marked()] the single statistic `count_fraction` -#' with `Single, not last`, `Last or replicated` and `Any` results. +#' @return +#' * `s_count_abnormal_by_marked()` returns statistic `count_fraction` with `Single, not last`, +#' `Last or replicated`, and `Any` results. #' #' @examples #' library(dplyr) @@ -133,10 +131,11 @@ s_count_abnormal_by_marked <- function(df, result } -#' @describeIn abnormal_by_marked Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn abnormal_by_marked Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_marked()`. #' -#' @return [a_count_abnormal_by_marked()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @return +#' * `a_count_abnormal_by_marked()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_abnormal_by_marked @@ -157,8 +156,13 @@ a_count_abnormal_by_marked <- make_afun( .formats = c(count_fraction = format_count_fraction) ) -#' @describeIn abnormal_by_marked Layout creating function which can be used for creating tables, -#' which can take statistics function arguments and additional format arguments (see below). +#' @describeIn abnormal_by_marked Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `count_abnormal_by_marked()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_abnormal_by_marked()` to the table layout. #' #' @examples #' map <- unique( diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 27aa18dcf1..fe9a88bd66 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -2,8 +2,8 @@ #' #' @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`). +#' 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, @@ -11,26 +11,25 @@ #' * `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. #' -#' @details -#' The pre-processing steps are crucial when using this function. From the standard -#' lab grade variable `ATOXGR`, derive the following two variables: +#' @inheritParams argument_convention +#' +#' @details The pre-processing steps are crucial when using this function. From the standard lab grade variable +#' `ATOXGR`, derive the following two variables: #' * A grade direction variable (e.g. `GRADE_DIR`) is required in order to obtain #' the correct denominators when building the layout as it is used to define row splitting. #' * A toxicity grade variable (e.g. `GRADE_ANL`) where all negative values from #' `ATOXGR` are replaced by their absolute values. -#' * Prior to tabulation, `df` must filtered to include only post-baseline records with worst grade flags. #' -#' @inheritParams argument_convention +#' @note Prior to tabulation, `df` must be filtered to include only post-baseline records with worst grade flags. #' #' @name abnormal_by_worst_grade NULL -#' @describeIn abnormal_by_worst_grade Statistics function which counts patients with worst grade, -#' consisting of counts and percentages of patients with worst grade -#' `1` to `4`, and `Any` non-zero grade. +#' @describeIn abnormal_by_worst_grade Statistics function which counts patients by worst grade. #' -#' @return [s_count_abnormal_by_worst_grade()] the single statistic `count_fraction` with grade 1 to 4 -#' and "Any" results. +#' @return +#' * `s_count_abnormal_by_worst_grade()` returns the single statistic `count_fraction` with grades 1 to 4 and +#' "Any" results. #' #' @examples #' library(dplyr) @@ -132,10 +131,11 @@ s_count_abnormal_by_worst_grade <- function(df, # nolint result } -#' @describeIn abnormal_by_worst_grade Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn abnormal_by_worst_grade Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_worst_grade()`. #' -#' @return [a_count_abnormal_by_worst_grade()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @return +#' * `a_count_abnormal_by_worst_grade()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_abnormal_by_worst_grade @@ -152,8 +152,13 @@ a_count_abnormal_by_worst_grade <- make_afun( # nolint .formats = c(count_fraction = format_count_fraction) ) -#' @describeIn abnormal_by_worst_grade Layout creating function which can be used for creating tables, -#' which can take statistics function arguments and additional format arguments (see below). +#' @describeIn abnormal_by_worst_grade Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `count_abnormal_by_worst_grade()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_abnormal_by_worst_grade()` to the table layout. #' #' @examples #' # Map excludes records without abnormal grade since they should not be displayed diff --git a/R/abnormal_by_worst_grade_worsen.R b/R/abnormal_by_worst_grade_worsen.R index 856b4a0730..30ed91a596 100644 --- a/R/abnormal_by_worst_grade_worsen.R +++ b/R/abnormal_by_worst_grade_worsen.R @@ -6,7 +6,7 @@ #' #' @inheritParams argument_convention #' -#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()]. +#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()] #' #' @name abnormal_by_worst_grade_worsen NULL @@ -26,13 +26,14 @@ NULL #' * `H`: high direction only #' * `B`: both low and high directions #' -#' @return [h_adlb_worsen()] returns the `adlb` `data.frame` containing only the +#' @return `h_adlb_worsen()` returns the `adlb` `data.frame` containing only the #' worst labs specified according to `worst_flag_low` or `worst_flag_high` for the #' direction specified according to `direction_var`. For instance, for a lab that is #' needed for the low direction only, only records flagged by `worst_flag_low` are #' selected. For a lab that is needed for both low and high directions, the worst #' low records are selected for the low direction, and the worst high record are selected #' for the high direction. +#' #' @seealso [abnormal_by_worst_grade_worsen] #' #' @examples @@ -157,9 +158,11 @@ h_adlb_worsen <- function(adlb, #' @inheritParams argument_convention #' @inheritParams h_adlb_worsen #' @param baseline_var (`string`)\cr baseline lab grade variable -#' @return [h_worsen_counter()] returns the counts and fraction of patients +#' +#' @return `h_worsen_counter()` returns the counts and fraction of patients #' whose worst post-baseline lab grades are worse than their baseline grades, for #' post-baseline worst grades "1", "2", "3", "4" and "Any". +#' #' @seealso [abnormal_by_worst_grade_worsen] #' #' @examples @@ -257,17 +260,18 @@ h_worsen_counter <- function(df, id, .var, baseline_var, direction_var) { list(fraction = c(by_grade, list("Any" = c(num = num, denom = denom)))) } -#' @describeIn abnormal_by_worst_grade_worsen Statistics function which calculates the -#' counts and fraction of patients whose worst post-baseline lab grades are worse than -#' their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any". +#' @describeIn abnormal_by_worst_grade_worsen Statistics function for patients whose worst post-baseline +#' lab grades are worse than their baseline grades. #' #' @param variables (named `list` of `string`)\cr list of additional analysis variables including: #' * `id` (`string`)\cr subject variable name. #' * `baseline_var` (`string`)\cr name of the data column containing baseline toxicity variable. #' * `direction_var` (`string`)\cr see `direction_var` for more details. -#' @return [s_count_abnormal_lab_worsen_by_baseline()] returns the -#' counts and fraction of patients whose worst post-baseline lab grades are worse than -#' their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any". +#' +#' @return +#' * `s_count_abnormal_lab_worsen_by_baseline()` returns the counts and fraction of patients whose worst +#' post-baseline lab grades are worse than their baseline grades, for post-baseline worst grades +#' "1", "2", "3", "4" and "Any". #' #' @examples #' library(dplyr) @@ -323,9 +327,11 @@ s_count_abnormal_lab_worsen_by_baseline <- function(df, # nolint } -#' @describeIn abnormal_by_worst_grade_worsen +#' @describeIn abnormal_by_worst_grade_worsen Formatted analysis function which is used as `afun` +#' in `count_abnormal_lab_worsen_by_baseline()`. #' -#' @return [a_count_abnormal_lab_worsen_by_baseline()] returns the corresponding list with +#' @return +#' * `a_count_abnormal_lab_worsen_by_baseline()` returns the corresponding list with #' formatted [rtables::CellValue()]. #' #' @examples @@ -345,8 +351,13 @@ a_count_abnormal_lab_worsen_by_baseline <- make_afun( # nolint .ungroup_stats = "fraction" ) -#' @describeIn abnormal_by_worst_grade_worsen Layout creating function which can be used for creating tables, -#' which can take statistics function arguments and additional format arguments (see below). +#' @describeIn abnormal_by_worst_grade_worsen Layout-creating function which can take statistics function +#' arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `count_abnormal_lab_worsen_by_baseline()` returns a layout object suitable for passing to further layouting +#' functions, or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted +#' rows containing the statistics from `s_count_abnormal_lab_worsen_by_baseline()` to the table layout. #' #' @examples #' basic_table() %>% diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 5427846ae4..0f3b756f37 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -2,22 +2,19 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' This function can be used to produce summary tables for PK datasets where -#' the relevant statistic is on the columns instead of on the rows. -#' -#' @name analyze_vars_in_cols -#' -NULL - -#' @describeIn analyze_vars_in_cols Layout creating -#' function which can be used for creating summary tables in columns, primarily used for PK data sets. +#' Layout-creating function which can be used for creating column-wise summary tables, primarily +#' used for PK data sets. This function is a wrapper for [rtables::analyze_colvars()]. #' #' @inheritParams argument_convention #' @inheritParams rtables::analyze_colvars #' -#' @seealso [summarize_vars], [`rtables::analyze_colvars()`]. +#' @return +#' A layout object suitable for passing to further layouting functions, or to [rtables::build_table()]. +#' Adding this function to an `rtable` layout will summarize the given variables, arrange the output +#' in columns, and add it to the table layout. +#' +#' @seealso [summarize_vars], [rtables::analyze_colvars()]. #' -#' @export #' @examples #' library(dplyr) #' @@ -77,6 +74,8 @@ NULL #' ) #' result <- build_table(lyt, df = adpp) #' result +#' +#' @export analyze_vars_in_cols <- function(lyt, vars, ..., diff --git a/R/argument_convention.R b/R/argument_convention.R index 31e4b4109b..eb1a4e12f4 100644 --- a/R/argument_convention.R +++ b/R/argument_convention.R @@ -3,12 +3,6 @@ #' The documentation to this function lists all the arguments in `tern` #' that are used repeatedly to express an analysis. #' -#' @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 -#' single reference point to import the `roxygen` argument description with: -#' `@inheritParams argument_convention` -#' #' @param ... additional arguments for the lower level functions. #' @param .df_row (`data.frame`)\cr data frame across all of the columns for the given row split. #' @param .in_ref_col (`logical`)\cr `TRUE` when working with the reference level, `FALSE` otherwise. @@ -61,7 +55,12 @@ #' @param var (`string`)\cr single variable name for the primary analysis variable. #' @param x (`numeric`)\cr vector of numbers we want to analyze. #' -#' @name argument_convention -#' @keywords internal +#' @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 +#' single reference point to import the `roxygen` argument description with: +#' `@inheritParams argument_convention` #' +#' @keywords internal +#' @name argument_convention NULL diff --git a/R/combination_function.R b/R/combination_function.R index 8bce22e499..a911affa8d 100644 --- a/R/combination_function.R +++ b/R/combination_function.R @@ -9,6 +9,8 @@ #' @param e2 (`CombinationFunction`)\cr right hand side of logical operator. #' @param x (`CombinationFunction`)\cr the function which should be negated. #' +#' @return Returns a logical value indicating whether the left hand side of the equation equals the right hand side. +#' #' @exportClass CombinationFunction #' @export CombinationFunction #' diff --git a/R/compare_variables.R b/R/compare_variables.R index cb2238122e..c3197a75bc 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -1,25 +1,35 @@ -#' @include summarize_variables.R -NULL - #' Compare Variables Between Groups #' #' @description `r lifecycle::badge("stable")` #' -#' We use the new S3 generic function [s_compare()] to implement comparisons for -#' different `x` objects. This is used as Statistics Function in combination -#' with the new Analyze Function [compare_vars()]. +#' Comparison with a reference group for different `x` objects. #' -#' @seealso Relevant constructor function [create_afun_compare()]. +#' @inheritParams argument_convention #' -#' @name compare_variables +#' @note +#' * For factor variables, `denom` for factor proportions can only be `n` since the purpose is to compare proportions +#' between columns, therefore a row-based proportion would not make sense. Proportion based on `N_col` would +#' be difficult since we use counts for the chi-squared test statistic, therefore missing values should be accounted +#' for as explicit factor levels. +#' * For character variables, automatic conversion to factor does not guarantee that the table +#' will be generated correctly. In particular for sparse tables this very likely can fail. +#' Therefore it is always better to manually convert character variables to factors during pre-processing. +#' * For `compare_vars()`, the column split must define a reference group via `ref_group` so that the comparison +#' is well defined. +#' * When factor variables contains `NA`, it is expected that `NA` values have been conveyed to `na_level` +#' appropriately beforehand via [df_explicit_na()]. +#' +#' @seealso Relevant constructor function [create_afun_compare()], and [s_summary()] which is used internally +#' to compute a summary within `s_compare()`. #' +#' @name compare_variables +#' @include summarize_variables.R NULL -#' @inheritParams argument_convention -#' @describeIn compare_variables `s_compare` is a S3 generic function to produce -#' an object description and comparison versus the reference column in the form -#' of p-values. -#' @seealso [s_summary()] which is used internally for the summary part per column. +#' @describeIn compare_variables S3 generic function to produce a comparison summary. +#' +#' @return +#' * `s_compare()` returns output of [s_summary()] and comparisons versus the reference group in the form of p-values. #' #' @export #' @@ -30,11 +40,8 @@ s_compare <- function(x, UseMethod("s_compare", x) } -#' @describeIn compare_variables Method for numeric class. This uses the standard t-test +#' @describeIn compare_variables Method for `numeric` class. This uses the standard t-test #' to calculate the p-value. -#' @return If `x` is of class `numeric`, returns a list with named items: -#' - all items from [s_summary.numeric()]. -#' - `pval`: the p-value. #' @method s_compare numeric #' #' @export @@ -69,17 +76,10 @@ s_compare.numeric <- function(x, y } -#' @describeIn compare_variables Method for factor class. This uses the chi-squared test -#' to calculate the p-value. Note that the `denom` for factor proportions can only be `n` here -#' since the usage is for comparing proportions between columns. -#' Therefore a row-based proportion would not make sense. Also proportion based on `N_col` would -#' be difficult since for the chi-squared test statistic we use the counts. Therefore -#' missing values should be accounted for explicitly as factor levels. +#' @describeIn compare_variables Method for `factor` class. This uses the chi-squared test +#' to calculate the p-value. #' @param denom (`string`)\cr choice of denominator for factor proportions, #' can only be `n` (number of values in this row and column intersection). -#' @return If `x` is of class `factor` or converted from `character`, returns a list with named items: -#' - all items from [s_summary.factor()]. -#' - `pval`: the p-value. #' @method s_compare factor #' #' @export @@ -135,14 +135,10 @@ s_compare.factor <- function(x, y } -#' @describeIn compare_variables Method for character class. This makes an automatic -#' conversion to factor (with a warning) and then forwards to the method for factors. -#' @param verbose defaults to `TRUE`. It prints out warnings and messages. It is mainly used -#' to print out information about factor casting. -#' @note Automatic conversion of character to factor does not guarantee that the table -#' can be generated correctly. In particular for sparse tables this very likely can fail. -#' It is therefore better to always pre-process the dataset such that factors are manually -#' created from character variables before passing the dataset to [rtables::build_table()]. +#' @describeIn compare_variables Method for `character` class. This makes an automatic +#' conversion to `factor` (with a warning) and then forwards to the method for factors. +#' @param verbose (`logical`)\cr Whether warnings and messages should be printed. Mainly used +#' to print out information about factor casting. Defaults to `TRUE`. #' @method s_compare character #' #' @examples @@ -188,11 +184,8 @@ s_compare.character <- function(x, ) } -#' @describeIn compare_variables Method for logical class. A chi-squared test +#' @describeIn compare_variables Method for `logical` class. A chi-squared test #' is used. If missing values are not removed, then they are counted as `FALSE`. -#' @return If `x` is of class `logical`, returns a list with named items: -#' - all items from [s_summary.logical()]. -#' - `pval`: the p-value. #' @method s_compare logical #' #' @export @@ -245,9 +238,11 @@ s_compare.logical <- function(x, y } -#' @describeIn compare_variables S3 generic Formatted Analysis function to produce -#' an object description and comparison versus the reference column in the form -#' of p-values. It is used as `afun` in [rtables::analyze()]. +#' @describeIn compare_variables Formatted analysis function which is used as `afun` +#' in `compare_vars()`. +#' +#' @return +#' * `a_compare()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @export #' @@ -259,7 +254,7 @@ a_compare <- function(x, UseMethod("a_compare", x) } -#' @describeIn compare_variables Formatted Analysis function method for `numeric`. +#' @describeIn compare_variables Formatted analysis function method for `numeric` class. #' @export #' #' @examples @@ -292,7 +287,7 @@ a_compare.numeric <- make_afun( pval = "p-value (chi-squared test)" ) -#' @describeIn compare_variables Formatted Analysis function method for `factor`. +#' @describeIn compare_variables Formatted analysis function method for `factor` class. #' @export #' #' @examples @@ -313,7 +308,7 @@ a_compare.factor <- make_afun( .null_ref_cells = FALSE ) -#' @describeIn compare_variables Formatted Analysis function method for `character`. +#' @describeIn compare_variables Formatted analysis function method for `character` class. #' @export #' #' @examples @@ -332,7 +327,7 @@ a_compare.character <- make_afun( .null_ref_cells = FALSE ) -#' @describeIn compare_variables Formatted Analysis function method for `logical`. +#' @describeIn compare_variables Formatted analysis function method for `logical` class. #' @export #' #' @examples @@ -352,8 +347,13 @@ a_compare.logical <- make_afun( #' Constructor Function for [compare_vars()] #' -#' @description `r lifecycle::badge("stable")` Constructor function which creates a combined Formatted -#' Analysis function for use in layout creating functions [compare_vars()]. +#' @description `r lifecycle::badge("stable")` +#' +#' Constructor function which creates a combined formatted analysis function. +#' +#' @inheritParams argument_convention +#' +#' @return Combined formatted analysis function for use in [compare_vars()]. #' #' @note Since [a_compare()] is generic and we want customization of the formatting arguments #' via [rtables::make_afun()], we need to create another temporary generic function, with @@ -361,9 +361,9 @@ a_compare.logical <- make_afun( #' we need to wrap them in a combined `afun`. Since this is required by two layout creating #' functions (and possibly others in the future), we provide a constructor that does this: #' [create_afun_compare()]. +#' #' @export -#' @inheritParams argument_convention -#' @seealso [compare_variables] +#' @seealso [compare_vars()] #' #' @examples #' # `create_afun_compare()` to create combined `afun` @@ -460,17 +460,16 @@ create_afun_compare <- function(.stats = NULL, } } -#' @describeIn compare_variables Analyze Function to add a comparison of variables to -#' `rtables` pipelines. The column split needs to have the reference group defined -#' via `ref_group` so that the comparison is well defined. -#' The ellipsis (`...`) conveys arguments to [s_compare()]. -#' When factor variables contains `NA`, it is expected that `NA` -#' have been conveyed to `na_level` appropriately beforehand with -#' [df_explicit_na()]. +#' @describeIn compare_variables Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' -#' @inheritParams argument_convention #' @param ... arguments passed to `s_compare()`. #' +#' @return +#' * `compare_vars()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_compare()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/control_incidence_rate.R b/R/control_incidence_rate.R index 5c1891df41..33490d9ea0 100644 --- a/R/control_incidence_rate.R +++ b/R/control_incidence_rate.R @@ -11,7 +11,9 @@ #' @param time_unit_output (`numeric`)\cr time unit for desired output (in person-years). #' @param conf_type (`string`)\cr `normal` (default), `normal_log`, `exact`, or `byar` #' for confidence interval type. -#' @return A list of components with the same name as the arguments. +#' +#' @return A list of components with the same names as the arguments. +#' #' @export #' @examples #' control_incidence_rate(0.9, "exact", "month", 100) diff --git a/R/control_logistic.R b/R/control_logistic.R index 60d23cb562..8e792f23fe 100644 --- a/R/control_logistic.R +++ b/R/control_logistic.R @@ -11,7 +11,9 @@ #' levels. By default this is just `"response"` such that the original response variable is used #' and not modified further. #' @inheritParams argument_convention +#' #' @return A list of components with the same names as the arguments. +#' #' @export #' @examples #' # Standard options. diff --git a/R/control_survival.R b/R/control_survival.R index 7283fb7ff3..24d7ef472c 100644 --- a/R/control_survival.R +++ b/R/control_survival.R @@ -10,6 +10,7 @@ #' @param ties (`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 [survival::coxph()] #' @inheritParams argument_convention +#' #' @return A list of components with the same names as the arguments #' #' @export @@ -34,6 +35,7 @@ control_coxph <- function(pval_method = c("log-rank", "wald", "likelihood"), #' @param 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. #' @param quantiles (`numeric`)\cr of length two to specify the quantiles of survival time. +#' #' @return A list of components with the same names as the arguments #' #' @export @@ -56,6 +58,7 @@ control_surv_time <- function(conf_level = 0.95, #' #' @inheritParams argument_convention #' @inheritParams control_surv_time +#' #' @return A list of components with the same names as the arguments #' #' @export diff --git a/R/count_cumulative.R b/R/count_cumulative.R index ccb22309bd..5adf025226 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -5,7 +5,7 @@ #' 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. #' -#' @seealso Relevant helper function [h_count_cumulative()], and descriptive function [d_count_cumulative()] +#' @seealso Relevant helper function [h_count_cumulative()], and descriptive function [d_count_cumulative()]. #' #' @name count_cumulative NULL @@ -22,13 +22,12 @@ NULL #' @param include_eq (`logical`)\cr whether to include value equal to the `threshold` in #' count, default is `TRUE`. #' @param .N_col (`count`)\cr denominator for fraction calculation. +#' #' @return A named vector with items: -#' \describe{ -#' \item{count}{the count of values less than, less or equal to, greater than, or greater or equal to a threshold +#' * `count`: the count of values less than, less or equal to, greater than, or greater or equal to a threshold #' of user specification. -#' } -#' \item{fraction}{the fraction of the count.} -#' } +#' * `fraction`: the fraction of the count. +#' #' @seealso [count_cumulative] #' #' @export @@ -73,11 +72,11 @@ h_count_cumulative <- function(x, #' #' @description `r lifecycle::badge("stable")` #' -#' This is a helper function that describes analysis in [s_count_cumulative()]. +#' This is a helper function that describes the analysis in [s_count_cumulative()]. #' #' @inheritParams h_count_cumulative -#' @return a descriptive `string`. -#' @seealso [s_count_cumulative()] +#' +#' @return Labels for [s_count_cumulative()]. #' #' @export d_count_cumulative <- function(threshold, lower_tail, include_eq) { @@ -87,12 +86,14 @@ d_count_cumulative <- function(threshold, lower_tail, include_eq) { paste0(lg, eq, " ", threshold) } -#' @describeIn count_cumulative Statistics function that produces a named lists given a numeric vector of thresholds. +#' @describeIn count_cumulative Statistics function that produces a named list given a numeric vector of thresholds. #' #' @inheritParams h_count_cumulative #' @param thresholds (`numeric`)\cr vector of cutoff value for the counts. -#' @return A named list of `count_fraction`s: a list with each `thresholds` value as a component, each component -#' contains a vector for the count and fraction. +#' +#' @return +#' * `s_count_cumulative()` returns a named list of `count_fraction`s: a list with each `thresholds` value as a +#' component, each component containing a vector for the count and fraction. #' #' @examples #' # Internal function - s_count_cumulative @@ -123,10 +124,11 @@ s_count_cumulative <- function(x, list(count_fraction = count_fraction_list) } -#' @describeIn count_cumulative Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_cumulative Formatted analysis function which is used as `afun` +#' in `count_cumulative()`. #' -#' @return [a_count_cumulative()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @return +#' * `a_count_cumulative()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_cumulative @@ -143,12 +145,16 @@ a_count_cumulative <- make_afun( .formats = c(count_fraction = format_count_fraction) ) -#' @describeIn count_cumulative Layout creating function which can be be used for creating -#' summary tables for cumulative counts of a variable. The ellipsis (`...`) conveys -#' arguments to `s_count_cumulative()`, for instance `lower_tail = FALSE` if upper tail -#' should be accounted for. +#' @describeIn count_cumulative Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention +#' +#' @return +#' * `count_cumulative()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_cumulative()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/count_missed_doses.R b/R/count_missed_doses.R index 70b2d31fc1..d6208d4550 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -8,11 +8,13 @@ #' @seealso Relevant description function [d_count_missed_doses()]. #' #' @name count_missed_doses -#' NULL #' @describeIn count_missed_doses Statistics function to count non-missing values. -#' @return [s_count_nonmissing()] returns the statistic `n` which is the count of non-missing values in `x`. +#' +#' @return +#' * `s_count_nonmissing()` returns the statistic `n` which is the count of non-missing values in `x`. +#' #' @examples #' set.seed(1) #' x <- c(sample(1:10, 10), NA) @@ -40,12 +42,12 @@ d_count_missed_doses <- function(thresholds) { paste0("At least ", thresholds, " missed dose", ifelse(thresholds > 1, "s", "")) } -#' @describeIn count_missed_doses Statistics function to count patients with missed doses when `x` -#' is the vector of number of missed doses with one value for each patient. +#' @describeIn count_missed_doses Statistics function to count patients with missed doses. #' @inheritParams argument_convention #' @param thresholds (vector of `count`)\cr number of missed doses the patients at least had. -#' @return [s_count_missed_doses()] returns the statistics `n` and -#' `count_fraction` with one element for each threshold. +#' +#' @return +#' * `s_count_missed_doses()` returns the statistics `n` and `count_fraction` with one element for each threshold. #' #' @examples #' # Internal function - s_count_missed_doses @@ -72,7 +74,11 @@ s_count_missed_doses <- function(x, c(n_stat, stat) } -#' @describeIn count_missed_doses Formatted Analysis function to count non-missing values. +#' @describeIn count_missed_doses Formatted analysis function which is used as `afun` +#' in `count_missed_doses()`. +#' +#' @return +#' * `a_count_missed_doses()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_count_missed_doses @@ -89,11 +95,15 @@ a_count_missed_doses <- make_afun( .formats = c(n = "xx", count_fraction = format_count_fraction) ) -#' @describeIn count_missed_doses Layout creating function which can be be used for creating -#' summary tables for summarizing missed doses given user-specified `thresholds`. This is -#' an additional layer on top of `count_cumulative` specifically for missed doses. -#' @inheritParams argument_convention +#' @describeIn count_missed_doses Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @inheritParams s_count_cumulative +#' +#' @return +#' * `count_missed_doses()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_missed_doses()` to the table layout. +#' #' @export #' @examples #' library(dplyr) diff --git a/R/count_occurrences.R b/R/count_occurrences.R index 74ae8ff8b5..d64300e169 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -1,18 +1,20 @@ #' Occurrence Counts #' +#' @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. Note that by default occurrences which don't appear in a given row split -#' are dropped from the table and the occurrences in the table are sorted alphabetically per row split. -#' Therefore the corresponding layout needs to use `split_fun = drop_split_levels` in the `split_rows_by` -#' calls. Use `drop = FALSE` if you would like to show all occurrences. +#' counted only once. #' -#' @description `r lifecycle::badge("stable")` #' @inheritParams argument_convention #' -#' @name count_occurrences +#' @note By default, occurrences which don't appear in a given row split are dropped from the table and +#' the occurrences in the table are sorted alphabetically per row split. Therefore, the corresponding layout +#' needs to use `split_fun = drop_split_levels` in the `split_rows_by` calls. Use `drop = FALSE` if you would +#' like to show all occurrences. #' +#' @name count_occurrences NULL #' @describeIn count_occurrences Statistics function which counts number of patients that report an @@ -21,12 +23,12 @@ NULL #' @param denom (`string`)\cr choice of denominator for patient proportions. Can be: #' - `N_col`: total number of patients in this column across rows #' - `n`: number of patients with any occurrences -#' @returns A list with: -#' \describe{ -#' \item{count}{list of counts with one element per occurrence.} -#' \item{count_fraction}{list of counts and fractions with one element per occurrence.} -#' \item{fraction}{list of numerators and denominators with one element per occurrence.} -#' } +#' +#' @return +#' * `s_count_occurrences()` returns a list with: +#' * `count`: list of counts with one element per occurrence. +#' * `count_fraction`: list of counts and fractions with one element per occurrence. +#' * `fraction`: list of numerators and denominators with one element per occurrence. #' #' @examples #' df <- data.frame( @@ -102,10 +104,13 @@ s_count_occurrences <- function(df, ) } -#' @describeIn count_occurrences Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_occurrences Formatted analysis function which is used as `afun` +#' in `count_occurrences()`. #' @export #' +#' @return +#' * `a_count_occurrences()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @examples #' # We need to ungroup `count_fraction` first so that the `rtables` formatting #' # function `format_count_fraction()` can be applied correctly. @@ -117,17 +122,23 @@ s_count_occurrences <- function(df, #' .var = "MHDECOD", #' id = "USUBJID" #' ) +#' a_count_occurrences <- make_afun( s_count_occurrences, .formats = c(count = "xx", count_fraction = format_count_fraction_fixed_dp, fraction = format_fraction_fixed_dp) ) -#' @describeIn count_occurrences Analyze Function that counts occurrences as part of `rtables` layouts. +#' @describeIn count_occurrences Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `count_occurrences()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_occurrences()` to the table layout. #' #' @export #' #' @examples -#' #' library(dplyr) #' df <- data.frame( #' USUBJID = as.character(c( diff --git a/R/count_occurrences_by_grade.R b/R/count_occurrences_by_grade.R index c2684da80f..7a3af8367d 100644 --- a/R/count_occurrences_by_grade.R +++ b/R/count_occurrences_by_grade.R @@ -9,12 +9,11 @@ #' @inheritParams argument_convention #' @param grade_groups (named `list` of `character`)\cr containing groupings of grades. #' @param remove_single (`logical`)\cr `TRUE` to not include the elements of one-element grade groups -#' in the the output list; in this case only the grade groups names will be included in the output. +#' in the the output list; in this case only the grade groups names will be included in the output. #' #' @seealso Relevant helper function [h_append_grade_groups()]. #' #' @name count_occurrences_by_grade -#' NULL #' Helper function for [s_count_occurrences_by_grade()] @@ -30,6 +29,8 @@ NULL #' @param refs (named `list` of `numeric`)\cr where each name corresponds to a reference grade level #' and each entry represents a count. #' +#' @return Formatted list of grade groupings. +#' #' @examples #' h_append_grade_groups( #' list( @@ -109,9 +110,12 @@ h_append_grade_groups <- function(grade_groups, refs, remove_single = TRUE) { result } -#' @describeIn count_occurrences_by_grade Statistics function which given occurrence data counts the -#' number of patients by highest grade. Returns a list of counts and fractions with one element -#' per grade level or grade level grouping. +#' @describeIn count_occurrences_by_grade Statistics function which counts the +#' number of patients by highest grade. +#' +#' @return +#' * `s_count_occurrences_by_grade()` returns a list of counts and fractions with one element per grade level or +#' grade level grouping. #' #' @examples #' library(dplyr) @@ -190,8 +194,12 @@ s_count_occurrences_by_grade <- function(df, ) } -#' @describeIn count_occurrences_by_grade Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_occurrences_by_grade Formatted analysis function which is used as `afun` +#' in `count_occurrences_by_grade()`. +#' +#' @return +#' * `a_count_occurrences_by_grade()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @export #' #' @examples @@ -205,18 +213,24 @@ s_count_occurrences_by_grade <- function(df, #' id = "USUBJID", #' grade_groups = list("ANY" = levels(df$AETOXGR)) #' ) +#' a_count_occurrences_by_grade <- make_afun( s_count_occurrences_by_grade, .formats = c("count_fraction" = format_count_fraction_fixed_dp) ) -#' @describeIn count_occurrences_by_grade Layout creating function which can be used for creating tables, -#' which can take statistics function arguments and additional format arguments (see below). +#' @describeIn count_occurrences_by_grade Layout-creating function which can take statistics function +#' arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @param var_labels (`character`)\cr labels to show in the result table. +#' +#' @return +#' * `count_occurrences_by_grade()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_occurrences_by_grade()` to the table layout. +#' #' @export #' @examples -#' #' # Layout creating function with custom format. #' basic_table() %>% #' split_cols_by("ARM") %>% @@ -242,6 +256,7 @@ a_count_occurrences_by_grade <- make_afun( #' grade_groups = grade_groups #' ) %>% #' build_table(df, alt_counts_df = df_adsl) +#' count_occurrences_by_grade <- function(lyt, var, var_labels = var, @@ -271,11 +286,16 @@ count_occurrences_by_grade <- function(lyt, ) } -#' @describeIn count_occurrences_by_grade Layout creating function which adds content rows using the -#' statistics function and additional format arguments (see below). +#' @describeIn count_occurrences_by_grade Layout-creating function which can take content function arguments +#' and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()]. +#' +#' @return +#' * `summarize_occurrences_by_grade()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted content rows +#' containing the statistics from `s_count_occurrences_by_grade()` to the table layout. +#' #' @export #' @examples -#' #' # Layout creating function with custom format. #' basic_table() %>% #' add_colcounts() %>% diff --git a/R/count_patients_events_in_cols.R b/R/count_patients_events_in_cols.R index ab7038234a..615a7fdaef 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -6,11 +6,10 @@ #' when a column table layout is required. #' #' @name count_patients_events_in_cols -#' NULL -#' @describeIn count_patients_events_in_cols Statistics function which counts numbers of patients and multiple events -#' defined by filters. +#' @describeIn count_patients_events_in_cols Statistics function which counts numbers of patients and multiple +#' events defined by filters. Used as analysis function `afun` in `summarize_patients_events_in_cols()`. #' #' @inheritParams argument_convention #' @param filters_list (named `list` of `character`)\cr each element in this list describes one @@ -21,7 +20,8 @@ NULL #' @param custom_label (`string` or `NULL`)\cr if provided and `labelstr` is empty then this will #' be used as label. #' -#' @return [s_count_patients_and_multiple_events()] returns a list with the statistics: +#' @return +#' * `s_count_patients_and_multiple_events()` returns a list with the statistics: #' - `unique`: number of unique patients in `df`. #' - `all`: number of rows in `df`. #' - one element with the same name as in `filters_list`: number of rows in `df`, @@ -106,12 +106,18 @@ s_count_patients_and_multiple_events <- function(df, # nolint y } -#' @describeIn count_patients_events_in_cols Layout creating function which adds the count -#' statistics of patients and events in the column layout as content rows. +#' @describeIn count_patients_events_in_cols Layout-creating function which can take statistics function +#' arguments and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()]. #' #' @inheritParams argument_convention #' @param col_split (`flag`)\cr whether the columns should be split. #' Set to `FALSE` when the required column split has been done already earlier in the layout pipe. +#' +#' @return +#' * `summarize_patients_events_in_cols()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted content rows +#' containing the statistics from `s_count_patients_and_multiple_events()` to the table layout. +#' #' @export #' @examples #' diff --git a/R/count_patients_with_event.R b/R/count_patients_with_event.R index 133e64e8b7..8f459e23ff 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -1,16 +1,15 @@ #' Count the Number of Patients with a Particular Event #' +#' @description `r lifecycle::badge("stable")` +#' #' The primary analysis variable `.var` denotes the unique patient identifier. #' #' @name count_patients_with_event -#' -#' @description `r lifecycle::badge("stable")` NULL -#' @describeIn count_patients_with_event Statistics Function that returns the number and the fraction -#' of unique identifiers with a particular type of event, e.g. the number and the fraction of patients who -#' had treatment-emergent adverse events. Note that the user can define a new data column containing -#' the event of interest. +#' @describeIn count_patients_with_event Statistics function which counts the number of patients for which +#' the defined event has occurred. +#' #' @inheritParams argument_convention #' @param .var (`character`)\cr name of the column that contains the unique identifier. #' @param filters (`character`)\cr a character vector specifying the column names and flag variables @@ -20,8 +19,8 @@ NULL #' Note that only equality is being accepted as condition. #' @inheritParams summarize_variables #' -#' @return [s_count_patients_with_event()] returns the count and fraction of patients with the -#' defined event. +#' @return +#' * `s_count_patients_with_event()` returns the count and fraction of unique identifiers with the defined event. #' #' @export #' @@ -75,8 +74,12 @@ s_count_patients_with_event <- function(df, result } -#' @describeIn count_patients_with_event Formatted Analysis function which can be further -#' customized by calling [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_patients_with_event Formatted analysis function which is used as `afun` +#' in `count_patients_with_event()`. +#' +#' @return +#' * `a_count_patients_with_event()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @export #' #' @examples @@ -94,11 +97,16 @@ a_count_patients_with_event <- make_afun( .formats = c(count_fraction = format_count_fraction_fixed_dp) ) -#' @describeIn count_patients_with_event Analyze Function which adds the count statistics -#' to the input layout. Note that additional formatting arguments can be used here. +#' @describeIn count_patients_with_event Layout-creating function which can take statistics function +#' arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' +#' @return +#' * `count_patients_with_event()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_patients_with_event()` to the table layout. +#' #' @export #' @examples #' # `count_patients_with_event()` @@ -158,14 +166,19 @@ count_patients_with_event <- function(lyt, ) } -#' @describeIn count_patients_with_event Statistics function that returns the number and the fraction -#' of unique identifiers with each particular flag. Returns a list of totals, counts, counts and -#' fractions with one element per flag. +#' @describeIn count_patients_with_event Statistics function which counts the number of patients for which +#' a particular flag variable is `TRUE`. +#' #' @inheritParams argument_convention #' @param .var (`character`)\cr name of the column that contains the unique identifier. #' @param flag_variables (`character`)\cr a character vector specifying the names of `logical` #' variables from analysis dataset used for counting the number of unique identifiers. #' @inheritParams summarize_variables +#' +#' @return +#' * `s_count_patients_with_flags()` returns the count and the fraction of unique identifiers with each particular +#' flag as a list of statistics `n`, `count`, `count_fraction`, and `n_blq`, with one element per flag. +#' #' @export #' #' @examples @@ -226,8 +239,12 @@ s_count_patients_with_flags <- function(df, result } -#' @describeIn count_patients_with_event Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_patients_with_event Formatted analysis function which is used as `afun` +#' in `count_patients_with_flags()`. +#' +#' @return +#' * `a_count_patients_with_flags()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @export #' #' @examples @@ -252,11 +269,16 @@ a_count_patients_with_flags <- make_afun( .formats = c("count_fraction" = format_count_fraction_fixed_dp) ) -#' @describeIn count_patients_with_event Analyze Function which is a modified version of [count_patients_with_event()]. -#' Adds the count statistics to the input layout for multiple flag variables at once. +#' @describeIn count_patients_with_event Layout-creating function which can take statistics function +#' arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' +#' @return +#' * `count_patients_with_flags()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_patients_with_flags()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/count_values.R b/R/count_values.R index 72e04ef348..810f2580d8 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -4,15 +4,22 @@ #' #' We can count the occurrence of specific values in a variable of interest. #' -#' @name count_values_funs +#' @note +#' * For `factor` variables, `s_count_values` checks whether `values` are all included in the levels of `x` +#' and fails otherwise. +#' * For `count_values()`, variable labels are shown when there is more than one element in `vars`, +#' otherwise they are hidden. #' +#' @name count_values_funs NULL -#' @describeIn count_values_funs Statistics Function which is a generic function to count values. +#' @describeIn count_values_funs S3 generic function to count values. #' @inheritParams argument_convention #' @inheritParams s_summary.logical #' @param values (`character`)\cr specific values that should be counted. -#' @return See [s_summary.logical()] for the returned statistics, as this is used inside. +#' +#' @return +#' * `s_count_values()` returns output of [s_summary()] for specified values of a non-numeric variable. #' #' @export #' @@ -25,7 +32,7 @@ s_count_values <- function(x, UseMethod("s_count_values", x) } -#' @describeIn count_values_funs Method for `character` vectors `x`. +#' @describeIn count_values_funs Method for `character` class. #' @method s_count_values character #' #' @export @@ -49,9 +56,8 @@ s_count_values.character <- function(x, s_summary(is_in_values, ...) } -#' @describeIn count_values_funs method for `factor` vectors `x`. This checks whether `values` are all -#' included in the levels of `x` and fails otherwise. It then proceeds by converting to `character` -#' and calling `s_count_values.character`. +#' @describeIn count_values_funs Method for `factor` class. This makes an automatic +#' conversion to `character` and then forwards to the method for characters. #' @method s_count_values factor #' #' @export @@ -65,7 +71,7 @@ s_count_values.factor <- function(x, s_count_values(as.character(x), values = as.character(values), ...) } -#' @describeIn count_values_funs method for `logical` vectors `x`. +#' @describeIn count_values_funs Method for `logical` class. #' @method s_count_values logical #' #' @export @@ -79,8 +85,12 @@ s_count_values.logical <- function(x, values = TRUE, ...) { } -#' @describeIn count_values_funs Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn count_values_funs Formatted analysis function which is used as `afun` +#' in `count_values()`. +#' +#' @return +#' * `a_count_values()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @export #' #' @examples @@ -91,13 +101,14 @@ a_count_values <- make_afun( .formats = c(count_fraction = "xx (xx.xx%)", count = "xx") ) -#' @describeIn count_values_funs Analyze Function which adds the counting analysis to -#' the input layout. Note that additional formatting arguments can be used -#' here. +#' @describeIn count_values_funs Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @inheritParams argument_convention #' -#' @note Variable labels are shown when there is more than one element in `vars`, otherwise they -#' are hidden. +#' @return +#' * `count_values()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_count_values()` to the table layout. #' #' @export #' diff --git a/R/cox_regression.R b/R/cox_regression.R index 39244001f5..ac2558031d 100644 --- a/R/cox_regression.R +++ b/R/cox_regression.R @@ -16,7 +16,7 @@ #' `efron` and `breslow`, see [survival::coxph()]. #' Note: there is no equivalent of SAS `EXACT` method in R. #' -#' @return A `list` of item corresponding to the arguments. +#' @return A `list` of items with names corresponding to the arguments. #' #' @examples #' control_coxreg() @@ -42,6 +42,14 @@ control_coxreg <- function(pval_method = c("wald", "likelihood"), #' #' @description `r lifecycle::badge("stable")` #' +#' @return [tidy()] returns: +#' * For `summary.coxph` objects, a `data.frame` with columns: `Pr(>|z|)`, `exp(coef)`, `exp(-coef)`, `lower .95`, +#' `upper .95`, `level`, and `n`. +#' * For `coxreg.univar` objects, a `data.frame` with columns: `effect`, `term`, `term_label`, `level`, `n`, `hr`, +#' `lcl`, `ucl`, `pval`, and `ci`. +#' * For `coxreg.multivar` objects, a `data.frame` with columns: `term`, `pval`, `term_label`, `hr`, `lcl`, `ucl`, +#' `level`, and `ci`. +#' #' @seealso [cox_regression] #' #' @name tidy_coxreg @@ -52,6 +60,7 @@ NULL #' Tidy the [survival::coxph()] results into a `data.frame` to extract model results. #' #' @inheritParams argument_convention +#' #' @method tidy summary.coxph #' @export #' @@ -97,7 +106,7 @@ tidy.summary.coxph <- function(x, # nolint ret } -#' @describeIn tidy_coxreg Custom tidy method for a Univariate Cox Regression +#' @describeIn tidy_coxreg Custom tidy method for a univariate Cox regression. #' #' Tidy up the result of a Cox regression model fitted by [`fit_coxreg_univar()`]. #' @@ -186,7 +195,7 @@ tidy.coxreg.univar <- function(x, # nolint result } -#' @describeIn tidy_coxreg Custom tidy method for a Multi-variable Cox Regression +#' @describeIn tidy_coxreg Custom tidy method for a multivariate Cox regression. #' #' Tidy up the result of a Cox regression model fitted by [`fit_coxreg_multivar()`]. #' @@ -288,15 +297,16 @@ NULL #' effect should be estimated. #' @param control (`list`)\cr a list of parameters as returned by the #' helper function [control_coxreg()]. -#' @return The function `fit_coxreg_univar` returns a `coxreg.univar` class object which is a named list -#' with 5 elements: -#' \describe{ -#' \item{mod}{Cox regression models fitted by [survival::coxph()].} -#' \item{data}{The original data frame input.} -#' \item{control}{The original control input.} -#' \item{vars}{The variables used in the model.} -#' \item{at}{Value of the covariate at which the effect should be estimated.} -#' } +#' +#' @return +#' * `fit_coxreg_univar()` returns a `coxreg.univar` class object which is a named `list` +#' with 5 elements: +#' * `mod`: Cox regression models fitted by [survival::coxph()]. +#' * `data`: The original data frame input. +#' * `control`: The original control input. +#' * `vars`: The variables used in the model. +#' * `at`: Value of the covariate at which the effect should be estimated. +#' #' @note When using `fit_coxreg_univar` there should be two study arms. #' #' @examples @@ -385,16 +395,15 @@ fit_coxreg_univar <- function(variables, ) } -#' @describeIn fit_coxreg Fit a multi-variable Cox regression model. +#' @describeIn fit_coxreg Fit a multivariate Cox regression model. #' -#' @return The function `fit_coxreg_multivar` returns a `coxreg.multivar` class object which is a named list -#' with 4 elements: -#' \describe{ -#' \item{mod}{Cox regression model fitted by [survival::coxph()].} -#' \item{data}{The original data frame input.} -#' \item{control}{The original control input.} -#' \item{vars}{The variables used in the model.} -#' } +#' @return +#' * `fit_coxreg_multivar()` returns a `coxreg.multivar` class object which is a named list +#' with 4 elements: +#' * `mod`: Cox regression model fitted by [survival::coxph()]. +#' * `data`: The original data frame input. +#' * `control`: The original control input. +#' * `vars`: The variables used in the model. #' #' @examples #' # fit_coxreg_multivar @@ -463,6 +472,8 @@ fit_coxreg_multivar <- function(variables, #' @param test_statistic (`string`)\cr the method used for estimation of p.values; #' `wald` (default) or `likelihood`. #' +#' @return Returns the output of [car::Anova()], with convergence message muffled. +#' #' @keywords internal muffled_car_anova <- function(mod, test_statistic) { tryCatch( diff --git a/R/cox_regression_inter.R b/R/cox_regression_inter.R index 064f4aa190..20dbfd6982 100644 --- a/R/cox_regression_inter.R +++ b/R/cox_regression_inter.R @@ -10,14 +10,10 @@ #' @param effect (`string`)\cr the name of the effect to be tested and estimated. #' @param covar (`string`)\cr the name of the covariate in the model. #' @param mod (`coxph`)\cr the Cox regression model. -#' @param label (`string`)\cr the label to be return as `term_label` -#' (see `return`). -#' @param control (`list`)\cr a list of controls as returned by -#' [control_coxreg()]. +#' @param label (`string`)\cr the label to be returned as `term_label`. +#' @param control (`list`)\cr a list of controls as returned by [control_coxreg()]. #' @param ... see methods. #' -#' @name cox_regression_inter -#' #' @examples #' library(survival) #' @@ -49,6 +45,15 @@ #' col = c("blue1", "blue2", "blue3", "blue4", "red1", "red2", "red3", "red4") #' ) #' +#' @name cox_regression_inter +NULL + +#' @describeIn cox_regression_inter S3 generic helper function to determine interaction effect. +#' +#' @return +#' * `h_coxreg_inter_effect()` returns a `data.frame` of covariate interaction effects consisting of the following +#' variables: `effect`, `term`, `term_label`, `level`, `n`, `hr`, `lcl`, `ucl`, `pval`, and `pval_inter`. +#' #' @export h_coxreg_inter_effect <- function(x, effect, @@ -61,8 +66,8 @@ h_coxreg_inter_effect <- function(x, } -#' @describeIn cox_regression_inter Estimate the interaction with a numerical -#' covariate +#' @describeIn cox_regression_inter Estimate the interaction with a `numeric` +#' covariate. #' #' @param at (`list`)\cr a list with items named after the covariate, every #' item is a vector of levels at which the interaction should be estimated. @@ -113,7 +118,7 @@ h_coxreg_inter_effect.numeric <- function(x, # nolint ) } -#' @describeIn cox_regression_inter Estimate the interaction with a factor +#' @describeIn cox_regression_inter Estimate the interaction with a `factor` #' covariate. #' #' @param data (`data.frame`)\cr the data frame on which the model was fit. @@ -149,9 +154,12 @@ h_coxreg_inter_effect.factor <- function(x, # nolint ) } -#' @describeIn cox_regression_inter a higher level function that returns -#' the test of the interaction test and the estimated values. If -#' no interaction, [h_coxreg_univar_extract()] is applied. +#' @describeIn cox_regression_inter A higher level function to get +#' the results of the interaction test and the estimated values. +#' +#' @return +#' * `h_coxreg_extract_interaction()` returns the result of an interaction test and the estimated values. If +#' no interaction, [h_coxreg_univar_extract()] is applied instead. #' #' @export #' @@ -207,7 +215,7 @@ h_coxreg_extract_interaction <- function(effect, } } -#' @describeIn cox_regression_inter hazard ratio estimation in interactions. +#' @describeIn cox_regression_inter Hazard ratio estimation in interactions. #' #' @inheritParams argument_convention #' @param variable,given (`string`)\cr the name of variables in interaction. We seek the estimation @@ -228,14 +236,13 @@ h_coxreg_extract_interaction <- function(effect, #' The interaction coefficient is deduced by b2 + b5 while the standard error #' is obtained as $sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$. #' -#' @return A list of matrix (one per level of variable) with rows corresponding to the combinations of -#' `variable` and `given`, with columns: -#' \describe{ -#' \item{coef_hat}{Estimation of the coefficient.} -#' \item{coef_se}{Standard error of the estimation.} -#' \item{hr}{Hazard ratio.} -#' \item{lcl, ucl}{Lower/upper confidence limit of the hazard ratio.} -#' } +#' @return +#' * `h_coxreg_inter_estimations()` returns a list of matrices (one per level of variable) with rows corresponding +#' to the combinations of `variable` and `given`, with columns: +#' * `coef_hat`: Estimation of the coefficient. +#' * `coef_se`: Standard error of the estimation. +#' * `hr`: Hazard ratio. +#' * `lcl, ucl`: Lower/upper confidence limit of the hazard ratio. #' #' @examples #' mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder) @@ -248,8 +255,10 @@ h_coxreg_extract_interaction <- function(effect, #' result #' #' @export -h_coxreg_inter_estimations <- function(variable, given, - lvl_var, lvl_given, +h_coxreg_inter_estimations <- function(variable, + given, + lvl_var, + lvl_given, mod, conf_level = 0.95) { var_lvl <- paste0(variable, lvl_var[-1]) # [-1]: reference level diff --git a/R/coxph.R b/R/coxph.R index e290647876..5287964fab 100644 --- a/R/coxph.R +++ b/R/coxph.R @@ -5,7 +5,9 @@ #' The special term `pairwise` indicate that the model should be fitted individually for #' every tested level in comparison to the reference level. #' -#' @param x the variable for which pairwise result is expected +#' @param x the variable for which pairwise result is expected. +#' +#' @return Variable "paired". #' #' @details Let's `ARM` being a factor with level A, B, C; let's be B the reference level, #' a model calling the formula including `pairwise(ARM)` will result in two models: @@ -24,7 +26,9 @@ pairwise <- function(x) { #' The special term `univariate` indicate that the model should be fitted individually for #' every variable included in univariate. #' -#' @param x A vector of variable name separated by comas. +#' @param x A vector of variable name separated by commas. +#' +#' @return When used within a model formula, produces univariate models for each variable provided. #' #' @details #' If provided alongside with pairwise specification, the model @@ -73,13 +77,12 @@ rht <- function(x) { #' as $1.96 * sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$ for a confidence level of 0.95. #' #' @return A list of matrix (one per level of variable) with rows corresponding to the combinations of -#' `variable` and `given`, with columns: -#' \describe{ -#' \item{coef_hat}{Estimation of the coefficient.} -#' \item{coef_se}{Standard error of the estimation.} -#' \item{hr}{Hazard ratio.} -#' \item{lcl, ucl}{Lower/upper confidence limit of the hazard ratio.} -#' } +#' `variable` and `given`, with columns: +#' * `coef_hat`: Estimation of the coefficient. +#' * `coef_se`: Standard error of the estimation. +#' * `hr`: Hazard ratio. +#' * `lcl, ucl`: Lower/upper confidence limit of the hazard ratio. +#' #' @seealso [s_cox_multivariate()]. #' #' @examples @@ -242,10 +245,11 @@ try_car_anova <- function(mod, #' more flexibility to get the effect p.values. #' #' @inheritParams t_coxreg -#' @noRd #' #' @return A list with items `mod` (results of [survival::coxph()]), -#' `msum` (result of `summary`) and `aov` (result of [car::Anova]). +#' `msum` (result of `summary`) and `aov` (result of [car::Anova]). +#' +#' @noRd fit_n_aov <- function(formula, data = data, conf_level = conf_level, @@ -343,6 +347,8 @@ check_increments <- function(increments, covariates) { #' @param ... Optional parameters passed to [survival::coxph()]. Can include `ties`, a character string specifying the #' method for tie handling, one of `exact` (default), `efron`, `breslow`. #' +#' @return A `list` with elements `mod`, `msum`, `aov`, and `coef_inter`. +#' #' @details The output is limited to single effect terms. Work in ongoing for estimation of interaction terms #' but is out of scope as defined by the Global Data Standards Repository #' (**`GDS_Standard_TLG_Specs_Tables_2.doc`**). diff --git a/R/d_pkparam.R b/R/d_pkparam.R index 7ba7c9336b..2ca63db5f7 100644 --- a/R/d_pkparam.R +++ b/R/d_pkparam.R @@ -2,7 +2,8 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' @return dataframe of PK parameters +#' @return `data.frame` of PK parameters +#' #' @export #' #' @examples diff --git a/R/decorate_grob.R b/R/decorate_grob.R index e14e0166b6..71edb5ff7f 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -26,16 +26,9 @@ #' The titles and footnotes will be ragged, i.e. each title will be wrapped #' individually. #' -#' \if{html}{ -#' The layout can be illustrated as follows: -#' -#' \figure{decorate_grob.png}{options: alt="decorate_grob layout"} -#' } -#' -#' @return a grid grob (\code{gTree}) +#' @return A grid grob (`gTree`). #' #' @export -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} #' #' @examples #' library(grid) @@ -238,7 +231,7 @@ decorate_grob <- function(grob, } #' @importFrom grid validDetails -#' @export +#' @noRd validDetails.decoratedGrob <- function(x) { # nolint checkmate::assert_character(x$titles) @@ -264,13 +257,13 @@ validDetails.decoratedGrob <- function(x) { # nolint } #' @importFrom grid widthDetails -#' @export +#' @noRd widthDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") } #' @importFrom grid heightDetails -#' @export +#' @noRd heightDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") } @@ -312,6 +305,8 @@ split_string <- function(text, width) { #' @param text character string #' @param width a unit object specifying max width of text #' +#' @return A text grob. +#' #' @details #' This code is taken from R Graphics by \code{Paul Murell}, 2nd edition #' @@ -399,7 +394,7 @@ split_text_grob <- function(text, } #' @importFrom grid validDetails -#' @export +#' @noRd validDetails.dynamicSplitText <- function(x) { # nolint checkmate::assert_character(x$text) checkmate::assert_true(grid::is.unit(x$width)) @@ -408,7 +403,7 @@ validDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid heightDetails -#' @export +#' @noRd heightDetails.dynamicSplitText <- function(x) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { attr(x$text, "fixed_text") @@ -419,13 +414,13 @@ heightDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid widthDetails -#' @export +#' @noRd widthDetails.dynamicSplitText <- function(x) { # nolint x$width } #' @importFrom grid drawDetails -#' @export +#' @noRd drawDetails.dynamicSplitText <- function(x, recording) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { attr(x$text, "fixed_text") @@ -448,10 +443,9 @@ drawDetails.dynamicSplitText <- function(x, recording) { # nolint #' @param npages number of pages in total #' @param ... passed on to \code{\link{decorate_grob}} #' -#' @return closure that increments the page number +#' @return Closure that increments the page number. #' #' @keywords internal -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} #' #' @examples #' # Internal function - decorate_grob_factory @@ -487,7 +481,7 @@ decorate_grob_factory <- function(npages, ...) { #' @param grobs a list of grid grobs #' @param ... arguments passed on to \code{\link{decorate_grob}} #' -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} +#' @return A decorated grob. #' #' @examples #' library(ggplot2) diff --git a/R/desctools_binom_diff.R b/R/desctools_binom_diff.R index 519b2c7e4e..021c50f8bb 100644 --- a/R/desctools_binom_diff.R +++ b/R/desctools_binom_diff.R @@ -8,14 +8,18 @@ #' (e.g. reference and treatment group). #' #' @name desctools_binom - NULL -#' Recycle list of parameters +#' Recycle List of Parameters +#' +#' This function recycles all supplied elements to the maximal dimension. +#' +#' @param ... (`any`)\cr Elements to recycle. #' -#' @describeIn desctools_binom This function recycles all supplied elements to the maximal dimension. +#' @return A `list`. #' #' @keywords internal +#' @noRd h_recycle <- function(...) { lst <- list(...) maxdim <- max(lengths(lst)) @@ -24,14 +28,12 @@ h_recycle <- function(...) { return(res) } -#' @describeIn desctools_binom Several Confidence Intervals for the difference between proportions. +#' @describeIn desctools_binom Several confidence intervals for the difference between proportions. #' -#' @return A named list of 3 values: -#' \describe{ -#' \item{est}{estimate of proportion difference.} -#' \item{lwrci}{estimate of lower end of the confidence interval.} -#' \item{upci}{estimate of upper end of the confidence interval.} -#' } +#' @return A `matrix` of 3 values: +#' * `est`: estimate of proportion difference. +#' * `lwr.ci`: estimate of lower end of the confidence interval. +#' * `upr.ci`: estimate of upper end of the confidence interval. #' #' @examples #' # Internal function - desctools_binom @@ -350,12 +352,10 @@ desctools_binom <- function(x1, n1, x2, n2, conf.level = 0.95, sides = c( # noli #' @param method (`character`)\cr method to use. Can be one out of: "wald", "wilson", "wilsoncc", "agresti-coull", #' "jeffreys", "modified wilson", "modified jeffreys", "clopper-pearson", "arcsine", "logit", "witting", "pratt", #' "midp", "lik", and "blaker". -#' @return A matrix with 3 columns containing: -#' \describe{ -#' \item{est}{estimate of proportion difference.} -#' \item{lwrci}{lower end of the confidence interval.} -#' \item{upci}{upper end of the confidence interval.} -#' } +#' @return A `matrix` with 3 columns containing: +#' * `est`: estimate of proportion difference. +#' * `lwr.ci`: lower end of the confidence interval. +#' * `upr.ci`: upper end of the confidence interval. #' #' @keywords internal desctools_binomci <- function(x, diff --git a/R/df_explicit_na.R b/R/df_explicit_na.R index 8ddd7fb512..d2805021b7 100644 --- a/R/df_explicit_na.R +++ b/R/df_explicit_na.R @@ -22,7 +22,7 @@ #' @param na_level (`string`)\cr used to replace all `NA` or empty #' values inside non-`omit_columns` columns. #' -#' @return The data frame with the desired changes made. +#' @return A `data.frame` with the chosen modifications applied. #' #' @export #' @seealso [sas_na()] and [explicit_na()] for other missing data helper functions. diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index f02e6258f8..67f4f08645 100644 --- a/R/estimate_multinomial_rsp.R +++ b/R/estimate_multinomial_rsp.R @@ -8,7 +8,6 @@ #' @seealso Relevant description function [d_onco_rsp_label()]. #' #' @name estimate_multinomial_rsp -#' NULL #' Description of Standard Oncology Response @@ -18,6 +17,9 @@ NULL #' Describe the oncology response in a standard way. #' #' @param x (`character`)\cr the standard oncology code to be described. +#' +#' @return Response labels. +#' #' @seealso [estimate_multinomial_rsp()] #' @export #' @@ -61,11 +63,13 @@ d_onco_rsp_label <- function(x) { # nolint } -#' @describeIn estimate_multinomial_rsp Statistics function which takes the length of the input `x` and takes that -#' as the number of successes, and the column number `.N_col` as the total number, and feeds that into -#' [s_proportion()]. +#' @describeIn estimate_multinomial_rsp Statistics function which feeds the length of `x` as number +#' of successes, and `.N_col` as total number of successes and failures into [s_proportion()]. +#' #' @inheritParams argument_convention -#' @return See [s_proportion()] for statistics and additional possible arguments. +#' +#' @return +#' * `s_length_proportion()` returns statistics from [s_proportion()]. #' #' @export #' @@ -85,8 +89,12 @@ s_length_proportion <- function(x, s_proportion(df = x_logical, ...) } -#' @describeIn estimate_multinomial_rsp Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn estimate_multinomial_rsp Formatted analysis function which is used as `afun` +#' in `estimate_multinomial_response()`. +#' +#' @return +#' * `a_length_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. +#' #' @export #' #' @examples @@ -100,11 +108,16 @@ a_length_proportion <- make_afun( ) ) -#' @describeIn estimate_multinomial_rsp Analyze Function which adds the multinomial proportion analysis to -#' the input layout. Note that additional formatting arguments can be used -#' here. +#' @describeIn estimate_multinomial_rsp Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' #' @inheritParams argument_convention #' +#' @return +#' * `estimate_multinomial_response()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_length_proportion()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/estimate_proportion.R b/R/estimate_proportion.R index e7a67137fe..929b8c9553 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -5,13 +5,13 @@ #' Estimate the proportion of responders within a studied population. #' #' @inheritParams argument_convention +#' #' @seealso [h_proportions] #' #' @name estimate_proportions -#' NULL -#' @describeIn estimate_proportions statistics function estimating a +#' @describeIn estimate_proportions Statistics function estimating a #' proportion along with its confidence interval. #' #' @inheritParams prop_strat_wilson @@ -26,6 +26,10 @@ NULL #' `wilson`, `wilsonc`, `strat_wilson`, `strat_wilsonc`, `agresti-coull` or `jeffreys`. #' @param long (`flag`)\cr a long description is required. #' +#' @return +#' * `s_proportion()` returns statistics `n_prop` (`n` and proportion) and `prop_ci` (proportion CI) for a +#' given variable. +#' #' @examples #' # Case with only logical vector. #' rsp_v <- c(1, 0, 1, 0, 1, 1, 0, 0) @@ -121,8 +125,11 @@ s_proportion <- function(df, ) } -#' @describeIn estimate_proportions Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn estimate_proportions Formatted analysis function which is used as `afun` +#' in `estimate_proportion()`. +#' +#' @return +#' * `a_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @export a_proportion <- make_afun( @@ -130,11 +137,17 @@ a_proportion <- make_afun( .formats = c(n_prop = "xx (xx.x%)", prop_ci = "(xx.x, xx.x)") ) -#' @describeIn estimate_proportions used in a `rtables` pipeline. +#' @describeIn estimate_proportions Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @param ... other arguments are ultimately conveyed to [s_proportion()]. #' +#' @return +#' * `estimate_proportion()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_proportion()` to the table layout. +#' #' @examples #' dta_test <- data.frame( #' USUBJID = paste0("S", 1:12), @@ -182,13 +195,16 @@ estimate_proportion <- function(lyt, #' #' @inheritParams argument_convention #' @inheritParams estimate_proportions +#' +#' @return Confidence interval of a proportion. +#' #' @seealso [estimate_proportions], descriptive function [d_proportion()], #' and helper functions [strata_normal_quantile()] and [update_weights_strat_wilson()]. #' #' @name h_proportions NULL -#' @describeIn h_proportions the Wilson interval calls [stats::prop.test()]. +#' @describeIn h_proportions Calculates the Wilson interval by calling [stats::prop.test()]. #' Also referred to as Wilson score interval. #' #' @examples @@ -211,8 +227,7 @@ prop_wilson <- function(rsp, conf_level, correct = FALSE) { } #' @describeIn h_proportions Calculates the stratified Wilson confidence -#' interval for unequal proportions as described in -#' \insertCite{Yan2010-jt;textual}{tern} +#' interval for unequal proportions as described in \insertCite{Yan2010-jt;textual}{tern} #' #' @param strata (`factor`)\cr variable with one level per stratum and same length as `rsp`. #' @param weights (`numeric` or `NULL`)\cr weights for each level of the strata. If `NULL`, they are @@ -332,8 +347,8 @@ prop_strat_wilson <- function(rsp, } } -#' @describeIn h_proportions the Clopper-Pearson interval calls -#' [stats::binom.test()]. Also referred to as the `exact` method. +#' @describeIn h_proportions Calculates the Clopper-Pearson interval by calling [stats::binom.test()]. +#' Also referred to as the `exact` method. #' #' @examples #' prop_clopper_pearson(rsp, conf_level = .95) @@ -349,9 +364,8 @@ prop_clopper_pearson <- function(rsp, as.numeric(y$conf.int) } -#' @describeIn h_proportions the Wald interval follows the usual -#' textbook definition for a single proportion confidence interval using the -#' normal approximation. +#' @describeIn h_proportions Calculates the Wald interval by following the usual textbook definition +#' for a single proportion confidence interval using the normal approximation. #' #' @param correct (`flag`)\cr apply continuity correction. #' @@ -374,10 +388,8 @@ prop_wald <- function(rsp, conf_level, correct = FALSE) { c(l_ci, u_ci) } -#' @describeIn h_proportions the Agresti-Coull interval was created by -#' Alan Agresti and Brent Coull and can be understood (for 95% CI) as adding -#' two successes and two failures to the data, and then using the Wald -#' formula to construct a CI. +#' @describeIn h_proportions Calculates the Agresti-Coull interval (created by Alan Agresti and Brent Coull) by +#' (for 95% CI) adding two successes and two failures to the data and then using the Wald formula to construct a CI. #' #' @examples #' prop_agresti_coull(rsp, conf_level = 0.95) @@ -402,9 +414,8 @@ prop_agresti_coull <- function(rsp, conf_level) { c(l_ci, u_ci) } -#' @describeIn h_proportions the Jeffreys interval is an equal-tailed -#' interval based on the non-informative Jeffreys prior for a binomial -#' proportion. +#' @describeIn h_proportions Calculates the Jeffreys interval, an equal-tailed interval based on the +#' non-informative Jeffreys prior for a binomial proportion. #' #' @examples #' prop_jeffreys(rsp, conf_level = 0.95) @@ -477,6 +488,8 @@ d_proportion <- function(conf_level, #' @inheritParams argument_convention #' @inheritParams prop_strat_wilson #' +#' @return Stratified quantile. +#' #' @seealso [prop_strat_wilson()] #' #' @examples @@ -515,6 +528,8 @@ strata_normal_quantile <- function(vars, weights, conf_level) { #' @param max_iterations (`count`)\cr maximum number of iterations to be tried. Convergence is always checked. #' @param tol (`number`)\cr tolerance threshold for convergence. #' +#' @return A `list` of 3 elements: `n_it`, `weights`, and `diff_v`. +#' #' @seealso For references and details see [prop_strat_wilson()]. #' #' @examples diff --git a/R/fit_rsp_step.R b/R/fit_rsp_step.R index 9ff64744e9..35ded23847 100644 --- a/R/fit_rsp_step.R +++ b/R/fit_rsp_step.R @@ -12,18 +12,20 @@ #' `response ~ arm * poly(biomarker, degree) + covariates + strata(strata)` #' #' where `degree` is specified by `control_step()`. -#' Note that for the default degree 0 the `biomarker` variable is not included in the model. #' #' @inheritParams argument_convention #' @param variables (named `list` of `character`)\cr list of analysis variables: -#' needs `response`, `arm`, `biomarker`, and optional `covariates` and -#' `strata`. +#' needs `response`, `arm`, `biomarker`, and optional `covariates` and `strata`. #' @param control (named `list`)\cr combined control list from [control_step()] #' and [control_logistic()]. -#' @return a matrix of class `step`. The first part of the columns describe the +#' +#' @return A matrix of class `step`. The first part of the columns describe the #' subgroup intervals used for the biomarker variable, including where the #' center of the intervals are and their bounds. The second part of the #' columns contain the estimates for the treatment arm comparison. +#' +#' @note For the default degree 0 the `biomarker` variable is not included in the model. +#' #' @seealso [control_step()] and [control_logistic()] for the available #' customization options. #' @export diff --git a/R/fit_survival_step.R b/R/fit_survival_step.R index 08563efa49..a830117b7a 100644 --- a/R/fit_survival_step.R +++ b/R/fit_survival_step.R @@ -11,15 +11,18 @@ #' `Surv(time, event) ~ arm * poly(biomarker, degree) + covariates + strata(strata)` #' #' where `degree` is specified by `control_step()`. -#' Note that for the default degree 0 the `biomarker` variable is not included in the model. #' #' @inheritParams argument_convention #' @param variables (named `list` of `character`)\cr list of analysis variables: needs `time`, `event`, #' `arm`, `biomarker`, and optional `covariates` and `strata`. #' @param control (named `list`)\cr combined control list from [control_step()] and [control_coxph()]. -#' @return a matrix of class `step`. The first part of the columns describe the subgroup intervals used +#' +#' @return A matrix of class `step`. The first part of the columns describe the subgroup intervals used #' for the biomarker variable, including where the center of the intervals are and their bounds. The #' second part of the columns contain the estimates for the treatment arm comparison. +#' +#' @note For the default degree 0 the `biomarker` variable is not included in the model. +#' #' @seealso [control_step()] and [control_coxph()] for the available customization options. #' @export #' diff --git a/R/formats.R b/R/formats.R index b29dfefdef..b2679c4128 100644 --- a/R/formats.R +++ b/R/formats.R @@ -16,7 +16,8 @@ NULL #' #' @param x (`integer`)\cr with elements `num` and `denom`. #' @param ... required for `rtables` interface. -#' @return a string in the format `num / denom (ratio %)`. If `num` is 0 the format is `num / denom`. +#' +#' @return A string in the format `num / denom (ratio %)`. If `num` is 0, the format is `num / denom`. #' #' @examples #' format_fraction(x = c(num = 2L, denom = 3L)) @@ -52,7 +53,8 @@ format_fraction <- function(x, ...) { #' #' @param x (`integer`)\cr with elements `num` and `denom`. #' @param ... required for `rtables` interface. -#' @return a string in the format `num / denom (ratio %)`. If `num` is 0 the format is `num / denom`. +#' +#' @return A string in the format `num / denom (ratio %)`. If `num` is 0, the format is `num / denom`. #' #' @examples #' format_fraction_fixed_dp(x = c(num = 1L, denom = 2L)) @@ -86,7 +88,8 @@ format_fraction_fixed_dp <- function(x, ...) { #' #' @param x (`integer`)\cr vector of length 2, count and fraction. #' @param ... required for `rtables` interface. -#' @return a string in the format `count (fraction %)`. If `count` is 0 the format is `0`. +#' +#' @return A string in the format `count (fraction %)`. If `count` is 0, the format is `0`. #' #' @examples #' format_count_fraction(x = c(2, 0.6667)) @@ -122,7 +125,8 @@ format_count_fraction <- function(x, ...) { #' #' @param x (`integer`)\cr vector of length 2, count and fraction. #' @param ... required for `rtables` interface. -#' @return a string in the format `count (fraction %)`. If `count` is 0 the format is `0`. +#' +#' @return A string in the format `count (fraction %)`. If `count` is 0, the format is `0`. #' #' @examples #' format_count_fraction_fixed_dp(x = c(2, 0.6667)) @@ -210,10 +214,11 @@ format_xx <- function(str) { #' a lower threshold, below which it is just stated that the fraction is smaller than that. #' #' @param threshold (`proportion`)\cr lower threshold. -#' @return An `rtables` Formatting Function that takes numeric input `x` where the second +#' +#' @return An `rtables` formatting function that takes numeric input `x` where the second #' element is the fraction that is formatted. If the fraction is above or equal to the threshold, -#' then it is displayed in percentage. If it is positive but below the threshold, it returns -#' "<1" e.g. if the threshold is `0.01`. If it is zero, then just "0" is returned. +#' then it is displayed in percentage. If it is positive but below the threshold, it returns, +#' e.g. "<1" if the threshold is `0.01`. If it is zero, then just "0" is returned. #' #' @examples #' format_fun <- format_fraction_threshold(0.05) @@ -245,15 +250,15 @@ format_fraction_threshold <- function(threshold) { #' #' @description `r lifecycle::badge("stable")` #' -#' `Rtables` Formatting Functions that handle extreme values. +#' `rtables` formatting functions that handle extreme values. +#' +#' @param digits (`integer`)\cr number of decimal places to display. #' #' @details For each input, apply a format to the specified number of `digits`. If the value is #' below a threshold, it returns "<0.01" e.g. if the number of `digits` is 2. If the value is #' above a threshold, it returns ">999.99" e.g. if the number of `digits` is 2. #' If it is zero, then returns "0.00". #' -#' @param digits (`integer`)\cr number of decimal places to display. -#' #' @family formatting functions #' @name extreme_format NULL @@ -261,6 +266,10 @@ NULL #' @describeIn extreme_format Internal helper function to calculate the threshold and create formatted strings #' used in Formatting Functions. Returns a list with elements `threshold` and `format_string`. #' +#' @return +#' * `h_get_format_threshold()` returns a `list` of 2 elements: `threshold`, with `low` and `high` thresholds, +#' and `format_string`, with thresholds formatted as strings. +#' #' @examples #' h_get_format_threshold(2L) #' @@ -285,6 +294,10 @@ h_get_format_threshold <- function(digits = 2L) { #' #' @param x (`number`)\cr value to format. #' +#' @return +#' * `h_format_threshold()` returns the given value, or if the value is not within the digit threshold the relation +#' of the given value to the digit threshold, as a formatted string. +#' #' @examples #' h_format_threshold(0.001) #' h_format_threshold(1000) @@ -317,6 +330,9 @@ h_format_threshold <- function(x, digits = 2L) { #' Create Formatting Function for a single extreme value. #' #' @inheritParams extreme_format +#' +#' @return An `rtables` formatting function that uses threshold `digits` to return a formatted extreme value. +#' #' @examples #' #' format_fun <- format_extreme_values(2L) @@ -340,10 +356,13 @@ format_extreme_values <- function(digits = 2L) { #' @description `r lifecycle::badge("stable")` #' #' Formatting Function for extreme values part of a confidence interval. Values -#' are formatted as e.g. "(xx.xx, xx.xx)" if if the number of `digits` is 2. +#' are formatted as e.g. "(xx.xx, xx.xx)" if the number of `digits` is 2. #' #' @inheritParams extreme_format #' +#' @return An `rtables` formatting function that uses threshold `digits` to return a formatted extreme +#' values confidence interval. +#' #' @examples #' format_fun <- format_extreme_values_ci(2L) #' format_fun(x = c(0.127, Inf)) diff --git a/R/g_forest.R b/R/g_forest.R index 53c0facd2e..d48f59c857 100644 --- a/R/g_forest.R +++ b/R/g_forest.R @@ -29,7 +29,9 @@ #' to the sample size used to calculate the estimator. If `NULL`, the same symbol size is used for all subgroups. #' By default tries to get this from `tbl` attribute `col_symbol_size`, otherwise needs to be manually specified. #' @param col (`character`)\cr color(s). -#' @return `gtree` object containing the forest plot and table +#' +#' @return `gTree` object containing the forest plot and table. +#' #' @export #' #' @examples @@ -658,6 +660,8 @@ forest_dot_line <- function(x, # nolint #' Create a Viewport Tree for the Forest Plot #' +#' @return A viewport tree. +#' #' @examples #' library(grid) #' diff --git a/R/g_lineplot.R b/R/g_lineplot.R index edab45fbb3..bc4b26ca72 100644 --- a/R/g_lineplot.R +++ b/R/g_lineplot.R @@ -59,9 +59,7 @@ #' @param newpage (`logical`)\cr should plot be drawn on new page? #' @param col (`character`)\cr colors. #' -#' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com -#' -#' @return \code{ggplot} +#' @return A `ggplot` line plot (and statistics table if applicable). #' #' @export #' @@ -424,9 +422,7 @@ g_lineplot <- function(df, # nolint #' If none of these attributes are attached to a given element of `x`, #' then the label is automatically generated. #' -#' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com -#' -#' @return 1-row \code{data.frame} object +#' @return A single row `data.frame` object. #' #' @examples #' @@ -482,9 +478,7 @@ h_format_row <- function(x, format, labels = NULL) { #' @param paramcd (`character` or `NA`)\cr paramcd variable name. #' @param y_unit (`character` or `NA`)\cr y_unit variable name. #' -#' @return A named character vector with names of variables. -#' -#' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com +#' @return A named character vector of variable names. #' #' @export #' diff --git a/R/g_step.R b/R/g_step.R index 78435f786b..b3ebffe201 100644 --- a/R/g_step.R +++ b/R/g_step.R @@ -13,7 +13,8 @@ #' ribbon area, or `NULL` to not plot a CI ribbon. #' @param col (`character`)\cr colors. #' -#' @return The `ggplot2` object. +#' @return A `ggplot` STEP graph. +#' #' @seealso Custom tidy method [tidy.step()]. #' @export #' @@ -141,8 +142,10 @@ g_step <- function(df, #' #' @param x (`step` matrix)\cr results from [fit_survival_step()]. #' @param ... not used here. +#' #' @return A `tibble` with one row per STEP subgroup. The estimates and CIs are on the HR or OR scale, -#' respectively. Additional attributes carry meta data also used for plotting. +#' respectively. Additional attributes carry metadata also used for plotting. +#' #' @seealso [g_step()] which consumes the result from this function. #' @method tidy step #' @export diff --git a/R/g_waterfall.R b/R/g_waterfall.R index 4c33e40fab..735655de04 100644 --- a/R/g_waterfall.R +++ b/R/g_waterfall.R @@ -13,9 +13,9 @@ #' @param ylab (`character`)\cr y label. Default is `"Value"`. #' @param title (`character`)\cr text to be displayed as plot title. #' @param col_legend_title (`character`)\cr text to be displayed as legend title. -#' @return (`ggplot` object)\cr waterfall plot. #' -#' @author Yuyao Song (songy) \email{yuyao.song@roche.com} +#' @return A `ggplot` waterfall plot. +#' #' @export #' #' @examples diff --git a/R/h_adsl_adlb_merge_using_worst_flag.R b/R/h_adsl_adlb_merge_using_worst_flag.R index 856df6c912..62df618f78 100644 --- a/R/h_adsl_adlb_merge_using_worst_flag.R +++ b/R/h_adsl_adlb_merge_using_worst_flag.R @@ -14,9 +14,9 @@ #' @param no_fillin_visits (named `character`)\cr Visits that are not considered for post-baseline worst toxicity #' grade. Defaults to `c("SCREENING", "BASELINE")`. #' -#' @return `df` containing variables shared between `adlb` and `adsl` along with variables relevant for analysis: -#' `PARAM`, `PARAMCD`, `ATOXGR`, and `BTOXGR`. Optionally `AVISIT`, `AVISITN` are included when `by_visit = TRUE` -#' and `no_fillin_visits = c("SCREENING", "BASELINE")`. +#' @return `df` containing variables shared between `adlb` and `adsl` along with variables `PARAM`, `PARAMCD`, +#' `ATOXGR`, and `BTOXGR` relevant for analysis. Optionally, `AVISIT` are `AVISITN` are included when +#' `by_visit = TRUE` and `no_fillin_visits = c("SCREENING", "BASELINE")`. #' #' @export #' diff --git a/R/h_biomarkers_subgroups.R b/R/h_biomarkers_subgroups.R index 8084ea0e1d..c8bade08e1 100644 --- a/R/h_biomarkers_subgroups.R +++ b/R/h_biomarkers_subgroups.R @@ -1,15 +1,15 @@ #' Helper Function for Tabulation of a Single Biomarker Result #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' -#' This is used by [h_tab_surv_one_biomarker()] and [h_tab_rsp_one_biomarker()], -#' please see there for examples. +#' Please see [h_tab_surv_one_biomarker()] and [h_tab_rsp_one_biomarker()], +#' which use this function for examples. #' #' @param df (`data.frame`)\cr results for a single biomarker. #' @param afuns (named `list` of `function`)\cr analysis functions. #' @param colvars (`list` with `vars` and `labels`)\cr variables to tabulate and their labels. #' -#' @return The `rtables` table object. +#' @return An `rtables` table object with statistics in columns. #' #' @export h_tab_one_biomarker <- function(df, diff --git a/R/h_cox_regression.R b/R/h_cox_regression.R index 307e747a50..eff7234cef 100644 --- a/R/h_cox_regression.R +++ b/R/h_cox_regression.R @@ -5,22 +5,20 @@ #' Helper functions used in [fit_coxreg_univar()] and [fit_coxreg_multivar()]. #' #' @inheritParams argument_convention +#' #' @seealso [cox_regression] #' #' @name h_cox_regression NULL -#' @describeIn h_cox_regression Helper for Cox Regression Formula -#' -#' Creates a list of formulas. It is used internally by [fit_coxreg_univar()] -#' for the comparison of univariate Cox regression models. +#' @describeIn h_cox_regression Helper for Cox regression formula. Creates a list of formulas. It is used +#' internally by [fit_coxreg_univar()] for the comparison of univariate Cox regression models. #' #' @inheritParams argument_convention #' @inheritParams control_coxreg #' #' @return -#' The function `h_coxreg_univar_formulas` returns a `character` vector coercible -#' into formulas (e.g [stats::as.formula()]). +#' * `h_coxreg_univar_formulas()` returns a `character` vector coercible into formulas (e.g [stats::as.formula()]). #' #' @examples #' # `h_coxreg_univar_formulas` @@ -107,17 +105,14 @@ h_coxreg_univar_formulas <- function(variables, stats::setNames(forms, nams) } -#' @describeIn h_cox_regression Helper for Multi-variable Cox Regression Formula -#' -#' Creates a formulas string. It is used internally by [fit_coxreg_multivar()] -#' for the comparison of multi-variable Cox regression models. Interactions will not -#' be included in multi-variable Cox regression model. +#' @describeIn h_cox_regression Helper for multivariate Cox regression formula. Creates a formulas +#' string. It is used internally by [fit_coxreg_multivar()] for the comparison of multivariate Cox +#' regression models. Interactions will not be included in multivariate Cox regression model. #' #' @inheritParams argument_convention #' #' @return -#' The function `h_coxreg_univar_formulas` returns a `character` vector coercible -#' into formulas (e.g [stats::as.formula()]). +#' * `h_coxreg_multivar_formula()` returns a `string` coercible into a formula (e.g [stats::as.formula()]). #' #' @export #' @@ -175,6 +170,10 @@ h_coxreg_multivar_formula <- function(variables) { #' @param effect (`string`)\cr the treatment variable. #' @param mod (`coxph`)\cr Cox regression model fitted by [survival::coxph()]. #' +#' @return +#' * `h_coxreg_univar_extract()` returns a `data.frame` with variables `effect`, `term`, `term_label`, `level`, +#' `n`, `hr`, `lcl`, `ucl`, and `pval`. +#' #' @examples #' library(survival) #' @@ -235,13 +234,16 @@ h_coxreg_univar_extract <- function(effect, ) } -#' @describeIn h_cox_regression Tabulation of Multi-variable Cox Regressions -#' -#' Utility function to help tabulate the result of a multi-variable Cox regression model -#' for a treatment/covariate variable. +#' @describeIn h_cox_regression Tabulation of multivariate Cox regressions. Utility function to help +#' tabulate the result of a multivariate Cox regression model for a treatment/covariate variable. #' #' @inheritParams argument_convention #' @inheritParams h_coxreg_univar_extract +#' +#' @return +#' * `h_coxreg_multivar_extract()` returns a `data.frame` with variables `pval`, `hr`, `lcl`, `ucl`, `level`, +#' `n`, `term`, and `term_label`. +#' #' @export #' #' @examples diff --git a/R/h_logistic_regression.R b/R/h_logistic_regression.R index ec011864d2..6fe8ceb823 100644 --- a/R/h_logistic_regression.R +++ b/R/h_logistic_regression.R @@ -1,4 +1,4 @@ -#' Helper Functions for Multi-Variable Logistic Regression +#' Helper Functions for Multivariate Logistic Regression #' #' @description `r lifecycle::badge("stable")` #' @@ -11,8 +11,6 @@ #' @param x (`string` or `character`)\cr a variable or interaction term in `fit_glm` (depending on the #' helper function). #' -#' @name h_logistic_regression -#' #' @examples #' library(dplyr) #' library(broom) @@ -43,11 +41,15 @@ #' interaction = "AGE" #' ) #' ) +#' +#' @name h_logistic_regression NULL #' @describeIn h_logistic_regression Helper function to extract interaction variable names from a fitted #' model assuming only one interaction term. #' +#' @return Vector of names of interaction variables. +#' #' @export h_get_interaction_vars <- function(fit_glm) { checkmate::assert_class(fit_glm, "glm") @@ -68,6 +70,8 @@ h_get_interaction_vars <- function(fit_glm) { #' @param second_var_with_level (`character` of length 2)\cr the second variable name with #' the interaction level. #' +#' @return Name of coefficient. +#' #' @export h_interaction_coef_name <- function(interaction_vars, first_var_with_level, @@ -92,6 +96,8 @@ h_interaction_coef_name <- function(interaction_vars, #' @param odds_ratio_var (`string`)\cr the odds ratio variable. #' @param interaction_var (`string`)\cr the interaction variable. #' +#' @return Odds ratio. +#' #' @export h_or_cat_interaction <- function(odds_ratio_var, interaction_var, @@ -144,6 +150,9 @@ h_or_cat_interaction <- function(odds_ratio_var, #' #' @param at (`NULL` or `numeric`)\cr optional values for the interaction variable. Otherwise #' the median is used. +#' +#' @return Odds ratio. +#' #' @note We don't provide a function for the case when both variables are continuous because #' this does not arise in this table, as the treatment arm variable will always be involved #' and categorical. @@ -239,6 +248,8 @@ h_or_cont_interaction <- function(odds_ratio_var, #' in case of an interaction. This is a wrapper for [h_or_cont_interaction()] and #' [h_or_cat_interaction()]. #' +#' @return Odds ratio. +#' #' @export h_or_interaction <- function(odds_ratio_var, interaction_var, @@ -272,6 +283,8 @@ h_or_interaction <- function(odds_ratio_var, #' @param terms (`character`)\cr simple terms. #' @param table (`table`)\cr table containing numbers for terms. #' +#' @return Term labels containing numbers of patients. +#' #' @export h_simple_term_labels <- function(terms, table) { @@ -290,6 +303,8 @@ h_simple_term_labels <- function(terms, #' @param any (`flag`)\cr whether any of `term1` and `term2` can be fulfilled to count the #' number of patients. In that case they can only be scalar (strings). #' +#' @return Term labels containing numbers of patients. +#' #' @export h_interaction_term_labels <- function(terms1, terms2, @@ -318,6 +333,8 @@ h_interaction_term_labels <- function(terms1, #' @describeIn h_logistic_regression Helper function to tabulate the main effect #' results of a (conditional) logistic regression model. #' +#' @return Tabulated main effect results from a logistic regression model. +#' #' @examples #' h_glm_simple_term_extract("AGE", mod1) #' h_glm_simple_term_extract("ARMCD", mod1) @@ -415,6 +432,8 @@ h_glm_simple_term_extract <- function(x, fit_glm) { #' @describeIn h_logistic_regression Helper function to tabulate the interaction term #' results of a logistic regression model. #' +#' @return Tabulated interaction term results from a logistic regression model. +#' #' @examples #' h_glm_interaction_extract("ARMCD:AGE", mod2) #' @@ -520,6 +539,8 @@ h_glm_interaction_extract <- function(x, fit_glm) { #' [h_or_interaction()] and [h_glm_simple_term_extract()] which puts the results #' in the right data frame format. #' +#' @return A `data.frame` of tabulated interaction term results from a logistic regression model. +#' #' @examples #' h_glm_inter_term_extract("AGE", "ARMCD", mod2) #' @@ -614,6 +635,9 @@ h_glm_inter_term_extract <- function(odds_ratio_var, #' @describeIn h_logistic_regression Helper function to tabulate the results including #' odds ratios and confidence intervals of simple terms. +#' +#' @return Tabulated statistics for the given variable(s) from the logistic regression model. +#' #' @export #' #' @examples @@ -644,6 +668,8 @@ h_logistic_simple_terms <- function(x, fit_glm, conf_level = 0.95) { #' @describeIn h_logistic_regression Helper function to tabulate the results including #' odds ratios and confidence intervals of interaction terms. #' +#' @return Tabulated statistics for the given variable(s) from the logistic regression model. +#' #' @examples #' h_logistic_inter_terms(c("RACE", "AGE", "ARMCD", "AGE:ARMCD"), mod2) #' diff --git a/R/h_map_for_count_abnormal.R b/R/h_map_for_count_abnormal.R index c10bfef8d9..74dda54773 100644 --- a/R/h_map_for_count_abnormal.R +++ b/R/h_map_for_count_abnormal.R @@ -15,6 +15,9 @@ #' records with all normal values will be excluded to avoid error in creating layout. #' If method is `"range"`, the returned map will be based on the rule that at least one observation with low range > 0 #' for low direction and at least one observation with high range is not missing for high direction. +#' +#' @return A map `data.frame`. +#' #' @export #' #' @examples diff --git a/R/h_pkparam_sort.R b/R/h_pkparam_sort.R index 2e44c87800..1a58adc223 100644 --- a/R/h_pkparam_sort.R +++ b/R/h_pkparam_sort.R @@ -1,10 +1,12 @@ -#' Sort `PK PARAM` variable +#' Sort Data by `PK PARAM` Variable #' #' @description `r lifecycle::badge("stable")` #' #' @param pk_data (`data.frame`)\cr Pharmacokinetics dataframe #' @param key_var (`character`)\cr key variable used to merge pk_data and metadata created by `d_pkparam()` -#' @return dataframe with `PK PARAM` variable ordered +#' +#' @return A PK `data.frame` sorted by a `PARAM` variable. +#' #' @export #' #' @examples diff --git a/R/h_response_biomarkers_subgroups.R b/R/h_response_biomarkers_subgroups.R index 5509c9242f..ef478ed4c5 100644 --- a/R/h_response_biomarkers_subgroups.R +++ b/R/h_response_biomarkers_subgroups.R @@ -8,7 +8,6 @@ #' @inheritParams response_biomarkers_subgroups #' @inheritParams extract_rsp_biomarkers #' @inheritParams argument_convention -#' @name h_response_biomarkers_subgroups #' #' @examples #' library(dplyr) @@ -22,6 +21,7 @@ #' mutate(rsp = AVALC == "CR") #' formatters::var_labels(adrs_f) <- c(adrs_labels, "Response") #' +#' @name h_response_biomarkers_subgroups NULL #' @describeIn h_response_biomarkers_subgroups helps with converting the "response" function variable list @@ -29,6 +29,9 @@ NULL #' inconsistency between the variable names accepted by `extract_rsp_subgroups()` and `fit_logistic()`. #' @param biomarker (`string`)\cr the name of the biomarker variable. #' +#' @return +#' * `h_rsp_to_logistic_variables()` returns a named `list` of elements `response`, `arm`, `covariates`, and `strata`. +#' #' @examples #' # This is how the variable list is converted internally. #' h_rsp_to_logistic_variables( @@ -60,6 +63,9 @@ h_rsp_to_logistic_variables <- function(variables, biomarker) { #' `rsp` and `biomarkers` (vector of continuous biomarker variables) and optionally `covariates` #' and `strat`. #' +#' @return +#' * `h_logistic_mult_cont_df()` returns a `data.frame` containing estimates and statistics for the selected biomarkers. +#' #' @examples #' # For a single population, estimate separately the effects #' # of two biomarkers. @@ -158,6 +164,9 @@ h_logistic_mult_cont_df <- function(variables, #' added by that high-level function relative to what is returned by [h_logistic_mult_cont_df()], #' see the example). #' +#' @return +#' * `h_tab_rsp_one_biomarker()` returns an `rtables` table object with the given statistics arranged in columns. +#' #' @examples #' # Starting from above `df`, zoom in on one biomarker and add required columns. #' df1 <- df[1, ] diff --git a/R/h_response_subgroups.R b/R/h_response_subgroups.R index d182732354..020d07ec94 100644 --- a/R/h_response_subgroups.R +++ b/R/h_response_subgroups.R @@ -1,15 +1,15 @@ #' Helper Functions for Tabulating Binary Response by Subgroup #' +#' @description `r lifecycle::badge("stable")` +#' #' Helper functions that tabulate in a data frame statistics such as response rate #' and odds ratio for population subgroups. #' -#' @details Main functionality is to prepare data for use in a layout creating function. -#' -#' @description `r lifecycle::badge("stable")` #' @inheritParams argument_convention #' @inheritParams response_subgroups #' @param arm (`factor`)\cr the treatment group variable. -#' @name h_response_subgroups +#' +#' @details Main functionality is to prepare data for use in a layout-creating function. #' #' @examples #' library(dplyr) @@ -28,10 +28,16 @@ #' rsp = AVALC == "CR" #' ) #' formatters::var_labels(adrs_f) <- c(adrs_labels, "Response") +#' +#' @name h_response_subgroups NULL #' @describeIn h_response_subgroups helper to prepare a data frame of binary responses by arm. #' @inheritParams h_response_subgroups +#' +#' @return +#' * `h_proportion_df()` returns a `data.frame` with columns `arm`, `n`, `n_rsp`, and `prop`. +#' #' @export #' @examples #' @@ -77,6 +83,11 @@ h_proportion_df <- function(rsp, arm) { #' in a data frame. `variables` corresponds to the names of variables found in `data`, passed as a named list and #' requires elements `rsp`, `arm` and optionally `subgroups`. `groups_lists` optionally specifies #' groupings for `subgroups` variables. +#' +#' @return +#' * `h_proportion_subgroups_df()` returns a `data.frame` with columns `arm`, `n`, `n_rsp`, `prop`, `subgroup`, +#' `var`, `var_label`, and `row_type`. +#' #' @export #' #' @examples @@ -141,6 +152,11 @@ h_proportion_subgroups_df <- function(variables, #' #' @inheritParams response_subgroups #' @param strata_data (`factor`, `data.frame` or `NULL`)\cr required if stratified analysis is performed. +#' +#' @return +#' * `h_odds_ratio_df()` returns a `data.frame` with columns `arm`, `n_tot`, `or`, `lcl`, `ucl`, `conf_level`, and +#' optionally `pval` and `pval_label`. +#' #' @export #' #' @examples @@ -263,6 +279,11 @@ h_odds_ratio_df <- function(rsp, arm, strata_data = NULL, conf_level = 0.95, met #' arm across subgroups in a data frame. `variables` corresponds to the names of variables found in #' `data`, passed as a named list and requires elements `rsp`, `arm` and optionally `subgroups` #' and `strat`. `groups_lists` optionally specifies groupings for `subgroups` variables. +#' +#' @return +#' * `h_odds_ratio_subgroups_df()` returns a `data.frame` with columns `arm`, `n_tot`, `or`, `lcl`, `ucl`, +#' `conf_level`, `subgroup`, `var`, `var_label`, and `row_type`. +#' #' @export #' #' @examples diff --git a/R/h_stack_by_baskets.R b/R/h_stack_by_baskets.R index c2fdb5d3ed..b848968767 100644 --- a/R/h_stack_by_baskets.R +++ b/R/h_stack_by_baskets.R @@ -19,6 +19,9 @@ #' there are some levels of interest that are not observed in the `df` dataset. #' The two columns of this dataset should be named `basket` and `basket_name`. #' +#' @return `data.frame` with variables in `keys` taken from `df` and new variable `SMQ` containing +#' records belonging to the baskets selected via the `baskets` argument. +#' #' @export #' #' @examples diff --git a/R/h_step.R b/R/h_step.R index 2583c32d1e..1ec1eeba32 100644 --- a/R/h_step.R +++ b/R/h_step.R @@ -3,22 +3,25 @@ NULL #' Helper Functions for Subgroup Treatment Effect Pattern (STEP) Calculations #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' Helper functions that are used internally for the STEP calculations. #' #' @inheritParams argument_convention -#' @name h_step #' +#' @name h_step NULL #' @describeIn h_step creates the windows for STEP, based on the control settings -#' provided. Returns a list containing the window-selection matrix `sel` -#' and the interval information matrix `interval`. +#' provided. #' #' @param x (`numeric`)\cr biomarker value(s) to use (without `NA`). #' @param control (named `list`)\cr output from `control_step()`. #' +#' @return +#' * `h_step_window()` returns a list containing the window-selection matrix `sel` +#' and the interval information matrix `interval`. +#' #' @export h_step_window <- function(x, control = control_step()) { @@ -65,9 +68,12 @@ h_step_window <- function(x, #' on the linear predictor scale and corresponding standard error from a STEP `model` fitted #' on `data` given `variables` specification, for a single biomarker value `x`. #' This works for both `coxph` and `glm` models, i.e. for calculating log hazard ratio or log odds -#' ratio estimates. It returns a vector with elements `est` and `se`. +#' ratio estimates. #' @param model the regression model object. #' +#' @return +#' * `h_step_trt_effect()` returns a vector with elements `est` and `se`. +#' #' @export h_step_trt_effect <- function(data, model, @@ -100,6 +106,9 @@ h_step_trt_effect <- function(data, #' @describeIn h_step builds the model formula used in survival STEP calculations. #' +#' @return +#' * `h_step_survival_formula()` returns a model formula. +#' #' @export h_step_survival_formula <- function(variables, control = control_step()) { @@ -121,13 +130,16 @@ h_step_survival_formula <- function(variables, #' @describeIn h_step estimates the model with `formula` built based on #' `variables` in `data` for a given `subset` and `control` parameters for the -#' Cox regression, and returns a matrix of number of observations `n`, -#' `events` as well as log hazard ratio estimates `loghr`, standard error `se` -#' and Wald confidence interval bounds `ci_lower` and `ci_upper`. One row is -#' included here for each biomarker value in `x`. +#' Cox regression. #' @param formula (`formula`)\cr the regression model formula. #' @param subset (`logical`)\cr subset vector. #' +#' @return +#' * `h_step_survival_est()` returns a matrix of number of observations `n`, +#' `events`, log hazard ratio estimates `loghr`, standard error `se`, +#' and Wald confidence interval bounds `ci_lower` and `ci_upper`. One row is +#' included for each biomarker value in `x`. +#' #' @export h_step_survival_est <- function(formula, data, @@ -190,6 +202,9 @@ h_step_survival_est <- function(formula, #' @describeIn h_step builds the model formula used in response STEP calculations. #' +#' @return +#' * `h_step_rsp_formula()` returns a model formula. +#' #' @export h_step_rsp_formula <- function(variables, control = c(control_step(), control_logistic())) { @@ -221,13 +236,15 @@ h_step_rsp_formula <- function(variables, #' @describeIn h_step estimates the model with `formula` built based on #' `variables` in `data` for a given `subset` and `control` parameters for the -#' logistic regression, and returns a matrix of number of observations `n` -#' as well as log odds ratio estimates `logor`, standard error `se` -#' and Wald confidence interval bounds `ci_lower` and `ci_upper`. One row is -#' included here for each biomarker value in `x`. +#' logistic regression. #' @param formula (`formula`)\cr the regression model formula. #' @param subset (`logical`)\cr subset vector. #' +#' @return +#' * `h_step_rsp_est()` returns a matrix of number of observations `n`, log odds +#' ratio estimates `logor`, standard error `se`, and Wald confidence interval bounds +#' `ci_lower` and `ci_upper`. One row is included for each biomarker value in `x`. +#' #' @export h_step_rsp_est <- function(formula, data, diff --git a/R/h_survival_biomarkers_subgroups.R b/R/h_survival_biomarkers_subgroups.R index 7cf2a53567..817951ea7f 100644 --- a/R/h_survival_biomarkers_subgroups.R +++ b/R/h_survival_biomarkers_subgroups.R @@ -1,6 +1,6 @@ #' Helper Functions for Tabulating Biomarker Effects on Survival by Subgroup #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' Helper functions which are documented here separately to not confuse the user #' when reading about the user-facing functions. @@ -8,7 +8,6 @@ #' @inheritParams survival_biomarkers_subgroups #' @inheritParams argument_convention #' @inheritParams fit_coxreg_multivar -#' @name h_survival_biomarkers_subgroups #' #' @examples #' library(dplyr) @@ -28,6 +27,7 @@ #' labels <- c("AVALU" = adtte_labels[["AVALU"]], "is_event" = "Event Flag") #' formatters::var_labels(adtte_f)[names(labels)] <- labels #' +#' @name h_survival_biomarkers_subgroups NULL #' @describeIn h_survival_biomarkers_subgroups helps with converting the "survival" function variable list @@ -35,6 +35,10 @@ NULL #' names accepted by `extract_survival_subgroups()` and `fit_coxreg_multivar()`. #' @param biomarker (`string`)\cr the name of the biomarker variable. #' +#' @return +#' * `h_surv_to_coxreg_variables()` returns a named `list` of elements `time`, `event`, `arm`, +#' `covariates`, and `strata`. +#' #' @examples #' # This is how the variable list is converted internally. #' h_surv_to_coxreg_variables( @@ -68,6 +72,9 @@ h_surv_to_coxreg_variables <- function(variables, biomarker) { #' `variables` corresponds to names of variables found in `data`, passed as a named list and requires elements #' `tte`, `is_event`, `biomarkers` (vector of continuous biomarker variables) and optionally `subgroups` and `strat`. #' +#' @return +#' * `h_coxreg_mult_cont_df()` returns a `data.frame` containing estimates and statistics for the selected biomarkers. +#' #' @examples #' # For a single population, estimate separately the effects #' # of two biomarkers. @@ -168,6 +175,9 @@ h_coxreg_mult_cont_df <- function(variables, #' added by that high-level function relative to what is returned by [h_coxreg_mult_cont_df()], #' see the example). #' +#' @return +#' * `h_tab_surv_one_biomarker()` returns an `rtables` table object with the given statistics arranged in columns. +#' #' @examples #' # Starting from above `df`, zoom in on one biomarker and add required columns. #' df1 <- df[1, ] diff --git a/R/h_survival_duration_subgroups.R b/R/h_survival_duration_subgroups.R index 3d12399490..a49a5151e8 100644 --- a/R/h_survival_duration_subgroups.R +++ b/R/h_survival_duration_subgroups.R @@ -5,13 +5,12 @@ #' Helper functions that tabulate in a data frame statistics such as median survival #' time and hazard ratio for population subgroups. #' -#' @details Main functionality is to prepare data for use in a layout creating function. -#' #' @inheritParams argument_convention #' @inheritParams survival_coxph_pairwise #' @inheritParams survival_duration_subgroups #' @param arm (`factor`)\cr the treatment group variable. -#' @name h_survival_duration_subgroups +#' +#' @details Main functionality is to prepare data for use in a layout-creating function. #' #' @examples #' library(dplyr) @@ -37,11 +36,15 @@ #' labels <- c("ARM" = adtte_labels[["ARM"]], "SEX" = adtte_labels[["SEX"]], "is_event" = "Event Flag") #' formatters::var_labels(adtte_f)[names(labels)] <- labels #' +#' @name h_survival_duration_subgroups NULL #' @describeIn h_survival_duration_subgroups helper to prepare a data frame of median survival times by arm. #' @inheritParams h_survival_duration_subgroups #' +#' @return +#' * `h_survtime_df()` returns a `data.frame` with columns `arm`, `n`, `n_events`, and `median`. +#' #' @examples #' # Extract median survival time for one group. #' h_survtime_df( @@ -97,6 +100,10 @@ h_survtime_df <- function(tte, is_event, arm) { #' requires elements `tte`, `is_event`, `arm` and optionally `subgroups`. `groups_lists` optionally specifies #' groupings for `subgroups` variables. #' +#' @return +#' * `h_survtime_subgroups_df()` returns a `data.frame` with columns `arm`, `n`, `n_events`, `median`, `subgroup`, +#' `var`, `var_label`, and `row_type`. +#' #' @examples #' # Extract median survival time for multiple groups. #' h_survtime_subgroups_df( @@ -172,6 +179,10 @@ h_survtime_subgroups_df <- function(variables, #' #' @param strata_data (`factor`, `data.frame` or `NULL`)\cr required if stratified analysis is performed. #' +#' @return +#' * `h_coxph_df()` returns a `data.frame` with columns `arm`, `n_tot`, `n_tot_events`, `hr`, `lcl`, `ucl`, +#' `conf_level`, `pval` and `pval_label`. +#' #' @examples #' # Extract hazard ratio for one group. #' h_coxph_df(adtte_f$AVAL, adtte_f$is_event, adtte_f$ARM) @@ -270,6 +281,10 @@ h_coxph_df <- function(tte, is_event, arm, strata_data = NULL, control = control #' optionally `subgroups` and `strat`. `groups_lists` optionally specifies #' groupings for `subgroups` variables. #' +#' @return +#' * `h_coxph_subgroups_df()` returns a `data.frame` with columns `arm`, `n_tot`, `n_tot_events`, `hr`, +#' `lcl`, `ucl`, `conf_level`, `pval`, `pval_label`, `subgroup`, `var`, `var_label`, and `row_type`. +#' #' @examples #' # Extract hazard ratio for multiple groups. #' h_coxph_subgroups_df( diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 8c99b700e0..f665cb5b13 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -26,13 +26,12 @@ NULL #' @describeIn incidence_rate Statistics function which estimates the incidence rate and the #' associated confidence interval. #' -#' @return The statistics are: -#' \describe{ -#' \item{person_years}{total person-years at risk} -#' \item{n_events}{total number of events observed} -#' \item{rate}{estimated incidence rate} -#' \item{rate_ci}{confidence interval for the incidence rate} -#' } +#' @return +#' * `s_incidence_rate()` returns the following statistics: +#' - `person_years`: Total person-years at risk. +#' - `n_events`: Total number of events observed. +#' - `rate`: Estimated incidence rate. +#' - `rate_ci`: Confidence interval for the incidence rate. #' #' @examples #' library(dplyr) @@ -107,8 +106,11 @@ s_incidence_rate <- function(df, } -#' @describeIn incidence_rate Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn incidence_rate Formatted analysis function which is used as `afun` +#' in `estimate_incidence_rate()`. +#' +#' @return +#' * `a_incidence_rate()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_incidence_rate @@ -132,8 +134,13 @@ a_incidence_rate <- make_afun( ) ) -#' @describeIn incidence_rate Layout creating function which adds analyze rows using the statistics -#' function `s_incidence_rate` and desired format. +#' @describeIn incidence_rate Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `estimate_incidence_rate()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_incidence_rate()` to the table layout. #' #' @examples #' basic_table() %>% @@ -189,11 +196,12 @@ estimate_incidence_rate <- function(lyt, #' * `time_unit_input`: (`string`)\cr `day`, `week`, `month`, or `year` (default) #' indicating time unit for data input. #' * `time_unit_output`: (`numeric`)\cr time unit for desired output (in person-years). -#' #' @param person_years (`numeric`)\cr total person-years at risk. #' @param alpha (`numeric`)\cr two-sided alpha-level for confidence interval. #' @param n_events (`integer`)\cr number of events observed. #' +#' @return Estimated incidence rate `rate` and associated confidence interval `rate_ci`. +#' #' @seealso [incidence_rate] #' #' @name h_incidence_rate diff --git a/R/individual_patient_plot.R b/R/individual_patient_plot.R index faa1b0128e..086862412b 100644 --- a/R/individual_patient_plot.R +++ b/R/individual_patient_plot.R @@ -14,15 +14,15 @@ #' @param title (`string`)\cr title for plot. #' @param subtitle (`string`)\cr subtitle for plot. #' @param add_baseline_hline (`flag`)\cr adds horizontal line at baseline y-value on -#' plot when TRUE. +#' plot when TRUE. #' @param yvar_baseline (`string`)\cr variable with baseline values only. -#' Ignored when `add_baseline_hline` is FALSE. +#' Ignored when `add_baseline_hline` is FALSE. #' @param ggtheme (`theme`)\cr optional graphical theme function as provided -#' by `ggplot2` to control outlook of plot. Use `ggplot2::theme()` to tweak the display. +#' by `ggplot2` to control outlook of plot. Use `ggplot2::theme()` to tweak the display. #' @param plotting_choices (`character`)\cr specifies options for displaying -#' plots. Must be one of "all_in_one", "split_by_max_obs", "separate_by_obs". +#' plots. Must be one of "all_in_one", "split_by_max_obs", "separate_by_obs". #' @param max_obs_per_plot (`count`)\cr Number of observations to be plotted on one -#' plot. Ignored when `plotting_choices` is not "separate_by_obs". +#' plot. Ignored when `plotting_choices` is not "separate_by_obs". #' @param caption (`character` scalar)\cr optional caption below the plot. #' @param col (`character`)\cr lines colors. #' @@ -39,6 +39,9 @@ NULL #' #' @inheritParams argument_convention #' @inheritParams g_ipp +#' +#' @return A `ggplot` line plot. +#' #' @seealso [g_ipp()] which uses this function. #' @export #' @examples @@ -147,7 +150,7 @@ h_g_ipp <- function(df, #' graphic or compiles a list of graphics that show trends in individual's parameter #' values over time. #' -#' @return a `ggplot` object or a list of `ggplot` objects. +#' @return A `ggplot` object or a list of `ggplot` objects. #' #' @export #' @examples diff --git a/R/kaplan_meier_plot.R b/R/kaplan_meier_plot.R index a042dca23a..bc3c46e64e 100644 --- a/R/kaplan_meier_plot.R +++ b/R/kaplan_meier_plot.R @@ -67,12 +67,12 @@ NULL #' including the number of patient at risk at given time and the median survival #' per group. #' -#' @return a `grob` of class `gTree`. -#' #' @inheritParams grid::gTree #' @inheritParams kaplan_meier #' @inheritParams argument_convention #' +#' @return A `grob` of class `gTree`. +#' #' @export #' #' @examples @@ -447,13 +447,11 @@ g_km <- function(df, #' Helper function: tidy survival fit #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' Convert the survival fit data into a data frame designed for plotting #' within `g_km`. #' -#' @description `r lifecycle::badge("stable")` -#' #' This starts from the [broom::tidy()] result, and then: #' - post-processes the `strata` column into a factor, #' - extends each stratum by an additional first row with time 0 @@ -465,6 +463,10 @@ g_km <- function(df, #' @param fit_km (`survfit`)\cr result of [survival::survfit()]. #' @param armval (`string`)\cr used as strata name when treatment arm #' variable only has one level. Default is "All". +#' +#' @return A `tibble` with columns `time`, `n.risk`, `n.event`, `n.censor`, +#' `estimate`, `std.error`, `conf.high`, `conf.low`, `strata`, and `censor`. +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -530,7 +532,7 @@ h_data_plot <- function(fit_km, #' Helper function: x tick positions #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' Calculate the positions of ticks on the x-axis. However, if `xticks` already #' exists it is kept as is. It is based on the same function `ggplot2` relies on, @@ -538,6 +540,9 @@ h_data_plot <- function(fit_km, #' #' @inheritParams kaplan_meier #' +#' @return A vector of positions to use for x-axis ticks on a `ggplot` object. +#' +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -590,6 +595,9 @@ h_xticks <- function(data, xticks = NULL, max_time = NULL) { #' Draw the Kaplan-Meier plot using `ggplot2`. #' #' @inheritParams kaplan_meier +#' +#' @return A `ggplot` object. +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -730,15 +738,18 @@ h_ggkm <- function(data, #' #' @description `r lifecycle::badge("stable")` #' -#' The elements composing the `ggplot` are extracted and organized in a -#' list containing: -#' the panel (`panel`), -#' the y-axis and its label (`yaxis`, `ylab`), -#' idem for the x-axis (`xaxis`, `xlab`), -#' the legend (`guide`). +#' The elements composing the `ggplot` are extracted and organized in a `list`. #' #' @param gg (`ggplot`)\cr a graphic to decompose. #' +#' @return A named `list` with elements: +#' * `panel`: The panel. +#' * `yaxis`: The y-axis. +#' * `xaxis`: The x-axis. +#' * `xlab`: The x-axis label. +#' * `ylab`: The y-axis label. +#' * `guide`: The legend. +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -795,6 +806,9 @@ h_decompose_gg <- function(gg) { #' @param annot_at_risk (`flag`)\cr compute and add the annotation table #' reporting the number of patient at risk matching the main grid of the #' Kaplan-Meier curve. +#' +#' @return A grid layout. +#' #' @export #' #' @details @@ -909,6 +923,8 @@ h_km_layout <- function(data, g_el, title, footnotes, annot_at_risk = TRUE) { #' @param xlim (`numeric`)\cr the maximum value on the x-axis (used to #' ensure the at risk table aligns with the KM graph). #' +#' @return A named `list` of two `gTree` objects: `at_risk` and `label`. +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -1047,6 +1063,8 @@ h_grob_tbl_at_risk <- function(data, annot_tbl, xlim) { #' #' @inheritParams h_data_plot #' +#' @return A summary table with statistics `N`, `Median`, and `XX% CI` (`XX` taken from `fit_km`). +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -1096,6 +1114,8 @@ h_tbl_median_surv <- function(fit_km, armval = "All") { #' @param y a `numeric` value between 0 and 1 specifying y-location. #' @inheritParams h_data_plot #' +#' @return A `grob` of a table containing statistics `N`, `Median`, and `XX% CI` (`XX` taken from `fit_km`). +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -1146,6 +1166,8 @@ h_grob_median_surv <- function(fit_km, #' @param yaxis (`gtable`)\cr the y-axis as a graphical object derived from #' a `ggplot`. #' +#' @return a `gTree` object containing the y-axis annotation from a `ggplot`. +#' #' @examples #' \dontrun{ #' library(dplyr) @@ -1191,9 +1213,13 @@ h_grob_y_annot <- function(ylab, yaxis) { #' #' @description `r lifecycle::badge("stable")` #' -#' Create an `rtable` of pairwise stratified or unstratified CoxPH analysis results. +#' Create a `data.frame` of pairwise stratified or unstratified CoxPH analysis results. #' #' @inheritParams g_km +#' +#' @return A `data.frame` containing statistics `HR`, `XX% CI` (`XX` taken from `control_coxph_pw`), +#' and `p-value (log-rank)`. +#' #' @export #' #' @examples @@ -1254,6 +1280,10 @@ h_tbl_coxph_pairwise <- function(df, #' @param ... arguments will be passed to [h_tbl_coxph_pairwise()]. #' @param x a `numeric` value between 0 and 1 specifying x-location. #' @param y a `numeric` value between 0 and 1 specifying y-location. +#' +#' @return A `grob` of a table containing statistics `HR`, `XX% CI` (`XX` taken from `control_coxph_pw`), +#' and `p-value (log-rank)`. +#' #' @export #' #' @examples diff --git a/R/logistic_regression.R b/R/logistic_regression.R index e100178ed1..ff32b55d65 100644 --- a/R/logistic_regression.R +++ b/R/logistic_regression.R @@ -1,8 +1,8 @@ -#' Multi-Variable Logistic Regression Table +#' Multivariate Logistic Regression Table #' #' @description `r lifecycle::badge("stable")` #' -#' Layout creating function which summarizes a logistic variable regression for binary outcome with +#' Layout-creating function which summarizes a logistic variable regression for binary outcome with #' categorical/continuous covariates in model statement. For each covariate category (if categorical) #' or specified values (if continuous), present degrees of freedom, regression parameter estimate and #' standard error (SE) relative to reference group or category. Report odds ratios for each covariate @@ -11,11 +11,15 @@ #' that covariate has no effect on response in model containing all specified covariates. #' Allow option to include one two-way interaction and present similar output for #' each interaction degree of freedom. -#' Note: For the formula, the variable names need to be standard dataframe column name without -#' special characters. #' #' @inheritParams argument_convention -#' @param drop_and_remove_str string to be dropped and removed +#' @param drop_and_remove_str (`character`)\cr string to be dropped and removed. +#' +#' @return A layout object suitable for passing to further layouting functions, or to [rtables::build_table()]. +#' Adding this function to an `rtable` layout will add a logistic regression variable summary to the table layout. +#' +#' @note For the formula, the variable names need to be standard `data.frame` column names without +#' special characters. #' #' @examples #' library(dplyr) @@ -106,17 +110,16 @@ summarize_logistic <- function(lyt, #' This will be used when fitting the (conditional) logistic regression model on the left hand #' side of the formula. #' +#' @return A fitted logistic regression model. +#' #' @section Model Specification: #' #' The `variables` list needs to include the following elements: -#' \describe{ -#' \item{arm}{treatment arm variable name.} -#' \item{response}{the response arm variable name. Usually this is a 0/1 variable.} -#' \item{covariates}{this is either `NULL` (no covariates) or a character vector of covariate variable names.} -#' \item{interaction}{this is either `NULL` (no interaction) or a string of a single covariate variable name already +#' * `arm`: Treatment arm variable name. +#' * `response`: The response arm variable name. Usually this is a 0/1 variable. +#' * `covariates`: This is either `NULL` (no covariates) or a character vector of covariate variable names. +#' * `interaction`: This is either `NULL` (no interaction) or a string of a single covariate variable name already #' included in `covariates`. Then the interaction with the treatment arm is included in the model. -#' } -#' } #' #' @examples #' library(dplyr) @@ -213,6 +216,9 @@ fit_logistic <- function(data, #' @param at (`NULL` or `numeric`)\cr optional values for the interaction variable. Otherwise #' the median is used. #' @param fit_glm logistic regression model fitted by [stats::glm()] with "binomial" family. +#' +#' @return A `data.frame` containing the tidied model. +#' #' @method tidy glm #' @seealso [h_logistic_regression] for relevant helper functions. #' @@ -280,15 +286,19 @@ tidy.glm <- function(fit_glm, # nolint df } -#' Logistic Regression Multi-Variable Column Layout Function +#' Logistic Regression Multivariate Column Layout Function #' #' @description `r lifecycle::badge("stable")` #' -#' Layout creating function for a multi-variable column layout summarizing -#' logistic regression results. +#' Layout-creating function which creates a multivariate column layout summarizing logistic +#' regression results. This function is a wrapper for [rtables::split_cols_by_multivar()]. #' #' @inheritParams argument_convention #' +#' @return A layout object suitable for passing to further layouting functions. Adding this +#' function to an `rtable` layout will split the table into columns corresponding to +#' statistics `df`, `estimate`, `std_error`, `odds_ratio`, `ci`, and `pvalue`. +#' #' @export logistic_regression_cols <- function(lyt, conf_level = 0.95) { @@ -312,12 +322,14 @@ logistic_regression_cols <- function(lyt, #' #' @description `r lifecycle::badge("stable")` #' -#' Constructor for content functions to be used to summarize +#' Constructor for content functions to be used in [`summarize_logistic()`] to summarize #' logistic regression results. #' #' @param flag_var (`string`)\cr variable name identifying which row should be used in this #' content function. #' +#' @return A content function. +#' #' @export logistic_summary_by_flag <- function(flag_var) { checkmate::assert_string(flag_var) diff --git a/R/missing_data.R b/R/missing_data.R index 52a56c9667..dd3dce4923 100644 --- a/R/missing_data.R +++ b/R/missing_data.R @@ -7,6 +7,8 @@ #' @param x factor or character vector #' @param label character string that missing data should be replaced with #' +#' @return `x` with any `NA` values substituted by `label`. +#' #' @export #' #' @examples @@ -42,6 +44,9 @@ explicit_na <- function(x, label = "") { #' @param empty boolean if true empty strings get replaced by \code{NA} #' @param whitespaces boolean, if true then strings made from whitespaces only get replaced with \code{NA} #' +#' @return `x` with `""` and/or whitespace-only values substituted by `NA`, depending on the values of +#' `empty` and `whitespaces`. +#' #' @export #' #' @examples diff --git a/R/odds_ratio.R b/R/odds_ratio.R index a4ae3c1cc0..88723bcdcd 100644 --- a/R/odds_ratio.R +++ b/R/odds_ratio.R @@ -8,22 +8,29 @@ #' @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 that, for stratified analyses, there is currently no -#' implementation for conditional likelihood confidence intervals, -#' therefore the likelihood confidence interval as an option is not yet -#' available. Besides, when `rsp` contains only responders or non-responders, -#' then the result values will be `NA`, because no odds ratio estimation is -#' possible. +#' 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. +#' #' @seealso Relevant helper function [h_odds_ratio()]. #' #' @name odds_ratio NULL #' @describeIn odds_ratio Statistics function which estimates the odds ratio -#' between a treatment and a control. Note that a `variables` list with `arm` and `strata` names -#' needs to be passed if a stratified analysis is required. +#' between a treatment and a control. A `variables` list with `arm` and `strata` +#' variable names must be passed if a stratified analysis is required. +#' #' @inheritParams split_cols_by_groups #' @inheritParams argument_convention +#' +#' @return +#' * `s_odds_ratio()` returns a named list with the statistics `or_ci` +#' (containing `est`, `lcl`, and `ucl`) and `n_tot`. +#' #' @export #' #' @examples @@ -134,8 +141,10 @@ s_odds_ratio <- function(df, y } -#' @describeIn odds_ratio Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn odds_ratio Formatted analysis function which is used as `afun` in `estimate_odds_ratio()`. +#' +#' @return +#' * `a_odds_ratio()` returns the corresponding list with formatted [rtables::CellValue()]. #' @export #' #' @examples @@ -152,12 +161,17 @@ a_odds_ratio <- make_afun( .indent_mods = c(or_ci = 1L) ) -#' @describeIn odds_ratio Layout creating function which can be used for creating -#' tables, which can take statistics function arguments and additional format -#' arguments (see below). +#' @describeIn odds_ratio Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @param ... arguments passed to `s_odds_ratio()`. +#' +#' @return +#' * `estimate_odds_ratio()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_odds_ratio()` to the table layout. +#' #' @export #' #' @examples @@ -208,12 +222,14 @@ estimate_odds_ratio <- function(lyt, #' @param data (`data.frame`)\cr data frame containing at least the variables `rsp` and `grp`, and optionally #' `strata` for [or_clogit()]. #' +#' @return A named `list` of elements `or_ci` and `n_tot`. +#' #' @seealso [odds_ratio] #' #' @name h_odds_ratio NULL -#' @describeIn h_odds_ratio estimates the odds ratio based on [stats::glm()]. Note that there must be +#' @describeIn h_odds_ratio Estimates the odds ratio based on [stats::glm()]. Note that there must be #' exactly 2 groups in `data` as specified by the `grp` variable. #' #' @export diff --git a/R/package.R b/R/package.R index 5aba49c81c..56f505f303 100644 --- a/R/package.R +++ b/R/package.R @@ -12,6 +12,7 @@ #' @importFrom magrittr %>% #' @importFrom rlang .data := !! #' @importFrom survival coxph strata Surv +#' @importFrom stats pchisq NULL # We need this to avoid R CMD check warning about missing global definitions. diff --git a/R/prop_diff.R b/R/prop_diff.R index b092b12ac3..d6ecced1bd 100644 --- a/R/prop_diff.R +++ b/R/prop_diff.R @@ -15,6 +15,9 @@ NULL #' @inheritParams prop_diff_strat_nc #' @param method (`string`)\cr the method used for the confidence interval estimation. #' +#' @return +#' * `s_proportion_diff()` returns a named list of elements `diff` and `diff_ci`. +#' #' @examples #' # Summary #' @@ -133,8 +136,10 @@ s_proportion_diff <- function(df, y } -#' @describeIn prop_diff Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn prop_diff Formatted analysis function which is used as `afun` in `estimate_proportion_diff()`. +#' +#' @return +#' * `a_proportion_diff()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' a_proportion_diff( @@ -153,15 +158,17 @@ a_proportion_diff <- make_afun( .indent_mods = c(diff = 0L, diff_ci = 1L) ) -#' @describeIn prop_diff Adds a descriptive analyze layer to `rtables` -#' pipelines. The analysis is applied to a `dataframe` and return the -#' estimations, in `rcells`. The ellipsis (`...`) conveys arguments to -#' `s_proportion_diff()`, for instance `na.rm = FALSE` if missing data -#' should be accounted for. +#' @describeIn prop_diff Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @param ... arguments passed to `s_proportion_diff()`. #' +#' @return +#' * `estimate_proportion_diff()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_proportion_diff()` to the table layout. +#' #' @examples #' l <- basic_table() %>% #' split_cols_by(var = "grp", ref_group = "B") %>% @@ -238,7 +245,9 @@ check_diff_prop_ci <- function(rsp, #' #' @inheritParams s_proportion_diff #' @param long (`logical`)\cr Whether a long or a short (default) description is required. -#' @return String describing the analysis. +#' +#' @return A `string` describing the analysis. +#' #' @seealso [prop_diff] #' #' @export @@ -280,6 +289,9 @@ d_proportion_diff <- function(conf_level, #' @param grp (`factor`)\cr vector assigning observations to one out of two groups #' (e.g. reference and treatment group). #' +#' @return A named `list` of elements `diff` (proportion difference) and `diff_ci` +#' (proportion difference confidence interval). +#' #' @seealso [prop_diff()] for implementation of these helper functions. #' #' @name h_prop_diff diff --git a/R/prop_diff_test.R b/R/prop_diff_test.R index ad43402e3a..f89d277e2b 100644 --- a/R/prop_diff_test.R +++ b/R/prop_diff_test.R @@ -7,10 +7,10 @@ #' #' @param tbl (`matrix`)\cr matrix with two groups in rows and the binary response #' (`TRUE`/`FALSE`) in columns. +#' #' @seealso [h_prop_diff_test] #' #' @name prop_diff_test -#' NULL #' @describeIn prop_diff_test Statistics function which tests the difference @@ -20,9 +20,9 @@ NULL #' @param method (`string`)\cr one of `chisq`, `cmh`, `fisher`, or `schouten`; specifies the test used #' to calculate the p-value. #' -#' @return Named `list` with a single item `pval` with an attribute `label` -#' describing the method used. The p-value tests the null hypothesis that -#' proportions in two groups are the same. +#' @return +#' * `s_test_proportion_diff()` returns a named `list` with a single item `pval` with an attribute `label` +#' describing the method used. The p-value tests the null hypothesis that proportions in two groups are the same. #' #' @examples #' @@ -101,6 +101,7 @@ s_test_proportion_diff <- function(df, #' `s_test_proportion_diff`. #' #' @inheritParams s_test_proportion_diff +#' #' @return `string` describing the test from which the p-value is derived. #' #' @export @@ -116,8 +117,10 @@ d_test_proportion_diff <- function(method) { paste0("p-value (", meth_part, ")") } -#' @describeIn prop_diff_test Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn prop_diff_test Formatted analysis function which is used as `afun` in `test_proportion_diff()`. +#' +#' @return +#' * `a_test_proportion_diff()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_test_proportion_diff @@ -139,11 +142,17 @@ a_test_proportion_diff <- make_afun( .indent_mods = c(pval = 1L) ) -#' @describeIn prop_diff_test Layout creating function which can be used for -#' creating tables, which can take statistics function arguments and -#' additional format arguments. +#' @describeIn prop_diff_test Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' #' @param ... other arguments are passed to [s_test_proportion_diff()]. #' @inheritParams argument_convention +#' +#' @return +#' * `test_proportion_diff()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_test_proportion_diff()` to the table layout. +#' #' @export #' #' @examples @@ -192,6 +201,8 @@ test_proportion_diff <- function(lyt, #' @param tbl (`matrix`)\cr matrix with two groups in rows and the binary response #' (`TRUE`/`FALSE`) in columns. #' +#' @return A p-value. +#' #' @seealso [prop_diff_test())] for implementation of these helper functions. #' #' @name h_prop_diff_test diff --git a/R/prune_occurrences.R b/R/prune_occurrences.R index 8b7bd4007a..cf0dcd1c16 100644 --- a/R/prune_occurrences.R +++ b/R/prune_occurrences.R @@ -9,9 +9,8 @@ #' #' @note Since most table specifications are worded positively, we name our constructor and condition #' functions positively, too. However, note that the result of [keep_rows()] says what -#' should be pruned though, to conform with the [rtables::prune_table()] interface. +#' should be pruned, to conform with the [rtables::prune_table()] interface. #' -#' @name prune_occurrences #' @examples #' \dontrun{ #' tab <- basic_table() %>% @@ -23,16 +22,21 @@ #' build_table(DM) #' } #' +#' @name prune_occurrences NULL -#' @describeIn prune_occurrences constructor for creating pruning functions based on +#' @describeIn prune_occurrences Constructor for creating pruning functions based on #' a row condition function. This removes all analysis rows (`TableRow`) that should be -#' pruned, i.e., don't fulfill the row condition. It removes the sub tree if there are no +#' pruned, i.e., don't fulfill the row condition. It removes the sub-tree if there are no #' children left. +#' #' @param row_condition (`CombinationFunction`)\cr condition function which works on individual #' analysis rows and flags whether these should be kept in the pruned table. -#' @return [keep_rows()] returns a pruning function that can be used with [rtables::prune_table()] -#' on `[rtables::TableTree()]` objects. +#' +#' @return +#' * `keep_rows()` returns a pruning function that can be used with [rtables::prune_table()] +#' to prune an `rtables` table. +#' #' @export #' #' @examples @@ -52,14 +56,16 @@ keep_rows <- function(row_condition) { } } -#' @describeIn prune_occurrences constructor for creating pruning functions based on +#' @describeIn prune_occurrences Constructor for creating pruning functions based on #' a condition for the (first) content row in leaf tables. This removes all leaf tables where #' the first content row does not fulfill the condition. It does not check individual rows. #' It then proceeds recursively by removing the sub tree if there are no children left. #' @param content_row_condition (`CombinationFunction`)\cr condition function which works on individual #' first content rows of leaf tables and flags whether these leaf tables should be kept in the pruned table. -#' @return [keep_content_rows()] also returns a pruning function, the difference is that it -#' checks the condition on the first content row of leaf tables in the table. +#' +#' @return +#' * `keep_content_rows()` returns a pruning function that checks the condition on the first content +#' row of leaf tables in the table. #' #' @examples #' # `keep_content_rows` @@ -85,14 +91,16 @@ keep_content_rows <- function(content_row_condition) { } } -#' @describeIn prune_occurrences constructor for creating condition functions on total counts in +#' @describeIn prune_occurrences Constructor for creating condition functions on total counts in #' the specified columns. #' @param atleast (`count` or `proportion`)\cr threshold which should be met in order to #' keep the row. #' @param ... arguments for row or column access, see [`rtables_access`]: either #' `col_names` (`character`) including the names of the columns which should be used, #' or alternatively `col_indices` (`integer`) giving the indices directly instead. -#' @return [has_count_in_cols()] returns a condition function that sums the counts in the specified +#' +#' @return +#' * `has_count_in_cols()` returns a condition function that sums the counts in the specified #' column. #' #' @examples @@ -112,12 +120,15 @@ has_count_in_cols <- function(atleast, ...) { }) } -#' @describeIn prune_occurrences constructor for creating condition functions on any of the counts in +#' @describeIn prune_occurrences Constructor for creating condition functions on any of the counts in #' the specified columns satisfying a threshold. #' @param atleast (`count` or `proportion`)\cr threshold which should be met in order to #' keep the row. -#' @return [has_count_in_any_col()] returns a condition function that compares the counts in the +#' +#' @return +#' * `has_count_in_any_col()` returns a condition function that compares the counts in the #' specified columns with the threshold. +#' #' @export #' #' @examples @@ -134,10 +145,13 @@ has_count_in_any_col <- function(atleast, ...) { }) } -#' @describeIn prune_occurrences constructor for creating condition functions on total fraction in +#' @describeIn prune_occurrences Constructor for creating condition functions on total fraction in #' the specified columns. -#' @return [has_fraction_in_cols()] returns a condition function that sums the counts in the +#' +#' @return +#' * `has_fraction_in_cols()` returns a condition function that sums the counts in the #' specified column, and computes the fraction by dividing by the total column counts. +#' #' @export #' #' @examples @@ -158,10 +172,13 @@ has_fraction_in_cols <- function(atleast, ...) { }) } -#' @describeIn prune_occurrences constructor for creating condition functions on any fraction in +#' @describeIn prune_occurrences Constructor for creating condition functions on any fraction in #' the specified columns. -#' @return [has_fraction_in_cols()] returns a condition function that looks at the fractions +#' +#' @return +#' * `has_fraction_in_any_col()` returns a condition function that looks at the fractions #' in the specified columns and checks whether any of them fulfill the threshold. +#' #' @export #' #' @examples @@ -178,10 +195,13 @@ has_fraction_in_any_col <- function(atleast, ...) { }) } -#' @describeIn prune_occurrences constructor for creating condition function that checks the difference +#' @describeIn prune_occurrences Constructor for creating condition function that checks the difference #' between the fractions reported in each specified column. -#' @return [has_fractions_difference()] returns a condition function that extracts the fractions of each +#' +#' @return +#' * `has_fractions_difference()` returns a condition function that extracts the fractions of each #' specified column, and computes the difference of the minimum and maximum. +#' #' @export #' #' @examples @@ -199,9 +219,11 @@ has_fractions_difference <- function(atleast, ...) { }) } -#' @describeIn prune_occurrences constructor for creating condition function that checks the difference +#' @describeIn prune_occurrences Constructor for creating condition function that checks the difference #' between the counts reported in each specified column. -#' @return [has_counts_difference()] returns a condition function that extracts the counts of each +#' +#' @return +#' * `has_counts_difference()` returns a condition function that extracts the counts of each #' specified column, and computes the difference of the minimum and maximum. #' #' @examples diff --git a/R/response_biomarkers_subgroups.R b/R/response_biomarkers_subgroups.R index ed136625d1..33273520dd 100644 --- a/R/response_biomarkers_subgroups.R +++ b/R/response_biomarkers_subgroups.R @@ -5,26 +5,27 @@ #' Tabulate the estimated effects of multiple continuous biomarker variables #' on a binary response endpoint across population subgroups. #' -#' @details These functions create a layout starting from a data frame which contains -#' the required statistics. The tables are then typically used as input for forest plots. -#' #' @param df (`data.frame`)\cr containing all analysis variables, as returned by #' [extract_rsp_biomarkers()]. -#' @param vars (`character`)\cr the name of statistics to be reported among -#' `n_tot` (total number of patients per group), -#' `n_rsp` (total number of responses per group), -#' `prop` (total response proportion per group), -#' `or` (odds ratio), -#' `ci` (confidence interval of odds ratio) and -#' `pval` (p value of the effect). -#' Note, the statistics `n_tot`, `or` and `ci` are required. +#' @param vars (`character`)\cr the names of statistics to be reported among: +#' * `n_tot`: Total number of patients per group. +#' * `n_rsp`: Total number of responses per group. +#' * `prop`: Total response proportion per group. +#' * `or`: Odds ratio. +#' * `ci`: Confidence interval of odds ratio. +#' * `pval`: p-value of the effect. +#' Note, the statistics `n_tot`, `or` and `ci` are required. +#' +#' @return An `rtables` table summarizing biomarker effects on binary response by subgroup. +#' +#' @details These functions create a layout starting from a data frame which contains +#' the required statistics. The tables are then typically used as input for forest plots. #' -#' @seealso [h_tab_rsp_one_biomarker()] which is used internally, [extract_rsp_biomarkers()]. #' @note In contrast to [tabulate_rsp_subgroups()] this tabulation function does #' not start from an input layout `lyt`. This is because internally the table is #' created by combining multiple subtables. -#' @name response_biomarkers_subgroups -#' @export +#' +#' @seealso [h_tab_rsp_one_biomarker()] which is used internally, [extract_rsp_biomarkers()]. #' #' @examples #' library(dplyr) @@ -51,6 +52,9 @@ #' ## Finally produce the forest plot. #' g_forest(tab, xlim = c(0.7, 1.4)) #' } +#' +#' @export +#' @name response_biomarkers_subgroups tabulate_rsp_biomarkers <- function(df, vars = c("n_tot", "n_rsp", "prop", "or", "ci", "pval")) { checkmate::assert_data_frame(df) @@ -98,10 +102,17 @@ tabulate_rsp_biomarkers <- function(df, #' @inheritParams response_subgroups #' @param control (named `list`)\cr controls for the response definition and the #' confidence level produced by [control_logistic()]. -#' @seealso [h_logistic_mult_cont_df()] which is used internally. +#' +#' @return A `data.frame` with columns `biomarker`, `biomarker_label`, `n_tot`, `n_rsp`, +#' `prop`, `or`, `lcl`, `ucl`, `conf_level`, `pval`, `pval_label`, `subgroup`, `var`, +#' `var_label`, and `row_type`. +#' #' @note You can also specify a continuous variable in `rsp` and then use the #' `response_definition` control to convert that internally to a logical #' variable reflecting binary response. +#' +#' @seealso [h_logistic_mult_cont_df()] which is used internally. +#' #' @export #' #' @examples diff --git a/R/response_subgroups.R b/R/response_subgroups.R index 4493adefa8..5c573e0b90 100644 --- a/R/response_subgroups.R +++ b/R/response_subgroups.R @@ -4,9 +4,6 @@ #' #' Tabulate statistics such as response rate and odds ratio for population subgroups. #' -#' @details These functions create a layout starting from a data frame which contains -#' the required statistics. Tables typically used as part of forest plot. -#' #' @inheritParams argument_convention #' @param data (`data.frame`)\cr the dataset containing the variables to summarize. #' @param groups_lists (named `list` of `list`)\cr optionally contains for each `subgroups` variable a @@ -15,7 +12,10 @@ #' @param label_all (`string`)\cr label for the total population analysis. #' @param method (`string`)\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. -#' @name response_subgroups +#' +#' @details These functions create a layout starting from a data frame which contains +#' the required statistics. Tables typically used as part of forest plot. +#' #' @seealso [extract_rsp_subgroups()] #' #' @examples @@ -42,6 +42,8 @@ #' data = adrs_f #' ) #' df +#' +#' @name response_subgroups NULL #' Prepares Response Data for Population Subgroups in Data Frames @@ -58,6 +60,13 @@ NULL #' @inheritParams argument_convention #' @inheritParams response_subgroups #' @param label_all (`string`)\cr label for the total population analysis. +#' +#' @return A named list of two elements: +#' * `prop`: A `data.frame` containing columns `arm`, `n`, `n_rsp`, `prop`, `subgroup`, `var`, +#' `var_label`, and `row_type`. +#' * `or`: A `data.frame` containing columns `arm`, `n_tot`, `or`, `lcl`, `ucl`, `conf_level`, +#' `subgroup`, `var`, `var_label`, and `row_type`. +#' #' @seealso [response_subgroups] #' @export #' @@ -130,8 +139,10 @@ extract_rsp_subgroups <- function(variables, list(prop = df_prop, or = df_or) } -#' @describeIn response_subgroups Formatted Analysis function used to format the results of [extract_rsp_subgroups()]. -#' Returns is a list of Formatted Analysis functions with one element per statistic. +#' @describeIn response_subgroups Formatted analysis function which is used as `afun` in `tabulate_rsp_subgroups()`. +#' +#' @return +#' * `a_response_subgroups()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_response_subgroups @@ -174,18 +185,23 @@ a_response_subgroups <- function(.formats = list( afun_lst } -#' @describeIn response_subgroups table creating function. +#' @describeIn response_subgroups Table-creating function which creates a table +#' summarizing binary response by subgroup. +#' #' @param df (`list`)\cr of data frames containing all analysis variables. List should be #' created using [extract_rsp_subgroups()]. -#' @param vars (`character`)\cr the name of statistics to be reported among -#' `n` (total number of observations per group), -#' `n_rsp` (number of responders per group), -#' `prop` (proportion of responders), -#' `n_tot` (total number of observations), -#' `or` (odds ratio), -#' `ci` (confidence interval of odds ratio) and -#' `pval` (p value of the effect). -#' Note, the statistics `n_tot`, `or` and `ci` are required. +#' @param vars (`character`)\cr the names of statistics to be reported among: +#' * `n`: Total number of observations per group. +#' * `n_rsp`: Number of responders per group. +#' * `prop`: Proportion of responders. +#' * `n_tot`: Total number of observations. +#' * `or`: Odds ratio. +#' * `ci` : Confidence interval of odds ratio. +#' * `pval`: p-value of the effect. +#' Note, the statistics `n_tot`, `or` and `ci` are required. +#' +#' @return An `rtables` table summarizing binary response by subgroup. +#' #' @export #' #' @examples @@ -329,7 +345,7 @@ tabulate_rsp_subgroups <- function(lyt, #' @inheritParams argument_convention #' @inheritParams tabulate_rsp_subgroups #' -#' @return `list` of variables to tabulate and their labels. +#' @return A `list` of variables to tabulate and their labels. #' #' @export d_rsp_subgroups_colvars <- function(vars, diff --git a/R/rtables_access.R b/R/rtables_access.R index ccffa5cac1..8d1971f246 100644 --- a/R/rtables_access.R +++ b/R/rtables_access.R @@ -1,6 +1,6 @@ #' `rtables` Access Helper Functions #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' These are a couple of functions that help with accessing the data in `rtables` objects. #' Currently these work for occurrence tables, which are defined @@ -11,7 +11,7 @@ #' @name rtables_access NULL -#' @describeIn rtables_access helper function to extract the first values from each content +#' @describeIn rtables_access Helper function to extract the first values from each content #' cell and from specified columns in a `TableRow`. Defaults to all columns. #' #' @param table_row (`TableRow`)\cr an analysis row in a occurrence table. @@ -21,6 +21,9 @@ NULL #' `table_row`. (Note that this currently only works well with a single #' column split.) #' +#' @return +#' * `h_row_first_values()` returns a `vector` of numeric values. +#' #' @examples #' tbl <- basic_table() %>% #' split_cols_by("ARM") %>% @@ -62,6 +65,9 @@ h_row_first_values <- function(table_row, #' @describeIn rtables_access Helper function that extracts row values and checks if they are #' convertible to integers (`integerish` values). #' +#' @return +#' * `h_row_counts()` returns a `vector` of numeric values. +#' #' @examples #' # Row counts (integer values) #' \dontrun{ @@ -85,6 +91,9 @@ h_row_counts <- function(table_row, #' in a `TableRow`. More specifically it extracts the second values from each #' content cell and checks it is a fraction. #' +#' @return +#' * `h_row_fractions()` returns a `vector` of proportions. +#' #' @examples #' # Row fractions #' tree_row_elem <- collect_leaves(tbl[4, ])[[1]] @@ -105,6 +114,9 @@ h_row_fractions <- function(table_row, #' in a table. #' @param table (`VTableNodeInfo`)\cr an occurrence table or row. #' +#' @return +#' * `h_col_counts()` returns a `vector` of column counts. +#' #' @export h_col_counts <- function(table, col_names = NULL, @@ -116,6 +128,9 @@ h_col_counts <- function(table, #' @describeIn rtables_access Helper function to get first row of content table of current table. #' +#' @return +#' * `h_content_first_row()` returns a row from an `rtables` table. +#' #' @export h_content_first_row <- function(table) { ct <- content_table(table) @@ -124,6 +139,9 @@ h_content_first_row <- function(table) { #' @describeIn rtables_access Helper function which says whether current table is a leaf in the tree. #' +#' @return +#' * `is_leaf_table()` returns a `logical` value indicating whether current table is a leaf. +#' #' @keywords internal is_leaf_table <- function(table) { children <- tree_children(table) @@ -133,6 +151,9 @@ is_leaf_table <- function(table) { #' @describeIn rtables_access Internal helper function that tests standard inputs for column indices. #' +#' @return +#' * `check_names_indices` returns column indices. +#' #' @keywords internal check_names_indices <- function(table_row, col_names = NULL, diff --git a/R/score_occurrences.R b/R/score_occurrences.R index 7237e171ad..eb13d89776 100644 --- a/R/score_occurrences.R +++ b/R/score_occurrences.R @@ -1,18 +1,19 @@ #' Occurrence Table Sorting #' +#' @description `r lifecycle::badge("stable")` +#' #' Functions to score occurrence table subtables and rows which can be used in the #' sorting of occurrence tables. #' #' @name score_occurrences -#' NULL -#' @description `r lifecycle::badge("stable")` #' @describeIn score_occurrences Scoring function which sums the counts across all #' columns. It will fail if anything else but counts are used. #' @inheritParams rtables_access #' -#' @return [score_occurrences()] returns the sum of counts across all columns of a table row. +#' @return +#' * `score_occurrences()` returns the sum of counts across all columns of a table row. #' #' @seealso [h_row_first_values()] #' @@ -54,7 +55,8 @@ score_occurrences <- function(table_row) { #' specific columns in the scoring. See [h_row_counts()] for further information. #' @inheritParams has_count_in_cols #' -#' @return [score_occurrences_cols()] returns a function that sums counts across all specified columns +#' @return +#' * `score_occurrences_cols()` returns a function that sums counts across all specified columns #' of a table row. #' #' @seealso [h_row_counts()] @@ -80,7 +82,9 @@ score_occurrences_cols <- function(...) { #' @describeIn score_occurrences Scoring functions produced by this constructor can be used on #' subtables: They sum up all specified column counts in the subtable. This is useful when #' there is no available content row summing up these counts. -#' @return [score_occurrences_subtable()] returns a function that sums counts in each subtable +#' +#' @return +#' * `score_occurrences_subtable()` returns a function that sums counts in each subtable #' across all specified columns. #' #' @export @@ -105,6 +109,11 @@ score_occurrences_subtable <- function(...) { #' @describeIn score_occurrences Produce score function for sorting table by summing the first content row in #' specified columns. Note that this is extending [rtables::cont_n_onecol()] and [rtables::cont_n_allcols()]. +#' +#' @return +#' * `score_occurrences_cont_cols()` returns a function that sums counts in the first content row in +#' specified columns. +#' #' @export #' score_occurrences_cont_cols <- function(...) { diff --git a/R/split_cols_by_groups.R b/R/split_cols_by_groups.R index 22e824c44a..596333a6f4 100644 --- a/R/split_cols_by_groups.R +++ b/R/split_cols_by_groups.R @@ -44,8 +44,8 @@ groups_list_to_df <- function(groups_list) { #' @param ref (`string`)\cr the reference level(s). #' @param collapse (`string`)\cr a character string to separate `fct` and `ref`. #' -#' @return a `list` with first item `ref` (reference) and second item `trt` -#' (treatment). +#' @return A `list` with first item `ref` (reference) and second item `trt` (treatment). +#' #' @export #' #' @examples @@ -88,14 +88,15 @@ combine_groups <- function(fct, #' #' @inheritParams argument_convention #' @inheritParams groups_list_to_df -#' @param ... additional arguments, see _note_ section. -#' -#' @note The ellipse (`...`) conveys arguments to [rtables::split_cols_by()] -#' in order, for instance, to control formats (`format`), add a joint column -#' for all groups (`incl_all`). +#' @param ... additional arguments to [rtables::split_cols_by()] in order. For instance, to +#' control formats (`format`), add a joint column for all groups (`incl_all`). #' #' @seealso [rtables::split_cols_by()] -#' @return the modified layout. +#' +#' @return A layout object suitable for passing to further layouting functions. Adding +#' this function to an `rtable` layout will add a column split including the given +#' groups to the table layout. +#' #' @export #' #' @examples @@ -223,6 +224,8 @@ split_cols_by_groups <- function(lyt, #' @inheritParams combine_groups #' @inheritParams groups_list_to_df #' +#' @return A `vector` of column counts. +#' #' @examples #' ref <- c("A: Drug X", "B: Placebo") #' groups <- combine_groups(fct = DM$ARM, ref = ref) diff --git a/R/stat.R b/R/stat.R index 74748374be..7a287358ae 100644 --- a/R/stat.R +++ b/R/stat.R @@ -14,6 +14,8 @@ #' @param geom_mean (`logical`)\cr `TRUE` when the geometric mean should be #' calculated #' +#' @return A named `vector` of values `mean_ci_lwr` and `mean_ci_upr`. +#' #' @export #' #' @examples @@ -93,6 +95,8 @@ stat_mean_ci <- function(x, #' #' @details The function was adapted from `DescTools/versions/0.99.35/source` #' +#' @return A named `vector` of values `median_ci_lwr` and `median_ci_upr`. +#' #' @export #' #' @examples @@ -148,6 +152,8 @@ stat_median_ci <- function(x, #' the p-value of the mean. #' @param test_mean (`number`)\cr mean value to test under the null hypothesis. #' +#' @return A p-value. +#' #' @examples #' stat_mean_pval(sample(10)) #' diff --git a/R/summarize_ancova.R b/R/summarize_ancova.R index 09325f6032..eaad76b3f7 100644 --- a/R/summarize_ancova.R +++ b/R/summarize_ancova.R @@ -25,6 +25,8 @@ NULL #' @param interaction_item (`character`)\cr name of the variable that should have interactions #' with arm. if the interaction is not needed, the default option is NULL. #' +#' @return The summary of a linear model. +#' #' @examples #' h_ancova( #' .var = "Sepal.Length", @@ -86,18 +88,16 @@ h_ancova <- function(.var, #' @param interaction_y (`character`)\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 -#' @return A named list of 5 statistics: -#' \describe{ -#' \item{n}{count of complete sample size for the group.} -#' \item{lsmean}{estimated marginal means in the group.} -#' \item{lsmean_diff}{difference in estimated marginal means in comparison to the reference group. +#' +#' @return +#' * `s_ancova()` returns a named list of 5 statistics: +#' * `n`: Count of complete sample size for the group. +#' * `lsmean`: Estimated marginal means in the group. +#' * `lsmean_diff`: Difference in estimated marginal means in comparison to the reference group. #' If working with the reference group, this will be empty. -#' } -#' \item{lsmean_diff_ci}{confidence level for difference in estimated marginal means in comparison to the -#' reference group. -#' } -#' \item{pval}{p-value (not adjusted for multiple comparisons).} -#' } +#' * `lsmean_diff_ci`: Confidence level for difference in estimated marginal means in comparison +#' to the reference group. +#' * `pval`: p-value (not adjusted for multiple comparisons). #' #' @examples #' library(dplyr) @@ -205,8 +205,10 @@ s_ancova <- function(df, } } -#' @describeIn summarize_ancova Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn summarize_ancova Formatted analysis function which is used as `afun` in `summarize_ancova()`. +#' +#' @return +#' * `a_ancova()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_ancova @@ -232,9 +234,15 @@ a_ancova <- make_afun( .null_ref_cells = FALSE ) -#' @describeIn summarize_ancova Layout creating function which can be be used for creating -#' summary tables for analysis of covariance (ANCOVA). +#' @describeIn summarize_ancova Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @inheritParams argument_convention +#' +#' @return +#' * `summarize_ancova()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_ancova()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/summarize_change.R b/R/summarize_change.R index 8aeb192a4d..c40e78e45d 100644 --- a/R/summarize_change.R +++ b/R/summarize_change.R @@ -8,12 +8,15 @@ #' or the change from baseline values (post-baseline) are then summarized. #' #' @name summarize_change -#' NULL +#' @describeIn summarize_change Statistics function that summarizes baseline or post-baseline visits. +#' #' @inheritParams argument_convention -#' @describeIn summarize_change Statistics Function that summarizes baseline or post-baseline visits. -#' @return See [s_summary.numeric()] for the return values. +#' +#' @return +#' * `s_change_from_baseline()` returns the same values returned by [`s_summary.numeric()`]. +#' #' @note The data in `df` must be either all be from baseline or post-baseline visits. Otherwise #' an error will be thrown. #' @@ -56,8 +59,10 @@ s_change_from_baseline <- function(df, s_summary(combined, na.rm = na.rm, ...) } -#' @describeIn summarize_change Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn summarize_change Formatted analysis function which is used as `afun` in `summarize_change()`. +#' +#' @return +#' * `a_change_from_baseline()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_change_from_baseline @@ -90,12 +95,19 @@ a_change_from_baseline <- make_afun( ) ) -#' @describeIn summarize_change Analyze Function for change from baseline analysis. -#' To be used after a split on visits in the layout, such that each data -#' subset only contains either baseline or post-baseline data. Allows additional -#' formatting options. +#' @describeIn summarize_change Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' #' @inheritParams argument_convention #' +#' @return +#' * `summarize_change()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_change_from_baseline()` to the table layout. +#' +#' @note To be used after a split on visits in the layout, such that each data subset only contains +#' either baseline or post-baseline data. +#' #' @export #' @examples #' diff --git a/R/summarize_colvars.R b/R/summarize_colvars.R index 2d021b5c1a..d1010f9159 100644 --- a/R/summarize_colvars.R +++ b/R/summarize_colvars.R @@ -2,13 +2,17 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' This Analyze Function uses the new S3 generic function [s_summary()] to summarize -#' different variables that are arranged in columns. -#' Additional standard formatting arguments are available. +#' 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. #' #' @inheritParams argument_convention #' @param ... arguments passed to `s_summary()`. #' +#' @return +#' A layout object suitable for passing to further layouting functions, or to [rtables::build_table()]. +#' Adding this function to an `rtable` layout will summarize the given variables, arrange the output +#' in columns, and add it to the table layout. +#' #' @seealso [rtables::split_cols_by_multivar()] #' #' @export diff --git a/R/summarize_coxreg.R b/R/summarize_coxreg.R index 041eeed4b5..723e7b810a 100644 --- a/R/summarize_coxreg.R +++ b/R/summarize_coxreg.R @@ -5,16 +5,15 @@ #' Fits a Cox regression model and estimates hazard ratio to describe the effect #' size in a survival analysis. #' -#' @details -#' Cox models are the most commonly used methods to estimate the magnitude of -#' the effect in survival analysis. It assumes proportional hazards: the ratio -#' of the hazards between groups (e.g., two arms) is constant over time. -#' This ratio is referred to as the "hazard ratio" (HR) and is one of the -#' most commonly reported metrics to describe the effect size in survival -#' analysis (NEST Team, 2020). -#' #' @inheritParams argument_convention #' +#' @details Cox models are the most commonly used methods to estimate the magnitude of +#' the effect in survival analysis. It assumes proportional hazards: the ratio +#' of the hazards between groups (e.g., two arms) is constant over time. +#' This ratio is referred to as the "hazard ratio" (HR) and is one of the +#' most commonly reported metrics to describe the effect size in survival +#' analysis (NEST Team, 2020). +#' #' @seealso [fit_coxreg] for relevant fitting functions, [h_cox_regression] for relevant #' helper functions, and [tidy_coxreg] for custom tidy methods. #' @@ -49,9 +48,8 @@ #' @name cox_regression NULL -#' @describeIn cox_regression transforms the tabulated results from [`fit_coxreg_univar()`] -#' and [`fit_coxreg_multivar()`] into a list. Not much calculation is done here, -#' it rather prepares the data to be used by the layout creating function. +#' @describeIn cox_regression Statistics function that transforms results tabulated +#' from [`fit_coxreg_univar()`] or [`fit_coxreg_multivar()`] into a list. #' #' @param model_df (`data.frame`)\cr contains the resulting model fit from a [`fit_coxreg`] #' function with tidying applied via [`broom::tidy()`]. @@ -63,13 +61,16 @@ NULL #' * `pval_inter`: p-value of the interaction effect between the treatment and the covariate (univariable only) #' @param .which_vars (`character`)\cr which rows should statistics be returned for from the given model. #' Defaults to "all". Other options include "var_main" for main effects, "inter" for interaction effects, -#' and "multi_lvl" for multivariable model covariate level rows. When `.which_vars` is "all" specific +#' and "multi_lvl" for multivariate model covariate level rows. When `.which_vars` is "all" specific #' variables can be selected by specifying `.var_nms`. #' @param .var_nms (`character`)\cr the `term` value of rows in `df` for which `.stats` should be returned. Typically #' this is the name of a variable. If using variable labels, `var` should be a vector of both the desired #' variable name and the variable label in that order to see all `.stats` related to that variable. When `.which_vars` #' is "var_main" `.var_nms` should be only the variable name. #' +#' @return +#' * `s_coxreg()` returns the selected statistic for from the Cox regression model for the selected variable(s). +#' #' @export #' #' @examples @@ -96,7 +97,7 @@ NULL #' df1_covs <- broom::tidy(univar_covs_model) #' s_coxreg(model_df = df1_covs, .stats = "hr", .var_nms = c("COVAR2", "Sex (F/M)")) #' -#' # Multivariable. +#' # Multivariate. #' m1_variables <- list( #' time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2") #' ) @@ -108,7 +109,7 @@ NULL #' .var_nms = c("COVAR1", "A Covariate Label") #' ) #' -#' # Multivariable without treatment arm - only "COVAR1" main effect +#' # Multivariate without treatment arm - only "COVAR1" main effect #' m2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2")) #' multivar_covs_model <- fit_coxreg_multivar(variables = m2_variables, data = dta_bladder) #' df2_covs <- broom::tidy(multivar_covs_model) @@ -142,7 +143,7 @@ s_coxreg <- function(model_df, .stats, .which_vars = "all", .var_nms = NULL) { ) } -#' @describeIn cox_regression Analysis function. It is used as `afun` in [rtables::analyze()] +#' @describeIn cox_regression Analysis function which is used as `afun` in [rtables::analyze()] #' and `cfun` in [rtables::summarize_row_groups()] within `summarize_coxreg()`. #' #' @param eff (`flag`)\cr whether treatment effect should be calculated. Defaults to `FALSE`. @@ -151,6 +152,9 @@ s_coxreg <- function(model_df, .stats, .which_vars = "all", .var_nms = NULL) { #' @param cache_env (`environment`)\cr an environment object used to cache the regression model in order to #' avoid repeatedly fitting the same model for every row in the table. Defaults to `NULL` (no caching). #' +#' @return +#' * `a_coxreg()` returns formatted [rtables::CellValue()]. +#' #' @examples #' tern:::a_coxreg( #' df = dta_bladder, @@ -248,10 +252,11 @@ a_coxreg <- function(df, ) } -#' @describeIn cox_regression layout creating function. +#' @describeIn cox_regression Layout-creating function which creates a Cox regression summary table +#' layout. This function is a wrapper for several `rtables` layouting functions. #' #' @inheritParams fit_coxreg_univar -#' @param multivar (`flag`)\cr Defaults to `FALSE`. If `TRUE` multivariable Cox regression will run, otherwise +#' @param multivar (`flag`)\cr Defaults to `FALSE`. If `TRUE` multivariate Cox regression will run, otherwise #' univariable Cox regression will run. #' @param common_var (`character`)\cr the name of a factor variable in the dataset which takes the same value #' for all rows. This should be created during pre-processing if no such variable currently exists. @@ -259,9 +264,14 @@ a_coxreg <- function(df, #' Defaults to `NA` for no section divider. If a vector of two strings are given, the first will be used between #' treatment and covariate sections and the second between different covariates. #' +#' @return +#' * `summarize_coxreg()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add a Cox regression table +#' containing the chosen statistics to the table layout. +#' #' @export #' @seealso [fit_coxreg_univar()] and [fit_coxreg_multivar()] which also take the `variables`, `data`, -#' `at` (univariable only), and `control` arguments but return unformatted univariable and multivariable +#' `at` (univariable only), and `control` arguments but return unformatted univariable and multivariate #' Cox regression models, respectively. #' #' @examples @@ -313,7 +323,7 @@ summarize_coxreg <- function(lyt, .section_div = NA_character_) { if (multivar && control$interaction) { warning(paste( - "Interactions are not available for multivariable cox regression using summarize_coxreg.", + "Interactions are not available for multivariate cox regression using summarize_coxreg.", "The model will be calculated without interaction effects." )) } diff --git a/R/summarize_glm_count.R b/R/summarize_glm_count.R index 2ca78330e6..5c5233c79e 100644 --- a/R/summarize_glm_count.R +++ b/R/summarize_glm_count.R @@ -6,7 +6,6 @@ #' This can be used to analyze count and/or frequency data using a linear model. #' #' @name summarize_glm_count -#' NULL #' Helper Functions for Poisson Models. @@ -18,7 +17,6 @@ NULL #' @seealso [summarize_glm_count] #' #' @name h_glm_count -#' NULL #' @describeIn h_glm_count Helper function to return results of a poisson model. @@ -28,15 +26,18 @@ NULL #' in `.var` and `variables`. #' @param variables (named `list` of `strings`)\cr list of additional analysis variables, with #' expected elements: -#' - `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple +#' * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple #' groups will be summarized. Specifically, the first level of `arm` variable is taken as the #' reference group. -#' - `covariates` (`character`)\cr a vector that can contain single variable names (such as +#' * `covariates` (`character`)\cr a vector that can contain single variable names (such as #' `"X1"`), and/or interaction terms indicated by `"X1 * X2"`. -#' - `offset` (`numeric`)\cr a numeric vector or scalar adding an offset. +#' * `offset` (`numeric`)\cr a numeric vector or scalar adding an offset. #' @param `weights`(`character`)\cr a character vector specifying weights used -#' in averaging predictions. Number of weights must equal the number of levels included in the covariates. -#' Weights option passed to emmeans function (hyperlink) (link to emmeans documentation) +#' in averaging predictions. Number of weights must equal the number of levels included in the covariates. +#' Weights option passed to emmeans function (hyperlink) (link to emmeans documentation) +#' +#' @return +#' * `h_glm_poisson()` returns the results of a Poisson model. #' #' @examples #' # Internal function - h_glm_poisson @@ -88,16 +89,20 @@ h_glm_poisson <- function(.var, } #' @describeIn h_glm_count Helper function to return results of a quasipoisson model. +#' #' @inheritParams argument_convention #' @inheritParams summarize_glm_count #' +#' @return +#' * `h_glm_quasipoisson()` returns the results of a Quasi-Poisson model. +#' #' @examples #' #' # Internal function - h_glm_quasipoisson #' \dontrun{ #' h_glm_quasipoisson( #' .var = "AVAL", -#' .df_row = anl, +#' .df_row = adtte, #' variables = list(arm = "ARM", offset = "lgTMATRSK", covariates = c("REGION1")) #' ) #' } @@ -149,16 +154,19 @@ h_glm_quasipoisson <- function(.var, #' in `.var` and `variables`. #' @param variables (named `list` of `strings`)\cr list of additional analysis variables, with #' expected elements: -#' - `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple +#' * `arm` (`string`)\cr group variable, for which the covariate adjusted means of multiple #' groups will be summarized. Specifically, the first level of `arm` variable is taken as the #' reference group. -#' - `covariates` (`character`)\cr a vector that can contain single variable names (such as +#' * `covariates` (`character`)\cr a vector that can contain single variable names (such as #' `"X1"`), and/or interaction terms indicated by `"X1 * X2"`. -#' - `offset` (`numeric`)\cr a numeric vector or scalar adding an offset. +#' * `offset` (`numeric`)\cr a numeric vector or scalar adding an offset. #' @param `weights`(`character`)\cr character vector specifying weights used in averaging predictions. #' @param `distribution`(`character`)\cr a character value specifying the distribution #' used in the regression (poisson, quasipoisson). #' +#' @return +#' * `h_glm_count()` returns the results of the selected model. +#' #' @examples #' # Internal function - h_glm_count #' \dontrun{ @@ -198,6 +206,9 @@ h_glm_count <- function(.var, #' groups will be summarized. Specifically, the first level of `arm` variable is taken as the #' reference group. #' +#' @return +#' * `h_ppmeans()` returns the estimated means. +#' #' @examples #' # Internal function - h_ppmeans #' \dontrun{ @@ -254,19 +265,19 @@ h_ppmeans <- function(obj, .df_row, arm, conf_level) { } #' @describeIn summarize_glm_count Statistics function that produces a named list of results -#' of the investigated poisson model. +#' of the investigated Poisson model. #' #' @inheritParams argument_convention #' @inheritParams h_glm_count -#' @return A named list of 5 statistics: -#' \describe{ -#' \item{n}{count of complete sample size for the group.} -#' \item{rate}{estimated event rate per follow-up time.} -#' \item{rate_ci}{confidence level for estimated rate per follow-up time.} -#' \item{rate_ratio}{ratio of event rates in each treatment arm to the reference arm.} -#' \item{rate_ratio_ci}{confidence level for the rate ratio.} -#' \item{pval}{p-value.} -#' } +#' +#' @return +#' * `s_glm_count()` returns a named `list` of 5 statistics: +#' * `n`: Count of complete sample size for the group. +#' * `rate`: Estimated event rate per follow-up time. +#' * `rate_ci`: Confidence level for estimated rate per follow-up time. +#' * `rate_ratio`: Ratio of event rates in each treatment arm to the reference arm. +#' * `rate_ratio_ci`: Confidence level for the rate ratio. +#' * `pval`: p-value. #' #' @examples #' # Internal function - s_change_from_baseline @@ -373,8 +384,10 @@ s_glm_count <- function(df, } } -#' @describeIn summarize_glm_count Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn summarize_glm_count Formatted analysis function which is used as `afun` in `summarize_glm_count()`. +#' +#' @return +#' * `a_glm_count()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' @@ -415,9 +428,16 @@ a_glm_count <- make_afun( .null_ref_cells = FALSE ) -#' @describeIn summarize_glm_count Layout creating function which can be be used for creating -#' summary tables for analysis of count data using generalized linear models (poisson, quasipoisson). +#' @describeIn summarize_glm_count Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' #' @inheritParams argument_convention +#' +#' @return +#' * `summarize_glm_count()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_glm_count()` to the table layout. +#' #' @export #' @examples #' library(dplyr) diff --git a/R/summarize_num_patients.R b/R/summarize_num_patients.R index a69fec57ea..9731404360 100644 --- a/R/summarize_num_patients.R +++ b/R/summarize_num_patients.R @@ -1,4 +1,4 @@ -#' Number of patients +#' Number of Patients #' #' @description `r lifecycle::badge("stable")` #' @@ -7,9 +7,9 @@ #' @inheritParams argument_convention #' @param x (`character` or `factor`)\cr vector of patient IDs. #' @param count_by (`character` or `factor`)\cr optional vector to be combined with `x` when counting -#' `nonunique` records. +#' `nonunique` records. #' @param unique_count_suffix (`logical`)\cr should `"(n)"` suffix be added to `unique_count` labels. -#' Defaults to `TRUE`. +#' Defaults to `TRUE`. #' #' @name summarize_num_patients NULL @@ -18,12 +18,11 @@ NULL #' unique patients, the corresponding percentage taken with respect to the #' total number of patients, and the number of non-unique patients. #' -#' @return A list with: -#' \describe{ -#' \item{unique}{vector of count and percentage.} -#' \item{nonunique}{vector of count.} -#' \item{unique_count}{count.} -#' } +#' @return +#' * `s_num_patients()` returns a named `list` of 3 statistics: +#' * `unique`: Vector of counts and percentages. +#' * `nonunique`: Vector of counts. +#' * `unique_count`: Counts. #' #' @examples #' # Use the statistics function to count number of unique and nonunique patients. @@ -61,13 +60,15 @@ s_num_patients <- function(x, labelstr, .N_col, count_by = NULL, unique_count_su out } -#' @describeIn summarize_num_patients Counts the number of unique patients 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. -#' Function serves as a wrapper that carries over both expected arguments `df` -#' and `labelstr` in `cfun` of [summarize_row_groups()]. +#' @describeIn summarize_num_patients Statistics function which counts the number of unique patients +#' 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()`. +#' #' @export #' #' @examples @@ -120,8 +121,13 @@ c_num_patients <- make_afun( .formats = c(unique = format_count_fraction_fixed_dp, nonunique = "xx", unique_count = "xx") ) -#' @describeIn summarize_num_patients Layout creating function which adds content rows using the statistics -#' function [s_num_patients_content()] and desired format. +#' @describeIn summarize_num_patients Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()]. +#' +#' @return +#' * `summarize_num_patients()` returns a layout object suitable for passing to further layouting functions, +#' 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. #' #' @export summarize_num_patients <- function(lyt, @@ -153,10 +159,13 @@ summarize_num_patients <- function(lyt, ) } -#' @describeIn summarize_num_patients Identically to [summarize_num_patients()], -#' This function creates a layout which adds content rows using the statistics -#' function [s_num_patients_content()] and desired format. Differently from its -#' counterpart, this function does not impose the produced rows to be repeated. +#' @describeIn summarize_num_patients Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `analyze_num_patients()` returns a layout object suitable for passing to further layouting functions, +#' 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. #' #' @details In general, functions that starts with `analyze*` are expected to #' work like [rtables::analyze()], while functions that starts with `summarize*` @@ -165,6 +174,8 @@ summarize_num_patients <- function(lyt, #' bound to the fundamental splits, it is repeated by design in every page #' when pagination is involved. #' +#' @note As opposed to [summarize_num_patients()], this function does not repeat the produced rows. +#' #' @examples #' df_tmp <- data.frame( #' USUBJID = as.character(c(1, 2, 1, 4, NA, 6, 6, 8, 9)), diff --git a/R/summarize_patients_exposure_in_cols.R b/R/summarize_patients_exposure_in_cols.R index 96e82e1670..5bf6d69ccd 100644 --- a/R/summarize_patients_exposure_in_cols.R +++ b/R/summarize_patients_exposure_in_cols.R @@ -6,20 +6,19 @@ #' when a column table layout is required. #' #' @name summarize_patients_exposure_in_cols -#' NULL #' @describeIn summarize_patients_exposure_in_cols Statistics function which counts numbers -#' of patients and the sum of exposure across all patients. +#' of patients and the sum of exposure across all patients. #' #' @inheritParams argument_convention #' @param custom_label (`string` or `NULL`)\cr if provided and `labelstr` is empty then this will #' be used as label. -#' @return [s_count_patients_sum_exposure()] returns a list with the statistics: -#' \describe{ -#' \item{n_patients}{number of unique patients in `df`.} -#' \item{sum_exposure}{sum of `.var` across all patients in `df`.} -#' } +#' +#' @return +#' * `s_count_patients_sum_exposure()` returns a named `list` with the statistics: +#' * `n_patients`: Number of unique patients in `df`. +#' * `sum_exposure`: Sum of `.var` across all patients in `df`. #' #' @examples #' set.seed(1) @@ -85,12 +84,20 @@ s_count_patients_sum_exposure <- function(df, # nolintr y } -#' @describeIn summarize_patients_exposure_in_cols Layout creating function which adds the count -#' statistics of patients and the sum of analysis value in the column layout as content rows. +#' @describeIn summarize_patients_exposure_in_cols Layout-creating function which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for +#' [rtables::split_cols_by_multivar()] and [rtables::summarize_row_groups()]. #' #' @inheritParams argument_convention #' @param col_split (`flag`)\cr whether the columns should be split. Set to `FALSE` when the required #' column split has been done already earlier in the layout pipe. +#' +#' @return +#' * `summarize_patients_exposure_in_cols()` returns a layout object suitable for passing to further +#' layouting functions, or to [rtables::build_table()]. Adding this function to an `rtable` layout will +#' add formatted rows, with the statistics from `s_count_patients_sum_exposure()` arranged in +#' columns, to the table layout. +#' #' @export #' #' @examples diff --git a/R/summarize_variables.R b/R/summarize_variables.R index 687721b68a..18f0f7d9c5 100644 --- a/R/summarize_variables.R +++ b/R/summarize_variables.R @@ -37,6 +37,8 @@ control_summarize_vars <- function(conf_level = 0.95, #' @param type (`string`)\cr choice of a summary data type. #' Only `counts` and `numeric` types are currently supported. #' +#' @return A named `vector` of default statistic formats for the given data type. +#' #' @keywords internal summary_formats <- function(type = "numeric") { if (type == "counts") { @@ -81,6 +83,8 @@ summary_formats <- function(type = "numeric") { #' #' Returns labels of descriptive statistics for numeric variables. #' +#' @return A named `vector` of default statistic labels. +#' #' @keywords internal summary_labels <- function() { c( @@ -108,17 +112,18 @@ summary_labels <- function() { #' #' @description `r lifecycle::badge("stable")` #' -#' We use the new S3 generic function [s_summary()] to implement summaries for -#' different `x` objects. This is used as Statistics Function in combination -#' with the new Analyze Function [summarize_vars()]. +#' We use the S3 generic function [s_summary()] to implement summaries for different `x` objects. This +#' is used as a statistics function in combination with the analyze function [summarize_vars()]. +#' +#' @inheritParams argument_convention #' #' @name summarize_variables NULL -#' @inheritParams argument_convention +#' @describeIn summarize_variables S3 generic function to produces a variable summary. #' -#' @describeIn summarize_variables `s_summary` is a S3 generic function to produce -#' an object description. +#' @return +#' * `s_summary()` returns different statistics depending on the class of `x`. #' #' @export s_summary <- function(x, @@ -133,12 +138,7 @@ s_summary <- function(x, UseMethod("s_summary", x) } -#' @describeIn summarize_variables Method for numeric class. Note that, -#' if `x` is an empty vector, `NA` is returned. This is the expected -#' feature so as to return `rcell` content in `rtables` when the -#' intersection of a column and a row delimits an empty data selection. -#' Also, when the `mean` function is applied to an empty vector, `NA` will -#' be returned instead of `NaN`, the latter being standard behavior in R. +#' @describeIn summarize_variables Method for `numeric` class. #' #' @param control (`list`)\cr parameters for descriptive statistics details, specified by using #' the helper function [control_summarize_vars()]. Some possible parameter options are: @@ -148,34 +148,40 @@ s_summary <- function(x, #' See more about `type` in [stats::quantile()]. #' * `test_mean` (`numeric`)\cr value to test against the mean under the null hypothesis when calculating p-value. #' -#' @return If `x` is of class `numeric`, returns a list with the following named `numeric` items: -#' \describe{ -#' \item{n}{the [length()] of `x`.} -#' \item{sum}{the [sum()] of `x`.} -#' \item{mean}{the [mean()] of `x`.} -#' \item{sd}{the [stats::sd()] of `x`.} -#' \item{se}{the standard error of `x` mean, i.e.: (`sd(x) / sqrt(length(x))`).} -#' \item{mean_sd}{the [mean()] and [stats::sd()] of `x`.} -#' \item{mean_se}{the [mean()] of `x` and its standard error (see above).} -#' \item{mean_ci}{the CI for the mean of `x` (from [stat_mean_ci()]).} -#' \item{mean_sei}{the SE interval for the mean of `x`, i.e.: ([mean()] -/+ [stats::sd()] / [sqrt()]).} -#' \item{mean_sdi}{the SD interval for the mean of `x`, i.e.: ([mean()] -/+ [stats::sd()]).} -#' \item{mean_pval}{the two-sided p-value of the mean of `x` (from [stat_mean_pval()]).} -#' \item{median}{the [stats::median()] of `x`.} -#' \item{mad}{the median absolute deviation of `x`, i.e.: ([stats::median()] of `xc`, -#' where `xc` = `x` - [stats::median()]). -#' } -#' \item{median_ci}{the CI for the median of `x` (from [stat_median_ci()]).} -#' \item{quantiles}{two sample quantiles of `x` (from [stats::quantile()]).} -#' \item{iqr}{the [stats::IQR()] of `x`.} -#' \item{range}{the [range_noinf()] of `x`.} -#' \item{min}{the [max()] of `x`.} -#' \item{max}{the [min()] of `x`.} -#' \item{median_range}{the [median()] and [range_noinf()] of `x`.} -#' \item{cv}{the coefficient of variation of `x`, i.e.: ([stats::sd()] / [mean()] * 100).} -#' \item{geom_mean}{the geometric mean of `x`, i.e.: (`exp(mean(log(x)))`).} -#' \item{geom_cv}{the geometric coefficient of variation of `x`, i.e.: (`sqrt(exp(sd(log(x)) ^ 2) - 1) * 100`).} -#' } +#' @return +#' * If `x` is of class `numeric`, returns a `list` with the following named `numeric` items: +#' * `n`: The [length()] of `x`. +#' * `sum`: The [sum()] of `x`. +#' * `mean`: The [mean()] of `x`. +#' * `sd`: The [stats::sd()] of `x`. +#' * `se`: The standard error of `x` mean, i.e.: (`sd(x) / sqrt(length(x))`). +#' * `mean_sd`: The [mean()] and [stats::sd()] of `x`. +#' * `mean_se`: The [mean()] of `x` and its standard error (see above). +#' * `mean_ci`: The CI for the mean of `x` (from [stat_mean_ci()]). +#' * `mean_sei`: The SE interval for the mean of `x`, i.e.: ([mean()] -/+ [stats::sd()] / [sqrt()]). +#' * `mean_sdi`: The SD interval for the mean of `x`, i.e.: ([mean()] -/+ [stats::sd()]). +#' * `mean_pval`: The two-sided p-value of the mean of `x` (from [stat_mean_pval()]). +#' * `median`: The [stats::median()] of `x`. +#' * `mad`: The median absolute deviation of `x`, i.e.: ([stats::median()] of `xc`, +#' where `xc` = `x` - [stats::median()]). +#' * `median_ci`: The CI for the median of `x` (from [stat_median_ci()]). +#' * `quantiles`: Two sample quantiles of `x` (from [stats::quantile()]). +#' * `iqr`: The [stats::IQR()] of `x`. +#' * `range`: The [range_noinf()] of `x`. +#' * `min`: The [max()] of `x`. +#' * `max`: The [min()] of `x`. +#' * `median_range`: The [median()] and [range_noinf()] of `x`. +#' * `cv`: The coefficient of variation of `x`, i.e.: ([stats::sd()] / [mean()] * 100). +#' * `geom_mean`: The geometric mean of `x`, i.e.: (`exp(mean(log(x)))`). +#' * `geom_cv`: The geometric coefficient of variation of `x`, i.e.: (`sqrt(exp(sd(log(x)) ^ 2) - 1) * 100`). +#' +#' @note +#' * If `x` is an empty vector, `NA` is returned. This is the expected +#' feature so as to return `rcell` content in `rtables` when the +#' intersection of a column and a row delimits an empty data selection. +#' * When the `mean` function is applied to an empty vector, `NA` will +#' be returned instead of `NaN`, the latter being standard behavior in R. +#' #' @method s_summary numeric #' #' @examples @@ -299,25 +305,26 @@ s_summary.numeric <- function(x, # nolint y } -#' @describeIn summarize_variables Method for factor class. Note that, -#' if `x` is an empty factor, then still a list is returned for `counts` with one element -#' per factor level. If there are no levels in `x`, the function fails. If `x` contains `NA`, -#' it is expected that `NA` have been conveyed to `na_level` appropriately beforehand with -#' [df_explicit_na()] or [explicit_na()]. +#' @describeIn summarize_variables Method for `factor` class. #' #' @param denom (`string`)\cr choice of denominator for factor proportions. Options are: #' - `n`: number of values in this row and column intersection. #' - `N_row`: total number of values in this row across columns. #' - `N_col`: total number of values in this column across rows. #' -#' @return If `x` is of class `factor` or converted from `character`, returns a list with named `numeric` items: -#' \describe{ -#' \item{n}{the [length()] of `x`.} -#' \item{count}{a list with the number of cases for each level of the factor `x`.} -#' \item{count_fraction}{similar to `count` but also includes the proportion of cases for each level of the -#' factor `x` relative to the denominator, or `NA` if the denominator is zero. -#' } -#' } +#' @return +#' * If `x` is of class `factor` or converted from `character`, returns a `list` with named `numeric` items: +#' * `n`: The [length()] of `x`. +#' * `count`: A list with the number of cases for each level of the factor `x`. +#' * `count_fraction`: Similar to `count` but also includes the proportion of cases for each level of the +#' factor `x` relative to the denominator, or `NA` if the denominator is zero. +#' +#' @note +#' * If `x` is an empty `factor`, a list is still returned for `counts` with one element +#' per factor level. If there are no levels in `x`, the function fails. +#' * If `x` contains `NA`, it is expected that `NA` have been conveyed to `na_level` +#' appropriately beforehand with [df_explicit_na()] or [explicit_na()]. +#' #' @method s_summary factor #' #' @examples @@ -374,14 +381,17 @@ s_summary.factor <- function(x, y } -#' @describeIn summarize_variables Method for character class. This makes an automatic +#' @describeIn summarize_variables Method for `character` class. This makes an automatic #' conversion to factor (with a warning) and then forwards to the method for factors. +#' #' @param verbose defaults to `TRUE`. It prints out warnings and messages. It is mainly used #' to print out information about factor casting. +#' #' @note Automatic conversion of character to factor does not guarantee that the table #' can be generated correctly. In particular for sparse tables this very likely can fail. #' It is therefore better to always pre-process the dataset such that factors are manually #' created from character variables before passing the dataset to [rtables::build_table()]. +#' #' @method s_summary character #' #' @export @@ -413,21 +423,20 @@ s_summary.character <- function(x, ) } -#' @describeIn summarize_variables Method for logical class. +#' @describeIn summarize_variables Method for `logical` class. #' #' @param denom (`string`)\cr choice of denominator for proportion. Options are: #' - `n`: number of values in this row and column intersection. #' - `N_row`: total number of values in this row across columns. #' - `N_col`: total number of values in this column across rows. #' -#' @return If `x` is of class `logical`, returns a list with named `numeric` items: -#' \describe{ -#' \item{n}{the [length()] of `x` (possibly after removing `NA`s).} -#' \item{count}{count of `TRUE` in `x`.} -#' \item{count_fraction}{count and proportion of `TRUE` in `x` relative to the denominator, or `NA` if the -#' denominator is zero. Note that `NA`s in `x` are never counted or leading to `NA` here. -#' } -#' } +#' @return +#' * If `x` is of class `logical`, returns a `list` with named `numeric` items: +#' * `n`: The [length()] of `x` (possibly after removing `NA`s). +#' * `count`: Count of `TRUE` in `x`. +#' * `count_fraction`: Count and proportion of `TRUE` in `x` relative to the denominator, or `NA` if the +#' denominator is zero. Note that `NA`s in `x` are never counted or leading to `NA` here. +#' #' @method s_summary logical #' #' @examples @@ -469,8 +478,11 @@ s_summary.logical <- function(x, y } -#' @describeIn summarize_variables S3 generic Formatted Analysis function to produce -#' an object description. It is used as `afun` in [rtables::analyze()]. +#' @describeIn summarize_variables Formatted analysis function which is used as `afun` +#' in `summarize_vars()`. +#' +#' @return +#' * `a_summary()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @export a_summary <- function(x, @@ -484,7 +496,7 @@ a_summary <- function(x, .a_summary_numeric_formats <- summary_formats() .a_summary_numeric_labels <- summary_labels() -#' @describeIn summarize_variables Formatted Analysis function method for `numeric`. +#' @describeIn summarize_variables Formatted analysis function method for `numeric` class. #' #' @export #' @@ -499,7 +511,7 @@ a_summary.numeric <- make_afun( .a_summary_counts_formats <- summary_formats(type = "counts") -#' @describeIn summarize_variables Method for `factor`. +#' @describeIn summarize_variables Formatted analysis function method for `factor` class. #' #' @export #' @@ -517,7 +529,7 @@ a_summary.factor <- make_afun( .formats = .a_summary_counts_formats ) -#' @describeIn summarize_variables Formatted Analysis function method for `character`. +#' @describeIn summarize_variables Formatted analysis function method for `character` class. #' #' @export #' @@ -533,7 +545,7 @@ a_summary.character <- make_afun( .formats = .a_summary_counts_formats ) -#' @describeIn summarize_variables Formatted Analysis function method for `logical`. +#' @describeIn summarize_variables Formatted analysis function method for `logical` class. #' #' @export #' @@ -550,9 +562,13 @@ a_summary.logical <- make_afun( #' Constructor Function for [summarize_vars()] and [summarize_colvars()] #' -#' @description Constructor function which creates a combined Formatted -#' Analysis function for use in layout creating functions [summarize_vars()] and -#' [summarize_colvars()]. +#' @description `r lifecycle::badge("stable")` +#' +#' Constructor function which creates a combined formatted analysis function. +#' +#' @inheritParams argument_convention +#' +#' @return Combined formatted analysis function for use in [summarize_vars()]. #' #' @note Since [a_summary()] is generic and we want customization of the formatting arguments #' via [rtables::make_afun()], we need to create another temporary generic function, with @@ -560,7 +576,6 @@ a_summary.logical <- make_afun( #' we need to wrap them in a combined `afun`. Since this is required by two layout creating #' functions (and possibly others in the future), we provide a constructor that does this: #' [create_afun_summary()]. -#' @inheritParams argument_convention #' #' @export #' @@ -648,17 +663,17 @@ create_afun_summary <- function(.stats, .formats, .labels, .indent_mods) { } } -#' @describeIn summarize_variables Analyze Function to add a descriptive analyze -#' layer to `rtables` pipelines. The analysis is applied to a vector and -#' return the summary, in `rcells`. The ellipsis (`...`) conveys arguments to -#' [s_summary()], for instance `na.rm = FALSE` if missing data should be -#' accounted for. When factor variables contains `NA`, it is expected that `NA` -#' have been conveyed to `na_level` appropriately beforehand with -#' [df_explicit_na()]. +#' @describeIn summarize_variables Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @param ... arguments passed to `s_summary()`. #' +#' @return +#' * `summarize_vars()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_summary()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index 84751285b6..8ef7e9ca74 100644 --- a/R/survival_biomarkers_subgroups.R +++ b/R/survival_biomarkers_subgroups.R @@ -5,13 +5,12 @@ #' Tabulate the estimated effects of multiple continuous biomarker variables #' across population subgroups. #' -#' @details These functions create a layout starting from a data frame which contains -#' the required statistics. The tables are then typically used as input for forest plots. -#' #' @inheritParams argument_convention #' @inheritParams fit_coxreg_multivar #' @inheritParams survival_duration_subgroups -#' @name survival_biomarkers_subgroups +#' +#' @details These functions create a layout starting from a data frame which contains +#' the required statistics. The tables are then typically used as input for forest plots. #' #' @examples #' library(dplyr) @@ -42,24 +41,30 @@ #' data = adtte_f #' ) #' df +#' +#' @name survival_biomarkers_subgroups NULL #' Prepares Survival Data Estimates for Multiple Biomarkers in a Single Data Frame #' #' @description `r lifecycle::badge("stable")` #' -#' Prepares estimates for number of events, patients and median survival -#' times, as well as hazard ratio estimates, confidence intervals and p-values, for multiple biomarkers across -#' population subgroups in a single data frame. -#' `variables` corresponds to the names of variables found in `data`, passed as a named list and requires elements -#' `tte`, `is_event`, `biomarkers` (vector of continuous biomarker variables) and optionally `subgroups` and `strat`. +#' Prepares estimates for number of events, patients and median survival times, as well as hazard ratio estimates, +#' confidence intervals and p-values, for multiple biomarkers across population subgroups in a single data frame. +#' `variables` corresponds to the names of variables found in `data`, passed as a named `list` and requires elements +#' `tte`, `is_event`, `biomarkers` (vector of continuous biomarker variables), and optionally `subgroups` and `strat`. #' `groups_lists` optionally specifies groupings for `subgroups` variables. #' #' @inheritParams argument_convention #' @inheritParams fit_coxreg_multivar #' @inheritParams survival_duration_subgroups #' +#' @return A `data.frame` with columns `biomarker`, `biomarker_label`, `n_tot`, `n_tot_events`, +#' `median`, `hr`, `lcl`, `ucl`, `conf_level`, `pval`, `pval_label`, `subgroup`, `var`, +#' `var_label`, and `row_type`. +#' #' @seealso [h_coxreg_mult_cont_df()] which is used internally, [tabulate_survival_biomarkers()]. +#' #' @export #' @examples #' # Typical analysis of two continuous biomarkers `BMRKR1` and `AGE`, @@ -161,22 +166,28 @@ extract_survival_biomarkers <- function(variables, } } -#' @describeIn survival_biomarkers_subgroups table creating function. +#' @describeIn survival_biomarkers_subgroups Table-creating function which creates a table +#' summarizing biomarker effects on survival by subgroup. #' #' @param df (`data.frame`)\cr containing all analysis variables, as returned by #' [extract_survival_biomarkers()]. #' @param vars (`character`)\cr the names of statistics to be reported among: -#' - `n_tot_events`: total number of events per group. -#' - `n_tot`: total number of observations per group. -#' - `median`: median survival time. -#' - `hr`: hazard ratio. -#' - `ci`: confidence interval of hazard ratio. -#' - `pval`: p-value of the effect. +#' * `n_tot_events`: Total number of events per group. +#' * `n_tot`: Total number of observations per group. +#' * `median`: Median survival time. +#' * `hr`: Hazard ratio. +#' * `ci`: Confidence interval of hazard ratio. +#' * `pval`: p-value of the effect. #' Note, one of the statistics `n_tot` and `n_tot_events`, as well as both `hr` and `ci` are required. -#' @seealso [h_tab_surv_one_biomarker()] which is used internally, [extract_survival_biomarkers()]. +#' +#' @return An `rtables` table summarizing biomarker effects on survival by subgroup. +#' #' @note In contrast to [tabulate_survival_subgroups()] this tabulation function does #' not start from an input layout `lyt`. This is because internally the table is #' created by combining multiple subtables. +#' +#' @seealso [h_tab_surv_one_biomarker()] which is used internally, [extract_survival_biomarkers()]. +#' #' @export #' #' @examples diff --git a/R/survival_coxph_pairwise.R b/R/survival_coxph_pairwise.R index 0ca2eea885..78fd8075ff 100644 --- a/R/survival_coxph_pairwise.R +++ b/R/survival_coxph_pairwise.R @@ -15,20 +15,19 @@ #' can also be set to "breslow" or "exact". See more in [survival::coxph()] #' * `conf_level` (`proportion`)\cr confidence level of the interval for HR. #' -#' @importFrom stats pchisq #' @name survival_coxph_pairwise NULL -#' @describeIn survival_coxph_pairwise Statistics Function which analyzes HR, CIs of HR and p-value with coxph model. -#' -#' @return The statistics are: -#' \describe{ -#' \item{pvalue}{p-value to test HR = 1.} -#' \item{hr}{hazard ratio.} -#' \item{hr_ci}{confidence interval for hazard ratio.} -#' \item{n_tot}{total number of observations.} -#' \item{n_tot_events}{total number of events.} -#' } +#' @describeIn survival_coxph_pairwise Statistics function which analyzes HR, CIs of HR and p-value +#' of a coxph model. +#' +#' @return +#' * `s_coxph_pairwise()` returns the statistics: +#' * `pvalue`: p-value to test HR = 1. +#' * `hr`: Hazard ratio. +#' * `hr_ci`: Confidence interval for hazard ratio. +#' * `n_tot`: Total number of observations. +#' * `n_tot_events`: Total number of events. #' #' @examples #' library(dplyr) @@ -119,8 +118,10 @@ s_coxph_pairwise <- function(df, ) } -#' @describeIn survival_coxph_pairwise Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn survival_coxph_pairwise Formatted analysis function which is used as `afun` in `coxph_pairwise()`. +#' +#' @return +#' * `a_coxph_pairwise()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_coxph_pairwise @@ -142,8 +143,14 @@ a_coxph_pairwise <- make_afun( ) -#' @describeIn survival_coxph_pairwise Analyze Function which adds the pairwise coxph analysis -#' to the input layout. Note that additional formatting arguments can be used here. +#' @describeIn survival_coxph_pairwise Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `coxph_pairwise()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_coxph_pairwise()` to the table layout. +#' #' @export #' #' @examples diff --git a/R/survival_duration_subgroups.R b/R/survival_duration_subgroups.R index ff5787f8f9..9f37dab298 100644 --- a/R/survival_duration_subgroups.R +++ b/R/survival_duration_subgroups.R @@ -4,9 +4,6 @@ #' #' Tabulate statistics such as median survival time and hazard ratio for population subgroups. #' -#' @details These functions create a layout starting from a data frame which contains -#' the required statistics. Tables typically used as part of forest plot. -#' #' @inheritParams argument_convention #' @inheritParams survival_coxph_pairwise #' @param data (`data.frame`)\cr the dataset containing the variables to summarize. @@ -16,7 +13,10 @@ #' @param label_all (`string`)\cr label for the total population analysis. #' @param time_unit (`string`)\cr label with unit of median survival time. Default `NULL` skips #' displaying unit. -#' @name survival_duration_subgroups +#' +#' @details These functions create a layout starting from a data frame which contains +#' the required statistics. Tables typically used as part of forest plot. +#' #' @seealso [extract_survival_subgroups()] #' #' @examples @@ -58,6 +58,8 @@ #' data = adtte_f #' ) #' df +#' +#' @name survival_duration_subgroups NULL #' Prepares Survival Data for Population Subgroups in Data Frames @@ -65,17 +67,24 @@ NULL #' @description `r lifecycle::badge("stable")` #' #' Prepares estimates of median survival times and treatment hazard ratios for population subgroups in -#' data frames. Simple wrapper for [h_survtime_subgroups_df()] and [h_coxph_subgroups_df()]. -#' Result is a list of two data frames: `survtime` and `hr`. -#' `variables` corresponds to the names of variables found in `data`, passed as a named list and requires elements -#' `tte`, `is_event`, `arm` and optionally `subgroups` and `strat`. `groups_lists` optionally specifies -#' groupings for `subgroups` variables. +#' data frames. Simple wrapper for [h_survtime_subgroups_df()] and [h_coxph_subgroups_df()]. Result is a `list` +#' of two `data.frame`s: `survtime` and `hr`. `variables` corresponds to the names of variables found in `data`, +#' passed as a named `list` and requires elements `tte`, `is_event`, `arm` and optionally `subgroups` and `strat`. +#' `groups_lists` optionally specifies groupings for `subgroups` variables. +#' #' @export -#' @seealso [survival_duration_subgroups] #' @inheritParams argument_convention #' @inheritParams survival_duration_subgroups #' @inheritParams survival_coxph_pairwise #' +#' @return A named `list` of two elements: +#' * `survtime`: A `data.frame` containing columns `arm`, `n`, `n_events`, `median`, `subgroup`, `var`, +#' `var_label`, and `row_type`. +#' * `hr`: A `data.frame` containing columns `arm`, `n_tot`, `n_tot_events`, `hr`, `lcl`, `ucl`, `conf_level`, +#' `pval`, `pval_label`, `subgroup`, `var`, `var_label`, and `row_type`. +#' +#' @seealso [survival_duration_subgroups] +#' #' @examples #' library(dplyr) #' library(forcats) @@ -152,8 +161,11 @@ extract_survival_subgroups <- function(variables, list(survtime = df_survtime, hr = df_hr) } -#' @describeIn survival_duration_subgroups Formatted Analysis function used to format the results of -#' [extract_survival_subgroups()]. Returns is a list of Formatted Analysis functions with one element per statistic. +#' @describeIn survival_duration_subgroups Formatted analysis function which is used as +#' `afun` in `tabulate_survival_subgroups()`. +#' +#' @return +#' * `a_survival_subgroups()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_survival_subgroups @@ -205,20 +217,25 @@ a_survival_subgroups <- function(.formats = list( afun_lst } -#' @describeIn survival_duration_subgroups table creating function. +#' @describeIn survival_duration_subgroups Table-creating function which creates a table +#' summarizing survival by subgroup. +#' #' @param df (`list`)\cr of data frames containing all analysis variables. List should be #' created using [extract_survival_subgroups()]. -#' @param vars (`character`)\cr the name of statistics to be reported among -#' `n_tot_events` (total number of events per group), -#' `n_events` (number of events per group), -#' `n_tot` (total number of observations per group), -#' `n` (number of observations per group), -#' `median` (median survival time), -#' `hr` (hazard ratio), -#' `ci` (confidence interval of hazard ratio) and -#' `pval` (p value of the effect). -#' Note, one of the statistics `n_tot` and `n_tot_events`, as well as both `hr` and `ci` -#' are required. +#' @param vars (`character`)\cr the name of statistics to be reported among: +#' * `n_tot_events`: Total number of events per group. +#' * `n_events`: Number of events per group. +#' * `n_tot`: Total number of observations per group. +#' * `n`: Number of observations per group. +#' * `median`: Median survival time. +#' * `hr`: Hazard ratio. +#' * `ci`: Confidence interval of hazard ratio. +#' * `pval`: p-value of the effect. +#' Note, one of the statistics `n_tot` and `n_tot_events`, as well as both `hr` and `ci` +#' are required. +#' +#' @return An `rtables` table summarizing survival by subgroup. +#' #' @export #' @examples #' @@ -364,14 +381,16 @@ tabulate_survival_subgroups <- function(lyt, #' #' @description `r lifecycle::badge("stable")` #' -#' Internal function to check variables included in -#' [tabulate_survival_subgroups()] and create column labels. -#' Note that at least one of `n_tot` and `n_tot_events` needs to be provided in `vars`. +#' Internal function to check variables included in [tabulate_survival_subgroups()] +#' and create column labels. #' #' @inheritParams tabulate_survival_subgroups #' @inheritParams argument_convention -#' @param method p-value method for testing hazard ratio = 1. -#' @return `list` of variables to tabulate and their labels. +#' @param method (`character`)\cr p-value method for testing hazard ratio = 1. +#' +#' @return A `list` of variables and their labels to tabulate. +#' +#' @note At least one of `n_tot` and `n_tot_events` must be provided in `vars`. #' #' @export d_survival_subgroups_colvars <- function(vars, diff --git a/R/survival_time.R b/R/survival_time.R index 5e1af9c94a..c3a3bc9567 100644 --- a/R/survival_time.R +++ b/R/survival_time.R @@ -16,18 +16,16 @@ #' @name survival_time NULL -#' @describeIn survival_time Statistics Function which analyzes survival times. -#' `range_censor` and `range_event`. +#' @describeIn survival_time Statistics function which analyzes survival times. #' -#' @return The statistics are: -#' \describe{ -#' \item{median}{median survival time.} -#' \item{median_ci}{confidence interval for median time.} -#' \item{quantiles}{survival time for two specified quantiles.} -#' \item{range_censor}{survival time range for censored observations.} -#' \item{range_event}{survival time range for observations with events.} -#' \item{range}{survival time range for all observations.} -#' } +#' @return +#' * `s_surv_time()` returns the statistics: +#' * `median`: Median survival time. +#' * `median_ci`: Confidence interval for median time. +#' * `quantiles`: Survival time for two specified quantiles. +#' * `range_censor`: Survival time range for censored observations. +#' * `range_event`: Survival time range for observations with events. +#' * `range`: Survival time range for all observations. #' #' @examples #' library(dplyr) @@ -85,8 +83,10 @@ s_surv_time <- function(df, ) } -#' @describeIn survival_time Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn survival_time Formatted analysis function which is used as `afun` in `surv_time()`. +#' +#' @return +#' * `a_surv_time()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_surv_time @@ -115,8 +115,13 @@ a_surv_time <- make_afun( ) ) -#' @describeIn survival_time Analyze Function which adds the survival times analysis -#' to the input layout. Note that additional formatting arguments can be used here. +#' @describeIn survival_time Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' +#' @return +#' * `surv_time()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_surv_time()` to the table layout. #' #' @export #' diff --git a/R/survival_timepoint.R b/R/survival_timepoint.R index aa5e7bf741..98dd635dcf 100644 --- a/R/survival_timepoint.R +++ b/R/survival_timepoint.R @@ -17,15 +17,14 @@ #' @name survival_timepoint NULL -#' @describeIn survival_timepoint Statistics Function which analyzes survival rate. +#' @describeIn survival_timepoint Statistics function which analyzes survival rate. #' -#' @return The statistics are: -#' \describe{ -#' \item{pt_at_risk}{patients remaining at risk.} -#' \item{event_free_rate}{event free rate (%).} -#' \item{rate_se}{standard error of event free rate.} -#' \item{rate_ci}{confidence interval for event free rate.} -#' } +#' @return +#' * `s_surv_timepoint()` returns the statistics: +#' * `pt_at_risk`: Patients remaining at risk. +#' * `event_free_rate`: Event-free rate (%). +#' * `rate_se`: Standard error of event free rate. +#' * `rate_ci`: Confidence interval for event free rate. #' #' @examples #' library(dplyr) @@ -85,8 +84,11 @@ s_surv_timepoint <- function(df, ) } -#' @describeIn survival_timepoint Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn survival_timepoint Formatted analysis function which is used as `afun` in `surv_timepoint()` +#' when `method = "surv"`. +#' +#' @return +#' * `a_surv_timepoint()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_surv_timepoint @@ -111,14 +113,13 @@ a_surv_timepoint <- make_afun( ) ) -#' @describeIn survival_timepoint Statistics Function which analyzes difference between two survival rates. +#' @describeIn survival_timepoint Statistics function which analyzes difference between two survival rates. #' -#' @return The statistics are: -#' \describe{ -#' \item{rate_diff}{event free rate difference between two groups.} -#' \item{rate_diff_ci}{confidence interval for the difference.} -#' \item{ztest_pval}{p-value to test the difference is 0.} -#' } +#' @return +#' * `s_surv_timepoint_diff()` returns the statistics: +#' * `rate_diff`: Event-free rate difference between two groups. +#' * `rate_diff_ci`: Confidence interval for the difference. +#' * `ztest_pval`: p-value to test the difference is 0. #' #' @examples #' df_ref_group <- adtte_f %>% @@ -179,8 +180,11 @@ s_surv_timepoint_diff <- function(df, ) } -#' @describeIn survival_timepoint Formatted Analysis function which can be further customized by calling -#' [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()]. +#' @describeIn survival_timepoint Formatted analysis function which is used as `afun` in `surv_timepoint()` +#' when `method = "surv_diff"`. +#' +#' @return +#' * `a_surv_timepoint_diff()` returns the corresponding list with formatted [rtables::CellValue()]. #' #' @examples #' # Internal function - a_surv_timepoint_diff @@ -210,14 +214,21 @@ a_surv_timepoint_diff <- make_afun( ) ) -#' @describeIn survival_timepoint Analyze Function which adds the survival rate analysis to the input layout. -#' Note that additional formatting arguments can be used here. +#' @describeIn survival_timepoint Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @param method (`string`)\cr either `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. +#' +#' @return +#' * `surv_timepoint()` returns a layout object suitable for passing to further layouting functions, +#' or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing +#' the statistics from `s_surv_timepoint()` and/or `s_surv_timepoint_diff()` to the table layout depending on +#' the value of `method`. +#' #' @export #' #' @examples diff --git a/R/utils.R b/R/utils.R index 2639163168..9533fef676 100644 --- a/R/utils.R +++ b/R/utils.R @@ -6,7 +6,7 @@ #' @param na.rm (`logical`)\cr indicating if NA should be omitted. #' @param finite (`logical`)\cr indicating if non-finite elements should be removed. #' -#' @return 2-elements vector of class numeric. +#' @return A 2-element vector of class `numeric`. #' #' @examples #' # Internal function - range_noinf @@ -47,7 +47,7 @@ range_noinf <- function(x, na.rm = FALSE, finite = FALSE) { # nolint #' @description `r lifecycle::badge("stable")` #' #' @inheritParams argument_convention -#' @return a `string` +#' @return A `string`. #' #' @export f_conf_level <- function(conf_level) { @@ -60,7 +60,7 @@ f_conf_level <- function(conf_level) { #' @description `r lifecycle::badge("stable")` #' #' @param test_mean (`number`)\cr mean value to test under the null hypothesis. -#' @return a `string` +#' @return A `string`. #' #' @export f_pval <- function(test_mean) { @@ -72,7 +72,7 @@ f_pval <- function(test_mean) { #' #' @param covariates (`character`)\cr a vector that can contain single variable names (such as #' `"X1"`), and/or interaction terms indicated by `"X1 * X2"`. -#' @return a named `list` of character vector. +#' @return A named `list` of `character` vector. #' #' @keywords internal get_covariates <- function(covariates) { @@ -85,15 +85,16 @@ get_covariates <- function(covariates) { #' #' @description `r lifecycle::badge("stable")` #' -#' Replicate entries of a vector if required. Note that this will fail if `x` -#' is not of length `n` or is not a scalar. +#' Replicate entries of a vector if required. #' #' @inheritParams argument_convention #' @param n (`count`)\cr how many entries we need. #' -#' @return Just input `x` if it has the required length already or is `NULL`, +#' @return `x` if it has the required length already or is `NULL`, #' otherwise if it is scalar the replicated version of it with `n` entries. #' +#' @note This function will fail if `x` is not of length `n` and/or is not a scalar. +#' #' @export to_n <- function(x, n) { if (is.null(x)) { @@ -116,6 +117,8 @@ to_n <- function(x, n) { #' @param ... data.frames or vectors #' @param omit_null are \code{NULL} elements in \code{...} to be omitted from the check? #' +#' @return A `logical` value. +#' #' @keywords internal check_same_n <- function(..., omit_null = TRUE) { dots <- list(...) @@ -153,7 +156,7 @@ check_same_n <- function(..., omit_null = TRUE) { #' #' @param nams (`character`)\cr vector of original names. #' -#' @return Character vector of proper names, which does not use dots in contrast to +#' @return A `character` `vector` of proper names, which does not use dots in contrast to #' [base::make.names()]. #' #' @examples @@ -209,7 +212,7 @@ day2month <- function(x) { #' #' @param x (`numeric`)\cr vector. #' -#' @return An empty `numeric`. +#' @return An empty `numeric` if all elements of `x` are `NA`, otherwise `x`. #' #' @examples #' x <- c(NA, NA, NA) @@ -261,7 +264,7 @@ combine_vectors <- function(x, y) { #' @param x (named `vector`)\cr where to extract named elements from. #' @param names (`character`)\cr vector of names to extract. #' -#' @return Either `NULL` or the extracted elements from `x`. +#' @return `NULL` if `x` is `NULL`, otherwise the extracted elements from `x`. #' #' @keywords internal extract_by_name <- function(x, names) { @@ -326,6 +329,8 @@ aesi_label <- function(aesi, scope = NULL) { #' #' @param x arm information #' +#' @return `x` +#' #' @keywords internal #' study_arm <- function(x) { @@ -343,8 +348,10 @@ study_arm <- function(x) { #' @param y (`character`)\cr value with y column name. #' @param groups (`character`)\cr vector with optional grouping variables names. #' @param level (`numeric`)\cr level of confidence interval to use (0.95 by default). -#' @return A `data.frame` with original `x`, smoothed `y`, `ylow`, `yhigh` and -#' optional `groups` variables formatted to factor type. +#' +#' @return A `data.frame` with original `x`, smoothed `y`, `ylow`, and `yhigh`, and +#' optional `groups` variables formatted as `factor` type. +#' #' @export #' get_smooths <- function(df, x, y, groups = NULL, level = 0.95) { @@ -432,6 +439,8 @@ n_available <- function(x) { #' @param varlabels (`character`)\cr vector of labels for `x`. #' @param ... further parameters to be added to the list. #' +#' @return `x` with variable labels reapplied. +#' #' @export reapply_varlabels <- function(x, varlabels, ...) { named_labels <- c(as.list(varlabels), list(...)) diff --git a/R/utils_checkmate.R b/R/utils_checkmate.R index 20fc9032d7..6d9d873799 100644 --- a/R/utils_checkmate.R +++ b/R/utils_checkmate.R @@ -1,8 +1,8 @@ #' Additional Assertions for `checkmate` #' -#' @description #' Additional assertion functions which can be used together with the `checkmate` package. #' +#' @inheritParams checkmate::assert_factor #' @param x (`any`)\cr object to test. #' @param df (`data.frame`)\cr data set to test. #' @param variables (named `list` of `character`)\cr list of variables to test. @@ -11,9 +11,11 @@ #' @param na_level (`character`)\cr the string you have been using to represent NA or #' missing data. For `NA` values please consider using directly `base::is.na` or #' similar approaches. -#' @inheritParams checkmate::assert_factor #' @param (`integer`)\cr minimum number of factor levels. Default is `1`. #' @param ... a collection of objects to test. +#' +#' @return Nothing if assertion passes, otherwise prints the error message. +#' #' @name assertions NULL @@ -33,8 +35,8 @@ check_list_of_variables <- function(x) { } return(res) } -#' @describeIn assertions Check whether `x` is a valid list of variable names. -#' `NULL` elements of the list `x` are dropped out with `Filter(Negate(is.null), x)`. +#' @describeIn assertions Checks whether `x` is a valid list of variable names. +#' `NULL` elements of the list `x` are dropped with `Filter(Negate(is.null), x)`. #' #' @examples #' # Check whether `x` is a valid list of variable names. @@ -154,7 +156,7 @@ check_valid_factor <- function(x, return(res) } -#' @describeIn assertions Check whether `x` is a valid factor (has levels and no empty +#' @describeIn assertions Check whether `x` is a valid factor (i.e. has levels and no empty #' string levels). Note that `NULL` and `NA` elements are allowed. #' #' @examples diff --git a/R/utils_factor.R b/R/utils_factor.R index 4baab48767..c6294c8f7d 100644 --- a/R/utils_factor.R +++ b/R/utils_factor.R @@ -8,7 +8,7 @@ #' @param levels level names to be combined #' @param new_level name of new level #' -#' @return a factor +#' @return A `factor` with the new levels. #' #' @export #' @@ -42,8 +42,7 @@ combine_levels <- function(x, levels, new_level = paste(levels, collapse = "/")) #' converting a character vector. #' @param verbose defaults to `TRUE`. It prints out warnings and messages. #' -#' @return The factor with same attributes (except class) as `x`. Does not do any modifications -#' if `x` is already a factor. +#' @return A `factor` with same attributes (except class) as `x`. Does not modify `x` if already a `factor`. #' #' @examples #' # Internal function - as_factor_keep_attributes @@ -104,7 +103,7 @@ as_factor_keep_attributes <- function(x, #' the boundaries 0 and 1 must not be included. #' @param digits (`integer`)\cr number of decimal places to round the percent numbers. #' -#' @return Character vector with labels in the format `[0%,20%]`, `(20%,50%]`, etc. +#' @return A `character` vector with labels in the format `[0%,20%]`, `(20%,50%]`, etc. #' #' @examples #' # Internal function - bins_percent_labels @@ -143,10 +142,7 @@ bins_percent_labels <- function(probs, #' #' @description `r lifecycle::badge("stable")` #' -#' This cuts a numeric vector into sample quantile bins. Note that the intervals are closed on -#' the right side. That is, the first bin is the interval `[-Inf, q1]` where `q1` is -#' the first quantile, the second bin is then `(q1, q2]`, etc., and the last bin -#' is `(qn, +Inf]` where `qn` is the last quantile. +#' This cuts a numeric vector into sample quantile bins. #' #' @inheritParams bins_percent_labels #' @param x (`numeric`)\cr the continuous variable values which should be cut into @@ -157,7 +153,12 @@ bins_percent_labels <- function(probs, #' @param type (`integer`)\cr type of quantiles to use, see [stats::quantile()] for details. #' @param ordered (`flag`)\cr should the result be an ordered factor. #' -#' @return The factor variable with the appropriately labeled bins as levels. +#' @return A `factor` variable with appropriately-labeled bins as levels. +#' +#' @note Intervals are closed on the right side. That is, the first bin is the interval +#' `[-Inf, q1]` where `q1` is the first quantile, the second bin is then `(q1, q2]`, etc., +#' and the last bin is `(qn, +Inf]` where `qn` is the last quantile. +#' #' @export #' #' @examples @@ -215,12 +216,15 @@ cut_quantile_bins <- function(x, #' Discard Certain Levels from a Factor #' +#' @description `r lifecycle::badge("stable")` +#' #' This discards the observations as well as the levels specified from a factor. #' #' @param x (`factor`)\cr the original factor. #' @param discard (`character`)\cr which levels to discard. #' -#' @return The modified factor with observations as well as levels from `discard` dropped. +#' @return A modified `factor` with observations as well as levels from `discard` dropped. +#' #' @export #' #' @examples @@ -235,14 +239,17 @@ fct_discard <- function(x, discard) { #' Insertion of Explicit Missings in a Factor #' -#' This inserts explicit missings in a factor based on a condition. Note that also additional +#' @description `r lifecycle::badge("stable")` +#' +#' This inserts explicit missings in a factor based on a condition. Additionally, #' existing `NA` values will be explicitly converted to given `na_level`. #' #' @param x (`factor`)\cr the original factor. #' @param condition (`logical`)\cr where to insert missings. #' @param na_level (`string`)\cr which level to use for missings. #' -#' @return The modified factor with inserted and existing `NA` converted to `na_level`. +#' @return A modified `factor` with inserted and existing `NA` converted to `na_level`. +#' #' @seealso [forcats::fct_na_value_to_level()] which is used internally. #' #' @examples @@ -259,10 +266,11 @@ fct_explicit_na_if <- function(x, condition, na_level = "") { #' Collapsing of Factor Levels and Keeping Only Those New Group Levels #' +#' @description `r lifecycle::badge("stable")` +#' #' This collapses levels and only keeps those new group levels, in the order provided. #' The returned factor has levels in the order given, with the possible missing level last (this will -#' only be included if there are missings). Note that any existing `NA` in the input vector will -#' not be replaced by the missing level. If needed [explicit_na()] can be called separately on the result. +#' only be included if there are missing values). #' #' @param .f (`factor` or `character`)\cr original vector. #' @param ... (named `character` vectors)\cr levels in each vector provided will be collapsed into @@ -270,8 +278,12 @@ fct_explicit_na_if <- function(x, condition, na_level = "") { #' @param .na_level (`string`)\cr which level to use for other levels, which should be missing in the #' new factor. Note that this level must not be contained in the new levels specified in `...`. #' -#' @return The modified factor with collapsed levels. Values and levels which are not included -#' in the given character vectors input will be set to the missing level. +#' @return A modified `factor` with collapsed levels. Values and levels which are not included +#' in the given `character` vector input will be set to the missing level `.na_level`. +#' +#' @note Any existing `NA`s in the input vector will not be replaced by the missing level. If needed, +#' [explicit_na()] can be called separately on the result. +#' #' @seealso [forcats::fct_collapse()], [forcats::fct_relevel()] which are used internally. #' #' @examples diff --git a/R/utils_grid.R b/R/utils_grid.R index 9908bcddb4..831d2db921 100644 --- a/R/utils_grid.R +++ b/R/utils_grid.R @@ -10,6 +10,9 @@ #' @param vp a \code{\link{viewport}} object (or \code{NULL}). #' @param name a character identifier for the grob. #' @param gp A \code{\link{gpar}} object. +#' +#' @return A `grob`. +#' #' @export #' #' @examples @@ -92,6 +95,8 @@ stack_grobs <- function(..., #' @param padding_ht unit of length 1, vertical space between each grob. #' @param padding_wt unit of length 1, horizontal space between each grob. #' +#' @return A `grob`. +#' #' @examples #' library(grid) #' @@ -226,6 +231,9 @@ arrange_grobs <- function(..., # nolint #' @param grob grid object #' @param newpage draw on a new page #' @param vp a \code{\link{viewport}} object (or \code{NULL}). +#' +#' @return A `grob`. +#' #' @export #' #' @examples diff --git a/R/utils_rtables.R b/R/utils_rtables.R index 5f78488a63..f494b355a5 100644 --- a/R/utils_rtables.R +++ b/R/utils_rtables.R @@ -13,7 +13,7 @@ #' @param print_txt_to_copy Utility to have a way to copy the input table directly #' into the expected variable instead of copying it too manually. #' -#' @return A matrix of strings +#' @return A `matrix` of `string`s. #' #' @export to_string_matrix <- function(x, with_spaces = FALSE, print_txt_to_copy = FALSE) { @@ -46,8 +46,8 @@ to_string_matrix <- function(x, with_spaces = FALSE, print_txt_to_copy = FALSE) #' #' @param x (`vector`)\cr input for a cell. #' -#' @return Either empty character vector if all entries in `x` are missing (`NA`), or otherwise -#' the unlisted version of `x` +#' @return An empty `character` vector if all entries in `x` are missing (`NA`), otherwise +#' the unlisted version of `x`. #' #' @keywords internal unlist_and_blank_na <- function(x) { @@ -69,7 +69,7 @@ unlist_and_blank_na <- function(x) { #' row should be returned. #' @param format (`string`)\cr `rtables` format to use. #' -#' @return Content function which just gives `df$analysis_var` at the row identified by +#' @return A content function which gives `df$analysis_var` at the row identified by #' `.df_row$flag` in the given format. #' #' @keywords internal @@ -94,10 +94,10 @@ cfun_by_flag <- function(analysis_var, #' #' @inheritParams argument_convention #' -#' @return list containing "row_count" with the row count value and the correct label. +#' @return A `list` containing "row_count" with the row count value and the correct label. #' -#' @note Important is here to not use `df` but `.N_row` in the implementation, because the former -#' is already split by columns and will refer to the first column of the data only. +#' @note It is important here to not use `df` but rather `.N_row` in the implementation, because +#' the former is already split by columns and will refer to the first column of the data only. #' #' @keywords internal c_label_n <- function(df, @@ -115,10 +115,11 @@ c_label_n <- function(df, #' #' @inheritParams argument_convention #' -#' @return The modified layout where the latest row split labels now have the row-wise -#' total counts (i.e. without column based subsetting) attached in parentheses. Row -#' count values are contained in these row count rows but are not displayed so that -#' they are not considered zero rows by default when pruning. +#' @return A modified layout where the latest row split labels now have the row-wise +#' total counts (i.e. without column-based subsetting) attached in parentheses. +#' +#' @note Row count values are contained in these row count rows but are not displayed +#' so that they are not considered zero rows by default when pruning. #' #' @examples #' basic_table() %>% @@ -152,7 +153,7 @@ add_rowcounts <- function(lyt) { #' @param table_tree (`VTableTree`)\cr table to extract the indices from. #' @param col_names (`character`)\cr vector of column names. #' -#' @return the vector of column indices. +#' @return A vector of column indices. #' #' @export h_col_indices <- function(table_tree, col_names) { @@ -168,7 +169,7 @@ h_col_indices <- function(table_tree, col_names) { #' #' @param x a list #' -#' @return a character vector with the labels or names for the list elements +#' @return A `character` vector with the labels or names for the list elements. #' #' @keywords internal labels_or_names <- function(x) { @@ -182,15 +183,14 @@ labels_or_names <- function(x) { #' Convert to `rtable` #' -#' @description`r lifecycle::badge("stable")` +#' @description `r lifecycle::badge("stable")` #' #' This is a new generic function to convert objects to `rtable` tables. #' #' @param x the object which should be converted to an `rtable`. #' @param ... additional arguments for methods. #' -#' @return The `rtable` object. Note that the concrete class will depend on the method -#' which is used. +#' @return An `rtables` table object. Note that the concrete class will depend on the method used. #' #' @export as.rtable <- function(x, ...) { # nolint @@ -200,6 +200,7 @@ as.rtable <- function(x, ...) { # nolint #' @describeIn as.rtable method for converting `data.frame` that contain numeric columns to `rtable`. #' #' @param format the format which should be used for the columns. +#' #' @method as.rtable data.frame #' #' @examples @@ -249,6 +250,9 @@ as.rtable.data.frame <- function(x, format = "xx.xx", ...) { # nolint #' @param value (`vector`)\cr the value used to split. #' @param f (`list` of `vectors`)\cr the reference to make the split #' +#' @return A named `list` with the same element names as `f`, each containing the +#' elements specified in `.stats`. +#' #' @examples #' f <- list( #' surv = c("pt_at_risk", "event_free_rate", "rate_se", "rate_ci"), @@ -290,7 +294,7 @@ h_split_param <- function(param, #' in this context that all default statistics should be used. #' @param all_stats (`character`)\cr all statistics which can be selected here potentially. #' -#' @return Character vector with the selected statistics. +#' @return A `character` vector with the selected statistics. #' #' @keywords internal afun_selected_stats <- function(.stats, all_stats) { @@ -312,16 +316,16 @@ afun_selected_stats <- function(.stats, all_stats) { #' from a given dataset in the top left corner. If a variable label is not found then the #' variable name itself is used instead. Multiple variable labels are concatenated with slashes. #' -#' @note This is not an optimal implementation of course, since we are using here the data set -#' itself during the layout creation. When we have a more mature `rtables` implementation then -#' this will also be improved or not necessary anymore. -#' #' @inheritParams argument_convention #' @param vars (`character`)\cr variable names of which the labels are to be looked up in `df`. #' @param indent (`integer`)\cr non-negative number of nested indent space, default to 0L which means no indent. -#' 1L means two spaces indent, 2L means four spaces indent and so on. +#' 1L means two spaces indent, 2L means four spaces indent and so on. +#' +#' @return A modified layout with the new variable label(s) added to the top-left material. #' -#' @return The modified layout. +#' @note This is not an optimal implementation of course, since we are using here the data set +#' itself during the layout creation. When we have a more mature `rtables` implementation then +#' this will also be improved or not necessary anymore. #' #' @examples #' lyt <- basic_table() %>% diff --git a/inst/WORDLIST b/inst/WORDLIST index 3a3ff13ef2..2cb989242a 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -36,9 +36,6 @@ Satterthwaite Schouten TLG TLGs -Wojciak -Wojciech -Yuyao agresti arcsine bimj @@ -55,11 +52,11 @@ efron funder https jeffreys +layouting lik lineplot lvl midp -multivariable nd onlinelibrary paramcd @@ -73,8 +70,6 @@ rds repo responder responders -roche -songy subtable subtables surv @@ -82,10 +77,7 @@ timepoint unformatted univariable unstratified -waddella wald wiley wilson wilsoncc -wojciak -wojciech diff --git a/man/abnormal.Rd b/man/abnormal.Rd index bc7007784f..fbc7f6671e 100644 --- a/man/abnormal.Rd +++ b/man/abnormal.Rd @@ -40,9 +40,9 @@ count_abnormal( \item{.var, var}{(\code{string})\cr single variable name that is passed by \code{rtables} when requested by a statistics function.} -\item{abnormal}{(\verb{named list})\cr identifying the abnormal range level(s) in \code{var}. Default to -\code{list(Low = "LOW", High = "HIGH")} but you can also group different levels into the name list, -for example, \code{abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))}} +\item{abnormal}{(named \code{list})\cr list identifying the abnormal range level(s) in \code{var}. Defaults to +\code{list(Low = "LOW", High = "HIGH")} but you can also group different levels into the named list, +for example, \code{abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))}.} \item{variables}{(named \code{list} of \code{string})\cr list of additional analysis variables.} @@ -65,12 +65,19 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=s_count_abnormal]{s_count_abnormal()}} returns the statistic \code{fraction} which is a -vector with \code{num} and \code{denom} counts of patients. +\itemize{ +\item \code{s_count_abnormal()} returns the statistic \code{fraction} which is a vector with \code{num} and \code{denom} counts of patients. +} -\code{\link[=a_count_abnormal]{a_count_abnormal()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\itemize{ +\item \code{a_count_abnormal()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} -\code{\link[=count_abnormal]{count_abnormal()}} can be used with multiple abnormal levels and modifies the layout. +\itemize{ +\item \code{count_abnormal()} 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_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]}} @@ -79,30 +86,31 @@ Primary analysis variable \code{.var} indicates the abnormal range result (\code 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: -\describe{ -\item{num}{the number of patients with this abnormality recorded while on treatment.} -\item{denom}{the number of patients with at least one post-baseline assessment.} -} -Note, the denominator includes patients that might have other abnormal levels at baseline, -and patients with missing baseline. Note, optionally patients with this abnormality at -baseline can be excluded from numerator and denominator. +\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. } -\details{ -Note that \code{df} should be filtered to include only post-baseline records. } \section{Functions}{ \itemize{ \item \code{s_count_abnormal()}: Statistics function which counts patients with abnormal range values for a single \code{abnormal} level. -\item \code{a_count_abnormal()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_abnormal()}: Formatted analysis function which is used as \code{afun} in \code{count_abnormal()}. -\item \code{count_abnormal()}: Layout creating function which can be used for creating tables, which can take -statistics function arguments and additional format arguments (see below). Note that it only -works with a single variable but multiple abnormal levels. +\item \code{count_abnormal()}: 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()}}. }} +\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. +} +} \examples{ library(dplyr) diff --git a/man/abnormal_by_baseline.Rd b/man/abnormal_by_baseline.Rd index 4266fc5450..dfad0221f1 100644 --- a/man/abnormal_by_baseline.Rd +++ b/man/abnormal_by_baseline.Rd @@ -44,7 +44,7 @@ by a statistics function.} \item{abnormal}{(\code{character})\cr identifying the abnormal range level(s) in \code{.var}.} \item{na_level}{(\code{string})\cr the explicit \code{na_level} argument you used in the pre-processing steps (maybe with -\code{df_explicit_na()}). The default is \code{""}.} +\code{\link[=df_explicit_na]{df_explicit_na()}}). The default is \code{""}.} \item{variables}{(named \code{list} of \code{string})\cr list of additional analysis variables.} @@ -64,16 +64,26 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=a_count_abnormal_by_baseline]{a_count_abnormal_by_baseline()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\itemize{ +\item \code{s_count_abnormal_by_baseline()} returns statistic \code{fraction} which is a named list with 3 labeled elements: +\code{not_abnormal}, \code{abnormal}, and \code{total}. Each element contains a vector with \code{num} and \code{denom} patient counts. +} + +\itemize{ +\item \code{a_count_abnormal_by_baseline()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_abnormal_by_baseline()} 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_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]}} -} -\details{ -Note that \code{df} should be filtered to include only post-baseline records. -Primary analysis variable \code{.var} indicates the abnormal range result (character or factor), and additional -analysis variables are \code{id} (character or factor) and \code{baseline} (character or factor). For each +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: \itemize{ @@ -96,19 +106,22 @@ patients in the numerator and denominator as follows: } \section{Functions}{ \itemize{ -\item \code{s_count_abnormal_by_baseline()}: For a single \code{abnormal} level, produce a statistic \code{fraction} which is -a named list with 3 elements: \code{not_abnormal}, \code{abnormal} and \code{total}. -Each element contains a vector with \code{num} and \code{denom} counts of patients. -Please note that 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{df_explicit_na()} or \code{explicit_na()}. +\item \code{s_count_abnormal_by_baseline()}: Statistics function for a single \code{abnormal} level. -\item \code{a_count_abnormal_by_baseline()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_abnormal_by_baseline()}: Formatted analysis function which is used as \code{afun} +in \code{count_abnormal_by_baseline()}. -\item \code{count_abnormal_by_baseline()}: Layout creating function which can be used for creating tables, which can take -statistics function arguments and additional format arguments (see below). +\item \code{count_abnormal_by_baseline()}: 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()}}. }} +\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()}}. +} +} \examples{ df <- data.frame( USUBJID = as.character(c(1:6)), diff --git a/man/abnormal_by_marked.Rd b/man/abnormal_by_marked.Rd index f5c39880ae..1ba7aa7c01 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -60,19 +60,28 @@ and last or replicated.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=s_count_abnormal_by_marked]{s_count_abnormal_by_marked()}} the single statistic \code{count_fraction} -with \verb{Single, not last}, \verb{Last or replicated} and \code{Any} results. +\itemize{ +\item \code{s_count_abnormal_by_marked()} returns statistic \code{count_fraction} with \verb{Single, not last}, +\verb{Last or replicated}, and \code{Any} results. +} -\code{\link[=a_count_abnormal_by_marked]{a_count_abnormal_by_marked()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\itemize{ +\item \code{a_count_abnormal_by_marked()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_abnormal_by_marked()} 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_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 (factor). -Additional analysis variables are \code{id} (character or factor) and \code{direction} indicating -the direction of the abnormality (factor). -Denominator is number of patients with at least one valid measurement during +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. \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. @@ -80,24 +89,22 @@ with \verb{Single, not last} and \verb{Last or replicated} levels, respectively. replicated marked abnormalities. } } -\details{ -Note that \verb{Single, not last} and \verb{Last or replicated} levels are -mutually exclusive. If a patient has abnormalities that meet both the \verb{Single, not last} -and \verb{Last or replicated} criteria, then the patient will be counted only under the \verb{Last or replicated} category. -} \section{Functions}{ \itemize{ -\item \code{s_count_abnormal_by_marked()}: Statistics function which returns -the counts and fractions of patients with \verb{Single, not last}, \verb{Last or replicated} and \code{Any} -marked laboratory abnormalities for a single \code{abnormal} level. +\item \code{s_count_abnormal_by_marked()}: Statistics function for patients with marked lab abnormalities. -\item \code{a_count_abnormal_by_marked()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_abnormal_by_marked()}: Formatted analysis function which is used as \code{afun} +in \code{count_abnormal_by_marked()}. -\item \code{count_abnormal_by_marked()}: Layout creating function which can be used for creating tables, -which can take statistics function arguments and additional format arguments (see below). +\item \code{count_abnormal_by_marked()}: 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()}}. }} +\note{ +\verb{Single, not last} and \verb{Last or replicated} levels are mutually exclusive. If a patient has +abnormalities that meet both the \verb{Single, not last} and \verb{Last or replicated} criteria, then the +patient will be counted only under the \verb{Last or replicated} category. +} \examples{ library(dplyr) diff --git a/man/abnormal_by_worst_grade.Rd b/man/abnormal_by_worst_grade.Rd index c547456669..f1ce400a87 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -55,16 +55,26 @@ that is passed by \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=s_count_abnormal_by_worst_grade]{s_count_abnormal_by_worst_grade()}} the single statistic \code{count_fraction} with grade 1 to 4 -and "Any" results. +\itemize{ +\item \code{s_count_abnormal_by_worst_grade()} returns the single statistic \code{count_fraction} with grades 1 to 4 and +"Any" results. +} + +\itemize{ +\item \code{a_count_abnormal_by_worst_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} -\code{\link[=a_count_abnormal_by_worst_grade]{a_count_abnormal_by_worst_grade()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\itemize{ +\item \code{count_abnormal_by_worst_grade()} 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_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 (factor), and additional -analysis variables are \code{id} (character or factor), \code{param} (\code{factor}) and \code{grade_dir} (\code{factor}). +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, @@ -75,29 +85,29 @@ and patients in the numerator as follows: } } \details{ -The pre-processing steps are crucial when using this function. From the standard -lab grade variable \code{ATOXGR}, derive the following two variables: +The pre-processing steps are crucial when using this function. From the standard lab grade variable +\code{ATOXGR}, derive the following two variables: \itemize{ \item A grade direction variable (e.g. \code{GRADE_DIR}) is required in order to obtain the correct denominators when building the layout as it is used to define row splitting. \item A toxicity grade variable (e.g. \code{GRADE_ANL}) where all negative values from \code{ATOXGR} are replaced by their absolute values. -\item Prior to tabulation, \code{df} must filtered to include only post-baseline records with worst grade flags. } } \section{Functions}{ \itemize{ -\item \code{s_count_abnormal_by_worst_grade()}: Statistics function which counts patients with worst grade, -consisting of counts and percentages of patients with worst grade -\code{1} to \code{4}, and \code{Any} non-zero grade. +\item \code{s_count_abnormal_by_worst_grade()}: Statistics function which counts patients by worst grade. -\item \code{a_count_abnormal_by_worst_grade()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_abnormal_by_worst_grade()}: Formatted analysis function which is used as \code{afun} +in \code{count_abnormal_by_worst_grade()}. -\item \code{count_abnormal_by_worst_grade()}: Layout creating function which can be used for creating tables, -which can take statistics function arguments and additional format arguments (see below). +\item \code{count_abnormal_by_worst_grade()}: 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()}}. }} +\note{ +Prior to tabulation, \code{df} must be filtered to include only post-baseline records with worst grade flags. +} \examples{ library(dplyr) library(forcats) diff --git a/man/abnormal_by_worst_grade_worsen.Rd b/man/abnormal_by_worst_grade_worsen.Rd index 9abbaf4308..a140bf7739 100644 --- a/man/abnormal_by_worst_grade_worsen.Rd +++ b/man/abnormal_by_worst_grade_worsen.Rd @@ -59,13 +59,23 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=s_count_abnormal_lab_worsen_by_baseline]{s_count_abnormal_lab_worsen_by_baseline()}} returns the -counts and fraction of patients whose worst post-baseline lab grades are worse than -their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any". +\itemize{ +\item \code{s_count_abnormal_lab_worsen_by_baseline()} returns the counts and fraction of patients whose worst +post-baseline lab grades are worse than their baseline grades, for post-baseline worst grades +"1", "2", "3", "4" and "Any". +} -\code{\link[=a_count_abnormal_lab_worsen_by_baseline]{a_count_abnormal_lab_worsen_by_baseline()}} returns the corresponding list with +\itemize{ +\item \code{a_count_abnormal_lab_worsen_by_baseline()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. } + +\itemize{ +\item \code{count_abnormal_lab_worsen_by_baseline()} 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_abnormal_lab_worsen_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]}} @@ -73,14 +83,14 @@ Patient count and fraction for laboratory events (worsen from baseline) shift ta } \section{Functions}{ \itemize{ -\item \code{s_count_abnormal_lab_worsen_by_baseline()}: Statistics function which calculates the -counts and fraction of patients whose worst post-baseline lab grades are worse than -their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any". +\item \code{s_count_abnormal_lab_worsen_by_baseline()}: Statistics function for patients whose worst post-baseline +lab grades are worse than their baseline grades. -\item \code{a_count_abnormal_lab_worsen_by_baseline()}: +\item \code{a_count_abnormal_lab_worsen_by_baseline()}: Formatted analysis function which is used as \code{afun} +in \code{count_abnormal_lab_worsen_by_baseline()}. -\item \code{count_abnormal_lab_worsen_by_baseline()}: Layout creating function which can be used for creating tables, -which can take statistics function arguments and additional format arguments (see below). +\item \code{count_abnormal_lab_worsen_by_baseline()}: 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()}}. }} \examples{ @@ -144,6 +154,6 @@ 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()}} } \keyword{internal} diff --git a/man/add_rowcounts.Rd b/man/add_rowcounts.Rd index 963ab870f8..1ea0674e3c 100644 --- a/man/add_rowcounts.Rd +++ b/man/add_rowcounts.Rd @@ -10,16 +10,18 @@ add_rowcounts(lyt) \item{lyt}{(\code{layout})\cr input layout where analyses will be added to.} } \value{ -The modified layout where the latest row split labels now have the row-wise -total counts (i.e. without column based subsetting) attached in parentheses. Row -count values are contained in these row count rows but are not displayed so that -they are not considered zero rows by default when pruning. +A modified layout where the latest row split labels now have the row-wise +total counts (i.e. without column-based subsetting) attached in parentheses. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} This works analogously to \code{\link[rtables:add_colcounts]{rtables::add_colcounts()}} but on the rows. } +\note{ +Row count values are contained in these row count rows but are not displayed +so that they are not considered zero rows by default when pruning. +} \examples{ basic_table() \%>\% split_cols_by("ARM") \%>\% diff --git a/man/afun_selected_stats.Rd b/man/afun_selected_stats.Rd index 1699c91c6e..5409c44de8 100644 --- a/man/afun_selected_stats.Rd +++ b/man/afun_selected_stats.Rd @@ -13,7 +13,7 @@ in this context that all default statistics should be used.} \item{all_stats}{(\code{character})\cr all statistics which can be selected here potentially.} } \value{ -Character vector with the selected statistics. +A \code{character} vector with the selected statistics. } \description{ Helper function to be used for creating \code{afun}. diff --git a/man/analyze_vars_in_cols.Rd b/man/analyze_vars_in_cols.Rd index 2337ba3076..ccba1d8daf 100644 --- a/man/analyze_vars_in_cols.Rd +++ b/man/analyze_vars_in_cols.Rd @@ -39,18 +39,17 @@ underneath analyses, which is not allowed.} \item{.formats}{(named \code{character} or \code{list})\cr formats for the statistics.} } +\value{ +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 summarize the given variables, arrange the output +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 function can be used to produce summary tables for PK datasets where -the relevant statistic is on the columns instead of on the rows. +Layout-creating function which can be used for creating column-wise summary tables, primarily +used for PK data sets. This function is a wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. } -\section{Functions}{ -\itemize{ -\item \code{analyze_vars_in_cols()}: Layout creating -function which can be used for creating summary tables in columns, primarily used for PK data sets. - -}} \examples{ library(dplyr) @@ -110,6 +109,7 @@ lyt <- basic_table() \%>\% ) result <- build_table(lyt, df = adpp) result + } \seealso{ \link{summarize_vars}, \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. diff --git a/man/append_varlabels.Rd b/man/append_varlabels.Rd index 08d0b558ce..68f67cf6e1 100644 --- a/man/append_varlabels.Rd +++ b/man/append_varlabels.Rd @@ -17,7 +17,7 @@ append_varlabels(lyt, df, vars, indent = 0L) 1L means two spaces indent, 2L means four spaces indent and so on.} } \value{ -The modified layout. +A modified layout with the new variable label(s) added to the top-left material. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/arrange_grobs.Rd b/man/arrange_grobs.Rd index b21d7c170f..5348828526 100644 --- a/man/arrange_grobs.Rd +++ b/man/arrange_grobs.Rd @@ -35,6 +35,9 @@ arrange_grobs( \item{name}{a character identifier for the grob.} } +\value{ +A \code{grob}. +} \description{ Arrange grobs as a new grob with \verb{n*m (rows*cols)} layout. } diff --git a/man/as.rtable.Rd b/man/as.rtable.Rd index 15b6391e2a..25b2d1ccb0 100644 --- a/man/as.rtable.Rd +++ b/man/as.rtable.Rd @@ -17,8 +17,7 @@ as.rtable(x, ...) \item{format}{the format which should be used for the columns.} } \value{ -The \code{rtable} object. Note that the concrete class will depend on the method -which is used. +An \code{rtables} table object. Note that the concrete class will depend on the method used. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/as_factor_keep_attributes.Rd b/man/as_factor_keep_attributes.Rd index 59c0ed94b3..cd78c029a4 100644 --- a/man/as_factor_keep_attributes.Rd +++ b/man/as_factor_keep_attributes.Rd @@ -22,8 +22,7 @@ converting a character vector.} \item{verbose}{defaults to \code{TRUE}. It prints out warnings and messages.} } \value{ -The factor with same attributes (except class) as \code{x}. Does not do any modifications -if \code{x} is already a factor. +A \code{factor} with same attributes (except class) as \code{x}. Does not modify \code{x} if already a \code{factor}. } \description{ Converts \code{x} to a factor and keeps its attributes. Warns appropriately such that the user diff --git a/man/assertions.Rd b/man/assertions.Rd index 94d51ad704..741dda753b 100644 --- a/man/assertions.Rd +++ b/man/assertions.Rd @@ -91,19 +91,22 @@ for proportions.} \item{...}{a collection of objects to test.} } +\value{ +Nothing if assertion passes, otherwise prints the error message. +} \description{ Additional assertion functions which can be used together with the \code{checkmate} package. } \section{Functions}{ \itemize{ -\item \code{assert_list_of_variables()}: Check whether \code{x} is a valid list of variable names. -\code{NULL} elements of the list \code{x} are dropped out with \code{Filter(Negate(is.null), x)}. +\item \code{assert_list_of_variables()}: Checks whether \code{x} is a valid list of variable names. +\code{NULL} elements of the list \code{x} are dropped with \code{Filter(Negate(is.null), x)}. \item \code{assert_df_with_variables()}: Check whether \code{df} is a data frame with the analysis \code{variables}. Please notice how this produces an error when not all variables are present in the data.frame while the opposite is not required. -\item \code{assert_valid_factor()}: Check whether \code{x} is a valid factor (has levels and no empty +\item \code{assert_valid_factor()}: Check whether \code{x} is a valid factor (i.e. has levels and no empty string levels). Note that \code{NULL} and \code{NA} elements are allowed. \item \code{assert_df_with_factors()}: Check whether \code{df} is a data frame where the analysis \code{variables} diff --git a/man/bins_percent_labels.Rd b/man/bins_percent_labels.Rd index 1d8b174fa9..d77df9e9fd 100644 --- a/man/bins_percent_labels.Rd +++ b/man/bins_percent_labels.Rd @@ -14,7 +14,7 @@ the boundaries 0 and 1 must not be included.} \item{digits}{(\code{integer})\cr number of decimal places to round the percent numbers.} } \value{ -Character vector with labels in the format \verb{[0\%,20\%]}, \verb{(20\%,50\%]}, etc. +A \code{character} vector with labels in the format \verb{[0\%,20\%]}, \verb{(20\%,50\%]}, etc. } \description{ This creates labels for quantile based bins in percent. This assumes the right-closed diff --git a/man/c_label_n.Rd b/man/c_label_n.Rd index 167aaa8722..01b1e816bf 100644 --- a/man/c_label_n.Rd +++ b/man/c_label_n.Rd @@ -15,13 +15,13 @@ c_label_n(df, labelstr, .N_row) \item{.N_row}{(\code{count})\cr column-wise N (column count) for the full column that is passed by \code{rtables}.} } \value{ -list containing "row_count" with the row count value and the correct label. +A \code{list} containing "row_count" with the row count value and the correct label. } \description{ This takes the label of the latest row split level and adds the row total in parentheses. } \note{ -Important is here to not use \code{df} but \code{.N_row} in the implementation, because the former -is already split by columns and will refer to the first column of the data only. +It is important here to not use \code{df} but rather \code{.N_row} in the implementation, because +the former is already split by columns and will refer to the first column of the data only. } \keyword{internal} diff --git a/man/cfun_by_flag.Rd b/man/cfun_by_flag.Rd index a867b868c5..789fc0d323 100644 --- a/man/cfun_by_flag.Rd +++ b/man/cfun_by_flag.Rd @@ -16,7 +16,7 @@ row should be returned.} \item{format}{(\code{string})\cr \code{rtables} format to use.} } \value{ -Content function which just gives \code{df$analysis_var} at the row identified by +A content function which gives \code{df$analysis_var} at the row identified by \code{.df_row$flag} in the given format. } \description{ diff --git a/man/check_same_n.Rd b/man/check_same_n.Rd index aab10b0a6e..43bc7ca217 100644 --- a/man/check_same_n.Rd +++ b/man/check_same_n.Rd @@ -11,6 +11,9 @@ check_same_n(..., omit_null = TRUE) \item{omit_null}{are \code{NULL} elements in \code{...} to be omitted from the check?} } +\value{ +A \code{logical} value. +} \description{ Checks if the elements in \code{...} have the same dimension. } diff --git a/man/combination_function.Rd b/man/combination_function.Rd index 1e672080b2..494a696f86 100644 --- a/man/combination_function.Rd +++ b/man/combination_function.Rd @@ -23,6 +23,9 @@ \item{x}{(\code{CombinationFunction})\cr the function which should be negated.} } +\value{ +Returns a logical value indicating whether the left hand side of the equation equals the right hand side. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/combine_counts.Rd b/man/combine_counts.Rd index af94abb992..2894586ad3 100644 --- a/man/combine_counts.Rd +++ b/man/combine_counts.Rd @@ -12,6 +12,9 @@ combine_counts(fct, groups_list = NULL) \item{groups_list}{(named \code{list} of \code{character})\cr 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.} } +\value{ +A \code{vector} of column counts. +} \description{ Simplifies the estimation of column counts, especially when group combination is required. diff --git a/man/combine_groups.Rd b/man/combine_groups.Rd index 1e7550b087..888703de59 100644 --- a/man/combine_groups.Rd +++ b/man/combine_groups.Rd @@ -14,8 +14,7 @@ combine_groups(fct, ref = NULL, collapse = "/") \item{collapse}{(\code{string})\cr a character string to separate \code{fct} and \code{ref}.} } \value{ -a \code{list} with first item \code{ref} (reference) and second item \code{trt} -(treatment). +A \code{list} with first item \code{ref} (reference) and second item \code{trt} (treatment). } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/combine_levels.Rd b/man/combine_levels.Rd index 943754a3e8..ecee143b57 100644 --- a/man/combine_levels.Rd +++ b/man/combine_levels.Rd @@ -14,7 +14,7 @@ combine_levels(x, levels, new_level = paste(levels, collapse = "/")) \item{new_level}{name of new level} } \value{ -a factor +A \code{factor} with the new levels. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/compare_variables.Rd b/man/compare_variables.Rd index 2bdf50a6f0..037f42bcfb 100644 --- a/man/compare_variables.Rd +++ b/man/compare_variables.Rd @@ -104,8 +104,8 @@ can only be \code{n} (number of values in this row and column intersection).} \item{.var}{(\code{string})\cr single variable name that is passed by \code{rtables} when requested by a statistics function.} -\item{verbose}{defaults to \code{TRUE}. It prints out warnings and messages. It is mainly used -to print out information about factor casting.} +\item{verbose}{(\code{logical})\cr Whether warnings and messages should be printed. Mainly used +to print out information about factor casting. Defaults to \code{TRUE}.} \item{lyt}{(\code{layout})\cr input layout where analyses will be added to.} @@ -131,79 +131,70 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -If \code{x} is of class \code{numeric}, returns a list with named items: \itemize{ -\item all items from \code{\link[=s_summary.numeric]{s_summary.numeric()}}. -\item \code{pval}: the p-value. +\item \code{s_compare()} returns output of \code{\link[=s_summary]{s_summary()}} and comparisons versus the reference group in the form of p-values. } -If \code{x} is of class \code{factor} or converted from \code{character}, returns a list with named items: \itemize{ -\item all items from \code{\link[=s_summary.factor]{s_summary.factor()}}. -\item \code{pval}: the p-value. +\item \code{a_compare()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. } -If \code{x} is of class \code{logical}, returns a list with named items: \itemize{ -\item all items from \code{\link[=s_summary.logical]{s_summary.logical()}}. -\item \code{pval}: the p-value. +\item \code{compare_vars()} 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_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]}} -We use the new S3 generic function \code{\link[=s_compare]{s_compare()}} to implement comparisons for -different \code{x} objects. This is used as Statistics Function in combination -with the new Analyze Function \code{\link[=compare_vars]{compare_vars()}}. +Comparison with a reference group for different \code{x} objects. } \section{Functions}{ \itemize{ -\item \code{s_compare()}: \code{s_compare} is a S3 generic function to produce -an object description and comparison versus the reference column in the form -of p-values. +\item \code{s_compare()}: S3 generic function to produce a comparison summary. -\item \code{s_compare(numeric)}: Method for numeric class. This uses the standard t-test +\item \code{s_compare(numeric)}: Method for \code{numeric} class. This uses the standard t-test to calculate the p-value. -\item \code{s_compare(factor)}: Method for factor class. This uses the chi-squared test -to calculate the p-value. Note that the \code{denom} for factor proportions can only be \code{n} here -since the usage is for comparing proportions between columns. -Therefore a row-based proportion would not make sense. Also proportion based on \code{N_col} would -be difficult since for the chi-squared test statistic we use the counts. Therefore -missing values should be accounted for explicitly as factor levels. +\item \code{s_compare(factor)}: Method for \code{factor} class. This uses the chi-squared test +to calculate the p-value. -\item \code{s_compare(character)}: Method for character class. This makes an automatic -conversion to factor (with a warning) and then forwards to the method for factors. +\item \code{s_compare(character)}: Method for \code{character} class. This makes an automatic +conversion to \code{factor} (with a warning) and then forwards to the method for factors. -\item \code{s_compare(logical)}: Method for logical class. A chi-squared test +\item \code{s_compare(logical)}: Method for \code{logical} class. A chi-squared test is used. If missing values are not removed, then they are counted as \code{FALSE}. -\item \code{a_compare()}: S3 generic Formatted Analysis function to produce -an object description and comparison versus the reference column in the form -of p-values. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_compare()}: Formatted analysis function which is used as \code{afun} +in \code{compare_vars()}. -\item \code{a_compare(numeric)}: Formatted Analysis function method for \code{numeric}. +\item \code{a_compare(numeric)}: Formatted analysis function method for \code{numeric} class. -\item \code{a_compare(factor)}: Formatted Analysis function method for \code{factor}. +\item \code{a_compare(factor)}: Formatted analysis function method for \code{factor} class. -\item \code{a_compare(character)}: Formatted Analysis function method for \code{character}. +\item \code{a_compare(character)}: Formatted analysis function method for \code{character} class. -\item \code{a_compare(logical)}: Formatted Analysis function method for \code{logical}. +\item \code{a_compare(logical)}: Formatted analysis function method for \code{logical} class. -\item \code{compare_vars()}: Analyze Function to add a comparison of variables to -\code{rtables} pipelines. The column split needs to have the reference group defined -via \code{ref_group} so that the comparison is well defined. -The ellipsis (\code{...}) conveys arguments to \code{\link[=s_compare]{s_compare()}}. -When factor variables contains \code{NA}, it is expected that \code{NA} -have been conveyed to \code{na_level} appropriately beforehand with -\code{\link[=df_explicit_na]{df_explicit_na()}}. +\item \code{compare_vars()}: 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()}}. }} \note{ -Automatic conversion of character to factor does not guarantee that the table -can be generated correctly. In particular for sparse tables this very likely can fail. -It is therefore better to always pre-process the dataset such that factors are manually -created from character variables before passing the dataset to \code{\link[rtables:build_table]{rtables::build_table()}}. +\itemize{ +\item For factor variables, \code{denom} for factor proportions can only be \code{n} since the purpose is to compare proportions +between columns, therefore a row-based proportion would not make sense. Proportion based on \code{N_col} would +be difficult since we use counts for the chi-squared test statistic, therefore missing values should be accounted +for as explicit factor levels. +\item For character variables, automatic conversion to factor does not guarantee that the table +will be generated correctly. In particular for sparse tables this very likely can fail. +Therefore it is always better to manually convert character variables to factors during pre-processing. +\item For \code{compare_vars()}, the column split must define a reference group via \code{ref_group} so that the comparison +is well defined. +\item When factor variables contains \code{NA}, it is expected that \code{NA} values have been conveyed to \code{na_level} +appropriately beforehand via \code{\link[=df_explicit_na]{df_explicit_na()}}. +} } \examples{ # `s_compare.numeric` @@ -311,7 +302,6 @@ lyt <- basic_table() \%>\% build_table(lyt, df = tern_ex_adsl) } \seealso{ -Relevant constructor function \code{\link[=create_afun_compare]{create_afun_compare()}}. - -\code{\link[=s_summary]{s_summary()}} which is used internally for the summary part per column. +Relevant constructor function \code{\link[=create_afun_compare]{create_afun_compare()}}, and \code{\link[=s_summary]{s_summary()}} which is used internally +to compute a summary within \code{s_compare()}. } diff --git a/man/control_coxreg.Rd b/man/control_coxreg.Rd index b7b68c1089..6a51c4bd61 100644 --- a/man/control_coxreg.Rd +++ b/man/control_coxreg.Rd @@ -27,7 +27,7 @@ for univariate models without treatment arm, and multivariate models, no interaction can be used so that this needs to be \code{FALSE}.} } \value{ -A \code{list} of item corresponding to the arguments. +A \code{list} of items with names corresponding to the arguments. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/control_incidence_rate.Rd b/man/control_incidence_rate.Rd index 68bcaa0d89..0c67fefbe3 100644 --- a/man/control_incidence_rate.Rd +++ b/man/control_incidence_rate.Rd @@ -23,7 +23,7 @@ indicating time unit for data input.} \item{time_unit_output}{(\code{numeric})\cr time unit for desired output (in person-years).} } \value{ -A list of components with the same name as the arguments. +A list of components with the same names as the arguments. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/control_lineplot_vars.Rd b/man/control_lineplot_vars.Rd index e019bd04bd..bde3591b71 100644 --- a/man/control_lineplot_vars.Rd +++ b/man/control_lineplot_vars.Rd @@ -24,7 +24,7 @@ control_lineplot_vars( \item{y_unit}{(\code{character} or \code{NA})\cr y_unit variable name.} } \value{ -A named character vector with names of variables. +A named character vector of variable names. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -36,6 +36,3 @@ A variable's default value can be overwritten for any variable. control_lineplot_vars() control_lineplot_vars(strata = NA) } -\author{ -Wojciech Wojciak wojciech.wojciak@contractors.roche.com -} diff --git a/man/count_cumulative.Rd b/man/count_cumulative.Rd index c32c1d3ad0..32add27595 100644 --- a/man/count_cumulative.Rd +++ b/man/count_cumulative.Rd @@ -71,10 +71,20 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -A named list of \code{count_fraction}s: a list with each \code{thresholds} value as a component, each component -contains a vector for the count and fraction. +\itemize{ +\item \code{s_count_cumulative()} returns a named list of \code{count_fraction}s: a list with each \code{thresholds} value as a +component, each component containing a vector for the count and fraction. +} -\code{\link[=a_count_cumulative]{a_count_cumulative()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\itemize{ +\item \code{a_count_cumulative()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_cumulative()} 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_cumulative()} 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]}} @@ -84,15 +94,13 @@ greater than, or greater or equal to user-specific thresholds. } \section{Functions}{ \itemize{ -\item \code{s_count_cumulative()}: Statistics function that produces a named lists given a numeric vector of thresholds. +\item \code{s_count_cumulative()}: Statistics function that produces a named list given a numeric vector of thresholds. -\item \code{a_count_cumulative()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_cumulative()}: Formatted analysis function which is used as \code{afun} +in \code{count_cumulative()}. -\item \code{count_cumulative()}: Layout creating function which can be be used for creating -summary tables for cumulative counts of a variable. The ellipsis (\code{...}) conveys -arguments to \code{s_count_cumulative()}, for instance \code{lower_tail = FALSE} if upper tail -should be accounted for. +\item \code{count_cumulative()}: 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()}}. }} \examples{ @@ -123,6 +131,6 @@ basic_table() \%>\% build_table(tern_ex_adsl) } \seealso{ -Relevant helper function \code{\link[=h_count_cumulative]{h_count_cumulative()}}, and descriptive function \code{\link[=d_count_cumulative]{d_count_cumulative()}} +Relevant helper function \code{\link[=h_count_cumulative]{h_count_cumulative()}}, and descriptive function \code{\link[=d_count_cumulative]{d_count_cumulative()}}. } \keyword{internal} diff --git a/man/count_missed_doses.Rd b/man/count_missed_doses.Rd index 65057347f8..ea15cee7b7 100644 --- a/man/count_missed_doses.Rd +++ b/man/count_missed_doses.Rd @@ -56,10 +56,23 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -\code{\link[=s_count_nonmissing]{s_count_nonmissing()}} returns the statistic \code{n} which is the count of non-missing values in \code{x}. +\itemize{ +\item \code{s_count_nonmissing()} returns the statistic \code{n} which is the count of non-missing values in \code{x}. +} + +\itemize{ +\item \code{s_count_missed_doses()} returns the statistics \code{n} and \code{count_fraction} with one element for each threshold. +} -\code{\link[=s_count_missed_doses]{s_count_missed_doses()}} returns the statistics \code{n} and -\code{count_fraction} with one element for each threshold. +\itemize{ +\item \code{a_count_missed_doses()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_missed_doses()} 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_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]}} @@ -71,14 +84,13 @@ mainly the special labels. \itemize{ \item \code{s_count_nonmissing()}: Statistics function to count non-missing values. -\item \code{s_count_missed_doses()}: Statistics function to count patients with missed doses when \code{x} -is the vector of number of missed doses with one value for each patient. +\item \code{s_count_missed_doses()}: Statistics function to count patients with missed doses. -\item \code{a_count_missed_doses()}: Formatted Analysis function to count non-missing values. +\item \code{a_count_missed_doses()}: Formatted analysis function which is used as \code{afun} +in \code{count_missed_doses()}. -\item \code{count_missed_doses()}: Layout creating function which can be be used for creating -summary tables for summarizing missed doses given user-specified \code{thresholds}. This is -an additional layer on top of \code{count_cumulative} specifically for missed doses. +\item \code{count_missed_doses()}: 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()}}. }} \examples{ diff --git a/man/count_occurrences.Rd b/man/count_occurrences.Rd index d12d0e4375..7afd6c2223 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -83,36 +83,51 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -A list with: -\describe{ -\item{count}{list of counts with one element per occurrence.} -\item{count_fraction}{list of counts and fractions with one element per occurrence.} -\item{fraction}{list of numerators and denominators with one element per occurrence.} +\itemize{ +\item \code{s_count_occurrences()} returns a list with: +\itemize{ +\item \code{count}: list of counts with one element per occurrence. +\item \code{count_fraction}: list of counts and fractions with one element per occurrence. +\item \code{fraction}: list of numerators and denominators with one element per occurrence. +} +} + +\itemize{ +\item \code{a_count_occurrences()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_occurrences()} 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_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]}} -} -\details{ + 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. Note that by default occurrences which don't appear in a given row split -are dropped from the table and the occurrences in the table are sorted alphabetically per row split. -Therefore the corresponding layout needs to use \code{split_fun = drop_split_levels} in the \code{split_rows_by} -calls. Use \code{drop = FALSE} if you would like to show all occurrences. +counted only once. } \section{Functions}{ \itemize{ \item \code{s_count_occurrences()}: Statistics function which counts number of patients that report an occurrence. -\item \code{a_count_occurrences()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_occurrences()}: Formatted analysis function which is used as \code{afun} +in \code{count_occurrences()}. -\item \code{count_occurrences()}: Analyze Function that counts occurrences as part of \code{rtables} layouts. +\item \code{count_occurrences()}: 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()}}. }} +\note{ +By default, occurrences which don't appear in a given row split are dropped from the table and +the occurrences in the table are sorted alphabetically per row split. Therefore, the corresponding layout +needs to use \code{split_fun = drop_split_levels} in the \code{split_rows_by} calls. Use \code{drop = FALSE} if you would +like to show all occurrences. +} \examples{ df <- data.frame( USUBJID = as.character(c(1, 1, 2, 4, 4, 4)), diff --git a/man/count_occurrences_by_grade.Rd b/man/count_occurrences_by_grade.Rd index 461692200b..b526289734 100644 --- a/man/count_occurrences_by_grade.Rd +++ b/man/count_occurrences_by_grade.Rd @@ -88,6 +88,28 @@ to avoid warnings from \code{rtables}.} \item{.labels}{(named \code{character})\cr labels for the statistics (without indent).} } +\value{ +\itemize{ +\item \code{s_count_occurrences_by_grade()} returns a list of counts and fractions with one element per grade level or +grade level grouping. +} + +\itemize{ +\item \code{a_count_occurrences_by_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_occurrences_by_grade()} 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_occurrences_by_grade()} to the table layout. +} + +\itemize{ +\item \code{summarize_occurrences_by_grade()} 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 content rows +containing the statistics from \code{s_count_occurrences_by_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]}} @@ -97,18 +119,17 @@ greatest intensity/highest grade level. } \section{Functions}{ \itemize{ -\item \code{s_count_occurrences_by_grade()}: Statistics function which given occurrence data counts the -number of patients by highest grade. Returns a list of counts and fractions with one element -per grade level or grade level grouping. +\item \code{s_count_occurrences_by_grade()}: Statistics function which counts the +number of patients by highest grade. -\item \code{a_count_occurrences_by_grade()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_occurrences_by_grade()}: Formatted analysis function which is used as \code{afun} +in \code{count_occurrences_by_grade()}. -\item \code{count_occurrences_by_grade()}: Layout creating function which can be used for creating tables, -which can take statistics function arguments and additional format arguments (see below). +\item \code{count_occurrences_by_grade()}: 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{summarize_occurrences_by_grade()}: Layout creating function which adds content rows using the -statistics function and additional format arguments (see below). +\item \code{summarize_occurrences_by_grade()}: Layout-creating function which can take content function arguments +and additional format arguments. This function is a wrapper for \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. }} \examples{ diff --git a/man/count_patients_events_in_cols.Rd b/man/count_patients_events_in_cols.Rd index 7c221e6875..63081568fb 100644 --- a/man/count_patients_events_in_cols.Rd +++ b/man/count_patients_events_in_cols.Rd @@ -56,7 +56,8 @@ be used as label.} Set to \code{FALSE} when the required column split has been done already earlier in the layout pipe.} } \value{ -\code{\link[=s_count_patients_and_multiple_events]{s_count_patients_and_multiple_events()}} returns a list with the statistics: +\itemize{ +\item \code{s_count_patients_and_multiple_events()} returns a list with the statistics: \itemize{ \item \code{unique}: number of unique patients in \code{df}. \item \code{all}: number of rows in \code{df}. @@ -64,6 +65,13 @@ Set to \code{FALSE} when the required column split has been done already earlier i.e. events, fulfilling the filter condition. } } + +\itemize{ +\item \code{summarize_patients_events_in_cols()} 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 content rows +containing the statistics from \code{s_count_patients_and_multiple_events()} 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]}} @@ -72,11 +80,11 @@ when a column table layout is required. } \section{Functions}{ \itemize{ -\item \code{s_count_patients_and_multiple_events()}: Statistics function which counts numbers of patients and multiple events -defined by filters. +\item \code{s_count_patients_and_multiple_events()}: Statistics function which counts numbers of patients and multiple +events defined by filters. Used as analysis function \code{afun} in \code{summarize_patients_events_in_cols()}. -\item \code{summarize_patients_events_in_cols()}: Layout creating function which adds the count -statistics of patients and events in the column layout as content rows. +\item \code{summarize_patients_events_in_cols()}: Layout-creating function which can take statistics function +arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. }} \examples{ diff --git a/man/count_patients_with_event.Rd b/man/count_patients_with_event.Rd index 88757ec5b0..d1b8111cb0 100644 --- a/man/count_patients_with_event.Rd +++ b/man/count_patients_with_event.Rd @@ -119,37 +119,59 @@ by a statistics function.} \item{show_labels}{(\code{string})\cr label visibility: one of "default", "visible" and "hidden".} } \value{ -\code{\link[=s_count_patients_with_event]{s_count_patients_with_event()}} returns the count and fraction of patients with the -defined event. +\itemize{ +\item \code{s_count_patients_with_event()} returns the count and fraction of unique identifiers with the defined event. +} + +\itemize{ +\item \code{a_count_patients_with_event()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_patients_with_event()} 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_patients_with_event()} to the table layout. +} + +\itemize{ +\item \code{s_count_patients_with_flags()} returns the count and the fraction of unique identifiers with each particular +flag as a list of statistics \code{n}, \code{count}, \code{count_fraction}, and \code{n_blq}, with one element per flag. +} + +\itemize{ +\item \code{a_count_patients_with_flags()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{count_patients_with_flags()} 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_patients_with_flags()} 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]}} -} -\details{ + The primary analysis variable \code{.var} denotes the unique patient identifier. } \section{Functions}{ \itemize{ -\item \code{s_count_patients_with_event()}: Statistics Function that returns the number and the fraction -of unique identifiers with a particular type of event, e.g. the number and the fraction of patients who -had treatment-emergent adverse events. Note that the user can define a new data column containing -the event of interest. +\item \code{s_count_patients_with_event()}: Statistics function which counts the number of patients for which +the defined event has occurred. -\item \code{a_count_patients_with_event()}: Formatted Analysis function which can be further -customized by calling \code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_patients_with_event()}: Formatted analysis function which is used as \code{afun} +in \code{count_patients_with_event()}. -\item \code{count_patients_with_event()}: Analyze Function which adds the count statistics -to the input layout. Note that additional formatting arguments can be used here. +\item \code{count_patients_with_event()}: 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_patients_with_flags()}: Statistics function that returns the number and the fraction -of unique identifiers with each particular flag. Returns a list of totals, counts, counts and -fractions with one element per flag. +\item \code{s_count_patients_with_flags()}: Statistics function which counts the number of patients for which +a particular flag variable is \code{TRUE}. -\item \code{a_count_patients_with_flags()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_patients_with_flags()}: Formatted analysis function which is used as \code{afun} +in \code{count_patients_with_flags()}. -\item \code{count_patients_with_flags()}: Analyze Function which is a modified version of \code{\link[=count_patients_with_event]{count_patients_with_event()}}. -Adds the count statistics to the input layout for multiple flag variables at once. +\item \code{count_patients_with_flags()}: 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()}}. }} \examples{ diff --git a/man/count_values_funs.Rd b/man/count_values_funs.Rd index 965e147a12..de2b572c35 100644 --- a/man/count_values_funs.Rd +++ b/man/count_values_funs.Rd @@ -83,7 +83,19 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -See \code{\link[=s_summary.logical]{s_summary.logical()}} for the returned statistics, as this is used inside. +\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()}}. +} + +\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. +} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -92,27 +104,29 @@ We can count the occurrence of specific values in a variable of interest. } \section{Functions}{ \itemize{ -\item \code{s_count_values()}: Statistics Function which is a generic function to count values. +\item \code{s_count_values()}: S3 generic function to count values. -\item \code{s_count_values(character)}: Method for \code{character} vectors \code{x}. +\item \code{s_count_values(character)}: Method for \code{character} class. -\item \code{s_count_values(factor)}: method for \code{factor} vectors \code{x}. This checks whether \code{values} are all -included in the levels of \code{x} and fails otherwise. It then proceeds by converting to \code{character} -and calling \code{s_count_values.character}. +\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} vectors \code{x}. +\item \code{s_count_values(logical)}: Method for \code{logical} class. -\item \code{a_count_values()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_count_values()}: Formatted analysis function which is used as \code{afun} +in \code{count_values()}. -\item \code{count_values()}: Analyze Function which adds the counting analysis to -the input layout. Note that additional formatting arguments can be used -here. +\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()}}. }} \note{ -Variable labels are shown when there is more than one element in \code{vars}, otherwise they -are hidden. +\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{ # `s_count_values.character` diff --git a/man/cox_regression.Rd b/man/cox_regression.Rd index 1f8f04e996..bb0e9d2266 100644 --- a/man/cox_regression.Rd +++ b/man/cox_regression.Rd @@ -56,7 +56,7 @@ function with tidying applied via \code{\link[broom:reexports]{broom::tidy()}}.} \item{.which_vars}{(\code{character})\cr which rows should statistics be returned for from the given model. Defaults to "all". Other options include "var_main" for main effects, "inter" for interaction effects, -and "multi_lvl" for multivariable model covariate level rows. When \code{.which_vars} is "all" specific +and "multi_lvl" for multivariate model covariate level rows. When \code{.which_vars} is "all" specific variables can be selected by specifying \code{.var_nms}.} \item{.var_nms}{(\code{character})\cr the \code{term} value of rows in \code{df} for which \code{.stats} should be returned. Typically @@ -73,7 +73,7 @@ is "var_main" \code{.var_nms} should be only the variable name.} \item{var_main}{(\code{flag})\cr whether main effects should be calculated. Defaults to \code{FALSE}.} -\item{multivar}{(\code{flag})\cr Defaults to \code{FALSE}. If \code{TRUE} multivariable Cox regression will run, otherwise +\item{multivar}{(\code{flag})\cr Defaults to \code{FALSE}. If \code{TRUE} multivariate Cox regression will run, otherwise univariable Cox regression will run.} \item{variables}{(named \code{list} of \code{string})\cr list of additional analysis variables.} @@ -106,6 +106,21 @@ for all rows. This should be created during pre-processing if no such variable c Defaults to \code{NA} for no section divider. If a vector of two strings are given, the first will be used between treatment and covariate sections and the second between different covariates.} } +\value{ +\itemize{ +\item \code{s_coxreg()} returns the selected statistic for from the Cox regression model for the selected variable(s). +} + +\itemize{ +\item \code{a_coxreg()} returns formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{summarize_coxreg()} 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 a Cox regression table +containing the chosen statistics 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]}} @@ -122,14 +137,14 @@ analysis (NEST Team, 2020). } \section{Functions}{ \itemize{ -\item \code{s_coxreg()}: transforms the tabulated results from \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} -and \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} into a list. Not much calculation is done here, -it rather prepares the data to be used by the layout creating function. +\item \code{s_coxreg()}: Statistics function that transforms results tabulated +from \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} or \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} into a list. -\item \code{a_coxreg()}: Analysis function. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}} +\item \code{a_coxreg()}: Analysis function which is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}} and \code{cfun} in \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}} within \code{summarize_coxreg()}. -\item \code{summarize_coxreg()}: layout creating function. +\item \code{summarize_coxreg()}: Layout-creating function which creates a Cox regression summary table +layout. This function is a wrapper for several \code{rtables} layouting functions. }} \examples{ @@ -183,7 +198,7 @@ univar_covs_model <- fit_coxreg_univar(variables = u2_variables, data = dta_blad df1_covs <- broom::tidy(univar_covs_model) s_coxreg(model_df = df1_covs, .stats = "hr", .var_nms = c("COVAR2", "Sex (F/M)")) -# Multivariable. +# Multivariate. m1_variables <- list( time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2") ) @@ -195,7 +210,7 @@ s_coxreg( .var_nms = c("COVAR1", "A Covariate Label") ) -# Multivariable without treatment arm - only "COVAR1" main effect +# Multivariate without treatment arm - only "COVAR1" main effect m2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2")) multivar_covs_model <- fit_coxreg_multivar(variables = m2_variables, data = dta_bladder) df2_covs <- broom::tidy(multivar_covs_model) @@ -256,7 +271,7 @@ result_multivar_covs helper functions, and \link{tidy_coxreg} for custom tidy methods. \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} and \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} which also take the \code{variables}, \code{data}, -\code{at} (univariable only), and \code{control} arguments but return unformatted univariable and multivariable +\code{at} (univariable only), and \code{control} arguments but return unformatted univariable and multivariate Cox regression models, respectively. } \keyword{internal} diff --git a/man/cox_regression_inter.Rd b/man/cox_regression_inter.Rd index 9024af3d7d..8f68324851 100644 --- a/man/cox_regression_inter.Rd +++ b/man/cox_regression_inter.Rd @@ -35,11 +35,9 @@ h_coxreg_inter_estimations( \item{mod}{(\code{coxph})\cr a fitted Cox regression model (see \code{\link[survival:coxph]{survival::coxph()}}).} -\item{label}{(\code{string})\cr the label to be return as \code{term_label} -(see \code{return}).} +\item{label}{(\code{string})\cr the label to be returned as \code{term_label}.} -\item{control}{(\code{list})\cr a list of controls as returned by -\code{\link[=control_coxreg]{control_coxreg()}}.} +\item{control}{(\code{list})\cr a list of controls as returned by \code{\link[=control_coxreg]{control_coxreg()}}.} \item{...}{see methods.} @@ -56,13 +54,25 @@ of the levels of \code{variable} given the levels of \code{given}.} \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} } \value{ -A list of matrix (one per level of variable) with rows corresponding to the combinations of -\code{variable} and \code{given}, with columns: -\describe{ -\item{coef_hat}{Estimation of the coefficient.} -\item{coef_se}{Standard error of the estimation.} -\item{hr}{Hazard ratio.} -\item{lcl, ucl}{Lower/upper confidence limit of the hazard ratio.} +\itemize{ +\item \code{h_coxreg_inter_effect()} returns a \code{data.frame} of covariate interaction effects consisting of the following +variables: \code{effect}, \code{term}, \code{term_label}, \code{level}, \code{n}, \code{hr}, \code{lcl}, \code{ucl}, \code{pval}, and \code{pval_inter}. +} + +\itemize{ +\item \code{h_coxreg_extract_interaction()} returns the result of an interaction test and the estimated values. If +no interaction, \code{\link[=h_coxreg_univar_extract]{h_coxreg_univar_extract()}} is applied instead. +} + +\itemize{ +\item \code{h_coxreg_inter_estimations()} returns a list of matrices (one per level of variable) with rows corresponding +to the combinations of \code{variable} and \code{given}, with columns: +\itemize{ +\item \code{coef_hat}: Estimation of the coefficient. +\item \code{coef_se}: Standard error of the estimation. +\item \code{hr}: Hazard ratio. +\item \verb{lcl, ucl}: Lower/upper confidence limit of the hazard ratio. +} } } \description{ @@ -89,17 +99,18 @@ is obtained as $sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$. } \section{Functions}{ \itemize{ -\item \code{h_coxreg_inter_effect(numeric)}: Estimate the interaction with a numerical -covariate +\item \code{h_coxreg_inter_effect()}: S3 generic helper function to determine interaction effect. + +\item \code{h_coxreg_inter_effect(numeric)}: Estimate the interaction with a \code{numeric} +covariate. -\item \code{h_coxreg_inter_effect(factor)}: Estimate the interaction with a factor +\item \code{h_coxreg_inter_effect(factor)}: Estimate the interaction with a \code{factor} covariate. -\item \code{h_coxreg_extract_interaction()}: a higher level function that returns -the test of the interaction test and the estimated values. If -no interaction, \code{\link[=h_coxreg_univar_extract]{h_coxreg_univar_extract()}} is applied. +\item \code{h_coxreg_extract_interaction()}: A higher level function to get +the results of the interaction test and the estimated values. -\item \code{h_coxreg_inter_estimations()}: hazard ratio estimation in interactions. +\item \code{h_coxreg_inter_estimations()}: Hazard ratio estimation in interactions. }} \examples{ diff --git a/man/create_afun_compare.Rd b/man/create_afun_compare.Rd index b8a4323d5a..9730b60939 100644 --- a/man/create_afun_compare.Rd +++ b/man/create_afun_compare.Rd @@ -20,9 +20,13 @@ create_afun_compare( \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +Combined formatted analysis function for use in \code{\link[=compare_vars]{compare_vars()}}. +} \description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} Constructor function which creates a combined Formatted -Analysis function for use in layout creating functions \code{\link[=compare_vars]{compare_vars()}}. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +Constructor function which creates a combined formatted analysis function. } \note{ Since \code{\link[=a_compare]{a_compare()}} is generic and we want customization of the formatting arguments @@ -59,5 +63,5 @@ lyt <- basic_table() \%>\% build_table(lyt, df = tern_ex_adsl) } \seealso{ -\link{compare_variables} +\code{\link[=compare_vars]{compare_vars()}} } diff --git a/man/create_afun_summary.Rd b/man/create_afun_summary.Rd index f7abb0f1a6..0dee04b719 100644 --- a/man/create_afun_summary.Rd +++ b/man/create_afun_summary.Rd @@ -15,10 +15,13 @@ create_afun_summary(.stats, .formats, .labels, .indent_mods) \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +Combined formatted analysis function for use in \code{\link[=summarize_vars]{summarize_vars()}}. +} \description{ -Constructor function which creates a combined Formatted -Analysis function for use in layout creating functions \code{\link[=summarize_vars]{summarize_vars()}} and -\code{\link[=summarize_colvars]{summarize_colvars()}}. +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +Constructor function which creates a combined formatted analysis function. } \note{ Since \code{\link[=a_summary]{a_summary()}} is generic and we want customization of the formatting arguments diff --git a/man/cut_quantile_bins.Rd b/man/cut_quantile_bins.Rd index c51081ffb1..53d7d866be 100644 --- a/man/cut_quantile_bins.Rd +++ b/man/cut_quantile_bins.Rd @@ -29,15 +29,17 @@ probabilities in \code{probs}, then this must be \code{n + 1} long.} \item{ordered}{(\code{flag})\cr should the result be an ordered factor.} } \value{ -The factor variable with the appropriately labeled bins as levels. +A \code{factor} variable with appropriately-labeled bins as levels. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -This cuts a numeric vector into sample quantile bins. Note that the intervals are closed on -the right side. That is, the first bin is the interval \verb{[-Inf, q1]} where \code{q1} is -the first quantile, the second bin is then \verb{(q1, q2]}, etc., and the last bin -is \verb{(qn, +Inf]} where \code{qn} is the last quantile. +This cuts a numeric vector into sample quantile bins. +} +\note{ +Intervals are closed on the right side. That is, the first bin is the interval +\verb{[-Inf, q1]} where \code{q1} is the first quantile, the second bin is then \verb{(q1, q2]}, etc., +and the last bin is \verb{(qn, +Inf]} where \code{qn} is the last quantile. } \examples{ # Default is to cut into quartile bins. diff --git a/man/d_count_abnormal_by_baseline.Rd b/man/d_count_abnormal_by_baseline.Rd index c748fd2e81..ae1fbedd0e 100644 --- a/man/d_count_abnormal_by_baseline.Rd +++ b/man/d_count_abnormal_by_baseline.Rd @@ -9,6 +9,9 @@ d_count_abnormal_by_baseline(abnormal) \arguments{ \item{abnormal}{(\code{character})\cr identifying the abnormal range level(s) in \code{.var}.} } +\value{ +Abnormal category labels for \code{\link[=s_count_abnormal_by_baseline]{s_count_abnormal_by_baseline()}}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/d_count_cumulative.Rd b/man/d_count_cumulative.Rd index b4bb51e0a2..09bb330146 100644 --- a/man/d_count_cumulative.Rd +++ b/man/d_count_cumulative.Rd @@ -15,13 +15,10 @@ d_count_cumulative(threshold, lower_tail, include_eq) count, default is \code{TRUE}.} } \value{ -a descriptive \code{string}. +Labels for \code{\link[=s_count_cumulative]{s_count_cumulative()}}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -This is a helper function that describes analysis in \code{\link[=s_count_cumulative]{s_count_cumulative()}}. -} -\seealso{ -\code{\link[=s_count_cumulative]{s_count_cumulative()}} +This is a helper function that describes the analysis in \code{\link[=s_count_cumulative]{s_count_cumulative()}}. } diff --git a/man/d_onco_rsp_label.Rd b/man/d_onco_rsp_label.Rd index 201b260cb6..7f5e45a98a 100644 --- a/man/d_onco_rsp_label.Rd +++ b/man/d_onco_rsp_label.Rd @@ -9,6 +9,9 @@ d_onco_rsp_label(x) \arguments{ \item{x}{(\code{character})\cr the standard oncology code to be described.} } +\value{ +Response labels. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/d_pkparam.Rd b/man/d_pkparam.Rd index 48b4322673..bb7abb9644 100644 --- a/man/d_pkparam.Rd +++ b/man/d_pkparam.Rd @@ -7,7 +7,7 @@ d_pkparam() } \value{ -dataframe of PK parameters +\code{data.frame} of PK parameters } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/d_proportion_diff.Rd b/man/d_proportion_diff.Rd index 4e797b512f..cb4df60268 100644 --- a/man/d_proportion_diff.Rd +++ b/man/d_proportion_diff.Rd @@ -14,7 +14,7 @@ d_proportion_diff(conf_level, method, long = FALSE) \item{long}{(\code{logical})\cr Whether a long or a short (default) description is required.} } \value{ -String describing the analysis. +A \code{string} describing the analysis. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/d_rsp_subgroups_colvars.Rd b/man/d_rsp_subgroups_colvars.Rd index aaec2739ac..18362e625d 100644 --- a/man/d_rsp_subgroups_colvars.Rd +++ b/man/d_rsp_subgroups_colvars.Rd @@ -15,7 +15,7 @@ d_rsp_subgroups_colvars(vars, conf_level = NULL, method = NULL) two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_proportion_diff()}}. Default is \code{NULL} so no test is performed.} } \value{ -\code{list} of variables to tabulate and their labels. +A \code{list} of variables to tabulate and their labels. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/d_survival_subgroups_colvars.Rd b/man/d_survival_subgroups_colvars.Rd index 991930c4e6..181d14e73f 100644 --- a/man/d_survival_subgroups_colvars.Rd +++ b/man/d_survival_subgroups_colvars.Rd @@ -7,32 +7,36 @@ d_survival_subgroups_colvars(vars, conf_level, method, time_unit = NULL) } \arguments{ -\item{vars}{(\code{character})\cr the name of statistics to be reported among -\code{n_tot_events} (total number of events per group), -\code{n_events} (number of events per group), -\code{n_tot} (total number of observations per group), -\code{n} (number of observations per group), -\code{median} (median survival time), -\code{hr} (hazard ratio), -\code{ci} (confidence interval of hazard ratio) and -\code{pval} (p value of the effect). +\item{vars}{(\code{character})\cr the name of statistics to be reported among: +\itemize{ +\item \code{n_tot_events}: Total number of events per group. +\item \code{n_events}: Number of events per group. +\item \code{n_tot}: Total number of observations per group. +\item \code{n}: Number of observations per group. +\item \code{median}: Median survival time. +\item \code{hr}: Hazard ratio. +\item \code{ci}: Confidence interval of hazard ratio. +\item \code{pval}: p-value of the effect. Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as both \code{hr} and \code{ci} -are required.} +are required. +}} \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} -\item{method}{p-value method for testing hazard ratio = 1.} +\item{method}{(\code{character})\cr p-value method for testing hazard ratio = 1.} \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} } \value{ -\code{list} of variables to tabulate and their labels. +A \code{list} of variables and their labels to tabulate. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Internal function to check variables included in -\code{\link[=tabulate_survival_subgroups]{tabulate_survival_subgroups()}} and create column labels. -Note that at least one of \code{n_tot} and \code{n_tot_events} needs to be provided in \code{vars}. +Internal function to check variables included in \code{\link[=tabulate_survival_subgroups]{tabulate_survival_subgroups()}} +and create column labels. +} +\note{ +At least one of \code{n_tot} and \code{n_tot_events} must be provided in \code{vars}. } diff --git a/man/decorate_grob.Rd b/man/decorate_grob.Rd index eeee8147be..7b9e2ec85d 100644 --- a/man/decorate_grob.Rd +++ b/man/decorate_grob.Rd @@ -60,7 +60,7 @@ not.} \item{vp}{a \code{\link[grid]{viewport}} object (or \code{NULL}).} } \value{ -a grid grob (\code{gTree}) +A grid grob (\code{gTree}). } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -71,12 +71,6 @@ with title, footnote, and page numbers. \details{ The titles and footnotes will be ragged, i.e. each title will be wrapped individually. - -\if{html}{ -The layout can be illustrated as follows: - -\figure{decorate_grob.png}{options: alt="decorate_grob layout"} -} } \examples{ library(grid) @@ -181,6 +175,3 @@ grid.draw( ) ) } -\author{ -Adrian Waddell (waddella) \email{adrian.waddell@roche.com} -} diff --git a/man/decorate_grob_factory.Rd b/man/decorate_grob_factory.Rd index 86edb2e5e5..63ea803b76 100644 --- a/man/decorate_grob_factory.Rd +++ b/man/decorate_grob_factory.Rd @@ -12,7 +12,7 @@ decorate_grob_factory(npages, ...) \item{...}{passed on to \code{\link{decorate_grob}}} } \value{ -closure that increments the page number +Closure that increments the page number. } \description{ Automatically updates page number. @@ -32,7 +32,4 @@ draw_grob(pf(NULL)) draw_grob(pf(NULL)) } } -\author{ -Adrian Waddell (waddella) \email{adrian.waddell@roche.com} -} \keyword{internal} diff --git a/man/decorate_grob_set.Rd b/man/decorate_grob_set.Rd index 954117cb03..217c122021 100644 --- a/man/decorate_grob_set.Rd +++ b/man/decorate_grob_set.Rd @@ -11,6 +11,9 @@ decorate_grob_set(grobs, ...) \item{...}{arguments passed on to \code{\link{decorate_grob}}} } +\value{ +A decorated grob. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -54,6 +57,3 @@ draw_grob(lg[[2]]) draw_grob(lg[[6]]) } -\author{ -Adrian Waddell (waddella) \email{adrian.waddell@roche.com} -} diff --git a/man/desctools_binom.Rd b/man/desctools_binom.Rd index 0f4a356b0e..fe3c0f97f2 100644 --- a/man/desctools_binom.Rd +++ b/man/desctools_binom.Rd @@ -2,12 +2,9 @@ % Please edit documentation in R/desctools_binom_diff.R \name{desctools_binom} \alias{desctools_binom} -\alias{h_recycle} \alias{desctools_binomci} \title{Confidence Intervals for a Difference of Binomials} \usage{ -h_recycle(...) - desctools_binom( x1, n1, @@ -49,18 +46,18 @@ desctools_binomci( (e.g. reference and treatment group).} } \value{ -A named list of 3 values: -\describe{ -\item{est}{estimate of proportion difference.} -\item{lwrci}{estimate of lower end of the confidence interval.} -\item{upci}{estimate of upper end of the confidence interval.} +A \code{matrix} of 3 values: +\itemize{ +\item \code{est}: estimate of proportion difference. +\item \code{lwr.ci}: estimate of lower end of the confidence interval. +\item \code{upr.ci}: estimate of upper end of the confidence interval. } -A matrix with 3 columns containing: -\describe{ -\item{est}{estimate of proportion difference.} -\item{lwrci}{lower end of the confidence interval.} -\item{upci}{upper end of the confidence interval.} +A \code{matrix} with 3 columns containing: +\itemize{ +\item \code{est}: estimate of proportion difference. +\item \code{lwr.ci}: lower end of the confidence interval. +\item \code{upr.ci}: upper end of the confidence interval. } } \description{ @@ -70,9 +67,7 @@ Several confidence intervals for the difference between proportions. } \section{Functions}{ \itemize{ -\item \code{h_recycle()}: This function recycles all supplied elements to the maximal dimension. - -\item \code{desctools_binom()}: Several Confidence Intervals for the difference between proportions. +\item \code{desctools_binom()}: Several confidence intervals for the difference between proportions. \item \code{desctools_binomci()}: Compute confidence intervals for binomial proportions. diff --git a/man/df_explicit_na.Rd b/man/df_explicit_na.Rd index d6f8d758f4..cc78acf2f1 100644 --- a/man/df_explicit_na.Rd +++ b/man/df_explicit_na.Rd @@ -28,7 +28,7 @@ in \code{data} to factors.} values inside non-\code{omit_columns} columns.} } \value{ -The data frame with the desired changes made. +A \code{data.frame} with the chosen modifications applied. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/draw_grob.Rd b/man/draw_grob.Rd index 7bb6bd9ab1..2d6033a9d2 100644 --- a/man/draw_grob.Rd +++ b/man/draw_grob.Rd @@ -13,6 +13,9 @@ draw_grob(grob, newpage = TRUE, vp = NULL) \item{vp}{a \code{\link{viewport}} object (or \code{NULL}).} } +\value{ +A \code{grob}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/empty_vector_if_na.Rd b/man/empty_vector_if_na.Rd index f4508c7122..aeb720308e 100644 --- a/man/empty_vector_if_na.Rd +++ b/man/empty_vector_if_na.Rd @@ -10,7 +10,7 @@ empty_vector_if_na(x) \item{x}{(\code{numeric})\cr vector.} } \value{ -An empty \code{numeric}. +An empty \code{numeric} if all elements of \code{x} are \code{NA}, otherwise \code{x}. } \description{ Return an empty numeric if all elements are \code{NA}. diff --git a/man/estimate_coef.Rd b/man/estimate_coef.Rd index d996261bc9..7d05662944 100644 --- a/man/estimate_coef.Rd +++ b/man/estimate_coef.Rd @@ -32,11 +32,11 @@ given the levels of \code{given}.} \value{ A list of matrix (one per level of variable) with rows corresponding to the combinations of \code{variable} and \code{given}, with columns: -\describe{ -\item{coef_hat}{Estimation of the coefficient.} -\item{coef_se}{Standard error of the estimation.} -\item{hr}{Hazard ratio.} -\item{lcl, ucl}{Lower/upper confidence limit of the hazard ratio.} +\itemize{ +\item \code{coef_hat}: Estimation of the coefficient. +\item \code{coef_se}: Standard error of the estimation. +\item \code{hr}: Hazard ratio. +\item \verb{lcl, ucl}: Lower/upper confidence limit of the hazard ratio. } } \description{ diff --git a/man/estimate_multinomial_rsp.Rd b/man/estimate_multinomial_rsp.Rd index 72aee3063b..9186f6234d 100644 --- a/man/estimate_multinomial_rsp.Rd +++ b/man/estimate_multinomial_rsp.Rd @@ -50,7 +50,19 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -See \code{\link[=s_proportion]{s_proportion()}} for statistics and additional possible arguments. +\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()}}. +} + +\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. +} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -60,16 +72,14 @@ regarding the level of a factor. } \section{Functions}{ \itemize{ -\item \code{s_length_proportion()}: Statistics function which takes the length of the input \code{x} and takes that -as the number of successes, and the column number \code{.N_col} as the total number, and feeds that into -\code{\link[=s_proportion]{s_proportion()}}. +\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 can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_length_proportion()}: Formatted analysis function which is used as \code{afun} +in \code{estimate_multinomial_response()}. -\item \code{estimate_multinomial_response()}: Analyze Function which adds the multinomial proportion analysis to -the input layout. Note that additional formatting arguments can be used -here. +\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()}}. }} \examples{ diff --git a/man/estimate_proportions.Rd b/man/estimate_proportions.Rd index 9e95891aa7..635ebd00b3 100644 --- a/man/estimate_proportions.Rd +++ b/man/estimate_proportions.Rd @@ -90,6 +90,22 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +\itemize{ +\item \code{s_proportion()} returns statistics \code{n_prop} (\code{n} and proportion) and \code{prop_ci} (proportion CI) for a +given variable. +} + +\itemize{ +\item \code{a_proportion()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{estimate_proportion()} 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_proportion()} 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]}} @@ -97,13 +113,14 @@ Estimate the proportion of responders within a studied population. } \section{Functions}{ \itemize{ -\item \code{s_proportion()}: statistics function estimating a +\item \code{s_proportion()}: Statistics function estimating a proportion along with its confidence interval. -\item \code{a_proportion()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_proportion()}: Formatted analysis function which is used as \code{afun} +in \code{estimate_proportion()}. -\item \code{estimate_proportion()}: used in a \code{rtables} pipeline. +\item \code{estimate_proportion()}: 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()}}. }} \examples{ diff --git a/man/explicit_na.Rd b/man/explicit_na.Rd index cb1fa541b4..cdd75f51b6 100644 --- a/man/explicit_na.Rd +++ b/man/explicit_na.Rd @@ -11,6 +11,9 @@ explicit_na(x, label = "") \item{label}{character string that missing data should be replaced with} } +\value{ +\code{x} with any \code{NA} values substituted by \code{label}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/extract_by_name.Rd b/man/extract_by_name.Rd index da2a4b50c6..25e0ad1199 100644 --- a/man/extract_by_name.Rd +++ b/man/extract_by_name.Rd @@ -12,7 +12,7 @@ extract_by_name(x, names) \item{names}{(\code{character})\cr vector of names to extract.} } \value{ -Either \code{NULL} or the extracted elements from \code{x}. +\code{NULL} if \code{x} is \code{NULL}, otherwise the extracted elements from \code{x}. } \description{ This utility function extracts elements from a vector \code{x} by \code{names}. diff --git a/man/extract_rsp_biomarkers.Rd b/man/extract_rsp_biomarkers.Rd index d34065a022..e05a6dd67a 100644 --- a/man/extract_rsp_biomarkers.Rd +++ b/man/extract_rsp_biomarkers.Rd @@ -26,6 +26,11 @@ confidence level produced by \code{\link[=control_logistic]{control_logistic()}} \item{label_all}{(\code{string})\cr label for the total population analysis.} } +\value{ +A \code{data.frame} with columns \code{biomarker}, \code{biomarker_label}, \code{n_tot}, \code{n_rsp}, +\code{prop}, \code{or}, \code{lcl}, \code{ucl}, \code{conf_level}, \code{pval}, \code{pval_label}, \code{subgroup}, \code{var}, +\code{var_label}, and \code{row_type}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/extract_rsp_subgroups.Rd b/man/extract_rsp_subgroups.Rd index c3a119dc8c..e3faedd4ce 100644 --- a/man/extract_rsp_subgroups.Rd +++ b/man/extract_rsp_subgroups.Rd @@ -29,6 +29,15 @@ two proportions. For options, see \code{\link[=s_test_proportion_diff]{s_test_pr \item{label_all}{(\code{string})\cr label for the total population analysis.} } +\value{ +A named list of two elements: +\itemize{ +\item \code{prop}: A \code{data.frame} containing columns \code{arm}, \code{n}, \code{n_rsp}, \code{prop}, \code{subgroup}, \code{var}, +\code{var_label}, and \code{row_type}. +\item \code{or}: A \code{data.frame} containing columns \code{arm}, \code{n_tot}, \code{or}, \code{lcl}, \code{ucl}, \code{conf_level}, +\code{subgroup}, \code{var}, \code{var_label}, and \code{row_type}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/extract_survival_biomarkers.Rd b/man/extract_survival_biomarkers.Rd index 35bad070b6..743ff93ece 100644 --- a/man/extract_survival_biomarkers.Rd +++ b/man/extract_survival_biomarkers.Rd @@ -26,14 +26,18 @@ helper function \code{\link[=control_coxreg]{control_coxreg()}}.} \item{label_all}{(\code{string})\cr label for the total population analysis.} } +\value{ +A \code{data.frame} with columns \code{biomarker}, \code{biomarker_label}, \code{n_tot}, \code{n_tot_events}, +\code{median}, \code{hr}, \code{lcl}, \code{ucl}, \code{conf_level}, \code{pval}, \code{pval_label}, \code{subgroup}, \code{var}, +\code{var_label}, and \code{row_type}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Prepares estimates for number of events, patients and median survival -times, as well as hazard ratio estimates, confidence intervals and p-values, for multiple biomarkers across -population subgroups in a single data frame. -\code{variables} corresponds to the names of variables found in \code{data}, passed as a named list and requires elements -\code{tte}, \code{is_event}, \code{biomarkers} (vector of continuous biomarker variables) and optionally \code{subgroups} and \code{strat}. +Prepares estimates for number of events, patients and median survival times, as well as hazard ratio estimates, +confidence intervals and p-values, for multiple biomarkers across population subgroups in a single data frame. +\code{variables} corresponds to the names of variables found in \code{data}, passed as a named \code{list} and requires elements +\code{tte}, \code{is_event}, \code{biomarkers} (vector of continuous biomarker variables), and optionally \code{subgroups} and \code{strat}. \code{groups_lists} optionally specifies groupings for \code{subgroups} variables. } \examples{ diff --git a/man/extract_survival_subgroups.Rd b/man/extract_survival_subgroups.Rd index b6a80c0e7c..37549a1a94 100644 --- a/man/extract_survival_subgroups.Rd +++ b/man/extract_survival_subgroups.Rd @@ -33,15 +33,23 @@ can also be set to "breslow" or "exact". See more in \code{\link[survival:coxph] \item{label_all}{(\code{string})\cr label for the total population analysis.} } +\value{ +A named \code{list} of two elements: +\itemize{ +\item \code{survtime}: A \code{data.frame} containing columns \code{arm}, \code{n}, \code{n_events}, \code{median}, \code{subgroup}, \code{var}, +\code{var_label}, and \code{row_type}. +\item \code{hr}: A \code{data.frame} containing columns \code{arm}, \code{n_tot}, \code{n_tot_events}, \code{hr}, \code{lcl}, \code{ucl}, \code{conf_level}, +\code{pval}, \code{pval_label}, \code{subgroup}, \code{var}, \code{var_label}, and \code{row_type}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} Prepares estimates of median survival times and treatment hazard ratios for population subgroups in -data frames. Simple wrapper for \code{\link[=h_survtime_subgroups_df]{h_survtime_subgroups_df()}} and \code{\link[=h_coxph_subgroups_df]{h_coxph_subgroups_df()}}. -Result is a list of two data frames: \code{survtime} and \code{hr}. -\code{variables} corresponds to the names of variables found in \code{data}, passed as a named list and requires elements -\code{tte}, \code{is_event}, \code{arm} and optionally \code{subgroups} and \code{strat}. \code{groups_lists} optionally specifies -groupings for \code{subgroups} variables. +data frames. Simple wrapper for \code{\link[=h_survtime_subgroups_df]{h_survtime_subgroups_df()}} and \code{\link[=h_coxph_subgroups_df]{h_coxph_subgroups_df()}}. Result is a \code{list} +of two \code{data.frame}s: \code{survtime} and \code{hr}. \code{variables} corresponds to the names of variables found in \code{data}, +passed as a named \code{list} and requires elements \code{tte}, \code{is_event}, \code{arm} and optionally \code{subgroups} and \code{strat}. +\code{groups_lists} optionally specifies groupings for \code{subgroups} variables. } \examples{ library(dplyr) diff --git a/man/extreme_format.Rd b/man/extreme_format.Rd index 373e5e60df..31fb097388 100644 --- a/man/extreme_format.Rd +++ b/man/extreme_format.Rd @@ -15,10 +15,21 @@ h_format_threshold(x, digits = 2L) \item{x}{(\code{number})\cr value to format.} } +\value{ +\itemize{ +\item \code{h_get_format_threshold()} returns a \code{list} of 2 elements: \code{threshold}, with \code{low} and \code{high} thresholds, +and \code{format_string}, with thresholds formatted as strings. +} + +\itemize{ +\item \code{h_format_threshold()} returns the given value, or if the value is not within the digit threshold the relation +of the given value to the digit threshold, as a formatted string. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -\code{Rtables} Formatting Functions that handle extreme values. +\code{rtables} formatting functions that handle extreme values. } \details{ For each input, apply a format to the specified number of \code{digits}. If the value is diff --git a/man/f_conf_level.Rd b/man/f_conf_level.Rd index 75c659be08..74838d2807 100644 --- a/man/f_conf_level.Rd +++ b/man/f_conf_level.Rd @@ -10,7 +10,7 @@ f_conf_level(conf_level) \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} } \value{ -a \code{string} +A \code{string}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/f_pval.Rd b/man/f_pval.Rd index 1c5f82bcb4..710129902c 100644 --- a/man/f_pval.Rd +++ b/man/f_pval.Rd @@ -10,7 +10,7 @@ f_pval(test_mean) \item{test_mean}{(\code{number})\cr mean value to test under the null hypothesis.} } \value{ -a \code{string} +A \code{string}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/fct_collapse_only.Rd b/man/fct_collapse_only.Rd index 0be786c2fb..174e4b70d3 100644 --- a/man/fct_collapse_only.Rd +++ b/man/fct_collapse_only.Rd @@ -16,14 +16,19 @@ the new level given by the respective name.} new factor. Note that this level must not be contained in the new levels specified in \code{...}.} } \value{ -The modified factor with collapsed levels. Values and levels which are not included -in the given character vectors input will be set to the missing level. +A modified \code{factor} with collapsed levels. Values and levels which are not included +in the given \code{character} vector input will be set to the missing level \code{.na_level}. } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + This collapses levels and only keeps those new group levels, in the order provided. The returned factor has levels in the order given, with the possible missing level last (this will -only be included if there are missings). Note that any existing \code{NA} in the input vector will -not be replaced by the missing level. If needed \code{\link[=explicit_na]{explicit_na()}} can be called separately on the result. +only be included if there are missing values). +} +\note{ +Any existing \code{NA}s in the input vector will not be replaced by the missing level. If needed, +\code{\link[=explicit_na]{explicit_na()}} can be called separately on the result. } \examples{ fct_collapse_only(factor(c("a", "b", "c", "d")), TRT = "b", CTRL = c("c", "d")) diff --git a/man/fct_discard.Rd b/man/fct_discard.Rd index 3510a9e512..111923e926 100644 --- a/man/fct_discard.Rd +++ b/man/fct_discard.Rd @@ -12,9 +12,11 @@ fct_discard(x, discard) \item{discard}{(\code{character})\cr which levels to discard.} } \value{ -The modified factor with observations as well as levels from \code{discard} dropped. +A modified \code{factor} with observations as well as levels from \code{discard} dropped. } \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + This discards the observations as well as the levels specified from a factor. } \examples{ diff --git a/man/fct_explicit_na_if.Rd b/man/fct_explicit_na_if.Rd index e2da7a0ec3..f58e2c7c32 100644 --- a/man/fct_explicit_na_if.Rd +++ b/man/fct_explicit_na_if.Rd @@ -14,10 +14,12 @@ fct_explicit_na_if(x, condition, na_level = "") \item{na_level}{(\code{string})\cr which level to use for missings.} } \value{ -The modified factor with inserted and existing \code{NA} converted to \code{na_level}. +A modified \code{factor} with inserted and existing \code{NA} converted to \code{na_level}. } \description{ -This inserts explicit missings in a factor based on a condition. Note that also additional +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + +This inserts explicit missings in a factor based on a condition. Additionally, existing \code{NA} values will be explicitly converted to given \code{na_level}. } \examples{ diff --git a/man/fit_coxreg.Rd b/man/fit_coxreg.Rd index 5ca864035b..fc11ff43df 100644 --- a/man/fit_coxreg.Rd +++ b/man/fit_coxreg.Rd @@ -28,23 +28,27 @@ effect should be estimated.} helper function \code{\link[=control_coxreg]{control_coxreg()}}.} } \value{ -The function \code{fit_coxreg_univar} returns a \code{coxreg.univar} class object which is a named list +\itemize{ +\item \code{fit_coxreg_univar()} returns a \code{coxreg.univar} class object which is a named \code{list} with 5 elements: -\describe{ -\item{mod}{Cox regression models fitted by \code{\link[survival:coxph]{survival::coxph()}}.} -\item{data}{The original data frame input.} -\item{control}{The original control input.} -\item{vars}{The variables used in the model.} -\item{at}{Value of the covariate at which the effect should be estimated.} +\itemize{ +\item \code{mod}: Cox regression models fitted by \code{\link[survival:coxph]{survival::coxph()}}. +\item \code{data}: The original data frame input. +\item \code{control}: The original control input. +\item \code{vars}: The variables used in the model. +\item \code{at}: Value of the covariate at which the effect should be estimated. +} } -The function \code{fit_coxreg_multivar} returns a \code{coxreg.multivar} class object which is a named list +\itemize{ +\item \code{fit_coxreg_multivar()} returns a \code{coxreg.multivar} class object which is a named list with 4 elements: -\describe{ -\item{mod}{Cox regression model fitted by \code{\link[survival:coxph]{survival::coxph()}}.} -\item{data}{The original data frame input.} -\item{control}{The original control input.} -\item{vars}{The variables used in the model.} +\itemize{ +\item \code{mod}: Cox regression model fitted by \code{\link[survival:coxph]{survival::coxph()}}. +\item \code{data}: The original data frame input. +\item \code{control}: The original control input. +\item \code{vars}: The variables used in the model. +} } } \description{ @@ -57,7 +61,7 @@ Fitting functions for univariate and multivariate Cox regression models. \item \code{fit_coxreg_univar()}: Fit a series of univariate Cox regression models given the inputs. -\item \code{fit_coxreg_multivar()}: Fit a multi-variable Cox regression model. +\item \code{fit_coxreg_multivar()}: Fit a multivariate Cox regression model. }} \note{ diff --git a/man/fit_logistic.Rd b/man/fit_logistic.Rd index dd6846b296..14a7ae2389 100644 --- a/man/fit_logistic.Rd +++ b/man/fit_logistic.Rd @@ -20,6 +20,9 @@ fit_logistic( This will be used when fitting the (conditional) logistic regression model on the left hand side of the formula.} } +\value{ +A fitted logistic regression model. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -29,15 +32,14 @@ Fit a (conditional) logistic regression model. The \code{variables} list needs to include the following elements: -\describe{ -\item{arm}{treatment arm variable name.} -\item{response}{the response arm variable name. Usually this is a 0/1 variable.} -\item{covariates}{this is either \code{NULL} (no covariates) or a character vector of covariate variable names.} -\item{interaction}{this is either \code{NULL} (no interaction) or a string of a single covariate variable name already +\itemize{ +\item \code{arm}: Treatment arm variable name. +\item \code{response}: The response arm variable name. Usually this is a 0/1 variable. +\item \code{covariates}: This is either \code{NULL} (no covariates) or a character vector of covariate variable names. +\item \code{interaction}: This is either \code{NULL} (no interaction) or a string of a single covariate variable name already included in \code{covariates}. Then the interaction with the treatment arm is included in the model. } } -} \examples{ library(dplyr) diff --git a/man/fit_rsp_step.Rd b/man/fit_rsp_step.Rd index 72f7ff7e4a..a2eba8608a 100644 --- a/man/fit_rsp_step.Rd +++ b/man/fit_rsp_step.Rd @@ -8,8 +8,7 @@ fit_rsp_step(variables, data, control = c(control_step(), control_logistic())) } \arguments{ \item{variables}{(named \code{list} of \code{character})\cr list of analysis variables: -needs \code{response}, \code{arm}, \code{biomarker}, and optional \code{covariates} and -\code{strata}.} +needs \code{response}, \code{arm}, \code{biomarker}, and optional \code{covariates} and \code{strata}.} \item{data}{(\code{data.frame})\cr the dataset containing the variables to summarize.} @@ -17,7 +16,7 @@ needs \code{response}, \code{arm}, \code{biomarker}, and optional \code{covariat and \code{\link[=control_logistic]{control_logistic()}}.} } \value{ -a matrix of class \code{step}. The first part of the columns describe the +A matrix of class \code{step}. The first part of the columns describe the subgroup intervals used for the biomarker variable, including where the center of the intervals are and their bounds. The second part of the columns contain the estimates for the treatment arm comparison. @@ -35,7 +34,9 @@ The (conditional) logistic regression model which is fit is: \code{response ~ arm * poly(biomarker, degree) + covariates + strata(strata)} where \code{degree} is specified by \code{control_step()}. -Note that for the default degree 0 the \code{biomarker} variable is not included in the model. +} +\note{ +For the default degree 0 the \code{biomarker} variable is not included in the model. } \examples{ # Testing dataset with just two treatment arms. diff --git a/man/fit_survival_step.Rd b/man/fit_survival_step.Rd index fc19902b90..ee5155c587 100644 --- a/man/fit_survival_step.Rd +++ b/man/fit_survival_step.Rd @@ -19,7 +19,7 @@ fit_survival_step( \item{control}{(named \code{list})\cr combined control list from \code{\link[=control_step]{control_step()}} and \code{\link[=control_coxph]{control_coxph()}}.} } \value{ -a matrix of class \code{step}. The first part of the columns describe the subgroup intervals used +A matrix of class \code{step}. The first part of the columns describe the subgroup intervals used for the biomarker variable, including where the center of the intervals are and their bounds. The second part of the columns contain the estimates for the treatment arm comparison. } @@ -35,7 +35,9 @@ The model which is fit is: \code{Surv(time, event) ~ arm * poly(biomarker, degree) + covariates + strata(strata)} where \code{degree} is specified by \code{control_step()}. -Note that for the default degree 0 the \code{biomarker} variable is not included in the model. +} +\note{ +For the default degree 0 the \code{biomarker} variable is not included in the model. } \examples{ # Testing dataset with just two treatment arms. diff --git a/man/forest_viewport.Rd b/man/forest_viewport.Rd index 8083cd6c9e..205bd0d368 100644 --- a/man/forest_viewport.Rd +++ b/man/forest_viewport.Rd @@ -14,6 +14,9 @@ forest_viewport( mat_form = NULL ) } +\value{ +A viewport tree. +} \description{ Create a Viewport Tree for the Forest Plot } diff --git a/man/format_count_fraction.Rd b/man/format_count_fraction.Rd index 86225a8d7f..8e6c8ec7d0 100644 --- a/man/format_count_fraction.Rd +++ b/man/format_count_fraction.Rd @@ -12,7 +12,7 @@ format_count_fraction(x, ...) \item{...}{required for \code{rtables} interface.} } \value{ -a string in the format \verb{count (fraction \%)}. If \code{count} is 0 the format is \code{0}. +A string in the format \verb{count (fraction \%)}. If \code{count} is 0, the format is \code{0}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/format_count_fraction_fixed_dp.Rd b/man/format_count_fraction_fixed_dp.Rd index 34bee70953..b7fcca7a78 100644 --- a/man/format_count_fraction_fixed_dp.Rd +++ b/man/format_count_fraction_fixed_dp.Rd @@ -12,7 +12,7 @@ format_count_fraction_fixed_dp(x, ...) \item{...}{required for \code{rtables} interface.} } \value{ -a string in the format \verb{count (fraction \%)}. If \code{count} is 0 the format is \code{0}. +A string in the format \verb{count (fraction \%)}. If \code{count} is 0, the format is \code{0}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} diff --git a/man/format_extreme_values.Rd b/man/format_extreme_values.Rd index e1ae7fa037..f9c10b440a 100644 --- a/man/format_extreme_values.Rd +++ b/man/format_extreme_values.Rd @@ -9,6 +9,9 @@ format_extreme_values(digits = 2L) \arguments{ \item{digits}{(\code{integer})\cr number of decimal places to display.} } +\value{ +An \code{rtables} formatting function that uses threshold \code{digits} to return a formatted extreme value. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/format_extreme_values_ci.Rd b/man/format_extreme_values_ci.Rd index 34065ffe0d..4844a725a9 100644 --- a/man/format_extreme_values_ci.Rd +++ b/man/format_extreme_values_ci.Rd @@ -9,11 +9,15 @@ format_extreme_values_ci(digits = 2L) \arguments{ \item{digits}{(\code{integer})\cr number of decimal places to display.} } +\value{ +An \code{rtables} formatting function that uses threshold \code{digits} to return a formatted extreme +values confidence interval. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} Formatting Function for extreme values part of a confidence interval. Values -are formatted as e.g. "(xx.xx, xx.xx)" if if the number of \code{digits} is 2. +are formatted as e.g. "(xx.xx, xx.xx)" if the number of \code{digits} is 2. } \examples{ format_fun <- format_extreme_values_ci(2L) diff --git a/man/format_fraction.Rd b/man/format_fraction.Rd index 1dfb998609..907db0a742 100644 --- a/man/format_fraction.Rd +++ b/man/format_fraction.Rd @@ -12,7 +12,7 @@ format_fraction(x, ...) \item{...}{required for \code{rtables} interface.} } \value{ -a string in the format \verb{num / denom (ratio \%)}. If \code{num} is 0 the format is \code{num / denom}. +A string in the format \verb{num / denom (ratio \%)}. If \code{num} is 0, the format is \code{num / denom}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/format_fraction_fixed_dp.Rd b/man/format_fraction_fixed_dp.Rd index 2e1c6bf2d1..515a3c5595 100644 --- a/man/format_fraction_fixed_dp.Rd +++ b/man/format_fraction_fixed_dp.Rd @@ -12,7 +12,7 @@ format_fraction_fixed_dp(x, ...) \item{...}{required for \code{rtables} interface.} } \value{ -a string in the format \verb{num / denom (ratio \%)}. If \code{num} is 0 the format is \code{num / denom}. +A string in the format \verb{num / denom (ratio \%)}. If \code{num} is 0, the format is \code{num / denom}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/format_fraction_threshold.Rd b/man/format_fraction_threshold.Rd index 0a10f0b167..67afc66ad6 100644 --- a/man/format_fraction_threshold.Rd +++ b/man/format_fraction_threshold.Rd @@ -10,10 +10,10 @@ format_fraction_threshold(threshold) \item{threshold}{(\code{proportion})\cr lower threshold.} } \value{ -An \code{rtables} Formatting Function that takes numeric input \code{x} where the second +An \code{rtables} formatting function that takes numeric input \code{x} where the second element is the fraction that is formatted. If the fraction is above or equal to the threshold, -then it is displayed in percentage. If it is positive but below the threshold, it returns -"<1" e.g. if the threshold is \code{0.01}. If it is zero, then just "0" is returned. +then it is displayed in percentage. If it is positive but below the threshold, it returns, +e.g. "<1" if the threshold is \code{0.01}. If it is zero, then just "0" is returned. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/g_forest.Rd b/man/g_forest.Rd index fe26f09498..6cc9b26230 100644 --- a/man/g_forest.Rd +++ b/man/g_forest.Rd @@ -65,7 +65,7 @@ By default tries to get this from \code{tbl} attribute \code{col_symbol_size}, o Only considered if \code{draw = TRUE} is used.} } \value{ -\code{gtree} object containing the forest plot and table +\code{gTree} object containing the forest plot and table. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/g_km.Rd b/man/g_km.Rd index 4a04064edf..a881648284 100644 --- a/man/g_km.Rd +++ b/man/g_km.Rd @@ -140,7 +140,7 @@ can also be set to "breslow" or "exact". See more in \code{\link[survival:coxph] time per group.} } \value{ -a \code{grob} of class \code{gTree}. +A \code{grob} of class \code{gTree}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/g_lineplot.Rd b/man/g_lineplot.Rd index ae5a9dbc8a..f3b2bd6688 100644 --- a/man/g_lineplot.Rd +++ b/man/g_lineplot.Rd @@ -121,7 +121,7 @@ appended to the plot. Names of \code{table_labels} must match the names of stati \item{col}{(\code{character})\cr colors.} } \value{ -\code{ggplot} +A \code{ggplot} line plot (and statistics table if applicable). } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -182,6 +182,3 @@ g_lineplot( adlb_f <- dplyr::filter(adlb, ARMCD != "ARM A" | AVISIT == "BASELINE") g_lineplot(adlb_f, table = c("n", "mean")) } -\author{ -Wojciech Wojciak wojciech.wojciak@contractors.roche.com -} diff --git a/man/g_step.Rd b/man/g_step.Rd index cb2b794255..4f42313a8b 100644 --- a/man/g_step.Rd +++ b/man/g_step.Rd @@ -26,7 +26,7 @@ ribbon area, or \code{NULL} to not plot a CI ribbon.} \item{col}{(\code{character})\cr colors.} } \value{ -The \code{ggplot2} object. +A \code{ggplot} STEP graph. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/g_waterfall.Rd b/man/g_waterfall.Rd index 4dc100f8a3..f7cd836961 100644 --- a/man/g_waterfall.Rd +++ b/man/g_waterfall.Rd @@ -33,7 +33,7 @@ g_waterfall( \item{title}{(\code{character})\cr text to be displayed as plot title.} } \value{ -(\code{ggplot} object)\cr waterfall plot. +A \code{ggplot} waterfall plot. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -85,6 +85,3 @@ g_waterfall( title = "Waterfall plot" ) } -\author{ -Yuyao Song (songy) \email{yuyao.song@roche.com} -} diff --git a/man/get_covariates.Rd b/man/get_covariates.Rd index b4871c61b2..724acad862 100644 --- a/man/get_covariates.Rd +++ b/man/get_covariates.Rd @@ -11,7 +11,7 @@ get_covariates(covariates) \code{"X1"}), and/or interaction terms indicated by \code{"X1 * X2"}.} } \value{ -a named \code{list} of character vector. +A named \code{list} of \code{character} vector. } \description{ Utility function to return a named list of covariate names. diff --git a/man/get_smooths.Rd b/man/get_smooths.Rd index 1a18ea06c3..3690283722 100644 --- a/man/get_smooths.Rd +++ b/man/get_smooths.Rd @@ -18,8 +18,8 @@ get_smooths(df, x, y, groups = NULL, level = 0.95) \item{level}{(\code{numeric})\cr level of confidence interval to use (0.95 by default).} } \value{ -A \code{data.frame} with original \code{x}, smoothed \code{y}, \code{ylow}, \code{yhigh} and -optional \code{groups} variables formatted to factor type. +A \code{data.frame} with original \code{x}, smoothed \code{y}, \code{ylow}, and \code{yhigh}, and +optional \code{groups} variables formatted as \code{factor} type. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_adlb_worsen.Rd b/man/h_adlb_worsen.Rd index 332ceae6e5..197aa04736 100644 --- a/man/h_adlb_worsen.Rd +++ b/man/h_adlb_worsen.Rd @@ -27,7 +27,7 @@ Only lab records flagged by \code{L}, \code{H} or \code{B} are included in the s }} } \value{ -\code{\link[=h_adlb_worsen]{h_adlb_worsen()}} returns the \code{adlb} \code{data.frame} containing only the +\code{h_adlb_worsen()} returns the \code{adlb} \code{data.frame} containing only the worst labs specified according to \code{worst_flag_low} or \code{worst_flag_high} for the direction specified according to \code{direction_var}. For instance, for a lab that is needed for the low direction only, only records flagged by \code{worst_flag_low} are diff --git a/man/h_adsl_adlb_merge_using_worst_flag.Rd b/man/h_adsl_adlb_merge_using_worst_flag.Rd index 9772f4c33d..5272d672ec 100644 --- a/man/h_adsl_adlb_merge_using_worst_flag.Rd +++ b/man/h_adsl_adlb_merge_using_worst_flag.Rd @@ -27,9 +27,9 @@ If worst grade per patient per visit is specified for \code{worst_flag}, then grade. Defaults to \code{c("SCREENING", "BASELINE")}.} } \value{ -\code{df} containing variables shared between \code{adlb} and \code{adsl} along with variables relevant for analysis: -\code{PARAM}, \code{PARAMCD}, \code{ATOXGR}, and \code{BTOXGR}. Optionally \code{AVISIT}, \code{AVISITN} are included when \code{by_visit = TRUE} -and \code{no_fillin_visits = c("SCREENING", "BASELINE")}. +\code{df} containing variables shared between \code{adlb} and \code{adsl} along with variables \code{PARAM}, \code{PARAMCD}, +\code{ATOXGR}, and \code{BTOXGR} relevant for analysis. Optionally, \code{AVISIT} are \code{AVISITN} are included when +\code{by_visit = TRUE} and \code{no_fillin_visits = c("SCREENING", "BASELINE")}. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_ancova.Rd b/man/h_ancova.Rd index d41891fda8..c459ded01d 100644 --- a/man/h_ancova.Rd +++ b/man/h_ancova.Rd @@ -26,6 +26,9 @@ reference group. \item{interaction_item}{(\code{character})\cr name of the variable that should have interactions with arm. if the interaction is not needed, the default option is NULL.} } +\value{ +The summary of a linear model. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} } diff --git a/man/h_append_grade_groups.Rd b/man/h_append_grade_groups.Rd index 705f3cc279..4b65c756c0 100644 --- a/man/h_append_grade_groups.Rd +++ b/man/h_append_grade_groups.Rd @@ -15,6 +15,9 @@ and each entry represents a count.} \item{remove_single}{(\code{logical})\cr \code{TRUE} to not include the elements of one-element grade groups in the the output list; in this case only the grade groups names will be included in the output.} } +\value{ +Formatted list of grade groupings. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_col_indices.Rd b/man/h_col_indices.Rd index 400329d399..5ac4368b66 100644 --- a/man/h_col_indices.Rd +++ b/man/h_col_indices.Rd @@ -12,7 +12,7 @@ h_col_indices(table_tree, col_names) \item{col_names}{(\code{character})\cr vector of column names.} } \value{ -the vector of column indices. +A vector of column indices. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_count_cumulative.Rd b/man/h_count_cumulative.Rd index 85c1918d99..8f45daea3d 100644 --- a/man/h_count_cumulative.Rd +++ b/man/h_count_cumulative.Rd @@ -29,11 +29,10 @@ count, default is \code{TRUE}.} } \value{ A named vector with items: -\describe{ -\item{count}{the count of values less than, less or equal to, greater than, or greater or equal to a threshold +\itemize{ +\item \code{count}: the count of values less than, less or equal to, greater than, or greater or equal to a threshold of user specification. -} -\item{fraction}{the fraction of the count.} +\item \code{fraction}: the fraction of the count. } } \description{ diff --git a/man/h_cox_regression.Rd b/man/h_cox_regression.Rd index 076358c792..0587eb5103 100644 --- a/man/h_cox_regression.Rd +++ b/man/h_cox_regression.Rd @@ -32,18 +32,29 @@ interaction can be used so that this needs to be \code{FALSE}.} \item{mod}{(\code{coxph})\cr Cox regression model fitted by \code{\link[survival:coxph]{survival::coxph()}}.} -\item{control}{(\code{list})\cr a list of controls as returned by -\code{\link[=control_coxreg]{control_coxreg()}}.} +\item{control}{(\code{list})\cr a list of controls as returned by \code{\link[=control_coxreg]{control_coxreg()}}.} \item{var}{(\code{string})\cr single variable name that is passed by \code{rtables} when requested by a statistics function.} } \value{ -The function \code{h_coxreg_univar_formulas} returns a \code{character} vector coercible -into formulas (e.g \code{\link[stats:formula]{stats::as.formula()}}). +\itemize{ +\item \code{h_coxreg_univar_formulas()} returns a \code{character} vector coercible into formulas (e.g \code{\link[stats:formula]{stats::as.formula()}}). +} -The function \code{h_coxreg_univar_formulas} returns a \code{character} vector coercible -into formulas (e.g \code{\link[stats:formula]{stats::as.formula()}}). +\itemize{ +\item \code{h_coxreg_multivar_formula()} returns a \code{string} coercible into a formula (e.g \code{\link[stats:formula]{stats::as.formula()}}). +} + +\itemize{ +\item \code{h_coxreg_univar_extract()} returns a \code{data.frame} with variables \code{effect}, \code{term}, \code{term_label}, \code{level}, +\code{n}, \code{hr}, \code{lcl}, \code{ucl}, and \code{pval}. +} + +\itemize{ +\item \code{h_coxreg_multivar_extract()} returns a \code{data.frame} with variables \code{pval}, \code{hr}, \code{lcl}, \code{ucl}, \code{level}, +\code{n}, \code{term}, and \code{term_label}. +} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -52,24 +63,18 @@ Helper functions used in \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} a } \section{Functions}{ \itemize{ -\item \code{h_coxreg_univar_formulas()}: Helper for Cox Regression Formula +\item \code{h_coxreg_univar_formulas()}: Helper for Cox regression formula. Creates a list of formulas. It is used +internally by \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} for the comparison of univariate Cox regression models. -Creates a list of formulas. It is used internally by \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} -for the comparison of univariate Cox regression models. - -\item \code{h_coxreg_multivar_formula()}: Helper for Multi-variable Cox Regression Formula - -Creates a formulas string. It is used internally by \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} -for the comparison of multi-variable Cox regression models. Interactions will not -be included in multi-variable Cox regression model. +\item \code{h_coxreg_multivar_formula()}: Helper for multivariate Cox regression formula. Creates a formulas +string. It is used internally by \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} for the comparison of multivariate Cox +regression models. Interactions will not be included in multivariate Cox regression model. \item \code{h_coxreg_univar_extract()}: Utility function to help tabulate the result of a univariate Cox regression model. -\item \code{h_coxreg_multivar_extract()}: Tabulation of Multi-variable Cox Regressions - -Utility function to help tabulate the result of a multi-variable Cox regression model -for a treatment/covariate variable. +\item \code{h_coxreg_multivar_extract()}: Tabulation of multivariate Cox regressions. Utility function to help +tabulate the result of a multivariate Cox regression model for a treatment/covariate variable. }} \examples{ diff --git a/man/h_data_plot.Rd b/man/h_data_plot.Rd index af90db5da2..d6acef6ea6 100644 --- a/man/h_data_plot.Rd +++ b/man/h_data_plot.Rd @@ -15,14 +15,16 @@ variable only has one level. Default is "All".} \item{max_time}{(\code{numeric})\cr maximum value to show on X axis. Only data values less than or up to this threshold value will be plotted (defaults to \code{NULL}).} } +\value{ +A \code{tibble} with columns \code{time}, \code{n.risk}, \code{n.event}, \code{n.censor}, +\code{estimate}, \code{std.error}, \code{conf.high}, \code{conf.low}, \code{strata}, and \code{censor}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} Convert the survival fit data into a data frame designed for plotting within \code{g_km}. -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} - This starts from the \code{\link[broom:reexports]{broom::tidy()}} result, and then: \itemize{ \item post-processes the \code{strata} column into a factor, diff --git a/man/h_decompose_gg.Rd b/man/h_decompose_gg.Rd index 056545144b..5224299354 100644 --- a/man/h_decompose_gg.Rd +++ b/man/h_decompose_gg.Rd @@ -9,15 +9,21 @@ h_decompose_gg(gg) \arguments{ \item{gg}{(\code{ggplot})\cr a graphic to decompose.} } +\value{ +A named \code{list} with elements: +\itemize{ +\item \code{panel}: The panel. +\item \code{yaxis}: The y-axis. +\item \code{xaxis}: The x-axis. +\item \code{xlab}: The x-axis label. +\item \code{ylab}: The y-axis label. +\item \code{guide}: The legend. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -The elements composing the \code{ggplot} are extracted and organized in a -list containing: -the panel (\code{panel}), -the y-axis and its label (\code{yaxis}, \code{ylab}), -idem for the x-axis (\code{xaxis}, \code{xlab}), -the legend (\code{guide}). +The elements composing the \code{ggplot} are extracted and organized in a \code{list}. } \examples{ \dontrun{ diff --git a/man/h_format_row.Rd b/man/h_format_row.Rd index 34ae657170..89cee85d49 100644 --- a/man/h_format_row.Rd +++ b/man/h_format_row.Rd @@ -24,7 +24,7 @@ If none of these attributes are attached to a given element of \code{x}, then the label is automatically generated.} } \value{ -1-row \code{data.frame} object +A single row \code{data.frame} object. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -42,6 +42,3 @@ x <- list(mean = 50, mean_ci = mean_ci) h_format_row(x, format, labels) } -\author{ -Wojciech Wojciak wojciech.wojciak@contractors.roche.com -} diff --git a/man/h_g_ipp.Rd b/man/h_g_ipp.Rd index d1ba71f0f9..ccf65ed39d 100644 --- a/man/h_g_ipp.Rd +++ b/man/h_g_ipp.Rd @@ -50,6 +50,9 @@ by \code{ggplot2} to control outlook of plot. Use \code{ggplot2::theme()} to twe \item{col}{(\code{character})\cr lines colors.} } +\value{ +A \code{ggplot} line plot. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_ggkm.Rd b/man/h_ggkm.Rd index e4e2d46311..5faaa4758c 100644 --- a/man/h_ggkm.Rd +++ b/man/h_ggkm.Rd @@ -62,6 +62,9 @@ to number of strata from \code{\link[survival:survfit]{survival::survfit()}}.} \item{ggtheme}{(\code{theme})\cr a graphical theme as provided by \code{ggplot2} to control outlook of the Kaplan-Meier curve.} } +\value{ +A \code{ggplot} object. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_glm_count.Rd b/man/h_glm_count.Rd index 8342093191..a5dfbc5589 100644 --- a/man/h_glm_count.Rd +++ b/man/h_glm_count.Rd @@ -46,6 +46,23 @@ used in the regression (poisson, quasipoisson).} groups will be summarized. Specifically, the first level of \code{arm} variable is taken as the reference group.} } +\value{ +\itemize{ +\item \code{h_glm_poisson()} returns the results of a Poisson model. +} + +\itemize{ +\item \code{h_glm_quasipoisson()} returns the results of a Quasi-Poisson model. +} + +\itemize{ +\item \code{h_glm_count()} returns the results of the selected model. +} + +\itemize{ +\item \code{h_ppmeans()} returns the estimated means. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} @@ -78,7 +95,7 @@ h_glm_poisson( \dontrun{ h_glm_quasipoisson( .var = "AVAL", - .df_row = anl, + .df_row = adtte, variables = list(arm = "ARM", offset = "lgTMATRSK", covariates = c("REGION1")) ) } diff --git a/man/h_grob_coxph.Rd b/man/h_grob_coxph.Rd index 35eda5f874..2602f947f4 100644 --- a/man/h_grob_coxph.Rd +++ b/man/h_grob_coxph.Rd @@ -21,6 +21,10 @@ h_grob_coxph( \item{ttheme}{(\code{list})\cr see \code{\link[gridExtra:tableGrob]{gridExtra::ttheme_default()}}.} } +\value{ +A \code{grob} of a table containing statistics \code{HR}, \verb{XX\% CI} (\code{XX} taken from \code{control_coxph_pw}), +and \code{p-value (log-rank)}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_grob_median_surv.Rd b/man/h_grob_median_surv.Rd index 8497535c38..ac50bb821a 100644 --- a/man/h_grob_median_surv.Rd +++ b/man/h_grob_median_surv.Rd @@ -24,6 +24,9 @@ variable only has one level. Default is "All".} \item{ttheme}{(\code{list})\cr see \code{\link[gridExtra:tableGrob]{gridExtra::ttheme_default()}}.} } +\value{ +A \code{grob} of a table containing statistics \code{N}, \code{Median}, and \verb{XX\% CI} (\code{XX} taken from \code{fit_km}). +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_grob_tbl_at_risk.Rd b/man/h_grob_tbl_at_risk.Rd index f2c16a2a2f..a5627256f4 100644 --- a/man/h_grob_tbl_at_risk.Rd +++ b/man/h_grob_tbl_at_risk.Rd @@ -16,6 +16,9 @@ patients at risk at given time points.} \item{xlim}{(\code{numeric})\cr the maximum value on the x-axis (used to ensure the at risk table aligns with the KM graph).} } +\value{ +A named \code{list} of two \code{gTree} objects: \code{at_risk} and \code{label}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_grob_y_annot.Rd b/man/h_grob_y_annot.Rd index 4def4a2a99..ec14ee9f66 100644 --- a/man/h_grob_y_annot.Rd +++ b/man/h_grob_y_annot.Rd @@ -13,6 +13,9 @@ a \code{ggplot}.} \item{yaxis}{(\code{gtable})\cr the y-axis as a graphical object derived from a \code{ggplot}.} } +\value{ +a \code{gTree} object containing the y-axis annotation from a \code{ggplot}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_incidence_rate.Rd b/man/h_incidence_rate.Rd index 1937c1b761..45454534cc 100644 --- a/man/h_incidence_rate.Rd +++ b/man/h_incidence_rate.Rd @@ -36,6 +36,9 @@ indicating time unit for data input. \item \code{time_unit_output}: (\code{numeric})\cr time unit for desired output (in person-years). }} } +\value{ +Estimated incidence rate \code{rate} and associated confidence interval \code{rate_ci}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} } diff --git a/man/h_km_layout.Rd b/man/h_km_layout.Rd index f7266a65f7..8a3de9da67 100644 --- a/man/h_km_layout.Rd +++ b/man/h_km_layout.Rd @@ -19,6 +19,9 @@ h_km_layout(data, g_el, title, footnotes, annot_at_risk = TRUE) reporting the number of patient at risk matching the main grid of the Kaplan-Meier curve.} } +\value{ +A grid layout. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_logistic_regression.Rd b/man/h_logistic_regression.Rd index 52a97221b1..4c4c10996b 100644 --- a/man/h_logistic_regression.Rd +++ b/man/h_logistic_regression.Rd @@ -14,7 +14,7 @@ \alias{h_glm_inter_term_extract} \alias{h_logistic_simple_terms} \alias{h_logistic_inter_terms} -\title{Helper Functions for Multi-Variable Logistic Regression} +\title{Helper Functions for Multivariate Logistic Regression} \usage{ h_get_interaction_vars(fit_glm) @@ -99,6 +99,31 @@ helper function).} \item{...}{additional arguments for the lower level functions.} } +\value{ +Vector of names of interaction variables. + +Name of coefficient. + +Odds ratio. + +Odds ratio. + +Odds ratio. + +Term labels containing numbers of patients. + +Term labels containing numbers of patients. + +Tabulated main effect results from a logistic regression model. + +Tabulated interaction term results from a logistic regression model. + +A \code{data.frame} of tabulated interaction term results from a logistic regression model. + +Tabulated statistics for the given variable(s) from the logistic regression model. + +Tabulated statistics for the given variable(s) from the logistic regression model. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -182,6 +207,7 @@ mod2 <- fit_logistic( interaction = "AGE" ) ) + h_glm_simple_term_extract("AGE", mod1) h_glm_simple_term_extract("ARMCD", mod1) diff --git a/man/h_map_for_count_abnormal.Rd b/man/h_map_for_count_abnormal.Rd index 46b53925ba..b99a1032e4 100644 --- a/man/h_map_for_count_abnormal.Rd +++ b/man/h_map_for_count_abnormal.Rd @@ -31,6 +31,9 @@ for low direction and at least one observation with high range is not missing fo \item{na_level}{(\code{string})\cr used to replace all \code{NA} or empty values in factors with custom \code{string}.} } +\value{ +A map \code{data.frame}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_odds_ratio.Rd b/man/h_odds_ratio.Rd index 29971da35a..59d3d6bdd7 100644 --- a/man/h_odds_ratio.Rd +++ b/man/h_odds_ratio.Rd @@ -16,6 +16,9 @@ or_clogit(data, conf_level) \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} } +\value{ +A named \code{list} of elements \code{or_ci} and \code{n_tot}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -23,7 +26,7 @@ Functions to calculate odds ratios in \code{\link[=estimate_odds_ratio]{estimate } \section{Functions}{ \itemize{ -\item \code{or_glm()}: estimates the odds ratio based on \code{\link[stats:glm]{stats::glm()}}. Note that there must be +\item \code{or_glm()}: Estimates the odds ratio based on \code{\link[stats:glm]{stats::glm()}}. Note that there must be exactly 2 groups in \code{data} as specified by the \code{grp} variable. \item \code{or_clogit()}: estimates the odds ratio based on \code{\link[survival:clogit]{survival::clogit()}}. This is done for diff --git a/man/h_pkparam_sort.Rd b/man/h_pkparam_sort.Rd index 06a3a76c1c..5291e00e02 100644 --- a/man/h_pkparam_sort.Rd +++ b/man/h_pkparam_sort.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/h_pkparam_sort.R \name{h_pkparam_sort} \alias{h_pkparam_sort} -\title{Sort \verb{PK PARAM} variable} +\title{Sort Data by \verb{PK PARAM} Variable} \usage{ h_pkparam_sort(pk_data, key_var = "PARAMCD") } @@ -12,7 +12,7 @@ h_pkparam_sort(pk_data, key_var = "PARAMCD") \item{key_var}{(\code{character})\cr key variable used to merge pk_data and metadata created by \code{d_pkparam()}} } \value{ -dataframe with \verb{PK PARAM} variable ordered +A PK \code{data.frame} sorted by a \code{PARAM} variable. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_prop_diff.Rd b/man/h_prop_diff.Rd index ec4f0793dc..8c791638b7 100644 --- a/man/h_prop_diff.Rd +++ b/man/h_prop_diff.Rd @@ -42,6 +42,10 @@ information, see \code{\link[stats:prop.test]{stats::prop.test()}}.} \item{weights_method}{(\code{string})\cr weights method. Can be either \code{"cmh"} or \code{"heuristic"} and directs the way weights are estimated.} } +\value{ +A named \code{list} of elements \code{diff} (proportion difference) and \code{diff_ci} +(proportion difference confidence interval). +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} } diff --git a/man/h_prop_diff_test.Rd b/man/h_prop_diff_test.Rd index f52d82828b..18ff7b9dfd 100644 --- a/man/h_prop_diff_test.Rd +++ b/man/h_prop_diff_test.Rd @@ -23,6 +23,9 @@ prop_fisher(tbl) \item{ary}{(\code{array}, 3 dimensions)\cr array with two groups in rows, the binary response (\code{TRUE}/\code{FALSE}) in columns, and the strata in the third dimension.} } +\value{ +A p-value. +} \description{ Helper functions to implement various tests on the difference between two proportions. diff --git a/man/h_proportions.Rd b/man/h_proportions.Rd index 8413a1ceb7..9243e87f37 100644 --- a/man/h_proportions.Rd +++ b/man/h_proportions.Rd @@ -45,6 +45,9 @@ minimizes the weighted squared length of the confidence interval.} \item{max_iterations}{(\code{count})\cr maximum number of iterations for the iterative procedure used to find estimates of optimal weights.} } +\value{ +Confidence interval of a proportion. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -52,28 +55,23 @@ Functions to calculate different proportion confidence intervals for use in \cod } \section{Functions}{ \itemize{ -\item \code{prop_wilson()}: the Wilson interval calls \code{\link[stats:prop.test]{stats::prop.test()}}. +\item \code{prop_wilson()}: Calculates the Wilson interval by calling \code{\link[stats:prop.test]{stats::prop.test()}}. Also referred to as Wilson score interval. \item \code{prop_strat_wilson()}: Calculates the stratified Wilson confidence -interval for unequal proportions as described in -\insertCite{Yan2010-jt;textual}{tern} +interval for unequal proportions as described in \insertCite{Yan2010-jt;textual}{tern} -\item \code{prop_clopper_pearson()}: the Clopper-Pearson interval calls -\code{\link[stats:binom.test]{stats::binom.test()}}. Also referred to as the \code{exact} method. +\item \code{prop_clopper_pearson()}: Calculates the Clopper-Pearson interval by calling \code{\link[stats:binom.test]{stats::binom.test()}}. +Also referred to as the \code{exact} method. -\item \code{prop_wald()}: the Wald interval follows the usual -textbook definition for a single proportion confidence interval using the -normal approximation. +\item \code{prop_wald()}: Calculates the Wald interval by following the usual textbook definition +for a single proportion confidence interval using the normal approximation. -\item \code{prop_agresti_coull()}: the Agresti-Coull interval was created by -Alan Agresti and Brent Coull and can be understood (for 95\% CI) as adding -two successes and two failures to the data, and then using the Wald -formula to construct a CI. +\item \code{prop_agresti_coull()}: Calculates the Agresti-Coull interval (created by Alan Agresti and Brent Coull) by +(for 95\% CI) adding two successes and two failures to the data and then using the Wald formula to construct a CI. -\item \code{prop_jeffreys()}: the Jeffreys interval is an equal-tailed -interval based on the non-informative Jeffreys prior for a binomial -proportion. +\item \code{prop_jeffreys()}: Calculates the Jeffreys interval, an equal-tailed interval based on the +non-informative Jeffreys prior for a binomial proportion. }} \examples{ diff --git a/man/h_response_biomarkers_subgroups.Rd b/man/h_response_biomarkers_subgroups.Rd index 2d5a8e992f..63eed639b1 100644 --- a/man/h_response_biomarkers_subgroups.Rd +++ b/man/h_response_biomarkers_subgroups.Rd @@ -28,14 +28,29 @@ returned by \code{\link[=extract_rsp_biomarkers]{extract_rsp_biomarkers()}} (it added by that high-level function relative to what is returned by \code{\link[=h_logistic_mult_cont_df]{h_logistic_mult_cont_df()}}, see the example).} -\item{vars}{(\code{character})\cr the name of statistics to be reported among -\code{n_tot} (total number of patients per group), -\code{n_rsp} (total number of responses per group), -\code{prop} (total response proportion per group), -\code{or} (odds ratio), -\code{ci} (confidence interval of odds ratio) and -\code{pval} (p value of the effect). -Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required.} +\item{vars}{(\code{character})\cr the names of statistics to be reported among: +\itemize{ +\item \code{n_tot}: Total number of patients per group. +\item \code{n_rsp}: Total number of responses per group. +\item \code{prop}: Total response proportion per group. +\item \code{or}: Odds ratio. +\item \code{ci}: Confidence interval of odds ratio. +\item \code{pval}: p-value of the effect. +Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required. +}} +} +\value{ +\itemize{ +\item \code{h_rsp_to_logistic_variables()} returns a named \code{list} of elements \code{response}, \code{arm}, \code{covariates}, and \code{strata}. +} + +\itemize{ +\item \code{h_logistic_mult_cont_df()} returns a \code{data.frame} containing estimates and statistics for the selected biomarkers. +} + +\itemize{ +\item \code{h_tab_rsp_one_biomarker()} returns an \code{rtables} table object with the given statistics arranged in columns. +} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_response_subgroups.Rd b/man/h_response_subgroups.Rd index 39d2c42b4c..1a9ed3d422 100644 --- a/man/h_response_subgroups.Rd +++ b/man/h_response_subgroups.Rd @@ -50,14 +50,34 @@ levels that belong to it in the character vectors that are elements of the list. \item{method}{(\code{string})\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.} } +\value{ +\itemize{ +\item \code{h_proportion_df()} returns a \code{data.frame} with columns \code{arm}, \code{n}, \code{n_rsp}, and \code{prop}. +} + +\itemize{ +\item \code{h_proportion_subgroups_df()} returns a \code{data.frame} with columns \code{arm}, \code{n}, \code{n_rsp}, \code{prop}, \code{subgroup}, +\code{var}, \code{var_label}, and \code{row_type}. +} + +\itemize{ +\item \code{h_odds_ratio_df()} returns a \code{data.frame} with columns \code{arm}, \code{n_tot}, \code{or}, \code{lcl}, \code{ucl}, \code{conf_level}, and +optionally \code{pval} and \code{pval_label}. +} + +\itemize{ +\item \code{h_odds_ratio_subgroups_df()} returns a \code{data.frame} with columns \code{arm}, \code{n_tot}, \code{or}, \code{lcl}, \code{ucl}, +\code{conf_level}, \code{subgroup}, \code{var}, \code{var_label}, and \code{row_type}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -} -\details{ + Helper functions that tabulate in a data frame statistics such as response rate and odds ratio for population subgroups. - -Main functionality is to prepare data for use in a layout creating function. +} +\details{ +Main functionality is to prepare data for use in a layout-creating function. } \section{Functions}{ \itemize{ @@ -95,6 +115,7 @@ adrs_f <- adrs \%>\% ) formatters::var_labels(adrs_f) <- c(adrs_labels, "Response") + h_proportion_df( c(TRUE, FALSE, FALSE), arm = factor(c("A", "A", "B"), levels = c("A", "B")) diff --git a/man/h_split_param.Rd b/man/h_split_param.Rd index c1a725bc46..9f697d6e7f 100644 --- a/man/h_split_param.Rd +++ b/man/h_split_param.Rd @@ -13,6 +13,10 @@ h_split_param(param, value, f) \item{f}{(\code{list} of \code{vectors})\cr the reference to make the split} } +\value{ +A named \code{list} with the same element names as \code{f}, each containing the +elements specified in \code{.stats}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_stack_by_baskets.Rd b/man/h_stack_by_baskets.Rd index 09767a52c0..b1f4230d91 100644 --- a/man/h_stack_by_baskets.Rd +++ b/man/h_stack_by_baskets.Rd @@ -31,6 +31,10 @@ The two columns of this dataset should be named \code{basket} and \code{basket_n \item{na_level}{(\code{string})\cr used to replace all \code{NA} or empty values in factors with custom \code{string}.} } +\value{ +\code{data.frame} with variables in \code{keys} taken from \code{df} and new variable \code{SMQ} containing +records belonging to the baskets selected via the \code{baskets} argument. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_step.Rd b/man/h_step.Rd index de52cfc8d4..5c5656209d 100644 --- a/man/h_step.Rd +++ b/man/h_step.Rd @@ -51,6 +51,37 @@ h_step_rsp_est( \item{subset}{(\code{logical})\cr subset vector.} } +\value{ +\itemize{ +\item \code{h_step_window()} returns a list containing the window-selection matrix \code{sel} +and the interval information matrix \code{interval}. +} + +\itemize{ +\item \code{h_step_trt_effect()} returns a vector with elements \code{est} and \code{se}. +} + +\itemize{ +\item \code{h_step_survival_formula()} returns a model formula. +} + +\itemize{ +\item \code{h_step_survival_est()} returns a matrix of number of observations \code{n}, +\code{events}, log hazard ratio estimates \code{loghr}, standard error \code{se}, +and Wald confidence interval bounds \code{ci_lower} and \code{ci_upper}. One row is +included for each biomarker value in \code{x}. +} + +\itemize{ +\item \code{h_step_rsp_formula()} returns a model formula. +} + +\itemize{ +\item \code{h_step_rsp_est()} returns a matrix of number of observations \code{n}, log odds +ratio estimates \code{logor}, standard error \code{se}, and Wald confidence interval bounds +\code{ci_lower} and \code{ci_upper}. One row is included for each biomarker value in \code{x}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -59,31 +90,24 @@ Helper functions that are used internally for the STEP calculations. \section{Functions}{ \itemize{ \item \code{h_step_window()}: creates the windows for STEP, based on the control settings -provided. Returns a list containing the window-selection matrix \code{sel} -and the interval information matrix \code{interval}. +provided. \item \code{h_step_trt_effect()}: calculates the estimated treatment effect estimate on the linear predictor scale and corresponding standard error from a STEP \code{model} fitted on \code{data} given \code{variables} specification, for a single biomarker value \code{x}. This works for both \code{coxph} and \code{glm} models, i.e. for calculating log hazard ratio or log odds -ratio estimates. It returns a vector with elements \code{est} and \code{se}. +ratio estimates. \item \code{h_step_survival_formula()}: builds the model formula used in survival STEP calculations. \item \code{h_step_survival_est()}: estimates the model with \code{formula} built based on \code{variables} in \code{data} for a given \code{subset} and \code{control} parameters for the -Cox regression, and returns a matrix of number of observations \code{n}, -\code{events} as well as log hazard ratio estimates \code{loghr}, standard error \code{se} -and Wald confidence interval bounds \code{ci_lower} and \code{ci_upper}. One row is -included here for each biomarker value in \code{x}. +Cox regression. \item \code{h_step_rsp_formula()}: builds the model formula used in response STEP calculations. \item \code{h_step_rsp_est()}: estimates the model with \code{formula} built based on \code{variables} in \code{data} for a given \code{subset} and \code{control} parameters for the -logistic regression, and returns a matrix of number of observations \code{n} -as well as log odds ratio estimates \code{logor}, standard error \code{se} -and Wald confidence interval bounds \code{ci_lower} and \code{ci_upper}. One row is -included here for each biomarker value in \code{x}. +logistic regression. }} diff --git a/man/h_survival_biomarkers_subgroups.Rd b/man/h_survival_biomarkers_subgroups.Rd index e7be6e47a7..6637c6d54f 100644 --- a/man/h_survival_biomarkers_subgroups.Rd +++ b/man/h_survival_biomarkers_subgroups.Rd @@ -30,11 +30,11 @@ see the example).} \item{vars}{(\code{character})\cr the names of statistics to be reported among: \itemize{ -\item \code{n_tot_events}: total number of events per group. -\item \code{n_tot}: total number of observations per group. -\item \code{median}: median survival time. -\item \code{hr}: hazard ratio. -\item \code{ci}: confidence interval of hazard ratio. +\item \code{n_tot_events}: Total number of events per group. +\item \code{n_tot}: Total number of observations per group. +\item \code{median}: Median survival time. +\item \code{hr}: Hazard ratio. +\item \code{ci}: Confidence interval of hazard ratio. \item \code{pval}: p-value of the effect. Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as both \code{hr} and \code{ci} are required. }} @@ -42,6 +42,20 @@ Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as bot \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} } +\value{ +\itemize{ +\item \code{h_surv_to_coxreg_variables()} returns a named \code{list} of elements \code{time}, \code{event}, \code{arm}, +\code{covariates}, and \code{strata}. +} + +\itemize{ +\item \code{h_coxreg_mult_cont_df()} returns a \code{data.frame} containing estimates and statistics for the selected biomarkers. +} + +\itemize{ +\item \code{h_tab_surv_one_biomarker()} returns an \code{rtables} table object with the given statistics arranged in columns. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_survival_duration_subgroups.Rd b/man/h_survival_duration_subgroups.Rd index b2c00a08ac..017c11a033 100644 --- a/man/h_survival_duration_subgroups.Rd +++ b/man/h_survival_duration_subgroups.Rd @@ -56,6 +56,26 @@ can also be set to "breslow" or "exact". See more in \code{\link[survival:coxph] \item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. }} } +\value{ +\itemize{ +\item \code{h_survtime_df()} returns a \code{data.frame} with columns \code{arm}, \code{n}, \code{n_events}, and \code{median}. +} + +\itemize{ +\item \code{h_survtime_subgroups_df()} returns a \code{data.frame} with columns \code{arm}, \code{n}, \code{n_events}, \code{median}, \code{subgroup}, +\code{var}, \code{var_label}, and \code{row_type}. +} + +\itemize{ +\item \code{h_coxph_df()} returns a \code{data.frame} with columns \code{arm}, \code{n_tot}, \code{n_tot_events}, \code{hr}, \code{lcl}, \code{ucl}, +\code{conf_level}, \code{pval} and \code{pval_label}. +} + +\itemize{ +\item \code{h_coxph_subgroups_df()} returns a \code{data.frame} with columns \code{arm}, \code{n_tot}, \code{n_tot_events}, \code{hr}, +\code{lcl}, \code{ucl}, \code{conf_level}, \code{pval}, \code{pval_label}, \code{subgroup}, \code{var}, \code{var_label}, and \code{row_type}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -63,7 +83,7 @@ Helper functions that tabulate in a data frame statistics such as median surviva time and hazard ratio for population subgroups. } \details{ -Main functionality is to prepare data for use in a layout creating function. +Main functionality is to prepare data for use in a layout-creating function. } \section{Functions}{ \itemize{ diff --git a/man/h_tab_one_biomarker.Rd b/man/h_tab_one_biomarker.Rd index afa4e0a559..2e832d3c93 100644 --- a/man/h_tab_one_biomarker.Rd +++ b/man/h_tab_one_biomarker.Rd @@ -14,11 +14,11 @@ h_tab_one_biomarker(df, afuns, colvars) \item{colvars}{(\code{list} with \code{vars} and \code{labels})\cr variables to tabulate and their labels.} } \value{ -The \code{rtables} table object. +An \code{rtables} table object with statistics in columns. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -This is used by \code{\link[=h_tab_surv_one_biomarker]{h_tab_surv_one_biomarker()}} and \code{\link[=h_tab_rsp_one_biomarker]{h_tab_rsp_one_biomarker()}}, -please see there for examples. +Please see \code{\link[=h_tab_surv_one_biomarker]{h_tab_surv_one_biomarker()}} and \code{\link[=h_tab_rsp_one_biomarker]{h_tab_rsp_one_biomarker()}}, +which use this function for examples. } diff --git a/man/h_tbl_coxph_pairwise.Rd b/man/h_tbl_coxph_pairwise.Rd index dc44a45f32..f2a4778ad5 100644 --- a/man/h_tbl_coxph_pairwise.Rd +++ b/man/h_tbl_coxph_pairwise.Rd @@ -27,10 +27,14 @@ can also be set to "breslow" or "exact". See more in \code{\link[survival:coxph] \item \code{conf_level} (\code{proportion})\cr confidence level of the interval for HR. }} } +\value{ +A \code{data.frame} containing statistics \code{HR}, \verb{XX\% CI} (\code{XX} taken from \code{control_coxph_pw}), +and \code{p-value (log-rank)}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Create an \code{rtable} of pairwise stratified or unstratified CoxPH analysis results. +Create a \code{data.frame} of pairwise stratified or unstratified CoxPH analysis results. } \examples{ \dontrun{ diff --git a/man/h_tbl_median_surv.Rd b/man/h_tbl_median_surv.Rd index bd62784e06..ac4e87ed03 100644 --- a/man/h_tbl_median_surv.Rd +++ b/man/h_tbl_median_surv.Rd @@ -12,6 +12,9 @@ h_tbl_median_surv(fit_km, armval = "All") \item{armval}{(\code{string})\cr used as strata name when treatment arm variable only has one level. Default is "All".} } +\value{ +A summary table with statistics \code{N}, \code{Median}, and \verb{XX\% CI} (\code{XX} taken from \code{fit_km}). +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/h_worsen_counter.Rd b/man/h_worsen_counter.Rd index 832ca42b68..054a04d072 100644 --- a/man/h_worsen_counter.Rd +++ b/man/h_worsen_counter.Rd @@ -25,7 +25,7 @@ Only lab records flagged by \code{L}, \code{H} or \code{B} are included in the s }} } \value{ -\code{\link[=h_worsen_counter]{h_worsen_counter()}} returns the counts and fraction of patients +\code{h_worsen_counter()} returns the counts and fraction of patients whose worst post-baseline lab grades are worse than their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any". } diff --git a/man/h_xticks.Rd b/man/h_xticks.Rd index 6681b36b9b..ee4b0fae89 100644 --- a/man/h_xticks.Rd +++ b/man/h_xticks.Rd @@ -16,6 +16,9 @@ an optimal tick position on the x axis.} \item{max_time}{(\code{numeric})\cr maximum value to show on X axis. Only data values less than or up to this threshold value will be plotted (defaults to \code{NULL}).} } +\value{ +A vector of positions to use for x-axis ticks on a \code{ggplot} object. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/incidence_rate.Rd b/man/incidence_rate.Rd index 9e853e47e6..497cfefad3 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -80,12 +80,24 @@ to avoid warnings from \code{rtables}.} \item{alpha}{(\code{numeric})\cr two-sided alpha-level for confidence interval.} } \value{ -The statistics are: -\describe{ -\item{person_years}{total person-years at risk} -\item{n_events}{total number of events observed} -\item{rate}{estimated incidence rate} -\item{rate_ci}{confidence interval for the incidence rate} +\itemize{ +\item \code{s_incidence_rate()} returns the following statistics: +\itemize{ +\item \code{person_years}: Total person-years at risk. +\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. +} +} + +\itemize{ +\item \code{a_incidence_rate()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{estimate_incidence_rate()} 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_incidence_rate()} to the table layout. } } \description{ @@ -99,11 +111,11 @@ as incidence rate. Primary analysis variable is the person-years at risk. \item \code{s_incidence_rate()}: Statistics function which estimates the incidence rate and the associated confidence interval. -\item \code{a_incidence_rate()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_incidence_rate()}: Formatted analysis function which is used as \code{afun} +in \code{estimate_incidence_rate()}. -\item \code{estimate_incidence_rate()}: Layout creating function which adds analyze rows using the statistics -function \code{s_incidence_rate} and desired format. +\item \code{estimate_incidence_rate()}: 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()}}. }} \examples{ diff --git a/man/individual_patient_plot.Rd b/man/individual_patient_plot.Rd index 901d246099..b942248bfa 100644 --- a/man/individual_patient_plot.Rd +++ b/man/individual_patient_plot.Rd @@ -60,7 +60,7 @@ plot. Ignored when \code{plotting_choices} is not "separate_by_obs".} \item{col}{(\code{character})\cr lines colors.} } \value{ -a \code{ggplot} object or a list of \code{ggplot} objects. +A \code{ggplot} object or a list of \code{ggplot} objects. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/labels_or_names.Rd b/man/labels_or_names.Rd index c04542e8d4..828104ea26 100644 --- a/man/labels_or_names.Rd +++ b/man/labels_or_names.Rd @@ -10,7 +10,7 @@ labels_or_names(x) \item{x}{a list} } \value{ -a character vector with the labels or names for the list elements +A \code{character} vector with the labels or names for the list elements. } \description{ Internal helper function for working with nested statistic function results which typically diff --git a/man/logistic_regression_cols.Rd b/man/logistic_regression_cols.Rd index 50c755453d..6c26be795b 100644 --- a/man/logistic_regression_cols.Rd +++ b/man/logistic_regression_cols.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/logistic_regression.R \name{logistic_regression_cols} \alias{logistic_regression_cols} -\title{Logistic Regression Multi-Variable Column Layout Function} +\title{Logistic Regression Multivariate Column Layout Function} \usage{ logistic_regression_cols(lyt, conf_level = 0.95) } @@ -11,9 +11,14 @@ logistic_regression_cols(lyt, conf_level = 0.95) \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} } +\value{ +A layout object suitable for passing to further layouting functions. Adding this +function to an \code{rtable} layout will split the table into columns corresponding to +statistics \code{df}, \code{estimate}, \code{std_error}, \code{odds_ratio}, \code{ci}, and \code{pvalue}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Layout creating function for a multi-variable column layout summarizing -logistic regression results. +Layout-creating function which creates a multivariate column layout summarizing logistic +regression results. This function is a wrapper for \code{\link[rtables:split_cols_by_multivar]{rtables::split_cols_by_multivar()}}. } diff --git a/man/logistic_summary_by_flag.Rd b/man/logistic_summary_by_flag.Rd index e9cc34366d..c7d9ad4ac5 100644 --- a/man/logistic_summary_by_flag.Rd +++ b/man/logistic_summary_by_flag.Rd @@ -10,9 +10,12 @@ logistic_summary_by_flag(flag_var) \item{flag_var}{(\code{string})\cr variable name identifying which row should be used in this content function.} } +\value{ +A content function. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Constructor for content functions to be used to summarize +Constructor for content functions to be used in \code{\link[=summarize_logistic]{summarize_logistic()}} to summarize logistic regression results. } diff --git a/man/make_names.Rd b/man/make_names.Rd index 8aebce6dda..603767e10c 100644 --- a/man/make_names.Rd +++ b/man/make_names.Rd @@ -10,7 +10,7 @@ make_names(nams) \item{nams}{(\code{character})\cr vector of original names.} } \value{ -Character vector of proper names, which does not use dots in contrast to +A \code{character} \code{vector} of proper names, which does not use dots in contrast to \code{\link[base:make.names]{base::make.names()}}. } \description{ diff --git a/man/muffled_car_anova.Rd b/man/muffled_car_anova.Rd index cc8cc8a099..978af264c3 100644 --- a/man/muffled_car_anova.Rd +++ b/man/muffled_car_anova.Rd @@ -12,6 +12,9 @@ muffled_car_anova(mod, test_statistic) \item{test_statistic}{(\code{string})\cr the method used for estimation of p.values; \code{wald} (default) or \code{likelihood}.} } +\value{ +Returns the output of \code{\link[car:Anova]{car::Anova()}}, with convergence message muffled. +} \description{ Applied on survival models, \code{\link[car:Anova]{car::Anova()}} signal that the \code{strata} terms is dropped from the model formula when present, this function deliberately muffles this message. diff --git a/man/odds_ratio.Rd b/man/odds_ratio.Rd index 1531efe6ed..23c72e8790 100644 --- a/man/odds_ratio.Rd +++ b/man/odds_ratio.Rd @@ -79,6 +79,22 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +\itemize{ +\item \code{s_odds_ratio()} returns a named list with the statistics \code{or_ci} +(containing \code{est}, \code{lcl}, and \code{ucl}) and \code{n_tot}. +} + +\itemize{ +\item \code{a_odds_ratio()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{estimate_odds_ratio()} 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_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]}} @@ -89,27 +105,26 @@ along with a confidence interval. 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 that, for stratified analyses, there is currently no -implementation for conditional likelihood confidence intervals, -therefore the likelihood confidence interval as an option is not yet -available. 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. +calculated. } \section{Functions}{ \itemize{ \item \code{s_odds_ratio()}: Statistics function which estimates the odds ratio -between a treatment and a control. Note that a \code{variables} list with \code{arm} and \code{strata} names -needs to be passed if a stratified analysis is required. +between a treatment and a control. A \code{variables} list with \code{arm} and \code{strata} +variable names must be passed if a stratified analysis is required. -\item \code{a_odds_ratio()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_odds_ratio()}: Formatted analysis function which is used as \code{afun} in \code{estimate_odds_ratio()}. -\item \code{estimate_odds_ratio()}: Layout creating function which can be used for creating -tables, which can take statistics function arguments and additional format -arguments (see below). +\item \code{estimate_odds_ratio()}: 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()}}. }} +\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. +} \examples{ set.seed(12) dta <- data.frame( diff --git a/man/pairwise.Rd b/man/pairwise.Rd index 57ef9a8122..c1a5d7e81a 100644 --- a/man/pairwise.Rd +++ b/man/pairwise.Rd @@ -7,7 +7,10 @@ pairwise(x) } \arguments{ -\item{x}{the variable for which pairwise result is expected} +\item{x}{the variable for which pairwise result is expected.} +} +\value{ +Variable "paired". } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/prop_diff.Rd b/man/prop_diff.Rd index 79e768a8aa..8e85d0934a 100644 --- a/man/prop_diff.Rd +++ b/man/prop_diff.Rd @@ -84,6 +84,21 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +\itemize{ +\item \code{s_proportion_diff()} returns a named list of elements \code{diff} and \code{diff_ci}. +} + +\itemize{ +\item \code{a_proportion_diff()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{estimate_proportion_diff()} 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_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]}} } @@ -92,14 +107,10 @@ to avoid warnings from \code{rtables}.} \item \code{s_proportion_diff()}: Statistics function estimating the difference in terms of responder proportion. -\item \code{a_proportion_diff()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_proportion_diff()}: Formatted analysis function which is used as \code{afun} in \code{estimate_proportion_diff()}. -\item \code{estimate_proportion_diff()}: Adds a descriptive analyze layer to \code{rtables} -pipelines. The analysis is applied to a \code{dataframe} and return the -estimations, in \code{rcells}. The ellipsis (\code{...}) conveys arguments to -\code{s_proportion_diff()}, for instance \code{na.rm = FALSE} if missing data -should be accounted for. +\item \code{estimate_proportion_diff()}: 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()}}. }} \examples{ diff --git a/man/prop_diff_test.Rd b/man/prop_diff_test.Rd index 7686f45bdc..a75c13db5c 100644 --- a/man/prop_diff_test.Rd +++ b/man/prop_diff_test.Rd @@ -78,9 +78,20 @@ to avoid warnings from \code{rtables}.} (\code{TRUE}/\code{FALSE}) in columns.} } \value{ -Named \code{list} with a single item \code{pval} with an attribute \code{label} -describing the method used. The p-value tests the null hypothesis that -proportions in two groups are the same. +\itemize{ +\item \code{s_test_proportion_diff()} returns a named \code{list} with a single item \code{pval} with an attribute \code{label} +describing the method used. The p-value tests the null hypothesis that proportions in two groups are the same. +} + +\itemize{ +\item \code{a_test_proportion_diff()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{test_proportion_diff()} 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_test_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]}} @@ -93,12 +104,10 @@ proportions. \item \code{s_test_proportion_diff()}: Statistics function which tests the difference between two proportions. -\item \code{a_test_proportion_diff()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_test_proportion_diff()}: Formatted analysis function which is used as \code{afun} in \code{test_proportion_diff()}. -\item \code{test_proportion_diff()}: Layout creating function which can be used for -creating tables, which can take statistics function arguments and -additional format arguments. +\item \code{test_proportion_diff()}: 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()}}. }} \examples{ diff --git a/man/prune_occurrences.Rd b/man/prune_occurrences.Rd index 8ef686cf88..6a65b9449c 100644 --- a/man/prune_occurrences.Rd +++ b/man/prune_occurrences.Rd @@ -43,30 +43,46 @@ keep the row.} or alternatively \code{col_indices} (\code{integer}) giving the indices directly instead.} } \value{ -\code{\link[=keep_rows]{keep_rows()}} returns a pruning function that can be used with \code{\link[rtables:prune_table]{rtables::prune_table()}} -on \verb{[rtables::TableTree()]} objects. +\itemize{ +\item \code{keep_rows()} returns a pruning function that can be used with \code{\link[rtables:prune_table]{rtables::prune_table()}} +to prune an \code{rtables} table. +} -\code{\link[=keep_content_rows]{keep_content_rows()}} also returns a pruning function, the difference is that it -checks the condition on the first content row of leaf tables in the table. +\itemize{ +\item \code{keep_content_rows()} returns a pruning function that checks the condition on the first content +row of leaf tables in the table. +} -\code{\link[=has_count_in_cols]{has_count_in_cols()}} returns a condition function that sums the counts in the specified +\itemize{ +\item \code{has_count_in_cols()} returns a condition function that sums the counts in the specified column. +} -\code{\link[=has_count_in_any_col]{has_count_in_any_col()}} returns a condition function that compares the counts in the +\itemize{ +\item \code{has_count_in_any_col()} returns a condition function that compares the counts in the specified columns with the threshold. +} -\code{\link[=has_fraction_in_cols]{has_fraction_in_cols()}} returns a condition function that sums the counts in the +\itemize{ +\item \code{has_fraction_in_cols()} returns a condition function that sums the counts in the specified column, and computes the fraction by dividing by the total column counts. +} -\code{\link[=has_fraction_in_cols]{has_fraction_in_cols()}} returns a condition function that looks at the fractions +\itemize{ +\item \code{has_fraction_in_any_col()} returns a condition function that looks at the fractions in the specified columns and checks whether any of them fulfill the threshold. +} -\code{\link[=has_fractions_difference]{has_fractions_difference()}} returns a condition function that extracts the fractions of each +\itemize{ +\item \code{has_fractions_difference()} returns a condition function that extracts the fractions of each specified column, and computes the difference of the minimum and maximum. +} -\code{\link[=has_counts_difference]{has_counts_difference()}} returns a condition function that extracts the counts of each +\itemize{ +\item \code{has_counts_difference()} returns a condition function that extracts the counts of each specified column, and computes the difference of the minimum and maximum. } +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -77,39 +93,39 @@ functions. } \section{Functions}{ \itemize{ -\item \code{keep_rows()}: constructor for creating pruning functions based on +\item \code{keep_rows()}: Constructor for creating pruning functions based on a row condition function. This removes all analysis rows (\code{TableRow}) that should be -pruned, i.e., don't fulfill the row condition. It removes the sub tree if there are no +pruned, i.e., don't fulfill the row condition. It removes the sub-tree if there are no children left. -\item \code{keep_content_rows()}: constructor for creating pruning functions based on +\item \code{keep_content_rows()}: Constructor for creating pruning functions based on a condition for the (first) content row in leaf tables. This removes all leaf tables where the first content row does not fulfill the condition. It does not check individual rows. It then proceeds recursively by removing the sub tree if there are no children left. -\item \code{has_count_in_cols()}: constructor for creating condition functions on total counts in +\item \code{has_count_in_cols()}: Constructor for creating condition functions on total counts in the specified columns. -\item \code{has_count_in_any_col()}: constructor for creating condition functions on any of the counts in +\item \code{has_count_in_any_col()}: Constructor for creating condition functions on any of the counts in the specified columns satisfying a threshold. -\item \code{has_fraction_in_cols()}: constructor for creating condition functions on total fraction in +\item \code{has_fraction_in_cols()}: Constructor for creating condition functions on total fraction in the specified columns. -\item \code{has_fraction_in_any_col()}: constructor for creating condition functions on any fraction in +\item \code{has_fraction_in_any_col()}: Constructor for creating condition functions on any fraction in the specified columns. -\item \code{has_fractions_difference()}: constructor for creating condition function that checks the difference +\item \code{has_fractions_difference()}: Constructor for creating condition function that checks the difference between the fractions reported in each specified column. -\item \code{has_counts_difference()}: constructor for creating condition function that checks the difference +\item \code{has_counts_difference()}: Constructor for creating condition function that checks the difference between the counts reported in each specified column. }} \note{ Since most table specifications are worded positively, we name our constructor and condition functions positively, too. However, note that the result of \code{\link[=keep_rows]{keep_rows()}} says what -should be pruned though, to conform with the \code{\link[rtables:prune_table]{rtables::prune_table()}} interface. +should be pruned, to conform with the \code{\link[rtables:prune_table]{rtables::prune_table()}} interface. } \examples{ \dontrun{ diff --git a/man/range_noinf.Rd b/man/range_noinf.Rd index af89730783..da6035debf 100644 --- a/man/range_noinf.Rd +++ b/man/range_noinf.Rd @@ -16,7 +16,7 @@ range_noinf(x, na.rm = FALSE, finite = FALSE) \item{finite}{(\code{logical})\cr indicating if non-finite elements should be removed.} } \value{ -2-elements vector of class numeric. +A 2-element vector of class \code{numeric}. } \description{ Re-implemented \code{\link[base:range]{range.default}} default S3 method for numerical objects only. diff --git a/man/reapply_varlabels.Rd b/man/reapply_varlabels.Rd index dfd4cb47bf..f9156107b6 100644 --- a/man/reapply_varlabels.Rd +++ b/man/reapply_varlabels.Rd @@ -13,6 +13,9 @@ reapply_varlabels(x, varlabels, ...) \item{...}{further parameters to be added to the list.} } +\value{ +\code{x} with variable labels reapplied. +} \description{ This is a helper function that is used in tests. } diff --git a/man/response_biomarkers_subgroups.Rd b/man/response_biomarkers_subgroups.Rd index acbf797cf3..b78fec90a5 100644 --- a/man/response_biomarkers_subgroups.Rd +++ b/man/response_biomarkers_subgroups.Rd @@ -14,14 +14,19 @@ tabulate_rsp_biomarkers( \item{df}{(\code{data.frame})\cr containing all analysis variables, as returned by \code{\link[=extract_rsp_biomarkers]{extract_rsp_biomarkers()}}.} -\item{vars}{(\code{character})\cr the name of statistics to be reported among -\code{n_tot} (total number of patients per group), -\code{n_rsp} (total number of responses per group), -\code{prop} (total response proportion per group), -\code{or} (odds ratio), -\code{ci} (confidence interval of odds ratio) and -\code{pval} (p value of the effect). -Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required.} +\item{vars}{(\code{character})\cr the names of statistics to be reported among: +\itemize{ +\item \code{n_tot}: Total number of patients per group. +\item \code{n_rsp}: Total number of responses per group. +\item \code{prop}: Total response proportion per group. +\item \code{or}: Odds ratio. +\item \code{ci}: Confidence interval of odds ratio. +\item \code{pval}: p-value of the effect. +Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required. +}} +} +\value{ +An \code{rtables} table summarizing biomarker effects on 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]}} @@ -63,6 +68,7 @@ tab <- tabulate_rsp_biomarkers( ## Finally produce the forest plot. g_forest(tab, xlim = c(0.7, 1.4)) } + } \seealso{ \code{\link[=h_tab_rsp_one_biomarker]{h_tab_rsp_one_biomarker()}} which is used internally, \code{\link[=extract_rsp_biomarkers]{extract_rsp_biomarkers()}}. diff --git a/man/response_subgroups.Rd b/man/response_subgroups.Rd index b5a782105a..6a33d1b9bd 100644 --- a/man/response_subgroups.Rd +++ b/man/response_subgroups.Rd @@ -22,15 +22,17 @@ tabulate_rsp_subgroups(lyt, df, vars = c("n_tot", "n", "prop", "or", "ci")) \item{df}{(\code{list})\cr 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 name of statistics to be reported among -\code{n} (total number of observations per group), -\code{n_rsp} (number of responders per group), -\code{prop} (proportion of responders), -\code{n_tot} (total number of observations), -\code{or} (odds ratio), -\code{ci} (confidence interval of odds ratio) and -\code{pval} (p value of the effect). -Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required.} +\item{vars}{(\code{character})\cr the names of statistics to be reported among: +\itemize{ +\item \code{n}: Total number of observations per group. +\item \code{n_rsp}: Number of responders per group. +\item \code{prop}: Proportion of responders. +\item \code{n_tot}: Total number of observations. +\item \code{or}: Odds ratio. +\item \code{ci} : Confidence interval of odds ratio. +\item \code{pval}: p-value of the effect. +Note, the statistics \code{n_tot}, \code{or} and \code{ci} are required. +}} \item{data}{(\code{data.frame})\cr the dataset containing the variables to summarize.} @@ -43,6 +45,13 @@ levels that belong to it in the character vectors that are elements of the list. \item{method}{(\code{string})\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.} } +\value{ +\itemize{ +\item \code{a_response_subgroups()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +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]}} @@ -54,10 +63,10 @@ the required statistics. Tables typically used as part of forest plot. } \section{Functions}{ \itemize{ -\item \code{a_response_subgroups()}: Formatted Analysis function used to format the results of \code{\link[=extract_rsp_subgroups]{extract_rsp_subgroups()}}. -Returns is a list of Formatted Analysis functions with one element per statistic. +\item \code{a_response_subgroups()}: Formatted analysis function which is used as \code{afun} in \code{tabulate_rsp_subgroups()}. -\item \code{tabulate_rsp_subgroups()}: table creating function. +\item \code{tabulate_rsp_subgroups()}: Table-creating function which creates a table +summarizing binary response by subgroup. }} \examples{ @@ -84,6 +93,7 @@ df <- extract_rsp_subgroups( data = adrs_f ) df + # Internal function - a_response_subgroups \dontrun{ a_response_subgroups(.formats = list("n" = "xx", "prop" = "xx.xx\%")) diff --git a/man/rtables_access.Rd b/man/rtables_access.Rd index a8989624fa..bc14c49cb1 100644 --- a/man/rtables_access.Rd +++ b/man/rtables_access.Rd @@ -37,6 +37,35 @@ column split.)} \item{table}{(\code{VTableNodeInfo})\cr an occurrence table or row.} } +\value{ +\itemize{ +\item \code{h_row_first_values()} returns a \code{vector} of numeric values. +} + +\itemize{ +\item \code{h_row_counts()} returns a \code{vector} of numeric values. +} + +\itemize{ +\item \code{h_row_fractions()} returns a \code{vector} of proportions. +} + +\itemize{ +\item \code{h_col_counts()} returns a \code{vector} of column counts. +} + +\itemize{ +\item \code{h_content_first_row()} returns a row from an \code{rtables} table. +} + +\itemize{ +\item \code{is_leaf_table()} returns a \code{logical} value indicating whether current table is a leaf. +} + +\itemize{ +\item \code{check_names_indices} returns column indices. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} @@ -46,7 +75,7 @@ as having a count as the first element and a fraction as the second element in e } \section{Functions}{ \itemize{ -\item \code{h_row_first_values()}: helper function to extract the first values from each content +\item \code{h_row_first_values()}: Helper function to extract the first values from each content cell and from specified columns in a \code{TableRow}. Defaults to all columns. \item \code{h_row_counts()}: Helper function that extracts row values and checks if they are diff --git a/man/s_cox_multivariate.Rd b/man/s_cox_multivariate.Rd index 2101985ec2..420b5e5158 100644 --- a/man/s_cox_multivariate.Rd +++ b/man/s_cox_multivariate.Rd @@ -26,6 +26,9 @@ including covariates.} \item{...}{Optional parameters passed to \code{\link[survival:coxph]{survival::coxph()}}. Can include \code{ties}, a character string specifying the method for tie handling, one of \code{exact} (default), \code{efron}, \code{breslow}.} } +\value{ +A \code{list} with elements \code{mod}, \code{msum}, \code{aov}, and \code{coef_inter}. +} \description{ Analyses based on multivariate Cox model are usually not performed for the Controlled Substance Reporting or regulatory documents but serve exploratory purposes only (e.g., for publication). In practice, the model usually diff --git a/man/sas_na.Rd b/man/sas_na.Rd index fc4c8c8635..882dd47152 100644 --- a/man/sas_na.Rd +++ b/man/sas_na.Rd @@ -13,6 +13,10 @@ sas_na(x, empty = TRUE, whitespaces = TRUE) \item{whitespaces}{boolean, if true then strings made from whitespaces only get replaced with \code{NA}} } +\value{ +\code{x} with \code{""} and/or whitespace-only values substituted by \code{NA}, depending on the values of +\code{empty} and \code{whitespaces}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/score_occurrences.Rd b/man/score_occurrences.Rd index 0c109c1c69..6022709747 100644 --- a/man/score_occurrences.Rd +++ b/man/score_occurrences.Rd @@ -23,19 +23,30 @@ score_occurrences_cont_cols(...) or alternatively \code{col_indices} (\code{integer}) giving the indices directly instead.} } \value{ -\code{\link[=score_occurrences]{score_occurrences()}} returns the sum of counts across all columns of a table row. +\itemize{ +\item \code{score_occurrences()} returns the sum of counts across all columns of a table row. +} -\code{\link[=score_occurrences_cols]{score_occurrences_cols()}} returns a function that sums counts across all specified columns +\itemize{ +\item \code{score_occurrences_cols()} returns a function that sums counts across all specified columns of a table row. +} -\code{\link[=score_occurrences_subtable]{score_occurrences_subtable()}} returns a function that sums counts in each subtable +\itemize{ +\item \code{score_occurrences_subtable()} returns a function that sums counts in each subtable across all specified columns. } + +\itemize{ +\item \code{score_occurrences_cont_cols()} returns a function that sums counts in the first content row in +specified columns. +} +} \description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} + Functions to score occurrence table subtables and rows which can be used in the sorting of occurrence tables. - -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} } \section{Functions}{ \itemize{ diff --git a/man/split_cols_by_groups.Rd b/man/split_cols_by_groups.Rd index f7389ce39b..5236bddf2c 100644 --- a/man/split_cols_by_groups.Rd +++ b/man/split_cols_by_groups.Rd @@ -17,19 +17,17 @@ levels that belong to it in the character vectors that are elements of the list. \item{ref_group}{(\code{data.frame} or \code{vector})\cr the data corresponding to the reference group.} -\item{...}{additional arguments, see \emph{note} section.} +\item{...}{additional arguments to \code{\link[rtables:split_cols_by]{rtables::split_cols_by()}} in order. For instance, to +control formats (\code{format}), add a joint column for all groups (\code{incl_all}).} } \value{ -the modified layout. +A layout object suitable for passing to further layouting functions. Adding +this function to an \code{rtable} layout will add a column split including the given +groups 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]}} } -\note{ -The ellipse (\code{...}) conveys arguments to \code{\link[rtables:split_cols_by]{rtables::split_cols_by()}} -in order, for instance, to control formats (\code{format}), add a joint column -for all groups (\code{incl_all}). -} \examples{ # 1 - Basic use diff --git a/man/split_text_grob.Rd b/man/split_text_grob.Rd index d9a4d7f3c3..22dfd38f08 100644 --- a/man/split_text_grob.Rd +++ b/man/split_text_grob.Rd @@ -54,6 +54,9 @@ split_text_grob( \item{vp}{A Grid viewport object (or NULL).} } +\value{ +A text grob. +} \description{ Dynamically wrap text. } diff --git a/man/stack_grobs.Rd b/man/stack_grobs.Rd index 7954b540da..8aacffdc40 100644 --- a/man/stack_grobs.Rd +++ b/man/stack_grobs.Rd @@ -26,6 +26,9 @@ stack_grobs( \item{name}{a character identifier for the grob.} } +\value{ +A \code{grob}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/stat_mean_ci.Rd b/man/stat_mean_ci.Rd index 28d835cd27..2d87702bcc 100644 --- a/man/stat_mean_ci.Rd +++ b/man/stat_mean_ci.Rd @@ -29,6 +29,9 @@ for the use with \code{ggplot}.} \item{geom_mean}{(\code{logical})\cr \code{TRUE} when the geometric mean should be calculated} } +\value{ +A named \code{vector} of values \code{mean_ci_lwr} and \code{mean_ci_upr}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/stat_mean_pval.Rd b/man/stat_mean_pval.Rd index 49f7ae4380..b7f37501a9 100644 --- a/man/stat_mean_pval.Rd +++ b/man/stat_mean_pval.Rd @@ -16,6 +16,9 @@ the p-value of the mean.} \item{test_mean}{(\code{number})\cr mean value to test under the null hypothesis.} } +\value{ +A p-value. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/stat_median_ci.Rd b/man/stat_median_ci.Rd index 688e430b30..f62ac40c8b 100644 --- a/man/stat_median_ci.Rd +++ b/man/stat_median_ci.Rd @@ -16,6 +16,9 @@ stat_median_ci(x, conf_level = 0.95, na.rm = TRUE, gg_helper = TRUE) \item{gg_helper}{(\code{logical})\cr \code{TRUE} when output should be aligned for the use with \code{ggplot}.} } +\value{ +A named \code{vector} of values \code{median_ci_lwr} and \code{median_ci_upr}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/strata_normal_quantile.Rd b/man/strata_normal_quantile.Rd index 877dc338f8..8890224bcf 100644 --- a/man/strata_normal_quantile.Rd +++ b/man/strata_normal_quantile.Rd @@ -15,6 +15,9 @@ minimizes the weighted squared length of the confidence interval.} \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} } +\value{ +Stratified quantile. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/study_arm.Rd b/man/study_arm.Rd index d3d3c06ed6..27e8001581 100644 --- a/man/study_arm.Rd +++ b/man/study_arm.Rd @@ -9,6 +9,9 @@ study_arm(x) \arguments{ \item{x}{arm information} } +\value{ +\code{x} +} \description{ We use \code{study_arm} to indicate the study arm variable in \code{tern} formulas. } diff --git a/man/summarize_ancova.Rd b/man/summarize_ancova.Rd index 7fccd93489..b74c2515d2 100644 --- a/man/summarize_ancova.Rd +++ b/man/summarize_ancova.Rd @@ -90,17 +90,27 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -A named list of 5 statistics: -\describe{ -\item{n}{count of complete sample size for the group.} -\item{lsmean}{estimated marginal means in the group.} -\item{lsmean_diff}{difference in estimated marginal means in comparison to the reference group. +\itemize{ +\item \code{s_ancova()} returns a named list of 5 statistics: +\itemize{ +\item \code{n}: Count of complete sample size for the group. +\item \code{lsmean}: Estimated marginal means in the group. +\item \code{lsmean_diff}: Difference in estimated marginal means in comparison to the reference group. If working with the reference group, this will be empty. +\item \code{lsmean_diff_ci}: Confidence level for difference in estimated marginal means in comparison +to the reference group. +\item \code{pval}: p-value (not adjusted for multiple comparisons). } -\item{lsmean_diff_ci}{confidence level for difference in estimated marginal means in comparison to the -reference group. } -\item{pval}{p-value (not adjusted for multiple comparisons).} + +\itemize{ +\item \code{a_ancova()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{summarize_ancova()} 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_ancova()} to the table layout. } } \description{ @@ -114,11 +124,10 @@ multiple timepoints within the same response variable \code{.var}. \item \code{s_ancova()}: Statistics function that produces a named list of results of the investigated linear model. -\item \code{a_ancova()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_ancova()}: Formatted analysis function which is used as \code{afun} in \code{summarize_ancova()}. -\item \code{summarize_ancova()}: Layout creating function which can be be used for creating -summary tables for analysis of covariance (ANCOVA). +\item \code{summarize_ancova()}: 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()}}. }} \examples{ diff --git a/man/summarize_change.Rd b/man/summarize_change.Rd index 23d85687c5..a6762a3d42 100644 --- a/man/summarize_change.Rd +++ b/man/summarize_change.Rd @@ -49,7 +49,19 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -See \code{\link[=s_summary.numeric]{s_summary.numeric()}} for the return values. +\itemize{ +\item \code{s_change_from_baseline()} returns the same values returned by \code{\link[=s_summary.numeric]{s_summary.numeric()}}. +} + +\itemize{ +\item \code{a_change_from_baseline()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{summarize_change()} 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_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]}} @@ -61,20 +73,20 @@ or the change from baseline values (post-baseline) are then summarized. } \section{Functions}{ \itemize{ -\item \code{s_change_from_baseline()}: Statistics Function that summarizes baseline or post-baseline visits. +\item \code{s_change_from_baseline()}: Statistics function that summarizes baseline or post-baseline visits. -\item \code{a_change_from_baseline()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_change_from_baseline()}: Formatted analysis function which is used as \code{afun} in \code{summarize_change()}. -\item \code{summarize_change()}: Analyze Function for change from baseline analysis. -To be used after a split on visits in the layout, such that each data -subset only contains either baseline or post-baseline data. Allows additional -formatting options. +\item \code{summarize_change()}: 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()}}. }} \note{ The data in \code{df} must be either all be from baseline or post-baseline visits. Otherwise an error will be thrown. + +To be used after a split on visits in the layout, such that each data subset only contains +either baseline or post-baseline data. } \examples{ df <- data.frame( diff --git a/man/summarize_colvars.Rd b/man/summarize_colvars.Rd index c78251a4f2..a0331f376c 100644 --- a/man/summarize_colvars.Rd +++ b/man/summarize_colvars.Rd @@ -26,12 +26,16 @@ summarize_colvars( \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } +\value{ +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 summarize the given variables, arrange the output +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 new S3 generic function \code{\link[=s_summary]{s_summary()}} to summarize -different variables that are arranged in columns. -Additional standard formatting arguments are available. +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. } \examples{ diff --git a/man/summarize_glm_count.Rd b/man/summarize_glm_count.Rd index 1d3653da8a..dbf53d7b31 100644 --- a/man/summarize_glm_count.Rd +++ b/man/summarize_glm_count.Rd @@ -85,14 +85,26 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -A named list of 5 statistics: -\describe{ -\item{n}{count of complete sample size for the group.} -\item{rate}{estimated event rate per follow-up time.} -\item{rate_ci}{confidence level for estimated rate per follow-up time.} -\item{rate_ratio}{ratio of event rates in each treatment arm to the reference arm.} -\item{rate_ratio_ci}{confidence level for the rate ratio.} -\item{pval}{p-value.} +\itemize{ +\item \code{s_glm_count()} returns a named \code{list} of 5 statistics: +\itemize{ +\item \code{n}: Count of complete sample size for the group. +\item \code{rate}: Estimated event rate per follow-up time. +\item \code{rate_ci}: Confidence level for estimated rate per follow-up time. +\item \code{rate_ratio}: Ratio of event rates in each treatment arm to the reference arm. +\item \code{rate_ratio_ci}: Confidence level for the rate ratio. +\item \code{pval}: p-value. +} +} + +\itemize{ +\item \code{a_glm_count()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{summarize_glm_count()} 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_glm_count()} to the table layout. } } \description{ @@ -104,13 +116,12 @@ This can be used to analyze count and/or frequency data using a linear model. \section{Functions}{ \itemize{ \item \code{s_glm_count()}: Statistics function that produces a named list of results -of the investigated poisson model. +of the investigated Poisson model. -\item \code{a_glm_count()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_glm_count()}: Formatted analysis function which is used as \code{afun} in \code{summarize_glm_count()}. -\item \code{summarize_glm_count()}: Layout creating function which can be be used for creating -summary tables for analysis of count data using generalized linear models (poisson, quasipoisson). +\item \code{summarize_glm_count()}: 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()}}. }} \examples{ diff --git a/man/summarize_logistic.Rd b/man/summarize_logistic.Rd index 24f3791575..543db5309a 100644 --- a/man/summarize_logistic.Rd +++ b/man/summarize_logistic.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/logistic_regression.R \name{summarize_logistic} \alias{summarize_logistic} -\title{Multi-Variable Logistic Regression Table} +\title{Multivariate Logistic Regression Table} \usage{ summarize_logistic(lyt, conf_level, drop_and_remove_str = "") } @@ -11,12 +11,16 @@ summarize_logistic(lyt, conf_level, drop_and_remove_str = "") \item{conf_level}{(\code{proportion})\cr confidence level of the interval.} -\item{drop_and_remove_str}{string to be dropped and removed} +\item{drop_and_remove_str}{(\code{character})\cr string to be dropped and removed.} +} +\value{ +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 a logistic regression variable summary 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]}} -Layout creating function which summarizes a logistic variable regression for binary outcome with +Layout-creating function which summarizes a logistic variable regression for binary outcome with categorical/continuous covariates in model statement. For each covariate category (if categorical) or specified values (if continuous), present degrees of freedom, regression parameter estimate and standard error (SE) relative to reference group or category. Report odds ratios for each covariate @@ -25,7 +29,9 @@ to specify other confidence levels. Report p-value for Wald chi-square test of t that covariate has no effect on response in model containing all specified covariates. Allow option to include one two-way interaction and present similar output for each interaction degree of freedom. -Note: For the formula, the variable names need to be standard dataframe column name without +} +\note{ +For the formula, the variable names need to be standard \code{data.frame} column names without special characters. } \examples{ diff --git a/man/summarize_num_patients.Rd b/man/summarize_num_patients.Rd index 3a698fb20b..6e32870f99 100644 --- a/man/summarize_num_patients.Rd +++ b/man/summarize_num_patients.Rd @@ -5,7 +5,7 @@ \alias{s_num_patients} \alias{s_num_patients_content} \alias{analyze_num_patients} -\title{Number of patients} +\title{Number of Patients} \usage{ s_num_patients( x, @@ -90,11 +90,29 @@ unmodified default behavior.} \item{show_labels}{(\code{string})\cr label visibility: one of "default", "visible" and "hidden".} } \value{ -A list with: -\describe{ -\item{unique}{vector of count and percentage.} -\item{nonunique}{vector of count.} -\item{unique_count}{count.} +\itemize{ +\item \code{s_num_patients()} returns a named \code{list} of 3 statistics: +\itemize{ +\item \code{unique}: Vector of counts and percentages. +\item \code{nonunique}: Vector of counts. +\item \code{unique_count}: Counts. +} +} + +\itemize{ +\item \code{s_num_patients_content()} returns the same values as \code{s_num_patients()}. +} + +\itemize{ +\item \code{summarize_num_patients()} 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_num_patients_content()} to the table layout. +} + +\itemize{ +\item \code{analyze_num_patients()} 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_num_patients_content()} to the table layout. } } \description{ @@ -116,21 +134,20 @@ when pagination is involved. unique patients, the corresponding percentage taken with respect to the total number of patients, and the number of non-unique patients. -\item \code{s_num_patients_content()}: Counts the number of unique patients 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. -Function serves as a wrapper that carries over both expected arguments \code{df} -and \code{labelstr} in \code{cfun} of \code{\link[=summarize_row_groups]{summarize_row_groups()}}. +\item \code{s_num_patients_content()}: Statistics function which counts the number of unique patients +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. -\item \code{summarize_num_patients()}: Layout creating function which adds content rows using the statistics -function \code{\link[=s_num_patients_content]{s_num_patients_content()}} and desired format. +\item \code{summarize_num_patients()}: Layout-creating function which can take statistics function arguments +and additional format arguments. This function is a wrapper for \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. -\item \code{analyze_num_patients()}: Identically to \code{\link[=summarize_num_patients]{summarize_num_patients()}}, -This function creates a layout which adds content rows using the statistics -function \code{\link[=s_num_patients_content]{s_num_patients_content()}} and desired format. Differently from its -counterpart, this function does not impose the produced rows to be repeated. +\item \code{analyze_num_patients()}: 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()}}. }} +\note{ +As opposed to \code{\link[=summarize_num_patients]{summarize_num_patients()}}, this function does not repeat the produced rows. +} \examples{ # 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) diff --git a/man/summarize_patients_exposure_in_cols.Rd b/man/summarize_patients_exposure_in_cols.Rd index f0df6ecd15..25eeb274b0 100644 --- a/man/summarize_patients_exposure_in_cols.Rd +++ b/man/summarize_patients_exposure_in_cols.Rd @@ -55,10 +55,19 @@ be used as label.} column split has been done already earlier in the layout pipe.} } \value{ -\code{\link[=s_count_patients_sum_exposure]{s_count_patients_sum_exposure()}} returns a list with the statistics: -\describe{ -\item{n_patients}{number of unique patients in \code{df}.} -\item{sum_exposure}{sum of \code{.var} across all patients in \code{df}.} +\itemize{ +\item \code{s_count_patients_sum_exposure()} returns a named \code{list} with the statistics: +\itemize{ +\item \code{n_patients}: Number of unique patients in \code{df}. +\item \code{sum_exposure}: Sum of \code{.var} across all patients in \code{df}. +} +} + +\itemize{ +\item \code{summarize_patients_exposure_in_cols()} 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, with the statistics from \code{s_count_patients_sum_exposure()} arranged in +columns, to the table layout. } } \description{ @@ -72,8 +81,9 @@ when a column table layout is required. \item \code{s_count_patients_sum_exposure()}: Statistics function which counts numbers of patients and the sum of exposure across all patients. -\item \code{summarize_patients_exposure_in_cols()}: Layout creating function which adds the count -statistics of patients and the sum of analysis value in the column layout as content rows. +\item \code{summarize_patients_exposure_in_cols()}: Layout-creating function which can take statistics +function arguments and additional format arguments. This function is a wrapper for +\code{\link[rtables:split_cols_by_multivar]{rtables::split_cols_by_multivar()}} and \code{\link[rtables:summarize_row_groups]{rtables::summarize_row_groups()}}. }} \examples{ diff --git a/man/summarize_variables.Rd b/man/summarize_variables.Rd index a372132ca1..e9a2293304 100644 --- a/man/summarize_variables.Rd +++ b/man/summarize_variables.Rd @@ -185,104 +185,120 @@ defined by this split instruction, or \code{NA_character_} (the default) for no \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -If \code{x} is of class \code{numeric}, returns a list with the following named \code{numeric} items: -\describe{ -\item{n}{the \code{\link[=length]{length()}} of \code{x}.} -\item{sum}{the \code{\link[=sum]{sum()}} of \code{x}.} -\item{mean}{the \code{\link[=mean]{mean()}} of \code{x}.} -\item{sd}{the \code{\link[stats:sd]{stats::sd()}} of \code{x}.} -\item{se}{the standard error of \code{x} mean, i.e.: (\code{sd(x) / sqrt(length(x))}).} -\item{mean_sd}{the \code{\link[=mean]{mean()}} and \code{\link[stats:sd]{stats::sd()}} of \code{x}.} -\item{mean_se}{the \code{\link[=mean]{mean()}} of \code{x} and its standard error (see above).} -\item{mean_ci}{the CI for the mean of \code{x} (from \code{\link[=stat_mean_ci]{stat_mean_ci()}}).} -\item{mean_sei}{the SE interval for the mean of \code{x}, i.e.: (\code{\link[=mean]{mean()}} -/+ \code{\link[stats:sd]{stats::sd()}} / \code{\link[=sqrt]{sqrt()}}).} -\item{mean_sdi}{the SD interval for the mean of \code{x}, i.e.: (\code{\link[=mean]{mean()}} -/+ \code{\link[stats:sd]{stats::sd()}}).} -\item{mean_pval}{the two-sided p-value of the mean of \code{x} (from \code{\link[=stat_mean_pval]{stat_mean_pval()}}).} -\item{median}{the \code{\link[stats:median]{stats::median()}} of \code{x}.} -\item{mad}{the median absolute deviation of \code{x}, i.e.: (\code{\link[stats:median]{stats::median()}} of \code{xc}, +\itemize{ +\item \code{s_summary()} returns different statistics depending on the class of \code{x}. +} + +\itemize{ +\item If \code{x} is of class \code{numeric}, returns a \code{list} with the following named \code{numeric} items: +\itemize{ +\item \code{n}: The \code{\link[=length]{length()}} of \code{x}. +\item \code{sum}: The \code{\link[=sum]{sum()}} of \code{x}. +\item \code{mean}: The \code{\link[=mean]{mean()}} of \code{x}. +\item \code{sd}: The \code{\link[stats:sd]{stats::sd()}} of \code{x}. +\item \code{se}: The standard error of \code{x} mean, i.e.: (\code{sd(x) / sqrt(length(x))}). +\item \code{mean_sd}: The \code{\link[=mean]{mean()}} and \code{\link[stats:sd]{stats::sd()}} of \code{x}. +\item \code{mean_se}: The \code{\link[=mean]{mean()}} of \code{x} and its standard error (see above). +\item \code{mean_ci}: The CI for the mean of \code{x} (from \code{\link[=stat_mean_ci]{stat_mean_ci()}}). +\item \code{mean_sei}: The SE interval for the mean of \code{x}, i.e.: (\code{\link[=mean]{mean()}} -/+ \code{\link[stats:sd]{stats::sd()}} / \code{\link[=sqrt]{sqrt()}}). +\item \code{mean_sdi}: The SD interval for the mean of \code{x}, i.e.: (\code{\link[=mean]{mean()}} -/+ \code{\link[stats:sd]{stats::sd()}}). +\item \code{mean_pval}: The two-sided p-value of the mean of \code{x} (from \code{\link[=stat_mean_pval]{stat_mean_pval()}}). +\item \code{median}: The \code{\link[stats:median]{stats::median()}} of \code{x}. +\item \code{mad}: The median absolute deviation of \code{x}, i.e.: (\code{\link[stats:median]{stats::median()}} of \code{xc}, where \code{xc} = \code{x} - \code{\link[stats:median]{stats::median()}}). +\item \code{median_ci}: The CI for the median of \code{x} (from \code{\link[=stat_median_ci]{stat_median_ci()}}). +\item \code{quantiles}: Two sample quantiles of \code{x} (from \code{\link[stats:quantile]{stats::quantile()}}). +\item \code{iqr}: The \code{\link[stats:IQR]{stats::IQR()}} of \code{x}. +\item \code{range}: The \code{\link[=range_noinf]{range_noinf()}} of \code{x}. +\item \code{min}: The \code{\link[=max]{max()}} of \code{x}. +\item \code{max}: The \code{\link[=min]{min()}} of \code{x}. +\item \code{median_range}: The \code{\link[=median]{median()}} and \code{\link[=range_noinf]{range_noinf()}} of \code{x}. +\item \code{cv}: The coefficient of variation of \code{x}, i.e.: (\code{\link[stats:sd]{stats::sd()}} / \code{\link[=mean]{mean()}} * 100). +\item \code{geom_mean}: The geometric mean of \code{x}, i.e.: (\code{exp(mean(log(x)))}). +\item \code{geom_cv}: The geometric coefficient of variation of \code{x}, i.e.: (\code{sqrt(exp(sd(log(x)) ^ 2) - 1) * 100}). } -\item{median_ci}{the CI for the median of \code{x} (from \code{\link[=stat_median_ci]{stat_median_ci()}}).} -\item{quantiles}{two sample quantiles of \code{x} (from \code{\link[stats:quantile]{stats::quantile()}}).} -\item{iqr}{the \code{\link[stats:IQR]{stats::IQR()}} of \code{x}.} -\item{range}{the \code{\link[=range_noinf]{range_noinf()}} of \code{x}.} -\item{min}{the \code{\link[=max]{max()}} of \code{x}.} -\item{max}{the \code{\link[=min]{min()}} of \code{x}.} -\item{median_range}{the \code{\link[=median]{median()}} and \code{\link[=range_noinf]{range_noinf()}} of \code{x}.} -\item{cv}{the coefficient of variation of \code{x}, i.e.: (\code{\link[stats:sd]{stats::sd()}} / \code{\link[=mean]{mean()}} * 100).} -\item{geom_mean}{the geometric mean of \code{x}, i.e.: (\code{exp(mean(log(x)))}).} -\item{geom_cv}{the geometric coefficient of variation of \code{x}, i.e.: (\code{sqrt(exp(sd(log(x)) ^ 2) - 1) * 100}).} } -If \code{x} is of class \code{factor} or converted from \code{character}, returns a list with named \code{numeric} items: -\describe{ -\item{n}{the \code{\link[=length]{length()}} of \code{x}.} -\item{count}{a list with the number of cases for each level of the factor \code{x}.} -\item{count_fraction}{similar to \code{count} but also includes the proportion of cases for each level of the +\itemize{ +\item If \code{x} is of class \code{factor} or converted from \code{character}, returns a \code{list} with named \code{numeric} items: +\itemize{ +\item \code{n}: The \code{\link[=length]{length()}} of \code{x}. +\item \code{count}: A list with the number of cases for each level of the factor \code{x}. +\item \code{count_fraction}: Similar to \code{count} but also includes the proportion of cases for each level of the factor \code{x} relative to the denominator, or \code{NA} if the denominator is zero. } } -If \code{x} is of class \code{logical}, returns a list with named \code{numeric} items: -\describe{ -\item{n}{the \code{\link[=length]{length()}} of \code{x} (possibly after removing \code{NA}s).} -\item{count}{count of \code{TRUE} in \code{x}.} -\item{count_fraction}{count and proportion of \code{TRUE} in \code{x} relative to the denominator, or \code{NA} if the +\itemize{ +\item If \code{x} is of class \code{logical}, returns a \code{list} with named \code{numeric} items: +\itemize{ +\item \code{n}: The \code{\link[=length]{length()}} of \code{x} (possibly after removing \code{NA}s). +\item \code{count}: Count of \code{TRUE} in \code{x}. +\item \code{count_fraction}: Count and proportion of \code{TRUE} in \code{x} relative to the denominator, or \code{NA} if the denominator is zero. Note that \code{NA}s in \code{x} are never counted or leading to \code{NA} here. } } + +\itemize{ +\item \code{a_summary()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{summarize_vars()} 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_summary()} 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]}} -We use the new S3 generic function \code{\link[=s_summary]{s_summary()}} to implement summaries for -different \code{x} objects. This is used as Statistics Function in combination -with the new Analyze Function \code{\link[=summarize_vars]{summarize_vars()}}. +We use the S3 generic function \code{\link[=s_summary]{s_summary()}} to implement summaries for different \code{x} objects. This +is used as a statistics function in combination with the analyze function \code{\link[=summarize_vars]{summarize_vars()}}. } \section{Functions}{ \itemize{ -\item \code{s_summary()}: \code{s_summary} is a S3 generic function to produce -an object description. +\item \code{s_summary()}: S3 generic function to produces a variable summary. -\item \code{s_summary(numeric)}: Method for numeric class. Note that, -if \code{x} is an empty vector, \code{NA} is returned. This is the expected -feature so as to return \code{rcell} content in \code{rtables} when the -intersection of a column and a row delimits an empty data selection. -Also, when the \code{mean} function is applied to an empty vector, \code{NA} will -be returned instead of \code{NaN}, the latter being standard behavior in R. +\item \code{s_summary(numeric)}: Method for \code{numeric} class. -\item \code{s_summary(factor)}: Method for factor class. Note that, -if \code{x} is an empty factor, then still a list is returned for \code{counts} with one element -per factor level. If there are no levels in \code{x}, the function fails. If \code{x} contains \code{NA}, -it is expected that \code{NA} have 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 \code{s_summary(factor)}: Method for \code{factor} class. -\item \code{s_summary(character)}: Method for character class. This makes an automatic +\item \code{s_summary(character)}: Method for \code{character} class. This makes an automatic conversion to factor (with a warning) and then forwards to the method for factors. -\item \code{s_summary(logical)}: Method for logical class. +\item \code{s_summary(logical)}: Method for \code{logical} class. -\item \code{a_summary()}: S3 generic Formatted Analysis function to produce -an object description. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_summary()}: Formatted analysis function which is used as \code{afun} +in \code{summarize_vars()}. -\item \code{a_summary(numeric)}: Formatted Analysis function method for \code{numeric}. +\item \code{a_summary(numeric)}: Formatted analysis function method for \code{numeric} class. -\item \code{a_summary(factor)}: Method for \code{factor}. +\item \code{a_summary(factor)}: Formatted analysis function method for \code{factor} class. -\item \code{a_summary(character)}: Formatted Analysis function method for \code{character}. +\item \code{a_summary(character)}: Formatted analysis function method for \code{character} class. -\item \code{a_summary(logical)}: Formatted Analysis function method for \code{logical}. +\item \code{a_summary(logical)}: Formatted analysis function method for \code{logical} class. -\item \code{summarize_vars()}: Analyze Function to add a descriptive analyze -layer to \code{rtables} pipelines. The analysis is applied to a vector and -return the summary, in \code{rcells}. The ellipsis (\code{...}) conveys arguments to -\code{\link[=s_summary]{s_summary()}}, for instance \code{na.rm = FALSE} if missing data should be -accounted for. When factor variables contains \code{NA}, it is expected that \code{NA} -have been conveyed to \code{na_level} appropriately beforehand with -\code{\link[=df_explicit_na]{df_explicit_na()}}. +\item \code{summarize_vars()}: 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()}}. }} \note{ +\itemize{ +\item If \code{x} is an empty vector, \code{NA} is returned. This is the expected +feature so as to return \code{rcell} content in \code{rtables} when the +intersection of a column and a row delimits an empty data selection. +\item When the \code{mean} function is applied to an empty vector, \code{NA} will +be returned instead of \code{NaN}, the latter being standard behavior in R. +} + +\itemize{ +\item If \code{x} is an empty \code{factor}, a list is still returned for \code{counts} with one element +per factor level. If there are no levels in \code{x}, the function fails. +\item If \code{x} contains \code{NA}, it is expected that \code{NA} have been conveyed to \code{na_level} +appropriately beforehand with \code{\link[=df_explicit_na]{df_explicit_na()}} or \code{\link[=explicit_na]{explicit_na()}}. +} + Automatic conversion of character to factor does not guarantee that the table can be generated correctly. In particular for sparse tables this very likely can fail. It is therefore better to always pre-process the dataset such that factors are manually diff --git a/man/summary_formats.Rd b/man/summary_formats.Rd index 519370b107..02848e6382 100644 --- a/man/summary_formats.Rd +++ b/man/summary_formats.Rd @@ -10,6 +10,9 @@ summary_formats(type = "numeric") \item{type}{(\code{string})\cr choice of a summary data type. Only \code{counts} and \code{numeric} types are currently supported.} } +\value{ +A named \code{vector} of default statistic formats for the given data type. +} \description{ Returns format patterns for descriptive statistics. The format is understood by the \code{rtables}. diff --git a/man/summary_labels.Rd b/man/summary_labels.Rd index 7899e46921..a7cc88596a 100644 --- a/man/summary_labels.Rd +++ b/man/summary_labels.Rd @@ -6,6 +6,9 @@ \usage{ summary_labels() } +\value{ +A named \code{vector} of default statistic labels. +} \description{ Returns labels of descriptive statistics for numeric variables. } diff --git a/man/survival_biomarkers_subgroups.Rd b/man/survival_biomarkers_subgroups.Rd index 13e8362719..e506629c19 100644 --- a/man/survival_biomarkers_subgroups.Rd +++ b/man/survival_biomarkers_subgroups.Rd @@ -17,11 +17,11 @@ tabulate_survival_biomarkers( \item{vars}{(\code{character})\cr the names of statistics to be reported among: \itemize{ -\item \code{n_tot_events}: total number of events per group. -\item \code{n_tot}: total number of observations per group. -\item \code{median}: median survival time. -\item \code{hr}: hazard ratio. -\item \code{ci}: confidence interval of hazard ratio. +\item \code{n_tot_events}: Total number of events per group. +\item \code{n_tot}: Total number of observations per group. +\item \code{median}: Median survival time. +\item \code{hr}: Hazard ratio. +\item \code{ci}: Confidence interval of hazard ratio. \item \code{pval}: p-value of the effect. Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as both \code{hr} and \code{ci} are required. }} @@ -29,6 +29,9 @@ Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as bot \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} } +\value{ +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]}} @@ -41,7 +44,8 @@ the required statistics. The tables are then typically used as input for forest } \section{Functions}{ \itemize{ -\item \code{tabulate_survival_biomarkers()}: table creating function. +\item \code{tabulate_survival_biomarkers()}: Table-creating function which creates a table +summarizing biomarker effects on survival by subgroup. }} \note{ @@ -78,6 +82,7 @@ df <- extract_survival_biomarkers( data = adtte_f ) df + ## Table with default columns. tabulate_survival_biomarkers(df) diff --git a/man/survival_coxph_pairwise.Rd b/man/survival_coxph_pairwise.Rd index fff4d11338..e11a351324 100644 --- a/man/survival_coxph_pairwise.Rd +++ b/man/survival_coxph_pairwise.Rd @@ -86,13 +86,25 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -The statistics are: -\describe{ -\item{pvalue}{p-value to test HR = 1.} -\item{hr}{hazard ratio.} -\item{hr_ci}{confidence interval for hazard ratio.} -\item{n_tot}{total number of observations.} -\item{n_tot_events}{total number of events.} +\itemize{ +\item \code{s_coxph_pairwise()} returns the statistics: +\itemize{ +\item \code{pvalue}: p-value to test HR = 1. +\item \code{hr}: Hazard ratio. +\item \code{hr_ci}: Confidence interval for hazard ratio. +\item \code{n_tot}: Total number of observations. +\item \code{n_tot_events}: Total number of events. +} +} + +\itemize{ +\item \code{a_coxph_pairwise()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{coxph_pairwise()} 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_coxph_pairwise()} to the table layout. } } \description{ @@ -102,13 +114,13 @@ Summarize p-value, HR and CIs from stratified or unstratified CoxPH model. } \section{Functions}{ \itemize{ -\item \code{s_coxph_pairwise()}: Statistics Function which analyzes HR, CIs of HR and p-value with coxph model. +\item \code{s_coxph_pairwise()}: Statistics function which analyzes HR, CIs of HR and p-value +of a coxph model. -\item \code{a_coxph_pairwise()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_coxph_pairwise()}: Formatted analysis function which is used as \code{afun} in \code{coxph_pairwise()}. -\item \code{coxph_pairwise()}: Analyze Function which adds the pairwise coxph analysis -to the input layout. Note that additional formatting arguments can be used here. +\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()}}. }} \examples{ diff --git a/man/survival_duration_subgroups.Rd b/man/survival_duration_subgroups.Rd index 4c69224ba9..a3d95ea168 100644 --- a/man/survival_duration_subgroups.Rd +++ b/man/survival_duration_subgroups.Rd @@ -27,17 +27,19 @@ tabulate_survival_subgroups( \item{df}{(\code{list})\cr of data frames containing all analysis variables. List should be created using \code{\link[=extract_survival_subgroups]{extract_survival_subgroups()}}.} -\item{vars}{(\code{character})\cr the name of statistics to be reported among -\code{n_tot_events} (total number of events per group), -\code{n_events} (number of events per group), -\code{n_tot} (total number of observations per group), -\code{n} (number of observations per group), -\code{median} (median survival time), -\code{hr} (hazard ratio), -\code{ci} (confidence interval of hazard ratio) and -\code{pval} (p value of the effect). +\item{vars}{(\code{character})\cr the name of statistics to be reported among: +\itemize{ +\item \code{n_tot_events}: Total number of events per group. +\item \code{n_events}: Number of events per group. +\item \code{n_tot}: Total number of observations per group. +\item \code{n}: Number of observations per group. +\item \code{median}: Median survival time. +\item \code{hr}: Hazard ratio. +\item \code{ci}: Confidence interval of hazard ratio. +\item \code{pval}: p-value of the effect. Note, one of the statistics \code{n_tot} and \code{n_tot_events}, as well as both \code{hr} and \code{ci} -are required.} +are required. +}} \item{time_unit}{(\code{string})\cr label with unit of median survival time. Default \code{NULL} skips displaying unit.} @@ -50,6 +52,13 @@ levels that belong to it in the character vectors that are elements of the list. \item{label_all}{(\code{string})\cr label for the total population analysis.} } +\value{ +\itemize{ +\item \code{a_survival_subgroups()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +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]}} @@ -61,10 +70,11 @@ the required statistics. Tables typically used as part of forest plot. } \section{Functions}{ \itemize{ -\item \code{a_survival_subgroups()}: Formatted Analysis function used to format the results of -\code{\link[=extract_survival_subgroups]{extract_survival_subgroups()}}. Returns is a list of Formatted Analysis functions with one element per statistic. +\item \code{a_survival_subgroups()}: Formatted analysis function which is used as +\code{afun} in \code{tabulate_survival_subgroups()}. -\item \code{tabulate_survival_subgroups()}: table creating function. +\item \code{tabulate_survival_subgroups()}: Table-creating function which creates a table +summarizing survival by subgroup. }} \examples{ @@ -106,6 +116,7 @@ df <- extract_survival_subgroups( data = adtte_f ) df + # Internal function - a_survival_subgroups \dontrun{ a_survival_subgroups(.formats = list("n" = "xx", "median" = "xx.xx")) diff --git a/man/survival_time.Rd b/man/survival_time.Rd index 5a09ad04c2..ca1c325f1f 100644 --- a/man/survival_time.Rd +++ b/man/survival_time.Rd @@ -60,14 +60,26 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -The statistics are: -\describe{ -\item{median}{median survival time.} -\item{median_ci}{confidence interval for median time.} -\item{quantiles}{survival time for two specified quantiles.} -\item{range_censor}{survival time range for censored observations.} -\item{range_event}{survival time range for observations with events.} -\item{range}{survival time range for all observations.} +\itemize{ +\item \code{s_surv_time()} returns the statistics: +\itemize{ +\item \code{median}: Median survival time. +\item \code{median_ci}: Confidence interval for median time. +\item \code{quantiles}: Survival time for two specified quantiles. +\item \code{range_censor}: Survival time range for censored observations. +\item \code{range_event}: Survival time range for observations with events. +\item \code{range}: Survival time range for all observations. +} +} + +\itemize{ +\item \code{a_surv_time()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{surv_time()} 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_surv_time()} to the table layout. } } \description{ @@ -78,14 +90,12 @@ time range of censored/event patients. } \section{Functions}{ \itemize{ -\item \code{s_surv_time()}: Statistics Function which analyzes survival times. -\code{range_censor} and \code{range_event}. +\item \code{s_surv_time()}: Statistics function which analyzes survival times. -\item \code{a_surv_time()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_surv_time()}: Formatted analysis function which is used as \code{afun} in \code{surv_time()}. -\item \code{surv_time()}: Analyze Function which adds the survival times analysis -to the input layout. Note that additional formatting arguments can be used here. +\item \code{surv_time()}: 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()}}. }} \examples{ diff --git a/man/survival_timepoint.Rd b/man/survival_timepoint.Rd index 5cf1074636..28f70c6f82 100644 --- a/man/survival_timepoint.Rd +++ b/man/survival_timepoint.Rd @@ -108,19 +108,38 @@ avoid warnings from duplicate table names.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -The statistics are: -\describe{ -\item{pt_at_risk}{patients remaining at risk.} -\item{event_free_rate}{event free rate (\%).} -\item{rate_se}{standard error of event free rate.} -\item{rate_ci}{confidence interval for event free rate.} +\itemize{ +\item \code{s_surv_timepoint()} returns the statistics: +\itemize{ +\item \code{pt_at_risk}: Patients remaining at risk. +\item \code{event_free_rate}: Event-free rate (\%). +\item \code{rate_se}: Standard error of event free rate. +\item \code{rate_ci}: Confidence interval for event free rate. +} +} + +\itemize{ +\item \code{a_surv_timepoint()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. } -The statistics are: -\describe{ -\item{rate_diff}{event free rate difference between two groups.} -\item{rate_diff_ci}{confidence interval for the difference.} -\item{ztest_pval}{p-value to test the difference is 0.} +\itemize{ +\item \code{s_surv_timepoint_diff()} returns the statistics: +\itemize{ +\item \code{rate_diff}: Event-free rate difference between two groups. +\item \code{rate_diff_ci}: Confidence interval for the difference. +\item \code{ztest_pval}: p-value to test the difference is 0. +} +} + +\itemize{ +\item \code{a_surv_timepoint_diff()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ +\item \code{surv_timepoint()} 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_surv_timepoint()} and/or \code{s_surv_timepoint_diff()} to the table layout depending on +the value of \code{method}. } } \description{ @@ -130,18 +149,18 @@ Summarize patients' survival rate and difference of survival rates between group } \section{Functions}{ \itemize{ -\item \code{s_surv_timepoint()}: Statistics Function which analyzes survival rate. +\item \code{s_surv_timepoint()}: Statistics function which analyzes survival rate. -\item \code{a_surv_timepoint()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_surv_timepoint()}: Formatted analysis function which is used as \code{afun} in \code{surv_timepoint()} +when \code{method = "surv"}. -\item \code{s_surv_timepoint_diff()}: Statistics Function which analyzes difference between two survival rates. +\item \code{s_surv_timepoint_diff()}: Statistics function which analyzes difference between two survival rates. -\item \code{a_surv_timepoint_diff()}: Formatted Analysis function which can be further customized by calling -\code{\link[rtables:make_afun]{rtables::make_afun()}} on it. It is used as \code{afun} in \code{\link[rtables:analyze]{rtables::analyze()}}. +\item \code{a_surv_timepoint_diff()}: Formatted analysis function which is used as \code{afun} in \code{surv_timepoint()} +when \code{method = "surv_diff"}. -\item \code{surv_timepoint()}: Analyze Function which adds the survival rate analysis to the input layout. -Note that additional formatting arguments can be used here. +\item \code{surv_timepoint()}: 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()}}. }} \examples{ diff --git a/man/tidy.glm.Rd b/man/tidy.glm.Rd index f6c02be5ca..1634d0a76f 100644 --- a/man/tidy.glm.Rd +++ b/man/tidy.glm.Rd @@ -14,6 +14,9 @@ \item{at}{(\code{NULL} or \code{numeric})\cr optional values for the interaction variable. Otherwise the median is used.} } +\value{ +A \code{data.frame} containing the tidied model. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/tidy.step.Rd b/man/tidy.step.Rd index 95f8f6c644..e97ddefd1f 100644 --- a/man/tidy.step.Rd +++ b/man/tidy.step.Rd @@ -13,7 +13,7 @@ } \value{ A \code{tibble} with one row per STEP subgroup. The estimates and CIs are on the HR or OR scale, -respectively. Additional attributes carry meta data also used for plotting. +respectively. Additional attributes carry metadata also used for plotting. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/tidy_coxreg.Rd b/man/tidy_coxreg.Rd index e38d701fd8..2c06f2ba6b 100644 --- a/man/tidy_coxreg.Rd +++ b/man/tidy_coxreg.Rd @@ -18,6 +18,17 @@ \item{...}{additional arguments for the lower level functions.} } +\value{ +\code{\link[=tidy]{tidy()}} returns: +\itemize{ +\item For \code{summary.coxph} objects, a \code{data.frame} with columns: \verb{Pr(>|z|)}, \code{exp(coef)}, \code{exp(-coef)}, \verb{lower .95}, +\verb{upper .95}, \code{level}, and \code{n}. +\item For \code{coxreg.univar} objects, a \code{data.frame} with columns: \code{effect}, \code{term}, \code{term_label}, \code{level}, \code{n}, \code{hr}, +\code{lcl}, \code{ucl}, \code{pval}, and \code{ci}. +\item For \code{coxreg.multivar} objects, a \code{data.frame} with columns: \code{term}, \code{pval}, \code{term_label}, \code{hr}, \code{lcl}, \code{ucl}, +\code{level}, and \code{ci}. +} +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} } @@ -27,11 +38,11 @@ Tidy the \code{\link[survival:coxph]{survival::coxph()}} results into a \code{data.frame} to extract model results. -\item \code{tidy(coxreg.univar)}: Custom tidy method for a Univariate Cox Regression +\item \code{tidy(coxreg.univar)}: Custom tidy method for a univariate Cox regression. Tidy up the result of a Cox regression model fitted by \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}}. -\item \code{tidy(coxreg.multivar)}: Custom tidy method for a Multi-variable Cox Regression +\item \code{tidy(coxreg.multivar)}: Custom tidy method for a multivariate Cox regression. Tidy up the result of a Cox regression model fitted by \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}}. diff --git a/man/to_n.Rd b/man/to_n.Rd index 50017e82bc..361f768f6e 100644 --- a/man/to_n.Rd +++ b/man/to_n.Rd @@ -12,12 +12,14 @@ to_n(x, n) \item{n}{(\code{count})\cr how many entries we need.} } \value{ -Just input \code{x} if it has the required length already or is \code{NULL}, +\code{x} if it has the required length already or is \code{NULL}, otherwise if it is scalar the replicated version of it with \code{n} entries. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Replicate entries of a vector if required. Note that this will fail if \code{x} -is not of length \code{n} or is not a scalar. +Replicate entries of a vector if required. +} +\note{ +This function will fail if \code{x} is not of length \code{n} and/or is not a scalar. } diff --git a/man/to_string_matrix.Rd b/man/to_string_matrix.Rd index 5cbb4d112e..4e95e21853 100644 --- a/man/to_string_matrix.Rd +++ b/man/to_string_matrix.Rd @@ -16,7 +16,7 @@ spaces?} into the expected variable instead of copying it too manually.} } \value{ -A matrix of strings +A \code{matrix} of \code{string}s. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/univariate.Rd b/man/univariate.Rd index 6285bf2826..430382f2c6 100644 --- a/man/univariate.Rd +++ b/man/univariate.Rd @@ -7,7 +7,10 @@ univariate(x) } \arguments{ -\item{x}{A vector of variable name separated by comas.} +\item{x}{A vector of variable name separated by commas.} +} +\value{ +When used within a model formula, produces univariate models for each variable provided. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/man/unlist_and_blank_na.Rd b/man/unlist_and_blank_na.Rd index 30c8acd46d..3b58ff64e7 100644 --- a/man/unlist_and_blank_na.Rd +++ b/man/unlist_and_blank_na.Rd @@ -10,8 +10,8 @@ unlist_and_blank_na(x) \item{x}{(\code{vector})\cr input for a cell.} } \value{ -Either empty character vector if all entries in \code{x} are missing (\code{NA}), or otherwise -the unlisted version of \code{x} +An empty \code{character} vector if all entries in \code{x} are missing (\code{NA}), otherwise +the unlisted version of \code{x}. } \description{ Helper function to use in tabulating model results. diff --git a/man/update_weights_strat_wilson.Rd b/man/update_weights_strat_wilson.Rd index cbbbfddc34..29656637d0 100644 --- a/man/update_weights_strat_wilson.Rd +++ b/man/update_weights_strat_wilson.Rd @@ -30,6 +30,9 @@ be optimized in the future if we need to estimate better initial weights.} \item{tol}{(\code{number})\cr tolerance threshold for convergence.} } +\value{ +A \code{list} of 3 elements: \code{n_it}, \code{weights}, and \code{diff_v}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} diff --git a/tests/testthat/test-coxreg.R b/tests/testthat/test-coxreg.R index dbe66231ba..2136b2b095 100644 --- a/tests/testthat/test-coxreg.R +++ b/tests/testthat/test-coxreg.R @@ -539,7 +539,7 @@ testthat::test_that("fit_coxreg_multivar works correctly also without treatment # tidy.coxreg.multivar ---- -testthat::test_that("tidy.coxreg.multivar method tidies up the multi-variable Cox regression model", { +testthat::test_that("tidy.coxreg.multivar method tidies up the multivariate Cox regression model", { set.seed(1, kind = "Mersenne-Twister") dta_bladder <- dta_bladder_raw diff --git a/tests/testthat/test-summarize_coxreg.R b/tests/testthat/test-summarize_coxreg.R index be0f60f80e..30bccb5dff 100644 --- a/tests/testthat/test-summarize_coxreg.R +++ b/tests/testthat/test-summarize_coxreg.R @@ -176,7 +176,7 @@ testthat::test_that("summarize_coxreg works with numeric covariate without treat testthat::expect_snapshot(res) }) -testthat::test_that("summarize_coxreg adds the multivariable Cox regression layer to rtables", { +testthat::test_that("summarize_coxreg adds the multivariate Cox regression layer to rtables", { variables <- list(time = "TIME", event = "STATUS", arm = "ARMCD", covariates = c("AGE", "COVAR1", "COVAR2")) result <- basic_table() %>%