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

    plot(randoms)

My figure

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

    plot(randoms)

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.

Figure 3

    plot(randoms)

##### The title of my plot

A paragraph for my figure including some strong emphasis.

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

1. 1. Stencila
   2021 R Markdown: Authoring executable documents with R Markdown
2. 1. Jules Verne
   1870 Twenty Thousand Leagues Under the Seas Pierre-Jules Hetzel
3. BibTeX Editor