4 Documenting Work
Overview
Here we’ll introduce some functions from the package rmarkdown that is integrated in RStudio and greatly simplifies documenting your work. We’ll be using Chapter 4 of Essential R Course Notes.
Objectives
Upon completion of this lesson, you should be able to:
- create and save an R script file (.R file) with code, comments, and figures,
- compile this file to produce an HTML notebook which includes all of these elements, and
- recognize common errors when compiling HTML notebooks.
Data and R Code Files
The R code file and data files for this lesson can be found on the Essential R - Notes on learning R page.
4.1 Approaches to Documenting Your Work/Thinking
Good documentation has two purposes. The first is to help you think clearly about what you are doing. The second is to communicate your results to others. (If you can’t communicate them to yourself, what hope do you have of communicating them to others?)
The left side of this diagrams embodies the “two document” way of documenting work - an R script file that contains data and code and comments and a word processor file that contains all justification, description of methods, output, figures, and commentary. Material is copied between the two documents as needed. This system seems easier, as most people already know the word processor side of it and most new R users are busy figuring out R.
The right side of the diagram shows the second way - everything is in one text file, which can be compiled to create output in various formats. During compilation, all the code is evaluated, and output and figures are generated and placed in the document.
This way of documenting work can seem very odd since you don’t see the final product while you are working on the document. However, the payoff in simplicity (no copying and pasting, changes in the data automatically showing up in the new document) is well worth it. In this set of videos, we’ll show you how it is done, using the package rmarkdown (integrated in RStudio). We’ll also demonstrate how to do this from the console.
4.2 Installation of rmarkdown
In order to use the package rmarkdown to compile documents, you need to install the package. This video walks through the package installation process, beginning with setting a CRAN mirror.
In the next video, I’ll show you how to use this package to compile an R script (.R file) to HTML.
4.3 Creating HTML from R Script
Here we’ll open a new R script file (FileFile > NewNew> RR in RStudio). First, paste some simple code into it from the Chapter4.R file, and then compile the document using Rstudio’s “compile” integration.
4.4 Creating HTML from R Script in the Console
You can use rmarkdown without using rstudio - here, I’ll show you how. This will require that you have rmarkdown installed (if you followed along on the last video, you already do) and loaded (you did not need to do this for the last video).
4.5 Common Problems While Using Knitr
Errors can pop up with surprising frequency when compiling documents. Here we explore the most common cause of these errors - calling variables that haven’t been defined - and explain how to avoid them - (spoiler alert, writing all your code in the editor and running it from there before compiling will prevent almost all errors). Note that for this and all subsequent assignments only HTML and pdf documents will be accepted for homework.