---
title: "Building Reports into the Package"
author: "Nick Howlett, Sandro Gsteiger"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Building Reports into the Package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Building Reports into the Package

Example usage reports are built into this package (as vignettes) with the aim to make the analysis more accessible to new users. Developers can add to the collection of reports by creating a new vignette using devtools

```{r, eval = FALSE}
devtools::use_vignette(name = "Report title", package = "gemtcPlus")
```

Executing the line above will create an R Markdown file in the `vingettes` directory of the package root. All R Markdown files in this directory are built as vignettes when the package is built by running

```{r, eval = FALSE}
devtools::build(vignettes = TRUE)
```

This document will not cover the details of R Markdown, for a good reference I recommend [this](http://r-pkgs.had.co.nz/vignettes.html) resource.

During a `build` (with argument `vignettes = TRUE`) the package is first installed, so the code can be used, and then the vignettes are built. This means that in order to access the functions/datasets that come with the package in the vignette you will need to make a call to `library(gemtcPlus)` at the start of the document.

However there are two conventions which are specific to the vignette building used in this package. The conventions concern reading/writing files. NMAs may involve running very long MCMCs. This can take some time and can have outputs of sizes larger than 100Mb. For this reason it's practical to break the generation of results and presentation of them into separate steps. It's also a good idea to break the output objects required to do so into smaller chunks. Another requirement of running NMA analyses here is the use of `BUGS` code which is most conveniently loaded in from a text file. This necessitates a process to read/write files when building the package vignettes. To handle this properly there are two functions you need to use.

For reading system files the `system.file()` function which will produce a directory path string. Here is an example of loading a `BUGS` file using `system.file()`

```{r, eval = FALSE}
fit <- jags(model.file = system.file("BUGScode",                  
                                     "tte_piece-wise-cst_fe.txt", 
                                     package = "gemtcRoche"),
            data = c(dat_jg,
                     list(prior_mean = 0),
                     list(prior_prec = 0.0001)),
            parameters = c("d", "mu"),
            n.chains = n.chains,
            n.iter = n.iter,
            n.burnin = n.burnin,
            n.thin = n.thin)
```

The call to `system.file()` bases it's root around the `inst` directory which is in the package root. So here the `.txt` files have been previously placed into the `inst/BUGScode` directory.


This solves the file read issue but unfortunately `system.file()` only generates a path to a file that already exists and can not be used to create a path to an output file. Instead we use the `here()` function from the `here` package. Here is an example of the usage when writing output files from a results generation script.

```{r, eval = FALSE}
for(i in seq_along(out_all)){
  out <- out_all[[i]]
  save(out, file = here::here("inst",
                              "extdata",
                              "results",
                              paste("fit-pwe-", i, ".RData", sep = "")))
}
```
The syntax is very similar to `system.file()` however the root is actually the package root and not `inst`. Output files are therefore stored in the `inst/extdata/results/` directory and are read from there when building the output reports using `system.file()`. 

This means that any output results are built into the package. Users should be careful not to save many large files here.