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