---
title: RMarkdown and Stencila
author:
  - surname: Bentley
    given-names: Nokome
    affiliation: stencila
  - surname: Pawlik
    given-names: Aleksandra
  - surname: Aufrieter
    given-names: Michael
    affiliation: substance
  - surname: Buchtala
    given-names: Oliver
    affiliation: substance
organisations:
  - id: stencila
    name: Stencila
    city: Kaikoura
    country: New Zealand
  - id: substance
    name: Substance GmbH
    city: Linz
    country: Austria
abstract: |
  Stencila currently supports import of RMarkdown documents. This allows use cases like allowing collaborators to work on the same document using a WYSIWYG editing environment, or for you to put the final touches on a paper before final submission to a journal.
bibliography: bibliography.bibtex
---

# Introduction

[RMarkdown](https://rmarkdown.rstudio.com/) is a popular format for reproducible research using the R programming language ([@baumer2014r],[@xie2016bookdown]). Stencila is a able to import RMarkdown documents. For example, the source for this example document is available on [Github](https://github.com/stencila/stencila/blob/more-examples/data/r-markdown/rmarkdown.Rmd). Eventually, we'll also support exporting to RMarkdown, allowing WYSIWYG editing of RMarkdown documents in Stencila.

# Code chunks

In RMarkdown, code "chunks" are written using "fenced" code blocks. Stencila converts these code "chunks" into Stencila code "cells" like this one:

```{r}
n <- 500
```

Stencila cells behave like functions having zero or more named `inputs` (like function arguments) and an optional `output` (like a assigning a function's return value). A cell's inputs and outputs are determined by analyzing the cell's code. The cell above has no inputs but produces an output variable named `n`. Stencila's execution engine uses this information to make code cells reactive. For instance, the cell below has `n` as an input i.e it is dependent on the first cell. So when you update the `n` in the cell above, the following plot will update.

```{r}
s <- min(1000, n)
x <- runif(s)
y <- x + runif(s)
z <- y + rnorm(s)
plot(x, y, cex=z*2, col=rainbow(length(z), alpha=0.5)[rank(x+z)], pch=16)
```

# Figures

In RMarkdown, code chunks can have various options. A common use for options is to set the caption and dimensions of figures. Stencila converts code chunks with the `fig.cap` option into JATS `<fig fig-type="repro-fig">` elements with a `<caption>`. This allows the user to edit the figure caption and for automatic figure numbering and referencing (although that is not working 100% right now). Other options are placed in a comment at the top of the cell so that they are preserved (and eventually will be used to apply those options within the R execution context).

```{r fig.width=7,fig.height=6,fig.cap="Figure title"}
hist(z, breaks=40, col=hsv(0.6, 0.9, 1), xlab="Value", main="")
```