atorus-research · bms63 · Jun 15, 2023 · May 1, 2023 · May 1, 2023 · May 9, 2023
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -22,3 +22,5 @@
 ^advs\.xpt$
 ^advs_Define-Excel-Spec_match_admiral\.xlsx
 ^cran-comments\.md$
+^example_data_specs$
+^deepdive.Rmd$
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -82,3 +82,5 @@ Suggests:
     metacore
 Config/testthat/edition: 3
 VignetteBuilder: knitr
+Depends: 
+    R (>= 2.10)
diff --git a/NEWS.md b/NEWS.md
@@ -2,18 +2,21 @@
 
 ## New Features and Bug Fixes
 
-* Fixed an issue where `xportr_type` would overwrite column labels, widths, and "sas.formats"
-* Fixed messaging of `xportr_order`to give better visability of the number of variables being reordered.
-* Add new argument to `xportr_write` to allow users to specify how xpt validation checks are handled.
+* Fixed an issue where `xportr_type()` would overwrite column labels, widths, and "sas.formats"
+* Fixed messaging of `xportr_order()`to give better visability of the number of variables being reordered.
+* Add new argument to `xportr_write()` to allow users to specify how xpt validation checks are handled.
 * Fixed bug where character_types were case sensitive. They are now case insensitive.
