In lgatto/rauthoring: An introduction to authoring literate programming documents.

Authoring document for R

library("rauthoring")
library("DESeq2")

Introduction

This first section introduces some tools to author documents that contain analysis results produced with R. Bringing data, results and their interpretation is essential to assure reproducibility of an analysis pipeline and to comprehensively communicate these results to collaborators. A popular solution for this is literate programming, a technique and set of tools that permit to

Write text and code within a single document. Here we will use the simple markdown syntax and include R code chunks; such documents are denoted R markdown and have the Rmd extension.
Extract (called tangling) and execute the code
Replace the original code chunks by their results into the original document (called weaving).
Compile the document into a final easily read format such as pdf or html.

Steps 2 to 4 are can be executed individually or automated into a single command such as knit2html from the knitr package or using editors such as Rstudio.

Other types of document and frameworks that combine a programming and authoring languages are Sweave and knitr files Rnw (combining LaTeX and R), IPython for python and other languages, orgmode, ...

The second section introduces the ReportingTools package, in particular generation of interactive tables.

The last part very briefly presents the shiny package by describing a simple application and suggesting a few ways to improve it.

The test data used throughout this document is a DESeq2 result, available with

library("rauthoring")
data(res)
head(res)
class(res)

R Markdown

Markdown syntax

The figures below, taken from the Rstudio markdown (v2) tutorial illustrates basic markdown syntax and its output using Rstudio.

Headers can be defined using ====== or ----- (level 1 and 2 respectively) or one or multiple # (for level 1, 2, ... respectively).
Italic and bold fonts are defined using one to two * around the text.
Bullet lists items start with a -.
In-line code and verbatim expression are surrounded by `.
Code blocks start and end with three back ticks.
Starting a line with > offsets the text.

Markdow basics

R code chunks

To include R code in the R markdown file, the native code chunk syntax is augmented with code chunk tags inside {r, ...}, as illustrated below:

Markdown code chunk

The following optimal code chunk options are available:

{r, chunkname} the first unnamed string is used to name the code chunk; useful for following the code execution and debugging.
{r, eval=TRUE} by default the code in the chunk is executed. Alternatively, set eval=FALSE.
{r, echo=TRUE} by default, the code is displayed before the output. Use echo=FALSE to hide the code.
Control if messages, warnings or errors are to be displayed with {r, message=TRUE, warning=TRUE, error=TRUE}.
Figure dimensions can be controlled with fig.height and fig.width.

To execute in-line code, use ` r 1+1` (no space between ` and r).

From `Rmd` to `html`

If you are using Rstudio, the simplest way to generate your final output is to open your Rmd file and click the Knit HTML (or Knit PDF, ...) button. From R, you can use the knit2html function and give the Rmd as input. Both options will use the knit function to weave the document and generate the markdown md file that includes the code outputs. The generation of the final output will depend on the software version you use: either markdown::markdownToHTML or the more recent rmarkdown::render functions.

Exercise: Experiment with R markdown and the features described so far. Either create your Rmd file from scratch or use the simple template from the rauthoring package with rmdtemplate().

More markdown

Superscript^2^ using ^2^ and ~~strikethrough~~ using ~~strikethrough~~.
To use ordered lists, just precede to list items by their respective number:
1. first item
2. second item
3. and so on ...
To use links, enclose the link text in [] and the the actual link in (): [my link](http://linkurl.com)
To add a static figure to the document, use the link syntax and precede it by !: ![image text](./fig/myfig.png).
Tables can easily be printed inside an R chunk. Below, we explicitly convert res to a data.frame. Although the next code chunk would also work, not every function to display a table would accept a specific class such as DESeqResults.

library("rauthoring")
library("DESeq2")
data(res)
head(res)
class(res)
res <- data.frame(res)

The most recent version of R Markdown also has a table syntax described here. Such tables can be generated with the helper function knitr::kable. Such tables are then displayed as html tables. Instead of copy/pasting the output of kabble into the R markdown document, one can specify results='asis' for the output of the code chunk to be interpreted as is, i.e. write raw results from R into the output document.

library("knitr")
kable(head(res))

library("knitr")
kable(head(res))

To avoid wasting time in repeating long calculations over and over again, it is possible to cache specific code chunks specifying cache=TRUE in the chunk header.
The most recent release of R markdown (version 2) supports many more features and requires a recent version of pandoc, the workhorse that converts markdown to html and many other formats.

Try out some of these additional features in your own Rmd file or look at this vignettes source code. Find where it is with system.file("doc/rauthoring.Rmd", package = "rauthoring").

ReportingTools

The Bioconductor ReportingTools provides additional features to generate reports. From the Bioc landing page:

The ReportingTools software package enables users to easily
display reports of analysis results generated from sources such as
microarray and sequencing data. The package allows users to create
HTML pages that may be viewed on a web browser such as Safari, or
in other formats readable by programs such as Excel. Users can
generate tables with sortable and filterable columns, make and
display plots, and link table entries to other data sources such
as NCBI or larger plots within the HTML page. Using the package,
users can also produce a table of contents page to link various
reports together for a particular project that can be viewed in a
web browser. For more examples, please visit our site:
http://research-pub.gene.com/ReportingTools.

For example, to create a html report that contains an interactive html table:

library("ReportingTools")
htmlRep <- HTMLReport(shortName = "htmltable",
                      reportDirectory = "./reports")
publish(res, htmlRep)
finish(htmlRep)
browseURL("./reports/htmltable.html")

Note that the code above requires a data.frame and would not work with DESeqResults.

Generate the ReportingTools dynamic html table as shown above.

In particular, it seamlessly integrates with knitr and R markdown documents, as illustrated in the knitrreptools vignette.

See the ReportingTools vignettes for more details and other use cases:

vignette(package = "ReportingTools")

Web applications with `shiny`

shiny is an R package that allows to build interactive web applications from R. These apps are composed of a user interface part and a server back end. These are saved in the ui.R and server.R files respectively. Both files are stored in a directory, app1 below. Both sides continuously react to their respective updates, hence the term of reactive programming.

Server

The server back end defines the server functionality through the shinyServer function, which itself takes an anonymous function as input with parameters input and output. The former corresponds to data that stems for the user interface (see below) and the latter defines the server output that will be available to the interface.

writeLines(readLines(system.file("extdata/app1/server.R", package = "rauthoring")))

Interface

The interface is handled by the shinyUI function that draws the interface layout. Below, we create a fluidPage layout composed by a title and a side bar layout. The latter contains a side bar and a main panel. The side bar get a slider input widget with ranges from 10 to 100 and default value 50 - the value will be available in the server input as input$breaks. The main panel is composed by a plot renderer that display the value "hist", that is returned by the server back end.

writeLines(readLines(system.file("extdata/app1/ui.R", package = "rauthoring")))

To start this application use the runApp function with the name of the directory containing the server and interface definitions.

runApp("./app1")

Create the ui.R and server.R files, store them in a directory, and start you shiny app.

Let's try to improve our simple first app. A suggestion is available by running the app2() function. The additional widgets added to the interface are radioButtons, a numericInput field (side bar) and a verbatimTextOutput (main panel). The server back end takes advantage of two new inputs to add a vertical line to the histogram and displays a table of significant/non-significant features.

A few useful links : - shiny tutorial - shiny widgets. - Application layouts