Merge branch 'main' into feat/reintroduce-multiversion-docs

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: admiral
 Title: ADaM in R Asset Library
-Version: 1.1.1.9050
+Version: 1.2.0.9004
 Authors@R: c(
     person("Ben", "Straub", , "[email protected]", role = c("aut", "cre")),
     person("Stefan", "Bundfuss", role = "aut",
@@ -40,9 +40,9 @@ URL: https://pharmaverse.github.io/admiral/cran-release/,
     https://github.com/pharmaverse/admiral
 BugReports: https://github.com/pharmaverse/admiral/issues
 Depends: 
-    R (>= 4.0)
+    R (>= 4.1)
 Imports:
-    admiraldev (>= 1.1.0.9007),
+    admiraldev (>= 1.2.0),
     cli (>= 3.6.2),
     dplyr (>= 1.0.5),
     hms (>= 0.5.3),
@@ -65,7 +65,8 @@ Suggests:
     readxl,
     rmarkdown,
     testthat (>= 3.0.0),
-    tibble
+    tibble,
+    withr
 VignetteBuilder: 
     knitr
 Remotes: 

NAMESPACE

@@ -284,6 +284,7 @@ importFrom(rlang,sym)
 importFrom(rlang,syms)
 importFrom(rlang,type_of)
 importFrom(rlang,warn)
+importFrom(rlang,zap)
 importFrom(stats,setNames)
 importFrom(stringr,str_c)
 importFrom(stringr,str_count)

NEWS.md

@@ -2,19 +2,51 @@
 
 ## New Features
 
+## Updates of Existing Functions
+
+## Breaking Changes
+
+- The following function arguments are entering the next phase of the [deprecation process](https://pharmaverse.github.io/admiraldev/articles/programming_strategy.html#deprecation): (#2487) (#2595)
+
+    **Phase 1 (message)**
+
+    **Phase 2 (warning)**
+
+    **Phase 3 (error)**
+
+    **Phase 4 (removed)**
+
+## Documentation
+
+## Various
+
+<details>
+<summary>Developer Notes</summary>
+
+</details>
+
+# admiral 1.2.0
+
+## New Features
+
 - New function `derive_vars_cat()` for deriving pairs of variables or more, e.g. 
 `AVALCATy` & `AVALCAyN`. (#2480)
 - New function `derive_vars_crit_flag()` for deriving criterion flag variables
 (`CRITy`, `CRITyFL`, `CRITyFN`). (#2468)
 - New function `transform_range()`  to transform values from a source range to a
 target range. (#2571)
-- Replace use of `data("sdtm")` with `sdtm <- pharmaverse::sdtm` in templates and vignettes. (#2498)
-
-- Remove `dthcaus_source()` calls in `ADSL` template because they are deprecated. (#2517)
-- Update `ADEG` template to flag `ABLFL` and `ANL01FL` based on `DTYPE == "AVERAGE"` records. (#2561)
 
 ## Updates of Existing Functions
 
+- Added `"message"` as option for `check_type` argument in `derive_var_obs_number()` function. (#2481)
+
+- Added `"message"` as option for `check_type` argument in `filter_extreme()` function. (#2481)
+
+- Users can now specify how duplicate records are handled in `derive_param_tte()` using the `check_type` argument, with options including `"error"`, `"warning"`, `"message"`, or `"none"`, allowing for greater flexibility in managing duplicate data scenarios. (#2481)
+
+- The `order` argument has been added to `event_source()` and `censor_source()` and  
+  defaulted to `NULL` to allow specifying variables in addition to the date variable. This can be used to ensure the uniqueness of the select records if there is more than one record per date.  (#2481)  
+
 - NCICTCAEv5 grading criteria (`atoxgr_criteria_ctcv5`):
 
   - fix for `TERM = "INR increased"`, criteria was wrongly using `x ULN`, for first part of criteria for grades 1 to 3. For example, `">2.5 x ULN"` changed to `">2.5"` for grade 3. (#2534).
@@ -39,45 +71,62 @@ or that the queries dataset contains duplicates. (#2543)
 
 - `derive_vars_atc()` and `create_single_dose_dataset()` `by_vars` argument updated to use `get_admiral_option("subject_keys")` instead of  `USUBJID` or `STUDYID` in `bds_exposure.Rmd`. (#2501)
 
-- test scripts, R, and markdown files for `create_single_dose_dataset` and `occds.Rmd` updated to include a `STUDYID` column because of `get_admiral_option("subject_keys")` update above. (#2501)
+- The test scripts, R, and markdown files for `create_single_dose_dataset()` and `occds.Rmd` updated to include a `STUDYID` column because of `get_admiral_option("subject_keys")` update above. (#2501)
 
 - Update `derive_vars_period()` to make it work when there is only one new variable. (#2582)
 
-- In `get_summary_records()`, previously deprecated formal arguments `analysis_var` and `summary_fun` now removed from function, documentation, tests etc. (#2521)
-
 - A check was added to `derive_vars_transposed()` and `derive_vars_atc()` which
 stops execution if the records in `dataset_merge` or `dataset_facm` respectively
 are not unique. (#2563)
 
 - The functions `derive_vars_joined()`, `derive_var_joined_exist_flag()`,
 `derive_extreme_event()`, and `filter_joined()` were updated to reduce their
-memory consumption. (#2590)
+memory consumption. As the new code increases the run-time, it is not used by
+default. To enable it the new admiral option `save_memory` has to be set to
+`TRUE`. (#2590)
 
 - The function `compute_egfr()` updated to allow missing values for sex which result in missing values for output. (#2612)
 
 ## Breaking Changes
 
-- The following function arguments are entering the next phase of the deprecation process: (#2487)
+- The following function arguments are entering the next phase of the [deprecation process](https://pharmaverse.github.io/admiraldev/articles/programming_strategy.html#deprecation): (#2487) (#2595)
 
-### Phase 1 (warning)
+    **Phase 1 (message)**
+
+    - `derive_param_extreme_record()` is deprecated and replaced by `derive_extreme_event()`
+    - `derive_var_dthcaus()` is deprecated and replaced by `derive_vars_extreme_event()`
+    - `date_source()` is deprecated and replaced by `event()`
+    - `dthcaus_source()` is deprecated and replaced by `event()`
+    - `derive_var_extreme_dt()` and `derive_var_extreme_dtm()` are deprecated and replaced by `derive_vars_extreme_event()`
+    - `get_summary_records()` is deprecated. Please use `derive_summary_records()` with the `dataset_add` argument and without the `dataset` argument.
 
-### Phase 2 (error)
+
+    **Phase 2 (warning)**
+
+    No functions or arguments in this Phase
 
-### Phase 3 (removed)
-  - `consolidate_metadata(check_keys)`
-  - Removed at v1.1.1 `compute_egfr(wt)`
-  - Removed at v1.1.1 `derive_expected_records(dataset_expected_obs)` 
-  - Removed at v1.1.1 `derive_locf_records(dataset_expected_obs)`
-  - `derive_extreme_event(ignore_event_order)`
-  - `derive_vars_merged(match_flag)`
-  - `derive_var_merged_summary(new_var, analysis_var, summary_fun)`
-  - Removed at v1.1.1 `derive_param_computed(analysis_value, analysis_var)`
-  - `derive_param_exposure(filter, analysis_var, summary_fun)`
-  - `derive_summary_records(filter)`
-  - Removed at v1.1.1 `derive_extreme_records(filter)`
-  - `derive_var_joined_exist_flag(first_cond, filter)`
-  - `event_joined(first_cond)`
-  - `filter_joined(first_cond, filter)`
+    **Phase 3 (error)**
+
+    No functions or arguments in this Phase
+
+    **Phase 4 (removed)**
+
+    - `consolidate_metadata(check_keys)`
+    - Removed at v1.1.1 `compute_egfr(wt)`
+    - Removed at v1.1.1 `derive_expected_records(dataset_expected_obs)` 
+    - Removed at v1.1.1 `derive_locf_records(dataset_expected_obs)`
+    - `derive_extreme_event(ignore_event_order)`
+    - `derive_vars_merged(match_flag)`
+    - `derive_var_merged_summary(new_var, analysis_var, summary_fun)`
+    - Removed at v1.1.1 `derive_param_computed(analysis_value, analysis_var)`
+    - `derive_param_exposure(filter, analysis_var, summary_fun)`
+    - `derive_summary_records(filter)`
+    - Removed at v1.1.1 `derive_extreme_records(filter)`
+    - `derive_var_joined_exist_flag(first_cond, filter)`
+    - `event_joined(first_cond)`
+    - `filter_joined(first_cond, filter)`
+    - In `get_summary_records()`, previously deprecated formal arguments `analysis_var` and   
+    `summary_fun` now removed from function, documentation, tests etc. (#2521)
 
 ## Documentation
 
@@ -86,15 +135,28 @@ memory consumption. (#2590)
 
 - `derive_var_joined_exist_flag()` documentation updated with extra examples. (#2523)
 
+- Updated the Cheat Sheet to be in line with the 1.2 release of `{admiral}`. (#2458)
+- In the `derive_param_tte()` documentation is was clarified which
+event/censoring is selected if there is more than one at the same date (for
+events the first one specified in `event_conditions` and for censoring the last
+one in `censor_conditions`). (#2639)
+
 ## Various
 
+- Replace use of `data("sdtm")` with `sdtm <- pharmaverse::sdtm` in templates and vignettes. (#2498)
+- Remove `dthcaus_source()` calls in `ADSL` template because they are deprecated. (#2517)
+- Update `ADEG` template to flag `ABLFL` and `ANL01FL` based on `DTYPE == "AVERAGE"` records. (#2561)
+
 <details>
 <summary>Developer Notes</summary>
 
 - Created unit tests for developer internal function `restricted_imputed_dtc_dt()` (#2495)
 - Adopted `data-raw/data` R Package Convention (#2427, #2584)
 - `compute_bsa()` now uses the more common (but equivalent) version of the DuBois-DuBois formula for BSA. The results have not changed. (#2532)  
 - Removed `.devcontainer` file (codespace) (#2524)
+- Restructured `derive_adeg_parms.R` and `derive_advs_parms.R` and related test files for easier reference (#2551)
+
+
 
 </details>
 
@@ -412,7 +474,7 @@ the imputation functions, e.g. `derive_vars_dtm()`. (#2222)
 - Moved Development Process from `{admiraldev}` to Contribution Model in the 
 `admiral` website, updated GitHub strategy. (#2196)
 
-- Added new drop downs in Get Started navigation bar- Getting Started, Admiral Discovery, Cheatsheet. Community removed from top. (#2217)
+- Added new drop downs in Get Started navigation bar- Getting Started, Admiral Discovery, Cheat Sheet. Community removed from top. (#2217)
 
 - All "Example Script(s)" sections in the User Guide vignettes were updated to point the user towards using `use_ad_template("ADaM")` rather 
   than linking to the template in the code repository. (#2239)

R/admiral-package.R

@@ -21,7 +21,7 @@
 #'   current_env .data enexpr enexprs eval_bare eval_tidy expr expr_interp exec
 #'   expr_label exprs f_lhs f_rhs  inform is_call is_expression is_missing
 #'   is_named list2 new_environment new_formula parse_expr parse_exprs set_names
-#'   sym syms type_of warn
+#'   sym syms type_of warn zap
 #' @importFrom stats setNames
 #' @importFrom stringr str_c str_count str_detect str_extract str_glue
 #'             str_length str_locate str_locate_all str_match str_remove

R/admiral_environment.R

@@ -20,7 +20,8 @@ admiral_environment <- new.env(parent = emptyenv())
 admiral_environment$admiral_options <- list(
   # future_input = exprs(...), nolint
   subject_keys = exprs(STUDYID, USUBJID),
-  signif_digits = 15
+  signif_digits = 15,
+  save_memory = FALSE
 )
 
 # To enhance features and add inputs as necessary

R/admiral_options.R

@@ -65,14 +65,15 @@ get_admiral_option <- function(option) {
   # change cli `.val` to end with OR instead of AND
   divid <- cli_div(theme = list(.val = list("vec-last" = ", or ", "vec_sep2" = " or ")))
   # Return message otherwise, catch typos
-  cli_abort(c("Invalid function argument.",
+  cli_abort(c(
+    "Invalid function argument.",
     "i" = "Select one of {.val {possible_inputs}}"
   ))
 }
 
-#' Set the Value of Admiral Options
+#' Set the Value of admiral Options
 #'
-#' Set the Values of Admiral Options That Can Be Modified for Advanced Users.
+#' Set the values of admiral options that can be modified for advanced users.
 #'
 #' @param subject_keys Variables to uniquely identify a subject, defaults to
 #'   `exprs(STUDYID, USUBJID)`. This option is used as default value for the
@@ -82,6 +83,11 @@ get_admiral_option <- function(option) {
 #'  defaults to `15`. This option is used as default value for the  `signif_dig` argument in
 #'  admiral functions `derive_var_atoxgr_dir()` and `derive_var_anrind()`.
 #'
+#' @param save_memory If set to `TRUE`, an alternative algorithm is used in the
+#'   functions `derive_vars_joined()`, `derive_var_joined_exist_flag()`,
+#'   `derive_extreme_event()`, and `filter_joined()` which requires less memory
+#'   but more run-time.
+#'
 #' @details
 #' Modify an admiral option, e.g `subject_keys`, such that it automatically affects downstream
 #' function inputs where `get_admiral_option()` is called such as `derive_param_exist_flag()`.
@@ -153,7 +159,7 @@ get_admiral_option <- function(option) {
 #'
 #' derive_var_anrind(advs)
 #'
-set_admiral_options <- function(subject_keys, signif_digits) {
+set_admiral_options <- function(subject_keys, signif_digits, save_memory) {
   if (!missing(subject_keys)) {
     assert_vars(subject_keys)
     admiral_environment$admiral_options$subject_keys <- subject_keys
@@ -162,6 +168,10 @@ set_admiral_options <- function(subject_keys, signif_digits) {
     assert_integer_scalar(signif_digits, subset = "positive")
     admiral_environment$admiral_options$signif_digits <- signif_digits
   }
+  if (!missing(save_memory)) {
+    assert_logical_scalar(save_memory)
+    admiral_environment$admiral_options$save_memory <- save_memory
+  }
 
   # Add future input to function formals above
   # if (!missing(future_input)) {

R/data.R

@@ -4,7 +4,7 @@
 #' @keywords datasets
 #' @family datasets
 #' @source
-#' Derived from the `ex` dataset using `{admiral}` and `{dplyr}` (\url{https://github.com/pharmaverse/admiral/blob/main/inst/example_scripts/derive_single_dose.R})
+#' Derived from the `ex` dataset using `{admiral}` and `{dplyr}` (\url{https://github.com/pharmaverse/admiral/blob/main/data-raw/create_ex_single.R})
 "ex_single"
 
 #' Example `QS` Dataset
@@ -17,7 +17,7 @@
 #' @keywords datasets
 #' @family datasets
 #' @source
-#' Created by (\url{https://github.com/pharmaverse/admiral/blob/main/inst/example_scripts/example_qs.R})
+#' Created by (\url{https://github.com/pharmaverse/admiral/blob/main/data-raw/create_example_qs.R})
 "example_qs"
 
 #' Queries Dataset