v1.1.1

admiral 1.1.1

• derive_extreme_event() was fixed such that check_type = "none" is accepted again. (#2462)

admiral 1.1.0

admiral 1.1.0

New Features

• Added helper functions to derive_vars_merged() (get_flagged_records()) and derive_vars_query() (get_vars_query()) so that those can be called independently as per user's request. derive_vars_merged() function call results are not impacted by the change (#2441).

• Error Messaging has been made more "user-friendly". (#2372)

• New country_code_lookup() metadata added to decode countries based on ISO 3166 codes. (#2388)

Updates of Existing Functions

• group_var (optional) parameter is added to derive_var_trtemfl() to derive TRTEMFL for AE data if the data are collected as one episode of AE with multiple lines. (#2302)

• Templates for ADPC, ADPPK and ADPP are updated to handle urine records. (#2392)

• create_single_dose_dataset() has been updated to error if the lookup_table contains duplicates. (#2247)

• derive_vars_merged() and derive_vars_transposed() have a relationship argument added (the same as found in dplyr::*_join() functions) for users to specify what type of join (one-to-one, one-to-many, etc.) should take place. (#2247)

• basket_select() function updated to add ... argument to allow other qualifiers to be passed to user-defined function specified in get_terms_fun() argument for function create_query_data(). (#2265)

• Messaging updated for derive_extreme_event() to improve clarity around duplicates. #2405

• The id_vars argument was added to derive_vars_transposed() and derive_vars_atc() to allow additional variables, beyond those in by_vars, to uniquely identify records in the dataset_merge argument. (#2325)

• Update PK Programming vignette and templates for ADPC and ADPPK for the nominal time formula NFRLT to reduce duplicate records in dose expansion with create_single_dose_dataset(). (#2426)

• Template for ADSL updated so that EOSSTT is assigned as "ONGOING" when no study completion rows exist yet in DS. (#2436)

• The slice_derivation() function was updated such that it works now when
  called in a function where objects from the function environment are used.
  (#2244)

Breaking Changes

• The following function arguments are entering the next phase of the deprecation process: (#2299)

  • compute_egfr(wt)
  • consolidate_metadata(check_keys)
  • derive_expected_records(dataset_expected_obs)
  • derive_locf_records(dataset_expected_obs)
  • derive_extreme_event(ignore_event_order)
  • derive_vars_merged(match_flag, new_var, analysis_var, summary_fun)
  • derive_param_computed(analysis_value, analysis_var)
  • derive_param_exposure(filter, analysis_var, summary_fun)
  • derive_summary_records(filter)
  • derive_extreme_records(filter)
  • derive_var_joined_exist_flag(first_cond, filter)
  • event_joined(first_cond)
  • filter_joined(first_cond, filter)

• The following function arguments have reached the end of the deprecation process and been removed: (#2299)

  • dthcaus_source(traceability_vars)
  • date_source(traceability_vars)
  • derive_var_ontrtfl(span_period)
  • derive_var_shift(na_val)
  • derive_vars_aage(unit)

Documentation

• Documentation for derive_extreme_event() has been updated to include a description for the value of derive_extreme_event() when keep_source_vars = NULL. (#2398)

• The "Visit and Period Variables" vignette was updated and refactored to include example code to create a period reference dataset. (#2321)

• The documentation of derive_vars_merged() function is updated to describe that the check_type argument is ignored (an error is issued) if order is not specified. (#2326)

• The "User Guides" section has been reorganized. A new "Programming Concepts and Conventions" vignette was also added to provide more context and information around common {admiral} behaviors and ways of working. (#2395)

• The "Get Started" section has been revamped, placing greater focus on material that may help users familiarize themselves with {admiral}. There are now new sections showcasing the various types of {admiral}
  functions and some of the more advanced topics have been moved to the new "Programming Concepts and Conventions" vignette. (#2395)

• The Examples section of derive_param_computed() now contains a new item showcasing how to create a derived parameter in the case that a variable contributing to the derived parameter has some/all of its values missing. (#2338)

Various

• Templates and vignettes do not add or populate AVALC for BDS-findings datasets where the information contained in AVALC would be redundant with AVAL. (#2442)

• The function dplyr::transmute() is superseded in favor of dplyr::mutate(.keep = "none"). Consequently, all the admiral functions that utilized the former have been updated accordingly. (#2274)

• The templates for ADPP and ADPC are updated for missing variables (#2308) and to make ATPT and ATPTN consistent. (#2328)

• ADLB template updated to make PARAM consistent for PARAMCD values "BASO" and "LYMPH". (#2327)

Developer Notes

• In the previous version, renv was the default framework used to manage package dependencies. Now, we use devtools as our main package manager (some changes also occurred for admiralci workflows).
  There is a possibility to get package dependency versions used for the workflows to ensure local reproducibility. For this, you need to go under the latest action summary in your current PR. You can see a deps artifact. For each version of R used for R CMD CHECKS jobs, there is an associated renv.lock file (under the deps artifact).
• Splitting out R and test files for date/time functions for cyclomatic complexity refactor (#2340)(#2339)
• Created three unit tests for get_summary_records(). (#2304)
• Created unit tests for developer internal function get_imputation_target_date() (#2378)
• Modified date/time unit tests to use unified example (#2424)

admiral 1.0.2

Fix bug in derive_param_tte() where argument dataset populated and PARAMCD in set_values_to argument is an expression. Previously, there was a check early in function to see if PARAMCD defined in set_values_to argument, already existed in the dataset passed into dataset argument. If PARAMCD was not an expression i.e. PARAMCD = "XYZ" then check worked. However, if PARAMCD to be created was an expression, and wasn't resolved yet, this caused an ERROR. The check has been moved to near the end of the function, where PARAMCD is resolved in the dataset holding the new parameters. (#2336)

admiral 1.0.1

• Fix bug in derive_vars_query() where if AE terms were in mixed case no terms are flagged. (#2311)

admiral 1.0.0

admiral 1.0.0

New Features

• The new function derive_vars_extreme_event(), which works as derive_extreme_event()
  but adds variables instead of a parameter. (#2138)

• The new function derive_var_merged_ef_msrc() is provided to add a flag
  indicating if one of the conditions in one of multiple source datasets is
  fulfilled. (#1728)

• New global option created signif_digits and added to set_admiral_options() to
  handle floating point issue, the value is set to 15, and is used with the base R
  function signif() when comparing 2 numeric values. This is implemented in admiral
  functions derive_var_atoxgr_dir() and derive_var_anrind(). (#2134)

  For more information, please see blog: How admiral handles floating points

• The new function derive_vars_computed() is provided which has the same
  functionality as derive_param_computed() but instead of adding the computed
  values as a new parameter, adds it as a new variable. (#2178)

Updates of Existing Functions

• Fixed a bug in compute_tmf() where the time imputation flag was being incorrectly
  populated when any of the existing time components (hour, minute and/or second) of the date
  character vector ('--DTC'), was imputed. (#2146)

• derive_extreme_records(), derive_var_extreme_flag(),derive_vars_joined() and derive_vars_merged() were enhanced with the arguments true_value and false_value to align with preexisting functions that had similar functionality. (#2125)

• restrict_derivation() now allows {dplyr} functions like mutate() in the
  derivation argument. (#2143)

• derive_summary_records(), derive_var_merged_summary(), and get_summary_records()
  were enhanced such that more than one summary variable can be derived, e.g.,
  AVAL as the sum and ADT as the maximum of the contributing records. (#1792)

• derive_summary_records() was enhanced with the following arguments: dataset_add (required), dataset_ref (optional), missing_values (optional). These arguments respectively, generate summary variables from additional datasets, retain/add specific records from a reference dataset, and impute user-defined missing values. Note that dataset_add can be set to the same value as dataset if a different additional dataset is not required. derive_param_exposure() was enhanced with dataset_add as well. (#2142)

• The missing_values argument was added to derive_var_merged_summary(). It
  allows to define values for by groups, e.g., subjects which are not in the
  additional dataset. (#2230)

• The argument dataset is now optional for derive_summary_records() and derive_param_exposure(). (#2142)

• The "joined" functions (derive_vars_joined(), derive_var_joined_exist_flag(),
  filter_joined(), and event_joined()) were unified: (#2126)

  • The dataset_add and filter_add arguments were added to
    derive_var_joined_exist_flag() and filter_joined().
  • The filter argument was renamed to filter_join in
    derive_var_joined_exist_flag() and filter_joined().
  • The tmp_obs_nr_var, the join_type, the first_cond_lower, and the
    first_cond_upper arguments were added to derive_vars_joined().
  • In derive_var_joined_exist_flag(), filter_joined(), and event_joined()
    the first_cond argument was renamed to first_cond_upper and the
    first_cond_lower argument was added.
  • In all "joined" functions the filter_add argument is applied to the
    additional dataset grouped by by_vars and the filter_join argument is
    applied to the joined dataset grouped by the observations from the input
    dataset. I.e., summary functions like all() or any() can be used.

• The tmp_event_nr_var argument was added to derive_extreme_records() to
  allow more control of the selection of records. It creates a temporary variable
  for the event number, which can be used in order. (#2140)

• signif_dig argument added to both derive_var_atoxgr_dir() and derive_var_anrind()
  functions with default value set to general option signif_digits. The new argument to
  these functions handles any floating point issues. (#2134)

• Fixed a bug in derive_vars_period() where the function was throwing an error whenever dataset_ref contained variables that were neither key variables, nor APERIOD, ASPER, APHASEN, nor mentioned in the new_vars argument. (#2231)

• compute_duration(), derive_vars_duration(), derive_vars_aage() now accepts more terms for the in_unit, out_unit, and age_unit arguments (#2255)

• Updated the unit test for derive_var_obs_number(). The new test checked the derivation of the default and customized new_var,
  sorting with the the missing value and expected conditions. (#2260)

• The check for existence of TERMNUM/TERMCHAR in queries dataset is now less strict depending on values of SRCVAR for derive_vars_query() (#2264)

• DAIDS grading criteria fixed for Grade = 0 for TERM = "Absolute Lymphocyte Count, Low", criteria was AVAL <= 0.65, now corrected to AVAL >= 0.65 (#2284).

• A bug in derive_extreme_event() was fixed. The condition field is no
  longer ignored if mode is specified for event() (#2291).

• A bug in derive_vars_joined() was fixed. The function no longer fails if
  renaming is used in by_vars and new_vars is not specified (#2289).

Breaking Changes

• {admiral} now only supports R >= 4.0.0

• In derive_extreme_records() the dataset_add argument is now mandatory. (#2139)

• In derive_summary_records() and get_summary_records() the arguments
  analysis_var and summary_fun were deprecated in favor of set_values_to.
  (#1792)

• In derive_summary_records() and derive_param_exposure() the argument filter was renamed to filter_add (#2142)

• In derive_var_merged_summary() the arguments new_var, analysis_var, and
  summary_fun were deprecated in favor of new_vars. (#1792)

• In derive_vars_merged(), the argument match_flag was renamed to exist_flag (#2125)

• The default value for the false_value argument in derive_extreme_records() was changed to NA_character_ (#2125)

• In consolidate_metadata(), the argument check_keys was renamed to check_type to align with other functions (#2184)

• In filter_joined() and derive_var_joined_exist_flag() (#2126)

  • the first_cond argument was deprecated in favor of first_cond_upper and
  • the filter argument was deprecated in favor of filter_join.

• In event_joined() the first_cond argument was deprecated in favor of
  first_cond_upper. (#2126)

• In derive_extreme_event(), the ignore_event_order argument was deprecated
  and the selection of the records was changed to allow more control. Before, the
  records were selected first by event and then by order. Now they are selected
  by order only, but the event number can be added to it.

  To achieve the old behavior update

order = exprs(my_order_var),
ignore_event_order = FALSE,

to

tmp_event_nr_var = event_nr,
order = exprs(event_nr, my_order_var),

and

order = exprs(my_order_var),
ignore_event_order = TRUE,

to

order = exprs(my_order_var),

• create_query_data() and derive_vars_query() were updated to rename variables in
  query data set as follows: (#2186)

  • TERMNAME to TERMCHAR
  • TERMID to TERMNUM

  Users need to adjust their get_terms() function accordingly.

• The following functions, which were deprecated in previous {admiral} versions, have been removed: (#2098)

  • derive_param_extreme_event()
  • derive_vars_last_dose()
  • derive_var_last_dose_amt()
  • derive_var_last_dose_date()
  • derive_var_last_dose_grp()
  • derive_var_basetype()
  • derive_var_merged_cat()
  • derive_var_merged_character()
  • derive_var_confirmation_flag()

• The following function arguments are entering the next phase of the deprecation process: (#2098)

  • compute_egfr(wt)
  • derive_extreme_records(filter)
  • derive_param_computed(analysis_value, analysis_var)
  • derive_var_shift(na_val)
  • 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)

• The functions derive_var_dthcaus(), derive_var_extreme_dt(), and derive_var_extreme_dtm() have been superseded in favor of derive_vars_extreme_event(). (#2138)

Documentation

• The documentation of the by_vars and constant_by_vars argument was improved and unified across all functions where it is used. (#2137)

• The functions assert_db_requirements(), assert_terms(), assert_valid_queries(),
  extend_source_datasets(), filter_date_sources(), validate_basket_select(),
  validate_query() are no longer exported and have had documentation removed. (#2220)

• The function extract_duplicate_records() has been re-classified as an internal
  function, which means that the function still appears in our help pages but not
  on our website. (#2220)

• The "Generic Functions" vignette (now "Generic Derivations") was rewritten.
  Now it provides a more complete overview of the generic derivations, describe
  the common concepts, and makes it easier to find the appropriate function.
  (#2230)

• A way to standardize roxygen labels and descriptions for function arguments was implemented and tested. (#2034)

• A link to published CDISC Population PK (ADPPK) implementation guide was added. (#2161)

• Removed Deprecation section in Reference tab. Added new Superseded section in
  Reference tab. (#2174)

• Added a link to the previous...

admiral 0.12.3

What's Changed

• Closes #2154 fix_dthcaus: fix derive_var_dthcaus() by @bundfussr in #2162
  Full Changelog: v0.12.2...v0.12.3

admiral 0.12.2

What's Changed

• Closes #2147 addressing cran failure by @zdz2101 in #2149
• Update README.md by @bms63 in #2155

Full Changelog: v0.12.0...v0.12.2

admiral 0.12.1

What's Changed

• ignore notes r cmd checks by @dgrassellyb in #2114
• Closes #2113 fix derive extreme records by @bundfussr in #2121
• Closes #2109 ADPP template program has x and y variables by @jeffreyad in #2110
• Closes #2112 add type to functions downstream of compute_duration() by @zdz2101 in #2118

Full Changelog: v0.12.0...v0.12.1

admiral 0.12.0

admiral 0.12.0

New Features

• event_joined() events were added. They can be specified for the events
  argument in derive_extreme_event(). This allows to define events based on more
  than one observation, e.g., events which need to be confirmed by a second
  assessment. (#1960)

• atoxgr_criteria_daids.rda added, which holds metadata for Division of AIDS (DAIDS) Table for Grading the Severity of Adult and Pediatric Adverse Events. You can find additional documentation here atoxgr_criteria_daids()

Updates of Existing Functions

• The functions derive_param_bmi() and derive_param_bsa() are updated to have the option of producing more values at visits when only weight is collected (#1228).

• The functions derive_var_age_years() and compute_age_years() are updated to return an NA age in the case that the age unit is missing. (#2001) The argument unit for derive_vars_aage() is also changed to age_unit for consistency between these age-related functions. (#2025)

• The derive_var_ontrtfl() function has been updated to allow for the column passed in ref_end_date to contain NA values. Previously, if the end date was NA, the row would never be flagged. Now, an NA value is interpreted as the treatment being ongoing, for example. (#1984)

• The function derive_var_extreme_flag() has a new function argument, flag_all that additionally flags all records if the first or last record is not unique. (#1979)

• The function derive_param_computed() was enhanced: (#1968)

  • The analysis_value and analysis_var arguments were deprecated in favor of
    set_values_to. This enables users to compute more than one variable.
  • The keep_nas argument was added. If it is set to TRUE, observations are
    created even if values contributing to the computed values are NA.

• The function derive_vars_dy() is updated to avoid potential error when the input dataset with columns ending with temp. (#2012)

• Argument keep_source_vars was added to derive_extreme_records() which
  specifies which variables in the new observations should be kept. (#1697)

• Templates, vignettes, and other uses of {admiral.test} SDTM data are updated to use {pharmaversesdtm} instead. (#2040)

• The traceability_vars argument in date_source() and dthcaus_source were deprecated in favor of set_values_to. The date_source() function creates a date_source object as input for derive_var_extreme_dt() and derive_var_extreme_dtm(),users can now define the traceability variables by assigning those variables to the set_values_toargument.Similarly, the dthcaus_source creates a dthcaus_source Object. (#2068)

• derive_extreme_event() was enhanced (#1960):

  • event_joined() events can be specified for the events argument. This
    allows to define events based on more than one observation, e.g., events
    which need to be confirmed by a second assessment.

  • The source_datasets argument was added to the function and the
    dataset_name field to event(). It can be used to define events based on
    a different dataset than the input dataset.

  • The keep_source_vars argument was added to the function and the
    keep_source_vars field to event(). It allows to select which variables
    should be kept for the selected observations.

  • The mode and order field were added to event(). They allow to select
    the first or last observation per by group if there are multiple observation
    fulfilling the event condition.

  • The ignore_event_order argument was added.

  • The description field was added to event(). It can be used to provide
    a description of the event in plain language.

• derive_var_atoxgr_dir() was enhanced (#1859):

  • Can now select atoxgr_criteria_daids in argument meta_criteria to create ATOXGRL and ATOXGRH based on Division of AIDS (DAIDS) Table for Grading the Severity of Adult and Pediatric Adverse Events

  • New argument signif_dig added to control the number of significant digits to use when comparing 2 numeric values.
    (#2060)

Breaking Changes

• The compute_duration(type) argument added the "duration" type calculation, and this is the new default (previously "interval" differences were returned). See function help file for details on the difference between "duration" and "interval" calculations. (#1875)

• The following functions, which were deprecated in previous {admiral} versions, have been removed: (#1950)

  • derive_var_disposition_status()
  • derive_vars_disposition_reason()
  • format_eoxxstt_default()
  • format_reason_default()
  • derive_var_worst_flag()

• The following functions have been deprecated from previous {admiral} versions using the next phase of the deprecation process: (#1950)

  • derive_param_extreme_event()
  • derive_vars_last_dose()
  • derive_var_last_dose_amt()
  • derive_var_last_dose_date()
  • derive_var_last_dose_grp()
  • derive_var_basetype()
  • derive_var_merged_cat()
  • derive_var_merged_character()

• The arguments dataset_adsl in the function derive_param_exist_flag() and
  subject_keys have been deprecated versions using the next phase of the deprecation process. (#1950)

• The argument wt in the function compute_egfr() was deprecated in favor of weight using the first phase of the deprecation process. (#2020)

• The filter argument in derive_extreme_records() was deprecated in favor of
  the filter_add using the next phase of the deprecation process. (#1950)

• The analysis_value and analysis_var arguments in derive_param_computed()
  were deprecated in favor of set_values_to (#1968).

• The na_val argument in derive_var_shift() has been deprecated in favor of
  missing_value using the first phase of the deprecation process. (#2014)

• The dataset_expected_obs argument in derive_expected_records() and derive_locf_records()
  has been deprecated in favor of dataset_ref. (#2037)

• The span_period argument in derive_var_ontrtfl() has been updated to only accept
  TRUE or FALSE, where is previously accepted "Y" and NULL. (#2033)

Documentation

• Non-exported utility and print functions were previously listed on the admiral website reference page. They have been removed. (#2049, #2050)

• The description of the argument reference_date in the function derive_vars_dy()
  has been clarified to make it agnostic to start/end selection. (#2027)

• Date and Time Imputation User Guide/Vignette has section on preserving partial
  dates updated (#2028)

Various

• The list of package authors/contributors has been reformatted so that those who are actively maintaining the code base are now marked as authors, whereas those who made a significant contribution in the past are now down as contributors. All other acknowledgements have been moved to README section (#1941).

• derive_vars_joined() had two bugs with regards to duplicates messaging and when new_vars was set to NULL that have now been addressed (#1966).

• compute_dtf() had a bug with regards to imputing days to full date-time character strings. (#2042)

admiral 0.11.1

Bug Fixes

• Fix bug in derive_param_tte(). (#1962)
• Get Started page now points to correct article. (#1969)