Explore a working knitr document
OverviewTeaching: 30 min
Exercises: 10 minQuestions
How does it all come together?
What reseources exist?Objectives
See how literate programming helps you
See a how easy it is to make changes to
2. Bring it all together
- Contrast literate programming with stand-alone scripts and stand-alone documentation.
- Relate literate programming to reproducible generation of scientific figures and analysis results.
- Recognize benefits of and opportunities for applying literate programming.
- Produce and modify R knitr reports.
- Identify intermediary files, and thus which files can be regenerated.
Interactive knitr document: countryPick4.Rmd.
Reading code is often difficult, even if you are the programmer. Literate programming is an approach to writing code that combines plain English interspersed with code to help explain the why and how behind the code. The end result is often a report that provides narrative to your work. These reports alleviate many of the problems associating with computational work including:
- Making your code pleasurable to read.
- Reduction of tedium and manual processes when making changes to experiments.
- Reduction of friction for communication of results.
- Begins the process of writing papers as the data, figures and rationale for each project are all in one place and can be copied and edited when writing your papers.
Essentially literate programming acts as your lab notebook for your computational work. As with scientific notebooks, there are many styles to writing in one. Every project is unique, but the end goal is always to make it as easy as possible for you and others to reproduce your work.
In this lesson we are going to use
RStudio to combine
R code, markdown, and knitr to create reports that can be saved in many formats for distribution. Depending on the language you can combine the same or similar tools for creating literate programming reports, for example for
Project Jupyter are powerful options.
Step 1: Open .Rmd Document and Run Code
Open countryPick4.Rmd. This is a report exploring population size of four countries.
Save this document with a new filename. The filename should end in
.Rmd. Use what you have learned from file naming to give an appropriate new name to this report.
Goal: Make the report unique by choosing four new countries. Explore a few countries and try to find a combination that shows you something unique about the data. Read through report while running each of the code chunks.
Stretch Goal: If you are familiar with
ggplot, try adding a fifth country to this report.
Step 2: Save new report and knit
Click on “Knit HTML” or do
File > Knit.
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
RMarkdown document, i.e.
foo.Rmd and the resulting HTML
- Distinguish what was the input and output in creating this document. What role did the
.Rmdfile take and what the .html file?
- Which file can you delete while still being able to fully reproduce the result? What are all the files that are needed to re-create the
Step 3: Develop your report
In this incremental manner, develop a new report. Add new code to this file. Refine it. Add new chunks. Re-run the report frequently to make sure it works.
Sometimes left-over objects in the workspace make a report appear to fail even though it is correct. Clean out your workspace, restart
R, and re-run everything if you see weird failures. 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 every time you reach a point that you’d like as a “fall back” position.
Step 4: Publishing your report
Although not required, one of most accessible and often easiest ways to share
RMarkdown reports is over the web. Rpubs is a free database of
knitr documents, and makes it very easy to publish your knitr documents, especially when using
RStudio. In RStudio, create a new R Markdown document by choosing
File > New > RMarkdown. Click the
Knit HTML button in the doc toolbar to preview your document. In the preview window, click the Publish button. Browse recently published reports at Rpubs.
Another popular option is Github, which allows the publication and hosting of .md files for free. Github also provides the power of version control through Git.
RStudio and the rmarkdown package (and its dependencies) are up-to-date. In case of catastrophic failure to render
RMarkdown, consider that your software may be too old.
RMarkdown has been developing rapidly (written 2016-12), so you need a very current version of
You may need to get rid of your
.Rprofile, at least temporarily. Specifically, if you’ve got anything in there relating to
RStudio stuff, it may be preventing the installation or usage of the most recent versions.
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:
near the top of your R Markdown document if you want to the report to run in full even if there are errors, i.e. turn
foo.html no matter what.
Check whether your working directory is set correctly. Drop these commands into
R chunks to check the above:
getwd() will display working directory at run time.
Don’t try to change working directory within an
RMarkdown document. And don’t be in a hurry to create a complicated sub-directory structure.
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.
Knitr Cheat Sheet - cheat sheet for
RStudio - Up-to-date RStudio versions also contain direct links to these “cheatseets”
Help > Cheatsheets
Ipython - Powerful option for writing literate programming in
Project Jupyter - The offsrping of Ipython allows literate programming in a variety of languagues, including
Credits This material was adapted from an activity by Jenny Bryan.
knitrare powerful tools.
It all comes together very nicely