[skip vbump] prepare for CRAN release

.Rbuildignore

@@ -15,3 +15,4 @@ SECURITY\.md
 ^Meta$
 ^\.vscode$
 ^pkgdown$
+LICENSE

DESCRIPTION

@@ -1,8 +1,8 @@
 Type: Package
 Package: chevron
 Title: Standard TLGs for Clinical Trials Reporting
-Version: 0.2.4.9021
-Date: 2023-12-18
+Version: 0.2.5
+Date: 2024-01-31
 Authors@R: c(
     person("Liming", "Li", , "[email protected]", role = c("aut", "cre")),
     person("Benoit", "Falquet", , "[email protected]", role = "aut"),
@@ -14,9 +14,12 @@ Authors@R: c(
     person("Tian", "Fang", , "[email protected]", role = "ctb"),
     person("F. Hoffmann-La Roche AG", role = c("cph", "fnd"))
   )
-Description: Standard Table, Listings, and Graphs (TLG) library used in
-    clinical trials.
-License: Apache License 2.0 | file LICENSE
+Description: Provide standard tables, listings, and graphs (TLGs) libraries used in
+    clinical trials. This package implements a structure to reformat the data with
+    'dunlin', create reporting tables using 'rtables' and 'tern' with standardized
+    input arguments to enable quick generation of standard outputs.
+    In addition, it also provides comprehensive data checks and script generation functionality.
+License: Apache License 2.0
 URL: https://insightsengineering.github.io/chevron/,
     https://github.com/insightsengineering/chevron/
 BugReports: https://github.com/insightsengineering/chevron/issues
@@ -25,9 +28,9 @@ Depends:
 Imports:
     checkmate (>= 2.1.0),
     dplyr (>= 1.1.0),
-    dunlin (>= 0.1.6.9002),
+    dunlin (>= 0.1.7),
     forcats (>= 1.0.0),
-    formatters (>= 0.5.4),
+    formatters (>= 0.5.5),
     ggplot2 (>= 3.4.0),
     glue (>= 1.0.0),
     grid,
@@ -37,10 +40,10 @@ Imports:
     nestcolor (>= 0.1.1),
     purrr (>= 0.3.0),
     rlang (>= 1.0.0),
-    rlistings (>= 0.2.6),
-    rtables (>= 0.6.5),
+    rlistings (>= 0.2.7),
+    rtables (>= 0.6.6),
     stringr (>= 1.4.1),
-    tern (>= 0.9.2),
+    tern (>= 0.9.3),
     tibble (>= 2.0.0),
     utils
 Suggests:
@@ -74,7 +77,7 @@ Encoding: UTF-8
 Language: en-US
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 Collate:
     'utils.R'
     'chevron_tlg-S4class.R'

NEWS.md

@@ -1,11 +1,11 @@
-# chevron 0.2.4.9021
+# chevron 0.2.5
 
 * `MNG01` plot can now be displayed without error bars and can display a continuous temporal scale on the `x` axis.
 * Add a `chevron_simple` class only contain main function.
 * Remove `details` argument in `script_funs`, add `name` argument.
 * In the `run` method, the argument passed through `...` are combined with the one passed through `user_arg`. `...` arguments have priority.
 * `AET05` preprocessing now filters on `"(AE|CQ|SMQ)TTE"` rather than `"AETTE"`.
-* Rename the dataset `ADAETTE` in `syn_data` object to `ADSAFTTE`.
+* Rename the dataset `ADAETTE` in `syn_data` object to `ADSAFTTE`. Trim the dataset to remove unused variables.
 * Use uppercase variable names in `AET05` and `AET05_ALL`.
 * The string replacing `NA` values in the tables is now controlled by the `tern_default_na_str` option set during package load.
 * Specified minimal version of package dependencies.

R/ael01_nollt.R

@@ -6,6 +6,7 @@
 #' @param dataset (`character`) the name of a table in the `adam_db` object.
 #' @param default_formatting (`list`) the default format of the listing columns. See [`rlistings::as_listing`].
 #' @param col_formatting (`list`) the format of specific listing columns. See [`rlistings::as_listing`].
+#' @returns the main function returns an `rlistings` object.
 #'
 #' @details
 #'  * Removes duplicate rows.
@@ -47,6 +48,7 @@ ael01_nollt_main <- function(adam_db,
 #' @describeIn ael01_nollt Preprocessing
 #'
 #' @inheritParams ael01_nollt_main
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #'
 #' @export
 #'
@@ -67,6 +69,7 @@ ael01_nollt_pre <- function(adam_db,
 #' @describeIn ael01_nollt Postprocessing
 #'
 #' @inheritParams gen_args
+#' @returns the postprocessing function returns an `rlistings` object or an `ElementaryTable` (null report).
 #'
 ael01_nollt_post <- function(tlg, ...) {
   if (nrow(tlg) == 0) tlg <- null_report

R/aet01.R

@@ -5,6 +5,7 @@
 #' @inheritParams gen_args
 #' @param anl_vars Named (`list`) of (`character`) variables the safety variables to be summarized.
 #' @param anl_lbls (`character`) of analysis labels.
+#' @returns the main function returns an `rtables` object.
 #'
 #' @details
 #'  * Does not remove rows with zero counts by default.
@@ -75,6 +76,7 @@ aet01_main <- function(adam_db,
 #' @param anl_vars Named (`list`) of analysis variables.
 #' @param anl_lbls (`character`) of labels.
 #' @param lbl_vars Named (`list`) of analysis labels.
+#' @returns a `PreDataTableLayouts` object.
 #' @keywords internal
 #'
 aet01_lyt <- function(arm_var,
@@ -126,6 +128,7 @@ aet01_lyt <- function(arm_var,
 #' @describeIn aet01 Preprocessing
 #'
 #' @inheritParams aet01_main
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #'
 #' @export
 #'
@@ -160,6 +163,7 @@ aet01_pre <- function(adam_db, ...) {
 #' @describeIn aet01 Postprocessing
 #'
 #' @inheritParams gen_args
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #'
 #' @export
 #'

R/aet01_aesi.R

@@ -5,6 +5,7 @@
 #' @inheritParams gen_args
 #' @param aesi_vars (`character`) the `AESI` variables to be included in the summary. Defaults to `NA`.
 #' @param grade_groups (`list`) the grade groups to be displayed.
+#' @returns the main function returns an `rtables` object.
 #' @details
 #'  * Does not remove rows with zero counts by default.
 #'
@@ -78,7 +79,7 @@ aet01_aesi_main <- function(adam_db,
 #'
 #' @inheritParams gen_args
 #' @param lbl_aesi_vars (`character`) the labels of the `AESI` variables to be summarized.
-#'
+#' @returns a `PreDataTableLayouts` object.
 #' @keywords internal
 #'
 aet01_aesi_lyt <- function(arm_var,
@@ -118,6 +119,7 @@ aet01_aesi_lyt <- function(arm_var,
 #' @describeIn aet01_aesi Preprocessing
 #'
 #' @inheritParams aet01_aesi_main
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #'
 #' @export
 #'
@@ -203,6 +205,7 @@ aet01_aesi_pre <- function(adam_db,
 #' @describeIn aet01_aesi Postprocessing
 #'
 #' @inheritParams gen_args
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #'
 #' @export
 #'

R/aet02.R

@@ -12,6 +12,7 @@ aet02_label <- c(
 #'
 #' @inheritParams gen_args
 #' @param summary_labels (`list`) of summarize labels. See details.
+#' @returns the main function returns an `rtables` object.
 #'
 #' @details
 #'  * Numbers represent absolute numbers of subject and fraction of `N`, or absolute number of event when specified.
@@ -76,7 +77,7 @@ aet02_main <- function(adam_db,
 #' @describeIn aet02 Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet02_pre <- function(adam_db, row_split_var = "AEBODSYS", ...) {
@@ -91,7 +92,7 @@ aet02_pre <- function(adam_db, row_split_var = "AEBODSYS", ...) {
 #' @describeIn aet02 Postprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #' @export
 #'
 aet02_post <- function(tlg, row_split_var = "AEBODSYS", prune_0 = TRUE, ...) {

R/aet03.R

@@ -3,6 +3,7 @@
 #' @describeIn aet03 Main TLG function
 #'
 #' @inheritParams gen_args
+#' @returns the main function returns an `rtables` object.
 #'
 #' @details
 #'  * Default Adverse Events by Greatest Intensity table.
@@ -54,7 +55,7 @@ aet03_main <- function(adam_db,
 #' @param lbl_aebodsys (`string`) text label for `AEBODSYS`.
 #' @param lbl_aedecod (`string`) text label for `AEDECOD`.
 #' @param intensity_grade (`character`) describing the intensity levels present in the dataset.
-#'
+#' @returns a `PreDataTableLayouts` object.
 #' @keywords internal
 #'
 aet03_lyt <- function(arm_var,
@@ -107,7 +108,7 @@ aet03_lyt <- function(arm_var,
 #' @describeIn aet03 Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet03_pre <- function(adam_db, ...) {
@@ -127,7 +128,7 @@ aet03_pre <- function(adam_db, ...) {
 #' @describeIn aet03 Postprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #' @export
 #'
 aet03_post <- function(tlg, prune_0 = TRUE, ...) {

R/aet04.R

@@ -4,6 +4,7 @@
 #'
 #' @inheritParams gen_args
 #' @param grade_groups (`list`) putting in correspondence toxicity grades and labels.
+#' @returns the main function returns an `rtables` object.
 #'
 #' @details
 #'  * Numbers represent absolute numbers of patients and fraction of `N`, or absolute number of event when specified.
@@ -70,7 +71,7 @@ aet04_main <- function(adam_db,
 #' @param lbl_aebodsys (`string`) text label for `AEBODSYS`.
 #' @param lbl_aedecod (`string`) text label for `AEDECOD`.
 #' @param grade_groups (`list`) putting in correspondence toxicity grades and labels.
-#'
+#' @returns a `PreDataTableLayouts` object.
 #' @keywords internal
 #'
 aet04_lyt <- function(arm_var,
@@ -130,7 +131,7 @@ aet04_lyt <- function(arm_var,
 #' @describeIn aet04 Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet04_pre <- function(adam_db, ...) {
@@ -148,7 +149,7 @@ aet04_pre <- function(adam_db, ...) {
 #' @describeIn aet04 Postprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #' @export
 #'
 aet04_post <- function(tlg, prune_0 = TRUE, ...) {

R/aet05.R

@@ -6,6 +6,7 @@
 #' @param dataset (`string`) the name of a table in the `adam_db` object.
 #' @param arm_var (`string`) the arm variable used for arm splitting.
 #' @param ... Further arguments passed to `tern::control_incidence_rate()`.
+#' @returns the main function returns an `rtables` object.
 #'
 #' @details
 #'  * Total patient-years at risk is the sum over all patients of the time intervals (in years).
@@ -68,6 +69,7 @@ aet05_main <- function(adam_db,
 #' @param n_events (`string`) variable to count the number of events observed.
 #' @param control (`list`) parameters for estimation details, specified by using the helper function
 #' control_incidence_rate().
+#' @returns a `PreDataTableLayouts` object.
 #'
 #' @keywords internal
 #'
@@ -90,7 +92,7 @@ aet05_lyt <- function(arm_var,
 #' @describeIn aet05 Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet05_pre <- function(adam_db, dataset = "adsaftte", ...) {
@@ -106,7 +108,7 @@ aet05_pre <- function(adam_db, dataset = "adsaftte", ...) {
 #' @describeIn aet05 Postprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #' @export
 #'
 aet05_post <- function(tlg, prune_0 = FALSE, ...) {

R/aet05_all.R

@@ -3,7 +3,7 @@
 #' @describeIn aet05_all Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet05_all_pre <- function(adam_db, dataset = "adsaftte", ...) {

R/aet10.R

@@ -3,7 +3,7 @@
 #' @describeIn aet10 Main TLG function
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the main function returns an `rtables` object
 #' @details
 #'  * Numbers represent absolute numbers of subject and fraction of `N`, or absolute number of event when specified.
 #'  * Remove zero-count rows unless overridden with `prune_0 = FALSE`.
@@ -47,7 +47,7 @@ aet10_main <- function(adam_db,
 #'
 #' @inheritParams gen_args
 #' @param lbl_aedecod (`character`) text label for `AEDECOD`.
-#'
+#' @returns a `PreDataTableLayouts` object.
 #' @keywords internal
 #'
 aet10_lyt <- function(arm_var,
@@ -65,7 +65,7 @@ aet10_lyt <- function(arm_var,
 #' @describeIn aet10 Preprocessing
 #'
 #' @inheritParams gen_args
-#'
+#' @returns the preprocessing function returns a `list` of `data.frame`.
 #' @export
 #'
 aet10_pre <- function(adam_db, ...) {
@@ -79,7 +79,7 @@ aet10_pre <- function(adam_db, ...) {
 #'
 #' @inheritParams gen_args
 #' @param atleast given cut-off in numeric format, default is `0.05`
-#'
+#' @returns the postprocessing function returns an `rtables` object or an `ElementaryTable` (null report).
 #' @export
 #'
 aet10_post <- function(tlg, atleast = 0.05, ...) {

R/assertions.R

@@ -3,6 +3,7 @@
 #' Check variable only has one unique value.
 #' @param x value vector.
 #' @param label (`string`) label of input.
+#' @returns invisible `NULL` or an error message if the criteria are not fulfilled.
 #' @export
 assert_single_value <- function(x, label = deparse(substitute(x))) {
   unique_param_val <- unique(x)
@@ -26,6 +27,7 @@ assert_single_value <- function(x, label = deparse(substitute(x))) {
 #' @param na_ok (`flag`) whether NA value is allowed
 #' @param empty_ok (`flag`) whether length 0 value is allowed.
 #' @param ... Further arguments to methods.
+#' @returns invisible `NULL` or an error message if the criteria are not fulfilled.
 #' @export
 assert_valid_var <- function(x, label, na_ok, empty_ok, ...) {
   UseMethod("assert_valid_var")
@@ -108,7 +110,7 @@ assert_valid_var.default <- function(x, label = deparse(substitute(x)), na_ok =
 #' @param types Named (`list`) of type of the input.
 #' @param ... further arguments for `assert_valid_var`. Please note that different methods have different arguments
 #' so if provided make sure the variables to check is of the same class.
-#'
+#' @returns invisible `TRUE` or an error message if the criteria are not fulfilled.
 #' @export
 assert_valid_variable <- function(df, vars, label = deparse(substitute(df)), types = NULL, ...) {
   assert_names(colnames(df), must.include = vars, what = "colnames")
@@ -137,6 +139,7 @@ assert_valid_variable <- function(df, vars, label = deparse(substitute(df)), typ
 #' @param x Object to check the type.
 #' @param types (`character`) possible types to check.
 #' @param label (`string`) label.
+#' @returns invisible `NULL` or an error message if the criteria are not fulfilled.
 assert_valid_type <- function(x, types, label = deparse(substitute(x))) {
   if (!any(vapply(types, is, object = x, FUN.VALUE = TRUE))) {
     abort(
@@ -157,6 +160,7 @@ assert_valid_type <- function(x, types, label = deparse(substitute(x))) {
 #' @param var (`string`) variable to check.
 #' @param lab1 (`string`) label hint for `df1`.
 #' @param lab2 (`string`) label hint for `df2`.
+#' @returns invisible `NULL` or an error message if the criteria are not fulfilled.
 assert_valid_var_pair <- function(df1, df2, var, lab1 = deparse(substitute(df1)), lab2 = deparse(substitute(df2))) {
   assert_data_frame(df1)
   assert_data_frame(df2)