# Creation of a clinical data review report

#### Laure Cougnaud, Michela Pasetto

#### February 23, 2022

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.

    library(clinDataReview)

# 1 Create an example report

To create your clinical data review report, we advise to start from a skeleton of such report, via:

    createClinDataReviewReportSkeleton()

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:

    render_clinDataReviewReport()

You can further tailor the report to your dataset(s) of interest and sections of interest.

See the next sections for further informations.

# 2 File structure

## 2.1 Input

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 format
  - `patientProfilesPath`(optional) : path to a directory that will contain patient profiles (if they are created with the `patientProfilesTemplate.Rmd` template report)
  - `study` (optional): study name
  - `version` (optional): data version, e.g. batch
- a 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 chapter
  - `templatePackage`: name of the R package where the Rmd should be extracted from
  - template-specific parameters:
    For the template reports available in the `clinDataReview` package, these include:
    - `reportTitle`: chapter title, used for section header
    - `dataFileName`: filename of the dataset of interest for this chapter, e.g.: ‘adae.sas7bdat’
    - `reportTitleLevel`: integer with section level, e.g. 2
    - extra parameters, accessed inside the template via `params$`

Please see the `? clinDataReview-templates` documentation for further information on the template reports available in the `clinDataReview` package, and their input parameters.

## 2.2 Output

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:

- final clinical data report, in a set of multiple HTML files
- required Javascript libraries in the subfolder: ‘libs’
- any extra directories created during report execution, by default: ‘tables’ and ‘figures’ (`extraDirs` parameter)
- (optionally) a directory with patient profiles

Intermediary results

A folder of intermediary results (‘interim’ by default) containing:

- Markdown file(s) for each report part
  (one per `template`/`templatePackage` combination of the config file(s))
- associated rds file containing specification of the Javascript libraries (via `knit_meta` object) and session information required for each report part

# 3 Template reports

A 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``.

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: 1

# 4 Render a clinical data review report

## 4.1 Production

### 4.1.1 Create a report for production

The function `render_clinDataReviewReport` renders a clinical data report for production.

    clinDataReview::render_clinDataReviewReport()

The `render_clinDataReviewReport` creates several html files, one per section/subsection.

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.

### 4.1.2 Create redirect page

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

    clinDataReview::createRedirectPage()

This function:

- stores all html files into a folder
- create a landing page next to the folder that allows the user to navigate through the report.

The default names of the folder and landing page are report_dependencies and report.html. The names can be changed by the user.

### 4.1.3 Zip and send the report to collaborators

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:

    clinDataReview::zipClinDataReview()

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.

### 4.1.4 Add metadata

Metadata can be added in the landing page, containing information concerning the data set creation time, the path to the original data etc.

A metadata file should be in yaml format.

The metadata function can be directly called in a Rmd documents with

    clinDataReview::getMetadata()

## 4.2 Development

To facilitate the creation of the report, a few utility functions & dedicated parameters are available.

### 4.2.1 Modular framework

#### 4.2.1.1 (Re-)run part(s) of the report

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.

    # run one specific report
    clinDataReview::render_clinDataReviewReport(configFiles = "config-AE_timeprofile.yml")
    # only run the listings:
    clinDataReview::render_clinDataReviewReport(configFiles = list.files(pattern = "listing", "config"))

#### 4.2.1.2 Create the final clinical data report from the Markdown reports

To convert all created Markdown files to HTML, the dedicated function `convertMdToHtml` can be used.

    convertMdToHtml()

### 4.2.2 Debug a sub-report

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)

# 5 Appendix

## 5.1 Session info

R version 4.1.2 (2021-11-01)

Platform: x86_64-pc-linux-gnu (64-bit)

locale: 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, LC_PAPER=en_US.UTF-8, LC_NAME=C, LC_ADDRESS=C, LC_TELEPHONE=C, LC_MEASUREMENT=en_US.UTF-8 and LC_IDENTIFICATION=C

attached base packages: stats, graphics, grDevices, utils, datasets, methods and base

other attached packages: plyr(v.1.8.6), inTextSummaryTable(v.3.1.1), reshape2(v.1.4.4), plotly(v.4.10.0), ggplot2(v.3.3.5), clinUtils(v.0.1.1), clinDataReview(v.1.2.2), pander(v.0.6.4) and knitr(v.1.37)

loaded via a namespace (and not attached): ggrepel(v.0.9.1), Rcpp(v.1.0.8), tidyr(v.1.2.0), digest(v.0.6.29), utf8(v.1.2.2), R6(v.2.5.1), evaluate(v.0.15), httr(v.1.4.2), pillar(v.1.7.0), gdtools(v.0.2.4), rlang(v.1.0.1), lazyeval(v.0.2.2), uuid(v.1.0-3), data.table(v.1.14.2), DT(v.0.20), flextable(v.0.6.10), rmarkdown(v.2.11), labeling(v.0.4.2), stringr(v.1.4.0), htmlwidgets(v.1.5.4), munsell(v.0.5.0), compiler(v.4.1.2), xfun(v.0.29), pkgconfig(v.2.0.3), systemfonts(v.1.0.4), base64enc(v.0.1-3), htmltools(v.0.5.2), tidyselect(v.1.1.1), tibble(v.3.1.6), bookdown(v.0.24), jsonvalidate(v.1.3.2), fansi(v.1.0.2), viridisLite(v.0.4.0), crayon(v.1.5.0), dplyr(v.1.0.8), withr(v.2.4.3), grid(v.4.1.2), jsonlite(v.1.7.3), gtable(v.0.3.0), lifecycle(v.1.0.1), magrittr(v.2.0.2), scales(v.1.1.1), zip(v.2.2.0), cli(v.3.2.0), stringi(v.1.7.6), farver(v.2.1.0), xml2(v.1.3.3), ellipsis(v.0.3.2), generics(v.0.1.2), vctrs(v.0.3.8), cowplot(v.1.1.1), tools(v.4.1.2), forcats(v.0.5.1), glue(v.1.6.1), officer(v.0.4.1), purrr(v.0.3.4), hms(v.1.1.1), crosstalk(v.1.2.0), fastmap(v.1.1.0), yaml(v.2.3.5), colorspace(v.2.0-3) and haven(v.2.4.3)