Getting Started

library(siera)

We will use the following example to get started:

A modified CDISC Common Safety Displays ARS metadata file (JSON format, with example dynamic AnalysisMethodCodeTemplate R code handling operations, based on functions from the cards package)

In order to facilitate the example, siera includes several example files, which we use throughout the documentation. These include several ARS metadata files (JSON), as well as csv-format ADaMs which can be run with the R scripts produced by readARS function. Use the helper ARS_example() with no arguments to list them or call it with an example filename to get the path.

What you will produce

Before we start, it helps to see where we are headed. The end product of siera is an Analysis Results Dataset (ARD) - one result per row, in machine-readable form. Below is the ARD for a Demographics output, produced by running one of the example scripts that siera generates (more on running scripts further down). This is what we are building toward:

# Run a ready-made example script shipped with siera; the result is the object `ARD`
source(ARD_script_example("ARD_Out14-1-1.R"))
head(ARD)
#> # An ARD data frame: 6 × 22
#>   variable variable_level       stat_name   stat operationid AnalysisId MethodId
#>   <chr>    <chr>                <chr>     <name> <chr>       <chr>      <chr>   
#> 1 TRT01A   Placebo              n          86    Mth01_CatV… An01_05_S… Mth01_C…
#> 2 TRT01A   Xanomeline High Dose n          84    Mth01_CatV… An01_05_S… Mth01_C…
#> 3 TRT01A   Xanomeline Low Dose  n          84    Mth01_CatV… An01_05_S… Mth01_C…
#> 4 AGE      <NA>                 N          86    Mth02_Cont… An03_01_A… Mth02_C…
#> 5 AGE      <NA>                 mean       75.2  Mth02_Cont… An03_01_A… Mth02_C…
#> 6 AGE      <NA>                 sd          8.59 Mth02_Cont… An03_01_A… Mth02_C…
#> # ℹ 15 more variables: context <chr>, stat_label <chr>, warning <named list>,
#> #   error <named list>, OutputId <chr>, group1 <chr>, group1_level <chr>,
#> #   group1_groupingId <chr>, group1_groupId <chr>, group2_level <chr>,
#> #   group2_groupingId <chr>, group2_groupId <chr>, res <dbl>, pattern <chr>,
#> #   disp <chr>

Each row carries the statistic together with metadata (such as AnalysisId and the grouping columns) that traces it back to the ARS definition. The Concepts and conventions vignette explains these traceability columns in more detail.

# To see a list of example files:
ARS_example()
#>  [1] "ADAE.csv"                          "ADEXSUM.csv"                      
#>  [3] "ADSL.csv"                          "ADVS.csv"                         
#>  [5] "ADZSDER.csv"                       "cards_constructs.xlsx"            
#>  [7] "Common_Safety_Displays_cards.json" "Common_Safety_Displays_cards.xlsx"
#>  [9] "exampleARS_1.json"                 "exampleARS_1a.json"               
#> [11] "exampleARS_2.json"                 "exampleARS_2.xlsx"                
#> [13] "exampleARS_2a.xlsx"                "exampleARS_3.json"                
#> [15] "exampleARS_3.xlsx"                 "exampleARS_4.json"                
#> [17] "exampleARS_5_documentref.json"     "exampleARS_5.json"                
#> [19] "exampleARS_5.xlsx"                 "exampleARS_6.json"                
#> [21] "exampleARS_6.xlsx"                 "exampleARS_7.json"                
#> [23] "exampleARS_methods.json"           "R_siera_codes.xlsx"               
#> [25] "test_cards.json"

# A temporary path to a specific file:
ARS_example("exampleARS_1.json")
#> [1] "/tmp/RtmpowRPMZ/Rinsteda7b4e935b/siera/extdata/exampleARS_1.json"

Reading in ARS metadata - what to expect

The ARS metadata contains all ARS information for the Reporting Event. This information includes:

mainListOfContents (links outputs to their respective analyses)
otherListsOfContents (contains Output metadata)
dataSubsets (filters data for individual analyses)
analysisSets (filters data to get the Population Set for each analysis)
analysisGroupings (groups data according to analysis specifications)
analyses (contains linking information to all components required for calculation of results)
methods (describes operations to be performed on data to get results)

For a fuller treatment of what each of these sections is for, and how they flow through siera, see the Concepts and conventions vignette.

Example

The readARS function reads in a completed ARS metadata file in JSON format, and generates R scripts for each Output defined in the file. Below is an example of how this can be done using a ready-to-use ARS metadata file.

