Building Reports into the Package

Nick Howlett, Sandro Gsteiger

2022-07-26

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

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

devtools::build(vignettes = TRUE)

This document will not cover the details of R Markdown, for a good reference I recommend this 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()

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.

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.