Bookdown – Authoring Books and Technical Documents with R Markdown

Bookdown – Authoring Books and Technical Documents with R Markdown
blog.rstudio.org

The benefit of RMarkdown publications is that they contain the code to reproduce every single step in the argument - as far as it is based on data.

Examples from me, made for a course on Coursera some time ago (so especially in the 2nd example the focus wasn't on the result, effort for data cleaning was deliberately kept to a minimum):

- https://rpubs.com/Noseshine/74191

- https://rpubs.com/Noseshine/79343

Every single line of code necessary to produce the graphs and tables and summary statistics is in there. If you get the source RMarkdown file you can run it yourself. The graphics and tables are not images created somewhere else!

Usually you will have the code in an appendix at the very end, but every single thing in the document based on data is calculated using code somewhere in the document itself.

The main target for these kinds of publications are statistics-heavy papers. Usually you just read the conclusions of the authors and some summary statistics but you don't have access a) to the data they used and b) to the methods they used on the data. RMarkdown documents provide b) and (hopefully) an embedded link to a) (in the form of source code that when executed downloads it into your R environment).

The background story is that not infrequently you find studies (in all kinds of statistics-heavy fields from medicine to psychology) where the summary conclusions are based on faulty premises, faulty data collection/selection, faulty statistical methods. If all you have is a LaTeX or Word or whatever (passive) summary document you cannot find any of those problems unless you keep bugging the authors for a copy of their data and their code used to analyse it, which is a lot of work and was too often altogether unsuccessful. So there is a push in science to get people and organizations to publish more than just the summary.

Another advantage: You can produce interactive (online) versions, for example showing a graph where you can change parameters interactively, but show a few static example graphs in the static document version.

As for just the format:

The reason to compete with LaTeX has been given right here on HN a few times when LaTeX was discussed: It is far more difficult and has plenty of bugs and difficulties. A long time ago I wrote my thesis in it and had no major issues, but I don't know why I would want to write anything in it now. Things like RMarkdown are much less flexible - and orders of magnitude easier, both to write and to debug.

As for the competition with Word, text-based formats have the advantage to be easily "processable" using other tools.

It's not too hard to, say, write a Python Markdown extension to do the same using pandas, seaborn and the usual data science tools from the Python universe, but I salute the R folk for getting this done in what appears to be a quite consistent fashion.