-* Updated `xportr_type` to make type coercion more explicit.
+* Updated `xportr_type()` to make type coercion more explicit. 
 * Added function `xportr_metadata()` to explicitly set metadata at the start of a pipeline (#44)
 
 ## Documentation
 
 * Moved `{pkgdown}` site to bootswatch. Enabled search and linked slack icon (#122).
+* Additional vignette showcasing functions and quality of life utilities for processing `xpts` created (#84)
 
-## Deprecation and Breaking Changes
+
+## Deprecation
+and Breaking Changes
 
 * The `metacore` argument has been renamed to `metadata` in the following six xportr functions: `xportr_df_label()`, `xportr_format()`, `xportr_label()`, `xportr_length()`, `xportr_order()`, and `xportr_type()`. Please update your code to use the new `metadata` argument in place of `metacore`.
 # xportr 0.2.0

diff --git a/R/data.R b/R/data.R
@@ -0,0 +1,84 @@
+#' Analysis Dataset Subject Level
+#'
+#' An example dataset containing subject level data
+#'
+#' @format ## `adsl`
+#' A data frame with 254 rows and 48 columns:
+#' \describe{
+#'   \item{STUDYID}{Study Identifier}
+#'   \item{USUBJID}{Unique Subject Identifier}
+#'   \item{SUBJID}{Subject Identifier for the Study}
+#'   \item{SITEID}{Study Site Identifier}
+#'   \item{SITEGR1}{Pooled Site Group 1}
+#'   \item{ARM}{Description of Planned Arm}
+#'   \item{TRT01P}{Planned Treatment for Period 01}
+#'   \item{TRT01PN}{Planned Treatment for Period 01 (N)}
+#'   \item{TRT01A}{Actual Treatment for Period 01}
+#'   \item{TRT01AN}{Actual Treatment for Period 01 (N)}
+#'   \item{TRTSDT}{Date of First Exposure to Treatment}
+#'   \item{TRTEDT}{Date of Last Exposure to Treatment}
+#'   \item{TRTDUR}{Duration of Treatment (days)}
+#'   \item{AVGDD}{Avg Daily Dose (as planned)}
+#'   \item{CUMDOSE}{Cumulative Dose (as planned)}
+#'   \item{AGE}{Age}
+#'   \item{AGEGR1}{Pooled Age Group 1}
+#'   \item{AGEGR1N}{Pooled Age Group 1 (N)}
+#'   \item{AGEU}{Age Units}
+#'   \item{RACE}{Race}
+#'   \item{RACEN}{Race (N)}
+#'   \item{SEX}{Sex}
+#'   \item{ETHNIC}{Ethnicity}
+#'   \item{SAFFL}{Safety Population Flag}
+#'   \item{ITTFL}{Intent-To-Treat Population Flag}
+#'   \item{EFFFL}{Efficacy Population Flag}
+#'   \item{COMP8FL}{Completers of Week 8 Population Flag}
+#'   \item{COMP16FL}{Completers of Week 16 Population Flag}
+#'   \item{COMP24FL}{Completers of Week 24 Population Flag}
+#'   \item{DISCONFL}{Did the Subject Discontinue the Study}
+#'   \item{DSRAEFL}{Discontinued due to AE}
+#'   \item{DTHFL}{Subject Died}
+#'   \item{BMIBL}{Baseline BMI (kg/m^2)}
+#'   \item{BMIBLGR1}{Pooled Baseline BMI Group 1}
+#'   \item{HEIGHTBL}{Baseline Height (cm)}
+#'   \item{WEIGHTBL}{Baseline Weight (kg)}
+#'   \item{EDUCLVL}{Years of Education}
+#'   \item{DISONSDT}{Date of Onset of Disease}
+#'   \item{DURDIS}{Duration of Disease (Months)}
+#'   \item{DURDSGR1}{Pooled Disease Duration Group 1}
+#'   \item{VISIT1DT}{Date of Visit 1}
+#'   \item{RFSTDTC}{Subject Reference Start Date/Time}
+#'   \item{RFENDTC}{Subject Reference End Date/Time}
+#'   \item{VISNUMEN}{End of Trt Visit (Vis 12 or Early Term.)}
+#'   \item{RFENDT}{Date of Discontinuation/Completion}
+#'   \item{DCDECOD}{Standardized Disposition Term}
+#'   \item{DCREASCD}{Reason for Discontinuation}
+#'   \item{MMSETOT}{MMSE Total}
+#' }
+"adsl"
+
+#' Example Dataset Specification
+#'
+#' @format ## `var_spec`
+#' A data frame with 216 rows and 19 columns:
+#' \describe{
+#'   \item{Order}{Order of variable}
+#'   \item{Dataset}{Dataset}
+#'   \item{Variable}{Variable}
+#'   \item{Label}{Variable Label}
+#'   \item{Data Type}{Data Type}
+#'   \item{Length}{Variable Length}
+#'   \item{Significant Digits}{Significant Digits}
+#'   \item{Format}{Variable Format}
+#'   \item{Mandatory}{Mandatory Variable Flag}
+#'   \item{Assigned Value}{Variable Assigned Value}
+#'   \item{Codelist}{Variable Codelist}
+#'   \item{Common}{Common Variable Flag}
+#'   \item{Origin}{Variable Origin}
+#'   \item{Pages}{Pages}
+#'   \item{Method}{Variable Method}
+#'   \item{Predecessor}{Variable Predecessor}
+#'   \item{Role}{Variable Role}
+#'   \item{Comment}{Comment}
+#'   \item{Developer Notes}{Developer Notes}
+#' }
+"var_spec"
diff --git a/R/format.R b/R/format.R
@@ -28,12 +28,11 @@
 #' )
 #'
 #' adsl <- xportr_format(adsl, metadata)
-xportr_format <- function(
-    .df,
-    metadata = NULL,
-    domain = NULL,
-    verbose = getOption("xportr.length_verbose", "none"),
-    metacore = deprecated()) {
+xportr_format <- function(.df,
+                          metadata = NULL,
+                          domain = NULL,
+                          verbose = getOption("xportr.length_verbose", "none"),
+                          metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",

diff --git a/R/label.R b/R/label.R
@@ -30,12 +30,11 @@
 #' )
 #'
 #' adsl <- xportr_label(adsl, metadata)
-xportr_label <- function(
-    .df,
-    metadata = NULL,
-    domain = NULL,
-    verbose = getOption("xportr.length_verbose", "none"),
-    metacore = deprecated()) {
+xportr_label <- function(.df,
+                         metadata = NULL,
+                         domain = NULL,
+                         verbose = getOption("xportr.length_verbose", "none"),
+                         metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",

diff --git a/R/length.R b/R/length.R
@@ -28,12 +28,11 @@
 #' )
 #'
 #' adsl <- xportr_length(adsl, metadata)
-xportr_length <- function(
-    .df,
-    metadata = NULL,
-    domain = NULL,
-    verbose = getOption("xportr.length_verbose", "none"),
-    metacore = deprecated()) {
+xportr_length <- function(.df,
+                          metadata = NULL,
+                          domain = NULL,
+                          verbose = getOption("xportr.length_verbose", "none"),
+                          metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",

diff --git a/R/order.R b/R/order.R
@@ -25,12 +25,11 @@
 #' )
 #'
 #' adsl <- xportr_order(adsl, metadata)
-xportr_order <- function(
-    .df,
-    metadata = NULL,
-    domain = NULL,
-    verbose = getOption("xportr.length_verbose", "none"),
-    metacore = deprecated()) {
+xportr_order <- function(.df,
+                         metadata = NULL,
+                         domain = NULL,
+                         verbose = getOption("xportr.length_verbose", "none"),
+                         metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",

diff --git a/R/type.R b/R/type.R
@@ -32,12 +32,11 @@
 #' )
 #'
 #' df2 <- xportr_type(.df, metadata, "test")
-xportr_type <- function(
-    .df,
-    metadata = NULL,
-    domain = NULL,
-    verbose = getOption("xportr.length_verbose", "none"),
-    metacore = deprecated()) {
+xportr_type <- function(.df,
+                        metadata = NULL,
+                        domain = NULL,
+                        verbose = getOption("xportr.length_verbose", "none"),
+                        metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",
@@ -63,8 +62,11 @@ xportr_type <- function(
 
   ## Pull out correct metadata
   metadata <- metadata %||%
-    attr(.df, "_xportr.df_metadata_") %||%
+    attr(.df, "_xportr.df_metadata_")
+
+  if (is.null(metadata)) {
     rlang::abort("Metadata must be set with `metadata` or `xportr_metadata()`")
+  }
 
   if (inherits(metadata, "Metacore")) {
     metadata <- metadata$var_spec

diff --git a/README.Rmd b/README.Rmd
@@ -138,6 +138,19 @@ adsl %>%
   xportr_write("adsl.xpt", label = "Subject-Level Analysis Dataset")
 ```
 
+The `xportr_metadata()` function can reduce duplication by setting the variable specification and domain explicitly at the top of a pipeline.
+
+```{r, message=FALSE, eval=FALSE}
+adsl %>%
+  xportr_metadata(var_spec, "ADSL") %>%
+  xportr_type() %>%
+  xportr_length() %>%
+  xportr_label() %>%
+  xportr_order() %>%
+  xportr_format() %>%
+  xportr_write("adsl.xpt", label = "Subject-Level Analysis Dataset")
+```
+
 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.  

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -18,7 +18,6 @@ navbar:
       href: https://pharmaverse.slack.com/archives/C030EB2M4GM
       aria-label: slack
 
-
 reference:
 - title: The six core xportr functions
 - contents:
@@ -40,10 +39,10 @@ reference:
   - xportr_df_label
   - xportr_metadata
 
-- title: xportr
-  navbar: ~
-  contents:
-  - xportr
+- title: xportr example datasets and specification files
+- contents:
+  - adsl
+  - var_spec
 
 - title: internal
   contents:
@@ -53,4 +52,9 @@ reference:
   - minimal_table
 
 
+articles:
+- title: ~
+  navbar: ~
+  contents:
+    - deepdive
 
diff --git a/data/adsl.rda b/data/adsl.rda
diff --git a/data/var_spec.rda b/data/var_spec.rda
diff --git a/example_data_specs/TDF_ADaM - Pilot 3 Team updated.xlsx b/example_data_specs/TDF_ADaM - Pilot 3 Team updated.xlsx
diff --git a/example_data_specs/TDF_ADaM_Pilot3.xlsx b/example_data_specs/TDF_ADaM_Pilot3.xlsx
diff --git a/example_data_specs/adadas.xpt b/example_data_specs/adadas.xpt
diff --git a/example_data_specs/adae.xpt b/example_data_specs/adae.xpt
diff --git a/example_data_specs/adlbc.xpt b/example_data_specs/adlbc.xpt
diff --git a/example_data_specs/adtte.xpt b/example_data_specs/adtte.xpt
diff --git a/example_data_specs/readme.md b/example_data_specs/readme.md
@@ -0,0 +1 @@
+Data taken from Pilot 3 Submission Study: https://github.com/RConsortium/submissions-pilot3-adam
diff --git a/man/adsl.Rd b/man/adsl.Rd
diff --git a/man/figures/design_flow.png b/man/figures/design_flow.png
diff --git a/man/var_spec.Rd b/man/var_spec.Rd