title: "Test drive R Markdown" output: html_document: toc: yes

toc_depth: 4

Overview

This describes a hands-on activity where the goal is to author an R Markdown document and render it to HTML. We discuss how to keep the intermediate Markdown file, the figures, and what to commit to Git and push to GitHub.

Here is the official R Markdown documentation:

Step 0: Software installation and configuration

We assume the following

Step 1: Get ready to work

Launch RStudio, probably in the Project that corresponds to the repository where you are keeping all STAT 545 coursework. Make sure the workspace is clean and you've launched a fresh R process. Make sure the working directory is sensible.

Step 2: Practice with RStudio's boilerplate R Markdown document

I am modelling "walk before you run" here. It is best, especially for novices, to increase complexity in small increments. We will test our system's ability to render the "hello world" of R Markdown documents before we muddy the waters with our own, probably buggy, documents.

Do this: File > New File > R Markdown ...

  • Give it an informative title. This will appear in the document but does not necessarily have anything to do with the file's name. But the title and filename should be similar! The title is for human eyeballs, so it can contain spaces and punctuation. The filename is for humans and computers, so it should have similar words in it but no spaces and no punctuation.
  • Accept the default Author or edit if you wish.
  • Accept the default output format of HTML.
  • Click OK.

Save this document to a reasonable filename and location. The filename should end in .Rmd or .rmd. I highly recommend saving in the top-level of the directory that is also also a Git repository for your coursework and that is also an RStudio project and that is also current working directory. Trust me on this.

Click on "Knit HTML" or do File > Knit Document. RStudio should display a preview of the resulting HTML. Also look at the file browser (which should be pointed at the directory where you saved the .Rmd file). You should see the R Markdown document, i.e. foo.Rmd AND the resulting HTML foo.html.

Congratulations, you've just made your first reproducible report with R Markdown.

Step 3: Save the intermediate Markdown

This is directly related to eventual publishing on GitHub. If that does not apply to you, skip this step.

It will have nice side effects on GitHub if we save the intermediate Markdown file that is produced when compiling to HTML. The magical process is like so: foo.Rmd --> foo.md --> foo.html. By default RStudio discards foo.md but it's easy to request that it be kept. This is one of the many things we can control in the YAML frontmatter -- the text at the top of your file between leading and trailing lines of ---. Two approaches:

  • RStudio GUI: click on the "gear" in the top bar of the source editor, near the "Knit HTML" button. Select "Output options" and go to the Advanced tab and check "Keep markdown source file."

  • "By hand:" Make your YAML frontmatter look something like this:

    ---  
    title: "Something fascinating"  
    author: "Jenny Bryan"  
    date: "`r format(Sys.Date())`"
    output:  
      html_document:  
        keep_md: true  
    ---

Save! Render via "Knit HTML" button.

Now revisit the file browser. In addition to foo.Rmd and foo.html, you should now see foo.md and a directory foo_files, where any figures created by the document will live.

Step 4: Swap out the "guts" of the document

Select everything but the YAML frontmatter and ... delete it!

Write a single English sentence.

Insert an empty R chunk, via the "Chunk" menu in upper right of source editor or with corresponding keyboard shortcut.

```{r}
## insert your brilliant WORKING code here
```

Insert 1 to 3 lines of functioning code that begin the task at hand. "Walk through" and run those lines using the "Run" button or the corresponding keyboard shortcut. You MUST make sure your code actually works!

Satisfied? Save!

Now render the whole document via "Knit HTML." Voilà!

Step 5: Develop your report

In this incremental manner, develop your report. Add code to this chunk. Refine it. Add new chunks. Go crazy! But keep running the code "manually" to make sure it works.

If it doesn't work with you babysitting it, I can guarantee you it will fail, in a more spectacular and cryptic way, when run at arms-length via "Knit HTML" or rmarkdown::render().

