Lab 1 Jan 09 2019

Learning Objectives

For all homeworks in this class I’ll expect you to submit a PDF that has been “Knit” from an Rmarkdown document. This ensures your work has a minimal level of reproducibility and that the TA and I can see exactly how you reached your answers. It’s also a great skill to learn and used extensively in industry.

By the end of today’s lab, you should be able to:

• Navigate to the class workspace on RStudio cloud and make a copy of a project
• “Knit” an Rmarkdown document to PDF
• Combine code, results, plots, tables, math and narrative in an Rmarkdown document
• Debug common rendering errors

rstudio.cloud

rstudio.cloud is a web-based version of R and RStudio. Today you’ll start from a project I’ve created, but by the end you will have created your own project ready for Homework 1.

Rmarkdown

We’ll use Rmarkdown to generate our reports. Rmarkdown files combine markdown (a kind of plain text markup language) with chunks of R code. When compiled, the R code in the file is evaluated, then the results are woven into the markdown. Markdown is flexible enough that it can then be turned into a pdf (via LaTeX), a Word document, or an html file (for hosting on the web for instance, like this lab!).

Let’s learn by example. The TA will walk you through this part:

1. Open 01-getting-started-rmarkdown.Rmd

2. Skim through the file. This is just a plain text file with some special syntax. TA will point out:

   • YAML header

     ---
     # Some options that control the output
     ---

   • code chunks

     ```{r}
     # R CODE HERE
     
     ```

   • Markdown syntax in the plain text parts, e.g. ## Section Headings and `code`.

3. Hit the Knit button to “Knit” this Rmarkdown to PDF. All going well a PDF file will appear (you’ll also find it in the Files pane as 01-getting-started-rmarkdown.pdf). Give it a quick skim. TA will point out:

   • code chunks are “echoed”,
   • the results from code chunks are included shown after the code
   • … same for figures
   • the special Markdown syntax has generated formatting like sections and text that looks like code.

4. You don’t have to “Knit” a document to see the results of running code, if your cursor is inside a code chunk, you can hit Crtl/Cmd + Enter to run the current line, or Crtl/Cmd + Shift + Enter to run the whole chunk. In fact, this is usually how you work as you build an Rmarkdown document.

Your turn Make some changes in the Rmarkdown re-Knit and check the changes propagated. You might like to:

• Change the author to your name
• Add some text outside a code chunk
• Change the labels in a plot

Debugging problems with Knitting

Errors when you Knit can be a little hard to track down because the error could be a code error, or an error from converting to the output you’ve chosen. If you run into an error, a good first step is to rule out code errors.

Rule out code errors, by going to Run -> “Restart R and Run All Chunks”. Any code errors should raise their heads and you can fix them before trying to Knit again.

The code in an Rmarkdown document is run in a clean R session, so the most common mistakes are forgetting to load a package, or relying on objects you have in your workspace but that aren’t defined in your document.

Your Turn Open 02-errors.Rmd and Knit it. You’ll get an error, try the strategy outlined above to track down the error, fix it, and re-Knit. (There’s more than one problem you you might need to iterate through this process).

Starting from scratch

Let’s get you ready to embark on a new Rmarkdown file:

1. Create a new Rmarkdown file: File -> New File -> R markdown. Provide a title (how about “Homework 1”?), your name as the author, and select PDF output. A new file will open with some contents designed to remind you how to use Rmarkdown. Save it with an informative name.

2. You probably don’t want this template contents, so delete everything below the header, and start a new section called Q1.

3. You can easily insert a code chunk with the shortcut Ctrl/Cmd + Alt/Option + I. Then you can write R code inside it. How about loading the faraway package?

4. Take a look at Homework 1. This first task is to complete an initial analysis of the pima dataset. Perhaps you might start with looking at a few values. Create a new code chunk, and include:

   head(pima)

   Practice running the code with a the keyboard shortcut. What do you notice about the data? You’ll probably find looking at ?pima useful. You might make a few notes to yourself in the Rmarkdown.

5. It’s a good time to check our file still Knits. Knit it to check.

And that’s basically how you proceed to complete your homework…

Looking ahead

Sometimes I’ll provide you an entire project, like I did today, because I can make sure you have the right packages and provide some files. But, you’ll also want to maintain your own projects for submitting homeworks.

The easiest approach to begin with, is to create a new project in the class workspace (this ensures you’ll have all the needed packages pre-installed), and do all your homeworks inside as individual Rmarkdown documents. You can use folders inside a project to help organise things.

If you create a project in your private workspace, you will have to install the packages you need.