Fast and reproducible reports with bookdown

As data scientists, we spend a lot of time writing documents for clients which communicate the results of our analyses. We used to do our analyses using rmarkdown-style html documents, which can easily mix text and code outputs. Then we took the images in the rmarkdown documents and put them into Microsoft Word, doing all the final formatting in Word.

But this wasn't an ideal way to work. For example, if the data changed slightly, or we wanted to run the analysis under different conditions, it's possible that all the tables and images would change. Then we would have to copy that all into a Word document, which has potential for error (as well as wasting time re-formatting the document).

The solution is to completely produce the document from R. rmarkdown documents almost satisfy this requirement, with the small but important caveat in that it doesn't handle cross-referencing of images, tables, sections, and equations.

Enter bookdown. This package is written by Yihui Xie, who also created rmarkdown. The bookdown package adds the ability to create cross-references within the document. It can also easily integrate multiple files (chapters) into a single document (or "book").

We use bookdown to produce pdf documents. Because bookdown weaves code and report text together, we can easily re-compile the document, and all the numbers and tables will be updated. We don't have to worry about transferring images from rmarkdown to Word, because they are incorporated directly into the document, and we don't have to spend ages formatting the document, because that is done automatically (and nicely) by the LaTeX engine hiding behind everything.

The default aesthetic of a bookdown document is rather plain. However, with some style wrangling of LaTeX template files, we can incorporate custom formatting, such as the company logo in a header.

The title page of a bookdown report can be customised with logos.

In conclusion, using bookdown is very helpful for quickly producing reports, eliminates potential error transferring results from R to Word, and produces professional-quality documents.

The best resource for getting started with bookdown is probably Yihui Xie's book (written with bookdown!), which can be found here. It contains a link to a bookdown demo, which is a useful resource for getting started.