diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index c2022b66..2a20386e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -52,6 +52,7 @@ jobs: riskmetric tidyCDISC mirai + sdtm.oak - name: Install tinytex run: quarto install tool tinytex diff --git a/inst/WORDLIST.txt b/inst/WORDLIST.txt index f668b780..52ddf83b 100644 --- a/inst/WORDLIST.txt +++ b/inst/WORDLIST.txt @@ -1160,3 +1160,51 @@ mypackage parmsam shinyl zzz +BEFORE’ +CDASH +CMSTRTPT +CMTRT +CRF +DM +eCRF +EDC +eDT +FLUIDS’ +hardcode +hardcoded +MDPRIOR +MHOCCUR +MHPRESP +MHTERM +NonCRF +oak +Pressure +RELREC +Roadmap +SV +TEMP +VSMETHOD +VSPOS +VSTEST +VSLAT +tgt +Y +oakgarden +stringsAsFactors +Rammprasad +mmHg +MDRAW +kable +Ganapathy +FASCAT +DOSU +dat +CORTISPORIN +CMSTTPT +CMMODIFY +CMDOSU +CMDOSE +clst +br +Varialble +sdtmoak diff --git a/posts/zzz_DO_NOT_EDIT_introducing.../appendix.R b/posts/zzz_DO_NOT_EDIT_introducing.../appendix.R new file mode 100644 index 00000000..c69926b0 --- /dev/null +++ b/posts/zzz_DO_NOT_EDIT_introducing.../appendix.R @@ -0,0 +1,73 @@ +suppressMessages(library(dplyr)) +# markdown helpers -------------------------------------------------------- + +markdown_appendix <- function(name, content) { + paste(paste("##", name, "{.appendix}"), " ", content, sep = "\n") +} +markdown_link <- function(text, path) { + paste0("[", text, "](", path, ")") +} + + + +# worker functions -------------------------------------------------------- + +insert_source <- function(repo_spec, name, + collection = "posts", + branch = "main", + host = "https://github.com", + text = "Source", + file_name) { + path <- paste( + host, + repo_spec, + "tree", + branch, + collection, + name, + file_name, + sep = "/" + ) + return(markdown_link(text, path)) +} + +insert_timestamp <- function(tzone = Sys.timezone()) { + time <- lubridate::now(tzone = tzone) + stamp <- as.character(time, tz = tzone, usetz = TRUE) + return(stamp) +} + +insert_lockfile <- function(repo_spec, name, + collection = "posts", + branch = "main", + host = "https://github.com", + text = "Session info") { + path <- path <- "https://pharmaverse.github.io/blog/session_info.html" + + return(markdown_link(text, path)) +} + + + +# top level function ------------------------------------------------------ + +insert_appendix <- function(repo_spec, name, collection = "posts", file_name) { + appendices <- paste( + markdown_appendix( + name = "Last updated", + content = insert_timestamp() + ), + " ", + markdown_appendix( + name = "Details", + content = paste( + insert_source(repo_spec, name, collection, file_name = file_name), + # get renv information, + insert_lockfile(repo_spec, name, collection), + sep = ", " + ) + ), + sep = "\n" + ) + knitr::asis_output(appendices) +} diff --git a/posts/zzz_DO_NOT_EDIT_introducing.../introducing_sdtm.oak.qmd b/posts/zzz_DO_NOT_EDIT_introducing.../introducing_sdtm.oak.qmd new file mode 100644 index 00000000..b2d7b060 --- /dev/null +++ b/posts/zzz_DO_NOT_EDIT_introducing.../introducing_sdtm.oak.qmd @@ -0,0 +1,274 @@ +--- +title: "Introducing sdtm.oak" +author: + - name: Rammprasad Ganapathy +description: "An EDC & Data Standards agnostic solution that enables the pharmaceutical programming community to develop SDTM datasets in R" +# Note that the date below will be auto-updated when the post is merged. +date: "2024-10-19" +# Please do not use any non-default categories. +# You can find the default categories in the repository README.md +categories: [SDTM] +# Feel free to change the image +image: "sdtmoak.png" +--- + + + +```{r setup, include=FALSE} +library(link) +long_slug <- "zzz_DO_NOT_EDIT_introducing..." +# renv::use(lockfile = "renv.lock") +link::auto(keep_pkg_prefix = FALSE) +``` + + + +{sdtm.oak} v0.1 is now available on [CRAN](https://cran.r-project.org/web/packages/sdtm.oak/index.html). +In this blog post, we will introduce the package, key concepts, and examples. {sdtm.oak} is developed in collaboration with volunteers from several companies, including Roche, Pfizer, GSK, Pattern Institute, Transition Technologies Science, and Atorus Research. {sdtm.oak} is also sponsored by [CDISC COSA](https://www.cdisc.org/cosa) with a vision of being part of [CDISC 360](https://www.cdisc.org/cdisc-360) to address end-to-end standards development and implementation. + +# Filling the Gap + +{sdtm.oak} package addresses a critical gap in the pharmaverse suite by enabling study programmers to create SDTM datasets in R, complementing the existing capabilities for ADaM, TLGs, eSubmission, etc. + +Let's explore the challenges with SDTM programming. Although SDTM is simpler with less complex derivations compared to ADaM, it presents unique challenges. Unlike ADaM, which uses SDTM datasets as its source with a well-defined structure, SDTM relies on raw datasets as input. +These raw datasets can vary widely in structure, depending on the data collection and EDC (Electronic Data Capture) system used. Even the same eCRF (electronic Case Report Form), when designed in different EDC systems, can produce raw datasets with different structures. + +Another challenge is the variability in data collection standards. Although CDISC has established CDASH data collection standards, many pharmaceutical companies have their own standards, which can differ significantly from CDASH. Additionally, since CDASH is not mandated by the FDA, sponsors can choose the data collection standards that best fit their needs. + +There are hundreds of EDC systems available in the marketplace, and the data collection standards vary significantly. Creating a single open-source package to work with all sorts of raw data formats and data collection standards seemed impossible. But here's the good news: not anymore! The {sdtm.oak} team has a solution to address this challenge. + +{sdtm.oak} is designed to be highly versatile, accommodating varying raw data structures from different EDC systems and external vendors. Moreover, {sdtm.oak} is data standards agnostic, meaning it supports both CDISC-defined data collection standards (CDASH) and various proprietary data collection standards defined by pharmaceutical companies. The reusable algorithms concept in {sdtm.oak} provides a framework for modular programming, making it a valuable addition to the pharmaverse ecosystem. + +# EDC & Data standards agnostic + +We adopted the following innovative approach to make {sdtm.oak} adaptable to various EDC systems and data collection standards: + +- SDTM mappings are categorized as algorithms and developed as R functions. +- Used datasets and variables are specified as arguments to function calls. + +# Algorithms + +The SDTM mappings that transform the collected source data (eDT: External Data Transfer) into the target SDTM data model are grouped into algorithms. +These mapping algorithms form the backbone of {sdtm.oak}. + +Key Points: +* Algorithms can be re-used across multiple SDTM domains. +* Programming language agnostic: This concept does not rely on a specific programming language for implementation. + +The {sdtm.oak} package includes R functions to handle these algorithms. + +Some of the basic algorithms are below, also explaining how these algorithms can be used across multiple domains. + +```{r echo = FALSE, results = "asis"} +library(knitr) +algorithms <- data.frame( + `Algorithm Name` = c( + "assign_no_ct", + "assign_ct", + "assign_datetime", + "hardcode_ct", + "hardcode_no_ct", + "condition_add" + ), + `Description` = c( + paste( + "One-to-one mapping between the raw source and a target", + "SDTM variable that has no controlled terminology restrictions.", + "Just a simple assignment", + "statement." + ), + paste( + "One-to-one mapping between the raw source and a target ", + "SDTM variable that is subject to controlled terminology restrictions.", + "A simple assign statement and applying controlled terminology.", + "This will be used only if the SDTM variable has an associated", + "controlled terminology." + ), + paste( + "One-to-one mapping between the raw source and a target that involves ", + "mapping a Date or time or datetime component. This mapping algorithm", + "also takes care of handling unknown dates and converting them into.", + "ISO8601 format." + ), + paste( + "Mapping a hardcoded value to a target SDTM variable that is subject to terminology restrictions.", + "This will be used only if the SDTM variable has an associated", + "controlled terminology." + ), + paste( + "Mapping a hardcoded value to a target SDTM variable that has no terminology restrictions." + ), + paste( + "Algorithm that is used to filter the source data and/or target domain", + "based on a condition. The mapping will be applied only if the condition is met.", + " This algorithm has to be used in conjunction with other algorithms, that is if the", + " condition is met perform the mapping using algorithms like assign_ct,", + "assign_no_ct, hardcode_ct, hardcode_no_ct, assign_datetime." + ) + ), + `Example` = c( + paste( + "MH.MHTERM
", + "AE.AETERM" + ), + paste("VS.VSPOS
", "VS.VSLAT"), + paste("MH.MHSTDTC
", "AE.AEENDTC"), + paste( + "MH.MHPRESP = 'Y'
", + "
VS.VSTEST = 'Systolic Blood Pressure'
", + "
VS.VSORRESU = 'mmHg'
" + ), + paste( + "FA.FASCAT = 'COVID-19 PROBABLE CASE'
", + "
CM.CMTRT = 'FLUIDS'" + ), + paste( + "If If MDPRIOR == 1 then CM.CMSTRTPT = 'BEFORE'.
", + "
VS.VSMETHOD when VSTESTCD = 'TEMP'
", + "
If collected value in raw variable DOS is numeric then CM.CMDOSE
", + "
If collected value in raw variable MOD is different to CMTRT then map to CM.CMMODIFY" + ) + ), stringsAsFactors = TRUE +) +knitr::kable(algorithms) +``` + +Here is an example of reusing an algorithm across multiple domains, +variables, and also to a non-standard mapping + +![](reusable_algorithms.jpg){width="600"} + +# Functions and Arguments + +All the aforementioned algorithms are implemented as R functions, each accepting the raw dataset, raw variable, target SDTM dataset, and target SDTM variable as parameters. + +```{r, message = FALSE} +library(sdtm.oak) +library(dplyr) + +cm_raw <- tibble::tribble( + ~oak_id, ~raw_source, ~patient_number, ~MDRAW, ~DOSU, ~MDPRIOR, + 1L, "cm_raw", 375L, "BABY ASPIRIN", "mg", 1L, + 2L, "cm_raw", 375L, "CORTISPORIN", "Gram", 0L, + 3L, "cm_raw", 376L, "ASPIRIN", NA, 0L +) + +study_ct <- tibble::tribble( + ~codelist_code, ~term_code, ~term_value, ~collected_value, ~term_preferred_term, ~term_synonyms, + "C71620", "C25613", "%", "%", "Percentage", "Percentage", + "C71620", "C28253", "mg", "mg", "Milligram", "Milligram", + "C71620", "C48155", "g", "g", "Gram", "Gram" +) + +cm <- + # Derive topic variable + # SDTM Mapping - Map the collected value to CM. CMTRT + assign_no_ct( + raw_dat = cm_raw, + raw_var = "MDRAW", + tgt_var = "CMTRT" + ) %>% + # Derive qualifier CMDOSU + # SDTM Mapping - Map the collected value to CM. CMDOSU + assign_ct( + raw_dat = cm_raw, + raw_var = "DOSU", + tgt_var = "CMDOSU", + ct_spec = study_ct, + ct_clst = "C71620", + id_vars = oak_id_vars() + ) %>% + # Derive qualifier CMSTTPT + # SDTM mapping - If MDPRIOR == 1 then CM.CMSTTPT = 'SCREENING' + hardcode_no_ct( + raw_dat = condition_add(cm_raw, MDPRIOR == "1"), + raw_var = "MDPRIOR", + tgt_var = "CMSTTPT", + tgt_val = "SCREENING", + id_vars = oak_id_vars() + ) +``` + +As you can see in this function call, the raw dataset and variable names are passed as arguments. As long as the raw dataset and variable are present in the global environment, the function will execute the algorithm's logic and create the target SDTM variable. + +{sdtm.oak} is designed to handle any type of raw input format. It is not tied to any specific data collection standards, making it both EDC-agnostic and data standards-agnostic. + +# Why not use dplyr? + +As you can see from the definition of the algorithms, all of them are a form of {dplyr::mutate()} statement. +However, these functions provide a way to pass dataset and variable names as arguments and the ability to merge with the previous step by id variables. +This enables users to build the code in a modular and simplistic fashion, mapping one SDTM variable at a time, connected by pipes. + +The SDTM mappings can also be used together in a single step, such as applying a filter condition, executing a mapping, and merging the outcome with the previous step. +When there is a need to apply controlled terminology, the algorithms perform additional checks, such as verifying the presence of the value in the study's controlled terminology specification, which is passed as an argument to the function call. +If the collected value is present, it applies the standard submission value. + +While all these functionalities can be achieved with {dplyr}, the functions provided by {sdtm.oak} simplify the process and enhance efficiency. By leveraging metadata and controlled terminology, we further minimize errors and offer a modular approach to building SDTM datasets. + +# `oak_id_vars` + +The `oak_id_vars` is a crucial link between the raw datasets and the mapped SDTM domain. +As the user derives each SDTM variable, it is merged with the corresponding topic variable using `oak_id_vars`. +In {sdtm.oak}, the variables `oak_id`, `raw_source`, and `patient_number` are considered `oak_id_vars`. +These three variables must be added to all raw datasets. Users can also extend this with any additional id vars.`oak_id_vars` can be added to the raw datasets using the function {sdtm.oak::generate_oak_id_vars()}. + + +```{r echo = FALSE, results = "asis"} +library(knitr) +oak_id_vars <- data.frame( + `Varialble` = c( + "oak_id", + "raw_source", + "patient_number" + ), + `Type` = c( + "Numeric", + "Character", + "Numeric" + ), + `Description` = c( + paste( + "The row number of the raw dataframe" + ), + paste("The raw dataset (eCRF) name or eDT dataset name"), + paste("Subject number in eCRF or eDT data source") + ), stringsAsFactors = TRUE +) +knitr::kable(oak_id_vars) +``` + +# In this Release + +The v0.1.0 release of {sdtm.oak} users can create the majority of the SDTM domains. +Domains that are NOT in scope for the v0.1.0 release are DM (Demographics), Trial Design Domains, SV (Subject Visits), SE (Subject Elements), RELREC (Related Records), Associated Person domains, creation of SUPP domain, and EPOCH variable across all domains. + +# Roadmap + +We are planning to develop the below features in the subsequent releases. + +- Functions required to derive reference date variables in the DM domain.\ +- Metadata driven automation based on the standardized SDTM specification.\ +- Functions required to program the EPOCH variable.\ +- Functions to derive standard units and results based on metadata.\ +- Functions required to create SUPP domains.\ +- Making the algorithms part of the standard CDISC eCRF portal enabling automation of CDISC standard eCRFs. + +# Get Involved +Please try the package and provide us with your feedback, or get involved in the development of new features. We can be reached through any of the following means: + +Slack: [https://oakgarden.slack.com](https://oakgarden.slack.com)\ +GitHub: [https://github.com/pharmaverse/sdtm.oak](https://github.com/pharmaverse/sdtm.oak)\ +CDISC Wiki: [https://wiki.cdisc.org/display/oakgarden](https://wiki.cdisc.org/display/oakgarden) + + + + +```{r, echo=FALSE} +source("appendix.R") +insert_appendix( + repo_spec = "pharmaverse/blog", + name = long_slug, + # file_name should be the name of your file + file_name = list.files() %>% stringr::str_subset(".qmd") %>% first() +) +``` diff --git a/posts/zzz_DO_NOT_EDIT_introducing.../reusable_algorithms.jpg b/posts/zzz_DO_NOT_EDIT_introducing.../reusable_algorithms.jpg new file mode 100644 index 00000000..5b5bd027 Binary files /dev/null and b/posts/zzz_DO_NOT_EDIT_introducing.../reusable_algorithms.jpg differ diff --git a/posts/zzz_DO_NOT_EDIT_introducing.../sdtmoak.png b/posts/zzz_DO_NOT_EDIT_introducing.../sdtmoak.png new file mode 100644 index 00000000..fde50ffc Binary files /dev/null and b/posts/zzz_DO_NOT_EDIT_introducing.../sdtmoak.png differ