Merge branch 'devel' into 318_321_documentation_update@devel

NEWS.md

@@ -4,6 +4,8 @@
 
 ## Updates of Existing Functions
 
+- The messaging for `warn_if_invalid_dtc()` was updated to align with what the date/datetime functions in `admiral` currently do. (#316)
+
 ## Breaking Changes
 
 - The following functions/arguments have been deprecated from previous admiral versions using the next phase of the deprecation process: (#288)

R/warnings.R

@@ -69,20 +69,10 @@ warn_if_invalid_dtc <- function(dtc, is_valid = is_valid_dtc(dtc)) {
     )
 
     info <- paste0(
-      "The following ISO representations are handled: \n",
-      "2003-12-15T13:15:17.123\n",
-      "2003-12-15T13:15:17\n",
-      "2003-12-15T13:15\n",
-      "2003-12-15T13\n",
-      "2003-12-15\n",
-      "2003-12\n",
-      "2003\n",
-      "2003---15\n\n",
-      "The following ISO representations, and any other representation are NOT handled: \n",
-      "2003-12-15T-:15:18\n",
-      "2003-12-15T13:-:19\n",
-      "--12-15\n",
-      "-----T07:15"
+      "ISO representations of the form YYYY-MM-DDThh:mm:ss.ddd are expected, ",
+      "e.g., 2003-12-15T13:15:17.123. Missing parts at the end can be omitted. ",
+      "Missing parts in the middle must be represented by a dash, e.g., 2003---15.",
+      sep = "\n"
     )
     warn(paste(main_msg, tbl, info, sep = "\n"))
   }

tests/testthat/test-warnings.R

@@ -21,11 +21,12 @@ test_that("warn_if_vars_exist Test 1: warning if a variable already exists in th
   )
 })
 
-# warn_if_invalud_dtc ----
+# warn_if_invalid_dtc ----
 ## Test 2: Warning if vector contains unknown datetime format ----
-test_that("warn_if_invalud_dtc Test 2: Warning if vector contains unknown datetime format", {
+test_that("warn_if_invalid_dtc Test 2: Warning if vector contains unknown datetime format", {
   expect_warning(
-    warn_if_invalid_dtc(dtc = "20210406T12:30:30")
+    warn_if_invalid_dtc(dtc = "20210406T12:30:30"),
+    "Dataset contains incorrect datetime format:"
   )
 })
 

vignettes/programming_strategy.Rmd

@@ -208,25 +208,26 @@ Arguments which expect a boolean or boolean vector must start with a verb, e.g.,
 Arguments which only expect one value or variable name must be a singular version of the word(s), e.g., `missing_value` or `new_var`. Arguments which expect several values or variable names (as a list, expressions, etc.) must be a plural version of the word(s), e.g., `missing_values` or `new_vars`.
 
 ## List of Common Arguments
-
-| Argument Name   | Description                                                                                                        |
+| Argument Name   | Description                                                                                                         |
 |------------------|--------------------------------------------------------------------------------------------------------------------|
 | `dataset`        | The input dataset. Expects a data.frame or a tibble.                                                               |
+| `dataset_ref`    | The reference dataset, e.g. ADSL. Typically includes just one observation per subject.                             |
+| `dataset_add`    | An additional dataset. Used in some `derive_xx` and `filter_xx` functions to access variables from an additional dataset.            |
 | `by_vars`        | Variables to group by.                                                                                             |
-| `order`          | List of expressions for sorting a dataset, e.g., `exprs(PARAMCD, AVISITN, desc(AVAL))`.                             |
+| `order`          | List of expressions for sorting a dataset, e.g., `exprs(PARAMCD, AVISITN, desc(AVAL))`.                            |
 | `new_var`        | Name of a single variable to be added to the dataset.                                                              |
 | `new_vars`       | List of variables to be added to the dataset.                                                                      |
-| `new_var_unit`   | Name of the unit variable to be added. It should be the unit of the variable specified for the `new_var` argument.  |
+| `new_var_unit`   | Name of the unit variable to be added. It should be the unit of the variable specified for the `new_var` argument. |
 | `filter`         | Expression to filter a dataset, e.g., `PARAMCD == "TEMP"`.                                                         |
 | `start_date`     | The start date of an event/interval. Expects a date object.                                                        |
 | `end_date`       | The end date of an event/interval. Expects a date object.                                                          |
 | `start_dtc`      | (Partial) start date/datetime in ISO 8601 format.                                                                  |
 | `dtc`            | (Partial) date/datetime in ISO 8601 format.                                                                        |
 | `date`           | Date of an event / interval. Expects a date object.                                                                |
-| `subject_keys`   | Variables to uniquely identify a subject, defaults to `exprs(STUDYID, USUBJID)`. In function formals, use `subject_keys = get_admiral_option("subject_keys")`      
-| `set_values_to`  | List of variable name-value pairs. Use `process_set_values_to()` for processing the value and providing user friendly error messages. |                               |
-| `keep_source_vars` | Specifies which variables from the selected observations should be kept. The default of the argument should be `everything()`. The primary difference between `set_values_to` and `keep_source_vars` is that `keep_source_vars` only selects and retains the variables from a source dataset, so e.g. `keep_source_vars = exprs(DOMAIN)` would join + keep the `DOMAIN` variable, whereas `set_values_to` can make renaming and inline function changes such as `set_values_to = exprs(LALVDOM = DOMAIN)`                       |
-| `missing_value`    | A singular value to be entered if the data is missing.                                  |
+| `set_values_to`  | List of variable name-value pairs. Use `process_set_values_to()` for processing the value and providing user friendly error messages. |
+| `subject_keys`   | Variables to uniquely identify a subject, defaults to `exprs(STUDYID, USUBJID)`. In function formals, use `subject_keys = get_admiral_option("subject_keys")`                                     |
+| `keep_source_vars` | Specifies which variables from the selected observations should be kept. The default of the argument should be `everything()`.                                          |
+| `missing_value`    | A singular value to be entered if the data is missing.                                                           |
 | `missing_values`   | A named list of expressions where the names are variables in the dataset and the values are a value to be entered if the data is missing, e.g., `exprs(BASEC = "MISSING", BASE = -1)`.      |
 
 ## Source Code Formatting