---
title: "Creation of a clinical data review report"
author: "Laure Cougnaud, Michela Pasetto"
date: "`r format(Sys.Date(), '%B %d, %Y')`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 5
    number_sections: true
vignette: >
  %\VignetteIndexEntry{Creation of a clinical data review report}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r options, echo = FALSE, message = FALSE}

library(knitr)
opts_chunk$set(
    echo = TRUE, 
    results = 'asis', 
    warning = FALSE, 
    error = FALSE, message = FALSE, cache = FALSE,
    fig.width = 8, fig.height = 7,
    fig.path = "./figures_vignette/",
    fig.align = 'center')
options(width = 170)
options(warn = 1)#instead of warn = 0 by default -> to have place where warnings occur in the call to Sweave function

```

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.

```{r loadLibraries}

library(clinDataReview)

```

# Create an example report

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

```{r exampleReport-createClinDataReviewReportSkeleton, eval = FALSE}
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:
```{r exampleReport-render_clinDataReviewReport, eval = FALSE}
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.

# File structure

## 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.  
    If not specified, the template _Rmd_ file should be available in the input
    directory (`inputDir`).
    + 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 section [Template reports](#template-reports) for details on the template reports.
        
## 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
    
# Template reports {#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` ``** (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:

```{js, eval = FALSE}
template: divisionTemplate.Rmd
templatePackage: clinDataReview
reportTitle: "Title for a chapter"
reportTitleLevel: 1
```

Please note that you can create your own template reports and store
it in your custom R package (in a 'inst/template' folder).

# Render a clinical data review report

## Production

### Create a report for production

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

```{r render_clinDataReviewReport, eval = FALSE}

clinDataReview::render_clinDataReviewReport()

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

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

```{r createRedirectPage, eval = FALSE}

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.


### Convert to .aspx format

When reports are to be deployed and displayed as webpages on SharePoint, the function:

```{r convertReportToAspx, eval = FALSE}

clinDataReview::convertReportToAspx(reportDir = ".")

```

can be used to change all extensions and cross-links of all files within the _reportDir_ to .aspx-format.


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

```{r zipclinDataReview, eval = FALSE}

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.


### 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

```{r metadata, eval = FALSE}

clinDataReview::getMetadata()

```

## Development

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

### Modular framework

#### (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.

```{r render_clinDataReviewReport-configFiles, eval = FALSE}
# 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"))
```

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

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

```{r postProcessReport, eval = FALSE}

postProcessReport()

```

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

```{r render_clinDataReviewReport-devel, eval = FALSE}

# 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)

```

## Optimization for big clinical trial data

### Optimize the report creation

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.

```{r, eval = FALSE}
clinDataReview::render_clinDataReviewReport(nCores = 4)
```

### Optimize the report loading time

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.

```{js, eval = FALSE}
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.

### Optimize the report structure

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.

# Appendix

## Session info

```{r sessionInfo, echo = FALSE}

print(sessionInfo())

```