Headline update: documentation that gets you

Our crowning update this release cycle is…

Documentation updates!

Hmmm, doesn’t sound fancy enough? What about…

Documentation updates!!

Still not that interesting? Well, let us change your mind with an example. Here’s what the examples section of the reference page for Add the First or Last Observation for Each By Group as New Records — derive_extreme_records • admiral admiral::derive_extreme_records() looked like in ADaM in R Asset Library • admiral {admiral} 1.2:

And here’s what it looks like in ADaM in R Asset Library • admiral {admiral} 1.3:

That’s right! Some of our reference examples have now been enhanced such that:

• Each example has a title, which is also shown in the table of contents, and a description explaining what is happening.
• The examples are often building up in complexity, starting from a simple application of the function in a toy case and building up to more structured use-cases.
• The examples for this function now cover all the arguments of the function.

As usual, you can access these reference examples from our documentation website or alternatively directly from RStudio’s own Help pane by typing ?function_name in the console.

For this first iteration, we have targeted some of the most complex, flexible and important functions within ADaM in R Asset Library • admiral {admiral} . The functions which have received this enhanced example treatment are:

• Add the First or Last Observation for Each By Group as New Records — derive_extreme_records • admiral admiral::derive_extreme_records()
• Derive a Time-to-Event Parameter — derive_param_tte • admiral admiral::derive_param_tte()
• Add New Records Within By Groups Using Aggregation Functions — derive_summary_records • admiral admiral::derive_summary_records()
• Add the Worst or Best Observation for Each By Group as New Records — derive_extreme_event • admiral admiral::derive_extreme_event()
• Add Variables from an Additional Dataset Based on Conditions from Both Datasets — derive_vars_joined • admiral admiral::derive_vars_joined()
• Summarize Variables from an Additional Dataset Based on Conditions from Both Datasets — derive_vars_joined_summary • admiral admiral::derive_vars_joined_summary()
• Add New Variable(s) to the Input Dataset Based on Variables from Another Dataset — derive_vars_merged • admiral admiral::derive_vars_merged()
• Derive Criterion Flag Variables CRITy, CRITyFL, and CRITyFN — derive_vars_crit_flag • admiral admiral::derive_vars_crit_flag()
• Derive Treatment-emergent Flag — derive_var_trtemfl • admiral admiral::derive_var_trtemfl() (now showcasing all scenarios discussed in the PHUSE White Paper on Treatment-Emergent AEs!)
• Adds a Parameter Computed from the Analysis Value of Other Parameters — derive_param_computed • admiral admiral::derive_param_computed()
• Derive/Impute a Date from a Character Date — derive_vars_dt • admiral admiral::derive_vars_dt()
• Derive/Impute a Date from a Character Date — derive_vars_dt • admiral admiral::derive_vars_dt()
• Add a Variable Flagging the First or Last Observation Within Each By Group — derive_var_extreme_flag • admiral admiral::derive_var_extreme_flag()

This is not to say that the other functions do not have examples anymore; rather, they retain the previous material.

Now, our aim as a development team is to continually enhance the reference examples of our large portfolio of functions regularly across release cycles. If you’d like to play a part, this is also a great opportunity to contribute to ADaM in R Asset Library • admiral {admiral} yourself – please get in touch with our development team through Slack or our Github repo and we’d be happy to help you get started.

We’ve also made various other small documentation enhancements, which you can peruse in the Changelog.

New Function

But we haven’t stopped there! Here’s what else is new in ADaM in R Asset Library • admiral {admiral} 1.3:

• We’ve enhanced our catalog of functions with a new addition: Summarize Variables from an Additional Dataset Based on Conditions from Both Datasets — derive_vars_joined_summary • admiral admiral::derive_vars_joined_summary() . This function is similar to Add Variables from an Additional Dataset Based on Conditions from Both Datasets — derive_vars_joined • admiral admiral::derive_vars_joined() , but allows the derivation of summary variables (e.g. cumulative sum, etc) rather than variables using a formula. For instance, here’s an example derivation in ADAE of CUMDOSA, the cumulative dose received up until an adverse event:

