Introduction to interactive documents

Garrett Grolemund

July 9, 2014

Interactive documents are a new way to build Shiny apps. An interactive document is an R Markdown file that contains Shiny widgets and outputs. You write the report in markdown, and then launch it as an app with the click of a button.

R Markdown

You can embed executable R code into your file, which saves manual labor and creates a reproducible report.

You can convert R Markdown files into HTML, PDF, and Word documents with the click of a button.

You can convert R Markdown files into ioslides and beamer slideshows with the click of a button.

In fact, R Markdown files are the ultimate R reporting tool.

This article will show you one more thing that R Markdown files can do: you can embed Shiny components in an R Markdown file to create an interactive report or slideshow.

Your report will be a complete Shiny app. In fact, R Markdown provides the easiest way to build light-weight Shiny apps. I will refer to apps that combine Shiny with R Markdown as interactive documents.

The structure of an interactive document

When you run an interactive document, rmarkdown extracts the code in your code chunks and places them into a pseudo server.R file. R Markdown uses the html output of the markdown file as an index.html file to place the reactive elements into.

As a result, outputs in one code chunk can use widgets and reactive expressions that occur in other code chunks.

Since the R Markdown document provides a layout for the app, you do not need to write a ui.R file.

Sharing interactive documents

Interactive documents are a type of Shiny app, which means that you can share them in the same way that you share other Shiny apps. You can

Email a .Rmd file to a colleague. He or she can run the file locally by opening the file and clicking “Run Document”

Note: If you are familiar with R Markdown, you might expect RStudio to save an HTML version of an interactive document in your working directory. However, this only works with static HTML documents. Each interactive document must be served by a computer that manages the document. As a result, interactive documents cannot be shared as a standalone HTML file.

Conclusion

Interactive documents provide a new and easy way to make Shiny apps.

Interactive documents will not replace standard Shiny apps since they cannot provide the design options that come with a ui.R or index.html file. However, interactive documents do create some easy wins:

The R Markdown workflow makes it easy to build light-weight apps. You do not need to worry about laying out your app or building an HTML user interface for the app.

You can use R Markdown to create interactive slideshows, something that is difficult to do with Shiny alone. To create a slideshow, change output: html_document to output: ioslides_presentation in the YAML front matter of your .Rmd file. R Markdown will divide your document into slides when you click “Run Document.” A new slide will begin whenever a header or horizontal rule (***) appears.

Interactive documents enhance the existing R Markdown workflow. R Markdown makes it easy to write literate programs and reproducible reports. You can make these reports even more effective by adding Shiny to the mix.