Update keep to mandatory in ds_vars table

NEWS.md

@@ -1,4 +1,5 @@
 # metacore 0.3.0
+- `keep` variable in `ds_vars` table has been changed to `mandatory` to better reflect the CDISC standard terminology. 
 
 # Metacore 0.2.1
 -   Hotfix import `cli_alert_info` issue from {cli} package.

R/metacore.R

@@ -30,7 +30,7 @@ MetaCore_initialize <- function(ds_spec, ds_vars, var_spec, value_spec, derivati
                variable = "Variable Name",
                key_seq = "Sequence Key",
                order = "Variable Order",
-               keep = "Keep (Boolean)",
+               mandatory = "Mandatory (Boolean)",
                core = "ADaM core (Expected, Required, Permissible)",
                supp_flag = "Supplemental Flag")
 
@@ -250,7 +250,7 @@ MetaCore <- R6::R6Class("Metacore",
                            .ds_vars = tibble(
                               dataset = character(),
                               variable = character(),
-                              keep = logical(),
+                              mandatory = logical(),
                               key_seq = integer(),
                               order = integer(),
                               core = character(),
@@ -333,7 +333,7 @@ MetaCore <- R6::R6Class("Metacore",
 #' @export
 #'
 metacore <- function(ds_spec = tibble(dataset = character(), structure = character(), label = character()),
-                     ds_vars = tibble(dataset = character(), variable = character(), keep = logical(),
+                     ds_vars = tibble(dataset = character(), variable = character(), mandatory = logical(),
                                       key_seq = integer(), order = integer(), core = character(),
                                       supp_flag = logical()),
                      var_spec = tibble(variable = character(), label = character(), length = integer(),

R/spec_builder.R

@@ -143,14 +143,14 @@ spec_type_to_ds_spec <- function(doc, cols = c("dataset" = "[N|n]ame|[D|d]ataset
 spec_type_to_ds_vars <- function(doc, cols = c("dataset" = "[D|d]ataset|[D|d]omain",
                                                "variable" = "[V|v]ariable [[N|n]ame]?|[V|v]ariables?",
                                                "order" = "[V|v]ariable [O|o]rder|[O|o]rder",
-                                               "keep" = "[K|k]eep|[M|m]andatory"),
+                                               "mandatory" = "[K|k]eep|[M|m]andatory"),
                                  key_seq_sep_sheet = TRUE,
                                  key_seq_cols = c("dataset" = "Dataset",
                                                   "key_seq" = "Key Variables"),
                                  sheet = "[V|v]ar|Datasets"){
 
    name_check <- names(cols) %in% c("variable", "dataset", "order",
-                                    "keep", "key_seq", "core", "supp_flag") %>%
+                                    "mandatory", "key_seq", "core", "supp_flag") %>%
       all()
 
    name_check_extra <- names(key_seq_cols) %in% c("dataset", "key_seq") %>%
@@ -160,7 +160,7 @@ spec_type_to_ds_vars <- function(doc, cols = c("dataset" = "[D|d]ataset|[D|d]oma
    # Testing for names of vectors
    if(any(!name_check, !name_check_extra, is.null(names(cols)))){
       cli_abort("Supplied column vector must be named using the following names:
-              'variable', 'dataset', 'order', 'keep', 'core', 'key_seq', 'supp_flag'")
+              'variable', 'dataset', 'order', 'mandatory', 'core', 'key_seq', 'supp_flag'")
    }
    # Subsetting sheets
    if(!is.null(sheet)){
@@ -191,10 +191,10 @@ spec_type_to_ds_vars <- function(doc, cols = c("dataset" = "[D|d]ataset|[D|d]oma
    out %>%
       distinct() %>%
       `is.na<-`(missing) %>%
-      mutate(key_seq = as.integer(key_seq),
-             keep = yn_to_tf(keep),
-             core = as.character(core),
-             order = as.numeric(order))
+      mutate(key_seq = as.integer(.data$key_seq),
+             mandatory = yn_to_tf(.data$mandatory),
+             core = as.character(.data$core),
+             order = as.numeric(.data$order))
 }
 
 
@@ -403,7 +403,7 @@ spec_type_to_value_spec <- function(doc, cols = c("dataset" = "[D|d]ataset|[D|d]
          left_join(where_df, by = c("where" = "id")) %>%
          select(-where, where = where_new)
    } else if(where_sep_sheet) {
-      cli_warn("Not able to add where infromation from seperate sheet cause a where column is needed to cross-reference the information",
+      cli_warn("Not able to add where information from seperate sheet cause a where column is needed to cross-reference the information",
                call. = FALSE)
    }
 

R/validators.R

@@ -194,7 +194,7 @@ supp_check <- function(ds_vars, supp){
 #' @noRd
 col_vars <- function(){
    list(.ds_spec = c("dataset", "structure", "label"),
-        .ds_vars = c("dataset", "variable", "key_seq", "order","keep", "core", "supp_flag"),
+        .ds_vars = c("dataset", "variable", "key_seq", "order","mandatory", "core", "supp_flag"),
         .var_spec = c("variable", "length", "label", "type", "common", "format"),
         .value_spec = c("dataset", "variable", "type", "origin","sig_dig", "code_id", "where", "derivation_id"),
         .derivations = c("derivation_id", "derivation"),
@@ -259,7 +259,7 @@ all_message <- function() {
    "ds_vars",     "variable",      is.character,                FALSE,
    "ds_vars",     "key_seq",       is.numeric,                  TRUE,
    "ds_vars",     "order",         is.numeric,                  TRUE,
-   "ds_vars",     "keep",          is.logical,                  TRUE,
+   "ds_vars",     "mandatory",          is.logical,                  TRUE,
    "ds_vars",     "core",          check_words("Expected", "Required", "Permissible", "Conditionally Required", "Conditionally Expected", NA), TRUE,
    "ds_vars",     "supp_flag",     is.logical,                  TRUE,
    "var_spec",    "variable",      is.character,                FALSE,

R/xml_builders.R

@@ -80,13 +80,13 @@ xml_to_ds_vars <- function(doc) {
       }) %>%
       mutate(
          variable = id_to_var(.data$oid),
-         keep = .data$mandatory == "Yes",
+         mandatory = .data$mandatory == "Yes",
          core = NA_character_,
          supp_flag = NA
       ) %>%
       select(.data$dataset, .data$variable, .data$key_seq,
-             .data$order, .data$keep, .data$core, .data$supp_flag,
-             -.data$mandatory, -.data$oid)
+             .data$order, .data$mandatory, .data$core, .data$supp_flag,
+             .data$mandatory, -.data$oid)
 }
 
 

R/zzz.R

@@ -39,3 +39,7 @@ globalVariables(c("private",
                   "where_new",
                   "var1",
                   "n_lab"))
+
+.onAttach <- function(libname, pkgname) {
+   packageStartupMessage("Attaching package `metacore`\n\nAs of metacore 0.3.0 the `keep` variable in the `ds_vars` table has been renamed to `mandatory`. Please see release documentation for details.")
+}

README.Rmd

@@ -80,7 +80,7 @@ This table contains the information that bridges between purely dataset level an
 
 -   *order*: Order sets the order of the columns to appear in the dataset. This is also a numeric value
 
--   *keep*: Logical value about if the variable needs to be kept
+-   *mandatory (previously `keep`)*: Boolean specifying whether a variable can have blank values. From the CDISC Define-XML v2.1 documentation: Required items that have Mandatory set to "Yes" cannot have blank values. Variables in SDTM domains that have `core = "Required"` should have `mandatory = TRUE`. Note that `keep` was deprecated in v0.3.0 in favour of `mandatory` to better align the package and CDISC terminology.
 
 -   *core*: ADaM core, which should be one of the following values: "Expected", "Required", "Permissible", "Conditionally Required", "Conditionally Expected", or NA. For more information about core see [CDISC](https://www.cdisc.org/standards/foundational/adam)
 

tests/testthat/test-metacore.R

@@ -56,7 +56,7 @@ test_that("Can pass metacore NULL df's", {
    dummy <- list(character(), character(), numeric(), numeric(),
                  logical(), character(), logical())
    names(dummy) <- c("dataset", "variable", "key_seq", "order",
-                     "keep", "core", "supp_flag")
+                     "mandatory", "core", "supp_flag")
    dummy <- as_tibble(dummy)
    #Because of the labels the dfs are slightly different so checking
    # the insides match

tests/testthat/test-reader.R

@@ -40,7 +40,7 @@ test_that("Test ds_spec readers", {
 test_that("Test ds_vars readers", {
    # Create a reference ds_vars
    ref_ds_vars <- tibble::tribble(
-      ~dataset,  ~variable, ~key_seq, ~order, ~keep, ~core, ~supp_flag,
+      ~dataset,  ~variable, ~key_seq, ~order, ~mandatory, ~core, ~supp_flag,
       "AE",    "AEACN",       NA,    21L, FALSE,    NA_character_, NA,
       "AE", "AEBDSYCD",       NA,    16L, FALSE,    NA_character_, NA,
       "AE", "AEBODSYS",       NA,    15L, FALSE,    NA_character_, NA,
@@ -150,7 +150,7 @@ test_that("Test ds_vars readers", {
    # Read from spec
    spec_ds_vars <- spec_type_to_ds_vars(spec) %>%
       arrange(dataset, variable) %>%
-      select(dataset, variable, key_seq, order, keep, core, supp_flag)
+      select(dataset, variable, key_seq, order, mandatory, core, supp_flag)
 
 
    # Tests

vignettes/Building_Specification_Readers.Rmd

@@ -107,7 +107,7 @@ The ds_vars table has 7 columns:
 
 -   order: integer controlling the column order of each dataset
 
--   keep: boolean to determine if the variable is needed
+-   mandatory: from Define-XML v2.1. A Boolean value indicating if NULL values are permitted. `mandatory = TRUE` indicates that NULL values are not permitted.
 
 -   core: ADaM core (Expected, Required, Permissible)
 
@@ -127,7 +127,7 @@ doc$Variables %>% head()
 ds_vars<- spec_type_to_ds_vars(doc, cols = c("dataset" = "Domain",
                                              "variable" = "[V|v]ariable [N|n]ame",
                                              "order" = "[V|v]ariable [O|o]rder",
-                                             "keep" = "[M|m]andatory"),
+                                             "mandatory" = "[M|m]andatory"),
                                key_seq_cols = c("dataset" = "Domain Name",
                                                 "key_seq" = "Key"),
                                sheet = "[V|v]ar|Domains")