6.1 My First Rmd

Before we get started, let’s make sure that the RMarkdown package is installed. Remember, you only need to run install.packages command once, unless you want to update the package.

(Unlike most packages, we don’t need a library() statement for rmarkdown. Don’t worry about that much for now- RStudio takes care of things behind the scenes.)

install.packages("rmarkdown")

Rstudio makes it easy to create a new RMarkdown file, and it even starts with a demo file that shows off most of the basic features of the Rmd format. In the upper-left corner, click the “new file” icon and select RMarkdown. A window should appear to help you configure this file initially. There’s a lot of options (R Markdown can do so much!), but for now, make sure your name is in the “Author” field, and change the “Title” to be something like “AARUG Workshop”.

Before we delve into what each of these pieces mean, let’s “knit” the document so we can see what kind of output RMarkdown produces. Above the file, press the knit button, the one that looks like a ball of yarn.

You should see a new pane open in RStudio that shows R “knitting” the document, and when it’s done, a pop-up will appear showing the knitted output.

This new output being displayed as an html file; look in the file browser pane, and you’ll see a .html file next to your .Rmd file (may need to refresh), because RStudio automatically saved this output when the document finished knitting.

Let’s look at the individual pieces in this document:

6.1.1 Header

This is the section at the top, with three dashes before and after. This lists some metadata about the object. The title, date, and author form the start of the output document, and the output: line instructs the knitting process to generate an html file.

6.1.2 Section Titles

You can enlarge text be preceding it with one or more pound signs (#). This is mainly useful for organizing a document into sections. The more pound signs, the smaller the text, so when you make sub-section you should add at least one more pound sign than used in the parent sections’ title.

6.1.3 Link

You can make text clickable by including a link to a different website. An example can be found above, where we included a link to CRAN.

There are two parts to creating linked text. The first part is including the text you want to see, surrounded by square brackets [CRAN]. Immediately after that, add the link surrounded by parentheses (https://cran.r-project.org). The final product looks like [CRAN](https://cran.r-project.org).

6.1.4 Bold/Italic Text

The double-asterisks surrounding the word “Knit” in the second paragraph cause that piece of text to be bold. This phrase can be multiple words, but should not have spaces immediately on the inside of the asterisks. You can make text italix by similarly wrapping in underscores (_) or using single asterisks.

6.1.5 Code Chunks

This is the real meat of the document! An R Markdown code chunk is a section which starts and ends with triple-backticks (`, not '). After the initial set, the curly-bracketed section which starts with {r is what forces this to be ran as R code; without this piece, the section would get formatted like code, but would not be executed when knitting. The phrase after the r is the chunk name. Chunks do not need to be named, but no two chunks can have the same name. Naming chunks can help keep code organized and make it easier to track down the source of errors when they occur.

6.1.5.1 Chunk Options

As the second default section discusses, we can hide the code in a code chunk by placing a comma after out chunk name and setting an option echo=FALSE. The code will still execute, and its output will be inserted in the knitted document, but it will not be shown.

Similarly, you can set eval=FALSE to avoid running a code chunk.