Closes #100 add labels, save specs as JSON, improve readme

DESCRIPTION

@@ -44,7 +44,8 @@ Suggests:
     roxygen2,
     spelling,
     testthat (>= 3.0.0),
-    usethis
+    usethis,
+    jsonlite
 Config/testthat/edition: 3
 Encoding: UTF-8
 Language: en-US

NEWS.md

@@ -10,6 +10,8 @@
 
 - Improved reference page so that dataset labels are displayed under each dataset name. (#103)
 
+- Added labels to variables within datasets that were missing them. (#100)
+
  <details>
 <summary>Developer Notes</summary>
 

R/adae.R

@@ -97,12 +97,12 @@
 #'     \item{ EOSSTT }{End of Study Status}
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adcm.R

@@ -28,7 +28,7 @@
 #'     \item{ CMENDTC }{End Date/Time of Medication}
 #'     \item{ CMSTDY }{Study Day of Start of Medication}
 #'     \item{ CMENDY }{Study Day of End of Medication}
-#'     \item{ CMENRTPT }{undocumented field}
+#'     \item{ CMENRTPT }{End Relative to Reference Time Point}
 #'     \item{ TRTSDT }{Date of First Exposure to Treatment}
 #'     \item{ TRTEDT }{Date of Last Exposure to Treatment}
 #'     \item{ DTHDT }{Date of Death}
@@ -87,12 +87,12 @@
 #'     \item{ EOSSTT }{End of Study Status}
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adeg.R

@@ -100,12 +100,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adex.R

@@ -84,12 +84,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adface_vaccine.R

@@ -67,7 +67,7 @@
 #'     \item{ EVENTDFL }{Day Event Value Flag}
 #'     \item{ ANL01FL }{Analysis Flag 01}
 #'     \item{ ANL02FL }{Analysis Flag 02}
-#'     \item{ ANL03FL }{undocumented field}
+#'     \item{ ANL03FL }{Analysis Flag 03}
 #'   }
 #'
 #' @source Generated from admiralvaccine package (template ad_adface.R).

R/adlb.R

@@ -107,12 +107,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/admh.R

@@ -106,12 +106,12 @@
 #'     \item{ EOSSTT }{End of Study Status}
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adoe_ophtha.R

@@ -94,12 +94,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adpc.R

@@ -119,12 +119,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adpp.R

@@ -71,12 +71,12 @@
 #'     \item{ EOSSTT }{End of Study Status}
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/adsl.R

@@ -49,9 +49,9 @@
 #'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/advfq_ophtha.R

@@ -81,12 +81,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

R/advs.R

@@ -97,12 +97,12 @@
 #'     \item{ FRVDT }{Final Retrievel Visit Date}
 #'     \item{ RANDDT }{Date of Randomization}
 #'     \item{ DTHDT }{Date of Death}
-#'     \item{ DTHDTF }{undocumented field}
+#'     \item{ DTHDTF }{Date of Death Imputation Flag}
 #'     \item{ DTHADY }{Relative Day of Death}
 #'     \item{ LDDTHELD }{Elapsed Days from Last Dose to Death}
-#'     \item{ DTHCAUS }{undocumented field}
-#'     \item{ DTHDOM }{undocumented field}
-#'     \item{ DTHCGR1 }{undocumented field}
+#'     \item{ DTHCAUS }{Cause of Death}
+#'     \item{ DTHDOM }{Domain for Date of Death Collection}
+#'     \item{ DTHCGR1 }{Cause of Death Reason 1}
 #'     \item{ LSTALVDT }{Date Last Known Alive}
 #'     \item{ SAFFL }{Safety Population Flag}
 #'     \item{ RACEGR1 }{Pooled Race Group 1}

README.md

@@ -44,14 +44,18 @@ The workflow consists of two main steps:
 
 Firstly, the user reviews `inst/extdata/adams-specs.xlsx` and ensures its contents is up-to-date. If a new template has been added to an existing package, or if a new extension package has been created whose ADaM templates they wish to execute in `{pharmaverseadam}`, then the user should update `adams-specs.xlsx` with specifications for the new dataset(s). Note that any missing metadata fields will be set by default to "No label/description/source available."
 
-### 2. Execute `create_adams_data`
+### 2. Execute `create_adams_data.R`
 
 Secondly, the user runs `data-raw/create_adams_data.R`. This script handles the installation of each package, the execution of the templates, the saving of the ADaM datasets and the creation of the documentation pages.
 
 #### Script steps
 
-1. **Installs Required Packages**  
-   Installs the following packages:
+1. **Save specs as JSON**  
+   The script saves the specs stored in `inst/extdata/adams-specs.xlsx` as a JSON file located here: `inst/extdata/adams-specs.json`. 
+   This is so that the specs themselves, as well as any diffs across commits, are easily viewable on Github and R Studio.
+
+2. **Installs Required Packages**  
+   The script installs the following packages:
    - `{admiral}`
    - `{admiralonco}`
    - `{admiralophtha}`
@@ -60,11 +64,11 @@ Secondly, the user runs `data-raw/create_adams_data.R`. This script handles the
    - `{pharmaversesdtm}`
    By default, the latest development versions of each package will be used, but the user can also select a different version instead (e.g. a released version) with which to refresh `{pharmaverseadam}`. The user may also deselect some packages whose templates they do not wish to run. If a new extension package has been created, this should be added to the script in each relevant section (see the script itself for more details).
 
-2. **Executes Templates from Each Package**  
+3. **Executes Templates from Each Package**  
 
-3. **Processes and Saves Datasets into {pharmaverseadam}**  
+4. **Processes and Saves Datasets into {pharmaverseadam}**  
 
-4. **Generates Dataset Documentation**  
+5. **Generates Dataset Documentation**  
    For every dataset, a matching `.R` file is created in the `R/` folder containing:
    - Dataset name and title,
    - Variable-level documentation (names and labels),

data-raw/create_adams_data.R

@@ -1,4 +1,16 @@
-# ensure every packages are installed
+# Save specs as JSON file for traceability of changes ----
+
+library(readxl)
+library(jsonlite)
+
+# Read the .xlsx file
+specs_xlsx <- readxl::read_excel("inst/extdata/adams-specs.xlsx")
+
+specs_json <- toJSON(specs_xlsx, pretty = TRUE)
+
+write(json_data, "inst/extdata/adams-specs.json")
+
+# Ensure all packages are installed ----
 library(stringr)
 update_pkg <- TRUE
 ignore_templates <- list(
@@ -29,6 +41,7 @@ get_attr <- function(data, col_name) {
   return(att)
 }
 
+# Create documentation ----
 write_doc <- function(data, dataset_name, dataset_label, pkg, template_name) {
   # create documentation for the current dataset
   # TODO: use metatools/metacore for doc  ?
@@ -138,8 +151,8 @@ if (update_pkg) {
 # dict to match admiral xlsx specs suffixes
 suffixes_dict <- list("_ophtha" = "_P", "_onco" = "_O", "_vaccine" = "_V", "_peds" = "_E")
 mc <- metacore::spec_to_metacore("inst/extdata/adams-specs.xlsx",
-                                 where_sep_sheet = FALSE,
-                                 quiet = TRUE
+  where_sep_sheet = FALSE,
+  quiet = TRUE
 )
 
 packages_list <- c("admiral", "admiralonco", "admiralophtha", "admiralvaccine", "admiralpeds")
@@ -151,12 +164,12 @@ for (pkg in packages_list) {
   if (update_pkg) {
     # TODO: replace by main once done
     remotes::install_github(sprintf("pharmaverse/%s", pkg),
-                            ref = "main", auth_token = if (github_pat == "") {
-                              NULL
-                            } else {
-                              github_pat
-                            },
-                            upgrade = "always", force = TRUE
+      ref = "main", auth_token = if (github_pat == "") {
+        NULL
+      } else {
+        github_pat
+      },
+      upgrade = "always", force = TRUE
     )
   }
   # get templates scripts
@@ -187,5 +200,5 @@ for (res in all_results) {
   }
 }
 
-# Generate the documentation
+# Generate the documentation ----
 roxygen2::roxygenize(".", roclets = c("rd", "collate", "namespace"))

inst/WORDLIST

@@ -207,3 +207,7 @@ CRANstatus
 tibble
 Changelog
 README
+viewable
+diffs
+JSON
+Github