Radix for R Markdown

Scientific and technical writing, native to the web

JJ Allaire https://github.com/jjallaire (RStudio)https://www.rstudio.com , Rich Iannone https://github.com/rich-iannone (RStudio)https://www.rstudio.com , Yihui Xie https://github.com/yihui (RStudio)https://www.rstudio.com
May 4, 2018

Radix is an online publication format designed for scientific and technical communication. Radix articles include:

Radix is based on the Distill web framework, which was originally created for use in the Distill Machine Learning Journal (Carter, Olah, and Satyanarayan 2016). Radix combines the technical authoring features of Distill with R Markdown, enabling a fully reproducible workflow based on literate programming (Knuth 1984).

Getting Started

Installation

To create an R Markdown document that uses the Radix format, first install the radix R package:


devtools::install_github("rstudio/radix")

Using Radix requires Pandoc v2.0 or higher. If you are using RStudio then you should use RStudio v1.2.718 or higher (which comes bundled with Pandoc v2.0).

You can download the daily build of RStudio v1.2 at https://dailies.rstudio.com/.

Creating an article

Use the New R Markdown dialog within RStudio to create a new Radix article:

You can also create a new Radix article from the command line with:


library(rmarkdown)
draft("article.Rmd", "radix_article", package = "radix")

Radix articles use radix::radix_article as their output format, and typically include title, description, date, author/affiliation, and bibliography entries in their YAML front-matter:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
date: May 4, 2018
author:
  - name: "JJ Allaire"
    url: https://github.com/jjallaire
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
  - name: "Rich Iannone"
    url: https://github.com/rich-iannone
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
  - name: "Yihui Xie"
    url: https://github.com/yihui
    affiliation: RStudio
    affiliation_url: https://www.rstudio.com
bibliography: biblio.bib
output: radix::radix_article
---

Author entries must have at least name and url specified (the affiliation fields are optional). The date field should be formatted as month, day, year (various notations are supported as long as the components appear in that order).

The article’s description and author bylines are automatically rendered as part of the title area of the document.

The bibliography field is used to provide a reference to the Bibtex file where all of the sources cited in your article are defined. The citations section describes how to include references to these sources in your article.

Figures

Radix provides a number of options for laying out figures within your article. By default figures span the width of the main article body:

However, some figures benefit from using additional horizontal space. In this cases the layout chunk option enables you to specify a wide variety of other layouts.

For example, if we wanted to display a figure a bit outside the bounds of the article text, we could specify the l-body-outset layout via the layout chunk option:


```{r, layout="l-body-outset", fig.width=6, fig.height=1.5}
library(ggplot2)
ggplot(diamonds, aes(carat, price)) + geom_smooth() +
  facet_grid(~ cut)
```

Note that when specifying an alternate layout you should also specify an appropriate fig.width and fig.height for that layout. These values don’t determine the absolute size of the figure (that’s dynamic based on the layout) but they do determine the aspect ratio of the figure.

See the documentation on figure layout for details on additional layout options.

The examples above are based on conventional R plots. Radix articles can also incorporate diagrams and interactive visualizations based on JavaScript and D3.

Tables

There are a number of options available for HTML display of data frames within Radix articles. Here, we use the paged_table() function to display a page-able view of the mtcars dataset built in to R:


```{r, layout="l-body-outset"}
library(rmarkdown)
paged_table(mtcars)
```

Note that we used layout="l-body-outset" to cause the table to occupy slightly more horizontal space than the article text. All of available figure layout options work as expected for tables.

See the documentation on table display for details on the various techniques available for rendering tables.

Equations

Inline and display equations are supported via standard markdown MathJax syntax. For example, the following LaTeX math:


$$
\sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2}
$$

Will be rendered as:

\[ \sigma = \sqrt{ \frac{1}{N} \sum_{i=1}^N (x_i -\mu)^2} \]

Citations

Bibtex is the supported way of making academic citations. To include citations, first create a bibtex file and refer to it from the bibliography field of the YAML front-matter (as illustrated above).

For example, your bibliography file might contain:


