Merge branch 'main' into propagation-march-2024

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: tern
 Title: Create Common TLGs Used in Clinical Trials
-Version: 0.9.3.9031
-Date: 2024-04-05
+Version: 0.9.3.9032
+Date: 2024-04-12
 Authors@R: c(
     person("Joe", "Zhu", , "[email protected]", role = c("aut", "cre")),
     person("Daniel", "Sabanés Bové", , "[email protected]", role = "aut"),
@@ -122,6 +122,7 @@ Collate:
     'fit_rsp_step.R'
     'fit_survival_step.R'
     'g_forest.R'
+    'g_ipp.R'
     'g_km.R'
     'g_lineplot.R'
     'g_step.R'
@@ -141,7 +142,6 @@ Collate:
     'h_survival_duration_subgroups.R'
     'imputation_rule.R'
     'incidence_rate.R'
-    'individual_patient_plot.R'
     'logistic_regression.R'
     'missing_data.R'
     'odds_ratio.R'

NEWS.md

@@ -1,4 +1,4 @@
-# tern 0.9.3.9031
+# tern 0.9.3.9032
 
 ### New Features
 * Refactored `g_forest` to output a `ggplot` object instead of a `grob` object.
@@ -29,6 +29,7 @@
 * Began deprecation of no longer used Kaplan-Meier helper functions `h_ggkm`, `h_decompose_gg`, `h_km_layout`, `h_grob_tbl_at_risk`, `h_grob_median_surv`, `h_grob_y_annot`, and `h_grob_coxph`.
 * Began deprecation of `grob`/`grid` related functions `stack_grobs`, `arrange_grobs`, and `draw_grob` which are no longer used in `tern`.
 * Removed `vdiffr` package from Suggests in DESCRIPTION file.
+* Renamed `individual_patient_plot.R` to `g_ipp.R`. 
 
 # tern 0.9.3
 
@@ -43,7 +44,7 @@
 * Added list containing default statistics for each method group, `tern_default_stats`.
 * Added summarize function version of `count_occurrences` analyze function, `summarize_occurrences`.
 * Added referential footnotes to `surv_time` for censored range observations, controlled via the `ref_fn_censor` parameter.
-* Added helper function `h_adlb_abnormal_by_worst_grade` to prepare `ADLB` data to use as input in `count_abnormal_by_worst_grade`.
+* Added helper function `h_adlb_abnormal_by_worst_grade` to prepare ADLB data to use as input in `count_abnormal_by_worst_grade`.
 * Added `s_bland_altman` function to assess agreement between two numerical vectors.
 * Added function `rtable2gg` that converts `rtable` objects to `ggplot` objects.
 * Added helper function to set default `na_str` globally with `set_default_na_str()` and added `default_na_str()` for all interested functions.
@@ -236,7 +237,7 @@
   repetition when paginating.
 * Updated tests to use `testthat` 3rd edition and replaced applicable tests with snapshot testing.
 * Updated `summarize_ancova` examples to use `iris` dataset instead of `scda` data.
-* Created vignette which saves cached synthetic `CDISC` dataset files to the `data/` folder and
+* Created vignette which saves cached synthetic CDISC dataset files to the `data/` folder and
   generated cached synthetic datasets.
 * Updated all examples/tests to use datasets from the `data/` folder instead of `scda` datasets.
 * Removed all template tests from `tern`. These tests are in internal repo `scda.test`.
@@ -253,7 +254,7 @@
 # tern 0.7.10
 
 ### New Features
-* Added stratified `Newcombe` and stratified Wilson statistics to `estimate_proportion` and
+* Added stratified Newcombe and stratified Wilson statistics to `estimate_proportion` and
   `estimate_proportion_diff` with relative tests.
 * Added `stat_mean_pval`, a new summary statistic to calculate the p-value of
   the mean.
@@ -271,7 +272,7 @@
   log-rank test instead of Cox Proportional-Hazards Model.
 * Implemented `nestcolor` in all examples by adapting `g_km`, `g_ipp`,
   `g_waterfall`, `g_step`, `g_lineplot`, and `g_forest`.
-* Added parameters `interaction_y` and `interaction_item` in `ANCOVA` to make the
+* Added parameters `interaction_y` and `interaction_item` in ANCOVA to make the
   interaction calculations available.
 * Added new parameter `footnotes` to add footnotes to `g_km`.
 
@@ -368,7 +369,7 @@
   `nestcolor::color_palette` and `nestcolor::theme_nest`, respectively.
 * Removed deprecated functions: `color_palette`, `color_palette_core`,
   `h_set_nest_theme`, `s_cox_univariate`.
-* Removed deprecated `mmrm` functions: `fit_mmrm`, `g_mmrm_diagnostic`,
+* Removed deprecated MMRM functions: `fit_mmrm`, `g_mmrm_diagnostic`,
   `g_mmrm_lsmeans`, `as.rtable.mmrm`, `h_mmrm_fixed`, `h_mmrm_cov`,
   `h_mmrm_diagnostic`, `tidy.mmrm`, `s_mmrm_lsmeans`, `s_mmrm_lsmeans_single`,
   `summarize_lsmeans`.
@@ -414,7 +415,7 @@
 
 * Enhanced `g_lineplot` with table to automatically scale the table height and return a `ggplot` object.
 * Enhanced `g_ipp` with caption argument and adjust the position.
-* Enhanced `prop_diff`, `tern` function and related functions to be able to apply a continuity correction in the `Newcombe` method.
+* Enhanced `prop_diff`, `tern` function and related functions to be able to apply a continuity correction in the Newcombe method.
 * Enhanced `summarize_numeric_in_columns` and `summarize_variables` to allow factor/character summary and to be able to summarize the number of `BLQs` in `AVALC` from `ADPC` dataset.
 * Updated order of summarize variables stats in manual for order consistency.
 * Added a `sum` option to `summarize_variables`.
@@ -435,7 +436,7 @@
 
 ### Breaking changes
 
-* Move `MMRM` into a separate package `tern.mmrm`.
+* Move MMRM into a separate package `tern.mmrm`.
 
 ### New features
 
@@ -479,7 +480,7 @@
 ### New features
 * Added functions to estimate continuous biomarker effects across subgroups for survival and binary response endpoints, used to produce corresponding forest plots, see `survival_biomarkers_subgroups` and `response_biomarkers_subgroups`.
 * Added `g_lineplot` plot function, including new `h_format_row` helper function and `control_lineplot_vars` function. Removed `g_summary_by`.
-* Added new safety helper function `h_stack_by_baskets` to stack events in `SMQ` and/or `CQ` basket flag in `ADAE` data set.
+* Added new safety helper function `h_stack_by_baskets` to stack events in SMQ and/or CQ basket flag in ADAE data set.
 
 ### Enhancements
 * Added a couple of new statistics to `s_summary.numeric`. Added `names` attribute to each element of the final list returned by the `s_summary.numeric` function. Added `summary_formats` and `summary_labels` helper functions.
@@ -493,7 +494,7 @@
 * Fixed `prop_diff_cmh` to handle edge case of no FALSE (or TRUE) responses.
 * Enhanced `g_mmrm_diagnostic` to improve error handling when data is not amenable to the Locally Weighted Scatterplot Smoothing.
 * Fixes in `g_km`:
-  * Plot can now display any combination of the annotation tables for number of patients at risk, median survival time, and `CoxPH` summary.
+  * Plot can now display any combination of the annotation tables for number of patients at risk, median survival time, and Cox-PH summary.
   * Function will return a warning instead of an error if the `arm` variable includes a single level and `annot_coxph = TRUE`.
   * Lines in the plot now start at time 0 and probability 1.
   * Category labels can include the equals sign.
@@ -513,7 +514,7 @@
   * `summarize_patients_exposure_in_cols` tabulates patient counts and sum of exposure across all patients.
 
 ### Enhancements
-* Enhanced `mmrm` related functions for fitting models without `arm` variable.
+* Enhanced MMRM-related functions for fitting models without `arm` variable.
 * Updated `cox_regression` to work without covariates. Also in case of interaction model summary, p-values for main effect coefficients are no longer displayed.
 * Descriptive statistics returned by `summarize_vars` now include quantiles. `summarize_vars` now accepts the control function `control_summarize_vars` to specify details about confidence level for mean and median and quantile details. The `control` argument replaces `conf_level`.
 * Added `var_labels` and `show_labels` arguments to `count_occurrences_by_grade`.
@@ -577,7 +578,7 @@
 * New arguments `yval` and `ci_ribbon` added to `g_km`.
 * Add new individual patient plot function `g_ipp` along with helpers `h_g_ipp` and `h_set_nest_theme`.
 * Fixed bug in `count_patients_with_events`, now shows zero counts without percentage.
-* Fixed bug in `get_mmrm_lsmeans` which did not allow `MMRM` analysis of more than 3000 observations.
+* Fixed bug in `get_mmrm_lsmeans` which did not allow MMRM analysis of more than 3000 observations.
 * Updated `stat_mean_ci` and `stat_median_ci` to handle edge cases with number of elements in input series equal to 1. For such cases, `NA_real_` is now returned, instead of `NA` or `+/-Inf` for confidence interval (CI) estimates.
 * Rename `n_lim` argument of `stat_mean_ci` to `n_min` to better reflect its desired meaning.
 
@@ -598,7 +599,7 @@ This version of `tern` introduces a major rewriting of `tern` due to the change
 * Fitting and tabulating the results of Cox regressions with `fit_coxreg_univar`, `fit_coxreg_multivar` and `summarize_coxreg`, respectively.
 * Pruning occurrence tables (or tables with counts and fractions) with flexible rules, see `?prune_occurrences` for details.
 * Sorting occurrence tables using different options, see `?score_occurrences` for details.
-* Fitting and tabulating `MMRM` models with `fit_mmrm` and `as.rtable` and `summarize_lsmeans`, see `?tabulate_mmrm` for details.
+* Fitting and tabulating MMRM models with `fit_mmrm` and `as.rtable` and `summarize_lsmeans`, see `?tabulate_mmrm` for details.
 * Counting the number of unique and non-unique patients with `summarize_num_patients`.
 * Counting occurrences with `count_occurrences`.
 * Counting occurrences by grade with `summarize_occurrences_by_grade` and `count_occurrences_by_grade`.
@@ -615,16 +616,16 @@ This version of `tern` introduces a major rewriting of `tern` due to the change
 * Add new function `t_contingency` for contingency tables.
 * Renamed the class `splitText` to `dynamicSplitText` to resolve the name conflict with the package `ggpubr`.
 * Add `rreplace_format` for tabulation post-processing.
-* Add new tern function `t_ancova` to create `ANCOVA` tables, as well as corresponding elementary table function `t_el_ancova` and summary function `s_ancova`.
+* Add new tern function `t_ancova` to create ANCOVA tables, as well as corresponding elementary table function `t_el_ancova` and summary function `s_ancova`.
 * Add new tern function `s_odds_ratio` to estimate Odds Ratio of response between categories, as well as the corresponding elementary table function `t_el_odds_ratio`.
-* Added new CI methods (`Agresti-Coull`, `Jeffreys`) for `s_proportion`.
+* Added new CI methods (`agresti-coull`, `jeffreys`) for `s_proportion`.
 * Added new CI methods `anderson-hauck` and `newcombe` to `s_proportion_diff`.
 * Added new p-value methods (Fisher's Exact, Chi-Squared Test with Schouten Correction) for `s_test_proportion_diff`.
 * The binary summary table function `t_binary_outcome` takes now lists (instead of character vectors) specified by the helper function `control_binary_comparison` as the arguments `strat_analysis` and `unstrat_analysis`. Odds Ratio estimates and CIs are now removable and included by default, similarly to the other subsections of the arm comparison analyses. Also added argument `rsp_multinomial`.
 * Add new table function `t_el_multinomial_proportion`.
 * Add new table function `t_abn_shift`.
-* Add new `MMRM` analysis function `s_mmrm`, as well as corresponding table functions `t_mmrm_lsmeans`, `t_mmrm_cov`, `t_mmrm_diagnostic`, `t_mmrm_fixed`, and plot functions `g_mmrm_lsmeans`, `g_mmrm_diagnostic`. The results of these match SAS results (up to numeric precision).
-* Deprecated old `MMRM` functions `a_mmrm` and `t_mmrm` (they give a deprecation warning but still work) to remove in the next release. The reason is that the results of these functions don't match SAS results.
+* Add new MMRM analysis function `s_mmrm`, as well as corresponding table functions `t_mmrm_lsmeans`, `t_mmrm_cov`, `t_mmrm_diagnostic`, `t_mmrm_fixed`, and plot functions `g_mmrm_lsmeans`, `g_mmrm_diagnostic`. The results of these match SAS results (up to numeric precision).
+* Deprecated old MMRM functions `a_mmrm` and `t_mmrm` (they give a deprecation warning but still work) to remove in the next release. The reason is that the results of these functions don't match SAS results.
 * Fix bug in `g_km` related to numbers in patients at risk table to correct numbers for integer time-to-event variable inputs.
 
 # tern 0.6.7

R/abnormal.R

@@ -1,4 +1,4 @@
-#' Patient Counts with Abnormal Range Values
+#' Patient counts with abnormal range values
 #'
 #' @description `r lifecycle::badge("stable")`
 #'

R/abnormal_by_baseline.R

@@ -1,4 +1,4 @@
-#' Patient Counts with Abnormal Range Values by Baseline Status
+#' Patient counts with abnormal range values by baseline status
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
@@ -17,7 +17,7 @@
 #'     * `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`.
+#' @param abnormal (`character`)\cr values identifying the abnormal range level(s) in `.var`.
 #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("abnormal_by_baseline")`
 #'   to see available statistics for this function.
 #'
@@ -32,7 +32,7 @@
 #' @order 1
 NULL
 
-#' Description Function for [s_count_abnormal_by_baseline()]
+#' Description function for `s_count_abnormal_by_baseline()`
 #'
 #' @description `r lifecycle::badge("stable")`
 #'

R/abnormal_by_marked.R

@@ -1,4 +1,4 @@
-#' Count Patients with Marked Laboratory Abnormalities
+#' Count patients with marked laboratory abnormalities
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
@@ -12,7 +12,7 @@
 #'     replicated marked abnormalities.
 #'
 #' @inheritParams argument_convention
-#' @param category (`list`)\cr with different marked category names for single
+#' @param category (`list`)\cr a list with different marked category names for single
 #'   and last or replicated.
 #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("abnormal_by_marked")`
 #'   to see available statistics for this function.

R/abnormal_by_worst_grade.R

@@ -1,4 +1,4 @@
-#' Patient Counts with the Most Extreme Post-baseline Toxicity Grade per Direction of Abnormality
+#' Patient counts with the most extreme post-baseline toxicity grade per direction of abnormality
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
@@ -19,7 +19,7 @@
 #' @param .stats (`character`)\cr statistics to select for the table. Run `get_stats("abnormal_by_worst_grade")`
 #'   to see available statistics for this function.
 #'
-#' @seealso [h_adlb_abnormal_by_worst_grade()] which pre-processes `ADLB` data frames to be used in
+#' @seealso [h_adlb_abnormal_by_worst_grade()] which pre-processes ADLB data frames to be used in
 #'   [count_abnormal_by_worst_grade()].
 #'
 #' @name abnormal_by_worst_grade
@@ -167,11 +167,11 @@ count_abnormal_by_worst_grade <- function(lyt,
   )
 }
 
-#' Helper function to prepare `ADLB` for [count_abnormal_by_worst_grade()]
+#' Helper function to prepare ADLB for `count_abnormal_by_worst_grade()`
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' Helper function to prepare an `ADLB` data frame to be used as input in
+#' Helper function to prepare an ADLB data frame to be used as input in
 #' [count_abnormal_by_worst_grade()]. The following pre-processing steps are applied:
 #'
 #' 1. `adlb` is filtered on variable `avisit` to only include post-baseline visits.
@@ -185,13 +185,13 @@ count_abnormal_by_worst_grade <- function(lyt,
 #'     replaced by their absolute values.
 #' 4. Unused factor levels are dropped from `adlb` via [droplevels()].
 #'
-#' @param adlb (`data.frame`)\cr `ADLB` dataframe.
-#' @param atoxgr (`character`)\cr Analysis toxicity grade variable. This must be a `factor`
+#' @param adlb (`data.frame`)\cr ADLB data frame.
+#' @param atoxgr (`string`)\cr name of the analysis toxicity grade variable. This must be a `factor`
 #'   variable.
-#' @param avisit (`character`)\cr Analysis visit variable.
-#' @param worst_flag_low (`character`)\cr Worst low lab grade flag variable. This variable is
+#' @param avisit (`string`)\cr name of the analysis visit variable.
+#' @param worst_flag_low (`string`)\cr name of the worst low lab grade flag variable. This variable is
 #'   set to `"Y"` when indicating records of worst low lab grades.
-#' @param worst_flag_high (`character`)\cr Worst high lab grade flag variable. This variable is
+#' @param worst_flag_high (`string`)\cr name of the worst high lab grade flag variable. This variable is
 #'   set to `"Y"` when indicating records of worst high lab grades.
 #'
 #' @return `h_adlb_abnormal_by_worst_grade()` returns the `adlb` data frame with two new

R/abnormal_by_worst_grade_worsen.R

@@ -1,4 +1,4 @@
-#' Patient Counts for Laboratory Events (Worsen From Baseline) by Highest Grade Post-Baseline
+#' Patient counts for laboratory events (worsen from baseline) by highest grade post-baseline
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
@@ -18,17 +18,19 @@
 #' @order 1
 NULL
 
-#' Helper Function to Prepare `ADLB` with Worst Labs
+#' Helper function to prepare ADLB with worst labs
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' Helper function to prepare a `df` for generate the patient count shift table
+#' Helper function to prepare a `df` for generate the patient count shift table.
 #'
-#' @param adlb (`data.frame`)\cr `ADLB` dataframe
-#' @param worst_flag_low (named `vector`)\cr Worst low post-baseline lab grade flag variable
-#' @param worst_flag_high (named `vector`)\cr Worst high post-baseline lab grade flag variable
-#' @param direction_var (`string`)\cr Direction variable specifying the direction of the shift table of interest.
-#'   Only lab records flagged by `L`, `H` or `B` are included in the shift table.
+#' @param adlb (`data.frame`)\cr ADLB data frame.
+#' @param worst_flag_low (named `vector`)\cr worst low post-baseline lab grade flag variable. See how this is
+#'   implemented in the following examples.
+#' @param worst_flag_high (named `vector`)\cr worst high post-baseline lab grade flag variable. See how this is
+#'   implemented in the following examples.
+#' @param direction_var (`string`)\cr name of the direction variable specifying the direction of the shift table of
+#'   interest. Only lab records flagged by `L`, `H` or `B` are included in the shift table.
 #'   * `L`: low direction only
 #'   * `H`: high direction only
 #'   * `B`: both low and high directions
@@ -154,7 +156,7 @@ h_adlb_worsen <- function(adlb,
   out
 }
 
-#' Helper Function to Analyze Patients for [s_count_abnormal_lab_worsen_by_baseline()]
+#' Helper function to analyze patients for `s_count_abnormal_lab_worsen_by_baseline()`
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
@@ -164,9 +166,9 @@ h_adlb_worsen <- function(adlb,
 #'
 #' @inheritParams argument_convention
 #' @inheritParams h_adlb_worsen
-#' @param baseline_var (`string`)\cr baseline lab grade variable
+#' @param baseline_var (`string`)\cr name of the baseline lab grade variable.
 #'
-#' @return `h_worsen_counter()` returns the counts and fraction of patients
+#' @return 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".
 #'
@@ -294,7 +296,6 @@ s_count_abnormal_lab_worsen_by_baseline <- function(df, # nolint
   h_worsen_counter(df, variables$id, .var, variables$baseline_var, variables$direction_var)
 }
 
-
 #' @describeIn abnormal_by_worst_grade_worsen Formatted analysis function which is used as `afun`
 #'   in `count_abnormal_lab_worsen_by_baseline()`.
 #'

R/analyze_colvars_functions.R

@@ -1,4 +1,4 @@
-#' Analyze Functions on Columns
+#' Analyze functions on columns
 #'
 #' @description
 #' These functions are wrappers of [rtables::analyze_colvars()] which apply corresponding `tern`

R/analyze_functions.R

@@ -1,4 +1,4 @@
-#' Analyze Functions
+#' Analyze functions
 #'
 #' @description
 #'