Still working from an Excel workbook? ARS metadata in .xlsx format is deprecated in siera and will no longer be read in a future release. For now readARS() still accepts a workbook, with a warning. Convert each workbook to JSON once with ars_xlsx_to_json() (an R-native equivalent of CDISC’s excel2ars.py), for example ars_xlsx_to_json("study.xlsx"), and keep the resulting .json file as your ARS metadata from then on. The converter is deprecated too and will be removed together with .xlsx input, so do the conversion while it is available.

# Path to the ARS metadata file (JSON):
ARS_path <- ARS_example("Common_Safety_Displays_cards.json")

# Path to a folder which will contain the Output meta-programmed R scripts (recommended to update
# to a more suitable local path)
output_folder <- tempdir()

# Path to the folder containing ADaM datasets, in CSV (.csv), SAS transport
# (.xpt) or CDISC Dataset-JSON (.json) format - siera detects the format from
# each file's extension, so the folder can hold any mix (.xpt requires the
# {haven} package, .json the {datasetjson} package). We will use the
# temporary directory tempdir() to make the code run in this vignette, but it's
# recommended to
# 1. download the ADaMs required (csv ADSL and ADAE available using e.g. ARS_example("ADSL.csv"))
# 2. store it in a folder (the directly downloaded location can be found using dirname(ARS_example("ADSL.csv")), for example.  Use this location, or manually store the ADaM somewhere else)
# 3. use the folder path instead of tempdir() below.
ADaM_folder <- tempdir()

# run the readARS function with these 3 parameters.  This creates R scripts
# (1 for each Output in output_folder)
readARS(ARS_path, output_folder, ADaM_folder)

You should now have 4 R scripts (named ARD_Out14-1-1.R, ARD_Out14-3-1-1.R, ARD_Out14-3-3-1a.R, and ARD_Out14-3-3-1b.R) in the folder specified as output_folder. You can execute any of these 4 R scripts as-is (assuming the ADaM required for this script is available in the ADaM_folder), and the result will be an ARD (one result per row format) for each of the scripts.

Each analysis in a generated script reads as four steps - analysis set, data subset, method, and a final call to siera::ars_stamp() that links the result to the ARS metadata (AnalysisId, MethodId, OutputId and the grouping identifiers). This means the siera package must be installed wherever you run the scripts. If you prefer scripts that spell out that last step in plain dplyr code instead, use readARS(..., code_style = "expanded"); both styles produce an identical ARD.

The generated scripts are portable across operating systems: any Windows-style backslashes in the ADaM path are normalised to forward slashes, so a script generated on Windows runs unchanged on macOS or Linux (and vice versa).

Running a auto-generated ARD script

The structure of the auto-generated ARD script is discussed in the ARD structure vignette. Examples of such auto-generated ARD scripts are included in the package, and can be accessed with the ARD_script_example function. Running one (as we did to produce the preview at the top of this vignette) looks like this:

# Step 1: open ARD_xxx.R file
# Step 2: Confirm the location of ADaM dataset(s) is correct in the code section "Load ADaM".
# For the sake of simplicity, the only update made to the ARD_Out14-1-1.R script was to point to the ADaM folder to ARS_example("ADSL.csv")
# Step 3: Run the code and enjoy automated analysis results generation.
# Note: the ARD is contained in the object "ARD" (which contains the appended) mini-ARDs from all individual Analyses ARDs.

example_ARD_script <- ARD_script_example("ARD_Out14-1-1.R")
source(example_ARD_script)
head(ARD)

The ARD object is the result of appending all analysis-level ARD (created from the cards and cardx functions) for the output. It can be used (and re-used) downstream for various applications. See this vignette for next step in utilising the ARD - like creating Tables, or using it for QC. If you need to hand the ARD to someone outside R, readARS(..., output_format = "datasetjson") makes each script also write its ARD as a CDISC Dataset-JSON file - see Exporting ARDs as Dataset-JSON.

A note on example code used in AnalysisMethodCodeTemplate: using `cards` package

A powerful aspect of the ARS model, is that dynamic code can be supplied as part of the metadata and be evaluated on either 1. the Output level, 2. the Analysis level, or 3. the AnalysisMethod level (for more information on this, see this PHUSE paper). The latter case is implemented by making use of the AnalysisMethodCodeTemplate and AnalysisMethodCodeParameters classes in the metadata. The user supplies dynamic R code (with the option of making use of parameters referring to metadata pieces), which will be executed to perform the relevant AnalysisMethod operations. As was the case in this example, the cards and cardx R packages were used. See more information on this in the vignette on using cards and cardx.