Utility functions are provided to create a standard clinical data review report. Please note that the examples in this section are only informative, and not evaluated in the vignette itself.
To create your clinical data review report, we advise to start from a skeleton of such report, via:
This report is based on an example dataset (subset of the CDISC Pilot
01 dataset), available in the clinUtils package.
The report is created via:
You can further tailor the report to your dataset(s) of interest and sections of interest.
See the next sections for further informations.
The input for the clinical data report consists of a set of
Rmardown files and a config directory.
Rmd files
A set of Rmarkdown files in the working directory should be
index.Rmd file, containing the front page of the
document.
This file should be formatted as a Rmarkdown report with
YAML header, with output set to:
clinDataReview::gitbook_clinDataReview_report
multiple Rmd files, one for each chapter (or template for multiple chapters). These files can be included in a R package.
Config files
There should be a config directory containing:
a general configuration file: config.yml with:
pathDataFolder: path to a directory containing input
data in sas7bdat or xpt formatpatientProfilesPath(optional) : path to a directory
that will contain patient profiles (if they are created with the
patientProfilesTemplate.Rmd template report)study (optional): study nameversion (optional): data version, e.g. batcha configuration file for each chapter, as:
config-[chapterName].yml.
This file should contain input parameters containing:
template: filename of the Rmd file to consider
for this chaptertemplatePackage: name of the R package where the
Rmd should be extracted from.inputDir).clinDataReview
package, these include:
reportTitle: chapter title, used for section
headerdataFileName: filename of the dataset of interest for
this chapter, e.g.: ‘adae.sas7bdat’reportTitleLevel: integer with section level,
e.g. 2params$Please see the section Template reports for details on the template reports.
The clinical data report consists of a final report output and a set of intermediary results.
Final output
A final output folder (‘report’ by default) containing the:
extraDirs parameter)Intermediary results
A folder of intermediary results (‘interim’ by default) containing:
template/templatePackage combination
of the config file(s))knit_meta object) and
session information required for each report partA set of template reports are available in the
clinDataReview package itself.
The full list of the reports and the corresponding input parameters
is available at:
? `clinDataReview-templates` (please note
the backticks!).
To use a template available in the package for one of your report,
your config file should contain the corresponding name of the template
via the template tag and the templatePackage
set to ‘clinDataReview’.
For example, to include a division in the report, your YAML config file should be formatted as:
template: divisionTemplate.Rmd
templatePackage: clinDataReview
reportTitle: "Title for a chapter"
reportTitleLevel: 1Please note that you can create your own template reports and store it in your custom R package (in a ‘inst/template’ folder).
The function render_clinDataReviewReport renders
a clinical data report for production.
The render_clinDataReviewReport creates several html
files, one per configuration file, split based on the
split_by parameter.
To open the full report, the user should open the introduction.html file.
In case a lot of different html chapters are created, a landing page can be created to guide the end-user to the opening of the report.
A convenient way to store all html files into one location, and have only one page to look for to open the report is the function:
This function:
The default names of the folder and landing page are report_dependencies and report.html. The names can be changed by the user.
When reports are to be deployed and displayed as webpages on SharePoint, the function:
can be used to change all extensions and cross-links of all files within the reportDir to .aspx-format.
A dedicated functionality is available to zip the report and send it to colleagues within the team.
Once a report has been rendered, the user can call:
This function zips the report, so that the analyses can be easily put as attachement in a mail/uploaded to a shared drive.
If the folder is not unzipped before opening the reports, a message in the browser reminds to unzip the documents.
To facilitate the creation of the report, a few utility functions & dedicated parameters are available.
In case the creation of the entire report is time-consuming, and only
part(s) of the report have been updated, it might be interesting to only
re-run some parts of the report. Config files associated to the parts of
the report that should be rerun can be specified via the
configFiles parameter.
To debug a sub-report, it might be interesting to run only one specific R report in the current R session, with the parameters provided by the associated config file. This can be achieved as followed:
# get parameters from the general 'config.yml' and the specified config file
params <- getParamsFromConfig(configFile = "config-AE_timeprofile.yml")
# extract template from package if specified
if(params$templatePackage == "clinDataReview"){
pathTemplate <- clinDataReview::getPathTemplate(file = params$template)
file.copy(from = pathTemplate, to = ".")
}
# run a current chapter (without clinical data Js libraries)
# Note that Js library to have the functionality to download patient profiles is not imported
rmarkdown::render(input = params$template)
# preview a specific chapter (with clinical data Js libraries)
bookdown::render_book(input = params$template, preview = TRUE)
# include the index file:
bookdown::render_book(input = c("index.Rmd", params$template), preview = TRUE)The creation of the report can be time-consuming for big clinical trial data.
The creation of the report is speed up via the use of the
nCores parameter. If specified, the creation of the
Markdown file corresponding to each config file, and the creation of the
HTML file for each (split) Markdown file are run in parallel.
The report can take some time to load in the browser for big clinical trial data.
The loading time can be improved by splitting the HTML page into
smaller HTML pages, via the split_by parameter. This can be
set at a level 7 of sectioning (level 1 corresponds to a chapter), and
for a specific part of the report, corresponding to a specific config
file.
template: plotTemplate.Rmd
templatePackage: clinDataReview
reportTitle: 'Laboratory profiles'
reportTitleLevel: 2
split_by: 4
loopingVar: ["LBCAT", "LBTEST"]Example of config file with the use of the split_by
parameter
In the example above, the report contains a section titled: ‘2.1
Laboratory profiles’ (level 2 of sectioning via the
reportTitleLevel parameter), containing a subsection for
each category of laboratory parameter (LBCAT) and a
(nested) subsubsection for each laboratory test
(LBTEST).
For example, this report can contain the subsubsection: ‘2.1.1.1 Alanine
Aminotransferase’ with the laboratory profile for the Alanine
Aminotransferase laboratory parameter.
This chapter is split at level 4 of sectioning: [level 2 for the
title + 2 levels for the loopingVar variables], so the
subsubsections containing the content for a laboratory parameter are
available in separate HTML pages.
In case a lot of sections with interactive plots are created via the
loopingVar parameter, the table of contents can be quite
extensive.
An alternative is to create a selection box (instead of a section) to
select/filter the data of the plot based on grouping of a specific
variable, via the selectVars parameter in the plotting
function.
R version 4.4.1 (2024-06-14) Platform: x86_64-pc-linux-gnu Running under: Ubuntu 24.04.1 LTS
Matrix products: default BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
locale: [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C LC_TIME=en_US.UTF-8
LC_COLLATE=C LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
[7] LC_PAPER=en_US.UTF-8 LC_NAME=C LC_ADDRESS=C LC_TELEPHONE=C
LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
time zone: Etc/UTC tzcode source: system (glibc)
attached base packages: [1] stats graphics grDevices utils datasets methods base
other attached packages: [1] plyr_1.8.9 plotly_4.10.4 ggplot2_3.5.1 clinUtils_0.2.0 clinDataReview_1.6.1 knitr_1.48 rmarkdown_2.28
loaded via a namespace (and not attached): [1] gtable_0.3.6 xfun_0.48
bslib_0.8.0 htmlwidgets_1.6.4 ggrepel_0.9.6 vctrs_0.6.5
[7] tools_4.4.1 crosstalk_1.2.1 generics_0.1.3 parallel_4.4.1
tibble_3.2.1 fansi_1.0.6
[13] pkgconfig_2.0.3 data.table_1.16.2 uuid_1.2-1 lifecycle_1.0.4
flextable_0.9.7 compiler_4.4.1
[19] farver_2.1.2 stringr_1.5.1 textshaping_0.4.0 munsell_0.5.1
fontquiver_0.2.1 fontLiberation_0.1.0
[25] htmltools_0.5.8.1 sys_3.4.3 buildtools_1.0.0 sass_0.4.9 yaml_2.3.10
lazyeval_0.2.2
[31] pillar_1.9.0 jquerylib_0.1.4 tidyr_1.3.1 openssl_2.2.2 DT_0.33
cachem_1.1.0
[37] jsonvalidate_1.3.2 fontBitstreamVera_0.1.1 zip_2.3.1
tidyselect_1.2.1 digest_0.6.37 stringi_1.8.4
[43] reshape2_1.4.4 dplyr_1.1.4 purrr_1.0.2 bookdown_0.41
maketools_1.3.1 labeling_0.4.3
[49] forcats_1.0.0 cowplot_1.1.3 fastmap_1.2.0 grid_4.4.1
colorspace_2.1-1 cli_3.6.3
[55] magrittr_2.0.3 base64enc_0.1-3 utf8_1.2.4 withr_3.0.2 gdtools_0.4.0
scales_1.3.0
[61] officer_0.6.7 httr_1.4.7 inTextSummaryTable_3.3.3 askpass_1.2.1
ragg_1.3.3 hms_1.1.3
[67] evaluate_1.0.1 haven_2.5.4 viridisLite_0.4.2 rlang_1.1.4
Rcpp_1.0.13 glue_1.8.0
[73] xml2_1.3.6 jsonlite_1.8.9 R6_2.5.1 systemfonts_1.1.0