This is a quick introduction to using R, the R package `knitr`, and the markdown language to automatically generate monthly reports.
The Book “R for Data Science” by Hadley Wickham and Garrett Grolemund (read here) is a great resource too. Read chapter 28 on diagrams here. Pandoc’s user guide has some helpful comments on figures sizing with Pandoc’s markdown. Rstudio and R users in general can benefit from Rmarkdown for producing reproducible reports. R Markdown is an easy-to-write plain text format for creating dynamic documents and reports. TLDR: This tutorial teaches you how to install LaTeX, R and R Markdown on Windows 10. It also guides you through creating your first R Markdown file and shows how to compile it into a PDF file using.
Let’s say I track electricity usage and expenses for a client. I initially spent a lot of time analyzing and making models for the data, but at this point I’m now in more of a maintenance mode and simply want an updated report to email each month. So, when their new electricity bill arrives I scrape the data into R, save the data in an R workspace, and then use knitr to generate a simplistic HTML report.
There are three components to make the report. The first is a language called markdown. It’s meant as a simple language for writing basic text that will be turned into basic formatted HTML. It’s designed to look a lot like what people historically used in emails and online postings before HTML was widely used for that purpose. For example, to make a word italic, you would put asterisks around it *like this*. To make a title, you would type your title, then on the next line you’d “underscore” it with hyphens. To make a bullet list, you’d begin each line with an asterisk. And so on. You run the markdown file through a translator, and out comes HTML.
The second component is the `knitr` R package. It enhances markdown to include the ability to execute R code and to substitute the code, the results of the code, or both, into the output HTML. Inline R is placed within back ticks, like `r sum (1:5)`, while more extensive R code is placed in lines bracketed by triple back ticks, where the first line has “{r ” (no quotes) followed by a chunk name, a comma, and options:
So I could write a simplistic report like:
Where the opts_chunk$set is a knitr call to set default options for chunks, such as whether to display the R code (echo). This markdown code would create an HTML report that looks like:
Which is a reasonable start at a report that could be run automatically and emailed or uploaded to a website.
The last component of the trio is the knitr commands that are used within R to process the markdown file (let’s call the markdown file “knitrReport.Rmd”):
Put the three parts together and you have a dynamically-generated report that can show just the results or can include the R code that was used to generate the results.
Motivation
The cut-and-paste approach to report production is tedious, slow, and error-prone. It can be very harmful to reproducible research and it is inconvenient to reproduce results.
knitr is an R package that integrates computing and reporting. By incorporating code into text documents, the analysis, results and discussion are all in one place. Files can then be processed into a diverse array of document formats, including the important ones for collaborative science: pdfs, Word documents, slide presentations, and web pages.
This is important for reproducible research because you can create reports, papers, presentations in which every table, figure, and inline result is generated by code that is tied to the document itself. It makes life easier when it comes time to make small updates to an analysis, and more importantly, the code becomes more understandable by virtue of being directly related to the text description.
The importance of text
There are many advantages to creating scientific content using simple text documents. For one, they are future-proof. Microsoft and Apple are continually updating their software and document formats. In 5 years I probably won’t be able to easily open a Word document that I created today, and likewise, when a new document format comes out (remember when .docx was new?) it takes a while for it to be widely adopted. It is highly unlikely that text documents will become obsolete. I can still open a text file that I created on my old Apple IIe. Secondly, content tracking tools like git and github work wonderfully with text files. It is dead-easy to view line-by-line changes in a text file.
Knitr Kable R Markdown
Tools like knitr, rmarkdown, and pandoc do the hard work of translating your text files into “production” documents, like beautifully typeset pdfs, smooth presentations, and Word documents that your collaborators can’t live without. Creating the base in a text file allows you to focus on the content and not obsess over the details like formatting and figure placement. This document was created with knitr in markdown. Check out the source code here.