Clean out your workspace and restart R and re-run everything periodically, if things get weird. There are lots of chunk menu items and keyboard shortcuts to accelerate this workflow. Render the whole document often to catch errors when they're easy to pinpoint and fix. Save often and commit every time you reach a point that you'd like as a "fall back" position.

You'll develop your own mojo soon, but this should give you your first successful R Markdown experience.

Step 6: Publish your report

Since we are pushing coursework to GitHub anyway, I focus on how that delivers decent web publishing for "free."

Markdown documents get special treatment on GitHub: when you visit one in a web browser, instead of seeing the raw Markdown, by default you see a preview of how it will look when rendered to proper HTML. This is why, in Step 3, we alter the YAML to request retention of the intermediate Markdown file. If there are R chunks that make figures, keep_md: true will also cause those figure files to be left behind in a sensibly named sub-directory. If you commit and push foo.md and everything inside foo_files, then anyone with permission to view your GitHub repo can see a decent-looking version of your report.

This is (sort of) another example of keeping things machine- and human-readable. By making foo.Rmd available, others can see and run your actual code. By sharing foo.md and/or foo.html, others can casually browse your end product and decide if they even want to run your code.

HTML files, such as foo.html, are not immediately useful on GitHub (though your local versions are easily viewable). Visit one and you'll see the raw HTML. Yuck. But there are ways to get a preview: such as https://rawgit.com or http://htmlpreview.github.io. Expect some pain with HTML files inside private repos. When it becomes vital for the whole world to see proper HTML in its full glory, it's time to use a more sophisticated web publishing strategy.

I have more general ideas about how to make a GitHub repo function as a website.

Troubleshooting

Make sure RStudio and the rmarkdown package (and its dependencies) are up-to-date. In case of catastrophic failure to render R Markdown, consider that your software may be too old. R Markdown has been developing rapidly (written 2015-09), so you need a very current version of RStudio and rmarkdown to enjoy all the goodies we describe in this course.

Get rid of your .Rprofile, at least temporarily. I have found that a "mature" .Rprofile that has accumulated haphazardly over the years can cause trouble. Specifically, if you've got anything in there relating to knitr, markdown, rmarkdown and RStudio stuff, it may be preventing the installation or usage of the most recent goodies (see above). Comment the whole file out or rename it something else and relaunch or even re-install RStudio.

Insert a chunk in your .Rmd document so that it renders even when there are errors. Some errors are easier to diagnose if you can execute specific R statements during rendering and leave more evidence behind for forensic examination. Put this chunk:

```{r setup, include = FALSE, cache = FALSE}  
knitr::opts_chunk$set(error = TRUE)  
```

near the top of your R Markdown document if you want to soldier on through errors, i.e. turn foo.Rmd into foo.md and/or foo.html no matter what. This is also helpful if you are writing a tutorial and want to demo code that throws an error. You might want to keep this as an RStudio snippet for easy insertion.

Tolerate errors in one specific chunk. If it's undesirable to globally accept errors, you can still do this for a specific chunk like so:

```{r wing-and-a-prayer, error = FALSE}  
## your sketchy code goes here ;) 
```

Check your working directory. It's going to break your heart as you learn how often your mistakes are really mundane and basic. Ask me how I know. When things go wrong consider:

  • What is the working directory?
  • Is that file I want to read/write actually where I think it is?

Drop these commands into R chunks to check the above:

  • getwd() will display working directory at run time. If you monkeyed around with working directory with, e.g., the mouse, maybe it's set to one place for your interactive development and another when "Knit HTML" takes over?
  • list.files() will list the files in working directory. Is the file you want even there?

Don't try to change working directory within an R Markdown document. Just don't. That is all.

Don't be in a hurry to create a complicated sub-directory structure. RStudio/knitr/rmarkdown (which bring you the "Knit HTML" button) are rather opinionated about the working directory being set to the .Rmd file's location and about all files living together in one big happy directory. This can all be worked around. But not today.