Clean up documentation (#914)

Closes #913 --------- Signed-off-by: Emily de la Rua <[email protected]>
insightsengineering · May 15, 2023 · 36adf45 · 36adf45
1 parent c64ee78
commit 36adf45
Show file tree

Hide file tree

Showing 218 changed files with 1,037 additions and 1,133 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
diff --git a/R/abnormal.R b/R/abnormal.R
@@ -27,6 +27,7 @@ NULL
 
 #' @describeIn abnormal Statistics function which counts patients with abnormal range values
 #'   for a single `abnormal` level.
+#'
 #' @param exclude_base_abn (`flag`)\cr whether to exclude subjects with baseline abnormality
 #'   from numerator and denominator.
 #'
@@ -133,7 +134,6 @@ a_count_abnormal <- make_afun(
 #'   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.
 #' basic_table() %>%
@@ -160,6 +160,8 @@ a_count_abnormal <- make_afun(
 #'     variables = list(id = "ID", baseline = "BL_RANGE")
 #'   ) %>%
 #'   build_table(df2)
+#'
+#' @export
 count_abnormal <- function(lyt,
                            var,
                            ...,

diff --git a/R/abnormal_by_baseline.R b/R/abnormal_by_baseline.R
@@ -36,6 +36,7 @@ NULL
 #' Description function that produces the labels for [s_count_abnormal_by_baseline()].
 #'
 #' @inheritParams abnormal_by_baseline
+#'
 #' @return Abnormal category labels for [s_count_abnormal_by_baseline()].
 #'
 #' @examples

diff --git a/R/abnormal_by_marked.R b/R/abnormal_by_marked.R
@@ -95,7 +95,7 @@ s_count_abnormal_by_marked <- function(df,
   checkmate::assert_multi_class(df[[variables$id]], classes = c("factor", "character"))
 
 
-  first_row <- .spl_context[.spl_context$split == variables[["param"]], ] # nolint
+  first_row <- .spl_context[.spl_context$split == variables[["param"]], ]
   # Patients in the denominator have at least one post-baseline visit.
   subj <- first_row$full_parent_df[[1]][[variables[["id"]]]]
   subj_cur_col <- subj[first_row$cur_col_subset[[1]]]
@@ -193,7 +193,6 @@ a_count_abnormal_by_marked <- make_afun(
 #'   ) %>%
 #'   build_table(df = df)
 #'
-#'
 #' basic_table() %>%
 #'   split_cols_by("ARMCD") %>%
 #'   split_rows_by("PARAMCD") %>%

diff --git a/R/abnormal_by_worst_grade.R b/R/abnormal_by_worst_grade.R
@@ -106,7 +106,7 @@ s_count_abnormal_by_worst_grade <- function(df, # nolint
 
   # To verify that the `split_rows_by` are performed with correct variables.
   checkmate::assert_subset(c(variables[["param"]], variables[["grade_dir"]]), .spl_context$split)
-  first_row <- .spl_context[.spl_context$split == variables[["param"]], ] # nolint
+  first_row <- .spl_context[.spl_context$split == variables[["param"]], ]
   x_lvls <- c(setdiff(levels(df[[.var]]), "0"), "Any")
   result <- split(numeric(0), factor(x_lvls))
 

diff --git a/R/analyze_vars_in_cols.R b/R/analyze_vars_in_cols.R
@@ -13,7 +13,7 @@
 #' 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()].
+#' @seealso [summarize_vars()], [rtables::analyze_colvars()].
 #'
 #' @examples
 #' library(dplyr)

diff --git a/R/combination_function.R b/R/combination_function.R
@@ -14,9 +14,6 @@
 #' @exportClass CombinationFunction
 #' @export CombinationFunction
 #'
-#' @aliases CombinationFunction-class
-#' @name combination_function
-#'
 #' @examples
 #' higher <- function(a) {
 #'   force(a)
@@ -40,13 +37,16 @@
 #' c2 <- lower(10)
 #' c3 <- higher(5) & lower(10)
 #' c3(7)
+#'
+#' @aliases CombinationFunction-class
+#' @name combination_function
 CombinationFunction <- methods::setClass("CombinationFunction", contains = "function") # nolint
 
 #' @describeIn combination_function Logical "AND" combination of `CombinationFunction` functions.
 #'   The resulting object is of the same class, and evaluates the two argument functions. The result
 #'   is then the "AND" of the two individual results.
-#' @export
 #'
+#' @export
 methods::setMethod(
   "&",
   signature = c(e1 = "CombinationFunction", e2 = "CombinationFunction"),
@@ -60,8 +60,8 @@ methods::setMethod(
 #' @describeIn combination_function Logical "OR" combination of `CombinationFunction` functions.
 #'   The resulting object is of the same class, and evaluates the two argument functions. The result
 #'   is then the "OR" of the two individual results.
-#' @export
 #'
+#' @export
 methods::setMethod(
   "|",
   signature = c(e1 = "CombinationFunction", e2 = "CombinationFunction"),
@@ -75,8 +75,8 @@ methods::setMethod(
 #' @describeIn combination_function Logical negation of `CombinationFunction` functions.
 #'   The resulting object is of the same class, and evaluates the original function. The result
 #'   is then the opposite of this results.
-#' @export
 #'
+#' @export
 methods::setMethod(
   "!",
   signature = c(x = "CombinationFunction"),

diff --git a/R/compare_variables.R b/R/compare_variables.R
@@ -32,7 +32,6 @@ NULL
 #' * `s_compare()` returns output of [s_summary()] and comparisons versus the reference group in the form of p-values.
 #'
 #' @export
-#'
 s_compare <- function(x,
                       .ref_group,
                       .in_ref_col,
@@ -42,9 +41,8 @@ s_compare <- function(x,
 
 #' @describeIn compare_variables Method for `numeric` class. This uses the standard t-test
 #'   to calculate the p-value.
-#' @method s_compare numeric
 #'
-#' @export
+#' @method s_compare numeric
 #'
 #' @examples
 #' # `s_compare.numeric`
@@ -57,6 +55,8 @@ s_compare <- function(x,
 #'
 #' ## Empty numeric does not fail, it returns NA-filled items and no p-value.
 #' s_compare(numeric(), .ref_group = numeric(), .in_ref_col = FALSE)
+#'
+#' @export
 s_compare.numeric <- function(x,
                               .ref_group,
                               .in_ref_col,
@@ -78,11 +78,11 @@ s_compare.numeric <- function(x,
 
 #' @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).
-#' @method s_compare factor
 #'
-#' @export
+#' @method s_compare factor
 #'
 #' @examples
 #' # `s_compare.factor`
@@ -97,6 +97,8 @@ s_compare.numeric <- function(x,
 #' y <- explicit_na(factor(c("a", "b", "c", NA)))
 #' s_compare(x = x, .ref_group = y, .in_ref_col = FALSE, na.rm = TRUE)
 #' s_compare(x = x, .ref_group = y, .in_ref_col = FALSE, na.rm = FALSE)
+#'
+#' @export
 s_compare.factor <- function(x,
                              .ref_group,
                              .in_ref_col,
@@ -137,8 +139,10 @@ s_compare.factor <- function(x,
 
 #' @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
@@ -186,9 +190,8 @@ s_compare.character <- function(x,
 
 #' @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`.
-#' @method s_compare logical
 #'
-#' @export
+#' @method s_compare logical
 #'
 #' @examples
 #' # `s_compare.logical`
@@ -203,6 +206,8 @@ s_compare.character <- function(x,
 #' y <- c(NA, NA, NA, NA, FALSE)
 #' s_compare(x, .ref_group = y, .in_ref_col = FALSE, na.rm = TRUE)
 #' s_compare(x, .ref_group = y, .in_ref_col = FALSE, na.rm = FALSE)
+#'
+#' @export
 s_compare.logical <- function(x,
                               .ref_group,
                               .in_ref_col,
@@ -245,7 +250,6 @@ s_compare.logical <- function(x,
 #' * `a_compare()` returns the corresponding list with formatted [rtables::CellValue()].
 #'
 #' @export
-#'
 a_compare <- function(x,
                       .ref_group,
                       .in_ref_col,
@@ -255,7 +259,6 @@ a_compare <- function(x,
 }
 
 #' @describeIn compare_variables Formatted analysis function method for `numeric` class.
-#' @export
 #'
 #' @examples
 #' # `a_compare.numeric`
@@ -265,6 +268,8 @@ a_compare <- function(x,
 #'   .in_ref_col = FALSE,
 #'   .var = "bla"
 #' )
+#'
+#' @export
 a_compare.numeric <- make_afun(
   s_compare.numeric,
   .formats = c(
@@ -288,7 +293,6 @@ a_compare.numeric <- make_afun(
 )
 
 #' @describeIn compare_variables Formatted analysis function method for `factor` class.
-#' @export
 #'
 #' @examples
 #' # `a_compare.factor`
@@ -301,6 +305,8 @@ a_compare.numeric <- make_afun(
 #' x <- factor(c("a", "a", "b", "c", "a"))
 #' y <- factor(c("a", "a", "b", "c"))
 #' afun(x, .ref_group = y, .in_ref_col = FALSE)
+#'
+#' @export
 a_compare.factor <- make_afun(
   s_compare.factor,
   .formats = .a_compare_counts_formats,
@@ -309,7 +315,6 @@ a_compare.factor <- make_afun(
 )
 
 #' @describeIn compare_variables Formatted analysis function method for `character` class.
-#' @export
 #'
 #' @examples
 #' # `a_compare.character`
@@ -320,6 +325,8 @@ a_compare.factor <- make_afun(
 #' x <- c("A", "B", "A", "C")
 #' y <- c("B", "A", "C")
 #' afun(x, .ref_group = y, .in_ref_col = FALSE, .var = "x", verbose = FALSE)
+#'
+#' @export
 a_compare.character <- make_afun(
   s_compare.character,
   .formats = .a_compare_counts_formats,
@@ -328,7 +335,6 @@ a_compare.character <- make_afun(
 )
 
 #' @describeIn compare_variables Formatted analysis function method for `logical` class.
-#' @export
 #'
 #' @examples
 #' # `a_compare.logical`
@@ -338,6 +344,8 @@ a_compare.character <- make_afun(
 #' x <- c(TRUE, FALSE, FALSE, TRUE, TRUE)
 #' y <- c(TRUE, FALSE)
 #' afun(x, .ref_group = y, .in_ref_col = FALSE)
+#'
+#' @export
 a_compare.logical <- make_afun(
   s_compare.logical,
   .formats = .a_compare_counts_formats,
@@ -362,7 +370,6 @@ a_compare.logical <- make_afun(
 #'   functions (and possibly others in the future), we provide a constructor that does this:
 #'   [create_afun_compare()].
 #'
-#' @export
 #' @seealso [compare_vars()]
 #'
 #' @examples
@@ -390,6 +397,8 @@ a_compare.logical <- make_afun(
 #'     show_labels = "visible"
 #'   )
 #' build_table(lyt, df = tern_ex_adsl)
+#'
+#' @export
 create_afun_compare <- function(.stats = NULL,
                                 .formats = NULL,
                                 .labels = NULL,
@@ -470,7 +479,6 @@ create_afun_compare <- function(.stats = NULL,
 #'   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.
 #'
-#'
 #' @examples
 #' # `compare_vars()` in `rtables` pipelines
 #'

diff --git a/R/control_incidence_rate.R b/R/control_incidence_rate.R
@@ -14,10 +14,12 @@
 #'
 #' @return A list of components with the same names as the arguments.
 #'
-#' @export
+#' @seealso [incidence_rate]
+#'
 #' @examples
 #' control_incidence_rate(0.9, "exact", "month", 100)
-#' @seealso [incidence_rate]
+#'
+#' @export
 control_incidence_rate <- function(conf_level = 0.95,
                                    conf_type = c("normal", "normal_log", "exact", "byar"),
                                    time_unit_input = c("year", "day", "week", "month"),

diff --git a/R/control_logistic.R b/R/control_logistic.R
@@ -5,16 +5,15 @@
 #' This is an auxiliary function for controlling arguments for logistic regression models.
 #' `conf_level` refers to the confidence level used for the Odds Ratio CIs.
 #'
+#' @inheritParams argument_convention
 #' @param response_definition (`string`)\cr the definition of what an event is in terms of `response`.
 #'   This will be used when fitting the logistic regression model on the left hand side of the formula.
 #'   Note that the evaluated expression should result in either a logical vector or a factor with 2
 #'   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.
 #' control_logistic()
@@ -24,6 +23,8 @@
 #'
 #' # Use a different response definition.
 #' control_logistic(response_definition = "I(response %in% c('CR', 'PR'))")
+#'
+#' @export
 control_logistic <- function(response_definition = "response",
                              conf_level = 0.95) {
   checkmate::assert_true(grepl("response", response_definition))

diff --git a/R/control_step.R b/R/control_step.R
@@ -11,12 +11,12 @@
 #'   covered in each window. Suggest `TRUE` if the biomarker variable is not uniformly
 #'   distributed.
 #' @param bandwidth (`number` or `NULL`)\cr indicating the bandwidth of each window.
-#'    Depending on the argument `use_percentile`, it can be either the length of actual-value
-#'    windows on the real biomarker scale, or percentage windows.
-#'    If `use_percentile = TRUE`, it should be a number between 0 and 1.
-#'    If `NULL`, treat the bandwidth to be infinity, which means only one global model will be fitted.
-#'    By default, `0.25` is used for percentage windows and one quarter of the range of the `biomarker`
-#'    variable for actual-value windows.
+#'   Depending on the argument `use_percentile`, it can be either the length of actual-value
+#'   windows on the real biomarker scale, or percentage windows.
+#'   If `use_percentile = TRUE`, it should be a number between 0 and 1.
+#'   If `NULL`, treat the bandwidth to be infinity, which means only one global model will be fitted.
+#'   By default, `0.25` is used for percentage windows and one quarter of the range of the `biomarker`
+#'   variable for actual-value windows.
 #' @param degree (`count`)\cr the degree of polynomial function of the biomarker as an interaction term
 #'   with the treatment arm fitted at each window. If 0 (default), then the biomarker variable
 #'   is not included in the model fitted in each biomarker window.