Make as card check format (#534)

Resolves #514 

Incorportating `check_ard_structure` into `as_card` proved to not be
straight forwards as `as_card` is used throughout the code base to
coerce objects into a card class that do not pass the checks in
`check_ard_structure`.

For now at least I did the following

1) `check_ard_structure` can either error or warn based on user input. I
made a function to switch between these (I couldn't see any function
which existed to do this already). Part of me wonders about allowing the
user a bit more control over what it considers an error or a warning;
they can switch off caring about the column order, and whether there is
a methods entry, but maybe we could allow more in future. That said I
think it's probably better as a binary switch for a change
2) In `as_card`, there is now an argument for whether you want to check
if a card follows this structure. At the moment this defaults to TRUE,
but if you think this is too strong I could switch it to default FALSE.
Doing that would be the most low impact change.

---------

Signed-off-by: Kieran Martin <kieranjmartin@gmail.com>
Co-authored-by: Davide Garolini <davide.garolini@roche.com>
Co-authored-by: Davide Garolini <dgarolini@gmail.com>
Co-authored-by: Daniel Sjoberg <danield.sjoberg@gmail.com>

Author: 3 people

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: cards
 Title: Analysis Results Data
-Version: 0.7.1.9004
+Version: 0.7.1.9005
 Authors@R: c(
     person("Daniel D.", "Sjoberg", , "danield.sjoberg@gmail.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-0862-2018")),

NEWS.md

@@ -1,9 +1,12 @@
-# cards 0.7.1.9004
+# cards 0.7.1.9005
 
 * Adding `ard_tabulate_rows()` function to tabulate the number of rows in a data frame. (#531)
 
 * Users are now messaged if the `by` or `strata` arguments pass columns with different classes in the `ard_tabulate(data,denominator)` arguments as this _may_ cause issues downstream. (#515)
 
+* `as_card` now has the argument `check = TRUE` which when `TRUE` will confirm if the data frame being converted matches the cards spec using `check_ard_structure`. To support this, `check_ard_structure` has a new argument `error_on_fail` which is FALSE by default. When TRUE any failures will generate an error. (#514)
+
+
 # cards 0.7.1
 
 * Updated `ard_stack_hierarchical()` so that the `denominator` dataset only contains the `id` and `by` variables. (#482)

R/ard_attributes.R

@@ -54,7 +54,7 @@ ard_attributes.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
 

R/ard_formals.R

@@ -46,5 +46,5 @@ ard_formals <- function(fun, arg_names, passed_args = list(),
   # put formals list in ARD structure ------------------------------------------
   enframe(lst_args[arg_names], "stat_name", "stat") |>
     dplyr::mutate(stat_label = .data$stat_name, .after = "stat_name") |>
-    as_card()
+    as_card(check = FALSE)
 }

R/ard_hierarchical.R

@@ -114,7 +114,7 @@ ard_hierarchical.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
   # if denominator doesn't have all by, they need to be added ------------------
@@ -192,7 +192,7 @@ ard_hierarchical_count.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
   # add dummy variable for counting --------------------------------------------
@@ -210,7 +210,7 @@ ard_hierarchical_count.data.frame <- function(data,
   ) |>
     .rename_last_group_as_variable(by = by, variables = variables) |>
     dplyr::mutate(context = "hierarchical_count") |>
-    as_card()
+    as_card(check = FALSE)
 }
 
 #' Rename Last Group to Variable

R/ard_missing.R

@@ -58,7 +58,7 @@ ard_missing.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
   # convert all variables to T/F whether it's missing --------------------------

R/ard_mvsummary.R

@@ -91,7 +91,7 @@ ard_mvsummary.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
   missing_statistics_vars <- setdiff(variables, names(statistic))

R/ard_stack_hierarchical.R

@@ -517,7 +517,7 @@ internal_stack_hierarchical <- function(
   }
 
   # return final result --------------------------------------------------------
-  result |> as_card()
+  result |> as_card(check = FALSE)
 }
 
 # this function calculates either the counts or the rates of the events

R/ard_strata.R

@@ -111,6 +111,6 @@ ard_strata <- function(.data, .by = NULL, .strata = NULL, .f, ...) {
   # unnest ard data frame and return final table -------------------------------
   df_nested_data |>
     tidyr::unnest(cols = all_of("ard")) |>
-    as_card() |>
+    as_card(check = FALSE) |>
     tidy_ard_column_order(group_order = "descending")
 }

R/ard_summary.R

@@ -127,7 +127,7 @@ ard_summary.data.frame <- function(data,
 
   # return empty ARD if no variables selected ----------------------------------
   if (is_empty(variables)) {
-    return(dplyr::tibble() |> as_card())
+    return(dplyr::tibble() |> as_card(check = FALSE))
   }
 
 
@@ -187,7 +187,7 @@ ard_summary.data.frame <- function(data,
     dplyr::mutate(context = "summary") |>
     tidy_ard_column_order() |>
     tidy_ard_row_order() |>
-    as_card()
+    as_card(check = FALSE)
 }