library(tibble)
library(dplyr, warn.conflicts = FALSE)
library(admiral)

adex <- tribble(
  ~USUBJID, ~ADY, ~AVAL,
  "1",         1,    10,
  "1",         8,    20,
  "1",        15,    10,
  "2",         8,     5
)

adae <- tribble(
  ~USUBJID, ~ADY, ~AEDECOD,
  "1",         2, "Fatigue",
  "1",         9, "Influenza",
  "1",        15, "Theft",
  "1",        15, "Fatigue",
  "2",         4, "Parasomnia",
  "3",         2, "Truancy"
)

derive_vars_joined_summary(
  dataset = adae,
  dataset_add = adex,
  by_vars = exprs(USUBJID),
  filter_join = ADY.join <= ADY,
  join_type = "all",
  join_vars = exprs(ADY),
  new_vars = exprs(CUMDOSA = sum(AVAL, na.rm = TRUE))
)

# A tibble: 6 × 4
  USUBJID   ADY AEDECOD    CUMDOSA
  <chr>   <dbl> <chr>        <dbl>
1 1           2 Fatigue         10
2 1           9 Influenza       30
3 1          15 Theft           40
4 1          15 Fatigue         40
5 2           4 Parasomnia      NA
6 3           2 Truancy         NA

• We now provide new lab grading metadata specifically tailored for US (Conventional) units across three grading criteria: NCI-CTCAEv4 (atoxgr_criteria_ctcv4_uscv), NCI-CTCAEv5 (atoxgr_criteria_ctcv5_uscv), and DAIDs (atoxgr_criteria_daids_uscv).
• Default values for function arguments are now always displayed in argument descriptions.

Breaking Changes

Excluding deprecations, we have only two small breaking changes:

• We’ve renamed SI_UNIT_CHECK to UNIT_CHECK in lab grading metadata variables: atoxgr_criteria_ctcv4(), atoxgr_criteria_ctcv5(), and atoxgr_criteria_daids() to simplify specifications.
• The values of the variable specified for tmp_obs_nr_var in Add Variables from an Additional Dataset Based on Conditions from Both Datasets — derive_vars_joined • admiral admiral::derive_vars_joined() , Derives a Flag Based on an Existing Flag — derive_var_joined_exist_flag • admiral admiral::derive_var_joined_exist_flag() and Filter Observations Taking Other Observations into Account — filter_joined • admiral admiral::filter_joined() are now populated differently if there are multiple records in dataset or dataset_add for the same values of by_vars and order. Before each of these records was assigned a different value, i.e., the variable (together with by_vars) was a unique identifier. Now the value is the same for all these records.

We’ve also started pre-alerting users of an upcoming breaking change to the default behavior of Derive/Impute a Datetime from a Character Date — derive_vars_dtm • admiral admiral::derive_vars_dtm() in our next release (1.4.0), where we’ll switch the default value of ignore_seconds_flag from FALSE to TRUE. Ahead of this change, Derive/Impute a Datetime from a Character Date — derive_vars_dtm • admiral admiral::derive_vars_dtm() now issues a helpful message informing users of the upcoming change, to allowing mitigation ahead of time.

Updates of existing functions and bug fixes

We’ve also been busy updating some of our existing functions in response to bug fixes and requests for enhancements. One particular update of note was to admiral::derive_locf_records, which now comes with two new arguments id_vars_ref and imputation. The id_vars_ref argument allows users to select the variables to group by in the reference dataset when determining which observations to add to the input dataset. The imputation argument lets users decide whether to update analysis_var when its value is NA (“update” and “update_add”), or to add a new observation instead (“add”).

You can find the full list of updates in the Changelog.

Conclusion

We’ve been truly thrilled with the amount of user feedback and engagement with the package in the last six months, which is a big reason for the amount of content in this new release. As such, we’re super excited to finally make ADaM in R Asset Library • admiral {admiral} 1.3 available to the pharmaverse community, and look forward to continuing to co-create ADaM in R Asset Library • admiral {admiral} together!