R Notebook
Introduction
This document is primarily intended to be used as a syntax reference for authoring R Markdown files for sharing reproducible articles on Stencila. Please ensure you’re viewing the raw RMd file, and not the converted HTML file.
If you’re looking for material on how to use R Markdown for reproducible research, we recommend starting with the following links:
- Chris Hartgerink (2017) Composing reproducible manuscripts using R Markdown https://elifesciences.org/labs/cad57bcf/composing-reproducible-manuscripts-using-r-markdown
- Daniel Nüst, Vicky Steeves, Rémi Rampin, Markus Konkol, Edzer Pebesma (2018)Writing reprocible geoscience papers using R Markdown, Docker, and GitLab https://vickysteeves.gitlab.io/repro-papers/index.html
- Paul Bauer (2018) Writing a Reproducible Paper in R Markdown https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3175518
Project Assets
You can refer to any of you project files using relative paths, both as markdown assets such as the photo below, and as data sources inside your code blocks.
Code chunks
The basics
At the heart of R Markdown are
"code chunks". Code chunks can produce outputs, or they can be used to execute
arbitrary R code. For example, here we assign a variable called randoms
which will be an array of
1000 random numbers sampled from a normal distribution:
randoms <- rnorm(1000)
When you assign a variable in a
code chunk you can reuse it in another chunk, later in the document. For example, we can
plot the frequency distribution of the random numbers we assigned to the randoms
variable
earlier:
hist(randoms, breaks=30, col="grey", main="")
Adding figure and table captions
R Markdown allows you to
specify "options" for code chunks. One such option is fig.cap
which allows you to
specify a figure caption:
Longer captions
The above method is OK for short captions, but when you have longer captions you will probably want to use Bookdown style text references e.g.
Complex captions
Bookdown style text references are good for longer, single paragraph captions. However, for more structured captions having a title and paragraph as is often found in academic journals we suggest that you use a code chunk block extension. e.g.
Inline code chunks
In R Markdown you can also
inline "inline" code chunks within paragraphs and other text content. For
example, here is the mean of the randoms
variable that we assigned
earlier: mean(randoms)
In Stencila, we call these
CodeExpression
s,
because they are intended to display a calculated value, and shouldn't be used for
statements, such as assigning a variable.
References
When creating Code Chunks, you can assign them an identifier which can be used as a reference from other places. For example this links to the code chunk above.
Syntax
chunk: Figure Title here
:::
#### This is the caption title
Some descriptive paragraph.
```r
# code goes here
```
:::
{#unique-identifier} # <-- ID to use when referring to this figure
Citations
Stencila automatically parses a
BibTeX file if one is set under the bibliography
key in
the file's front-matter. The references will be automatically parsed and appended at
the end of the document under a References heading.
You can refer to items in the
bibliography file be prefixing the item's identifier with an @
symbol. This will automatically
create a formatted citation. The citation style can vary depending on the output file
format, as well as your chosen theme.
Example
Twenty Thousand Leagues Under the Seas (Verne, 1870) is a great read.
However if you don’t want to
create a formal inline citation, and simply link to the References section at the end of
the document, you can use the same reference identifier but use a #
symbol instead of a @
.
Twenty Thousand Leagues Under the Seas by Jules Verne is a great read.
Feedback welcome
This document is continuously being refined based on your feedback, so please reach out to us at hellostenci.la if you have questions or suggestions, would like to see a section added to this document, or if you find something unclear. We’d love to hear from you!
References
-
- Stencila
-
- JulesVerne
-