forked from STAT540-UBC/STAT540-UBC-archive
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsm02a_rMarkdown.html
259 lines (235 loc) · 13.4 KB
/
sm02a_rMarkdown.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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />
<title></title>
<script src="libs/jquery-1.11.0/jquery.min.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="libs/bootstrap-3.3.1/css/united.min.css" rel="stylesheet" />
<script src="libs/bootstrap-3.3.1/js/bootstrap.min.js"></script>
<script src="libs/bootstrap-3.3.1/shim/html5shiv.min.js"></script>
<script src="libs/bootstrap-3.3.1/shim/respond.min.js"></script>
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet"
href="libs/highlight/default.css"
type="text/css" />
<script src="libs/highlight/highlight.js"></script>
<style type="text/css">
pre:not([class]) {
background-color: white;
}
</style>
<script type="text/javascript">
if (window.hljs && document.readyState && document.readyState === "complete") {
window.setTimeout(function() {
hljs.initHighlighting();
}, 0);
}
</script>
<link rel="stylesheet" href="libs/local/nav.css" type="text/css" />
</head>
<body>
<style type = "text/css">
.main-container {
max-width: 940px;
margin-left: auto;
margin-right: auto;
}
code {
color: inherit;
background-color: rgba(0, 0, 0, 0.04);
}
img {
max-width:100%;
height: auto;
}
</style>
<div class="container-fluid main-container">
<header>
<div class="nav">
<a class="nav-logo" href="index.html">
<img src="static/img/stat540-logo-s.png" width="70px" height="70px"/>
</a>
<ul>
<li class="home"><a href="index.html">Home</a></li>
<li class="announcements"><a href="announcements.html">Announcements</a></li>
<li class="syllabus"><a href="syllabus.html">Syllabus</a></li>
<li class="lectures"><a href="lectures.html">Lectures</a></li>
<li class="seminars"><a href="seminars.html">Seminars</a></li>
<li class="assignments"><a href="assignments.html">Assignments</a></li>
<li class="people"><a href="people.html">People</a></li>
</ul>
</div>
</header>
<div id="markdown-and-r-markdown" class="section level1">
<h1>Markdown and R Markdown</h1>
<p><strong>This document was first written by Shaun Jackman and has been editted by W. Evan Durno</strong></p>
<p>This is a primer on R Markdown and Markdown and will enable you to construct elegant documents containing R scripts, the results of the R script executions, and formatted text. R Markdown files are easily created and edited in RStudio. Via RStudio, it is very easy to translate R Markdown files into Markdown and HTML files using the <em>knitr</em> package. Markdown and HTML are popular formats. For example, Github renders Markdown files when placed in repositories, and many webpages are renderings of HTML generated by R Markdown. When submitting seminar deliverables via your Github repositories, we would like you to render them using R Markdown.</p>
</div>
<div id="getting-started" class="section level1">
<h1>Getting Started</h1>
<p>Some students may need to install <em>knitr</em>. Open RStudio, and install the <em>knitr</em> package.</p>
<pre class="r"><code>install.packages('knitr')</code></pre>
</div>
<div id="markdown" class="section level1">
<h1>Markdown</h1>
<p>Markdown is a simple plain text markup language for formatting documents. It’s usually rendered to HTML, which is easy to view in a web browser or to publish on the web. It can be rendered to other document formats as well using a tool such as <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a>.</p>
<ul>
<li>GitHub’s <a href="https://help.github.com/articles/markdown-basics">Markdown Basics</a> describes the Markdown format</li>
<li>GitHub has a few extensions to the Markdown syntax, called <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown</a></li>
<li>Daring Fireball, the creator of Markdown, gives a more detailed description of the <a href="http://daringfireball.net/projects/markdown/syntax">Markdown syntax</a></li>
</ul>
<p>Markdown documents have the file extension <em>.md</em>. This is the canonical file extension. <em>Don’t get creative here.</em></p>
<div id="example-markdown-documents" class="section level2">
<h2>Example Markdown documents</h2>
<p>GitHub automatically renders Markdown files with the <em>.md</em> extension. Select <em>Raw</em> to view the raw Markdown.</p>
<ul>
<li><a href="https://github.com/STAT540-UBC/STAT540-UBC.github.io/blob/master/examples/rmdExample/rmdExample.md">An example</a>, including a mathematical formula in LaTeX</li>
<li><a href="https://github.com/STAT540-UBC/STAT540-UBC.github.io/blob/master/sm02a_rMarkdown.md">This document</a></li>
<li>Open RStudio, and select <em>RStudio File > New File > R Markdown</em>. Ignore or delete the chunks of R code, for now.</li>
<li>Find one on the Internet</li>
<li>Write one for yourself!</li>
</ul>
</div>
<div id="rendering-a-markdown-document" class="section level2">
<h2>Rendering a Markdown document</h2>
<div id="rstudio" class="section level3">
<h3>RStudio</h3>
<p>Open a Markdown document in RStudio. Click the <em>Preview</em> button.</p>
<p>Whenever you have a Markdown or R Markdown file open in the editor, the button bar of the editor will have special powers. Click on the question mark <code>?</code> to display the <em>Markdown Quick Reference</em> in the <em>Help</em> panel.</p>
</div>
<div id="r-command-line" class="section level3">
<h3>R command line</h3>
<pre class="r"><code>library(markdown)
markdownToHTML('README.md', 'README.html')</code></pre>
</div>
<div id="shell-command-line" class="section level3">
<h3>Shell command line</h3>
<p>You can run R from the command line and call <em>markdown::markdownToHTML</em>.</p>
<pre class="sh"><code>Rscript -e 'markdown::markdownToHTML("README.md", "README.html")'</code></pre>
<p>Alternatively on Mac OS, install the <em>markdown</em> program using <a href="http://brew.sh">Homebrew</a>.</p>
<pre class="sh"><code>brew install markdown
markdown README.md >README.html</code></pre>
</div>
<div id="mac-os-x" class="section level3">
<h3>Mac OS X</h3>
<p>The <a href="http://mouapp.com/">MOU</a> app shows a live preview of the rendered document while you edit the markdown.</p>
</div>
<div id="web-browser-extension" class="section level3">
<h3>Web browser extension</h3>
<p>With the <a href="http://markdown-here.com/">Markdown Here</a> browser extension, you can write an e-mail (or Google Group posting, etc.) in Markdown and render it before sending the e-mail.</p>
</div>
</div>
</div>
<div id="r-markdown" class="section level1">
<h1>R Markdown</h1>
<p>R Markdown intermingles documentation in Markdown format and chunks of R code in fenced code blocks. When the R Markdown document is <em>knit</em> (that is to say, compiled), the chunks of R code are run, and the results, which can be text or figures, are inserted in the rendered document. R Markdown documents have the file extension <em>.rmd</em>.</p>
<p>RStudio has some nice documentation on R Markdown.</p>
<ul>
<li><a href="http://www.rstudio.com/ide/docs/authoring/using_markdown">Using R Markdown with RStudio</a></li>
<li><a href="http://www.rstudio.com/ide/docs/authoring/using_markdown_equations">Equations in R Markdown</a></li>
</ul>
<div id="example-r-markdown-documents" class="section level2">
<h2>Example R Markdown documents</h2>
<ul>
<li><a href="https://github.com/STAT540-UBC/STAT540-UBC.github.io/blob/master/examples/rmdExample/rmdExample.Rmd">R Markdown example</a></li>
<li>Open RStudio, and select <em>RStudio File > New File > R Markdown</em>.</li>
</ul>
<p>GitHub does not render R Markdown documents automatically, sadly.</p>
</div>
<div id="rendering-a-r-markdown-document" class="section level2">
<h2>Rendering a R Markdown document</h2>
<div id="rstudio-1" class="section level3">
<h3>RStudio</h3>
<p>Open a R Markdown document in RStudio. Click the <em>Knit HTML</em> button.</p>
</div>
<div id="r-command-line-1" class="section level3">
<h3>R command line</h3>
<p>The R function <em>knit2html</em> first calls <em>knit</em> to generate a Markdown file and then <em>markdownToHTML</em> to generate a HTML file.</p>
<pre class="r"><code>library(knitr)
knit2html('simple-r-markdown.rmd')</code></pre>
</div>
<div id="shell-command-line-1" class="section level3">
<h3>Shell command line</h3>
<p>You can run R from the command line and call <em>knitr::knit2html</em>.</p>
<pre class="sh"><code>Rscript -e 'knitr::knit2html("simple-r-markdown.rmd")'</code></pre>
</div>
</div>
<div id="rendering-a-r-script" class="section level2">
<h2>Rendering a R script</h2>
<p>An R script can be rendered as though it were an R Markdown document containing a single code chunk.</p>
<div id="rstudio-2" class="section level3">
<h3>RStudio</h3>
<p>Open the R script in RStudio. Select <em>File -> Compile Notebook</em>.</p>
</div>
<div id="r-command-line-2" class="section level3">
<h3>R command line</h3>
<p>The R function <em>stitch_rmd</em> does something very similar to <em>File -> Compile Notebook</em>.</p>
<pre class="r"><code>library(knitr)
stitch_rmd('an-r-script.r')</code></pre>
</div>
<div id="shell-command-line-2" class="section level3">
<h3>Shell command line</h3>
<p>You can run R from the command line and call <em>knitr::stitch_rmd</em>.</p>
<pre class="sh"><code>Rscript -e 'knitr::stitch_rmd("an-r-script.r")'</code></pre>
</div>
</div>
<div id="publishing-a-r-markdown-document-on-rpubs" class="section level2">
<h2>Publishing a R Markdown document on RPubs</h2>
<p>RMarkdown documents can be published and shared on <a href="http://rpubs.com">RPubs</a>.</p>
<ul>
<li>Create an account on <a href="http://rpubs.com">RPubs</a></li>
<li>Open the RMarkdown file in RStudio</li>
<li>Click the <em>Knit HTML</em> butotn</li>
<li>Click the <em>Publish</em> button</li>
</ul>
<p>RPubs publishes the rendered document, but sadly does not also publish the raw R Markdown code. The <em>rmd</em> file can be published on <a href="github">GitHub</a> or as a <a href="gist">GitHub gist</a>.</p>
<div id="windows-ssl-certificate-problem" class="section level3">
<h3>Windows SSL certificate problem</h3>
<p>Windows users may run into an SSL certificate problem when first attempting to upload to RPubs. Here is advice developed by the long suffering students in STAT 545A:</p>
<ul>
<li>Your basic solution can be found <a href="http://support.rstudio.org/help/discussions/problems/2513-problem-with-publish-to-rpubs-windows-rstudio-096231">here</a></li>
<li>You will need to add the line <code>options(rpubs.upload.method = "internal")</code> to the file <code>Rprofile.site</code> which will live somewhere like this: <code>C:\Program Files\R\R-3.0.1\etc</code>. Yes take the <code>etc</code> <strong>literally</strong>. There is a directory with this name.</li>
<li>You will need administrator access to edit this file, which you can get by right licking and choosing “Run as administrator” when you launch whatever you’re going to use for editing.</li>
<li>Do not edit something like this with (eeeeekkk) Word. Use Notepad or even the RStudio editor. Plain text editing!</li>
<li>Another way to get permission to edit this file: Right click on the file, choose “Properties”–> “Security”, and Edit to give “Full control” to “Users”. Then you will be given the permission to edit the file.</li>
</ul>
</div>
</div>
</div>
<div id="further-reading" class="section level1">
<h1>Further Reading</h1>
<ul>
<li>Carson Sievert’s talk <a href="http://cpsievert.github.io/slides/markdown/">Reproducible web documents with R, knitr & Markdown</a></li>
<li><a href="http://www.mathjax.org">MathJax</a> is an open source JavaScript display engine for mathematics that works in all browsers … It just works</li>
<li>Jeromy Anglim’s blog post <a href="http://jeromyanglim.blogspot.ca/2012/05/getting-started-with-r-markdown-knitr.html">Getting Started with R Markdown, knitr, and Rstudio 0.96</a> and a <a href="https://gist.github.com/jeromyanglim/2716336">Gist containing the source</a></li>
<li>Yihui Xie <a href="http://yihui.name/en/2013/10/markdown-or-latex/">blog post</a> about when to use Markdown and when to use LaTeX</li>
<li>How to change the CSS used when R markdown is converted to HTML</li>
<li><a href="http://www.stat.ubc.ca/~jenny/STAT545A/topic10_tablesCSS.html">Step-by-step instructions</a> from Jenny Bryan’s STAT 545A course</li>
<li><a href="http://www.rstudio.com/ide/docs/authoring/markdown_custom_rendering">Customizing Markdown Rendering</a></li>
<li>Ben Bolker RPub <a href="http://rpubs.com/bbolker/3153">Literate programming, version control, reproducible research, collaboration, and all that</a></li>
</ul>
</div>
<div class="footer">
This work is licensed under the <a href="http://creativecommons.org/licenses/by-nc/3.0/">CC BY-NC 3.0 Creative Commons License</a>.
</div>
</div>
<script>
// add bootstrap table styles to pandoc tables
$(document).ready(function () {
$('tr.header').parent('thead').parent('table').addClass('table table-condensed');
});
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>