Detailed vignette of how to use xportr

[elimillera]

Layout of Vignette

Overview

• In-depth discussion of submission process
• Break down the specification file and how they fit into xportr functions
  • Possible opportunity to use Mermiad or some other diagramming software
• Discuss Assumptions of xportr functions
  • Example: assumptions around length in spec and in function
  • Discuss use of xportr options to address different specification file styles
  • Discuss use of xportr_set() to reduce repetitive tasks (Feature Request: ?global? object for spec file  #44)
  • Discuss metacore versus dataframe spec option

ADaMs and Specs

• Discuss Pilot 3 Submission as source of data
• Where is data located for users to experiment with.
• Read in data and briefly highlight features.
• Read in specs and briefly highlight features

Application of xportr functions to one ADaM dataset (TBD)

• Spec should be altered at times to help highlight messaging/warnings built it to xportr

Application of xportr functions to all ADaM datasets (TBD)

• Section will be repeat of above so should just be hand-wavey
• No highlighting of message/warnings
• Goal is to show bulk application of functions to multiple datasets

Validation Software

• Showcase readouts from community P21 Tool

Outstanding Questions

• Where does the specs and datasets live? Decision: Fine in example_data_sepc
• It would be nice to get some outside reviews done before we submit to CRAN.

Definition of Done

A detailed and user-reviewed vignette available within the package and on the site

[elimillera]

End to end examples can be found here for a starting point: https://github.com/pharmaverse/end_to_end_examples

[cpiraux]

The layout of the detailed vignette looks good to me.

ADaMs and Specs

• Discuss Pilot 3 Submission as source of data

I have a comment about the specification file from Pilot 3 Submission. Specifically, for the SDTM --DTC variables, the specifications do not conform to the define.xml specification. The data type should be listed as 'Date' and the length should be indicated as missing.

I think it would be nice to have data type and length for --DTC variables that follow define.xml specification. To see how xportr handles these variables in the vignette.

Specs Pilot 3 Submission:

defineV21-ADaM example:

[elimillera]

Also include how options work, defaults, and how to change. Possible second vignette.

https://github.com/pharmaverse/tidytlg/blob/e79d08aeb841a475d393a68dc8ed10c6a6139671/R/tidytlg.R#L8

[averissimo]

Tip: you can probably use the function system.file to replace here dependency.

system.file("example_data_specs", "TDF_ADaM_Pilot3.xlsx", package = "xportr")

I feel that it also helps the readability/maintenance of vignettes to have a new line per new phrase (it will still write all in a single paragraph).

However, this is more of a style preference, than a "real" improvement, I just noticed the line with 772 characters ehehehe

The Study Data Standardization Plan (SDSP) establishes and documents a plan for describing the data standardization approach for clinical and nonclinical studies within a development program.
The SDSP also assists the FDA in identifying potential data standardization issues early in the development program.
We hope the brevity of this section does not belie the huge importance of this document.
Please see [Study Data Standardisation Plan (SDSP) Package](https://advance.phuse.global/display/WEL/Study+Data+Standardisation+Plan+%28SDSP%29+Package) maintained by the [PHUSE working group](https://advance.phuse.global/display/WEL/Welcome+to+the+PHUSE+Advance+Hub).
However, we want to focus more on the actual data and how `{xportr}` can play a role in the submission.

instead of

The Study Data Standardization Plan (SDSP) establishes and documents a plan for describing the data standardization approach for clinical and nonclinical studies within a development program. The SDSP also assists the FDA in identifying potential data standardization issues early in the development program. We hope the brevity of this section does not belie the huge importance of this document. Please see [Study Data Standardisation Plan (SDSP) Package](https://advance.phuse.global/display/WEL/Study+Data+Standardisation+Plan+%28SDSP%29+Package) maintained by the [PHUSE working group](https://advance.phuse.global/display/WEL/Welcome+to+the+PHUSE+Advance+Hub).  However, we want to focus more on the actual data and how `{xportr}` can play a role in the submission.

[elimillera]

Storing bulk processing here for now for inclusion in a future vignette

Using {xportr} to bulk process multiple datasets.

library(dplyr)
library(xportr)
library(stringr)

spec_loc <- here::here("example_data_specs", "TDF_ADaM_Pilot3.xlsx")
data_loc <- str_remove(spec_loc, "/TDF_ADaM_Pilot3.xlsx")

var_spec <- readxl::read_xlsx(spec_loc, sheet = "Variables")

path_of_xpt_files <- list.files(data_loc, pattern = ".xpt", full.names = TRUE)

Read in all 5 xpts files

filepaths <- path_of_xpt_files %>%
  set_names(nm = basename(.) %>%
    tools::file_path_sans_ext())

files <- purrr::map(filepaths, read_xpt)

purrr::pmap(.l = list(.x = names(files), .y = files), .f = ~ assign(.x, .y, envir = .GlobalEnv))

Apply specification file to all 5 xpts files

xportr_apply_all <- function(spec_file, domain_name, data, path_name, label) {
  adsl %>%
    xportr_metadata({{ spec_file }}, {{ domain_name }}) %>%
    xportr_type() %>%
    xportr_length() %>%
    xportr_label() %>%
    xportr_order() %>%
    xportr_format() %>%
    xportr_write(.df = {{ data }}, path = {{ path }}, label = {{ label }})
}

xportr_apply_all(var_spec, "ADSL", adsl,
  path = "/cloud/project/adsl.xpt", label = "Subject-Level Analysis Dataset"
)

var_spec_view <- var_spec %>% filter(Dataset == "ADSL")

DT::datatable(var_spec_view, options = list(
  autoWidth = FALSE, scrollX = TRUE, pageLength = 5,
  lengthMenu = c(5, 10, 15, 20)
))