Skip to contents

Ingest ARS (Analysis Results Standard) metadata, produce ARD (Analysis Results Dataset) code for each output

Source: R/readARS.R
readARS.Rd

Ingest ARS (Analysis Results Standard) metadata, and meta-programme R scripts that could be run as-is to produce Analysis Results Datasets when ingesting ADaM datasets

Usage

readARS(
  ARS_path,
  output_path = tempdir(),
  adam_path = tempdir(),
  spec_output = "",
  output_format = "none",
  code_style = "wrapped",
  column_labels = NULL
)

Arguments

ARS_path

A file containing ARS metadata for a reporting event

output_path

Path to store .R ARD scripts

adam_path

Path to folder containing ADaM datasets, to be run in ARD program. Datasets may be supplied as CSV (`.csv`), SAS transport (`.xpt`) or CDISC Dataset-JSON (`.json`) files. siera chooses the reader for each dataset from the file extension found in this folder — `.csv` files are read with readr::read_csv(), `.xpt` files with haven::read_xpt() and `.json` files with datasetjson::read_dataset_json() — so no extra argument is required. Reading `.xpt` datasets in the generated script requires the haven package, and `.json` datasets the datasetjson package. When several formats exist for the same dataset, precedence is `.csv`, then `.xpt`, then `.json`.

spec_output

The output ID for a specific output to be run from the metadata

output_format

Format for emitting the generated ARD. Must be exactly one of `"none"` or `"datasetjson"` (no partial matching). `"none"` (default) generates the ARD scripts only. `"datasetjson"` additionally appends code that writes each ARD as a CDISC Dataset-JSON file (`ARD_<OutputId>.json`) when the generated script is run. The Dataset-JSON export requires the optional datasetjson package to be installed in the environment that runs the generated script.

code_style

Style of the generated analysis code. Must be exactly one of `"wrapped"` or `"expanded"` (no partial matching). `"wrapped"` (default) ends each analysis with a call to siera::ars_stamp(), which links the analysis' ARD to the ARS metadata (`AnalysisId`, `MethodId`, `OutputId` and the `group[n]_*` identifiers), so every analysis reads as analysis set, data subset, method, identifier linking. `"expanded"` writes all of that linking out as plain dplyr code in the script, so the generated script does not call siera functions for the linking step. Both styles produce an identical ARD.

column_labels

Optional named character vector of Dataset-JSON variable labels, e.g. `c(AGEGR1 = "Pooled Age Group 1", TRT01A = "Actual Treatment")`. Names are ARD column names and values are the labels to write. Overrides take precedence over siera's built-in label dictionary, so they can also reword built-in labels. Because the ARD's columns are only known once the generated script runs, a name that matches no ARD column triggers a warning at script runtime (likely a typo) rather than an error. Only used when `output_format = "datasetjson"`; otherwise it is ignored with a warning.

Value

R programmes generating ARDs - one for each output (or analysis from an output) specified in the ARS metadata

Examples

# path to file containing ARS metadata

ARS_path <- ARS_example("Common_Safety_Displays_cards.json")

# output path for R programs
output_dir <- tempdir()

# folder containing ADaM datasets
adam_folder <- tempdir()

# run function, write to temp directory
readARS(ARS_path, output_dir, adam_folder)