We will use the following example to get started:
A modified CDISC Common Safety Displays ARS metadata (xlsx
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 files (json and xlsx), 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.
# To see a list of example files:
ARS_example()
#> [1] "ADAE.csv" "ADSL.csv"
#> [3] "ADVS.csv" "ADZSDER.csv"
#> [5] "Common_Safety_Displays_cards.xlsx" "cards_constructs.xlsx"
#> [7] "exampleARS_1.json" "exampleARS_1a.json"
#> [9] "exampleARS_2.json" "exampleARS_2.xlsx"
#> [11] "exampleARS_2a.xlsx" "exampleARS_3.json"
#> [13] "test_cards.json"
# A temporary path to a specific file:
ARS_example("exampleARS_1.json")
#> [1] "C:/Users/mbosm/AppData/Local/Temp/RtmpOGuy4t/Rinsta79868865c7c/siera/extdata/exampleARS_1.json"
The ARS metadata contains all ARS information for the Reporting Event. This information includes:
The readARS function reads in a completed ARS metadata file, 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 Excel file (note that this is meant as an example. Official ARS metadata is in json format, which can also be passed to the readARS function):
# Path to the Excel ARS metadata file:
ARS_path <- ARS_example("Common_Safety_Displays_cards.xlsx")
# 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 format (we will use 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 5 R scripts (named ARD_Out14-1-1.R, ARD_Out14-3-1-1.R, ARD_Out14-3-2-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 5 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.
The structure of the auto-generated ARD script is discussed the the
ARD structure vignette. Examples
of such an auto-generated ARD scripts are included in the package, and
can be used by using the ARD_script_example
function.
Running this script will look 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)
#> group1 group1_level group2 group2_level variable variable_level stat_name
#> 1 <NA> <NA> TRT01A Placebo n
#> 2 <NA> <NA> TRT01A Xanomeli… n
#> 3 <NA> <NA> TRT01A Xanomeli… n
#> 4 TRT01A Placebo <NA> AGE N
#> 5 TRT01A Placebo <NA> AGE mean
#> 6 TRT01A Placebo <NA> AGE sd
#> stat_label stat
#> 1 n 86
#> 2 n 84
#> 3 n 84
#> 4 N 86
#> 5 Mean 75.209
#> 6 SD 8.59
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.
cards
packageA 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
.