Lesson 4: Documenting WorkLesson 4: Documenting Work
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.
- 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
- recognize common errors in compilation of HTML notebooks
The R code file for this chapter can be found in the "Code Files" folder. This chapter does not require external data.
4.1 - Approaches to Documenting your Work/Thinking4.1 - Approaches to Documenting your Work/Thinking
Good documentation has 2 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 "2 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 show 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 rmarkdown4.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 script4.3 - Creating html from R script
Here we'll open a new R script file (File > New> R script in RStudio), paste some simple code into it from the Chapter4.R file, and compile the document using Rstudio’s “compile” integration.
4.4 - Creating html from R script in the console4.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 Knitr4.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.