---
title: 'R Notebook'
output: pdf_document
bibliography: myCitations.bib
---

# 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](https://hub.stenci.la/stencila/reference-r-markdown/files/), 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.

[![Photo by Valentin Petkov](./redPandas.png)](https://unsplash.com/photos/loL9nnBK-fE)

---

## 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:

```{r}
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:

```{r}
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:

```{r fig.cap="My figure"}
plot(randoms)
```

#### Longer captions

The above method is OK for short captions, but when you have longer captions you will probably want to use
[Bookdown](https://bookdown.org/home/) style text references e.g.

```{r fig.cap="(ref:figure3)"}
plot(randoms)
```

(ref:figure3) This is a slightly longer caption for my figure including some **strong** emphasis.

#### 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.

chunk: Figure 3
:::

#### The title of my plot

A paragraph for my figure including some **strong** emphasis.

```{r}
plot(randoms)
```

:::
{#fig3}

---

## 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: `r 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](#fig3).

### Syntax

````md
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](http://www.bibtex.org) 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](http://help.stenci.la/en/articles/4330629-project-settings#theme).

### Example

> _Twenty Thousand Leagues Under the Seas_ (@julesverne1870) 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](#julesverne1870) is a great read.

---

## Feedback welcome

This document is continuously being refined based on your feedback, so please reach out to us at
[hello@stenci.la](mailto:hello@stenci.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!