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.
bookdown. This package is written by Yihui Xie, who also created
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").
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.
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.