Knitr in a knutshell tutorial; Dynamic Documents with R and knitr (book) R Markdown documentation; R Markdown cheat sheet; Getting started with R Markdown; R Markdown: The Definitive Guide (book by Rstudio team) Reproducible Reporting; The Ecosystem of R Markdown; Introducing Bookdown; Key Points. Mix reporting written in R Markdown with. The key R package is knitr. It allows you to create a document that is a mixture of text and chunks of code. When the document is processed by knitr, chunks of code will be executed, and graphs or other results inserted into the final document. This sort of idea has been called “literate programming”.
- Knitr Cheat Sheet 2020
- Knitr Cheat Sheet
- R Markdown Reference Guide
- Md File Cheat Sheet
- Rmarkdown Cheat Sheet 2.0
- Knitr Cheat Sheet
The simplest way to write a quick report, mixing in a bit of R, is touse R Markdown, avariant of Markdowndeveloped by the folks at Rstudio.
You should first read the page about Markdown.
R Markdown
R Markdown is avariant of Markdownthat has embedded R code chunks, tobe used with knitr to make it easy tocreate reproducible web-based reports. The Markdown syntax has someenhancements (see theR Markdown page); for example,you can include LaTeX equations (seeEquations in R Markdown).
Here’s an example R Markdown document,and the html document it produces.
Code chunks
The key thing for us to focus on are the code chunks, which look like this:
In the midst of an otherwise plain Markdown document, you’ll have abit of R code that is initiated by a line like this:
After the code, there’ll be a line with just three backticks.
It’s usually best to give each code chunk a name, like
simulate-data
and chunk-name
above. The name is optional; if included, each codechunk needs a distinct name. The advantage of giving each chunk a nameis that it will be easier to understand where to look for errors,should they occur. Also, any figures that are created will be givennames based on the name of the code chunk that produced them. Asdiscussed in R Markdown: The DefinitiveGuide, it is bestfor the chunk labels to use just letters, numbers, and dashes, andno other special characters.When you process the R Markdown document with knitr, each of the codechunks will be evaluated, and then the code and/or output will beinserted (unless you suppress one or both with chunk options, described below). Ifthe code produces a figure, that figure will be inserted.
An R Markdown document will have often have many code chunks. They areevaluated in order, in a single R session, and the state of thevarious variables in one code chunk are preserved in futurechunks. It’s as if you’d pulled out all of the R code as a single file(and you can dothat, using the
purl
command in knitr) and thensourceit into R.Chunk options
The initial line in a code chunk may include various options. Forexample,
echo=FALSE
indicates that the code will not be shown in thefinal document (though any results/output would still be displayed).You use
results='hide'
to hide the results/output (but here the codewould still be displayed).You use
include=FALSE
to have the chunk evaluated, but neither thecode nor its output displayed.If I’m writing a report for a collaborator, I’ll often use
include=FALSE
to suppress all of the code and largely just includefigures.For figures, you’ll want to use options like
fig.width
andfig.height
. For example:Note that if
include=FALSE
, all of the code, results, and figureswill be suppressed. If include=TRUE
and results='hide'
, the resultswill be hidden but figures will still be shown. To hide the figures,use fig.show='hide'
.There arelots of different possible “chunk options”.Each must be real R code, as R will be used to evaluate them. So
results=hide
is wrong; you need results='hide'
.Global chunk options
You may be inclined to use largely the same set of chunk optionsthroughout a document. But it would be a pain to retype those options in every chunk. Thus, you want to set someglobal chunk options at the top of your document.
For example, I might use
include=FALSE
or at least echo=FALSE
globally for a report to a scientific collaborator who wouldn’t wantto see all of the code. And I might want something like fig.width=12
and fig.height=6
if I generally want those sizes for my figures.I’d set such options by having an initial code chunk like this:
I snuck a few additional options in there:
warning=FALSE
andmessage=FALSE
suppress any R warnings or messages from being included inthe final document, and fig.path='Figs/'
makes it so the figurefiles get placed in the Figs
subdirectory. (By default, they are notsaved at all.)Note: the ending slash in
Figs/
is important. If you usedfig.path='Figs'
then the figures would go in the main directory butwith Figs
as the initial part of their names.The global chunk options become the defaults for the rest of thedocument. Then if you want a particular chunk to have a differentbehavior, for example, to have a different figure height, you’dspecify a different option within that chunk. For example:
In a report to a collaborator, I might use
include=FALSE, echo=FALSE
as a global option, and then use include=TRUE
for the chunks thatproduce figures. Then the code would be suppressed throughout, and any outputwould be suppressed except in the figure chunks (where I usedinclude=TRUE
), which would produce just the figures.Knitr Cheat Sheet 2020
Technical aside: In setting the global chunk options with
opts_chunk$set()
, you’ll need to use knitr::
(or to have firstloaded the knitr package with library(knitr)
). As we’ll discussbelow, we’ll use thermarkdown package to processthe document, first with knitr and then withpandoc, andrmarkdown::render()
will use knitr::knit()
but won’t loadthe knitr package.Package options
In addition to the chunk options, there are alsopackage options,set with something like:
I was confused about this at first: I’d use
opts_knit$set
when Ireally wanted opts_chunk$set
. knitr includes a lot of options; ifyou’re getting fancy you may need these package options, but initiallyyou’ll just be using the chunk options and, particularly, the globalchunk options defined via opts_chunk$set
. So mostly ignoreopts_knit$set()
in favor of opts_chunk$set()
.In-line code
A key motivation for knitr isreproducible research:that our results are accompanied by the data and code needed toproduce them.
Thus, your report should never explicitly include numbers that arederived from the data. Don’t write “There are 168 individuals.”Rather, insert a bit of code that, whenevaluated, gives the number of individuals.
That’s the point of the in-line code. You’d write something like this:
Another example:
In R Markdown, in-line code is indicated with
`r
and `
.The bit of R code between them is evaluated and the result inserted.An important point: you need to be sure that these in-line bits ofcode aren’t split across lines in your document. Othewise you’ll justsee the raw code and not the result that you want.
YAML header
Insert, at the top of your R Markdown document, a bit of text like thefollowing:
The final document will then contain a nicely formated title, alongwith the author name and date. You can include hyperlinks in there:
Knitr Cheat Sheet
and even R code:
This is called the YAML header. YAML is asimple text-based format for specifying data, sort of likeJSON but more human-readable.
You can leave off the author and date if you want; you can leave offthe title, too. Actually, you don’t need to include any of this. But
output: html_document
tells thermarkdown package to convertthe document to html. That’s the default, but you could also useoutput: pdf_document
or even output: word_document
, in which caseyour document will be converted to a PDF or Word .docx
file,respectively.Rounding
I’m very particular about the rounding of results, and you should be too. If I’ve estimateda correlation coefficient with 1000 data points, I don’t want to see
0.9032738
. I want 0.90
.You could use the R function
round
, like this: `r round(cor(x,y), 2)`
But that would produce 0.9
instead of 0.90
.One solution is to use the
sprintf
function, like so:`r sprintf('%.2f', cor(x,y))`
. That’s perfectly reasonable,right? Well, it is if you’re a C programmer.But a problem arises if the value is
-0.001
. `r sprintf('%.2f', -0.001)`
will produce -0.00
. I don’t like that, nor doesHilary.My solution to this problem is the
myround
functionin my R/broman package.At the start of my R Markdown document, I’d include:
And then later I could write
`r myround(cor(x,y), 2)`
and it would give 0.90
or 0.00
in the way that I want.Converting R Markdown to html
Via RStudio
If you use RStudio, the simplest way toconvert an R Markdown document to html is to open the document withinRStudio. (And really, you probably want to create the document inRStudio: click File → New File → R Markdown.)When you open an R Markdown document in RStudio, you’ll seea “Knit HTML” button just above the document. (It’s a particularlycute little button, with a ball of yarn and a knitting needle.) Clickthat, and another window will open, and you’ll see knitr in action,executing each code chunk and each bit of in-line code, to compile the RMarkdown to a Markdown document. This will then be converted to html,with a preview of the result. (The resulting
.html
file will beplaced in the same directory as your .Rmd
file.) You can click“Open in browser” to open the document in your web browser, or“Publish” to publish the document to the web (where it will beviewable by anyone).Another a nice feature in RStudio: when you open an R Markdowndocument, you’ll see a little question mark button, with links to“Using R Markdown” and to a MarkdownQuick Reference. convenient “Markdown Quick Reference” document: acheat-sheet on the Markdown syntax. Like@StrictlyStat,I seem to visit theMarkdown website almostevery time I’m writing a Markdown document. If I used RStudio, I’dhave easier access to this information.
RStudio is especially useful when you’re first learning knitr and RMarkdown, as it’s easy to create and view the corresponding html file,and you have access to that Markdown Quick Reference.
Via the command line (or GNU make)
To process an R Markdown document, you need thermarkdown package (which inturn will make use of theknitr package plus abunch of other packages), as well aspandoc.
To install the rmarkdown package, use
install.packages(rmarkdown)
.The simplest way to install pandoc is to just install theRStudio Desktop software,which includes pandoc, and then include pandoc without your
PATH
.On a Mac, you’d use:In Windows, you’d include
'c:Program FilesRStudiobinpandoc'
inyour Path
system environment variable. (For example, seethis page,though it’s a bit ad-heavy.)To convert your Markdown document to HTML, you’d then use
(Note that in Windows, it’s important to use double-quotes on theoutside and single-quotes inside, rather than the other way around.)
Rather than actually type that line, I include it within aGNU make file, likethis one.(Also see my minimal maketutorial.)
Up next
At this point, I’d recommend going off and playing with R Markdown fora while. Write your next report with R Markdown, even if it takes youa bit longer. Write it using RStudio, wherethe knitting process is easy and you have easy access to that“Markdown Quick Reference”.
R Markdown Reference Guide
Then, read a bit about figures and tables, mycomments on reproducibility, andperhaps about Knitr with AsciiDoc orKnitr with LaTeX.
R Markdown (Allaire et al. 2021) is a plain-text document format consisting of two components: R (or other computing languages) and Markdown. Markdown makes it easy for authors to write a document due to its simple syntax. Program code (such as R code) can be embedded in a source Markdown document to generate an output document directly: when compiling the source document, the program code will be executed and its output will be intermingled with the Markdown text.
Md File Cheat Sheet
![Knitr Cheat Sheet Knitr Cheat Sheet](/uploads/1/3/8/2/138297319/995366659.png)
R Markdown files usually use the filename extension
.Rmd
. Below is a minimal example:Such a document can be compiled using the function
rmarkdown::render()
, or equivalently, by clicking the Knit
button in RStudio. Under the hood, an R Markdown document is first compiled to Markdown through knitr(Xie 2021), which executes all program code in the document. Then the Markdown output document is compiled to the final output document through Pandoc, such as an HTML page, a PDF document, a Word document, and so on. It is important to know this two-step process, otherwise you may not know which package documentation to look up when you have questions. Basically, for anything related to the (R) code chunks, consult the knitr documentation (https://yihui.org/knitr/); for anything related to Markdown, consult the Pandoc documentation (https://pandoc.org).An R Markdown document typically consists of YAML metadata (optional) and the document body. YAML metadata are written between a pair of
---
to set some attributes of the document, such as the title, author, and date, etc. In the document body, you can mix code chunks and narratives. A code block starts with a chunk header ```{r}
and ends with ```
. There are many possible chunk options that you can set in the chunk header to control the output, e.g., you can set the figure height to 4 inches using ```{r fig.height=4}
. For all possible chunk options, see https://yihui.org/knitr/options/.Rmarkdown Cheat Sheet 2.0
Pandoc supports a large variety of output document formats. For blogdown, the output format is set to HTML (
blogdown::html_page
), since a website typically consists of HTML pages. If you want other formats, please see Section 2.7. To create an R Markdown post for blogdown, it is recommended that you use the RStudio “New Post” (Figure 1.2) or the function blogdown::new_post()
, instead of the RStudio menu File -> New File -> R Markdown
.You are strongly recommended to go through the documentation of knitr chunk options and Pandoc’s manual at least once to have an idea of all possibilities. The basics of Markdown are simple enough, but there are many less well-known features in Pandoc’s Markdown, too. As we mentioned in Section 1.5, blogdown’s output format is based on bookdown(Xie 2020a), which contains several other Markdown extensions, such as numbered equations and theorem environments, and you need to read Chapter 2 of the bookdown book (Xie 2016) to learn more about these features.
Knitr Cheat Sheet
You can find an R Markdown cheat sheet and a reference guide at https://www.rstudio.com/resources/cheatsheets/, which can be handy after you are more familiar with R Markdown.
With R Markdown, you only need to maintain the source documents; all output pages can be automatically generated from source documents. This makes it much easier to maintain a website, especially when the website is related to data analysis or statistical computing and graphics. When the source code is updated (e.g., the model or data is changed), your web pages can be updated accordingly and automatically. There is no need to run the code separately and cut-and-paste again. Besides the convenience, you gain reproducibility at the same time.