Document Code With R Markdown | NSF NEON

Skip to main content

Learning Hub

• Science Videos
• Tutorials
• Workshops & Courses
• Teaching Modules

Breadcrumb

1. Resources
2. Learning Hub
3. Tutorials
4. Document Code with R Markdown

You will need to have the rmarkdown and knitr packages installed on your computer prior to completing this tutorial. Refer to the setup materials to get these installed.

Learning Objectives

At the end of this activity, you will:

• Know how to create an R Markdown file in RStudio.
• Be able to write a script with text and R code chunks.
• Create an R Markdown document ready to be ‘knit’ into an HTML document to share your code and results.

Things You’ll Need To Complete This Tutorial

You will need the most current version of R and, preferably, RStudio loaded on your computer to complete this tutorial.

Install R Packages

• knitr: install.packages("knitr")
• rmarkdown: install.packages("rmarkdown")
• raster: install.packages("raster")
• rgdal: install.packages("rgdal")

Download Data

Download NEON Teaching Data Subset: TEAK-Data Institute 2016

The LiDAR and imagery data used to create this raster teaching data subset were collected over the National Ecological Observatory Network's (NEON) Lower Teakettle field site and processed at NEON headquarters. The entire dataset can be accessed by request from the NEON Data Portal.

Download Dataset

You will want to create a data directory for all the Data Institute teaching datasets. We suggest the pathway be ~/Documents/data/NEONDI-2016 or the equivalent for your operating system. Once you've downloaded and unzipped the dataset, move it to this directory.

Additional Resources

• R Markdown Cheatsheet: a very handy reference for using R Markdown
• R Markdown Reference Guide: a more expensive reference for R Markdown
• Introduction to R Markdown by Garrett Grolemund: a tutorial for learning R Markdown

Create an Rmd File

RMarkdown in RStudio Video

Our goal in this series is to document our workflow. We can do this by

1. Creating an R Markdown (RMD) file in R studio and
2. Rendering that RMD file to HTML using knitr.

Watch this 6:38 minute video below to learn more about how you can convert an R Markdown file to HTML (or other formats) using knitr in RStudio. The text size in the video is small so you may want to watch the video in full screen mode.

Now that you have a sense of how R Markdown can be used in RStudio, you are ready to create your own RMD document. Do the following:

1. Create a new R Markdown file and choose HTML as the desired output format.
2. Enter a Title (Explore NEON LiDAR Data) and Author Name (your name). Then click OK.
3. Save the file using the following format: LastName-institute-week3.rmd NOTE: The document title is not the same as the file name.
4. Hit the knit button in RStudio (as is done in the video above). What happens?

If everything went well, you should have an HTML format (web page) output after you hit the knit button. Note that this HTML output is built from a combination of code and documentation that was written using markdown syntax.

Next, we'll break down the structure of an R Markdown file.

Understand Structure of an R Markdown file

**Data Tip:** Screenshots on this page are from RStudio with appearance preferences set to `Twilight` with `Monaco` font. You can change the appearance of your RStudio by **Tools** > **Options** (or **Global Options** depending on the operating system). For more, see the Customizing RStudio page.

Let's next review the structure of an R Markdown (.Rmd) file. There are three main content types:

• Header: the text at the top of the document, written in YAML format.
• Markdown sections: text that describes your workflow written using markdown syntax.
• Code chunks: Chunks of R code that can be run and also can be rendered using knitr to an output document.

Next let's explore each section type.

Header -- YAML block

An R Markdown file always starts with header written using YAML syntax. There are four default elements in the RStudio generated YAML header:

• title: the title of your document. Note, this is not the same as the file name.
• author: who wrote the document.
• date: by default this is the date that the file is created.
• output: what format will the output be in. We will use HTML.

A YAML header may be structured differently depending upon how your are using it. Learn more on the R Markdown documentation page.

## Activity: R Markdown YAML Customize the header of your `.Rmd` file as follows:

• Title: Provide a title that fits the code that will be in your RMD.
• Author: Add your name here.
• Output: Leave the default output setting: html_document. We will be rendering an HTML file.

R Markdown Text/Markdown Blocks

An RMD document contains a mixture of code chunks and markdown blocks where you can describe aspects of your processing workflow. The markdown blocks use the same markdown syntax that we learned last week in week 2 materials. In these blocks you might describe the data that you are using, how it's being processed and and what the outputs are. You may even add some information that interprets the outputs.

When you render your document to HTML, this markdown will appear as text on the output HTML document.

Learn More about RStudio Markdown Basics

Explore Your R Markdown File

Look closely at the pre-populated markdown and R code chunks in your RMD file.

Does any of the markdown syntax look familiar?

• Are any words in bold?
• Are any words in italics?
• Are any words highlighted as code?

If you are unsure, the answers are at the bottom of this page.

## Activity: R Markdown Text

1. Remove the template markdown and code chunks added to the RMD file by RStudio. (Be sure to keep the YAML header!)
2. At the very top of your RMD document - after the YAML header, add the bio and short research description that you wrote last week in markdown syntax to the RMD file.
3. Between your profile and the research descriptions, add a header that says About My Project (or something similar).
4. Add a new header stating R Markdown Activity and text below that explaining that this page demonstrates using some of the NEON Teakettle LiDAR data products in R. The wording of this text should clearly describe the code and outputs that you will be adding the page.

**Data Tip**: You can add code output or an R object name to markdown segments of an RMD. For more, view this R Markdown documentation.

Code chunks

Code chunks are where your R code goes. All code chunks start and end with ``` – three backticks or graves. On your keyboard, the backticks can be found on the same key as the tilde. Graves are not the same as an apostrophe!

The initial line of a code chunk must appear as:

```{r chunk-name-with-no-spaces} # code goes here ```

The r part of the chunk header identifies this chunk as an R code chunk and is mandatory. Next to the {r, there is a chunk name. This name is not required for basic knitting however, it is good practice to give each chunk a unique name as it is required for more advanced knitting approaches.

Activity: Add Code Chunks to Your R Markdown File

Continue working on your document. Below the last section that you've just added, create a code chunk that loads the packages required to work with raster data in R.

```{r setup-library } library(rgdal) library(raster) ```

In R scripts, setting the working directory is normally done once near the beginning of your script. In R Markdown files, knit code chunks behave a little differently, and a warning appears upon kitting a chunk that sets a working directory.

```{r code-setwd} # set working directory to ensure R can find the file we wish to import. # This will depend on your local environment. setwd("~/Documents/data/NEONDI-2016/") ``` You changed the working directory to ~/Documents/data/NEONDI-2016/ (probably via setwd()). It will be restored to [directory path of current .rmd file]. See the Note section in ?knitr::knit ?knitr::knit

That's a bad sign if you want to set the working directory in one code chunk, and read or write data in another code chunk. To allow for a working data directory that is different from your Rmd file's current directory, you can store the directory path in a string variable.

```{r code-setwd-stringvariable} # set working directory as a string variable for use in other code chunks. # This will depend on your local environment. wd