Merge branch 'main' into 2139_Make_derive_extreme_records_consistent

.Rbuildignore

@@ -29,3 +29,4 @@
 ^staged_dependencies.yaml$
 ^inst/dev_dependencies.R$
 ^\.devcontainer$
+^vignettes/articles$

.github/workflows/common.yml

@@ -69,15 +69,8 @@ jobs:
     uses: pharmaverse/admiralci/.github/workflows/pkgdown.yml@main
     if: github.event_name == 'push' || startsWith(github.ref, 'refs/tags/v')
     with:
-      r-version: "4.1"
-      # Whether to skip multiversion docs
-      # Note that if you have multiple versions of docs,
-      # your URL links are likely to break due to path changes
-      skip-multiversion-docs: false
-      latest-tag-alt-name: cran-release
-      multiversion-docs-landing-page: cran-release
-      branches-or-tags-to-list: >-
-        ^cran-release$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$
+      r-version: "4.3"
+      skip-multiversion-docs: true
   linter:
     name: Lint
     uses: pharmaverse/admiralci/.github/workflows/lintr.yml@main

.github/workflows/templates.yml

@@ -1,17 +1,16 @@
----
 name: Check Templates
 
 on:
   workflow_dispatch:
   pull_request:
     branches:
       - main
-      - patch
+      - devel
 
 jobs:
   templates:
     name: Check Templates
     uses: pharmaverse/admiralci/.github/workflows/check-templates.yml@main
-    if: github.event_name == 'pull_request'
+    secrets: inherit
     with:
       r-version: "4.1"

DESCRIPTION

@@ -62,3 +62,4 @@ Suggests:
     tibble
 VignetteBuilder: knitr
 Config/testthat/edition: 3
+Config/Needs/website: gert

NEWS.md

@@ -50,12 +50,17 @@ were enhanced such that more than one summary variable can be derived, e.g.,
   - `derive_expected_records(dataset_expected_obs)` 
   - `derive_var_ontrtfl(span_period)` 
 
