R Markdown is a package that supports using R to dynamically create documents, such as websites (.html files), reports (.pdf files), slideshows (using ioslides or slidy), and even interactive web apps (using shiny).
As you may have guessed, R Markdown does this by providing the ability to blend Markdown syntax and R code so that, when executed, scripts will automatically inject your code results into a formatted document. The ability to automatically generate reports and documents from a computer script eliminates the need to manually update the results of a data analysis project, enabling you to more effectively share the information that you’ve produced from your data. In this chapter, you’ll learn the fundamentals of the RMarkdown library to create well-formatted documents that combine analysis and reporting.
Mathematics in R Markdown R Pruim October 19, 2016. Math inside RMarkdown. In side a text chunk. R Markdown v1: how can I convert Markdown to Word? Mynicedocument is your own function that returns a list of knitr and Pandoc options. The prettydoc package provides an alternative engine, htmlpretty, to knit your R Markdown document into. Rcpp::List optimtest Eigen::VectorXd x(2). Note: this can be confusing, because the R Markdown language delimits superscripts with two carets. Is always equal to zero in any list of numbers.
12.1 R Markdown and RStudio
R Markdown documents are created from a combination of two libraries: rmarkdown (which process the markdown and generates the output) and knitr (which runs R code and produces Markdown-like output). These packages are already included in RStudio, which provides built-in support for creating and viewing R Markdown documents.
12.1.1 Creating .Rmd Files
The easiest way to begin a new R-Markdown document in RStudio is to use the File > New File > R Markdown menu option:
RStudio will then prompt you to provide some additional details abour what kind of R Markdown document you want. In particular, you will need to choose a default document type and output format. You can also provide a title and author information which will be included in the document. This chapter will focus on creating HTML documents (websites; the default format)—other formats require the installation of additional software.
Specify document type.
Once you’ve chosen R Markdown as your desired file type, you’ll be prompted to choose a default document type and output format that you would like to create. In this module, we’ll discuss creating HTML documents (websites).
Once you’ve chosen your desired document type and output format, RStudio will open up a new script file for you. The file contains some example code for you.
12.1.2.Rmd Content
At the top of the file is some text that has the format:
This is the document “header” information, which tells R Markdown details about the file and how the file should be processed. For example, the title, author, and date will automatically be added to the top of your document. You can include additional information as well, such as whether there should be a table of contents or even variable defaults.
- The header is written in YAML format, which is yet another way of formatting structured data similar to
.csvor JSON (in fact, YAML is a superset of JSON and can represent the same data structure, just using indentation and dashes instead of braces and commas).
Below the header, you will find two types of content:
- Markdown: normal Markdown text like you learned in Chapter 3. For example, you can use two pound symbols (
##) for a second-level heading. - Code Chunks: These are segments (chunks) of R code that look like normal code block elements (using
```), but with an extra{r}immediately after the opening backticks.
R Markdown will be able to execute the R code you include in code chunks, and render that output in your Markdown. More on this below.
Important This file should be saved with the extension .Rmd (for “R Markdown”), which tells the computer and RStudio that the document contains Markdown content with embedded R code.
12.1.3 Knitting Documents
RStudio provides an easy interface to compile your .Rmd source code into an actual document (a process called “knitting”). Simply click the Knit button at the top of the script panel:
This will generate the document (in the same directory as your .Rmd file), as well as open up a preview window in RStudio.
While it is easy to generate such documents, the knitting process can make it hard to debug errors in your R code (whether syntax or logical), in part because the output may or may not show up in the document! We suggest that you write complex R code in another script and then source() that script into your .Rmd file for use the the output. This makes it possible to test your data processing work outside of the knit application, as well as separates the concerns of the data and its representation—which is good programming practice.
Nevertheless, you should still be sure and knit your document frequently, paying close attention to any errors that appear in the console.
Pro-tip: If you’re having trouble finding your error, a good strategy is to systematically remove segments of your code and attempt to re-knit the document. This will help you identify the problematic syntax.
12.1.4 HTML
Assuming that you’ve chosen HTML as your desired output type, RStudio will knit your .Rmd into a .html file. HTML stands for HyperText Markup Language and, like Markdown, is a syntax for describing the structure and formatting of content (though HTML is far more extensive and detailed). In particular, HTML is a markup language that can be automatically rendered by web browsers, and thus is the language used to create web pages. As such, the .html files you create can be put online as web pages for others to view—you will learn how to do this in a future chapter. For now, you can open a .html file in any browser (such as by double-clicking on the file) to see the content outside of RStudio!
- As it turns out, it’s quite simple to use GitHub to host publicly available webpages (like the
.htmlfiles you create with RMarkdown). But, this will require learning a bit more aboutgitand GitHub. For instructions on publishing your.htmlfiles as web-pages, see chapter 14.
12.2 R Markdown Syntax
What makes R Markdown distinct from simple Markdown code is the ability to actually execute your R code and include the output directly in the document. R code can be executed and included in the document in blocks of code, or even inline in the document!
12.2.1 R Code Chunks
Code that is to be executed (rather than simply displayed as formatted text) is called a code chunk. To specify a code chunk, you need to include {r} immediately after the backticks that start the code block (the ```). For example:
Note that by default, the code chunk will render any raw expressions (e.g., x)—just like you would see in the console if you selected all the code in the chunk and used ctrl-enter to execute it.
It is also possible to specify additional configuration options by including a comma-separate list of named arguments (like you’ve done with lists and functions) inside the curly braces following the r:
- The first “argument” (
options_example) is a “name” for the chunk, and the following are named arguments for the options. Chunks should be named as a variable or function, based on what code is being executed and/or rendered by the chunk. It’s always a good idea to name individual code chunks as a form of documentation.
There are many options for creating code chunks (see also the reference). However some of the most useful ones have to do with how the code is outputted in the the document. These include:
echoindicates whether you want the R code itself to be displayed in the document (e.g., if you want readers to be able to see your work and reproduce your calculations and analysis). Value is eitherTRUE(do display; the default) orFALSE(do not display).messageindicates whether you want any messages generated by the code to be displayed. This includes print statements! Value is eitherTRUE(do display; the default) orFALSE(do not display).
If you only want to show your R code (and not evaluate it), you can alternatively use a standard Markdown codeblock that indicates the r language (```r, not```{r}), or set the eval option to FALSE.
12.2.2 Inline Code
In addition to creating distinct code blocks, you may want to execute R code inline with the rest of your text. This empowers you to reference a variable from your code-chunk in a section of Markdown—injected that variable into the text you have written. This allows you to easily include a specific result inside a paragraph of text. So if the computation changes, re-knitting your document will update the values inside the text without any further work needed.
As with code blocks, you’ll follow the Markdown convention of using single backticks (`), but put the letter r immediately after the first backtick. For example:
When you knit the text above, the `r 3 + 4` would be replaced with the number 7.
Note you can also reference values computed in the code blocks preceding your inline code; it is best practice to do your calculations in a code block (with echo=FALSE), save the result in a variable, and then simply inline that variable with e.g., `r my.variable`.
12.3 Rendering Data
R Markdown’s code chunks let you perform data analysis directly in your document, but often you will want to include more complex data output. This section discusses a few tips for specifying dynamic, complex output to render using R Markdown.
12.3.1 Rendering Strings
If you experiment with knitting R Markdown, you will quickly notice that using print() will generate a code block with content that looks like a printed vector:
For this reason, you usually want to have the code block generate a string that you save in a variable, which you can then display with an inline expression (e.g., on its own line):
Note that any Markdown syntax included in the variable (e.g., if you had msg <- '**Hello** world') will be rendered as well—the `r msg `is replaced by the value of the expression just as if you had typed that Markdown in directly. This allows you to even include dynamic styling if you construct a “Markdown string” out of your data.
Alternatively, you can use as results option of 'asis', which will cause the “output” to be rendered directly into the markdown. When combined with the cat() function (which concatenates content without specifying additional information like vector position), you can make a code chunk effectively render a specific string:
12.3.2 Rendering Lists
Because outputted strings render any Markdown they contain, it’s possible to specify complex Markdown such as lists by constructing these strings to contain the - symbols utilized (note that each item will need to be separated by a line break or a n character):
Would output a list that looks like:
Combined with the vectorized paste() function, it’s to easily convert vectors into Markdown lists that can be rendered
And of course, the contents of the vector (e.g., the text 'Lions') could easily have additional Markdown syntax syntax to include bold, italic, or hyperlinked text.
- Creating a “helper function” to do this conversion is perfectly reasonable; or see libraries such as
panderwhich defines a number of such functions.
12.3.3 Rendering Tables
Because data frames are so central to programming with R, R Markdown includes capabilities to easily render data frames as Markdown tables via the knitr::kable() function. This function takes as an argument the data frame you wish to render, and it will automatically convert that value into a Markdown table:
kable()supports a number of other arguments that can be used to customize how it outputs a table.- And of courrse, if the values in the dataframe are strings that contain Markdown syntax (e.g., bold, itaic, or hyperlinks), they will be rendered as such in the table!
So while you may need to do a little bit of work to manually generate the Markdown syntax, it is possible to dynamically produce complex documents based on dynamic data sources
Resources
- R Markdown Cheatsheet (really useful!)
- R Markdown Reference (really useful!)
R Markdown in corporate settings
I’ve been busy recently writing a paper at work using R Markdown, the wonderful tool provided by the folks at RStudio “to weave together narrative text and code to produce elegantly formatted output”. I don’t use R Markdown for my blog, because I prefer to separate my analytical scripts from the text and reintegrate the products by hand (I have my reasons, not necessarily good ones, but reasons of a sort). Saints row 2 stillwater. But in many contexts the integration of the code, output and text in R Markdown is a fantastic way to quickly and easily produce good-looking content.
In most organisations I’ve worked for, documents need to reflect the corporate look and feel. Typically, details are defined in a style guide and manifested in Microsoft Word and PowerPoint templates. Important details include permissible fonts, heading styles, design elements’ colours, and so on. In an organisation which does a lot of statistical graphics, you might also have guidelines for colours and other thematic aspects of plots.
I found myself having to solve a few minor problems to get my R Markdown at work generating a stand-alone HTML file that looks close enough to the look and feel that customers wouldn’t get a jolt when they saw the result and ask me to re-do it in Word. So today’s blog post jots down some of what I learned, if only so I’ve got it all in one place for myself.
To illustrate this, I set up a GitHub repository of source code for a hypothetical project involving some data management, analysis and report writing. Feel free to clone and re-use it (attribution would be nice). Here’s a screenshot of the top of my hypothetical report:
Clicking on the image will get you the whole report including some plots of New Zealand’s regional tourism, which I used as readily-available data.
Structuring the project
I divide most of my projects of this sort into four conceptual tasks:
- setup - loading up packages and defining functions and assets that will be used repeatedly
- data munging - download / extraction / creation and management into a stable state to be referred to throughout the project
- analysis
- building outputs such as reports, presentations and web tools
These tasks aren’t done in a simple linear manner. For example, sometimes I start writing parts of the report first. Nearly always I don’t know what “functions and assets will be used repeatedly” until I find myself doing similar things a few times.
This project is set up as a folder system comprising a single Git repository and RStudio project. I like to have a one-to-one relationship of Git repositories and RStudio projects. In this project I’ve got four subfolders:
Rprepdatareport-1
The R folder has two scripts:
corp-palette.Rwhich defines the corporate font and colour scheme to be used in graphics created by Rbuild_doc.Rwhich defines a function to render the R Markdown file into HTML (more on why this is needed later).
The prep folder in this case holds a single script which downloads a dataset from the web, imports it from its Excel format and does some minor data management tasks like defining additional columns for use in future analysis.
The data folder holds data - both the raw data downloaded from the web, and analysis-ready versions as .rda files. The Git project has been told (via the .gitignore file) to ignore data files so they don’t bloat up the source code repository but are created by the script in prep.
Finally, the report-1 holds a file written in R Markdown (report.Rmd) and some other assets like the SVG of the corporate logo.
In a larger project I might have a separate analysis folder, with scripts doing various analytical tasks. In this case, all of that is done in R chunks in the report.Rmd file.
Now, with a project as simple as this I could have had it all in a single .Rmd file which could be distributed by itself, but that approach doesn’t scale up well. I intensely dislike using a big .Rmd file as my main workflow control. Getting on top of the caching of R chunks alone is a major cause of frustration. There are also challenges with working directories, although these have been mitigated by recent developments in the world of knitr. But mostly it’s just good practice to think of analytical projects beyond the trivial in size as projects, involving a portable folder system not just individual scripts.
In this approach, the .Rmd file itself doesn’t need to be (and isn’t) 100% reproducible, so I avoid the “knit” button in RStudio which spawns a fresh R session from scratch. Instead I ensure reproducibility of the project - I should be able to make a fresh clone on a fresh computer with the right R packages on it, source build.R in a fresh session and have it run. But the .Rmd file isn’t self-sufficient, and I don’t think that’s a reasonable expectation in a big project (bigger than this toy).
This approach also works well in the common situation that a single project has multiple outputs eg a couple of reports, a Shiny app and a presentation. Www xvidmovies com free. It makes little sense for each report and presentation to be self-sufficient and repeat tasks that are really one-off project tasks.
There’s an R script in the root directory of the project called build.R which basically runs scripts in the other folders in the correct order to re-create the whole exercise from scratch. Here’s what that script looks like. Notice I’ve tried to make it as aware of the environment as possible; for example, it doesn’t matter what order the files in the R subfolder are run in, so it just finds all the files there and runs them in alphabetical order. This means I don’t need to change the build.R script when I put a new script in the R directory.
R Markdown with RStudio Server on a mapped network drive
I’m pretty sure there’s a bug associated with the combination of RMarkdown, RStudio Server, Pandoc and mapped network drives. The long and the short of it is that rmarkdown::render('document.Rmd') will fail when asked to build a stand-alone HTML file if document.Rmd is on a mapped network drive. I really needed an emailable stand-alone HTML file, and at work my only access to R was on RStudio Server; and mapped network drives the only ones RStudio could see that I could access from the Windows file system.
I got past that problem with the following workaround, which made use of the fact that the RStudio Server was set up so I had a home directory (~) which, while not visible to Windows, I could save things in and navigate to and from in the R environment. So my approach was:
- copy all the files I need from the
report-1project sub-folder to my home directory ~ - change working directory to ~ and render the stand-alone HTML there
- copy the HTML file back to the original
report-1sub-folder, clean up the home directory, and return to the project root directory
This is all done in the function build_doc(), which is one of the assets created at the beginning of the project:
If you find that useful you can actually get it from my nascent pssmisc R package where I’m putting odds and pieces like this:
Approximating corporate style in HTML
Setting up the document
A few things I wanted in this situation I need to set up in the YAML front matter of the .Rmd file:
Bullet List R Markdown
- a stand-alone HTML document
- a dynamic and floating table of contents on the left of the screen
- syntax highlighting that works with SQL (not used in my demo project, but my real one at work had to do this)
- incorporate cascading style sheets w
Bulleted List R Markdown
So here’s the first 14 lines of the R Markdown ./report-1/report.Rmd:
R Markdown List Indent
Fonts and headings with CSS
This takes us to the file of Cascading Style Sheet instructions, corp-styles.css, sitting in the same folder as the report (this is probably a weakness to think through - better to have it in a central location somewhere). I’m no CSS expert but this is simple enough. I worked out the correct colours of headings and their sizes from the corporate Word templates, and converted them from point sizes to the percentage size relative to normal text. Colours and fonts in the below have been made up for this example:
In my real world example I had some other things in there too, such as table formatting.
Adding a logo
As well as the headings and the body, notice the definition of the style of the .title class. This is the one-off element that is the title of the whole report. I give it a wide right margin of 200 pixels so there is room for my hideous made-up corporate logo in the top right. That logo is in the main report.Rmd file with the code:
…and obviously the file logo.svg is in the same folder as the report.
Adding a watermark
I wanted a watermark saying “DRAFT” in pale letters that would always be visible for readers. This worked quite well and was fairly simple. I just needed to include the single line below in my main report.Rmd, creating a div of class “watermark”. The CSS to force objects of this class be fixed in the middle of the page, large in size and opaque is in the .watermark {..} code in the corp-styles.css file already shown.
Graphics
The final thing to mention is the styling of the graphics produced by R itself. This is defined in the file corp-palette.R, already mentioned, which is run at the beginning of the project. It creates an object corp_palette to hold my hypothetical corporate colours for statistical graphics, and makes them the default discrete colour scale for ggplot2. It also sets an appropriate theme and font, and makes the font the default for the text geom.
That means I don’t need to specify the colours and fonts for individual charts in my R Markdown file.
End result
Enjoy:
- built R Markdown -> HTML report with correct fonts, colours (headings and graphs), logo and draft watermark