<html lang="en"> <head> <title>R Notebook</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> <link href="https://unpkg.com/@stencila/thema@2/dist/themes/stencila/styles.css" rel="stylesheet"> <script src="https://unpkg.com/@stencila/thema@2/dist/themes/stencila/index.js" type="text/javascript"></script> <script src="https://unpkg.com/@stencila/components@<=1/dist/stencila-components/stencila-components.esm.js" type="module"></script> <script src="https://unpkg.com/@stencila/components@<=1/dist/stencila-components/stencila-components.js" type="text/javascript" nomodule=""></script> </head> <body> <main role="main"> <article itemscope="" itemtype="http://schema.org/Article" data-itemscope="root"> <h1 itemprop="headline">R Notebook</h1> <meta itemprop="image" content="https://via.placeholder.com/1200x714/dbdbdb/4a4a4a.png?text=R%20Notebook"><span itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher"> <meta itemprop="name" content="Unknown"><span itemscope="" itemtype="http://schema.org/ImageObject" itemprop="logo"> <meta itemprop="url" content="https://via.placeholder.com/600x60/dbdbdb/4a4a4a.png?text=Unknown"> </span> </span> <h2 itemscope="" itemtype="http://schema.stenci.la/Heading" id="introduction">Introduction </h2> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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 <a href="https://hub.stenci.la/stencila/reference-r-markdown/files/" itemscope="" itemtype="http://schema.stenci.la/Link">raw RMd file</a>, and not the converted HTML file.</p> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">If you’re looking for material on how to use R Markdown for reproducible research, we recommend starting with the following links:</p> <ul itemscope="" itemtype="http://schema.org/ItemList"> <li itemscope="" itemtype="http://schema.org/ListItem" itemprop="itemListElement"> <meta itemprop="position" content="1"> <meta itemprop="url" content="#1">Chris Hartgerink (2017) <em itemscope="" itemtype="http://schema.stenci.la/Emphasis">Composing reproducible manuscripts using R Markdown</em> <a href="https://elifesciences.org/labs/cad57bcf/composing-reproducible-manuscripts-using-r-markdown" itemscope="" itemtype="http://schema.stenci.la/Link">https://elifesciences.org/labs/cad57bcf/composing-reproducible-manuscripts-using-r-markdown</a> </li> <li itemscope="" itemtype="http://schema.org/ListItem" itemprop="itemListElement"> <meta itemprop="position" content="2"> <meta itemprop="url" content="#2">Daniel Nüst, Vicky Steeves, Rémi Rampin, Markus Konkol, Edzer Pebesma (2018)<em itemscope="" itemtype="http://schema.stenci.la/Emphasis">Writing reprocible geoscience papers using R Markdown, Docker, and GitLab</em> <a href="https://vickysteeves.gitlab.io/repro-papers/index.html" itemscope="" itemtype="http://schema.stenci.la/Link">https://vickysteeves.gitlab.io/repro-papers/index.html</a> </li> <li itemscope="" itemtype="http://schema.org/ListItem" itemprop="itemListElement"> <meta itemprop="position" content="3"> <meta itemprop="url" content="#3">Paul Bauer (2018) <em itemscope="" itemtype="http://schema.stenci.la/Emphasis">Writing a Reproducible Paper in R Markdown</em> <a href="https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3175518" itemscope="" itemtype="http://schema.stenci.la/Link">https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3175518</a> </li> </ul> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="project-assets">Project Assets</h3> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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.</p> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph"><a href="https://unsplash.com/photos/loL9nnBK-fE" itemscope="" itemtype="http://schema.stenci.la/Link"><img src="index.html.media/redPandas.png" alt="Photo by Valentin Petkov" itemscope="" itemtype="http://schema.org/ImageObject"></a></p> <hr itemscope="" itemtype="http://schema.stenci.la/ThematicBreak"> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="code-chunks">Code chunks </h3> <h4 itemscope="" itemtype="http://schema.stenci.la/Heading" id="the-basics">The basics</h4> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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 <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">randoms</code> which will be an array of 1000 random numbers sampled from a normal distribution:</p> <stencila-code-chunk itemscope="" itemtype="http://schema.stenci.la/CodeChunk" data-programminglanguage="r"> <pre class="language-r" itemscope="" itemtype="http://schema.stenci.la/CodeBlock" slot="text"><code>randoms <- rnorm(1000)</code></pre> </stencila-code-chunk> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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 <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">randoms</code> variable earlier:</p> <stencila-code-chunk itemscope="" itemtype="http://schema.stenci.la/CodeChunk" data-programminglanguage="r"> <pre class="language-r" itemscope="" itemtype="http://schema.stenci.la/CodeBlock" slot="text"><code>hist(randoms, breaks=30, col="grey", main="")</code></pre> </stencila-code-chunk> <h4 itemscope="" itemtype="http://schema.stenci.la/Heading" id="adding-figure-and-table-captions">Adding figure and table captions</h4> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">R Markdown allows you to specify "options" for code chunks. One such option is <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">fig.cap</code> which allows you to specify a figure caption:</p> <figure itemscope="" itemtype="http://schema.stenci.la/Figure"> <stencila-code-chunk itemscope="" itemtype="http://schema.stenci.la/CodeChunk" data-programminglanguage="r"> <pre class="language-r" itemscope="" itemtype="http://schema.stenci.la/CodeBlock" slot="text"><code>plot(randoms)</code></pre> </stencila-code-chunk> <figcaption> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">My figure</p> </figcaption> </figure> <h5 itemscope="" itemtype="http://schema.stenci.la/Heading" id="longer-captions">Longer captions</h5> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">The above method is OK for short captions, but when you have longer captions you will probably want to use <a href="https://bookdown.org/home/" itemscope="" itemtype="http://schema.stenci.la/Link">Bookdown</a> style text references e.g.</p> <stencila-code-chunk itemscope="" itemtype="http://schema.stenci.la/CodeChunk" data-programminglanguage="r"> <pre class="language-r" itemscope="" itemtype="http://schema.stenci.la/CodeBlock" slot="text"><code>plot(randoms)</code></pre> </stencila-code-chunk> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">(ref:figure3) This is a slightly longer caption for my figure including some <strong itemscope="" itemtype="http://schema.stenci.la/Strong">strong</strong> emphasis.</p> <h5 itemscope="" itemtype="http://schema.stenci.la/Heading" id="complex-captions">Complex captions</h5> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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.</p> <figure itemscope="" itemtype="http://schema.stenci.la/Figure" id="fig3" title="Figure 3"> <label data-itemprop="label">Figure 3</label> <stencila-code-chunk itemscope="" itemtype="http://schema.stenci.la/CodeChunk" data-programminglanguage="r"> <pre class="language-r" itemscope="" itemtype="http://schema.stenci.la/CodeBlock" slot="text"><code>plot(randoms)</code></pre> </stencila-code-chunk> <figcaption> <h5 itemscope="" itemtype="http://schema.stenci.la/Heading" id="the-title-of-my-plot"> The title of my plot</h5> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">A paragraph for my figure including some <strong itemscope="" itemtype="http://schema.stenci.la/Strong">strong</strong> emphasis.</p> </figcaption> </figure> <hr itemscope="" itemtype="http://schema.stenci.la/ThematicBreak"> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="inline-code-chunks">Inline code chunks</h3> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">In R Markdown you can also inline "inline" code chunks within paragraphs and other text content. For example, here is the mean of the <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">randoms</code> variable that we assigned earlier: <stencila-code-expression programming-language="r" itemscope="" itemtype="http://schema.stenci.la/CodeExpression"><code class="r" slot="text">mean(randoms)</code><output slot="output"></output> </stencila-code-expression>.</p> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">In Stencila, we call these <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">CodeExpression</code>s, because they are intended to display a calculated value, and shouldn't be used for statements, such as assigning a variable.</p> <hr itemscope="" itemtype="http://schema.stenci.la/ThematicBreak"> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="references">References</h3> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">When creating Code Chunks, you can assign them an identifier which can be used as a reference from other places. For example <a href="#fig3" itemscope="" itemtype="http://schema.stenci.la/Link">this links to the code chunk above</a>.</p> <h4 itemscope="" itemtype="http://schema.stenci.la/Heading" id="syntax">Syntax</h4> <pre class="language-md" itemscope="" itemtype="http://schema.stenci.la/CodeBlock"><code>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</code></pre> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="citations">Citations</h3> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">Stencila automatically parses a <a href="http://www.bibtex.org" itemscope="" itemtype="http://schema.stenci.la/Link">BibTeX</a> file if one is set under the <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">bibliography</code> key in the file's front-matter. The references will be automatically parsed and appended at the end of the document under a <em itemscope="" itemtype="http://schema.stenci.la/Emphasis">References</em> heading.</p> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">You can refer to items in the bibliography file be prefixing the item's identifier with an <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">@</code> symbol. This will automatically create a formatted citation. The citation style can vary depending on the output file format, as well as your <a href="http://help.stenci.la/en/articles/4330629-project-settings#theme" itemscope="" itemtype="http://schema.stenci.la/Link">chosen theme</a>.</p> <h4 itemscope="" itemtype="http://schema.stenci.la/Heading" id="example">Example</h4> <blockquote itemscope="" itemtype="http://schema.stenci.la/QuoteBlock"> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph"><em itemscope="" itemtype="http://schema.stenci.la/Emphasis">Twenty Thousand Leagues Under the Seas</em> (<cite itemscope="" itemtype="http://schema.stenci.la/Cite"><a href="#julesverne1870"><span>2</span><span>Verne, 1870</span></a></cite>) is a great read.</p> </blockquote> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">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 <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">#</code> symbol instead of a <code itemscope="" itemtype="http://schema.stenci.la/CodeFragment">@</code>.</p> <blockquote itemscope="" itemtype="http://schema.stenci.la/QuoteBlock"> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph"><a href="#julesverne1870" itemscope="" itemtype="http://schema.stenci.la/Link"><em itemscope="" itemtype="http://schema.stenci.la/Emphasis">Twenty Thousand Leagues Under the Seas</em> by Jules Verne</a> is a great read.</p> </blockquote> <hr itemscope="" itemtype="http://schema.stenci.la/ThematicBreak"> <h3 itemscope="" itemtype="http://schema.stenci.la/Heading" id="feedback-welcome">Feedback welcome</h3> <p itemscope="" itemtype="http://schema.stenci.la/Paragraph">This document is continuously being refined based on your feedback, so please reach out to us at <a href="mailto:hello@stenci.la" itemscope="" itemtype="http://schema.stenci.la/Link">hello<cite itemscope="" itemtype="http://schema.stenci.la/Cite"><a href="#stenci">stenci</a></cite>.la</a> 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!</p> <section data-itemprop="references"> <h2 data-itemtype="http://schema.stenci.la/Heading">References</h2> <ol> <li itemscope="" itemtype="http://schema.org/CreativeWork" itemprop="citation" id="RMD-Guide"> <ol data-itemprop="authors"> <li itemscope="" itemtype="http://schema.org/Person" itemprop="author"> <meta itemprop="name" content="Stencila"><span data-itemprop="familyNames"><span itemprop="familyName">Stencila</span></span> </li> </ol><time itemprop="datePublished" datetime="2021">2021</time><span itemprop="headline">R Markdown: Authoring executable documents with R Markdown</span><span itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher"> <meta itemprop="name" content="Unknown"><span itemscope="" itemtype="http://schema.org/ImageObject" itemprop="logo"> <meta itemprop="url" content="https://via.placeholder.com/600x60/dbdbdb/4a4a4a.png?text=Unknown"> </span> </span> </li> <li itemscope="" itemtype="http://schema.org/CreativeWork" itemprop="citation" id="julesverne1870"> <ol data-itemprop="authors"> <li itemscope="" itemtype="http://schema.org/Person" itemprop="author"> <meta itemprop="name" content="Jules Verne"><span data-itemprop="givenNames"><span itemprop="givenName">Jules</span></span><span data-itemprop="familyNames"><span itemprop="familyName">Verne</span></span> </li> </ol><time itemprop="datePublished" datetime="1870">1870</time><span itemprop="headline">Twenty Thousand Leagues Under the Seas</span><span itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher"><span itemprop="name">Pierre-Jules Hetzel</span><span itemscope="" itemtype="http://schema.org/ImageObject" itemprop="logo"> <meta itemprop="url" content="https://via.placeholder.com/600x60/dbdbdb/4a4a4a.png?text=Pierre-Jules%20Hetzel"> </span></span> </li> <li itemscope="" itemtype="http://schema.org/CreativeWork" itemprop="citation" id="bibtex-editor"> <ol data-itemprop="authors"></ol><span itemprop="headline">BibTeX Editor</span><span itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher"> <meta itemprop="name" content="Unknown"><span itemscope="" itemtype="http://schema.org/ImageObject" itemprop="logo"> <meta itemprop="url" content="https://via.placeholder.com/600x60/dbdbdb/4a4a4a.png?text=Unknown"> </span> </span> </li> </ol> </section> </article> </main> </body> </html>