+- The `derive_param_extreme_record()` function has been superseded in favor of `derive_extreme_event()`. (#2141)
+
 ## Documentation
 
 - A way to standardize roxygen labels and descriptions for function arguments was implemented and tested (#2034)
 
 - Link to published CDISC Population PK (ADPPK) implementation guide added. (#2161)
 
+- Removed Deprecation section in Reference tab.  Added new Superseded section in 
+Reference tab. (#2174)
+
 ## Various
 
 - Website now has button/links to Slack channel and GitHub Issues (#2127)
@@ -722,7 +727,7 @@ updated to process additional parameter (#1125).
 imputation functions themselves (#1299). I.e., if a derivation like last known alive
 date is based on dates, DTC variables have to be converted to numeric date or
 datetime variables in a preprocessing step. For examples see the [ADSL
-vignette](https://pharmaverse.github.io/admiral/cran-release/articles/adsl.html).
+vignette](https://pharmaverse.github.io/admiral/articles/adsl.html).
   The following arguments were deprecated:
 
   - `date_imputation`, `time_imputation`, and `preserve` in `date_source()`
@@ -821,7 +826,7 @@ empty (#1309)
 
 
 - `create_query_data()` is provided to create the [queries
-dataset](https://pharmaverse.github.io/admiral/cran-release/articles/queries_dataset.html) required as input for `derive_vars_query()` (#606)
+dataset](https://pharmaverse.github.io/admiral/articles/queries_dataset.html) required as input for `derive_vars_query()` (#606)
 
 - `create_single_dose_dataset()` - Derives dataset of single dose from aggregate dose information (#660)
 
@@ -854,7 +859,7 @@ first disease progression. (#1023)
 ### ADLB
 
   - New ADLB template script available `ad_adlb.R`, specific ADLB functions developed and
-  [BDS Finding vignette](https://pharmaverse.github.io/admiral/cran-release/articles/bds_finding.html) has examples enhanced with ADLB functions. (#1122)
+  [BDS Finding vignette](https://pharmaverse.github.io/admiral/articles/bds_finding.html) has examples enhanced with ADLB functions. (#1122)
 
   - `derive_var_shift()` - Derives a character shift variable containing concatenated shift in values based on user-defined pairing (#944)
   - `derive_var_analysis_ratio()` - Derives a ratio variable based on user-supplied variables from a BDS dataset, e.g. ADLB. (#943)
@@ -936,7 +941,7 @@ specific for admiral. Derivations like this can be implemented calling
 - Updated `derive_var_worst_flag()` and `derive_var_extreme_flag()` vignettes to clarify their purpose (#691)
 
 - Added example of ASEQ derivation in ADCM to 
-[OCCDS vignette](https://pharmaverse.github.io/admiral/cran-release/articles/occds.html#aseq)
+[OCCDS vignette](https://pharmaverse.github.io/admiral/articles/occds.html#aseq)
 (#720)
 
 - Examples have been added for `format_reason_default()`, `format_eoxxstt_default()`, `extend_source_datasets()` and `filter_date_sources()` (#745)
@@ -1036,7 +1041,7 @@ this case the day is imputed as `15` (#592)
 
 - The first truly open source release licensed under Apache 2.0 (#680)
 
-- New vignette [Contributing to admiral](https://pharmaverse.github.io/admiral/cran-release/articles/contribution_model.html) (#679)
+- New vignette [Contributing to admiral](https://pharmaverse.github.io/admiral/articles/contribution_model.html) (#679)
 
 - New vignette [Unit Test Guidance](https://pharmaverse.github.io/admiraldev/main/articles/unit_test_guidance.html) (#679)
 
@@ -1058,7 +1063,7 @@ age in different units (#569)
 - `derive_param_tte()` derives time-to-event-parameters (#546)
 
 - For common time-to-event endpoints [event and censoring source
-objects](https://pharmaverse.github.io/admiral/cran-release/reference/index.html#section-pre-defined-time-to-event-sources) are
+objects](https://pharmaverse.github.io/admiral/reference/index.html#section-pre-defined-time-to-event-sources) are
 provided (#612)
 
 ### Developer
@@ -1093,9 +1098,9 @@ to specify the unit of the input age (#569)
 
 ## Documentation
 
-- New vignette [Creating a BDS Time-to-Event ADaM](https://pharmaverse.github.io/admiral/cran-release/articles/bds_tte.html) (#549)
+- New vignette [Creating a BDS Time-to-Event ADaM](https://pharmaverse.github.io/admiral/articles/bds_tte.html) (#549)
 
-- New vignette [Queries Dataset Documentation](https://pharmaverse.github.io/admiral/cran-release/articles/queries_dataset.html) (#561)
+- New vignette [Queries Dataset Documentation](https://pharmaverse.github.io/admiral/articles/queries_dataset.html) (#561)
 
 - New vignette [Writing Vignettes](https://pharmaverse.github.io/admiraldev/main/articles/writing_vignettes.html) (#334)
 
@@ -1290,10 +1295,10 @@ to specify the unit of the input age (#569)
 
 ## Documentation
 
-- [Frequently Asked Questions](https://pharmaverse.github.io/admiral/cran-release/articles/faq.html)
+- [Frequently Asked Questions](https://pharmaverse.github.io/admiral/articles/faq.html)
 
-- [Creating ADSL](https://pharmaverse.github.io/admiral/cran-release/articles/adsl.html)
+- [Creating ADSL](https://pharmaverse.github.io/admiral/articles/adsl.html)
 
-- [Creating a BDS Finding ADaM](https://pharmaverse.github.io/admiral/cran-release/articles/bds_finding.html)
+- [Creating a BDS Finding ADaM](https://pharmaverse.github.io/admiral/articles/bds_finding.html)
 
-- [Creating an OCCDS ADaM](https://pharmaverse.github.io/admiral/cran-release/articles/occds.html)
+- [Creating an OCCDS ADaM](https://pharmaverse.github.io/admiral/articles/occds.html)

R/derive_param_extreme_record.R

@@ -1,5 +1,9 @@
 #' Adds a Parameter Based on First or Last Record from Multiple Sources
 #'
+#' @description
+#' `r lifecycle::badge("superseded")` The `derive_param_extreme_record()`
+#' function has been superseded in favor of `derive_extreme_event()`.
+#'
 #' Generates parameter based on the first or last observation from multiple
 #' source datasets, based on user-defined filter, order and by group criteria.
 #' All variables of the selected observation are kept.
@@ -71,8 +75,8 @@
 #' The input dataset with the first or last observation of each by group
 #' added as new observations.
 #'
-#' @family der_prm_bds_findings
-#' @keywords der_prm_bds_findings
+#' @family superseded
+#' @keywords superseded
 #'
 #' @export
 #' @examples

R/derive_var_trtemfl.R

@@ -31,7 +31,7 @@
 #'
 #' @param end_window
 #'
-#'    If the argument is specified, events starting more than the specified
+#'    If the argument is specified (in 'days'), events starting more than the specified
 #'    number of days after end of treatment, are not flagged.
 #'
 #'    *Permitted Values:* A non-negative integer or `NULL`
@@ -46,7 +46,7 @@
 #' @param initial_intensity Initial severity/intensity or toxicity
 #'
 #'   This derivation assumes AE data collection method as single record per AE
-#'   with “initial” and “most extreme” severity/intensity recorded separately.
+#'   with "initial" and "most extreme" severity/intensity recorded separately.
 #'
 #'   If the argument is specified, events which start before treatment start and
 #'   end after treatment start (or are ongoing) and worsened (i.e., the

README.md

@@ -32,7 +32,7 @@ devtools::install_github("pharmaverse/admiral")
 
 ## Release Schedule
 
-[{admiral}](https://pharmaverse.github.io/admiral/cran-release/) releases are targeted for the first Monday of the last month of each quarter.
+[{admiral}](https://pharmaverse.github.io/admiral/) releases are targeted for the first Monday of the last month of each quarter.
 The {admiral} family has several downstream and upstream dependencies and so this release shall be done in three
 Phases:
 
@@ -44,14 +44,14 @@ Phases:
 | Q4-2023          | December 4th                                                             | December 11th                                                        |
 |                  | [{pharmaversesdtm}](https://pharmaverse.github.io/pharmaversesdtm/main/) | [{admiralonco}](https://pharmaverse.github.io/admiralonco/main/)     |
 |                  | [{admiraldev}](https://pharmaverse.github.io/admiraldev/main/)           | [{admiralophtha}](https://pharmaverse.github.io/admiralophtha/main/) |
-|                  | [{admiral}](https://pharmaverse.github.io/admiral/cran-release/)                 |                                                                      |
+|                  | [{admiral}](https://pharmaverse.github.io/admiral/)                 |                                                                      |
 
 The `{admiral}` Q4-2023 release will officially be `{admiral}`'s version 1.0.0 release, where we commit to increased package maturity and pivot towards focusing on maintenance rather than new content. This does not mean that there will never be any new content in `{admiral}`, rather it means we will be more mindful about introducing new functionality and/or breaking changes. The release schedule in 2024 and onward will also shift to twice-yearly, rather than quarterly, so that our users have ample time to react to any new content and changes that do make it onto `{admiral}`.
 
 ## Main Goal
 
 Provide users with an open source, modularized toolbox with which to create ADaM datasets
-in R. _As opposed to a “run 1 line and an ADaM appears” black-box solution or an attempt to
+in R. _As opposed to a "run 1 line and an ADaM appears" black-box solution or an attempt to
 automate ADaM._
 
 One of the key aspects of `{admiral}` is its development by the users for the users.
@@ -73,7 +73,7 @@ We will provide:
 * Pharmaceutical communities and companies are encouraged to contribute to `{admiral}` following
   the provided programming strategy and modular approach
 * Functions that are comprehensively documented and tested, including example calls---these are
-  all listed in the [Reference section](https://pharmaverse.github.io/admiral/cran-release/reference/index.html)
+  all listed in the [Reference section](https://pharmaverse.github.io/admiral/reference/index.html)
 * Vignettes on how to create ADSL, BDS and OCCDS datasets, including example scripts
 * Vignettes for ADaM dataset specific functionality (i.e. dictionary coding, date imputation, SMQs ...)
 
@@ -106,7 +106,7 @@ The following packages are also useful when working with ADaM datasets:
 For `{admiral}` and all extension packages, we prioritize providing our users with a __simple to adopt__ toolkit
 that enables them to produce __readable__ and __easily constructible__ ADaM programs. The following explains
 our philosophy, which we try to adhere to across the `{admiral}` family of packages.
-There isn’t always a clear single, straightforward rule, but there are guiding principles we adhere to for `{admiral}`.
+There isn't always a clear single, straightforward rule, but there are guiding principles we adhere to for `{admiral}`.
 This manifesto helps show the considerations of our developers when making decisions.
 
 We have four design principles to achieve the main goal:
@@ -115,7 +115,7 @@ We have four design principles to achieve the main goal:
 
 All `{admiral}` functions should be easy to use.
 
-* Documentation is an absolute priority. Each function reference page should cover the purpose, descriptions of each argument with permitted values, the expected input and output, with clear real-life examples---so that users don’t need to dig through code to find answers.
+* Documentation is an absolute priority. Each function reference page should cover the purpose, descriptions of each argument with permitted values, the expected input and output, with clear real-life examples---so that users don't need to dig through code to find answers.
 * Vignettes that complement the functional documentation to help users see how best the functions can be applied to achieve ADaM requirements.
 * Functions should be written and structured in a way that users are able to read, re-use or extend them for study specific purposes if needed (see Readability below).
 
@@ -149,18 +149,18 @@ that all our developers and contributors must follow, so that all our code has a
 
 * We mandate use of tidyverse (e.g. dplyr) over similar functionality existing in base R.
 * For sections of code that perform the actual derivations (e.g. besides assertions or basic utilities), we try to limit nesting of too many dependencies or functions.
-* Modularity is a focus---we don’t try to achieve too many steps in one.
+* Modularity is a focus---we don't try to achieve too many steps in one.
 * All code has to be well commented.
 * We recognize that a user or a Health Authority reviewer may have the wish to delve into the code base (especially given this open source setting), or users may need to extend/adapt the code for their study specific needs. We therefore want any module to be understandable to all, not only the `{admiral}` developers.
 
 ## References and Documentation
 
-* Please go to [Get Started](https://pharmaverse.github.io/admiral/cran-release/articles/admiral.html) section to start using `{admiral}`
+* Please go to [Get Started](https://pharmaverse.github.io/admiral/articles/admiral.html) section to start using `{admiral}`
 * Please see the [pharmaverse YouTube channel](https://www.youtube.com/channel/UCxQFEv8HNqM01DXzdQLCy6Q) for videos related to `{admiral}`.
 * Please see the [Programming Strategy](https://pharmaverse.github.io/admiraldev/main/articles/programming_strategy.html) to understand how functions are created
-* Please see the [FAQ](https://pharmaverse.github.io/admiral/cran-release/articles/faq.html) for the most frequent questions
-* Please see the [Contribution Model](https://pharmaverse.github.io/admiral/cran-release/articles/contribution_model.html) for how to get involved with making contributions
-* Please see [FAQ: R and Package Versions](https://pharmaverse.github.io/admiral/cran-release/articles/faq.html#why-do-we-use-a-certain-r-version-and-package-versions-for-development) for why we develop with certain R and package versions.
+* Please see the [FAQ](https://pharmaverse.github.io/admiral/articles/faq.html) for the most frequent questions
+* Please see the [Contribution Model](https://pharmaverse.github.io/admiral/articles/contribution_model.html) for how to get involved with making contributions
+* Please see [FAQ: R and Package Versions](https://pharmaverse.github.io/admiral/articles/faq.html#why-do-we-use-a-certain-r-version-and-package-versions-for-development) for why we develop with certain R and package versions.
 
 ## Pharmaverse Blog
 

_pkgdown.yml

@@ -19,7 +19,7 @@ development:
   mode: auto
 
 authors:
-  before: "We define *authors* as those who are actively maintaining the code base, and *contributors* as those who made a significant contribution in the past. For all acknowledgements, see the eponymous section in the [Home Page](https://pharmaverse.github.io/admiral/cran-release/)."
+  before: "We define *authors* as those who are actively maintaining the code base, and *contributors* as those who made a significant contribution in the past. For all acknowledgements, see the eponymous section in the [Home Page](https://pharmaverse.github.io/admiral/)."
   footer:
     roles: [aut, ctb, cre, fnd]
     text: "Developed by"
@@ -128,19 +128,13 @@ reference:
   contents:
   - has_keyword('reexport')
 
-- title: Deprecated
+- title: Superseded
   desc: |
-    As `{admiral}` is still evolving, functions/parameters may need to be removed or replaced over time. In such cases, the function/parameter will enter the following 6-month deprecation cycle:
-
-    * In the first release (0-3 months), there will be a warning issued if you use the function/parameter, but it will still be available to use.
-    * In the following release (3-6 months), an error will be produced if you use the function/parameter.
-    * Finally, from the 3rd release (6 months) onwards, the function/parameter will be removed from `{admiral}` and its documentation completely.
-
-    *Note: Guidance on replacement functionality can be found in the warning/error message produced or in the function's documentation.*
-
-    Below, you can find a list of functions in the process of being deprecated:
+    Superseded functions have been replaced with better functions. However, we
+    will not be removing these functions from `{admiral}`.  We do strongly
+    encourage you to make the switch over.
   contents:
-  - has_keyword("deprecated")
+  - has_keyword("superseded")
 
 navbar:
   structure:

inst/templates/ad_adae.R

@@ -24,7 +24,7 @@ adsl <- admiral_adsl
 # When SAS datasets are imported into R using haven::read_sas(), missing
 # character values from SAS appear as "" characters in R, instead of appearing
 # as NA values. Further details can be obtained via the following link:
-# https://pharmaverse.github.io/admiral/cran-release/articles/admiral.html#handling-of-missing-values # nolint
+# https://pharmaverse.github.io/admiral/articles/admiral.html#handling-of-missing-values # nolint
 
 ae <- convert_blanks_to_na(ae)
 ex <- convert_blanks_to_na(ex_single)
@@ -133,5 +133,9 @@ adae <- adae %>%
 
 # Save output ----
 
-dir <- tempdir() # Change to whichever directory you want to save the dataset in
-saveRDS(adae, file = file.path(dir, "adae.rds"), compress = "bzip2")
+dir <- file.path(getwd(), "tmp")
+if (!file.exists(dir)) {
+  # Create the folder
+  dir.create(dir)
+}
+save(adae, file = file.path(dir, "adae.rda"), compress = "bzip2")

inst/templates/ad_adcm.R

@@ -22,7 +22,7 @@ adsl <- admiral_adsl
 # When SAS datasets are imported into R using haven::read_sas(), missing
 # character values from SAS appear as "" characters in R, instead of appearing
 # as NA values. Further details can be obtained via the following link:
-# https://pharmaverse.github.io/admiral/cran-release/articles/admiral.html#handling-of-missing-values # nolint
+# https://pharmaverse.github.io/admiral/articles/admiral.html#handling-of-missing-values # nolint
 
 cm <- convert_blanks_to_na(cm)
 
@@ -108,7 +108,7 @@ adcm <- adcm %>%
 ## Derive APHASE and APHASEN Variable ----
 # Other timing variable can be derived similarly.
 # See also the "Visit and Period Variables" vignette
-# (https://pharmaverse.github.io/admiral/cran-release/articles/visits_periods.html)
+# (https://pharmaverse.github.io/admiral/articles/visits_periods.html)
 adcm <- adcm %>%
   mutate(
     APHASE = case_when(
@@ -138,5 +138,9 @@ adcm <- adcm %>%
 
 # Save output ----
 
-dir <- tempdir() # Change to whichever directory you want to save the dataset in
-saveRDS(adcm, file = file.path(dir, "adcm.rds"), compress = "bzip2")
+dir <- file.path(getwd(), "tmp")
+if (!file.exists(dir)) {
+  # Create the folder
+  dir.create(dir)
+}
+save(adcm, file = file.path(dir, "adcm.rda"), compress = "bzip2")