@Book{xie2015,
  title = {Dynamic Documents with R and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {http://yihui.name/knitr/},
}

Citations are then used in the article body with standard R Markdown notation, for example: [@xie2015] (which references an id provided in the bibliography). Note that multiple ids (separated by semicolons) can be provided.

The citation is presented inline like this: (Xie 2015) (a number that displays more information on hover). If you have an appendix, a bibliography is automatically created and populated in it.

See the article on citations for additional details on using citations, including how to provide the metadata required to make your article more easily citable for others.

Footnotes and asides

Footnotes use standard Pandoc markdown notation, for example ^[This will become a hover-able footnote]. The number of the footnote will be automatically generated.1

You can also optionally include notes in the gutter of the article (immediately to the right of the article text). To do this use the <aside> tag.


<aside>
This content will appear in the gutter of the article.
</aside>

You can also include figures in the gutter. Just enclose the code chunk which generates the figure in an <aside> tag:


<aside>
```{r}
ggplot(mtcars, aes(hp, mpg)) + geom_point() + geom_smooth()
```
</aside>

Code blocks

Syntax highlighting is provided for knitr code chunks. Note that by default the Radix format does not display the code for chunks that are evaluated to produce output (knitr option echo = FALSE).

The echo = FALSE default reflects the fact that Radix articles are often used to present the results of analyses rather than the underlying code. To display the code that was evaluated to produce output you can set the echo chunk option to TRUE:


```{r, echo=TRUE}
1 + 1
```

To include code that is only displayed and not evaluated specify the eval=FALSE option:


```{r, eval=FALSE, echo=TRUE}
1 + 1
```

There are a number of default values that Radix establishes for knitr chunk options (these defaults also reflect the use case of presenting results/output rather than underlying code):

Option Value Comment
echo FALSE Don’t print code by default.
warning FALSE Don’t print warnings by default.
message FALSE Don’t print R messages by default.
comment NA Don’t preface R output with a comment.
R.options list(width = 70) 70 character wide console output.

Keeping R code and output at 70 characters wide (or less) is recommended for readability on a variety of devices and screen sizes.

As illustrated above, all of these defaults can be overridden on a chunk-by-chunk basis by specifying chunk options.

You can also change the global defaults using a setup chunk. For example:


```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  warning = TRUE,
  message = TRUE,
  comment = "##",
  R.options = list(width = 60)
)
```

Appendices

Appendices can be added after your article by adding the .appendix class to any level 1 or level 2 header. For example:


## Acknowledgments {.appendix}

This is a place to recognize people and institutions. It may also be a good place
to acknowledge and cite software that makes your work possible.

## Author Contributions {.appendix}

We strongly encourage you to include an author contributions statement briefly 
describing what each author did.

Footnotes and references will be included in the same section, immediately beneath any custom appendices.

Why Radix?

Why the name Radix? The most common definition of radix in the English language comes from Mathematics, where it is used to describe the base of a system of numeration. It is also used to describe the source or origin of something. Both of these usages derive from the Latin meaning of radix, which is literally root.

The purpose of scientific communication is to help get to the root of things! Radix provides a set of tools to facilitate clear scientific communication that links richly with other sources of knowledge and insight.

Acknowledgments

Radix builds on the work of many individuals and projects. Shan Carter, Ludwig Schubert, and Christopher Olah created the Distill web framework. John MacFarlane created the Pandoc universal markup converter. Davide Cervone and Volker Sorge created the MathJax library for rendering mathematical notation on the web. Mike Bostock created the D3 library for producing dynamic, interactive data visualizations for the web. We are grateful for the spirit of generosity that moved these individuals to create high-quality open source software for the benefit of all.

Carter, Shan, Chirs Olah, and Arvind Satyanarayan. 2016. “Distill.” Distill Working Group. https://doi.org/10.23915/distill.

Knuth, Donald E. 1984. “Literate Programming.” The Computer Journal 27 (2). British Computer Society: 97–111.

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. http://yihui.name/knitr/.


  1. This will become a hover-able footnote

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/radixpub/radix-r, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

Allaire, et al. (2018, May 4). Radix for R Markdown. Retrieved from https://radixpub.github.io/radix-r

BibTeX citation

@misc{allaire2018radix,
  author = {Allaire, JJ and Iannone, Rich and Xie, Yihui},
  title = {Radix for R Markdown},
  url = {https://radixpub.github.io/radix-r},
  year = {2018}
}