From bbe29f0942d186615fbfd433cf23bf10f7655b85 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 31 Mar 2023 16:15:31 -0400 Subject: [PATCH 01/20] Files from abnormal to count --- R/abnormal.R | 37 ++++----- R/abnormal_by_baseline.R | 43 ++++++----- R/abnormal_by_marked.R | 39 +++++----- R/abnormal_by_worst_grade.R | 32 ++++---- R/abnormal_by_worst_grade_worsen.R | 37 +++++---- R/analyze_vars_in_cols.R | 18 ++--- R/combination_function.R | 2 + R/compare_variables.R | 107 ++++++++++++-------------- R/count_cumulative.R | 30 ++++---- R/count_missed_doses.R | 24 +++--- R/count_occurrences.R | 30 +++++--- R/count_occurrences_by_grade.R | 33 +++++--- R/count_patients_events_in_cols.R | 20 +++-- R/count_patients_with_event.R | 49 +++++++----- R/count_values.R | 37 +++++---- man/abnormal.Rd | 42 +++++----- man/abnormal_by_baseline.Rd | 39 ++++++---- man/abnormal_by_marked.Rd | 41 +++++----- man/abnormal_by_worst_grade.Rd | 32 ++++---- man/abnormal_by_worst_grade_worsen.Rd | 28 ++++--- man/analyze_vars_in_cols.Rd | 5 +- man/combination_function.Rd | 3 + man/compare_variables.Rd | 92 +++++++++------------- man/count_cumulative.Rd | 24 +++--- man/count_missed_doses.Rd | 23 +++--- man/count_occurrences.Rd | 18 +++-- man/count_occurrences_by_grade.Rd | 30 +++++--- man/count_patients_events_in_cols.Rd | 11 ++- man/count_patients_with_event.Rd | 45 ++++++----- man/count_values_funs.Rd | 36 +++++---- man/create_afun_compare.Rd | 10 ++- man/d_count_abnormal_by_baseline.Rd | 3 + man/d_count_cumulative.Rd | 7 +- man/h_adlb_worsen.Rd | 2 +- man/h_append_grade_groups.Rd | 16 +++- man/h_worsen_counter.Rd | 2 +- 36 files changed, 585 insertions(+), 462 deletions(-) diff --git a/R/abnormal.R b/R/abnormal.R index 17c31badec..81c59d99c7 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -10,16 +10,25 @@ #' \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. +#' @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. #' #' @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"))`. +#' +#' @return +#' * `s_count_abnormal()` returns the statistic `fraction` which is a vector with `num` and `denom` counts of patients. +#' * `a_count_abnormal()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. #' #' @name abnormal #' @include formats.R @@ -29,9 +38,6 @@ 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. -#' #' @examples #' library(dplyr) #' @@ -105,10 +111,7 @@ 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()]. -#' -#' @return [a_count_abnormal()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @describeIn abnormal Formatted analysis function which is used as `afun` in `count_abnormal()`. #' #' @examples #' # Internal function - a_count_abnormal @@ -124,10 +127,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @export #' @examples #' # Layout creating function. diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index 7afdd6e0d9..e507fd3377 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 ` @@ -19,12 +16,25 @@ #' * `denom`: the number of patients with at least one valid measurement post-baseline #' * `num`: the number of patients in `denom` who also have at least one abnormality post-baseline #' +#' @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()]. +#' #' @inheritParams argument_convention #' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`. #' @seealso Relevant description function [d_count_abnormal_by_baseline()]. #' +#' @return +#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labelled elements: +#' `not_abnormal`, `abnormal`, and `total`. Each element contains a vector with `num` and `denom` patient counts. +#' * `a_count_abnormal_by_baseline()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' +#' #' @name abnormal_by_baseline -#' @include formats.R NULL #' Description Function for [s_count_abnormal_by_baseline()] @@ -34,6 +44,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 +63,10 @@ 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 `""`. #' #' @examples #' df <- data.frame( @@ -138,10 +145,8 @@ 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()]. -#' -#' @return [a_count_abnormal_by_baseline()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @describeIn abnormal_by_baseline Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_baseline()`. #' #' @examples #' # Internal function - a_count_abnormal_by_baseline @@ -158,10 +163,8 @@ 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). -#' -#' @inheritParams argument_convention +#' @describeIn abnormal_by_baseline Layout-creating function which can which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @examples #' # Layout creating function. diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index f888e61a8f..59b74314e3 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -3,32 +3,35 @@ #' @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 +#' 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. +#' 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. #' +#' @return +#' * `s_count_abnormal_by_marked()` returns statistic `count_fraction` with `Single, not last`, +#' `Last or replicated`, and `Any` results. +#' * `a_count_abnormal_by_marked()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @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. -#' -#' @return [s_count_abnormal_by_marked()] the single statistic `count_fraction` -#' with `Single, not last`, `Last or replicated` and `Any` results. +#' @describeIn abnormal_by_marked Statistics function for patients with marked lab abnormalities. #' #' @examples #' library(dplyr) @@ -133,10 +136,8 @@ 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()]. -#' -#' @return [a_count_abnormal_by_marked()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @describeIn abnormal_by_marked Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_marked()`. #' #' @examples #' # Internal function - a_count_abnormal_by_marked @@ -157,8 +158,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @examples #' map <- unique( diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 27aa18dcf1..8d47e14eee 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, @@ -18,19 +18,23 @@ #' 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. +#' +#' @note Prior to tabulation, `df` must filtered to include only post-baseline records with worst grade flags. #' #' @inheritParams argument_convention #' +#' @return +#' * `s_count_abnormal_by_worst_grade()` returns the single statistic `count_fraction` with grades 1 to 4 and +#' "Any" results. +#' * `a_count_abnormal_by_worst_grade()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @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. -#' -#' @return [s_count_abnormal_by_worst_grade()] the single statistic `count_fraction` with grade 1 to 4 -#' and "Any" results. +#' @describeIn abnormal_by_worst_grade Statistics function which counts patients by worst grade. #' #' @examples #' library(dplyr) @@ -132,10 +136,8 @@ 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()]. -#' -#' @return [a_count_abnormal_by_worst_grade()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @describeIn abnormal_by_worst_grade Formatted analysis function which is used as `afun` +#' in `count_abnormal_by_worst_grade()`. #' #' @examples #' # Internal function - a_count_abnormal_by_worst_grade @@ -152,8 +154,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @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..fe2ad5d8e0 100644 --- a/R/abnormal_by_worst_grade_worsen.R +++ b/R/abnormal_by_worst_grade_worsen.R @@ -6,7 +6,17 @@ #' #' @inheritParams argument_convention #' -#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()]. +#' @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". +#' * `a_count_abnormal_lab_worsen_by_baseline()` returns the corresponding list with +#' formatted [rtables::CellValue()]. +#' * `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. +#' +#' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()] #' #' @name abnormal_by_worst_grade_worsen NULL @@ -26,13 +36,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 +168,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 +270,13 @@ 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". #' #' @examples #' library(dplyr) @@ -323,10 +332,8 @@ s_count_abnormal_lab_worsen_by_baseline <- function(df, # nolint } -#' @describeIn abnormal_by_worst_grade_worsen -#' -#' @return [a_count_abnormal_lab_worsen_by_baseline()] returns the corresponding list with -#' formatted [rtables::CellValue()]. +#' @describeIn abnormal_by_worst_grade_worsen Formatted analysis function which is used as `afun` +#' in `count_abnormal_lab_worsen_by_baseline()`. #' #' @examples #' # Internal function - a_count_abnormal_lab_worsen_by_baseline @@ -345,8 +352,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @examples #' basic_table() %>% diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 5427846ae4..9a6575dd47 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -5,19 +5,17 @@ #' 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. -#' #' @inheritParams argument_convention #' @inheritParams rtables::analyze_colvars #' -#' @seealso [summarize_vars], [`rtables::analyze_colvars()`]. +#' @seealso [summarize_vars], [rtables::analyze_colvars()]. +#' +#' @name analyze_vars_in_cols +NULL + +#' @describeIn analyze_vars_in_cols 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()]. #' -#' @export #' @examples #' library(dplyr) #' @@ -77,6 +75,8 @@ NULL #' ) #' result <- build_table(lyt, df = adpp) #' result +#' +#' @export analyze_vars_in_cols <- function(lyt, vars, ..., 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..4622d818c9 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -1,25 +1,40 @@ -#' @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 +#' @return +#' * `s_compare()` returns output of [s_summary()] and comparisons versus the reference group in the form of p-values. +#' * `a_compare()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' +#' @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 statistics function to produce a comparison summary. #' #' @export #' @@ -30,11 +45,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 +81,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 +140,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 +189,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 +243,8 @@ 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()`. #' #' @export #' @@ -259,7 +256,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 +289,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 +310,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 +329,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 +349,9 @@ 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. #' #' @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 +359,12 @@ 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()]. +#' +#' @return Combined formatted analysis function for use in [compare_vars()]. +#' #' @export #' @inheritParams argument_convention -#' @seealso [compare_variables] +#' @seealso [compare_vars()] #' #' @examples #' # `create_afun_compare()` to create combined `afun` @@ -460,15 +461,9 @@ 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 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()`. #' #' @export diff --git a/R/count_cumulative.R b/R/count_cumulative.R index ccb22309bd..c2d24bd098 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -5,6 +5,14 @@ #' 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. #' +#' @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. +#' * `a_count_cumulative()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @seealso Relevant helper function [h_count_cumulative()], and descriptive function [d_count_cumulative()] #' #' @name count_cumulative @@ -73,11 +81,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 +95,10 @@ 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. #' #' @examples #' # Internal function - s_count_cumulative @@ -123,10 +129,8 @@ 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()]. -#' -#' @return [a_count_cumulative()] returns the corresponding list with formatted [rtables::CellValue()]. +#' @describeIn count_cumulative Formatted analysis function which is used as `afun` +#' in `count_cumulative()`. #' #' @examples #' # Internal function - a_count_cumulative @@ -143,10 +147,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @export diff --git a/R/count_missed_doses.R b/R/count_missed_doses.R index 70b2d31fc1..d5fee9edf5 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -5,6 +5,14 @@ #' These are specific functions to count patients with missed doses. The difference to [count_cumulative()] is #' mainly the special labels. #' +#' @return +#' * `s_count_nonmissing()` returns the statistic `n` which is the count of non-missing values in `x`. +#' * `s_count_missed_doses()` returns the statistics `n` and `count_fraction` with one element for each threshold. +#' * `a_count_missed_doses()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @seealso Relevant description function [d_count_missed_doses()]. #' #' @name count_missed_doses @@ -12,7 +20,7 @@ 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`. +#' #' @examples #' set.seed(1) #' x <- c(sample(1:10, 10), NA) @@ -40,12 +48,9 @@ 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. #' #' @examples #' # Internal function - s_count_missed_doses @@ -72,7 +77,8 @@ 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()`. #' #' @examples #' # Internal function - a_count_missed_doses @@ -89,10 +95,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @inheritParams s_count_cumulative #' @export #' @examples diff --git a/R/count_occurrences.R b/R/count_occurrences.R index 74ae8ff8b5..97c4d1e705 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -1,5 +1,7 @@ #' 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 @@ -8,9 +10,20 @@ #' 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. #' -#' @description `r lifecycle::badge("stable")` #' @inheritParams argument_convention #' +#' @return +#' * `s_count_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.} +#' } +#' * `a_count_occurrences()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @name count_occurrences #' NULL @@ -21,12 +34,6 @@ 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.} -#' } #' #' @examples #' df <- data.frame( @@ -102,8 +109,8 @@ 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 #' #' @examples @@ -117,17 +124,18 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @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..acf76e9a91 100644 --- a/R/count_occurrences_by_grade.R +++ b/R/count_occurrences_by_grade.R @@ -11,6 +11,16 @@ #' @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. #' +#' * `s_count_occurrences_by_grade()` returns a list of counts and fractions with one element per grade level or +#' grade level grouping. +#' * `a_count_occurrences_by_grade()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' * `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. +#' #' @seealso Relevant helper function [h_append_grade_groups()]. #' #' @name count_occurrences_by_grade @@ -30,6 +40,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 +121,8 @@ 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. #' #' @examples #' library(dplyr) @@ -190,8 +201,8 @@ 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()`. #' @export #' #' @examples @@ -205,18 +216,18 @@ 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 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. #' @export #' @examples -#' #' # Layout creating function with custom format. #' basic_table() %>% #' split_cols_by("ARM") %>% @@ -242,6 +253,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 +283,10 @@ 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 which can take content function arguments +#' and additional format arguments. This function is a wrapper for [rtables::summarize_row_groups()]. #' @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..9ccbd4a748 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -5,6 +5,16 @@ #' Counting the number of unique patients and the total number of all and specific events #' when a column table layout is required. #' +#' @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`, +#' i.e. events, fulfilling the filter condition. +#' * `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. +#' #' @name count_patients_events_in_cols #' NULL @@ -21,12 +31,6 @@ 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: -#' - `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`, -#' i.e. events, fulfilling the filter condition. -#' #' @examples #' # `s_count_patients_and_multiple_events()` #' df <- data.frame( @@ -106,8 +110,8 @@ 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 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. diff --git a/R/count_patients_with_event.R b/R/count_patients_with_event.R index 133e64e8b7..0e3390b279 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -1,16 +1,30 @@ #' Count the Number of Patients with a Particular Event #' +#' @description `r lifecycle::badge("stable")` +#' #' The primary analysis variable `.var` denotes the unique patient identifier. #' +#' @return +#' * `s_count_patients_with_event()` returns the count and fraction of unique identifiers with the defined event. +#' * `a_count_patients_with_event()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' +#' * `s_count_patients_with_flags()` returns the count and the fraction of unique identifiers with each particular +#' flag. Returns a list of `n`s, `count`s, `count_fraction`s, and `n_blq`s with one element per flag. +#' * `a_count_patients_with_flags()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @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,9 +34,6 @@ 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. -#' #' @export #' #' @examples @@ -75,8 +86,8 @@ 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()`. #' @export #' #' @examples @@ -94,8 +105,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' @@ -158,9 +169,9 @@ 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` @@ -226,8 +237,8 @@ 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()`. #' @export #' #' @examples @@ -252,8 +263,8 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @inheritParams argument_convention #' diff --git a/R/count_values.R b/R/count_values.R index 72e04ef348..f7deba908b 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -4,15 +4,27 @@ #' #' We can count the occurrence of specific values in a variable of interest. #' +#' @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. +#' +#' @return +#' * `s_count_values()` returns output of [s_summary()] for specified values of a non-numeric variable. +#' * `a_count_values()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @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 statistics 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. #' #' @export #' @@ -25,7 +37,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 +61,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 +76,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 +90,8 @@ 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()`. #' @export #' #' @examples @@ -91,14 +102,10 @@ 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 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. -#' #' @export #' #' @examples diff --git a/man/abnormal.Rd b/man/abnormal.Rd index bc7007784f..3601387ad0 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,13 @@ 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. - -\code{\link[=a_count_abnormal]{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{s_count_abnormal()} returns the statistic \code{fraction} which is a vector with \code{num} and \code{denom} counts of patients. +\item \code{a_count_abnormal()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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]}} @@ -83,26 +84,27 @@ numerator and denominator as follows: \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 \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 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..dcf76ca211 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,20 @@ 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 labelled elements: +\code{not_abnormal}, \code{abnormal}, and \code{total}. Each element contains a vector with \code{num} and \code{denom} patient counts. +\item \code{a_count_abnormal_by_baseline()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +100,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 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..6fdc2b38c9 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -60,42 +60,43 @@ 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. - -\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{s_count_abnormal_by_marked()} returns statistic \code{count_fraction} with \verb{Single, not last}, +\verb{Last or replicated}, and \code{Any} results. +\item \code{a_count_abnormal_by_marked()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +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. \item For \code{Any}: Numerator is the number of patients with either single or 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. + +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 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/abnormal_by_worst_grade.Rd b/man/abnormal_by_worst_grade.Rd index c547456669..4864cdffde 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -55,16 +55,20 @@ 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. - -\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{s_count_abnormal_by_worst_grade()} returns the single statistic \code{count_fraction} with grades 1 to 4 and +"Any" results. +\item \code{a_count_abnormal_by_worst_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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, @@ -82,22 +86,22 @@ lab grade variable \code{ATOXGR}, derive the following two variables: 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 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 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..a75704113b 100644 --- a/man/abnormal_by_worst_grade_worsen.Rd +++ b/man/abnormal_by_worst_grade_worsen.Rd @@ -59,12 +59,16 @@ 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". - -\code{\link[=a_count_abnormal_lab_worsen_by_baseline]{a_count_abnormal_lab_worsen_by_baseline()}} returns the corresponding list with +\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". +\item \code{a_count_abnormal_lab_worsen_by_baseline()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +77,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 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 +148,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/analyze_vars_in_cols.Rd b/man/analyze_vars_in_cols.Rd index 2337ba3076..6c6ae1c75c 100644 --- a/man/analyze_vars_in_cols.Rd +++ b/man/analyze_vars_in_cols.Rd @@ -47,8 +47,8 @@ the relevant statistic is on the columns instead of on the rows. } \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. +\item \code{analyze_vars_in_cols()}: 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()}}. }} \examples{ @@ -110,6 +110,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/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/compare_variables.Rd b/man/compare_variables.Rd index 51722690ee..4c5477405a 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,64 @@ 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. -} - -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. -} - -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{s_compare()} returns output of \code{\link[=s_summary]{s_summary()}} and comparisons versus the reference group in the form of p-values. +\item \code{a_compare()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 statistics 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 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 +296,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/count_cumulative.Rd b/man/count_cumulative.Rd index 75dae47021..a0c3bd3647 100644 --- a/man/count_cumulative.Rd +++ b/man/count_cumulative.Rd @@ -71,10 +71,14 @@ 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. - -\code{\link[=a_count_cumulative]{a_count_cumulative()}} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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. +\item \code{a_count_cumulative()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +88,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 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_missed_doses.Rd b/man/count_missed_doses.Rd index 3b24a3f407..67440bda01 100644 --- a/man/count_missed_doses.Rd +++ b/man/count_missed_doses.Rd @@ -56,10 +56,14 @@ 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}. - -\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{s_count_nonmissing()} returns the statistic \code{n} which is the count of non-missing values in \code{x}. +\item \code{s_count_missed_doses()} returns the statistics \code{n} and \code{count_fraction} with one element for each threshold. +\item \code{a_count_missed_doses()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +75,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 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 486de0ceae..d0970884a8 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -83,17 +83,22 @@ to avoid warnings from \code{rtables}.} \item{.indent_mods}{(named \code{integer})\cr indent modifiers for the labels.} } \value{ -A list with: +\itemize{ +\item \code{s_count_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.} } +\item \code{a_count_occurrences()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 @@ -107,10 +112,11 @@ calls. Use \code{drop = FALSE} if you would like to show all occurrences. \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 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_by_grade.Rd b/man/count_occurrences_by_grade.Rd index fcb497d866..1286de1142 100644 --- a/man/count_occurrences_by_grade.Rd +++ b/man/count_occurrences_by_grade.Rd @@ -64,7 +64,18 @@ by a statistics function.} \item{grade_groups}{(named \code{list} of \code{character})\cr containing groupings of grades.} \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.} +in the the output list; in this case only the grade groups names will be included in the output. +\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. +\item \code{a_count_occurrences_by_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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. +\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. +}} \item{labelstr}{(\code{character})\cr label of the level of the parent split currently being summarized (must be present as second argument in Content Row Functions).} @@ -97,18 +108,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 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 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..4dbee888e8 100644 --- a/man/count_patients_events_in_cols.Rd +++ b/man/count_patients_events_in_cols.Rd @@ -56,13 +56,18 @@ 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}. \item one element with the same name as in \code{filters_list}: number of rows in \code{df}, i.e. events, fulfilling the filter condition. } +\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]}} @@ -75,8 +80,8 @@ when a column table layout is required. \item \code{s_count_patients_and_multiple_events()}: Statistics function which counts numbers of patients and multiple events defined by filters. -\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 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 a66b7742a8..98ad4be93b 100644 --- a/man/count_patients_with_event.Rd +++ b/man/count_patients_with_event.Rd @@ -119,37 +119,44 @@ by a statistics function.} \item{show_labels}{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. +\item \code{a_count_patients_with_event()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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. +\item \code{s_count_patients_with_flags()} returns the count and the fraction of unique identifiers with each particular +flag. Returns a list of \code{n}s, \code{count}s, \code{count_fraction}s, and \code{n_blq}s with one element per flag. +\item \code{a_count_patients_with_flags()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 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 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..fa6962f1af 100644 --- a/man/count_values_funs.Rd +++ b/man/count_values_funs.Rd @@ -83,7 +83,13 @@ 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. +\item \code{a_count_values()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +98,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 statistics 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 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/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/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/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_append_grade_groups.Rd b/man/h_append_grade_groups.Rd index 705f3cc279..09ef9cafc9 100644 --- a/man/h_append_grade_groups.Rd +++ b/man/h_append_grade_groups.Rd @@ -13,7 +13,21 @@ h_append_grade_groups(grade_groups, refs, remove_single = TRUE) 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.} +in the the output list; in this case only the grade groups names will be included in the output. +\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. +\item \code{a_count_occurrences_by_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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. +\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. +}} +} +\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_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". } From dd955fa70f25a617a6c28ae496d79ad5cd5ce0d3 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 31 Mar 2023 17:58:27 -0400 Subject: [PATCH 02/20] Cox reg. functions --- R/cox_regression.R | 65 ++++++++++++++++++++++++------------- R/cox_regression_inter.R | 43 ++++++++++++++---------- R/coxph.R | 22 ++++++++----- R/h_cox_regression.R | 37 +++++++++------------ man/cox_regression.Rd | 17 +++++++--- man/cox_regression_inter.Rd | 35 ++++++++++++-------- man/estimate_coef.Rd | 10 +++--- man/fit_coxreg.Rd | 30 +++++++++-------- man/h_cox_regression.Rd | 33 +++++++++---------- man/muffled_car_anova.Rd | 3 ++ man/pairwise.Rd | 3 ++ man/s_cox_multivariate.Rd | 3 ++ man/tidy_coxreg.Rd | 15 +++++++-- man/univariate.Rd | 5 ++- 14 files changed, 194 insertions(+), 127 deletions(-) diff --git a/R/cox_regression.R b/R/cox_regression.R index c2169aaecc..d2c0295b1c 100644 --- a/R/cox_regression.R +++ b/R/cox_regression.R @@ -17,6 +17,14 @@ #' `summarize_coxreg` are not yet accepted (`.stats`, `.indent_mod`, `.formats`, #' `.labels`). #' @inheritParams argument_convention +#' +#' @return +#' * `s_coxreg()` returns a formatted list with the specified statistic, with each element corresponding +#' to one term in the given model. +#' * `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 rows for a formatted +#' Cox regression summary table containing the statistics from `s_coxreg()` to the table layout. +#' #' @seealso [fit_coxreg] for relevant fitting functions, [h_cox_regression] for relevant #' helper functions, and [tidy_coxreg] for custom tidy methods. #' @@ -52,9 +60,8 @@ #' ) 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 to transform the tabulated results from [fit_coxreg_univar()] +#' and [fit_coxreg_multivar()] into a list. #' @export #' #' @examples @@ -120,7 +127,8 @@ s_coxreg <- function(df, .var) { ) } -#' @describeIn cox_regression layout creating function. +#' @describeIn cox_regression Layout-creating function which can which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze_colvars()]. #' @inheritParams argument_convention #' @inheritParams control_coxreg #' @param multivar (`flag`)\cr if `TRUE`, the multi-variable Cox regression will run @@ -258,6 +266,15 @@ control_coxreg <- function(pval_method = c("wald", "likelihood"), #' #' @seealso [cox_regression] #' +#' @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`. +#' #' @name tidy_coxreg NULL @@ -266,6 +283,7 @@ NULL #' Tidy the [survival::coxph()] results into a `data.frame` to extract model results. #' #' @inheritParams argument_convention +#' #' @method tidy summary.coxph #' @export #' @@ -311,7 +329,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()`]. #' @@ -400,7 +418,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 multi-variable Cox regression. #' #' Tidy up the result of a Cox regression model fitted by [`fit_coxreg_multivar()`]. #' @@ -502,15 +520,15 @@ 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 @@ -601,14 +619,13 @@ fit_coxreg_univar <- function(variables, #' @describeIn fit_coxreg Fit a multi-variable 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 @@ -677,6 +694,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..724a642493 100644 --- a/R/cox_regression_inter.R +++ b/R/cox_regression_inter.R @@ -16,6 +16,18 @@ #' [control_coxreg()]. #' @param ... see methods. #' +#' @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`. +#' * `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. +#' * `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. +#' #' @name cox_regression_inter #' #' @examples @@ -49,6 +61,9 @@ #' col = c("blue1", "blue2", "blue3", "blue4", "red1", "red2", "red3", "red4") #' ) #' +NULL + +#' @describeIn cox_regression_inter S3 generic helper function to determine interaction effect. #' @export h_coxreg_inter_effect <- function(x, effect, @@ -61,8 +76,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 +128,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 +164,8 @@ 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. #' #' @export #' @@ -207,7 +221,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,15 +242,6 @@ 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.} -#' } -#' #' @examples #' mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder) #' result <- h_coxreg_inter_estimations( @@ -248,8 +253,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..d188dcdccd 100644 --- a/R/coxph.R +++ b/R/coxph.R @@ -7,6 +7,8 @@ #' #' @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: #' * A model including only levels A and B, and effect of A estimated in reference to B. @@ -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 @@ -343,6 +346,9 @@ 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/h_cox_regression.R b/R/h_cox_regression.R index 307e747a50..7017b335eb 100644 --- a/R/h_cox_regression.R +++ b/R/h_cox_regression.R @@ -5,23 +5,26 @@ #' Helper functions used in [fit_coxreg_univar()] and [fit_coxreg_multivar()]. #' #' @inheritParams argument_convention +#' +#' @return +#' * `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()]). +#' * `h_coxreg_univar_extract()` returns a `data.frame` with variables `effect`, `term`, `term_label`, `level`, +#' `n`, `hr`, `lcl`, `ucl`, and `pval`. +#' * `h_coxreg_multivar_extract()` returns a `data.frame` with variables `pval`, `hr`, `lcl`, `ucl`, `level`, +#' `n`, `term`, and `term_label`. +#' #' @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()]). -#' #' @examples #' # `h_coxreg_univar_formulas` #' @@ -107,18 +110,12 @@ 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 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. #' #' @inheritParams argument_convention #' -#' @return -#' The function `h_coxreg_univar_formulas` returns a `character` vector coercible -#' into formulas (e.g [stats::as.formula()]). -#' #' @export #' #' @examples @@ -235,10 +232,8 @@ 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 multi-variable Cox regressions. Utility function to help +#' tabulate the result of a multi-variable Cox regression model for a treatment/covariate variable. #' #' @inheritParams argument_convention #' @inheritParams h_coxreg_univar_extract diff --git a/man/cox_regression.Rd b/man/cox_regression.Rd index 4accedfd91..0fbc9829e5 100644 --- a/man/cox_regression.Rd +++ b/man/cox_regression.Rd @@ -40,6 +40,15 @@ of the treatment arm effect estimate across models.} \code{pval_inter} (the p.value of the interaction effect between the treatment and the covariate).} } +\value{ +\itemize{ +\item \code{s_coxreg()} returns a formatted list with the specified statistic, with each element corresponding +to one term in the given model. +\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 rows for a formatted +Cox regression summary table containing the statistics from \code{s_coxreg()} 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]}} @@ -56,11 +65,11 @@ 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 to transform the tabulated results from \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} +and \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} into a list. -\item \code{summarize_coxreg()}: layout creating function. +\item \code{summarize_coxreg()}: Layout-creating function which can which can take statistics +function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. }} \note{ diff --git a/man/cox_regression_inter.Rd b/man/cox_regression_inter.Rd index 9024af3d7d..d92c1ff05f 100644 --- a/man/cox_regression_inter.Rd +++ b/man/cox_regression_inter.Rd @@ -56,13 +56,19 @@ 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}. +\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. +\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 +95,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/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/fit_coxreg.Rd b/man/fit_coxreg.Rd index 5ca864035b..3d6935cb14 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{ diff --git a/man/h_cox_regression.Rd b/man/h_cox_regression.Rd index 076358c792..265fd94122 100644 --- a/man/h_cox_regression.Rd +++ b/man/h_cox_regression.Rd @@ -39,11 +39,14 @@ interaction can be used so that this needs to be \code{FALSE}.} 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()}}). - -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()}}). +\item \code{h_coxreg_univar_formulas()} returns a \code{character} vector coercible into formulas (e.g \code{\link[stats:formula]{stats::as.formula()}}). +\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}. +\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 +55,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 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_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 multi-variable Cox regressions. Utility function to help +tabulate the result of a multi-variable Cox regression model for a treatment/covariate variable. }} \examples{ 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/pairwise.Rd b/man/pairwise.Rd index 57ef9a8122..e10903d660 100644 --- a/man/pairwise.Rd +++ b/man/pairwise.Rd @@ -9,6 +9,9 @@ pairwise(x) \arguments{ \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/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/tidy_coxreg.Rd b/man/tidy_coxreg.Rd index e38d701fd8..b0bb60003c 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 multi-variable 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/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]}} From 05ef358b8c5de74306ba74c06fbd895f03dddc83 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 31 Mar 2023 17:58:34 -0400 Subject: [PATCH 03/20] Fix lists --- R/count_cumulative.R | 8 +++----- R/count_occurrences.R | 8 +++----- man/count_occurrences.Rd | 8 ++++---- man/h_count_cumulative.Rd | 7 +++---- 4 files changed, 13 insertions(+), 18 deletions(-) diff --git a/R/count_cumulative.R b/R/count_cumulative.R index c2d24bd098..9fb7962abf 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -31,12 +31,10 @@ NULL #' 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 diff --git a/R/count_occurrences.R b/R/count_occurrences.R index 97c4d1e705..2929e5268d 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -14,11 +14,9 @@ #' #' @return #' * `s_count_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.} -#' } +#' * `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. #' * `a_count_occurrences()` returns the corresponding list with formatted [rtables::CellValue()]. #' * `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 diff --git a/man/count_occurrences.Rd b/man/count_occurrences.Rd index d0970884a8..6b94c5f9a0 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -85,10 +85,10 @@ to avoid warnings from \code{rtables}.} \value{ \itemize{ \item \code{s_count_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.} +\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. } \item \code{a_count_occurrences()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. \item \code{count_occurrences()} returns a layout object suitable for passing to further layouting functions, 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{ From 61f980ca9833de1befcf7c987f1be26917921844 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 31 Mar 2023 18:20:46 -0400 Subject: [PATCH 04/20] d* files --- R/d_pkparam.R | 2 +- R/decorate_grob.R | 14 ++++++-------- R/desctools_binom_diff.R | 32 ++++++++++++++++---------------- R/df_explicit_na.R | 2 +- man/d_pkparam.Rd | 2 +- man/decorate_grob.Rd | 8 +------- man/decorate_grob_factory.Rd | 2 +- man/decorate_grob_set.Rd | 3 +++ man/desctools_binom.Rd | 27 +++++++++++---------------- man/df_explicit_na.Rd | 2 +- man/split_text_grob.Rd | 3 +++ 11 files changed, 45 insertions(+), 52 deletions(-) diff --git a/R/d_pkparam.R b/R/d_pkparam.R index 7ba7c9336b..f76e1136c2 100644 --- a/R/d_pkparam.R +++ b/R/d_pkparam.R @@ -2,7 +2,7 @@ #' #' @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..aa9e287cf3 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -26,13 +26,7 @@ #' 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} @@ -312,6 +306,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 #' @@ -448,7 +444,7 @@ 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} @@ -487,6 +483,8 @@ decorate_grob_factory <- function(npages, ...) { #' @param grobs a list of grid grobs #' @param ... arguments passed on to \code{\link{decorate_grob}} #' +#' @return A decorated grob. +#' #' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} #' #' @examples 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 d98a7e4ab2..f70dff1a19 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/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/decorate_grob.Rd b/man/decorate_grob.Rd index eeee8147be..9e850ff3fb 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) diff --git a/man/decorate_grob_factory.Rd b/man/decorate_grob_factory.Rd index 86edb2e5e5..56267da9b4 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. diff --git a/man/decorate_grob_set.Rd b/man/decorate_grob_set.Rd index 954117cb03..b285a1286c 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]}} 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 61eb63bf6c..3ecbf75fc8 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/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. } From 3bb7d4caf44af8f67bf8b1758970b1671e82334c Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 31 Mar 2023 19:04:58 -0400 Subject: [PATCH 05/20] Files up to formats.R --- R/estimate_multinomial_rsp.R | 27 ++++++++++----- R/estimate_proportion.R | 50 +++++++++++++++++---------- R/fit_rsp_step.R | 4 ++- R/fit_survival_step.R | 4 ++- R/formats.R | 33 +++++++++++++----- man/d_onco_rsp_label.Rd | 3 ++ man/estimate_multinomial_rsp.Rd | 22 +++++++----- man/estimate_proportions.Rd | 19 +++++++--- man/extreme_format.Rd | 8 +++++ man/fit_rsp_step.Rd | 2 +- man/fit_survival_step.Rd | 2 +- man/format_count_fraction.Rd | 2 +- man/format_count_fraction_fixed_dp.Rd | 2 +- man/format_extreme_values.Rd | 3 ++ man/format_extreme_values_ci.Rd | 6 +++- man/format_fraction.Rd | 2 +- man/format_fraction_fixed_dp.Rd | 2 +- man/format_fraction_threshold.Rd | 6 ++-- man/h_proportions.Rd | 28 +++++++-------- man/strata_normal_quantile.Rd | 3 ++ man/update_weights_strat_wilson.Rd | 3 ++ 21 files changed, 155 insertions(+), 76 deletions(-) diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index f02e6258f8..5a8c7e80d3 100644 --- a/R/estimate_multinomial_rsp.R +++ b/R/estimate_multinomial_rsp.R @@ -5,6 +5,13 @@ #' Estimate the proportion along with confidence interval of a proportion #' regarding the level of a factor. #' +#' @return +#' * `s_length_proportion()` returns statistics from [s_proportion()]. +#' * `a_length_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @seealso Relevant description function [d_onco_rsp_label()]. #' #' @name estimate_multinomial_rsp @@ -18,6 +25,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 +71,10 @@ 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. #' #' @export #' @@ -85,8 +94,8 @@ 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()`. #' @export #' #' @examples @@ -100,9 +109,9 @@ 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 which can take statistics +#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' #' @inheritParams argument_convention #' #' @export diff --git a/R/estimate_proportion.R b/R/estimate_proportion.R index e7a67137fe..997a837621 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -5,13 +5,22 @@ #' Estimate the proportion of responders within a studied population. #' #' @inheritParams argument_convention +#' +#' @return +#' * `s_proportion()` returns statistics `n_prop` (`n` and proportion) and `prop_ci` (proportion CI) for a +#' given variable. +#' * `a_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. +#' * `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. +#' #' @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 @@ -121,8 +130,8 @@ 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()`. #' #' @export a_proportion <- make_afun( @@ -130,7 +139,8 @@ 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 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()]. @@ -182,13 +192,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 +224,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 +344,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 +361,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 +385,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 +411,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 +485,8 @@ d_proportion <- function(conf_level, #' @inheritParams argument_convention #' @inheritParams prop_strat_wilson #' +#' @return Stratified quantile. +#' #' @seealso [prop_strat_wilson()] #' #' @examples @@ -515,6 +525,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..ff35a4ac6f 100644 --- a/R/fit_rsp_step.R +++ b/R/fit_rsp_step.R @@ -20,10 +20,12 @@ #' `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. +#' #' @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..c519dd55b8 100644 --- a/R/fit_survival_step.R +++ b/R/fit_survival_step.R @@ -17,9 +17,11 @@ #' @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. +#' #' @seealso [control_step()] and [control_coxph()] for the available customization options. #' @export #' diff --git a/R/formats.R b/R/formats.R index b29dfefdef..25ae608498 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) @@ -254,6 +259,12 @@ format_fraction_threshold <- function(threshold) { #' #' @param digits (`integer`)\cr number of decimal places to display. #' +#' @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. +#' * `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. +#' #' @family formatting functions #' @name extreme_format NULL @@ -317,6 +328,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 +354,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/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/estimate_multinomial_rsp.Rd b/man/estimate_multinomial_rsp.Rd index 351b35ee4c..4b44cb0833 100644 --- a/man/estimate_multinomial_rsp.Rd +++ b/man/estimate_multinomial_rsp.Rd @@ -50,7 +50,13 @@ 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()}}. +\item \code{a_length_proportion()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +66,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 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 e792a1ee89..d76644986f 100644 --- a/man/estimate_proportions.Rd +++ b/man/estimate_proportions.Rd @@ -90,6 +90,16 @@ 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. +\item \code{a_proportion()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +\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 +107,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 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/extreme_format.Rd b/man/extreme_format.Rd index 373e5e60df..f3ba0219ca 100644 --- a/man/extreme_format.Rd +++ b/man/extreme_format.Rd @@ -15,6 +15,14 @@ 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. +\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]}} diff --git a/man/fit_rsp_step.Rd b/man/fit_rsp_step.Rd index 72f7ff7e4a..c9b37e4e1c 100644 --- a/man/fit_rsp_step.Rd +++ b/man/fit_rsp_step.Rd @@ -17,7 +17,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. diff --git a/man/fit_survival_step.Rd b/man/fit_survival_step.Rd index fc19902b90..1d07f9c78c 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. } 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/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/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/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]}} From 3355ecb631bc3d1754e822a9ebaf58ddfbe26404 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 14:31:02 -0400 Subject: [PATCH 06/20] Update arrangement --- R/abnormal.R | 20 +++++++++------ R/abnormal_by_baseline.R | 21 +++++++++------- R/abnormal_by_marked.R | 20 +++++++++------ R/abnormal_by_worst_grade.R | 20 +++++++++------ R/abnormal_by_worst_grade_worsen.R | 24 ++++++++++-------- R/analyze_vars_in_cols.R | 5 ++++ R/compare_variables.R | 18 ++++++++------ R/control_incidence_rate.R | 4 ++- R/control_logistic.R | 2 ++ R/control_survival.R | 3 +++ R/count_cumulative.R | 22 ++++++++++------ R/count_missed_doses.R | 23 +++++++++++------ R/count_occurrences.R | 24 ++++++++++-------- R/count_occurrences_by_grade.R | 30 ++++++++++++++-------- R/count_patients_events_in_cols.R | 23 +++++++++-------- R/count_patients_with_event.R | 40 +++++++++++++++++++----------- R/count_values.R | 19 ++++++++------ R/cox_regression.R | 21 ++++++++++------ R/cox_regression_inter.R | 29 +++++++++++++--------- R/coxph.R | 8 +++--- R/d_pkparam.R | 1 + R/estimate_multinomial_rsp.R | 19 ++++++++------ R/estimate_proportion.R | 20 +++++++++------ R/formats.R | 14 ++++++----- 24 files changed, 268 insertions(+), 162 deletions(-) diff --git a/R/abnormal.R b/R/abnormal.R index 81c59d99c7..aebfa8126c 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -23,13 +23,6 @@ #' `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"))`. #' -#' @return -#' * `s_count_abnormal()` returns the statistic `fraction` which is a vector with `num` and `denom` counts of patients. -#' * `a_count_abnormal()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name abnormal #' @include formats.R NULL @@ -38,6 +31,10 @@ 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. +#' #' @examples #' library(dplyr) #' @@ -113,6 +110,9 @@ s_count_abnormal <- function(df, #' @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()]. +#' #' @examples #' # Internal function - a_count_abnormal #' \dontrun{ @@ -129,6 +129,12 @@ a_count_abnormal <- make_afun( #' @describeIn abnormal Layout-creating function which can 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 e507fd3377..7996882679 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -25,15 +25,6 @@ #' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`. #' @seealso Relevant description function [d_count_abnormal_by_baseline()]. #' -#' @return -#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labelled elements: -#' `not_abnormal`, `abnormal`, and `total`. Each element contains a vector with `num` and `denom` patient counts. -#' * `a_count_abnormal_by_baseline()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' -#' #' @name abnormal_by_baseline NULL @@ -68,6 +59,10 @@ d_count_abnormal_by_baseline <- function(abnormal) { #' @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 `""`. #' +#' @return +#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labelled elements: +#' `not_abnormal`, `abnormal`, and `total`. Each element contains a vector with `num` and `denom` patient counts. +#' #' @examples #' df <- data.frame( #' USUBJID = as.character(c(1:6)), @@ -148,6 +143,9 @@ s_count_abnormal_by_baseline <- function(df, #' @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()]. +#' #' @examples #' # Internal function - a_count_abnormal_by_baseline #' \dontrun{ @@ -166,6 +164,11 @@ a_count_abnormal_by_baseline <- make_afun( #' @describeIn abnormal_by_baseline Layout-creating function which can which can take statistics #' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' +#' @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. #' basic_table() %>% diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index 59b74314e3..8170180166 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -20,19 +20,15 @@ #' @param category (`list`)\cr with different marked category names for single #' and last or replicated. #' -#' @return -#' * `s_count_abnormal_by_marked()` returns statistic `count_fraction` with `Single, not last`, -#' `Last or replicated`, and `Any` results. -#' * `a_count_abnormal_by_marked()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name abnormal_by_marked NULL #' @describeIn abnormal_by_marked Statistics function for patients with marked lab abnormalities. #' +#' @return +#' * `s_count_abnormal_by_marked()` returns statistic `count_fraction` with `Single, not last`, +#' `Last or replicated`, and `Any` results. +#' #' @examples #' library(dplyr) #' @@ -139,6 +135,9 @@ s_count_abnormal_by_marked <- function(df, #' @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()]. +#' #' @examples #' # Internal function - a_count_abnormal_by_marked #' \dontrun{ @@ -161,6 +160,11 @@ a_count_abnormal_by_marked <- make_afun( #' @describeIn abnormal_by_marked Layout-creating function which can 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( #' df[df$abn_dir %in% c("Low", "High") & df$AVALCAT1 != "", c("PARAMCD", "abn_dir")] diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 8d47e14eee..1cc3be4ba1 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -23,19 +23,15 @@ #' #' @inheritParams argument_convention #' -#' @return -#' * `s_count_abnormal_by_worst_grade()` returns the single statistic `count_fraction` with grades 1 to 4 and -#' "Any" results. -#' * `a_count_abnormal_by_worst_grade()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name abnormal_by_worst_grade NULL #' @describeIn abnormal_by_worst_grade Statistics function which counts patients by worst grade. #' +#' @return +#' * `s_count_abnormal_by_worst_grade()` returns the single statistic `count_fraction` with grades 1 to 4 and +#' "Any" results. +#' #' @examples #' library(dplyr) #' library(forcats) @@ -139,6 +135,9 @@ s_count_abnormal_by_worst_grade <- function(df, # nolint #' @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()]. +#' #' @examples #' # Internal function - a_count_abnormal_by_worst_grade #' \dontrun{ @@ -157,6 +156,11 @@ a_count_abnormal_by_worst_grade <- make_afun( # nolint #' @describeIn abnormal_by_worst_grade Layout-creating function which can 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 #' # in the table. diff --git a/R/abnormal_by_worst_grade_worsen.R b/R/abnormal_by_worst_grade_worsen.R index fe2ad5d8e0..28bf29dd1b 100644 --- a/R/abnormal_by_worst_grade_worsen.R +++ b/R/abnormal_by_worst_grade_worsen.R @@ -6,16 +6,6 @@ #' #' @inheritParams argument_convention #' -#' @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". -#' * `a_count_abnormal_lab_worsen_by_baseline()` returns the corresponding list with -#' formatted [rtables::CellValue()]. -#' * `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. -#' #' @seealso Relevant helper functions [h_adlb_worsen()] and [h_worsen_counter()] #' #' @name abnormal_by_worst_grade_worsen @@ -278,6 +268,11 @@ h_worsen_counter <- function(df, id, .var, baseline_var, direction_var) { #' * `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". +#' #' @examples #' library(dplyr) #' @@ -335,6 +330,10 @@ s_count_abnormal_lab_worsen_by_baseline <- function(df, # nolint #' @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 +#' formatted [rtables::CellValue()]. +#' #' @examples #' # Internal function - a_count_abnormal_lab_worsen_by_baseline #' \dontrun{ @@ -355,6 +354,11 @@ a_count_abnormal_lab_worsen_by_baseline <- make_afun( # nolint #' @describeIn abnormal_by_worst_grade_worsen Layout-creating function which can 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() %>% #' split_cols_by("ARMCD") %>% diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 9a6575dd47..65a7622afe 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -8,6 +8,11 @@ #' @inheritParams argument_convention #' @inheritParams 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()]. #' #' @name analyze_vars_in_cols diff --git a/R/compare_variables.R b/R/compare_variables.R index 4622d818c9..683a383855 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -6,13 +6,6 @@ #' #' @inheritParams argument_convention #' -#' @return -#' * `s_compare()` returns output of [s_summary()] and comparisons versus the reference group in the form of p-values. -#' * `a_compare()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @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 @@ -36,6 +29,9 @@ NULL #' @describeIn compare_variables S3 generic statistics 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 #' s_compare <- function(x, @@ -246,6 +242,9 @@ s_compare.logical <- function(x, #' @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 #' a_compare <- function(x, @@ -466,6 +465,11 @@ create_afun_compare <- function(.stats = NULL, #' #' @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 9fb7962abf..e37c8be675 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -5,14 +5,6 @@ #' 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. #' -#' @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. -#' * `a_count_cumulative()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @seealso Relevant helper function [h_count_cumulative()], and descriptive function [d_count_cumulative()] #' #' @name count_cumulative @@ -30,6 +22,7 @@ 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: #' * `count`: the count of values less than, less or equal to, greater than, or greater or equal to a threshold #' of user specification. @@ -98,6 +91,10 @@ d_count_cumulative <- function(threshold, lower_tail, include_eq) { #' @inheritParams h_count_cumulative #' @param thresholds (`numeric`)\cr vector of cutoff value for the counts. #' +#' @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 #' \dontrun{ @@ -130,6 +127,9 @@ s_count_cumulative <- function(x, #' @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()]. +#' #' @examples #' # Internal function - a_count_cumulative #' \dontrun{ @@ -149,6 +149,12 @@ a_count_cumulative <- make_afun( #' 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 d5fee9edf5..b40ab2e422 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -5,14 +5,6 @@ #' These are specific functions to count patients with missed doses. The difference to [count_cumulative()] is #' mainly the special labels. #' -#' @return -#' * `s_count_nonmissing()` returns the statistic `n` which is the count of non-missing values in `x`. -#' * `s_count_missed_doses()` returns the statistics `n` and `count_fraction` with one element for each threshold. -#' * `a_count_missed_doses()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @seealso Relevant description function [d_count_missed_doses()]. #' #' @name count_missed_doses @@ -21,6 +13,9 @@ 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`. +#' #' @examples #' set.seed(1) #' x <- c(sample(1:10, 10), NA) @@ -52,6 +47,9 @@ d_count_missed_doses <- function(thresholds) { #' @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. +#' #' @examples #' # Internal function - s_count_missed_doses #' \dontrun{ @@ -80,6 +78,9 @@ s_count_missed_doses <- function(x, #' @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 #' \dontrun{ @@ -98,6 +99,12 @@ a_count_missed_doses <- make_afun( #' @describeIn count_missed_doses Layout-creating function which can 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 2929e5268d..4937d5df1d 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -12,16 +12,6 @@ #' #' @inheritParams argument_convention #' -#' @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. -#' * `a_count_occurrences()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name count_occurrences #' NULL @@ -33,6 +23,12 @@ NULL #' - `N_col`: total number of patients in this column across rows #' - `n`: number of patients with any occurrences #' +#' @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( #' USUBJID = as.character(c(1, 1, 2, 4, 4, 4)), @@ -111,6 +107,9 @@ s_count_occurrences <- function(df, #' 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. @@ -131,6 +130,11 @@ a_count_occurrences <- make_afun( #' @describeIn count_occurrences Layout-creating function which can 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 diff --git a/R/count_occurrences_by_grade.R b/R/count_occurrences_by_grade.R index acf76e9a91..85fe24bea9 100644 --- a/R/count_occurrences_by_grade.R +++ b/R/count_occurrences_by_grade.R @@ -11,16 +11,6 @@ #' @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. #' -#' * `s_count_occurrences_by_grade()` returns a list of counts and fractions with one element per grade level or -#' grade level grouping. -#' * `a_count_occurrences_by_grade()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' * `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. -#' #' @seealso Relevant helper function [h_append_grade_groups()]. #' #' @name count_occurrences_by_grade @@ -124,6 +114,10 @@ h_append_grade_groups <- function(grade_groups, refs, remove_single = TRUE) { #' @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) #' df <- data.frame( @@ -203,6 +197,10 @@ s_count_occurrences_by_grade <- function(df, #' @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 @@ -226,6 +224,12 @@ a_count_occurrences_by_grade <- make_afun( #' @describeIn count_occurrences_by_grade Layout-creating function which can 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. @@ -285,6 +289,12 @@ count_occurrences_by_grade <- function(lyt, #' @describeIn count_occurrences_by_grade Layout-creating function which can 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. diff --git a/R/count_patients_events_in_cols.R b/R/count_patients_events_in_cols.R index 9ccbd4a748..f4b453337c 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -5,16 +5,6 @@ #' Counting the number of unique patients and the total number of all and specific events #' when a column table layout is required. #' -#' @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`, -#' i.e. events, fulfilling the filter condition. -#' * `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. -#' #' @name count_patients_events_in_cols #' NULL @@ -31,6 +21,13 @@ 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: +#' - `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`, +#' i.e. events, fulfilling the filter condition. +#' #' @examples #' # `s_count_patients_and_multiple_events()` #' df <- data.frame( @@ -116,6 +113,12 @@ s_count_patients_and_multiple_events <- function(df, # nolint #' @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 0e3390b279..be52c8bbfc 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -4,20 +4,6 @@ #' #' The primary analysis variable `.var` denotes the unique patient identifier. #' -#' @return -#' * `s_count_patients_with_event()` returns the count and fraction of unique identifiers with the defined event. -#' * `a_count_patients_with_event()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' -#' * `s_count_patients_with_flags()` returns the count and the fraction of unique identifiers with each particular -#' flag. Returns a list of `n`s, `count`s, `count_fraction`s, and `n_blq`s with one element per flag. -#' * `a_count_patients_with_flags()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name count_patients_with_event #' NULL @@ -34,6 +20,9 @@ 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 unique identifiers with the defined event. +#' #' @export #' #' @examples @@ -88,6 +77,10 @@ s_count_patients_with_event <- function(df, #' @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 @@ -110,6 +103,11 @@ a_count_patients_with_event <- make_afun( #' #' @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()` @@ -177,6 +175,11 @@ count_patients_with_event <- function(lyt, #' @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. Returns a list of `n`s, `count`s, `count_fraction`s, and `n_blq`s with one element per flag. +#' #' @export #' #' @examples @@ -239,6 +242,10 @@ s_count_patients_with_flags <- function(df, #' @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 @@ -268,6 +275,11 @@ a_count_patients_with_flags <- make_afun( #' #' @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 f7deba908b..ca5f813d65 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -10,13 +10,6 @@ #' * For `count_values()`, variable labels are shown when there is more than one element in `vars`, #' otherwise they are hidden. #' -#' @return -#' * `s_count_values()` returns output of [s_summary()] for specified values of a non-numeric variable. -#' * `a_count_values()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @name count_values_funs #' NULL @@ -26,6 +19,9 @@ NULL #' @inheritParams s_summary.logical #' @param values (`character`)\cr specific values that should be counted. #' +#' @return +#' * `s_count_values()` returns output of [s_summary()] for specified values of a non-numeric variable. +#' #' @export #' s_count_values <- function(x, @@ -92,6 +88,10 @@ s_count_values.logical <- function(x, values = TRUE, ...) { #' @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 @@ -106,6 +106,11 @@ a_count_values <- make_afun( #' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' @inheritParams argument_convention #' +#' @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 #' #' @examples diff --git a/R/cox_regression.R b/R/cox_regression.R index d2c0295b1c..faa0041457 100644 --- a/R/cox_regression.R +++ b/R/cox_regression.R @@ -18,13 +18,6 @@ #' `.labels`). #' @inheritParams argument_convention #' -#' @return -#' * `s_coxreg()` returns a formatted list with the specified statistic, with each element corresponding -#' to one term in the given model. -#' * `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 rows for a formatted -#' Cox regression summary table containing the statistics from `s_coxreg()` to the table layout. -#' #' @seealso [fit_coxreg] for relevant fitting functions, [h_cox_regression] for relevant #' helper functions, and [tidy_coxreg] for custom tidy methods. #' @@ -62,6 +55,11 @@ NULL #' @describeIn cox_regression Statistics function to transform the tabulated results from [fit_coxreg_univar()] #' and [fit_coxreg_multivar()] into a list. +#' +#' @return +#' * `s_coxreg()` returns a formatted list with the specified statistic, with each element corresponding +#' to one term in the given model. +#' #' @export #' #' @examples @@ -144,6 +142,12 @@ s_coxreg <- function(df, .var) { #' `pval` (p.value of the treatment effect) and #' `pval_inter` (the p.value of the interaction effect between the treatment #' and the covariate). +#' +#' @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 rows for a formatted +#' Cox regression summary table containing the statistics from `s_coxreg()` to the table layout. +#' #' @export #' #' @examples @@ -238,7 +242,7 @@ summarize_coxreg <- function(lyt, #' `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() @@ -520,6 +524,7 @@ NULL #' effect should be estimated. #' @param control (`list`)\cr a list of parameters as returned by the #' helper function [control_coxreg()]. +#' #' @return #' * `fit_coxreg_univar()` returns a `coxreg.univar` class object which is a named `list` #' with 5 elements: diff --git a/R/cox_regression_inter.R b/R/cox_regression_inter.R index 724a642493..08f8e5f219 100644 --- a/R/cox_regression_inter.R +++ b/R/cox_regression_inter.R @@ -16,18 +16,6 @@ #' [control_coxreg()]. #' @param ... see methods. #' -#' @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`. -#' * `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. -#' * `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. -#' #' @name cox_regression_inter #' #' @examples @@ -64,6 +52,11 @@ 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, @@ -167,6 +160,10 @@ h_coxreg_inter_effect.factor <- function(x, # nolint #' @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 #' #' @examples @@ -242,6 +239,14 @@ 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 +#' * `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) #' result <- h_coxreg_inter_estimations( diff --git a/R/coxph.R b/R/coxph.R index d188dcdccd..3e1de571f5 100644 --- a/R/coxph.R +++ b/R/coxph.R @@ -245,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, @@ -346,8 +347,7 @@ 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`. +#' @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 diff --git a/R/d_pkparam.R b/R/d_pkparam.R index f76e1136c2..2ca63db5f7 100644 --- a/R/d_pkparam.R +++ b/R/d_pkparam.R @@ -3,6 +3,7 @@ #' @description `r lifecycle::badge("stable")` #' #' @return `data.frame` of PK parameters +#' #' @export #' #' @examples diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index 5a8c7e80d3..a8c43d1dd1 100644 --- a/R/estimate_multinomial_rsp.R +++ b/R/estimate_multinomial_rsp.R @@ -5,13 +5,6 @@ #' Estimate the proportion along with confidence interval of a proportion #' regarding the level of a factor. #' -#' @return -#' * `s_length_proportion()` returns statistics from [s_proportion()]. -#' * `a_length_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @seealso Relevant description function [d_onco_rsp_label()]. #' #' @name estimate_multinomial_rsp @@ -76,6 +69,9 @@ d_onco_rsp_label <- function(x) { # nolint #' #' @inheritParams argument_convention #' +#' @return +#' * `s_length_proportion()` returns statistics from [s_proportion()]. +#' #' @export #' #' @examples @@ -96,6 +92,10 @@ s_length_proportion <- function(x, #' @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 @@ -114,6 +114,11 @@ a_length_proportion <- make_afun( #' #' @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 997a837621..3b2560fea8 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -6,14 +6,6 @@ #' #' @inheritParams argument_convention #' -#' @return -#' * `s_proportion()` returns statistics `n_prop` (`n` and proportion) and `prop_ci` (proportion CI) for a -#' given variable. -#' * `a_proportion()` returns the corresponding list with formatted [rtables::CellValue()]. -#' * `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. -#' #' @seealso [h_proportions] #' #' @name estimate_proportions @@ -35,6 +27,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) @@ -133,6 +129,9 @@ s_proportion <- function(df, #' @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( s_proportion, @@ -145,6 +144,11 @@ a_proportion <- make_afun( #' @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), diff --git a/R/formats.R b/R/formats.R index 25ae608498..e52f74c598 100644 --- a/R/formats.R +++ b/R/formats.R @@ -259,12 +259,6 @@ format_fraction_threshold <- function(threshold) { #' #' @param digits (`integer`)\cr number of decimal places to display. #' -#' @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. -#' * `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. -#' #' @family formatting functions #' @name extreme_format NULL @@ -272,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) #' @@ -296,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) From 6688827ad2473ac15e7c607269a58f6de58f517f Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 16:25:56 -0400 Subject: [PATCH 07/20] Graph functions and helper functions --- R/g_forest.R | 6 ++++- R/g_lineplot.R | 6 ++--- R/g_step.R | 7 +++-- R/g_waterfall.R | 3 ++- R/h_adsl_adlb_merge_using_worst_flag.R | 6 ++--- R/h_biomarkers_subgroups.R | 8 +++--- R/h_cox_regression.R | 23 ++++++++++------ R/h_logistic_regression.R | 25 ++++++++++++++++++ R/h_map_for_count_abnormal.R | 3 +++ R/h_pkparam_sort.R | 6 +++-- R/h_response_biomarkers_subgroups.R | 10 +++++++ R/h_response_subgroups.R | 23 +++++++++++++++- R/h_stack_by_baskets.R | 3 +++ R/h_step.R | 36 ++++++++++++++++++-------- R/h_survival_biomarkers_subgroups.R | 9 +++++++ R/h_survival_duration_subgroups.R | 15 +++++++++++ 16 files changed, 153 insertions(+), 36 deletions(-) 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..1ef448852b 100644 --- a/R/g_lineplot.R +++ b/R/g_lineplot.R @@ -61,7 +61,7 @@ #' #' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com #' -#' @return \code{ggplot} +#' @return A `ggplot` line plot (and statistics table if applicable). #' #' @export #' @@ -426,7 +426,7 @@ g_lineplot <- function(df, # nolint #' #' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com #' -#' @return 1-row \code{data.frame} object +#' @return A single row `data.frame` object. #' #' @examples #' @@ -482,7 +482,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. +#' @return A named character vector of variable names. #' #' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com #' 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..ceb8afdace 100644 --- a/R/g_waterfall.R +++ b/R/g_waterfall.R @@ -13,7 +13,8 @@ #' @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. +#' +#' @return A `ggplot` waterfall plot. #' #' @author Yuyao Song (songy) \email{yuyao.song@roche.com} #' @export 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 7017b335eb..33c2c7df2b 100644 --- a/R/h_cox_regression.R +++ b/R/h_cox_regression.R @@ -6,14 +6,6 @@ #' #' @inheritParams argument_convention #' -#' @return -#' * `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()]). -#' * `h_coxreg_univar_extract()` returns a `data.frame` with variables `effect`, `term`, `term_label`, `level`, -#' `n`, `hr`, `lcl`, `ucl`, and `pval`. -#' * `h_coxreg_multivar_extract()` returns a `data.frame` with variables `pval`, `hr`, `lcl`, `ucl`, `level`, -#' `n`, `term`, and `term_label`. -#' #' @seealso [cox_regression] #' #' @name h_cox_regression @@ -25,6 +17,9 @@ NULL #' @inheritParams argument_convention #' @inheritParams control_coxreg #' +#' @return +#' * `h_coxreg_univar_formulas()` returns a `character` vector coercible into formulas (e.g [stats::as.formula()]). +#' #' @examples #' # `h_coxreg_univar_formulas` #' @@ -116,6 +111,9 @@ h_coxreg_univar_formulas <- function(variables, #' #' @inheritParams argument_convention #' +#' @return +#' * `h_coxreg_multivar_formula()` returns a `string` coercible into a formula (e.g [stats::as.formula()]). +#' #' @export #' #' @examples @@ -172,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) #' @@ -237,6 +239,11 @@ h_coxreg_univar_extract <- function(effect, #' #' @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..876c58d24c 100644 --- a/R/h_logistic_regression.R +++ b/R/h_logistic_regression.R @@ -48,6 +48,8 @@ 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, @@ -148,6 +154,8 @@ h_or_cat_interaction <- function(odds_ratio_var, #' this does not arise in this table, as the treatment arm variable will always be involved #' and categorical. #' +#' @return Odds ratio. +#' #' @export h_or_cont_interaction <- function(odds_ratio_var, interaction_var, @@ -239,6 +247,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 +282,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 +302,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 +332,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 +431,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 +538,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 +634,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 +667,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..c993191cad 100644 --- a/R/h_response_biomarkers_subgroups.R +++ b/R/h_response_biomarkers_subgroups.R @@ -8,6 +8,7 @@ #' @inheritParams response_biomarkers_subgroups #' @inheritParams extract_rsp_biomarkers #' @inheritParams argument_convention +#' #' @name h_response_biomarkers_subgroups #' #' @examples @@ -29,6 +30,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 +64,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 +165,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..44f5b67d6f 100644 --- a/R/h_response_subgroups.R +++ b/R/h_response_subgroups.R @@ -1,14 +1,16 @@ #' 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 #' #' @examples @@ -32,6 +34,10 @@ 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..fe8b75be92 100644 --- a/R/h_step.R +++ b/R/h_step.R @@ -13,12 +13,15 @@ NULL 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, @@ -221,13 +233,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..9cc6baf95b 100644 --- a/R/h_survival_biomarkers_subgroups.R +++ b/R/h_survival_biomarkers_subgroups.R @@ -35,6 +35,9 @@ 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 +71,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 +174,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..7d575cd79e 100644 --- a/R/h_survival_duration_subgroups.R +++ b/R/h_survival_duration_subgroups.R @@ -42,6 +42,9 @@ 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( From 0c2e0a4ef87e558248b7172b9b85df5282b06c77 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 17:00:42 -0400 Subject: [PATCH 08/20] Fix typo --- R/abnormal.R | 4 ++-- R/abnormal_by_baseline.R | 4 ++-- R/abnormal_by_marked.R | 4 ++-- R/abnormal_by_worst_grade.R | 4 ++-- R/abnormal_by_worst_grade_worsen.R | 4 ++-- R/analyze_vars_in_cols.R | 4 ++-- R/compare_variables.R | 4 ++-- R/count_cumulative.R | 4 ++-- R/count_missed_doses.R | 4 ++-- R/count_occurrences.R | 4 ++-- R/count_occurrences_by_grade.R | 6 +++--- R/count_patients_events_in_cols.R | 6 +++--- R/count_patients_with_event.R | 8 ++++---- R/count_values.R | 4 ++-- R/estimate_multinomial_rsp.R | 4 ++-- R/estimate_proportion.R | 4 ++-- 16 files changed, 36 insertions(+), 36 deletions(-) diff --git a/R/abnormal.R b/R/abnormal.R index aebfa8126c..072342f1f1 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -127,8 +127,8 @@ a_count_abnormal <- make_afun( .formats = c(fraction = format_fraction) ) -#' @describeIn abnormal Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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, diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index 7996882679..af99f6553b 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -161,8 +161,8 @@ a_count_abnormal_by_baseline <- make_afun( .formats = c(fraction = format_fraction) ) -#' @describeIn abnormal_by_baseline Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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()]. #' #' @return #' * `count_abnormal_by_baseline()` returns a layout object suitable for passing to further layouting functions, diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index 8170180166..edd75f03b5 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -157,8 +157,8 @@ a_count_abnormal_by_marked <- make_afun( .formats = c(count_fraction = format_count_fraction) ) -#' @describeIn abnormal_by_marked Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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, diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 1cc3be4ba1..664a5936c1 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -153,8 +153,8 @@ 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 which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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, diff --git a/R/abnormal_by_worst_grade_worsen.R b/R/abnormal_by_worst_grade_worsen.R index 28bf29dd1b..30ed91a596 100644 --- a/R/abnormal_by_worst_grade_worsen.R +++ b/R/abnormal_by_worst_grade_worsen.R @@ -351,8 +351,8 @@ a_count_abnormal_lab_worsen_by_baseline <- make_afun( # nolint .ungroup_stats = "fraction" ) -#' @describeIn abnormal_by_worst_grade_worsen Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 65a7622afe..97f404c7d8 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -18,8 +18,8 @@ #' @name analyze_vars_in_cols NULL -#' @describeIn analyze_vars_in_cols 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()]. +#' @describeIn analyze_vars_in_cols 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()]. #' #' @examples #' library(dplyr) diff --git a/R/compare_variables.R b/R/compare_variables.R index 683a383855..2c768dfa28 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -460,8 +460,8 @@ create_afun_compare <- function(.stats = NULL, } } -#' @describeIn compare_variables Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @describeIn compare_variables Layout-creating function which can take statistics function arguments +#' and additional format arguments. This function is a wrapper for [rtables::analyze()]. #' #' @param ... arguments passed to `s_compare()`. #' diff --git a/R/count_cumulative.R b/R/count_cumulative.R index e37c8be675..3288961f6a 100644 --- a/R/count_cumulative.R +++ b/R/count_cumulative.R @@ -145,8 +145,8 @@ a_count_cumulative <- make_afun( .formats = c(count_fraction = format_count_fraction) ) -#' @describeIn count_cumulative Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 #' diff --git a/R/count_missed_doses.R b/R/count_missed_doses.R index b40ab2e422..6ca59527b2 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -96,8 +96,8 @@ a_count_missed_doses <- make_afun( .formats = c(n = "xx", count_fraction = format_count_fraction) ) -#' @describeIn count_missed_doses Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 diff --git a/R/count_occurrences.R b/R/count_occurrences.R index 4937d5df1d..661a127fdf 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -127,8 +127,8 @@ a_count_occurrences <- make_afun( .formats = c(count = "xx", count_fraction = format_count_fraction_fixed_dp, fraction = format_fraction_fixed_dp) ) -#' @describeIn count_occurrences Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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, diff --git a/R/count_occurrences_by_grade.R b/R/count_occurrences_by_grade.R index 85fe24bea9..9ac3e7a4b4 100644 --- a/R/count_occurrences_by_grade.R +++ b/R/count_occurrences_by_grade.R @@ -221,8 +221,8 @@ a_count_occurrences_by_grade <- make_afun( ) -#' @describeIn count_occurrences_by_grade Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 @@ -287,7 +287,7 @@ count_occurrences_by_grade <- function(lyt, ) } -#' @describeIn count_occurrences_by_grade Layout-creating function which can which can take content function arguments +#' @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 diff --git a/R/count_patients_events_in_cols.R b/R/count_patients_events_in_cols.R index f4b453337c..04239fa025 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -9,8 +9,8 @@ #' 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 @@ -107,7 +107,7 @@ s_count_patients_and_multiple_events <- function(df, # nolint y } -#' @describeIn count_patients_events_in_cols Layout-creating function which can which can take statistics function +#' @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 diff --git a/R/count_patients_with_event.R b/R/count_patients_with_event.R index be52c8bbfc..673ce4bd86 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -98,8 +98,8 @@ a_count_patients_with_event <- make_afun( .formats = c(count_fraction = format_count_fraction_fixed_dp) ) -#' @describeIn count_patients_with_event Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 #' @@ -270,8 +270,8 @@ a_count_patients_with_flags <- make_afun( .formats = c("count_fraction" = format_count_fraction_fixed_dp) ) -#' @describeIn count_patients_with_event Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 #' diff --git a/R/count_values.R b/R/count_values.R index ca5f813d65..2d8fa8e2c1 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -102,8 +102,8 @@ a_count_values <- make_afun( .formats = c(count_fraction = "xx (xx.xx%)", count = "xx") ) -#' @describeIn count_values_funs Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 #' #' @return diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index a8c43d1dd1..a8ced3488e 100644 --- a/R/estimate_multinomial_rsp.R +++ b/R/estimate_multinomial_rsp.R @@ -109,8 +109,8 @@ a_length_proportion <- make_afun( ) ) -#' @describeIn estimate_multinomial_rsp Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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 #' diff --git a/R/estimate_proportion.R b/R/estimate_proportion.R index 3b2560fea8..0f60da9f80 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -138,8 +138,8 @@ a_proportion <- make_afun( .formats = c(n_prop = "xx (xx.x%)", prop_ci = "(xx.x, xx.x)") ) -#' @describeIn estimate_proportions Layout-creating function which can which can take statistics -#' function arguments and additional format arguments. This function is a wrapper for [rtables::analyze()]. +#' @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()]. From e9bc9468dd564c07d9655eb7875b777843819bd0 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 21:11:07 -0400 Subject: [PATCH 09/20] Functions until survival_* --- R/incidence_rate.R | 26 ++-- R/individual_patient_plot.R | 5 +- R/kaplan_meier_plot.R | 54 ++++++-- R/logistic_regression.R | 25 +++- R/missing_data.R | 5 + R/odds_ratio.R | 28 +++-- R/prop_diff.R | 28 +++-- R/prop_diff_test.R | 27 ++-- R/prune_occurrences.R | 61 ++++++--- R/response_biomarkers_subgroups.R | 7 ++ R/response_subgroups.R | 22 +++- R/rtables_access.R | 25 +++- R/score_occurrences.R | 18 ++- R/split_cols_by_groups.R | 12 +- R/stat.R | 6 + R/summarize_ancova.R | 38 +++--- R/summarize_change.R | 28 +++-- R/summarize_colvars.R | 5 + R/summarize_coxreg.R | 21 +++- R/summarize_glm_count.R | 52 +++++--- R/summarize_num_patients.R | 45 ++++--- R/summarize_patients_exposure_in_cols.R | 22 ++-- R/summarize_variables.R | 159 +++++++++++++----------- 23 files changed, 494 insertions(+), 225 deletions(-) diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 8c99b700e0..4e875a681c 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,8 @@ 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()]. #' #' @examples #' basic_table() %>% @@ -194,6 +196,8 @@ estimate_incidence_rate <- function(lyt, #' @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..8c7f893370 100644 --- a/R/individual_patient_plot.R +++ b/R/individual_patient_plot.R @@ -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..6ff91568e0 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) @@ -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..80ffaf29d7 100644 --- a/R/logistic_regression.R +++ b/R/logistic_regression.R @@ -11,12 +11,16 @@ #' 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. +#' +#' @note For the formula, the variable names need to be standard `data.frame` column names without +#' special characters. #' #' @inheritParams argument_convention #' @param drop_and_remove_str 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. +#' #' @examples #' library(dplyr) #' library(broom) @@ -118,6 +122,8 @@ summarize_logistic <- function(lyt, #' } #' } #' +#' @return A fitted logistic regression model. +#' #' @examples #' library(dplyr) #' @@ -213,6 +219,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. #' @@ -284,11 +293,15 @@ tidy.glm <- function(fit_glm, # nolint #' #' @description `r lifecycle::badge("stable")` #' -#' Layout creating function for a multi-variable column layout summarizing -#' logistic regression results. +#' Layout-creating function which creates a multi-variable 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 +325,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..482c06afe7 100644 --- a/R/odds_ratio.R +++ b/R/odds_ratio.R @@ -20,10 +20,15 @@ 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 +139,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 +159,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,6 +220,8 @@ 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 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..5c75f4f982 100644 --- a/R/prop_diff_test.R +++ b/R/prop_diff_test.R @@ -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..a19e0109bb 100644 --- a/R/prune_occurrences.R +++ b/R/prune_occurrences.R @@ -9,7 +9,7 @@ #' #' @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 @@ -25,14 +25,17 @@ #' 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 +55,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 +90,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 +119,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 +144,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 +171,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 +194,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 +218,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..e3103c40b0 100644 --- a/R/response_biomarkers_subgroups.R +++ b/R/response_biomarkers_subgroups.R @@ -19,6 +19,8 @@ #' `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. +#' #' @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 @@ -98,6 +100,11 @@ 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()]. +#' +#' @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`. +#' #' @seealso [h_logistic_mult_cont_df()] which is used internally. #' @note You can also specify a continuous variable in `rsp` and then use the #' `response_definition` control to convert that internally to a logical diff --git a/R/response_subgroups.R b/R/response_subgroups.R index 4493adefa8..b3e93ae8d4 100644 --- a/R/response_subgroups.R +++ b/R/response_subgroups.R @@ -58,6 +58,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 +137,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,7 +183,9 @@ 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 @@ -186,6 +197,9 @@ a_response_subgroups <- function(.formats = list( #' `ci` (confidence interval of odds ratio) and #' `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 +343,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..0ddba39711 100644 --- a/R/score_occurrences.R +++ b/R/score_occurrences.R @@ -1,5 +1,7 @@ #' 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. #' @@ -7,12 +9,12 @@ #' 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 +56,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 +83,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 +110,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..2a8e4accd9 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 @@ -95,7 +95,11 @@ combine_groups <- function(fct, #' 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 +227,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..5de3e4a731 100644 --- a/R/summarize_change.R +++ b/R/summarize_change.R @@ -11,9 +11,12 @@ #' 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..48f1d579b9 100644 --- a/R/summarize_colvars.R +++ b/R/summarize_colvars.R @@ -9,6 +9,11 @@ #' @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..8c8ebe1792 100644 --- a/R/summarize_coxreg.R +++ b/R/summarize_coxreg.R @@ -49,9 +49,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()`]. @@ -70,6 +69,9 @@ NULL #' 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 @@ -142,7 +144,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 +153,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,7 +253,8 @@ 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 @@ -259,6 +265,11 @@ 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 diff --git a/R/summarize_glm_count.R b/R/summarize_glm_count.R index 2ca78330e6..f24549b2ee 100644 --- a/R/summarize_glm_count.R +++ b/R/summarize_glm_count.R @@ -38,6 +38,10 @@ NULL #' 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 #' \dontrun{ @@ -91,13 +95,16 @@ h_glm_poisson <- function(.var, #' @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")) #' ) #' } @@ -159,6 +166,9 @@ h_glm_quasipoisson <- function(.var, #' @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 +208,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 +267,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 +386,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 +430,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..34484f5cfe 100644 --- a/R/summarize_num_patients.R +++ b/R/summarize_num_patients.R @@ -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,15 @@ 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. +#' +#' @note As opposed to [summarize_num_patients()], this function does not repeat the produced rows. #' #' @details In general, functions that starts with `analyze*` are expected to #' work like [rtables::analyze()], while functions that starts with `summarize*` diff --git a/R/summarize_patients_exposure_in_cols.R b/R/summarize_patients_exposure_in_cols.R index 96e82e1670..bd2bd4ab90 100644 --- a/R/summarize_patients_exposure_in_cols.R +++ b/R/summarize_patients_exposure_in_cols.R @@ -15,11 +15,11 @@ NULL #' @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,8 +85,16 @@ 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()]. +#' +#' @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. +#' #' #' @inheritParams argument_convention #' @param col_split (`flag`)\cr whether the columns should be split. Set to `FALSE` when the required diff --git a/R/summarize_variables.R b/R/summarize_variables.R index 687721b68a..2046efe60a 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( @@ -112,13 +116,15 @@ summary_labels <- function() { #' different `x` objects. This is used as Statistics Function in combination #' with the new Analyze Function [summarize_vars()]. #' +#' @inheritParams argument_convention +#' #' @name summarize_variables NULL -#' @inheritParams argument_convention +#' @describeIn summarize_variables S3 generic statistics 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,11 +139,13 @@ 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 +#' @describeIn summarize_variables Method for `numeric` class. +#' +#' @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. -#' Also, when the `mean` function is applied to an empty vector, `NA` will +#' * When the `mean` function is applied to an empty vector, `NA` will #' be returned instead of `NaN`, the latter being standard behavior in R. #' #' @param control (`list`)\cr parameters for descriptive statistics details, specified by using @@ -148,34 +156,33 @@ 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`). +#' #' @method s_summary numeric #' #' @examples @@ -299,25 +306,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. +#' +#' @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()]. #' #' @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. +#' #' @method s_summary factor #' #' @examples @@ -374,7 +382,7 @@ 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. @@ -413,21 +421,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 +476,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 +494,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 +509,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 +527,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 +543,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 +560,9 @@ 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. #' #' @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,8 +570,11 @@ 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 #' +#' @return Combined formatted analysis function for use in [summarize_vars()]. +#' #' @export #' #' @examples @@ -648,17 +661,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 From 5378a6aa0e6a7a5830d625c616c80d20fd36904f Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 21:57:39 -0400 Subject: [PATCH 10/20] Remaining functions --- R/survival_biomarkers_subgroups.R | 7 ++++ R/survival_coxph_pairwise.R | 36 +++++++++++++-------- R/survival_duration_subgroups.R | 23 +++++++++++--- R/survival_time.R | 35 +++++++++++--------- R/survival_timepoint.R | 53 +++++++++++++++++++------------ R/utils.R | 28 ++++++++++------ R/utils_checkmate.R | 7 ++-- R/utils_factor.R | 21 ++++++------ R/utils_grid.R | 8 +++++ R/utils_rtables.R | 38 ++++++++++++---------- 10 files changed, 165 insertions(+), 91 deletions(-) diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index 84751285b6..4f07bf8feb 100644 --- a/R/survival_biomarkers_subgroups.R +++ b/R/survival_biomarkers_subgroups.R @@ -59,6 +59,10 @@ NULL #' @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 @@ -173,6 +177,9 @@ extract_survival_biomarkers <- function(variables, #' - `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 biomarker effects on survival by subgroup. +#' #' @seealso [h_tab_surv_one_biomarker()] which is used internally, [extract_survival_biomarkers()]. #' @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 diff --git a/R/survival_coxph_pairwise.R b/R/survival_coxph_pairwise.R index 0ca2eea885..04d2006b53 100644 --- a/R/survival_coxph_pairwise.R +++ b/R/survival_coxph_pairwise.R @@ -19,16 +19,16 @@ #' @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 +119,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 +144,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..3978e7ecd6 100644 --- a/R/survival_duration_subgroups.R +++ b/R/survival_duration_subgroups.R @@ -76,6 +76,12 @@ NULL #' @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`. +#' #' @examples #' library(dplyr) #' library(forcats) @@ -152,8 +158,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,7 +214,9 @@ 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 @@ -219,6 +230,9 @@ a_survival_subgroups <- function(.formats = list( #' `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 #' @@ -371,7 +385,8 @@ tabulate_survival_subgroups <- function(lyt, #' @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. +#' +#' @return A `list` of variables and their labels to tabulate. #' #' @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..2bf6b9ab58 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) { @@ -91,7 +91,7 @@ get_covariates <- function(covariates) { #' @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. #' #' @export @@ -116,6 +116,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 +155,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 +211,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 +263,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 +328,8 @@ aesi_label <- function(aesi, scope = NULL) { #' #' @param x arm information #' +#' @return `x` +#' #' @keywords internal #' study_arm <- function(x) { @@ -343,8 +347,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 +438,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..2be2d150e5 100644 --- a/R/utils_checkmate.R +++ b/R/utils_checkmate.R @@ -14,6 +14,9 @@ #' @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 +36,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. diff --git a/R/utils_factor.R b/R/utils_factor.R index 4baab48767..95b9074ff5 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 @@ -157,7 +156,8 @@ 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. +#' #' @export #' #' @examples @@ -220,7 +220,8 @@ cut_quantile_bins <- function(x, #' @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 @@ -242,7 +243,8 @@ fct_discard <- function(x, discard) { #' @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 @@ -270,8 +272,9 @@ 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`. +#' #' @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..8f055ccbd9 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,7 +94,7 @@ 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. @@ -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,9 @@ 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. +#' +#' @return An `rtables` table object. +#' #' @method as.rtable data.frame #' #' @examples @@ -249,6 +252,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 +296,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) { @@ -321,7 +327,7 @@ afun_selected_stats <- function(.stats, all_stats) { #' @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. #' -#' @return The modified layout. +#' @return A modified layout with the new variable label(s) added to the top-left material. #' #' @examples #' lyt <- basic_table() %>% From fa085f1ad05784a5d3d63eac6c69dd27bb7c3454 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 22:02:25 -0400 Subject: [PATCH 11/20] Update docs --- man/abnormal.Rd | 10 +- man/abnormal_by_baseline.Rd | 10 +- man/abnormal_by_marked.Rd | 10 +- man/abnormal_by_worst_grade.Rd | 10 +- man/abnormal_by_worst_grade_worsen.Rd | 10 +- man/add_rowcounts.Rd | 10 +- man/afun_selected_stats.Rd | 2 +- man/analyze_vars_in_cols.Rd | 9 +- man/append_varlabels.Rd | 2 +- man/arrange_grobs.Rd | 3 + man/as.rtable.Rd | 5 +- man/as_factor_keep_attributes.Rd | 3 +- man/assertions.Rd | 7 +- man/bins_percent_labels.Rd | 2 +- man/c_label_n.Rd | 2 +- man/cfun_by_flag.Rd | 2 +- man/check_same_n.Rd | 3 + man/combine_counts.Rd | 3 + man/combine_groups.Rd | 3 +- man/combine_levels.Rd | 2 +- man/compare_variables.Rd | 10 +- man/control_coxreg.Rd | 2 +- man/control_incidence_rate.Rd | 2 +- man/control_lineplot_vars.Rd | 2 +- man/count_cumulative.Rd | 10 +- man/count_missed_doses.Rd | 13 +- man/count_occurrences.Rd | 10 +- man/count_occurrences_by_grade.Rd | 41 +++--- man/count_patients_events_in_cols.Rd | 9 +- man/count_patients_with_event.Rd | 23 +++- man/count_values_funs.Rd | 10 +- man/cox_regression.Rd | 24 ++-- man/cox_regression_inter.Rd | 6 + man/create_afun_summary.Rd | 9 +- man/cut_quantile_bins.Rd | 2 +- man/d_proportion_diff.Rd | 2 +- man/d_rsp_subgroups_colvars.Rd | 2 +- man/d_survival_subgroups_colvars.Rd | 2 +- man/draw_grob.Rd | 3 + man/empty_vector_if_na.Rd | 2 +- man/estimate_multinomial_rsp.Rd | 10 +- man/estimate_proportions.Rd | 10 +- man/explicit_na.Rd | 3 + man/extract_by_name.Rd | 2 +- man/extract_rsp_biomarkers.Rd | 5 + man/extract_rsp_subgroups.Rd | 9 ++ man/extract_survival_biomarkers.Rd | 5 + man/extract_survival_subgroups.Rd | 9 ++ man/extreme_format.Rd | 3 + man/f_conf_level.Rd | 2 +- man/f_pval.Rd | 2 +- man/fct_collapse_only.Rd | 4 +- man/fct_discard.Rd | 2 +- man/fct_explicit_na_if.Rd | 2 +- man/fit_logistic.Rd | 3 + man/forest_viewport.Rd | 3 + man/g_forest.Rd | 2 +- man/g_km.Rd | 2 +- man/g_lineplot.Rd | 2 +- man/g_step.Rd | 2 +- man/g_waterfall.Rd | 2 +- man/get_covariates.Rd | 2 +- man/get_smooths.Rd | 4 +- man/h_adsl_adlb_merge_using_worst_flag.Rd | 6 +- man/h_ancova.Rd | 3 + man/h_append_grade_groups.Rd | 13 +- man/h_col_indices.Rd | 2 +- man/h_cox_regression.Rd | 11 +- man/h_data_plot.Rd | 6 +- man/h_decompose_gg.Rd | 18 ++- man/h_format_row.Rd | 2 +- man/h_g_ipp.Rd | 3 + man/h_ggkm.Rd | 3 + man/h_glm_count.Rd | 19 ++- man/h_grob_coxph.Rd | 4 + man/h_grob_median_surv.Rd | 3 + man/h_grob_tbl_at_risk.Rd | 3 + man/h_grob_y_annot.Rd | 3 + man/h_incidence_rate.Rd | 3 + man/h_km_layout.Rd | 3 + man/h_logistic_regression.Rd | 25 ++++ man/h_map_for_count_abnormal.Rd | 3 + man/h_odds_ratio.Rd | 3 + man/h_pkparam_sort.Rd | 4 +- man/h_prop_diff.Rd | 4 + man/h_prop_diff_test.Rd | 3 + man/h_response_biomarkers_subgroups.Rd | 13 ++ man/h_response_subgroups.Rd | 26 +++- man/h_split_param.Rd | 4 + man/h_stack_by_baskets.Rd | 4 + man/h_step.Rd | 42 ++++-- man/h_survival_biomarkers_subgroups.Rd | 13 ++ man/h_survival_duration_subgroups.Rd | 20 +++ man/h_tab_one_biomarker.Rd | 6 +- man/h_tbl_coxph_pairwise.Rd | 6 +- man/h_tbl_median_surv.Rd | 3 + man/h_xticks.Rd | 3 + man/incidence_rate.Rd | 24 ++-- man/individual_patient_plot.Rd | 2 +- man/labels_or_names.Rd | 2 +- man/logistic_regression_cols.Rd | 9 +- man/logistic_summary_by_flag.Rd | 5 +- man/make_names.Rd | 2 +- man/odds_ratio.Rd | 28 +++- man/prop_diff.Rd | 25 +++- man/prop_diff_test.Rd | 25 ++-- man/prune_occurrences.Rd | 56 +++++--- man/range_noinf.Rd | 2 +- man/reapply_varlabels.Rd | 3 + man/response_biomarkers_subgroups.Rd | 3 + man/response_subgroups.Rd | 13 +- man/rtables_access.Rd | 31 ++++- man/sas_na.Rd | 4 + man/score_occurrences.Rd | 21 ++- man/split_cols_by_groups.Rd | 4 +- man/stack_grobs.Rd | 3 + man/stat_mean_ci.Rd | 3 + man/stat_mean_pval.Rd | 3 + man/stat_median_ci.Rd | 3 + man/study_arm.Rd | 3 + man/summarize_ancova.Rd | 33 +++-- man/summarize_change.Rd | 28 ++-- man/summarize_colvars.Rd | 5 + man/summarize_glm_count.Rd | 37 ++++-- man/summarize_logistic.Rd | 8 +- man/summarize_num_patients.Rd | 49 ++++--- man/summarize_patients_exposure_in_cols.Rd | 22 +++- man/summarize_variables.Rd | 143 ++++++++++++--------- man/summary_formats.Rd | 3 + man/summary_labels.Rd | 3 + man/survival_biomarkers_subgroups.Rd | 3 + man/survival_coxph_pairwise.Rd | 36 ++++-- man/survival_duration_subgroups.Rd | 14 +- man/survival_time.Rd | 38 ++++-- man/survival_timepoint.Rd | 57 +++++--- man/tidy.glm.Rd | 3 + man/tidy.step.Rd | 2 +- man/to_n.Rd | 2 +- man/to_string_matrix.Rd | 2 +- man/unlist_and_blank_na.Rd | 4 +- 140 files changed, 1046 insertions(+), 389 deletions(-) diff --git a/man/abnormal.Rd b/man/abnormal.Rd index 3601387ad0..7644a71978 100644 --- a/man/abnormal.Rd +++ b/man/abnormal.Rd @@ -67,7 +67,13 @@ to avoid warnings from \code{rtables}.} \value{ \itemize{ \item \code{s_count_abnormal()} returns the statistic \code{fraction} which is a vector with \code{num} and \code{denom} counts of patients. +} + +\itemize{ \item \code{a_count_abnormal()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\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. @@ -92,8 +98,8 @@ for a single \code{abnormal} level. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ diff --git a/man/abnormal_by_baseline.Rd b/man/abnormal_by_baseline.Rd index dcf76ca211..9d5f0cc91a 100644 --- a/man/abnormal_by_baseline.Rd +++ b/man/abnormal_by_baseline.Rd @@ -67,7 +67,13 @@ to avoid warnings from \code{rtables}.} \itemize{ \item \code{s_count_abnormal_by_baseline()} returns statistic \code{fraction} which is a named list with 3 labelled 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. @@ -105,8 +111,8 @@ patients in the numerator and denominator as follows: \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ diff --git a/man/abnormal_by_marked.Rd b/man/abnormal_by_marked.Rd index 6fdc2b38c9..ed94f2b16e 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -63,7 +63,13 @@ and last or replicated.} \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. +} + +\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. @@ -95,8 +101,8 @@ patient will be counted only under the \verb{Last or replicated} category. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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()}}. }} \examples{ diff --git a/man/abnormal_by_worst_grade.Rd b/man/abnormal_by_worst_grade.Rd index 4864cdffde..fd88191b07 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -58,7 +58,13 @@ that is passed by \code{rtables}.} \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()}}. +} + +\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. @@ -95,8 +101,8 @@ the correct denominators when building the layout as it is used to define row sp \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ diff --git a/man/abnormal_by_worst_grade_worsen.Rd b/man/abnormal_by_worst_grade_worsen.Rd index a75704113b..a140bf7739 100644 --- a/man/abnormal_by_worst_grade_worsen.Rd +++ b/man/abnormal_by_worst_grade_worsen.Rd @@ -63,8 +63,14 @@ to avoid warnings from \code{rtables}.} \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". +} + +\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. @@ -83,8 +89,8 @@ lab grades are worse than their baseline grades. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ 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 6c6ae1c75c..0821372059 100644 --- a/man/analyze_vars_in_cols.Rd +++ b/man/analyze_vars_in_cols.Rd @@ -39,6 +39,11 @@ 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]}} @@ -47,8 +52,8 @@ the relevant statistic is on the columns instead of on the rows. } \section{Functions}{ \itemize{ -\item \code{analyze_vars_in_cols()}: 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()}}. +\item \code{analyze_vars_in_cols()}: 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()}}. }} \examples{ 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..2d479f4ee8 100644 --- a/man/as.rtable.Rd +++ b/man/as.rtable.Rd @@ -17,8 +17,9 @@ 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. + +An \code{rtables} table 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/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..7960dcffc3 100644 --- a/man/assertions.Rd +++ b/man/assertions.Rd @@ -91,13 +91,16 @@ 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 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..3a2e4793cc 100644 --- a/man/c_label_n.Rd +++ b/man/c_label_n.Rd @@ -15,7 +15,7 @@ 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. 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/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 d2fa211f65..6a4c072a81 100644 --- a/man/compare_variables.Rd +++ b/man/compare_variables.Rd @@ -133,7 +133,13 @@ to avoid warnings from \code{rtables}.} \value{ \itemize{ \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. +} + +\itemize{ \item \code{a_compare()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. +} + +\itemize{ \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. @@ -171,8 +177,8 @@ in \code{compare_vars()}. \item \code{a_compare(logical)}: Formatted analysis function method for \code{logical} class. -\item \code{compare_vars()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ 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..5b0b9d302c 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]}} diff --git a/man/count_cumulative.Rd b/man/count_cumulative.Rd index 22de314957..743432ffdd 100644 --- a/man/count_cumulative.Rd +++ b/man/count_cumulative.Rd @@ -74,7 +74,13 @@ to avoid warnings from \code{rtables}.} \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. +} + +\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. @@ -93,8 +99,8 @@ greater than, or greater or equal to user-specific thresholds. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ diff --git a/man/count_missed_doses.Rd b/man/count_missed_doses.Rd index d5ae15ffa0..ea15cee7b7 100644 --- a/man/count_missed_doses.Rd +++ b/man/count_missed_doses.Rd @@ -58,8 +58,17 @@ to avoid warnings from \code{rtables}.} \value{ \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. +} + +\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. @@ -80,8 +89,8 @@ mainly the special labels. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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 9ba845959a..d8138f70d5 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -90,7 +90,13 @@ to avoid warnings from \code{rtables}.} \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. @@ -115,8 +121,8 @@ occurrence. \item \code{a_count_occurrences()}: Formatted analysis function which is used as \code{afun} in \code{count_occurrences()}. -\item \code{count_occurrences()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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()}}. }} \examples{ diff --git a/man/count_occurrences_by_grade.Rd b/man/count_occurrences_by_grade.Rd index eccf71c1d9..b526289734 100644 --- a/man/count_occurrences_by_grade.Rd +++ b/man/count_occurrences_by_grade.Rd @@ -64,18 +64,7 @@ by a statistics function.} \item{grade_groups}{(named \code{list} of \code{character})\cr containing groupings of grades.} \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. -\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. -\item \code{a_count_occurrences_by_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. -\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. -\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. -}} +in the the output list; in this case only the grade groups names will be included in the output.} \item{labelstr}{(\code{character})\cr label of the level of the parent split currently being summarized (must be present as second argument in Content Row Functions).} @@ -99,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]}} @@ -114,10 +125,10 @@ number of patients by highest grade. \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 which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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 can which can take content function arguments +\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()}}. }} diff --git a/man/count_patients_events_in_cols.Rd b/man/count_patients_events_in_cols.Rd index 4dbee888e8..63081568fb 100644 --- a/man/count_patients_events_in_cols.Rd +++ b/man/count_patients_events_in_cols.Rd @@ -64,6 +64,9 @@ Set to \code{FALSE} when the required column split has been done already earlier \item one element with the same name as in \code{filters_list}: number of rows in \code{df}, 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. @@ -77,10 +80,10 @@ 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 can which can take statistics function +\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()}}. }} diff --git a/man/count_patients_with_event.Rd b/man/count_patients_with_event.Rd index d480fe5f9f..4ecd8c2c6c 100644 --- a/man/count_patients_with_event.Rd +++ b/man/count_patients_with_event.Rd @@ -121,13 +121,28 @@ by a statistics function.} \value{ \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. Returns a list of \code{n}s, \code{count}s, \code{count_fraction}s, and \code{n_blq}s 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. @@ -146,8 +161,8 @@ the defined event has occurred. \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()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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 which counts the number of patients for which a particular flag variable is \code{TRUE}. @@ -155,8 +170,8 @@ a particular flag variable is \code{TRUE}. \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()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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 fa6962f1af..560eddb00e 100644 --- a/man/count_values_funs.Rd +++ b/man/count_values_funs.Rd @@ -85,7 +85,13 @@ to avoid warnings from \code{rtables}.} \value{ \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. @@ -110,8 +116,8 @@ conversion to \code{character} and then forwards to the method for characters. \item \code{a_count_values()}: Formatted analysis function which is used as \code{afun} in \code{count_values()}. -\item \code{count_values()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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{ diff --git a/man/cox_regression.Rd b/man/cox_regression.Rd index 634cc86358..1d67cf97a8 100644 --- a/man/cox_regression.Rd +++ b/man/cox_regression.Rd @@ -108,11 +108,17 @@ treatment and covariate sections and the second between different covariates.} } \value{ \itemize{ -\item \code{s_coxreg()} returns a formatted list with the specified statistic, with each element corresponding -to one term in the given model. +\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 rows for a formatted -Cox regression summary table containing the statistics from \code{s_coxreg()} to the table layout. +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{ @@ -131,14 +137,14 @@ analysis (NEST Team, 2020). } \section{Functions}{ \itemize{ -\item \code{s_coxreg()}: Statistics function to transform the tabulated results from \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} -and \code{\link[=fit_coxreg_multivar]{fit_coxreg_multivar()}} into a list. +\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 which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. +\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{ diff --git a/man/cox_regression_inter.Rd b/man/cox_regression_inter.Rd index d92c1ff05f..820ebbcf10 100644 --- a/man/cox_regression_inter.Rd +++ b/man/cox_regression_inter.Rd @@ -59,8 +59,14 @@ of the levels of \code{variable} given the levels of \code{given}.} \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{ 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..0f5f52c6f9 100644 --- a/man/cut_quantile_bins.Rd +++ b/man/cut_quantile_bins.Rd @@ -29,7 +29,7 @@ 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]}} 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..897038aeda 100644 --- a/man/d_survival_subgroups_colvars.Rd +++ b/man/d_survival_subgroups_colvars.Rd @@ -27,7 +27,7 @@ are required.} 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]}} 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_multinomial_rsp.Rd b/man/estimate_multinomial_rsp.Rd index 34e513d633..9186f6234d 100644 --- a/man/estimate_multinomial_rsp.Rd +++ b/man/estimate_multinomial_rsp.Rd @@ -52,7 +52,13 @@ to avoid warnings from \code{rtables}.} \value{ \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. @@ -72,8 +78,8 @@ of successes, and \code{.N_col} as total number of successes and failures into \ \item \code{a_length_proportion()}: Formatted analysis function which is used as \code{afun} in \code{estimate_multinomial_response()}. -\item \code{estimate_multinomial_response()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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 d63d95c5a6..635ebd00b3 100644 --- a/man/estimate_proportions.Rd +++ b/man/estimate_proportions.Rd @@ -94,7 +94,13 @@ to avoid warnings from \code{rtables}.} \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. @@ -113,8 +119,8 @@ proportion along with its confidence interval. \item \code{a_proportion()}: Formatted analysis function which is used as \code{afun} in \code{estimate_proportion()}. -\item \code{estimate_proportion()}: Layout-creating function which can which can take statistics -function arguments and additional format arguments. This function is a wrapper for \code{\link[rtables:analyze]{rtables::analyze()}}. +\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..4c69b1c8bb 100644 --- a/man/extract_survival_biomarkers.Rd +++ b/man/extract_survival_biomarkers.Rd @@ -26,6 +26,11 @@ 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]}} diff --git a/man/extract_survival_subgroups.Rd b/man/extract_survival_subgroups.Rd index b6a80c0e7c..739b7ede01 100644 --- a/man/extract_survival_subgroups.Rd +++ b/man/extract_survival_subgroups.Rd @@ -33,6 +33,15 @@ 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 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]}} diff --git a/man/extreme_format.Rd b/man/extreme_format.Rd index f3ba0219ca..4d9819e868 100644 --- a/man/extreme_format.Rd +++ b/man/extreme_format.Rd @@ -19,6 +19,9 @@ h_format_threshold(x, digits = 2L) \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. } 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..2859014a2e 100644 --- a/man/fct_collapse_only.Rd +++ b/man/fct_collapse_only.Rd @@ -16,8 +16,8 @@ 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{ This collapses levels and only keeps those new group levels, in the order provided. diff --git a/man/fct_discard.Rd b/man/fct_discard.Rd index 3510a9e512..1491b82b06 100644 --- a/man/fct_discard.Rd +++ b/man/fct_discard.Rd @@ -12,7 +12,7 @@ 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{ This discards the observations as well as the levels specified from a factor. diff --git a/man/fct_explicit_na_if.Rd b/man/fct_explicit_na_if.Rd index e2da7a0ec3..44132bc051 100644 --- a/man/fct_explicit_na_if.Rd +++ b/man/fct_explicit_na_if.Rd @@ -14,7 +14,7 @@ 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 diff --git a/man/fit_logistic.Rd b/man/fit_logistic.Rd index dd6846b296..7ba29244d7 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]}} 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/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..5f7f6c0c4c 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]}} 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..0976bfb102 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]}} 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_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 09ef9cafc9..4b65c756c0 100644 --- a/man/h_append_grade_groups.Rd +++ b/man/h_append_grade_groups.Rd @@ -13,18 +13,7 @@ h_append_grade_groups(grade_groups, refs, remove_single = TRUE) 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. -\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. -\item \code{a_count_occurrences_by_grade()} returns the corresponding list with formatted \code{\link[rtables:CellValue]{rtables::CellValue()}}. -\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. -\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. -}} +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. 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_cox_regression.Rd b/man/h_cox_regression.Rd index 265fd94122..1721857d62 100644 --- a/man/h_cox_regression.Rd +++ b/man/h_cox_regression.Rd @@ -41,9 +41,18 @@ by a statistics function.} \value{ \itemize{ \item \code{h_coxreg_univar_formulas()} returns a \code{character} vector coercible into formulas (e.g \code{\link[stats:formula]{stats::as.formula()}}). -\item \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}. } 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..ce852bd839 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]}} 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..7dfcfcc2f2 100644 --- a/man/h_logistic_regression.Rd +++ b/man/h_logistic_regression.Rd @@ -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]}} 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..5aaf2595d1 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]}} 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_response_biomarkers_subgroups.Rd b/man/h_response_biomarkers_subgroups.Rd index 2d5a8e992f..12daa25701 100644 --- a/man/h_response_biomarkers_subgroups.Rd +++ b/man/h_response_biomarkers_subgroups.Rd @@ -37,6 +37,19 @@ see the example).} \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..a0865e5db8 100644 --- a/man/h_response_subgroups.Rd +++ b/man/h_response_subgroups.Rd @@ -50,13 +50,33 @@ 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. - +} +\details{ Main functionality is to prepare data for use in a layout creating function. } \section{Functions}{ 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..30a3a787bb 100644 --- a/man/h_step.Rd +++ b/man/h_step.Rd @@ -51,6 +51,33 @@ 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_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 +86,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..1a337c5594 100644 --- a/man/h_survival_biomarkers_subgroups.Rd +++ b/man/h_survival_biomarkers_subgroups.Rd @@ -42,6 +42,19 @@ 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..c9f9ec59b3 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]}} 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_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..ba3e85fbc2 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -80,12 +80,16 @@ 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} +\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()}}. } } \description{ @@ -99,11 +103,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..379cafff7b 100644 --- a/man/logistic_regression_cols.Rd +++ b/man/logistic_regression_cols.Rd @@ -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 multi-variable 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/odds_ratio.Rd b/man/odds_ratio.Rd index 1531efe6ed..d04b68cd94 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]}} @@ -99,15 +115,13 @@ possible. \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()}}. }} \examples{ 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..40f019f72e 100644 --- a/man/response_biomarkers_subgroups.Rd +++ b/man/response_biomarkers_subgroups.Rd @@ -23,6 +23,9 @@ tabulate_rsp_biomarkers( \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]}} diff --git a/man/response_subgroups.Rd b/man/response_subgroups.Rd index b5a782105a..5f77a488d4 100644 --- a/man/response_subgroups.Rd +++ b/man/response_subgroups.Rd @@ -43,6 +43,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 +61,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{ 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/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..d2a830bce9 100644 --- a/man/split_cols_by_groups.Rd +++ b/man/split_cols_by_groups.Rd @@ -20,7 +20,9 @@ levels that belong to it in the character vectors that are elements of the list. \item{...}{additional arguments, see \emph{note} section.} } \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]}} 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/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..946463d885 100644 --- a/man/summarize_colvars.Rd +++ b/man/summarize_colvars.Rd @@ -26,6 +26,11 @@ 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]}} 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..10690ae07f 100644 --- a/man/summarize_logistic.Rd +++ b/man/summarize_logistic.Rd @@ -13,6 +13,10 @@ summarize_logistic(lyt, conf_level, drop_and_remove_str = "") \item{drop_and_remove_str}{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]}} @@ -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..cc63f563ec 100644 --- a/man/summarize_num_patients.Rd +++ b/man/summarize_num_patients.Rd @@ -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..d974d33e35 100644 --- a/man/summarize_variables.Rd +++ b/man/summarize_variables.Rd @@ -185,52 +185,69 @@ 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]}} @@ -241,48 +258,48 @@ with the new 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 statistics 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..066d13a4a2 100644 --- a/man/survival_biomarkers_subgroups.Rd +++ b/man/survival_biomarkers_subgroups.Rd @@ -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]}} 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..b0d4db0d08 100644 --- a/man/survival_duration_subgroups.Rd +++ b/man/survival_duration_subgroups.Rd @@ -50,6 +50,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 +68,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{ 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/to_n.Rd b/man/to_n.Rd index 50017e82bc..b39bfe4573 100644 --- a/man/to_n.Rd +++ b/man/to_n.Rd @@ -12,7 +12,7 @@ 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{ 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/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. From f56376145a27250c5184e05182fe4a848e44dcd2 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 1 May 2023 22:10:05 -0400 Subject: [PATCH 12/20] Add missing values --- R/analyze_vars_in_cols.R | 10 ++-------- R/decorate_grob.R | 7 +++++++ R/h_step.R | 3 +++ R/incidence_rate.R | 5 +++++ man/analyze_vars_in_cols.Rd | 10 ++-------- man/h_step.Rd | 4 ++++ man/incidence_rate.Rd | 6 ++++++ 7 files changed, 29 insertions(+), 16 deletions(-) diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R index 97f404c7d8..0f3b756f37 100644 --- a/R/analyze_vars_in_cols.R +++ b/R/analyze_vars_in_cols.R @@ -2,8 +2,8 @@ #' #' @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. +#' 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 @@ -15,12 +15,6 @@ #' #' @seealso [summarize_vars], [rtables::analyze_colvars()]. #' -#' @name analyze_vars_in_cols -NULL - -#' @describeIn analyze_vars_in_cols 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()]. -#' #' @examples #' library(dplyr) #' diff --git a/R/decorate_grob.R b/R/decorate_grob.R index aa9e287cf3..7d985f9cf7 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -232,6 +232,7 @@ decorate_grob <- function(grob, } #' @importFrom grid validDetails +#' @return A grid grob (`gTree`). #' @export validDetails.decoratedGrob <- function(x) { # nolint @@ -258,12 +259,14 @@ validDetails.decoratedGrob <- function(x) { # nolint } #' @importFrom grid widthDetails +#' @return A grid grob (`gTree`). #' @export widthDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") } #' @importFrom grid heightDetails +#' @return A grid grob (`gTree`). #' @export heightDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") @@ -395,6 +398,7 @@ split_text_grob <- function(text, } #' @importFrom grid validDetails +#' @return A text grob. #' @export validDetails.dynamicSplitText <- function(x) { # nolint checkmate::assert_character(x$text) @@ -404,6 +408,7 @@ validDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid heightDetails +#' @return A text grob. #' @export heightDetails.dynamicSplitText <- function(x) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { @@ -415,12 +420,14 @@ heightDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid widthDetails +#' @return A text grob. #' @export widthDetails.dynamicSplitText <- function(x) { # nolint x$width } #' @importFrom grid drawDetails +#' @return A text grob. #' @export drawDetails.dynamicSplitText <- function(x, recording) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { diff --git a/R/h_step.R b/R/h_step.R index fe8b75be92..6289c70f7e 100644 --- a/R/h_step.R +++ b/R/h_step.R @@ -202,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())) { diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 4e875a681c..41bd5e3d29 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -137,6 +137,11 @@ a_incidence_rate <- make_afun( #' @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() %>% #' split_cols_by("ARM") %>% diff --git a/man/analyze_vars_in_cols.Rd b/man/analyze_vars_in_cols.Rd index 0821372059..ccba1d8daf 100644 --- a/man/analyze_vars_in_cols.Rd +++ b/man/analyze_vars_in_cols.Rd @@ -47,15 +47,9 @@ 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 column-wise summary -tables, primarily used for PK data sets. This function is a wrapper for \code{\link[rtables:analyze_colvars]{rtables::analyze_colvars()}}. - -}} \examples{ library(dplyr) diff --git a/man/h_step.Rd b/man/h_step.Rd index 30a3a787bb..5c5656209d 100644 --- a/man/h_step.Rd +++ b/man/h_step.Rd @@ -72,6 +72,10 @@ and Wald confidence interval bounds \code{ci_lower} and \code{ci_upper}. One row 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 diff --git a/man/incidence_rate.Rd b/man/incidence_rate.Rd index ba3e85fbc2..2f8803c93a 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -91,6 +91,12 @@ to avoid warnings from \code{rtables}.} \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{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} From 14eec76294bda8e650c2df043e28257e992a434e Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 May 2023 12:22:04 -0400 Subject: [PATCH 13/20] Fix warnings --- NAMESPACE | 7 ------- R/count_patients_with_event.R | 2 +- R/decorate_grob.R | 21 +++++++-------------- man/count_patients_with_event.Rd | 2 +- 4 files changed, 9 insertions(+), 23 deletions(-) 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/count_patients_with_event.R b/R/count_patients_with_event.R index 673ce4bd86..9037a5f767 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -178,7 +178,7 @@ count_patients_with_event <- function(lyt, #' #' @return #' * `s_count_patients_with_flags()` returns the count and the fraction of unique identifiers with each particular -#' flag. Returns a list of `n`s, `count`s, `count_fraction`s, and `n_blq`s with one element per flag. +#' flag as a list of statistics `n`, `count`, `count_fraction`, and `n_blq`, with one element per flag. #' #' @export #' diff --git a/R/decorate_grob.R b/R/decorate_grob.R index 7d985f9cf7..b14b2f853a 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -232,8 +232,7 @@ decorate_grob <- function(grob, } #' @importFrom grid validDetails -#' @return A grid grob (`gTree`). -#' @export +#' @noRd validDetails.decoratedGrob <- function(x) { # nolint checkmate::assert_character(x$titles) @@ -259,15 +258,13 @@ validDetails.decoratedGrob <- function(x) { # nolint } #' @importFrom grid widthDetails -#' @return A grid grob (`gTree`). -#' @export +#' @noRd widthDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") } #' @importFrom grid heightDetails -#' @return A grid grob (`gTree`). -#' @export +#' @noRd heightDetails.decoratedGrob <- function(x) { # nolint grid::unit(1, "null") } @@ -398,8 +395,7 @@ split_text_grob <- function(text, } #' @importFrom grid validDetails -#' @return A text grob. -#' @export +#' @noRd validDetails.dynamicSplitText <- function(x) { # nolint checkmate::assert_character(x$text) checkmate::assert_true(grid::is.unit(x$width)) @@ -408,8 +404,7 @@ validDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid heightDetails -#' @return A text grob. -#' @export +#' @noRd heightDetails.dynamicSplitText <- function(x) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { attr(x$text, "fixed_text") @@ -420,15 +415,13 @@ heightDetails.dynamicSplitText <- function(x) { # nolint } #' @importFrom grid widthDetails -#' @return A text grob. -#' @export +#' @noRd widthDetails.dynamicSplitText <- function(x) { # nolint x$width } #' @importFrom grid drawDetails -#' @return A text grob. -#' @export +#' @noRd drawDetails.dynamicSplitText <- function(x, recording) { # nolint txt <- if (!is.null(attr(x$text, "fixed_text"))) { attr(x$text, "fixed_text") diff --git a/man/count_patients_with_event.Rd b/man/count_patients_with_event.Rd index 4ecd8c2c6c..d1b8111cb0 100644 --- a/man/count_patients_with_event.Rd +++ b/man/count_patients_with_event.Rd @@ -135,7 +135,7 @@ 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. Returns a list of \code{n}s, \code{count}s, \code{count_fraction}s, and \code{n_blq}s with one element per flag. +flag as a list of statistics \code{n}, \code{count}, \code{count_fraction}, and \code{n_blq}, with one element per flag. } \itemize{ From 3652bbd1b8b098d815b61984dc263f3d84561cca Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 May 2023 12:28:03 -0400 Subject: [PATCH 14/20] Remove duplicate --- R/utils_rtables.R | 2 -- man/as.rtable.Rd | 2 -- 2 files changed, 4 deletions(-) diff --git a/R/utils_rtables.R b/R/utils_rtables.R index 8f055ccbd9..601f979fd8 100644 --- a/R/utils_rtables.R +++ b/R/utils_rtables.R @@ -201,8 +201,6 @@ as.rtable <- function(x, ...) { # nolint #' #' @param format the format which should be used for the columns. #' -#' @return An `rtables` table object. -#' #' @method as.rtable data.frame #' #' @examples diff --git a/man/as.rtable.Rd b/man/as.rtable.Rd index 2d479f4ee8..25b2d1ccb0 100644 --- a/man/as.rtable.Rd +++ b/man/as.rtable.Rd @@ -18,8 +18,6 @@ as.rtable(x, ...) } \value{ An \code{rtables} table object. Note that the concrete class will depend on the method used. - -An \code{rtables} table object. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} From b28fb1c9b4b7b50c23db78889b9084268996b825 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 May 2023 12:46:36 -0400 Subject: [PATCH 15/20] Fix errors --- R/abnormal_by_baseline.R | 2 +- R/h_survival_biomarkers_subgroups.R | 3 ++- inst/WORDLIST | 1 + man/abnormal_by_baseline.Rd | 2 +- man/h_survival_biomarkers_subgroups.Rd | 3 ++- 5 files changed, 7 insertions(+), 4 deletions(-) diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index af99f6553b..bff05ba663 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -60,7 +60,7 @@ d_count_abnormal_by_baseline <- function(abnormal) { #' [df_explicit_na()]). The default is `""`. #' #' @return -#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labelled elements: +#' * `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 diff --git a/R/h_survival_biomarkers_subgroups.R b/R/h_survival_biomarkers_subgroups.R index 9cc6baf95b..a0b49805fe 100644 --- a/R/h_survival_biomarkers_subgroups.R +++ b/R/h_survival_biomarkers_subgroups.R @@ -36,7 +36,8 @@ NULL #' @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`. +#' * `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. diff --git a/inst/WORDLIST b/inst/WORDLIST index 3a3ff13ef2..b138f36f40 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -55,6 +55,7 @@ efron funder https jeffreys +layouting lik lineplot lvl diff --git a/man/abnormal_by_baseline.Rd b/man/abnormal_by_baseline.Rd index 9d5f0cc91a..dfad0221f1 100644 --- a/man/abnormal_by_baseline.Rd +++ b/man/abnormal_by_baseline.Rd @@ -65,7 +65,7 @@ to avoid warnings from \code{rtables}.} } \value{ \itemize{ -\item \code{s_count_abnormal_by_baseline()} returns statistic \code{fraction} which is a named list with 3 labelled elements: +\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. } diff --git a/man/h_survival_biomarkers_subgroups.Rd b/man/h_survival_biomarkers_subgroups.Rd index 1a337c5594..f1b9e309ab 100644 --- a/man/h_survival_biomarkers_subgroups.Rd +++ b/man/h_survival_biomarkers_subgroups.Rd @@ -44,7 +44,8 @@ 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}. +\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{ From ad4247533e3bd0efcbd6087b03764546aa37c433 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 May 2023 14:41:21 -0400 Subject: [PATCH 16/20] Empty commit From b8fa0d69b47a8c74e42602cffcf823da352dff8a Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 8 May 2023 13:13:34 -0400 Subject: [PATCH 17/20] Remove authors --- R/decorate_grob.R | 4 ---- R/g_lineplot.R | 6 ------ R/g_waterfall.R | 1 - man/control_lineplot_vars.Rd | 3 --- man/decorate_grob.Rd | 3 --- man/decorate_grob_factory.Rd | 3 --- man/decorate_grob_set.Rd | 3 --- man/g_lineplot.Rd | 3 --- man/g_waterfall.Rd | 3 --- man/h_format_row.Rd | 3 --- 10 files changed, 32 deletions(-) diff --git a/R/decorate_grob.R b/R/decorate_grob.R index b14b2f853a..71edb5ff7f 100644 --- a/R/decorate_grob.R +++ b/R/decorate_grob.R @@ -29,7 +29,6 @@ #' @return A grid grob (`gTree`). #' #' @export -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} #' #' @examples #' library(grid) @@ -447,7 +446,6 @@ drawDetails.dynamicSplitText <- function(x, recording) { # nolint #' @return Closure that increments the page number. #' #' @keywords internal -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} #' #' @examples #' # Internal function - decorate_grob_factory @@ -485,8 +483,6 @@ decorate_grob_factory <- function(npages, ...) { #' #' @return A decorated grob. #' -#' @author Adrian Waddell (waddella) \email{adrian.waddell@roche.com} -#' #' @examples #' library(ggplot2) #' library(grid) diff --git a/R/g_lineplot.R b/R/g_lineplot.R index 1ef448852b..bc4b26ca72 100644 --- a/R/g_lineplot.R +++ b/R/g_lineplot.R @@ -59,8 +59,6 @@ #' @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 A `ggplot` line plot (and statistics table if applicable). #' #' @export @@ -424,8 +422,6 @@ 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 A single row `data.frame` object. #' #' @examples @@ -484,8 +480,6 @@ h_format_row <- function(x, format, labels = NULL) { #' #' @return A named character vector of variable names. #' -#' @author Wojciech Wojciak wojciech.wojciak@contractors.roche.com -#' #' @export #' #' @examples diff --git a/R/g_waterfall.R b/R/g_waterfall.R index ceb8afdace..735655de04 100644 --- a/R/g_waterfall.R +++ b/R/g_waterfall.R @@ -16,7 +16,6 @@ #' #' @return A `ggplot` waterfall plot. #' -#' @author Yuyao Song (songy) \email{yuyao.song@roche.com} #' @export #' #' @examples diff --git a/man/control_lineplot_vars.Rd b/man/control_lineplot_vars.Rd index 5b0b9d302c..bde3591b71 100644 --- a/man/control_lineplot_vars.Rd +++ b/man/control_lineplot_vars.Rd @@ -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/decorate_grob.Rd b/man/decorate_grob.Rd index 9e850ff3fb..7b9e2ec85d 100644 --- a/man/decorate_grob.Rd +++ b/man/decorate_grob.Rd @@ -175,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 56267da9b4..63ea803b76 100644 --- a/man/decorate_grob_factory.Rd +++ b/man/decorate_grob_factory.Rd @@ -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 b285a1286c..217c122021 100644 --- a/man/decorate_grob_set.Rd +++ b/man/decorate_grob_set.Rd @@ -57,6 +57,3 @@ draw_grob(lg[[2]]) draw_grob(lg[[6]]) } -\author{ -Adrian Waddell (waddella) \email{adrian.waddell@roche.com} -} diff --git a/man/g_lineplot.Rd b/man/g_lineplot.Rd index 5f7f6c0c4c..f3b2bd6688 100644 --- a/man/g_lineplot.Rd +++ b/man/g_lineplot.Rd @@ -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_waterfall.Rd b/man/g_waterfall.Rd index 0976bfb102..f7cd836961 100644 --- a/man/g_waterfall.Rd +++ b/man/g_waterfall.Rd @@ -85,6 +85,3 @@ g_waterfall( title = "Waterfall plot" ) } -\author{ -Yuyao Song (songy) \email{yuyao.song@roche.com} -} diff --git a/man/h_format_row.Rd b/man/h_format_row.Rd index ce852bd839..89cee85d49 100644 --- a/man/h_format_row.Rd +++ b/man/h_format_row.Rd @@ -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 -} From 57478ce8cb6126717f1a5bb0c4722c05aaa70b80 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 8 May 2023 13:16:47 -0400 Subject: [PATCH 18/20] Implement review suggestions --- R/abnormal_by_marked.R | 2 +- R/abnormal_by_worst_grade.R | 2 +- man/abnormal_by_marked.Rd | 9 +++++---- man/abnormal_by_worst_grade.Rd | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index edd75f03b5..e03baf6b2e 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -12,7 +12,7 @@ #' * For `Any`: Numerator is the number of patients with either single or #' replicated marked abnormalities. #' -#' Note that `Single, not last` and `Last or replicated` levels are mutually exclusive. If a patient has +#' @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. #' diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 664a5936c1..8bb31bb3c4 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -19,7 +19,7 @@ #' * A toxicity grade variable (e.g. `GRADE_ANL`) where all negative values from #' `ATOXGR` are replaced by their absolute values. #' -#' @note Prior to tabulation, `df` must filtered to include only post-baseline records with worst grade flags. +#' @note Prior to tabulation, `df` must be filtered to include only post-baseline records with worst grade flags. #' #' @inheritParams argument_convention #' diff --git a/man/abnormal_by_marked.Rd b/man/abnormal_by_marked.Rd index ed94f2b16e..36ef19f104 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -89,10 +89,6 @@ with \verb{Single, not last} and \verb{Last or replicated} levels, respectively. \item For \code{Any}: Numerator is the number of patients with either single or replicated marked abnormalities. } - -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{ @@ -105,6 +101,11 @@ in \code{count_abnormal_by_marked()}. 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 fd88191b07..952270bc2f 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -106,7 +106,7 @@ and additional format arguments. This function is a wrapper for \code{\link[rtab }} \note{ -Prior to tabulation, \code{df} must filtered to include only post-baseline records with worst grade flags. +Prior to tabulation, \code{df} must be filtered to include only post-baseline records with worst grade flags. } \examples{ library(dplyr) From bf8d8a671e18a04b60c3bac53cd5a3805bbe5e08 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Tue, 9 May 2023 16:17:37 -0400 Subject: [PATCH 19/20] Clean up notes --- R/abnormal.R | 20 ++++----- R/abnormal_by_baseline.R | 5 ++- R/abnormal_by_marked.R | 17 ++++---- R/abnormal_by_worst_grade.R | 9 ++-- R/argument_convention.R | 15 ++++--- R/compare_variables.R | 12 +++--- R/count_cumulative.R | 2 +- R/count_missed_doses.R | 1 - R/count_occurrences.R | 11 ++--- R/count_occurrences_by_grade.R | 3 +- R/count_patients_events_in_cols.R | 1 - R/count_patients_with_event.R | 1 - R/count_values.R | 1 - R/cox_regression.R | 7 ++-- R/cox_regression_inter.R | 9 ++-- R/estimate_multinomial_rsp.R | 1 - R/estimate_proportion.R | 1 - R/fit_rsp_step.R | 6 +-- R/fit_survival_step.R | 3 +- R/formats.R | 6 +-- R/h_logistic_regression.R | 9 ++-- R/h_response_biomarkers_subgroups.R | 3 +- R/h_response_subgroups.R | 6 +-- R/h_step.R | 4 +- R/h_survival_biomarkers_subgroups.R | 4 +- R/h_survival_duration_subgroups.R | 6 +-- R/incidence_rate.R | 11 +++-- R/individual_patient_plot.R | 10 ++--- R/kaplan_meier_plot.R | 2 +- R/logistic_regression.R | 25 +++++------ R/odds_ratio.R | 16 +++---- R/package.R | 1 + R/prop_diff_test.R | 2 +- R/prune_occurrences.R | 3 +- R/response_biomarkers_subgroups.R | 34 ++++++++------- R/response_subgroups.R | 28 +++++++------ R/score_occurrences.R | 1 - R/split_cols_by_groups.R | 7 +--- R/summarize_change.R | 2 +- R/summarize_coxreg.R | 15 ++++--- R/summarize_glm_count.R | 20 ++++----- R/summarize_num_patients.R | 10 ++--- R/summarize_patients_exposure_in_cols.R | 11 +++-- R/summarize_variables.R | 37 ++++++++-------- R/survival_biomarkers_subgroups.R | 38 +++++++++-------- R/survival_coxph_pairwise.R | 1 - R/survival_duration_subgroups.R | 56 +++++++++++++------------ R/utils.R | 5 ++- R/utils_checkmate.R | 5 +-- R/utils_factor.R | 23 ++++++---- R/utils_rtables.R | 14 +++---- man/abnormal.Rd | 6 +-- man/abnormal_by_marked.Rd | 9 ++-- man/abnormal_by_worst_grade.Rd | 4 +- man/assertions.Rd | 2 +- man/c_label_n.Rd | 4 +- man/compare_variables.Rd | 4 +- man/count_cumulative.Rd | 2 +- man/count_occurrences.Rd | 11 +++-- man/cox_regression_inter.Rd | 6 +-- man/cut_quantile_bins.Rd | 10 +++-- man/d_survival_subgroups_colvars.Rd | 32 +++++++------- man/extract_survival_biomarkers.Rd | 9 ++-- man/extract_survival_subgroups.Rd | 11 +++-- man/extreme_format.Rd | 2 +- man/fct_collapse_only.Rd | 9 +++- man/fct_discard.Rd | 2 + man/fct_explicit_na_if.Rd | 4 +- man/fit_logistic.Rd | 11 +++-- man/fit_rsp_step.Rd | 7 ++-- man/fit_survival_step.Rd | 4 +- man/h_cox_regression.Rd | 3 +- man/h_logistic_regression.Rd | 1 + man/h_odds_ratio.Rd | 2 +- man/h_response_biomarkers_subgroups.Rd | 18 ++++---- man/h_response_subgroups.Rd | 3 +- man/h_survival_biomarkers_subgroups.Rd | 10 ++--- man/h_survival_duration_subgroups.Rd | 2 +- man/incidence_rate.Rd | 4 +- man/odds_ratio.Rd | 13 +++--- man/response_biomarkers_subgroups.Rd | 19 +++++---- man/response_subgroups.Rd | 21 ++++++---- man/split_cols_by_groups.Rd | 8 +--- man/summarize_logistic.Rd | 4 +- man/summarize_num_patients.Rd | 2 +- man/survival_biomarkers_subgroups.Rd | 14 ++++--- man/survival_duration_subgroups.Rd | 23 +++++----- man/to_n.Rd | 6 ++- 88 files changed, 438 insertions(+), 404 deletions(-) diff --git a/R/abnormal.R b/R/abnormal.R index 072342f1f1..d9ca3984b7 100644 --- a/R/abnormal.R +++ b/R/abnormal.R @@ -6,23 +6,21 @@ #' 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 -#' * `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. +#' * `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 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 NULL diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R index bff05ba663..a01dd733b5 100644 --- a/R/abnormal_by_baseline.R +++ b/R/abnormal_by_baseline.R @@ -16,13 +16,14 @@ #' * `denom`: the number of patients with at least one valid measurement post-baseline #' * `num`: the number of patients in `denom` who also have at least one abnormality post-baseline #' +#' @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()]. #' -#' @inheritParams argument_convention -#' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`. #' @seealso Relevant description function [d_count_abnormal_by_baseline()]. #' #' @name abnormal_by_baseline diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R index e03baf6b2e..58ccd7b2b3 100644 --- a/R/abnormal_by_marked.R +++ b/R/abnormal_by_marked.R @@ -2,24 +2,23 @@ #' #' @description `r lifecycle::badge("stable")` #' -#' Primary analysis variable `.var` indicates whether single, replicated -#' or last marked laboratory abnormality was observed (`factor`). -#' Additional analysis variables are `id` (`character` or `factor`) and `direction` (`factor`) -#' indicating the direction of the abnormality. -#' Denominator is number of patients with at least one valid measurement during the analysis. +#' 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. #' -#' @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. -#' #' @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 diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R index 8bb31bb3c4..fe9a88bd66 100644 --- a/R/abnormal_by_worst_grade.R +++ b/R/abnormal_by_worst_grade.R @@ -11,9 +11,10 @@ #' * `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 @@ -21,8 +22,6 @@ #' #' @note Prior to tabulation, `df` must be filtered to include only post-baseline records with worst grade flags. #' -#' @inheritParams argument_convention -#' #' @name abnormal_by_worst_grade NULL 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/compare_variables.R b/R/compare_variables.R index 2c768dfa28..ede999d6aa 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -19,9 +19,8 @@ #' * 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()`. +#' @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 @@ -352,6 +351,10 @@ a_compare.logical <- make_afun( #' #' 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 #' corresponding customized methods. Then in order for the methods to be found, @@ -359,10 +362,7 @@ a_compare.logical <- make_afun( #' functions (and possibly others in the future), we provide a constructor that does this: #' [create_afun_compare()]. #' -#' @return Combined formatted analysis function for use in [compare_vars()]. -#' #' @export -#' @inheritParams argument_convention #' @seealso [compare_vars()] #' #' @examples diff --git a/R/count_cumulative.R b/R/count_cumulative.R index 3288961f6a..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 diff --git a/R/count_missed_doses.R b/R/count_missed_doses.R index 6ca59527b2..d6208d4550 100644 --- a/R/count_missed_doses.R +++ b/R/count_missed_doses.R @@ -8,7 +8,6 @@ #' @seealso Relevant description function [d_count_missed_doses()]. #' #' @name count_missed_doses -#' NULL #' @describeIn count_missed_doses Statistics function to count non-missing values. diff --git a/R/count_occurrences.R b/R/count_occurrences.R index 661a127fdf..d64300e169 100644 --- a/R/count_occurrences.R +++ b/R/count_occurrences.R @@ -5,15 +5,16 @@ #' 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. #' #' @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 diff --git a/R/count_occurrences_by_grade.R b/R/count_occurrences_by_grade.R index 9ac3e7a4b4..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()] diff --git a/R/count_patients_events_in_cols.R b/R/count_patients_events_in_cols.R index 04239fa025..615a7fdaef 100644 --- a/R/count_patients_events_in_cols.R +++ b/R/count_patients_events_in_cols.R @@ -6,7 +6,6 @@ #' 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 diff --git a/R/count_patients_with_event.R b/R/count_patients_with_event.R index 9037a5f767..8f459e23ff 100644 --- a/R/count_patients_with_event.R +++ b/R/count_patients_with_event.R @@ -5,7 +5,6 @@ #' The primary analysis variable `.var` denotes the unique patient identifier. #' #' @name count_patients_with_event -#' NULL #' @describeIn count_patients_with_event Statistics function which counts the number of patients for which diff --git a/R/count_values.R b/R/count_values.R index 2d8fa8e2c1..ebf44a7a2d 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -11,7 +11,6 @@ #' otherwise they are hidden. #' #' @name count_values_funs -#' NULL #' @describeIn count_values_funs S3 generic statistics function to count values. diff --git a/R/cox_regression.R b/R/cox_regression.R index 77c96d6cdc..c1e16e8750 100644 --- a/R/cox_regression.R +++ b/R/cox_regression.R @@ -42,10 +42,7 @@ control_coxreg <- function(pval_method = c("wald", "likelihood"), #' #' @description `r lifecycle::badge("stable")` #' -#' @seealso [cox_regression] -#' -#' @return -#' [tidy()] returns: +#' @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`, @@ -53,6 +50,8 @@ control_coxreg <- function(pval_method = c("wald", "likelihood"), #' * 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 NULL diff --git a/R/cox_regression_inter.R b/R/cox_regression_inter.R index 08f8e5f219..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,7 @@ #' 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. diff --git a/R/estimate_multinomial_rsp.R b/R/estimate_multinomial_rsp.R index a8ced3488e..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 diff --git a/R/estimate_proportion.R b/R/estimate_proportion.R index 0f60da9f80..929b8c9553 100644 --- a/R/estimate_proportion.R +++ b/R/estimate_proportion.R @@ -9,7 +9,6 @@ #' @seealso [h_proportions] #' #' @name estimate_proportions -#' NULL #' @describeIn estimate_proportions Statistics function estimating a diff --git a/R/fit_rsp_step.R b/R/fit_rsp_step.R index ff35a4ac6f..35ded23847 100644 --- a/R/fit_rsp_step.R +++ b/R/fit_rsp_step.R @@ -12,12 +12,10 @@ #' `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()]. #' @@ -26,6 +24,8 @@ #' 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 c519dd55b8..a830117b7a 100644 --- a/R/fit_survival_step.R +++ b/R/fit_survival_step.R @@ -11,7 +11,6 @@ #' `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`, @@ -22,6 +21,8 @@ #' 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 e52f74c598..b2679c4128 100644 --- a/R/formats.R +++ b/R/formats.R @@ -250,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 diff --git a/R/h_logistic_regression.R b/R/h_logistic_regression.R index 876c58d24c..453a611f58 100644 --- a/R/h_logistic_regression.R +++ b/R/h_logistic_regression.R @@ -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,6 +41,8 @@ #' interaction = "AGE" #' ) #' ) +#' +#' @name h_logistic_regression NULL #' @describeIn h_logistic_regression Helper function to extract interaction variable names from a fitted @@ -150,12 +150,13 @@ 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. #' -#' @return Odds ratio. -#' #' @export h_or_cont_interaction <- function(odds_ratio_var, interaction_var, diff --git a/R/h_response_biomarkers_subgroups.R b/R/h_response_biomarkers_subgroups.R index c993191cad..ef478ed4c5 100644 --- a/R/h_response_biomarkers_subgroups.R +++ b/R/h_response_biomarkers_subgroups.R @@ -9,8 +9,6 @@ #' @inheritParams extract_rsp_biomarkers #' @inheritParams argument_convention #' -#' @name h_response_biomarkers_subgroups -#' #' @examples #' library(dplyr) #' library(forcats) @@ -23,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 diff --git a/R/h_response_subgroups.R b/R/h_response_subgroups.R index 44f5b67d6f..020d07ec94 100644 --- a/R/h_response_subgroups.R +++ b/R/h_response_subgroups.R @@ -5,13 +5,11 @@ #' 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. -#' #' @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) @@ -30,6 +28,8 @@ #' 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. diff --git a/R/h_step.R b/R/h_step.R index 6289c70f7e..1ec1eeba32 100644 --- a/R/h_step.R +++ b/R/h_step.R @@ -3,13 +3,13 @@ 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 diff --git a/R/h_survival_biomarkers_subgroups.R b/R/h_survival_biomarkers_subgroups.R index a0b49805fe..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 diff --git a/R/h_survival_duration_subgroups.R b/R/h_survival_duration_subgroups.R index 7d575cd79e..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,6 +36,7 @@ #' 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. diff --git a/R/incidence_rate.R b/R/incidence_rate.R index 41bd5e3d29..f665cb5b13 100644 --- a/R/incidence_rate.R +++ b/R/incidence_rate.R @@ -27,11 +27,11 @@ NULL #' associated confidence interval. #' #' @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. +#' * `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) @@ -196,7 +196,6 @@ 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. diff --git a/R/individual_patient_plot.R b/R/individual_patient_plot.R index 8c7f893370..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. #' diff --git a/R/kaplan_meier_plot.R b/R/kaplan_meier_plot.R index 6ff91568e0..bc3c46e64e 100644 --- a/R/kaplan_meier_plot.R +++ b/R/kaplan_meier_plot.R @@ -532,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, diff --git a/R/logistic_regression.R b/R/logistic_regression.R index 80ffaf29d7..3772aec9a3 100644 --- a/R/logistic_regression.R +++ b/R/logistic_regression.R @@ -2,7 +2,7 @@ #' #' @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 @@ -12,15 +12,15 @@ #' 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 `data.frame` column names 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) #' library(broom) @@ -110,19 +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. -#' } -#' } -#' -#' @return A fitted logistic regression model. #' #' @examples #' library(dplyr) diff --git a/R/odds_ratio.R b/R/odds_ratio.R index 482c06afe7..88723bcdcd 100644 --- a/R/odds_ratio.R +++ b/R/odds_ratio.R @@ -8,12 +8,13 @@ #' @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 @@ -22,6 +23,7 @@ NULL #' @describeIn odds_ratio Statistics function which estimates the odds ratio #' 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 #' @@ -227,7 +229,7 @@ estimate_odds_ratio <- function(lyt, #' @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_test.R b/R/prop_diff_test.R index 5c75f4f982..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 diff --git a/R/prune_occurrences.R b/R/prune_occurrences.R index a19e0109bb..cf0dcd1c16 100644 --- a/R/prune_occurrences.R +++ b/R/prune_occurrences.R @@ -11,7 +11,6 @@ #' functions positively, too. However, note that the result of [keep_rows()] says what #' should be pruned, to conform with the [rtables::prune_table()] interface. #' -#' @name prune_occurrences #' @examples #' \dontrun{ #' tab <- basic_table() %>% @@ -23,12 +22,14 @@ #' build_table(DM) #' } #' +#' @name prune_occurrences NULL #' @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 #' 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. #' diff --git a/R/response_biomarkers_subgroups.R b/R/response_biomarkers_subgroups.R index e3103c40b0..33273520dd 100644 --- a/R/response_biomarkers_subgroups.R +++ b/R/response_biomarkers_subgroups.R @@ -5,28 +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. #' -#' @seealso [h_tab_rsp_one_biomarker()] which is used internally, [extract_rsp_biomarkers()]. +#' @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. +#' #' @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) @@ -53,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) @@ -105,10 +107,12 @@ tabulate_rsp_biomarkers <- function(df, #' `prop`, `or`, `lcl`, `ucl`, `conf_level`, `pval`, `pval_label`, `subgroup`, `var`, #' `var_label`, and `row_type`. #' -#' @seealso [h_logistic_mult_cont_df()] which is used internally. #' @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 b3e93ae8d4..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 @@ -188,15 +190,15 @@ a_response_subgroups <- function(.formats = list( #' #' @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. #' diff --git a/R/score_occurrences.R b/R/score_occurrences.R index 0ddba39711..eb13d89776 100644 --- a/R/score_occurrences.R +++ b/R/score_occurrences.R @@ -6,7 +6,6 @@ #' sorting of occurrence tables. #' #' @name score_occurrences -#' NULL #' @describeIn score_occurrences Scoring function which sums the counts across all diff --git a/R/split_cols_by_groups.R b/R/split_cols_by_groups.R index 2a8e4accd9..596333a6f4 100644 --- a/R/split_cols_by_groups.R +++ b/R/split_cols_by_groups.R @@ -88,11 +88,8 @@ 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()] #' diff --git a/R/summarize_change.R b/R/summarize_change.R index 5de3e4a731..c40e78e45d 100644 --- a/R/summarize_change.R +++ b/R/summarize_change.R @@ -8,10 +8,10 @@ #' 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 #' #' @return diff --git a/R/summarize_coxreg.R b/R/summarize_coxreg.R index 8c8ebe1792..bf06e6c625 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. #' diff --git a/R/summarize_glm_count.R b/R/summarize_glm_count.R index f24549b2ee..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,20 +26,19 @@ 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 #' \dontrun{ @@ -92,6 +89,7 @@ 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 #' @@ -156,12 +154,12 @@ 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). diff --git a/R/summarize_num_patients.R b/R/summarize_num_patients.R index 34484f5cfe..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 @@ -167,8 +167,6 @@ summarize_num_patients <- function(lyt, #' 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. #' -#' @note As opposed to [summarize_num_patients()], this function does not repeat the produced rows. -#' #' @details In general, functions that starts with `analyze*` are expected to #' work like [rtables::analyze()], while functions that starts with `summarize*` #' are based upon [rtables::summarize_row_groups()]. The latter provides a @@ -176,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 bd2bd4ab90..5bf6d69ccd 100644 --- a/R/summarize_patients_exposure_in_cols.R +++ b/R/summarize_patients_exposure_in_cols.R @@ -6,11 +6,10 @@ #' 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 @@ -89,16 +88,16 @@ s_count_patients_sum_exposure <- function(df, # nolintr #' 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. #' -#' -#' @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. #' @export #' #' @examples diff --git a/R/summarize_variables.R b/R/summarize_variables.R index 2046efe60a..6f3a48b9e3 100644 --- a/R/summarize_variables.R +++ b/R/summarize_variables.R @@ -141,13 +141,6 @@ s_summary <- function(x, #' @describeIn summarize_variables Method for `numeric` class. #' -#' @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. -#' #' @param control (`list`)\cr parameters for descriptive statistics details, specified by using #' the helper function [control_summarize_vars()]. Some possible parameter options are: #' * `conf_level` (`proportion`)\cr confidence level of the interval for mean and median. @@ -183,6 +176,13 @@ s_summary <- function(x, #' * `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 @@ -308,12 +308,6 @@ s_summary.numeric <- function(x, # nolint #' @describeIn summarize_variables Method for `factor` class. #' -#' @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()]. -#' #' @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. @@ -326,6 +320,12 @@ s_summary.numeric <- function(x, # nolint #' * `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 @@ -384,12 +384,15 @@ s_summary.factor <- function(x, #' @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 @@ -564,6 +567,10 @@ a_summary.logical <- make_afun( #' #' 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 #' corresponding customized methods. Then in order for the methods to be found, @@ -571,10 +578,6 @@ a_summary.logical <- make_afun( #' functions (and possibly others in the future), we provide a constructor that does this: #' [create_afun_summary()]. #' -#' @inheritParams argument_convention -#' -#' @return Combined formatted analysis function for use in [summarize_vars()]. -#' #' @export #' #' @examples diff --git a/R/survival_biomarkers_subgroups.R b/R/survival_biomarkers_subgroups.R index 4f07bf8feb..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,17 +41,18 @@ #' 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 @@ -64,6 +64,7 @@ NULL #' `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`, @@ -165,25 +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. #' #' @return An `rtables` table summarizing biomarker effects on survival by subgroup. #' -#' @seealso [h_tab_surv_one_biomarker()] which is used internally, [extract_survival_biomarkers()]. #' @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 04d2006b53..78fd8075ff 100644 --- a/R/survival_coxph_pairwise.R +++ b/R/survival_coxph_pairwise.R @@ -15,7 +15,6 @@ #' 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 diff --git a/R/survival_duration_subgroups.R b/R/survival_duration_subgroups.R index 3978e7ecd6..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,23 +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: +#' @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) @@ -219,17 +222,17 @@ a_survival_subgroups <- function(.formats = list( #' #' @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. #' @@ -378,16 +381,17 @@ 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. +#' @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, conf_level, diff --git a/R/utils.R b/R/utils.R index 2bf6b9ab58..9533fef676 100644 --- a/R/utils.R +++ b/R/utils.R @@ -85,8 +85,7 @@ 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. @@ -94,6 +93,8 @@ get_covariates <- function(covariates) { #' @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)) { diff --git a/R/utils_checkmate.R b/R/utils_checkmate.R index 2be2d150e5..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,7 +11,6 @@ #' @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. #' @@ -157,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 95b9074ff5..c6294c8f7d 100644 --- a/R/utils_factor.R +++ b/R/utils_factor.R @@ -142,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 @@ -158,6 +155,10 @@ bins_percent_labels <- function(probs, #' #' @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,6 +216,8 @@ 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. @@ -236,7 +239,9 @@ 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. @@ -261,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 @@ -275,6 +281,9 @@ fct_explicit_na_if <- function(x, condition, na_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_rtables.R b/R/utils_rtables.R index 601f979fd8..f494b355a5 100644 --- a/R/utils_rtables.R +++ b/R/utils_rtables.R @@ -96,8 +96,8 @@ cfun_by_flag <- function(analysis_var, #' #' @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, @@ -316,17 +316,17 @@ 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. #' +#' @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() %>% #' split_cols_by("ARM") %>% diff --git a/man/abnormal.Rd b/man/abnormal.Rd index 7644a71978..fbc7f6671e 100644 --- a/man/abnormal.Rd +++ b/man/abnormal.Rd @@ -86,9 +86,9 @@ 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.} +\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. } } \section{Functions}{ diff --git a/man/abnormal_by_marked.Rd b/man/abnormal_by_marked.Rd index 36ef19f104..1ba7aa7c01 100644 --- a/man/abnormal_by_marked.Rd +++ b/man/abnormal_by_marked.Rd @@ -78,11 +78,10 @@ the statistics from \code{s_count_abnormal_by_marked()} to the table layout. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Primary analysis variable \code{.var} indicates whether single, replicated -or last marked laboratory abnormality was observed (\code{factor}). -Additional analysis variables are \code{id} (\code{character} or \code{factor}) and \code{direction} (\code{factor}) -indicating the direction of the abnormality. -Denominator is number of patients with at least one valid measurement during the analysis. +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. diff --git a/man/abnormal_by_worst_grade.Rd b/man/abnormal_by_worst_grade.Rd index 952270bc2f..f1ce400a87 100644 --- a/man/abnormal_by_worst_grade.Rd +++ b/man/abnormal_by_worst_grade.Rd @@ -85,8 +85,8 @@ 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. diff --git a/man/assertions.Rd b/man/assertions.Rd index 7960dcffc3..741dda753b 100644 --- a/man/assertions.Rd +++ b/man/assertions.Rd @@ -106,7 +106,7 @@ Additional assertion functions which can be used together with the \code{checkma 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/c_label_n.Rd b/man/c_label_n.Rd index 3a2e4793cc..01b1e816bf 100644 --- a/man/c_label_n.Rd +++ b/man/c_label_n.Rd @@ -21,7 +21,7 @@ A \code{list} containing "row_count" with the row count value and the correct la 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/compare_variables.Rd b/man/compare_variables.Rd index 6a4c072a81..1aacc73b9f 100644 --- a/man/compare_variables.Rd +++ b/man/compare_variables.Rd @@ -302,6 +302,6 @@ lyt <- basic_table() \%>\% build_table(lyt, df = tern_ex_adsl) } \seealso{ -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()}. +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/count_cumulative.Rd b/man/count_cumulative.Rd index 743432ffdd..32add27595 100644 --- a/man/count_cumulative.Rd +++ b/man/count_cumulative.Rd @@ -131,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_occurrences.Rd b/man/count_occurrences.Rd index d8138f70d5..7afd6c2223 100644 --- a/man/count_occurrences.Rd +++ b/man/count_occurrences.Rd @@ -108,10 +108,7 @@ the statistics from \code{s_count_occurrences()} to the table layout. 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{ @@ -125,6 +122,12 @@ in \code{count_occurrences()}. 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/cox_regression_inter.Rd b/man/cox_regression_inter.Rd index 820ebbcf10..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.} diff --git a/man/cut_quantile_bins.Rd b/man/cut_quantile_bins.Rd index 0f5f52c6f9..53d7d866be 100644 --- a/man/cut_quantile_bins.Rd +++ b/man/cut_quantile_bins.Rd @@ -34,10 +34,12 @@ 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_survival_subgroups_colvars.Rd b/man/d_survival_subgroups_colvars.Rd index 897038aeda..181d14e73f 100644 --- a/man/d_survival_subgroups_colvars.Rd +++ b/man/d_survival_subgroups_colvars.Rd @@ -7,21 +7,23 @@ 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.} @@ -32,7 +34,9 @@ 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/extract_survival_biomarkers.Rd b/man/extract_survival_biomarkers.Rd index 4c69b1c8bb..743ff93ece 100644 --- a/man/extract_survival_biomarkers.Rd +++ b/man/extract_survival_biomarkers.Rd @@ -34,11 +34,10 @@ A \code{data.frame} with columns \code{biomarker}, \code{biomarker_label}, \code \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 739b7ede01..37549a1a94 100644 --- a/man/extract_survival_subgroups.Rd +++ b/man/extract_survival_subgroups.Rd @@ -34,7 +34,7 @@ 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 list of two elements: +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}. @@ -46,11 +46,10 @@ A named list of two elements: \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 4d9819e868..31fb097388 100644 --- a/man/extreme_format.Rd +++ b/man/extreme_format.Rd @@ -29,7 +29,7 @@ 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/fct_collapse_only.Rd b/man/fct_collapse_only.Rd index 2859014a2e..174e4b70d3 100644 --- a/man/fct_collapse_only.Rd +++ b/man/fct_collapse_only.Rd @@ -20,10 +20,15 @@ A modified \code{factor} with collapsed levels. Values and levels which are not 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 1491b82b06..111923e926 100644 --- a/man/fct_discard.Rd +++ b/man/fct_discard.Rd @@ -15,6 +15,8 @@ fct_discard(x, discard) 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 44132bc051..f58e2c7c32 100644 --- a/man/fct_explicit_na_if.Rd +++ b/man/fct_explicit_na_if.Rd @@ -17,7 +17,9 @@ fct_explicit_na_if(x, condition, 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_logistic.Rd b/man/fit_logistic.Rd index 7ba29244d7..14a7ae2389 100644 --- a/man/fit_logistic.Rd +++ b/man/fit_logistic.Rd @@ -32,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 c9b37e4e1c..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.} @@ -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 1d07f9c78c..ee5155c587 100644 --- a/man/fit_survival_step.Rd +++ b/man/fit_survival_step.Rd @@ -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/h_cox_regression.Rd b/man/h_cox_regression.Rd index 1721857d62..07f4c7b079 100644 --- a/man/h_cox_regression.Rd +++ b/man/h_cox_regression.Rd @@ -32,8 +32,7 @@ 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.} diff --git a/man/h_logistic_regression.Rd b/man/h_logistic_regression.Rd index 7dfcfcc2f2..512bbb0493 100644 --- a/man/h_logistic_regression.Rd +++ b/man/h_logistic_regression.Rd @@ -207,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_odds_ratio.Rd b/man/h_odds_ratio.Rd index 5aaf2595d1..59d3d6bdd7 100644 --- a/man/h_odds_ratio.Rd +++ b/man/h_odds_ratio.Rd @@ -26,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_response_biomarkers_subgroups.Rd b/man/h_response_biomarkers_subgroups.Rd index 12daa25701..63eed639b1 100644 --- a/man/h_response_biomarkers_subgroups.Rd +++ b/man/h_response_biomarkers_subgroups.Rd @@ -28,14 +28,16 @@ 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{ diff --git a/man/h_response_subgroups.Rd b/man/h_response_subgroups.Rd index a0865e5db8..1a9ed3d422 100644 --- a/man/h_response_subgroups.Rd +++ b/man/h_response_subgroups.Rd @@ -77,7 +77,7 @@ 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. +Main functionality is to prepare data for use in a layout-creating function. } \section{Functions}{ \itemize{ @@ -115,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_survival_biomarkers_subgroups.Rd b/man/h_survival_biomarkers_subgroups.Rd index f1b9e309ab..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. }} diff --git a/man/h_survival_duration_subgroups.Rd b/man/h_survival_duration_subgroups.Rd index c9f9ec59b3..017c11a033 100644 --- a/man/h_survival_duration_subgroups.Rd +++ b/man/h_survival_duration_subgroups.Rd @@ -83,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/incidence_rate.Rd b/man/incidence_rate.Rd index 2f8803c93a..497cfefad3 100644 --- a/man/incidence_rate.Rd +++ b/man/incidence_rate.Rd @@ -80,13 +80,15 @@ to avoid warnings from \code{rtables}.} \item{alpha}{(\code{numeric})\cr two-sided alpha-level for confidence interval.} } \value{ -\code{s_incidence_rate()} returns the following statistics: +\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()}}. diff --git a/man/odds_ratio.Rd b/man/odds_ratio.Rd index d04b68cd94..23c72e8790 100644 --- a/man/odds_ratio.Rd +++ b/man/odds_ratio.Rd @@ -105,12 +105,7 @@ 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{ @@ -124,6 +119,12 @@ variable names must be passed if a stratified analysis is required. 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/response_biomarkers_subgroups.Rd b/man/response_biomarkers_subgroups.Rd index 40f019f72e..b78fec90a5 100644 --- a/man/response_biomarkers_subgroups.Rd +++ b/man/response_biomarkers_subgroups.Rd @@ -14,14 +14,16 @@ 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. @@ -66,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 5f77a488d4..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.} @@ -91,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/split_cols_by_groups.Rd b/man/split_cols_by_groups.Rd index d2a830bce9..5236bddf2c 100644 --- a/man/split_cols_by_groups.Rd +++ b/man/split_cols_by_groups.Rd @@ -17,7 +17,8 @@ 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{ A layout object suitable for passing to further layouting functions. Adding @@ -27,11 +28,6 @@ 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/summarize_logistic.Rd b/man/summarize_logistic.Rd index 10690ae07f..d024a210ab 100644 --- a/man/summarize_logistic.Rd +++ b/man/summarize_logistic.Rd @@ -11,7 +11,7 @@ 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()}}. @@ -20,7 +20,7 @@ Adding this function to an \code{rtable} layout will add a logistic regression v \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 diff --git a/man/summarize_num_patients.Rd b/man/summarize_num_patients.Rd index cc63f563ec..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, diff --git a/man/survival_biomarkers_subgroups.Rd b/man/survival_biomarkers_subgroups.Rd index 066d13a4a2..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. }} @@ -44,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{ @@ -81,6 +82,7 @@ df <- extract_survival_biomarkers( data = adtte_f ) df + ## Table with default columns. tabulate_survival_biomarkers(df) diff --git a/man/survival_duration_subgroups.Rd b/man/survival_duration_subgroups.Rd index b0d4db0d08..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.} @@ -114,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/to_n.Rd b/man/to_n.Rd index b39bfe4573..361f768f6e 100644 --- a/man/to_n.Rd +++ b/man/to_n.Rd @@ -18,6 +18,8 @@ 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. } From ef246f0f8e7678e5f9178064e0af692b67b4f147 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Tue, 9 May 2023 16:29:19 -0400 Subject: [PATCH 20/20] Apply other suggestions from code review --- R/compare_variables.R | 2 +- R/count_values.R | 2 +- R/cox_regression.R | 4 ++-- R/coxph.R | 2 +- R/h_cox_regression.R | 10 +++++----- R/h_logistic_regression.R | 2 +- R/logistic_regression.R | 6 +++--- R/summarize_colvars.R | 5 ++--- R/summarize_coxreg.R | 12 ++++++------ R/summarize_variables.R | 7 +++---- inst/WORDLIST | 9 --------- man/compare_variables.Rd | 2 +- man/count_values_funs.Rd | 2 +- man/cox_regression.Rd | 10 +++++----- man/fit_coxreg.Rd | 2 +- man/h_cox_regression.Rd | 10 +++++----- man/h_logistic_regression.Rd | 2 +- man/logistic_regression_cols.Rd | 4 ++-- man/pairwise.Rd | 2 +- man/summarize_colvars.Rd | 5 ++--- man/summarize_logistic.Rd | 2 +- man/summarize_variables.Rd | 7 +++---- man/tidy_coxreg.Rd | 2 +- tests/testthat/test-coxreg.R | 2 +- tests/testthat/test-summarize_coxreg.R | 2 +- 25 files changed, 51 insertions(+), 64 deletions(-) diff --git a/R/compare_variables.R b/R/compare_variables.R index ede999d6aa..c3197a75bc 100644 --- a/R/compare_variables.R +++ b/R/compare_variables.R @@ -26,7 +26,7 @@ #' @include summarize_variables.R NULL -#' @describeIn compare_variables S3 generic statistics function to produce a comparison summary. +#' @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. diff --git a/R/count_values.R b/R/count_values.R index ebf44a7a2d..810f2580d8 100644 --- a/R/count_values.R +++ b/R/count_values.R @@ -13,7 +13,7 @@ #' @name count_values_funs NULL -#' @describeIn count_values_funs S3 generic statistics 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. diff --git a/R/cox_regression.R b/R/cox_regression.R index c1e16e8750..ac2558031d 100644 --- a/R/cox_regression.R +++ b/R/cox_regression.R @@ -195,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()`]. #' @@ -395,7 +395,7 @@ 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 #' * `fit_coxreg_multivar()` returns a `coxreg.multivar` class object which is a named list diff --git a/R/coxph.R b/R/coxph.R index 3e1de571f5..5287964fab 100644 --- a/R/coxph.R +++ b/R/coxph.R @@ -5,7 +5,7 @@ #' 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". #' diff --git a/R/h_cox_regression.R b/R/h_cox_regression.R index 33c2c7df2b..eff7234cef 100644 --- a/R/h_cox_regression.R +++ b/R/h_cox_regression.R @@ -105,9 +105,9 @@ 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 #' @@ -234,8 +234,8 @@ 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 diff --git a/R/h_logistic_regression.R b/R/h_logistic_regression.R index 453a611f58..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")` #' diff --git a/R/logistic_regression.R b/R/logistic_regression.R index 3772aec9a3..ff32b55d65 100644 --- a/R/logistic_regression.R +++ b/R/logistic_regression.R @@ -1,4 +1,4 @@ -#' Multi-Variable Logistic Regression Table +#' Multivariate Logistic Regression Table #' #' @description `r lifecycle::badge("stable")` #' @@ -286,11 +286,11 @@ 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 which creates a multi-variable column layout summarizing logistic +#' 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 diff --git a/R/summarize_colvars.R b/R/summarize_colvars.R index 48f1d579b9..d1010f9159 100644 --- a/R/summarize_colvars.R +++ b/R/summarize_colvars.R @@ -2,9 +2,8 @@ #' #' @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()`. diff --git a/R/summarize_coxreg.R b/R/summarize_coxreg.R index bf06e6c625..723e7b810a 100644 --- a/R/summarize_coxreg.R +++ b/R/summarize_coxreg.R @@ -61,7 +61,7 @@ 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 @@ -97,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") #' ) @@ -109,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) @@ -256,7 +256,7 @@ a_coxreg <- function(df, #' 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. @@ -271,7 +271,7 @@ a_coxreg <- function(df, #' #' @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 @@ -323,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_variables.R b/R/summarize_variables.R index 6f3a48b9e3..18f0f7d9c5 100644 --- a/R/summarize_variables.R +++ b/R/summarize_variables.R @@ -112,16 +112,15 @@ 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 -#' @describeIn summarize_variables S3 generic statistics function to produces a variable summary. +#' @describeIn summarize_variables S3 generic function to produces a variable summary. #' #' @return #' * `s_summary()` returns different statistics depending on the class of `x`. diff --git a/inst/WORDLIST b/inst/WORDLIST index b138f36f40..2cb989242a 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -36,9 +36,6 @@ Satterthwaite Schouten TLG TLGs -Wojciak -Wojciech -Yuyao agresti arcsine bimj @@ -60,7 +57,6 @@ lik lineplot lvl midp -multivariable nd onlinelibrary paramcd @@ -74,8 +70,6 @@ rds repo responder responders -roche -songy subtable subtables surv @@ -83,10 +77,7 @@ timepoint unformatted univariable unstratified -waddella wald wiley wilson wilsoncc -wojciak -wojciech diff --git a/man/compare_variables.Rd b/man/compare_variables.Rd index 1aacc73b9f..037f42bcfb 100644 --- a/man/compare_variables.Rd +++ b/man/compare_variables.Rd @@ -152,7 +152,7 @@ Comparison with a reference group for different \code{x} objects. } \section{Functions}{ \itemize{ -\item \code{s_compare()}: S3 generic statistics function to produce a comparison summary. +\item \code{s_compare()}: S3 generic function to produce a comparison summary. \item \code{s_compare(numeric)}: Method for \code{numeric} class. This uses the standard t-test to calculate the p-value. diff --git a/man/count_values_funs.Rd b/man/count_values_funs.Rd index 560eddb00e..de2b572c35 100644 --- a/man/count_values_funs.Rd +++ b/man/count_values_funs.Rd @@ -104,7 +104,7 @@ We can count the occurrence of specific values in a variable of interest. } \section{Functions}{ \itemize{ -\item \code{s_count_values()}: S3 generic statistics 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} class. diff --git a/man/cox_regression.Rd b/man/cox_regression.Rd index 1d67cf97a8..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.} @@ -198,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") ) @@ -210,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) @@ -271,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/fit_coxreg.Rd b/man/fit_coxreg.Rd index 3d6935cb14..fc11ff43df 100644 --- a/man/fit_coxreg.Rd +++ b/man/fit_coxreg.Rd @@ -61,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/h_cox_regression.Rd b/man/h_cox_regression.Rd index 07f4c7b079..0587eb5103 100644 --- a/man/h_cox_regression.Rd +++ b/man/h_cox_regression.Rd @@ -66,15 +66,15 @@ Helper functions used in \code{\link[=fit_coxreg_univar]{fit_coxreg_univar()}} a \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. -\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_logistic_regression.Rd b/man/h_logistic_regression.Rd index 512bbb0493..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) diff --git a/man/logistic_regression_cols.Rd b/man/logistic_regression_cols.Rd index 379cafff7b..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) } @@ -19,6 +19,6 @@ statistics \code{df}, \code{estimate}, \code{std_error}, \code{odds_ratio}, \cod \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 creates a multi-variable column layout summarizing logistic +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/pairwise.Rd b/man/pairwise.Rd index e10903d660..c1a5d7e81a 100644 --- a/man/pairwise.Rd +++ b/man/pairwise.Rd @@ -7,7 +7,7 @@ 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". diff --git a/man/summarize_colvars.Rd b/man/summarize_colvars.Rd index 946463d885..a0331f376c 100644 --- a/man/summarize_colvars.Rd +++ b/man/summarize_colvars.Rd @@ -34,9 +34,8 @@ 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_logistic.Rd b/man/summarize_logistic.Rd index d024a210ab..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 = "") } diff --git a/man/summarize_variables.Rd b/man/summarize_variables.Rd index d974d33e35..e9a2293304 100644 --- a/man/summarize_variables.Rd +++ b/man/summarize_variables.Rd @@ -252,13 +252,12 @@ 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()}: S3 generic statistics function to produces a variable summary. +\item \code{s_summary()}: S3 generic function to produces a variable summary. \item \code{s_summary(numeric)}: Method for \code{numeric} class. diff --git a/man/tidy_coxreg.Rd b/man/tidy_coxreg.Rd index b0bb60003c..2c06f2ba6b 100644 --- a/man/tidy_coxreg.Rd +++ b/man/tidy_coxreg.Rd @@ -42,7 +42,7 @@ Tidy the \code{\link[survival:coxph]{survival::coxph()}} results into a \code{da 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/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() %>%