by Matt Parker, Data Scientist at Microsoft
One of the great advantages of R's openness is its extensibility. R's abundant packages are the most conspicuous example of that extensibility, and Revolution R Enterprise is a powerful example of how far it can stretch.
But R is also part of an entire ecosystem of open tools that can be linked together. For example, Markdown, Pandoc, and knitr combine to make R an incredible tool for dynamic reporting and reproducible research. If your chosen output format is HTML, you've linked into yet another open ecosystem with countless further extensions.
One of those extensions - and the focus of this post - is jQuery UI. jQuery UI makes a set of JavaScript's most useful moves available to developers as a robust, easy-to-implement toolkit ideal for adding a bit of interactivity to your knitr reports.
Tabs
For example: it's easy to use jQuery UI's Tabs widget to split a long report across several tabs of a webpage. Tabs are great for splitting complex reports up by topic, or for providing different types of users with customized views of the results.
To get a sense of what this conversion might look like, here's a simple R-Markdown report without tabs (Rmd source):
... and the same report with tabs (source):
Here's how I added tabs to the report.
1) First, I downloaded jQuery UI. Picking the right place to store the library can be tricky, but as long as the jQuery UI files are accessible to knitr when it's building the report, you'll be okay. For this demo report, I just unzipped the files right next to the .rmd source.
2) Next, I added a few lines to the <head>
element of the report. Every
webpage has a <head>
element. knitr would typically build this for you, but
in this case we need to write it manually to be sure that the jQuery UI scripts
and CSS are linked in the HTML output.
<head>
<meta charset="utf-8">
<title>Reported Active Tuberculosis Cases in the United States, 1993-2013</title>
<link rel="stylesheet" href="jquery-ui/jquery-ui.min.css">
<script src="jquery-ui/external/jquery/jquery.js"></script>
<script src="jquery-ui/jquery-ui.js"></script>
<script>
$(function() {
$( "#tabs" ).tabs();
});
</script>
</head>
3) Next, I created the navigation bar by creating an HTML chunk (div
) with a
list inside of it (ul
). Each item in that list (li
) represents one tab
that I'd like the page to have. Finally, I make each of those list items a link
with a unique tag (<a href="#nation">
),
and give the link a title (Nationally
, By State
, Treatment Completion
).
<div id="tabs">
<ul>
<li><a href="#nation">Nationally</a></li>
<li><a href="#states">By State</a></li>
<li><a href="#treatment">Treatment Completion</a></li>
</ul>
Don't worry if you don't understand the HTML syntax here - you can just copy and edit the code above.
4) Finally, I marked out which sections of R-Markdown I wanted to put on each
tab by surrounding that section with a div
:
<div id="nation">
## Reported Active TB Cases in the United States, 1993-2013
```{r nation}
tbstats %>%
group_by(Year) %>%
summarise(n_cases = sum(Count)) %>%
ggplot(aes(x = Year, y = n_cases)) +
geom_line(size = 2) +
labs(x = "Year Reported",
y = "Number of Cases",
title = "Reported Active TB Cases in the United States") +
expand_limits(y = 0)
```
</div>
There are two crucial details here:
- the div
has an id
that corresponds to one of the tabs I've created
(href=#nation
corresponds to <div id="nation">
)
- the div
is closed with a </div>
tag. Without this, the entire report
would be included on the first tab.
5) Click the "Knit HTML" button! knitr will convert your R-Markdown into plain Markdown, and then call Pandoc to complete the conversion into gloriously-tabbed HTML.
Tabs are very handy for reporting - but the whole HTML/CSS/JavaScript ecosystem is at your disposal. If you've seen other good reporting tricks in HTML, let us know in the comments below.
This is fantastic; I'm really surprised at how easy it was to reproduce in RStudio on my system. Thank you for sharing this!
One minor tip: if you add "guide = guide_legend(title = "State")" to both scale_color_manual() and scale_size_manual(), you'll get a single legend with size and color combined, instead of the two separate legends.
Posted by: ThomasHopper | December 31, 2015 at 16:03
Why not use Shiny's built-in support for tabs? See an example here: http://shiny.rstudio.com/gallery/tabsets.html
Posted by: Kent Johnson | January 02, 2016 at 18:46
Oh, never mind! You aren't using Shiny...
Posted by: Kent Johnson | January 02, 2016 at 18:48
Nice, of course if you're using the bootstrap themes that come with RStudio
http://rmarkdown.rstudio.com/html_document_format.html
then you don't need to download jQuery UI - you get tabs (and other stuff) for free.
See the tabs here and view source to see what code to use:
http://bootswatch.com/flatly/#navs
I've created reports with tabbed sections in this way. Have also used alert boxes, list groups and panels.
Posted by: Dakvid | January 03, 2016 at 01:20
That'll teach me not to Preview.
Clickable links:
http://rmarkdown.rstudio.com/html_document_format.html
http://bootswatch.com/flatly/#navs
Posted by: Dakvid | January 03, 2016 at 01:22
This is a really interesting concept and route to using jquery.ui widgets.
I'd be very interested how to go about integrating more interactive widgets like sliders, comboboxes etc.
Any pointers on that would be much appreciated.
Posted by: _StarKingdom | January 06, 2016 at 07:38