Merge pull request #200 from atorus-research/137_apply_all_write

Closes #137 - Add `xportr_process()` to apply all and write

NAMESPACE

@@ -5,6 +5,7 @@ export(length_log)
 export(type_log)
 export(var_names_log)
 export(var_ord_msg)
+export(xportr)
 export(xportr_df_label)
 export(xportr_format)
 export(xportr_label)

NEWS.md

@@ -15,6 +15,14 @@
 * It is now possible to get and set the xportr options using the helper function `xportr_options()` (#130)
 * Adds argument assertions to public functions using `{checkmate}` (#175)
 
+* `xportr_metadata()` can set `verbose` for a whole pipeline, i.e. setting `verbose` in `xportr_metadata()` will populate to all `xportr` functions.  (#151)
+
+* All `xportr` functions now have `verbose = NULL` as the default. If left `NULL`, the previous default of `getOption("xportr.[fn_name]_verbose")` is used (#151)
+
+* All core functions can be run together by using new function `xportr()` (#137)
+
+## Documentation
+
 ## Deprecation and Breaking Changes
 
 * The `domain` argument for xportr functions will no longer be dynamically 

R/format.R

@@ -18,9 +18,9 @@
 #'   "dataset". This is the column subset by the 'domain' argument in the
 #'   function.
 #'
-#'   2) Format Name - passed as the 'xportr.format_name' option.
-#'   Default: "format". Character values to update the '`format.sas`' attribute of
-#'   the column. This is passed to `haven::write` to note the format.
+#'   2) Format Name - passed as the 'xportr.format_name' option. Default:
+#'   "format". Character values to update the '`format.sas`' attribute of the
+#'   column. This is passed to `haven::write` to note the format.
 #'
 #'   3) Variable Name - passed as the 'xportr.variable_name' option. Default:
 #'   "variable". This is used to match columns in '.df' argument and the

R/length.R

@@ -5,15 +5,9 @@
 #' character columns, and 8 for non-character columns. This value is stored in
 #' the 'width' attribute of the column.
 #'
-#' @param .df A data frame of CDISC standard.
+#' @inheritParams xportr
 #' @param metadata A data frame containing variable level metadata. See
 #'   'Metadata' section for details.
-#' @param domain Appropriate CDSIC dataset name, e.g. ADAE, DM. Used to subset
-#'   the metadata object. If none is passed, then  [xportr_metadata()] must be
-#'   called before hand to set the domain as an attribute of `.df`.
-#' @param verbose The action this function takes when an action is taken on the
-#'   dataset or function validation finds an issue. See 'Messaging' section for
-#'   details. Options are 'stop', 'warn', 'message', and 'none'
 #' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass
 #'   metadata now renamed with `metadata`
 #'

R/xportr-package.R

@@ -91,6 +91,7 @@
 #'
 #'
 #' @keywords internal
+#' @aliases xportr-package
 #'
 #' @import rlang haven
 #' @importFrom dplyr left_join bind_cols filter select rename rename_with n

R/xportr.R

@@ -0,0 +1,69 @@
+#' Wrapper to apply all core xportr functions and write xpt
+#'
+#' @param .df A data frame of CDISC standard.
+#' @param var_metadata A data frame containing variable level metadata
+#' @param domain Appropriate CDSIC dataset name, e.g. ADAE, DM. Used to subset
+#'   the metadata object. If none is passed, then name of the dataset passed as
+#'   .df will be used.
+#' @param verbose The action this function takes when an action is taken on the
+#'   dataset or function validation finds an issue. See 'Messaging' section for
+#'   details. Options are 'stop', 'warn', 'message', and 'none'
+#' @param df_metadata A data frame containing dataset level metadata.
+#' @param path Path where transport file will be written. File name sans will be
+#'   used as `xpt` name.
+#' @param strict_checks If TRUE, xpt validation will report errors and not write
+#'   out the dataset. If FALSE, xpt validation will report warnings and continue
+#'   with writing out the dataset. Defaults to FALSE
+#'
+#' @return Returns the input dataframe invisibly
+#' @export
+#'
+#' @examplesIf requireNamespace("magrittr")
+#' library(magrittr)
+#' test_dir <- tempdir()
+#'
+#' pipeline_path <- file.path(test_dir, "adslpipe.xpt")
+#' xportr_path <- file.path(test_dir, "adslxptr.xpt")
+#'
+#' dataset_spec_low <- setNames(dataset_spec, tolower(names(dataset_spec)))
+#' names(dataset_spec_low)[[2]] <- "label"
+#'
+#' var_spec_low <- setNames(var_spec, tolower(names(var_spec)))
+#' names(var_spec_low)[[5]] <- "type"
+#'
+#' adsl %>%
+#'   xportr_metadata(var_spec_low, "ADSL", verbose = "none") %>%
+#'   xportr_type() %>%
+#'   xportr_length() %>%
+#'   xportr_label() %>%
+#'   xportr_order() %>%
+#'   xportr_format() %>%
+#'   xportr_df_label(dataset_spec_low) %>%
+#'   xportr_write(pipeline_path)
+#'
+#' # `xportr()` can be used to apply a whole pipeline at once
+#' xportr(
+#'   adsl,
+#'   var_metadata = var_spec_low,
+#'   df_metadata = dataset_spec_low,
+#'   domain = "ADSL",
+#'   verbose = "none",
+#'   path = xportr_path
+#' )
+xportr <- function(.df,
+                   var_metadata = NULL,
+                   df_metadata = NULL,
+                   domain = NULL,
+                   verbose = NULL,
+                   path,
+                   strict_checks = FALSE) {
+  .df %>%
+    xportr_metadata(var_metadata, domain = domain, verbose = verbose) %>%
+    xportr_type() %>%
+    xportr_length() %>%
+    xportr_label() %>%
+    xportr_order() %>%
+    xportr_format() %>%
+    xportr_df_label(df_metadata) %>%
+    xportr_write(path)
+}

README.Rmd

@@ -143,7 +143,7 @@ adsl %>%
 
 The `xportr_metadata()` function can reduce duplication by setting the variable specification and domain explicitly at the top of a pipeline. If you would like to use the `verbose` argument, you will need to set in each function call.
 
-```{r, message=FALSE, eval=FALSE}
+```{r, warning=FALSE, message=FALSE, eval=FALSE}
 adsl %>%
   xportr_metadata(var_spec, "ADSL", verbose = "warn") %>%
   xportr_type() %>%
@@ -155,6 +155,19 @@ adsl %>%
   xportr_write("adsl.xpt")
 ```
 
+Furthermore, if you're calling all xportr functions at once with common metadata and verbosity, you can shorten it by simply using `xportr()`.
+
+```{r, warning=FALSE, message=FALSE, eval=FALSE}
+xportr(
+  .df = adsl,
+  var_metadata = var_spec,
+  df_metadata = dataset_spec,
+  domain = "ADSL",
+  verbose = "warn",
+  "adsl.xpt"
+)
+```
+
 That's it!  We now have a xpt file created in R with all appropriate types, lengths, labels, ordering and formats.  Please check out the [Get Started](https://atorus-research.github.io/xportr/articles/xportr.html) for more information and detailed walk through of each `xportr_` function.
 
 We are in talks with other Pharma companies involved with the [`{pharmaverse}`](https://pharmaverse.org/) to enhance this package to play well with other downstream and upstream packages.  

README.md

@@ -155,7 +155,7 @@ each function call.
 
 ``` r
 adsl %>%
-  xportr_metadata(var_spec, "ADSL") %>%
+  xportr_metadata(var_spec, "ADSL", verbose = "warn") %>%
   xportr_type() %>%
   xportr_length() %>%
   xportr_label() %>%
@@ -165,6 +165,20 @@ adsl %>%
   xportr_write("adsl.xpt")
 ```
 
+Furthermore, if you’re calling all xportr functions at once with common
+metadata and verbosity, you can shorten it by simply using `xportr()`.
+
+``` r
+xportr(
+  .df = adsl,
+  var_metadata = var_spec,
+  df_metadata = dataset_spec,
+  domain = "ADSL",
+  verbose = "warn",
+  "adsl.xpt"
+)
+```
+
 That’s it! We now have a xpt file created in R with all appropriate
 types, lengths, labels, ordering and formats. Please check out the [Get
 Started](https://atorus-research.github.io/xportr/articles/xportr.html)

_pkgdown.yml

@@ -32,6 +32,7 @@ reference:
       - xportr_order
       - xportr_df_label
       - xportr_metadata
+      - xportr
 
   - title: xportr helper functions
     desc: Utility functions called within core xportr functions