Table of Contents
The landscape of journal publications have long changed from its initial stages where journals were disseminated in hard-copy paper format. Now almost all journals would store and disseminate their articles online. New publication framework, such as arXiv and F1000Research, that accelerate dissemination by forgoing formal review process has emerged. These framework gave rise a new era of formal information sharing, however, there is still scope for middle-ground that allow less formal articles. Scientific and technical blogging based on R Markdown(J. Allaire et al. 2018; Xie, Allaire, and Grolemund 2018) documents have a huge potential to fill this gap as well as encourage the general community to adopt good scientific practices, i.e. open science and reproducibility.
This article firstly touches briefly on why you make like to make scientific or technical articles with R Markdown based tools. The article then describes radix(J. Allaire, Iannone, and Xie 2018) and blogdown(Xie, Hill, and Thomas 2017) R packages for blogging using R Markdown documents with comparisons between the two packages.
Why scientific or technical blog?
The line where a blog constitutes to be a scientific or technical blog is not clear, however, there are some blogs that provide large benefits to the scientific community. These could be blogs about technical use or tutorial of software which may not warrant a full-fledged academic article. I have personally benefited from many scientific and technical blogs.
Another benefit to blogging is that the author has control of the writing style. Scientific or technical articles usually call for formality while blogging is free from such obligation and allow the author to relax to his/her own style of writing. I particularly like authors that display a blend of humour or personal thoughts and experience that makes reading their blogs entertaining for me.
There is of course a downside to allowing anyone to blog in any style they like. Quality control. It is not hard for some people to make outrangeous scientific claims without any evidence. This of course doesn’t stop happening even with a rigorous scientific process (e.g. the well known case of the fradulent paper alluding that the vaccine causes autism). This is more of a lesson perhaps that it is important that each individuals train themselves with critical thinking.
Why R Markdown?
R Markdown, described briefly, allows you to use a simple syntax to seamlessly embed code and its output into documents. Contrary to the name, the code does not have to be R(R: A Language and Environment for Statistical Computing 2018) but support varying languages such as python, go, C and even SAS. For the full list see here.
R Markdown documents consist of all codes with the ability to easily hide the code (contained in the so-called chunks) for the desired output. The simplicity yet flexibility to customise makes R Markdown a powerful tool that makes it easy for users to adopt reproducible research and literate programming(Knuth 1984).
R Markdown is written by the team of software enginners in RStudio(J. Allaire et al. 2018) who have shown commitment to open source projects and work in a company that appears to have a viable business model. These two points as well as large community usage (shown by the increasing popularity in Figure 1) give some assurance to me that there will be a long term commitment to maintaining the R Markdown based R packages.
Figure 1: The data is taken for a 5 year period 2013-12-22 to 2018-12-16 from google trends on search for term “rmarkdown”. Interest represent worldwide search interest relative to the highest point on the chart over the 5 year period. A value of 100 is the peak popularity for the term. A value of 50 means that the term is half as popular. A score of 0 means there was not enough data for this term. The upward trend in the graph implies that R Markdown is gaining popularity.
Radix or Blogdown?
A brief description of radix and blogdown are shown later. Table 1 shows a comparison of features between radix and blogdown.
A key selling point for me to use radix was the metadata automatically generated that allows easier indexing for Google Scholar and automatic article citation generation. As a researcher, we are often required to show impact of our work for grant or promotion applications. This can be difficult to measure for a web post and consequently, a well-received and useful scientific or technical post do not even get the same recognition as a journal article that have contributed less to the scientific discussion or community. By making posts easily citable, I would hope that more recognition is given to web posts that have been helpful for scientific research and it would encourage more individuals to contribute positively to the scientific discussion.
Another point that radix made it easy for beautiful and elegant writing is the ability to write side comments and customise figure layouts to stretch beyond the post margins. This is doable in blogdown as well, however, it requires work for almost all themes.
It should be stressed that blogdown is used to create a more general purpose website and it is possible to incorporate all features of radix within the blogdown framework. To implement this requires time and effort so most will find it easier to just use radix for certain purposes. This may change in future though if someone capable can introduce it as a Hugo theme.
| Feature | radix | blogdown |
|---|---|---|
| Github Repo Creation Date | 2018-04-23 | 2016-11-02 |
| R Markdown | ✔ | ✔ |
| For general purpose blogging | ||
| Many themes available | ✘ | ✔ |
| Adding date and author for posts | ✔ | ✔ for most theme. |
| Easy structure customisation | ✘ | ✔ depending on the theme. |
| Adapts to different screens | ✔ | ✔ for most theme. |
| For scientific/technical writing | ||
| BibTeX citation easily works | ✔ | ✘ |
| Adding affiliation | ✔ | ✘ easy to add but some fiddling needed for almost all theme. |
| Customise figure layout | ✔ | ✘ fiddly if going over post margin. |
| Side comments (Tufte style) | ✔ | ✘ |
| Popup notes easily works | ✔ | ✘ works with some fiddling. |
| Metadata for Google Scholar | ✔ | ✘ can be added with some work. |
| LaTeX easily works | ✔ | ✔ |
| Cross-reference | ✔ | ✔ |
| Author | ||
| JJ Allaire | ✔ | ✘ |
| Rich Iannone | ✔ | ✘ |
| Yihui Xie | ✔ | ✔ |
Radix
radix is a new R package, that is based on the Distill web framework(Carter, Olah, and Satyanarayan 2016) to bring scientific or technical writing using R Markdown that is native to the web. The Distill web framework is used in the Distill Research Journal which publishes research on machine learning. More details about radix are well explained here. The radix framework is shown as a chart in Figure 2.
Figure 2: Radix Framework in a Chart
Blogdown
blogdown is an R package that uses Hugo in the backend to generate the website. blogdown also can use Jekyll or Hexo as the generator in place of Hugo however some features are only supported in Hugo. While the package name signifies that the primary motivation is for blogging, blogdown is not limited to blogs and is flexible to create any website. Details about the blogdown package is best explained in the book by Xie et al. (2017)(Xie, Hill, and Thomas 2017). The blogdown framework is shown as a chart in Figure 3.
Figure 3: blogdown Hugo Framework in a Chart. Note that blogdown can use other generators such as Jekyll and Hexo in place of Hugo.
Conclusion
With an explicit (but optional) entry for affiliation in radix, users are consciously reminded that their blog posts may also reflect upon their affiliation’s reputation and approach their writing with more seriousness and formality. Additionally, radix is built with scientific and technical writing in mind, thus, the format is more rigid, allowing for more consistency, and have a default set up and features convenient for this purpose (e.g. echo=FALSE as default for the chunks and side comments, etc). These features reduce the friction for the user to produce a beautiful scientific or technical web article.
It is possible to create a Hugo theme that mimics the radix output therefore there is no reason the more general purpose blogdown cannot be used for scientific or technical writing to achieve a similar output as radix. Of course this requires someone to create the theme and there isn’t a closing matching theme at the moment.
R Markdown documents are usually used to populate the content for websites generated from both radix and blogdown therefore it would be easy to transition between the two packages albeit requiring some work. Perhaps one day someone will write an article on how to achieve this with minimal work.
So radix or blogdown? This is ultimately up to you. One thing I’m sure is that writing articles using R Markdown documents has aided greatly in my scientific writing.
This article is an accompaniment of the Software Corner of the Biometric Bulletin (to appear). You can see the blogdown remix of this blog here.
Acknowledgments
This article is written using radix(J. Allaire, Iannone, and Xie 2018) using RStudio IDE and statistical computing tool R(R: A Language and Environment for Statistical Computing 2018). The charts are generated using DiagrammeR(Iannone 2018) and the graph using ggplot2(Wickham 2016).
Reuse
Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/emitanaka/r/_posts.
Corrections
If you see mistakes or want to suggest changes, please create an issue on the source repository. The author citation for R(R: A Language and Environment for Statistical Computing 2018) is not a mistake but waiting on a fix for bibliography parsing in the Distill framework.
Allaire, JJ, Rich Iannone, and Yihui Xie. 2018. Radix: ’R Markdown’ Format for Scientific and Technical Writing. https://github.com/rstudio/radix.
Allaire, JJ, Yihui Xie, Jonathan McPherson, Javier Luraschi, Kevin Ushey, Aron Atkins, Hadley Wickham, Joe Cheng, Winston Chang, and Richard Iannone. 2018. Rmarkdown: Dynamic Documents for R. https://rmarkdown.rstudio.com.
Carter, Shan, Chirs Olah, and Arvind Satyanarayan. 2016. “Distill.” Distill Working Group. https://doi.org/10.23915/distill.
Iannone, Richard. 2018. DiagrammeR: Graph/Network Visualization. https://CRAN.R-project.org/package=DiagrammeR.
Knuth, Donald E. 1984. “Literate Programming.” The Computer Journal 27 (2). British Computer Society: 97–111.
R: A Language and Environment for Statistical Computing. 2018. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.
Wickham, Hadley. 2016. Ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. http://ggplot2.org.
Xie, Yihui, J.J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.
Xie, Yihui, Alison Presmanes Hill, and Amber Thomas. 2017. Blogdown: Creating Websites with R Markdown. Boca Raton, Florida: Chapman; Hall/CRC. https://github.com/rstudio/blogdown.