RMarkdown Tutorial
Introduction
For the final lab I wanted to give a little more information about using RMarkdown. Markdown is a language for creating formatted text using a simple syntax. RMarkdown is particular deployment of Markdown in the R environment that allows you to execute code in your formatted document.
Although you have use RMarkdown for some of the assignments, I wanted to show how you can control the output and deploy different features and formats. I also want to show you how to publish your Markdown document directly to the web.
To begin a R Markdown document, open RStudio and click on the new
file button at the top left of the screen and select
R Markdown.
You will see a popup that will ask for a title, author and output
format. You will also see that there are a number of choices you can
make regarding format (Documents, Presentations, Shiny, Templates). We
used a template a few weeks ago (flexdashboard) for our CTA
station boarding assignment. There are MANY different types of documents
you can produce with RMarkdown. Since it can accommodate running code
one of the things it is useful for is to scrape the web to embed
real-time data into documents.
Documents and presentations are generally static and offer only limited user interaction. Shiny apps offer much more interaction. For example, here is the Cook County Department of Public Health COVID-19 Surveillance page, which is written in RMarkdown and deployed as a Shiny app: https://ccdphcd.shinyapps.io/covid19/
Create File
For this tutorial we will create the html document by making sure that HTML is checked. You can put your own title and author in the space provded if you wish.
You should now see a panel (or a tab) in the upper left panel that is called Untitled1.
Preamble
You will notice that the panel is populated with code. The top of the document is the header (sometimes it is referred to as the YAML or preamble. You can edit that as you wish if you want to change the title or author.
—
title: “Lab 7”
author: “Hugh Bartling”
date: “February 23, 2023”
output: html_document
—
The rest of the document alternates between text and code to produce
plots in your final document. The darkened parts between the
``` are R code.
Formatting
The ## makes the words R Markdown appear as
a section head with bold and bigger text:
R Markdown
Please be mindful of the blank line spaces in the illustrations.
There needs to be a blank line before the ## in order for
the section title to be rendered correctly.
To learn all of the formatting commands, see the users guide for R Markdown: https://rmarkdown.rstudio.com/authoring_basics.html
Example Using Code
Let’s do a quick plot using data from the Chicago Data Portal. We will look at 311 calls for water in basements to get an understanding of flooding problems in the city.
We first load all of the packages we need using the
library function. Then we download the data into an object
called flood and clean it to get rid of observations that
have empty values for the geocoded variables.
Next I change the options to make sure that the tigris
package returns a simple features object. That is done on the next line
where I download boundary files for all of the places in Illinois.
We then create a new object chic which filters Chicago
from all of the city boundaries in Illinois.
Next we transform the flood data into a spatial object called
flood_home and map it with the tmap
package.
library(RSocrata)
library(tigris)
library(dplyr)
library(sf)
library(tmap)
flood <- read.socrata("https://data.cityofchicago.org/resource/v6vf-nfxy.json?$where=SR_SHORT_CODE=%22AAF%22&$limit=1000")
flood <- flood[!is.na(flood$latitude),]
options(tigris_class = "sf")
df <- places(17)##
|
| | 0%
|
| | 1%
|
|= | 1%
|
|= | 2%
|
|== | 2%
|
|== | 3%
|
|== | 4%
|
|=== | 4%
|
|=== | 5%
|
|==== | 5%
|
|==== | 6%
|
|===== | 7%
|
|===== | 8%
|
|====== | 8%
|
|====== | 9%
|
|======= | 9%
|
|======= | 10%
|
|======== | 11%
|
|======== | 12%
|
|========= | 13%
|
|========== | 14%
|
|=========== | 15%
|
|=========== | 16%
|
|============ | 17%
|
|============= | 18%
|
|============== | 19%
|
|============== | 20%
|
|=============== | 22%
|
|================ | 23%
|
|================= | 24%
|
|====================== | 31%
|
|================================ | 45%
|
|========================================= | 59%
|
|=================================================== | 73%
|
|============================================================= | 87%
|
|======================================================================| 100%chic <- df %>%
filter(NAME == "Chicago")
flood_home <- st_as_sf(flood,
coords = c("longitude", "latitude"),
crs = 4269)
tm_shape(chic) + tm_polygons() +tm_shape(flood_home) + tm_dots(size=.05, col="red")
Clean up
You will notice that the code and then the plot were printed.
Normally for a report like this we don’t want to see the code. To
suppress the code, make sure that your first line before the code
includes the echo=FALSE and the
results = "hide" parameters. The entire line should like
this:
{r echo=FALSE, message=FALSE, warning=FALSE, results = "hide"}.
I am re-running the code in Markdown with the echo=FALSE
parameter in place and I will just get the chart. For a report it is
useful to include that preamble for every code chunk. If you are running
code to produce an interactive map, make sure to remove the
results = "hide" from the preamble in the code chunk that
includes the interactive map.
Interactivity
The previous map I made with the tmap package. You can
make a tmap map interactive by using the
tmap_mode function. To go back to making a static map, run
tmap_mode("plot").
RMarkdown Themes
There are a variety of themes that can be used with RMarkdown. Many of the themes are distributed as packages that you need to have installed through the package installer in order to work.
This week’s lab was written using a theme available from the
rmdformats package. Changing the theme is usually simply a
matter of changing lines in the document preamble. Below I’ve added a
table of contents by adding the toc: true line indented
after the output
—
title: “Lab 7”
author: “Hugh Bartling”
date: “February 26, 2020”
output:
html_document:
toc: true
—
If you encounter errors, make sure you have the spacing correct in
the preamble. Sometimes it is also necessary to clear the knitr cache
which can be done by clicking on the little triangle next to the
knit button.
A good resource for understanding more about RMarkdown is the free online book R Markdown: The Definitive Guide.
Saving and Publishing
When you are ready to see what your document looks like, you need to
“knit” it. Simply find the knit button and click.
You will notice activity in the
Render tab next to the console and soon a new window will
pop up with your document. The document is saved on your hard drive as a
stand-alone html document. That means you can view it with a web browser
and send the file to others if it is something you want to share.
If it looks good and you want to publish it, click on the “Publish” button on the top right of your new window. You may be asked to install some packages. Click ’OK.”
You should be given the option of
publishing to RPubs. It will give you a warning that all of your
published documents will be publicly visible. Clicking
OK will open up your web browser and give you the
option to create a free account.
Please create an account. You should next get to a screen that says Document Details. Fill in the details if you wish.
Clicking continue will publish the
document and you will be taken to the URL where your document
resides.
If you make additional changes to the document in RStudio, you can
choose to republish the document. Just knit the document
again and on the popup rendering, click republish. You
should be able to update the existing document or create a new instance
of the document on RPubs.
I will add a markdown copy of this lab in the Posit assignment space
if you want to experiment with this particular markdown template. If you
encounter an error while knitting the document that says
Error: path for html_dependency not found:, clear the Knit
cache by clicking on the arrow next to Knit and selecting
Clear Knitr Cache.