-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy path08-knitr.html
176 lines (159 loc) · 9.9 KB
/
08-knitr.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<title>Software Carpentry: R for reproducible scientific analysis</title>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap.css" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap-theme.css" />
<link rel="stylesheet" type="text/css" href="css/swc.css" />
<link rel="alternate" type="application/rss+xml" title="Software Carpentry Blog" href="http://software-carpentry.org/feed.xml"/>
<meta charset="UTF-8" />
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body class="lesson">
<div class="container card">
<div class="banner">
<a href="http://software-carpentry.org" title="Software Carpentry">
<img alt="Software Carpentry banner" src="img/software-carpentry-banner.png" />
</a>
</div>
<article>
<div class="row">
<div class="col-md-10 col-md-offset-1">
<a href="index.html"><h1 class="title">R for reproducible scientific analysis</h1></a>
<h2 class="subtitle">Dynamic reports with knitr</h2>
<section class="objectives panel panel-warning">
<div class="panel-heading">
<h2 id="learning-objectives"><span class="glyphicon glyphicon-certificate"></span>Learning Objectives</h2>
</div>
<div class="panel-body">
<ul>
<li>Learn how to render R Markdown documents. Generate dynamic documents that include text, code, and results.</li>
<li>Control basic formatting using Markdown syntax.</li>
<li>Create, edit, and compile an R Markdown document including code chunks and inline code.</li>
</ul>
</div>
</section>
<h3 id="the-what-and-why-of-r-markdown">The What and Why of R Markdown</h3>
<p>R Markdown is a way to keep our notes, code, and results organized in a single document. It is a great tool for “reproducible research” – the idea that your research output should be easy for others to reproduce. It keeps your writing and results together, so if you collect some new data or change how you clean the data, you just have to re-compile the document and you’re up to date.</p>
<p>An R Markdown file is a plain text file containing content in a simple document markup language called <em>markdown</em> interspersed with R code blocks. R Markdown files can be converted to html, pdf (if you have LaTeX on your machine), or Word files for dissemination. You can write websites in R Markdown, articles that conform to publishing standards, CVs, presentations… People have even written dissertations in RMarkdown. The syntax of the language is designed to be super simple, but you still get high quality output.</p>
<section class="challenge panel panel-success">
<div class="panel-heading">
<h2 id="challenge---render-an-r-markdown-document"><span class="glyphicon glyphicon-pencil"></span>Challenge - Render an R Markdown document</h2>
</div>
<div class="panel-body">
<ul>
<li>Right-click on this <a href="./code/example.Rmd">link</a> to “Save Link As…”</li>
<li>Open <code>example.Rmd</code> in RStudio.</li>
<li>Render the R Markdown document by pressing the “Knit” button at the top of document.</li>
<li>Compare the output (html) file to the input (Rmd) file.</li>
</ul>
</div>
</section>
<h3 id="organization-of-an-r-markdown-document">Organization of an R Markdown Document</h3>
<p>The top of the an Rmd file has some header material in YAML format (enclosed by triple dashes). Some of this (<code>title</code>, <code>author</code>, …) gets displayed in the output header, other parts provide formatting information to the conversion engine.</p>
<p>After the header, there is a mix of plain-text, formatted with markdown syntax, and R code chunks.</p>
<h4 id="markdown-syntax">Markdown Syntax</h4>
<blockquote>
<p>The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. - John Gruber</p>
</blockquote>
<pre><code># A Markdown Example
Paragraphs are separated by a blank line.
This is a new paragraph. Words and phrases can be made _italic_,
__bold__, or `monospace`. Use asterisks to create bullet items:
* Item-A
* Item-B
* Item-C
Enumerated lists look like this:
1. Item-1
2. Item-2
3. Item-3
Here's a code snippet:
```
for (i in 1:10) {
print(i)
}
```
Here's a link to [a website](https://www.google.com/) and images
can be included like so:
## MathJax Support
Inline math is placed between dollar signs: $y = mx + b$. Display
math should get its own line and be put between double dollar
signs:
$$ y = ax^2 + bx + c $$</code></pre>
<p><a href="http://rmarkdown.rstudio.com/authoring_basics.html">This page</a> covers the basics of formatting text in R Markdown.</p>
<section class="challenge panel panel-success">
<div class="panel-heading">
<h2 id="challenge---practice-writing-markdown"><span class="glyphicon glyphicon-pencil"></span>Challenge - Practice writing Markdown</h2>
</div>
<div class="panel-body">
<ul>
<li>In RStudio, create a new R Markdown file.</li>
<li>Write a top level section heading with the content <code>Text formatting</code>.</li>
<li>Under the heading write <code>R Markdown makes writing easy and fun</code>. Make the word <code>easy</code> italic and the word <code>fun</code> bold.</li>
<li>Create another top level section heading with the content <code>Lists are easy</code></li>
<li>Under the heading write a numbered list of your four favorite foods.</li>
</ul>
</div>
</section>
<h4 id="code-chunks-and-inline-code">Code Chunks and Inline Code</h4>
<p>To distinguish R code from text, R Markdown uses three back-ticks followed by <code>{r}</code> to distinguish a “code chunk”. In RStudio, the keyboard shortcut to create a code chunk is command-option-i or control-alt-i. You can set options for how that code chunk renders after the <code>r</code>. For example, <code>echo = FALSE</code> will prevent the code from being displayed, but its output will still be rendered. <code>fig.height = 8</code> will make plots generated in that code chunk 8 inches in height. It is also possible to set the chunk options for the entire document by calling <a href="http://kbroman.org/knitr_knutshell/pages/Rmarkdown.html#global-chunk-options"><code>knitr::opts_chunk$set()</code></a>. Check out the full suite of chunk options in the <a href="http://yihui.name/knitr/options/">knitr documentation</a>.</p>
<p>A code chunk will set off the code and its results in the output document, but you can also print the results of code within a text block by enclosing code like so: <code>`r code-here`</code>.</p>
<pre><code>Below is a code chunk. Rendering the chunk will result in the code
being highlighted for R syntax and the output being included below
the code.
```{r}
1 + 1
```
`r 1 + 1` is inline code. Rendering inline code will replace the
code with the result.
The following code snippet will not be evaluated:
```
1 + 1
```
Similarly, this inline code snippet will not be evaluated: `1 + 1`</code></pre>
<h4 id="r-markdown-documents-are-self-contained">R Markdown Documents are Self-Contained</h4>
<p>Any data or package you use in an R Markdown document must be loaded in that document. <code>knitr</code> will not look in the Environment for data or functions. It is sometimes useful to include a code-chunk at the beginning of your document where you load data and packages and perhaps set <code>knitr</code> options for the whole document. You may or may not want to include this code in the output. If not, you can give it the option <code>include = FALSE</code>.</p>
<section class="challenge panel panel-success">
<div class="panel-heading">
<h2 id="challenge---write-a-new-r-markdown-document-and-render-it"><span class="glyphicon glyphicon-pencil"></span>Challenge - Write a new R Markdown document and render it</h2>
</div>
<div class="panel-body">
<ol style="list-style-type: decimal">
<li>Create a new R Markdown file and save it as life_expectancy.Rmd</li>
<li>Create a plot of life_expectancy versus year. Start simple, when you’re finished with the rest of this challenge, return to this to improve it.</li>
<li>Add a few notes describing what the code does and what the main findings are. Include an in-line calculation of the average life expectancy over the whole dataset.</li>
<li>Knit the document and view the html result.</li>
</ol>
</div>
</section>
<h3 id="further-reading">Further Reading</h3>
<ul>
<li><a href="http://rmarkdown.rstudio.com/lesson-1.html">RStudio’s Lessons on R Markdown</a></li>
<li>RStudio > Help > Cheatsheets > R Markdown Cheat Sheet</li>
<li>RStudio > Help > Markdown Quick Reference</li>
<li><a href="https://daringfireball.net/projects/markdown/syntax">Markdown Syntax</a></li>
<li><a href="http://rmarkdown.rstudio.com/formats.html">R Markdown Output Formats</a></li>
</ul>
</div>
</div>
</article>
<div class="footer">
<a class="label swc-blue-bg" href="http://software-carpentry.org">Software Carpentry</a>
<a class="label swc-blue-bg" href="https://github.com/swcarpentry/lesson-template">Source</a>
<a class="label swc-blue-bg" href="mailto:[email protected]">Contact</a>
<a class="label swc-blue-bg" href="LICENSE.html">License</a>
</div>
</div>
<!-- Javascript placed at the end of the document so the pages load faster -->
<script src="http://software-carpentry.org/v5/js/jquery-1.9.1.min.js"></script>
<script src="css/bootstrap/bootstrap-js/bootstrap.js"></script>
</body>
</html>