Skip to content
LumenaryAcademy
Professional 65 min

Plots, packages and reproducible reports

Base graphics and ggplot2, installing and managing packages from CRAN, reproducible environments with renv, reports with R Markdown and Quarto, the tidyverse, and testing R code.

Code tested · 3AI-draftedAwaiting review by a computer scientist
MotivationH

From a script to something you can share

An analysis is only useful when other people can see it, trust it and, ideally, repeat it. That needs three things the earlier lessons have not covered. Graphics, because a good plot shows in a second what a table hides: two clusters, an outlier, a curve where you assumed a line. Packages, because no one writes everything themselves, and the more than twenty thousand packages contributed to CRAN are a large part of why people choose R. And reproducibility: a report that regenerates its numbers and figures from the raw data whenever the data or the code changes, on anyone's machine, with the same package versions.

This lesson covers each of these as R professionals practise them, and ends with how R code is tested and checked. The plotting packages and most of the tools mentioned here are not installed where this course's programs are checked, so their code is shown for reading; the checked programs compute what the plots would show, and demonstrate the ideas behind package management and testing with base R.

Worked examplesH

Base graphics

R has two main plotting systems. Base graphics come with R and work like drawing on paper: one function draws a plot, and others add points, lines, text and legends on top of it. They are quick for exploration and fully customisable. This code draws a histogram of Old Faithful's waiting times beside a scatter plot of waiting time against eruption length, with the least-squares line added, and saves both to a PNG file:

r
png("faithful.png", width = 900, height = 450)   # open a file "device"
par(mfrow = c(1, 2))                              # two plots side by side

hist(faithful$waiting, breaks = 20,
     main = "Old Faithful", xlab = "Waiting time (minutes)", col = "grey80")

plot(waiting ~ eruptions, data = faithful,
     xlab = "Eruption length (minutes)", ylab = "Waiting time (minutes)",
     pch = 19, col = adjustcolor("steelblue", alpha.f = 0.5))
abline(lm(waiting ~ eruptions, data = faithful), lwd = 2)

dev.off()                                         # close the file

The histogram is clearly bimodal, with one peak of waits around 50 to 55 minutes and a larger one around 75 to 85, something the mean of 70.9 completely hides. The scatter plot shows why: there are two kinds of eruption, short ones followed by short waits and long ones followed by long waits. A box plot is the other workhorse; boxplot(len ~ supp + dose, data = ToothGrowth) draws one box per combination of supplement and dose, using the formula interface you know from models.

Plots are drawn on a graphics device: a window when you work interactively, or a file opened with png(), pdf() or svg() and closed with dev.off(). The numbers behind these plots can be computed without drawing anything, which is how this program checks what the plots show:

r
# The numbers behind a histogram and a box plot, computed without drawing.
h <- hist(faithful$waiting, breaks = seq(40, 100, by = 10), plot = FALSE)
data.frame(from = head(h$breaks, -1), to = h$breaks[-1], count = h$counts)

# Two peaks: short waits after short eruptions, long waits after long ones.
tapply(faithful$waiting, faithful$eruptions > 3, median)

# boxplot.stats() gives the five numbers a box plot draws, plus any outliers.
boxplot.stats(ToothGrowth$len)$stats
boxplot.stats(c(2, 3, 3, 4, 5, 5, 6, 30))$out

# A quick text "bar chart" of tooth length by dose, one # per unit of the mean.
means <- tapply(ToothGrowth$len, ToothGrowth$dose, mean)
for (d in names(means)) cat(sprintf("%4s mg | %s %.1f\n", d, strrep("#", round(means[[d]])), means[[d]]))
text
  from  to count
1   40  50    26
2   50  60    57
3   60  70    24
4   70  80    81
5   80  90    78
6   90 100     6
FALSE  TRUE
   54    80
[1]  4.20 12.55 19.25 25.35 33.90
[1] 30
 0.5 mg | ########### 10.6
   1 mg | #################### 19.7
   2 mg | ########################## 26.1

The counts show the two peaks (57 waits in the 50s, 81 in the 70s, few in the 60s), and the medians split by eruption length, 54 and 80 minutes, explain them. A box plot draws five numbers: the lower whisker, lower quartile, median, upper quartile and upper whisker, with points beyond 1.5 box-lengths from the box drawn individually as outliers, like the 30 in the small example. sprintf() formats text with C-style placeholders, a handy tool for aligned console output.

IntuitionH

ggplot2: a grammar of graphics

ggplot2, by Hadley Wickham, is the most widely used R plotting package. Instead of drawing step by step, you describe a plot as a combination of independent parts, following Leland Wilkinson's Grammar of Graphics: the data; aesthetic mappings from columns to visual properties such as position, colour and size (aes()); geoms, the geometric objects that represent the data (points, lines, bars, boxes); and optionally statistical transformations, scales, facets (small multiples) and a theme. Layers are added with +.

r
library(ggplot2)

ggplot(faithful, aes(x = eruptions, y = waiting)) +
  geom_point(alpha = 0.5) +
  geom_smooth(method = "lm") +
  labs(x = "Eruption length (minutes)", y = "Waiting time (minutes)",
       title = "Longer eruptions are followed by longer waits")

ggplot(ToothGrowth, aes(x = factor(dose), y = len, fill = supp)) +
  geom_boxplot() +
  facet_wrap(~ supp) +
  labs(x = "Dose (mg/day)", y = "Tooth length", fill = "Supplement") +
  theme_minimal()

ggsave("toothgrowth.png", width = 6, height = 4, dpi = 300)

Read the second call aloud: take ToothGrowth, map dose (as a category) to x, length to y and supplement to fill colour; draw box plots; make one panel per supplement; label everything; use a minimal theme. Changing a box plot into a violin plot means changing one word, geom_violin(); adding colour by another variable means adding one mapping. That composability is why ggplot2 is so popular, and why it works best with tidy (long) data, where every visual property you might want to map is a column.

Whichever system you use, a few principles make plots honest and readable: label axes with units; start bar charts at zero (other plots need not); prefer position over colour for the comparison that matters; use colour palettes that people with colour-vision deficiencies can distinguish (ggplot2's scale_colour_viridis_d() is one); and show the data, not just a summary, when there are few enough points.

ComputationC

Packages and CRAN

A package bundles R functions, data, documentation and tests. R itself comes with the base packages (base, stats, utils, graphics and others) and a set of recommended packages (such as MASS, lattice, survival and mgcv). Everything else is installed from a repository:

r
install.packages("ggplot2")          # download from CRAN and install: once per machine
library(ggplot2)                     # attach: in every session that uses it
ggplot2::ggplot(faithful)            # or call one function without attaching
update.packages()                    # update installed packages

install.packages("BiocManager")      # Bioconductor: packages for genomics and biology
BiocManager::install("limma")

CRAN checks every package on several operating systems and R versions, and requires it to pass R CMD check without errors before it is published, which is part of why R packages are generally dependable. Bioconductor is a separate, curated repository for bioinformatics, with its own release cycle. Packages still in development are often installed from GitHub with the pak or remotes packages, and R-universe builds packages from many sources.

r
# Which packages are attached in a fresh session (Rscript --vanilla)?
search()

# The base and recommended packages come with R; ask for their versions.
packageVersion("stats") >= "4.1.0"
"survival" %in% rownames(installed.packages())

# pkg::fun calls a function without attaching the package.
tools::file_ext(c("report.qmd", "data.csv"))
stats::median(c(5, 1, 9))

# requireNamespace() checks for a package without stopping if it is missing:
# the usual way to make an optional dependency optional.
has_pkg <- function(p) requireNamespace(p, quietly = TRUE)
print(has_pkg("tools"))
print(has_pkg("surely.not.a.real.package"))

# Record what your results depend on: R itself, the platform, the packages.
info <- sessionInfo()
class(info)
info$R.version$language
text
[1] ".GlobalEnv"        "package:stats"     "package:graphics"
[4] "package:grDevices" "package:utils"     "package:datasets"
[7] "package:methods"   "Autoloads"         "package:base"
[1] TRUE
[1] TRUE
[1] "qmd" "csv"
[1] 5
[1] TRUE
[1] FALSE
[1] "sessionInfo"
[1] "R"

search() lists where R looks for names, in order: your own workspace first, then each attached package. library(pkg) adds a package to this list; if two attached packages define a function with the same name, the one attached last wins (R prints a "masked" message). The pkg::fun form avoids that ambiguity, and many professionals use it in scripts for any function outside the base packages, so that a reader can see where each function comes from. requireNamespace() returns TRUE or FALSE instead of failing, which is how code makes a package optional (here its result had to be printed explicitly, because it is returned invisibly).

ExplanationH

Reproducible environments and reports

An analysis that ran last year should give the same results today. Three things threaten that: the data changes, the code changes, and the packages change underneath it. The first two are handled by keeping raw data unedited and the code in version control (Git). The third is handled by recording package versions:

r
renv::init()       # give this project its own package library and a lockfile
renv::snapshot()   # record the exact version of every package in renv.lock
renv::restore()    # on another machine, or next year: install exactly those versions

renv keeps each project's packages separate, so upgrading a package for one project cannot break another, and its renv.lock file, committed alongside the code, lets anyone recreate the environment. Calling sessionInfo() at the end of a report records the R version, platform and package versions that produced it. For complete control, teams run R in containers, for example the Rocker project's Docker images, which pin the operating system as well.

The last step is the report itself. R Markdown (.Rmd, rendered by the knitr and rmarkdown packages) and its successor Quarto (.qmd, a standalone program that also supports Python and Julia) let you write a document in Markdown with code chunks embedded in it. Rendering the document runs every chunk in a fresh session and inserts the results, tables and figures, so the numbers in the text can never drift away from the code that produced them:

markdown
---
title: "Old Faithful waiting times"
format: html
---

The geyser's waiting times have two peaks.

```{r}
#| echo: false
hist(faithful$waiting, breaks = 20, main = "", xlab = "Minutes")
```

The median wait was `r median(faithful$waiting)` minutes.

Rendering with quarto render report.qmd (or rmarkdown::render("report.Rmd") for R Markdown) produces an HTML page; changing format: to pdf or docx produces a PDF or Word document from the same source. Chunk options such as echo: false hide code from readers who only want results, and inline code such as the median above puts computed numbers directly into sentences. Quarto also builds slide decks, websites and books; Posit, which develops both tools, presents Quarto as the successor for new projects, while R Markdown remains widely used and supported.

DefinitionsH

The tidyverse in one table

Definition— The tidyverse

The tidyverse is a collection of R packages for data science that share a design philosophy, a style of naming and the tidy data format. install.packages("tidyverse") installs them all, and library(tidyverse) attaches the core set.

PackageWhat it does
ggplot2graphics with the grammar of graphics
dplyrfilter, select, mutate, join and summarise data frames
tidyrreshape data (pivot_longer, pivot_wider) and handle missing values
readrread and write rectangular text files quickly
tibblea modern data frame that prints compactly and never drops to a vector
purrrfunctional programming: map() and friends, the tidyverse's apply family
stringrconsistent functions for working with strings
forcatstools for factors: reordering, lumping and relabelling levels
lubridateparsing and arithmetic with dates and times

You have seen most of their base R counterparts in this course. The tidyverse's strengths are consistency (data first, verbs as names, predictable outputs) and excellent documentation; its costs are more dependencies and an API that has evolved, so code written several years ago sometimes needs updating. Many teams mix both, and the free book R for Data Science teaches the tidyverse approach thoroughly.

ComputationC

Testing R code

Code that others rely on should be tested automatically. The standard tool is testthat: tests live in files under tests/testthat/, each test states expectations about a function's results, and devtools::test() (or testthat::test_dir()) runs them all and reports failures:

r
# tests/testthat/test-convert.R
test_that("temperatures convert between scales", {
  expect_equal(convert_temp(0), 32)
  expect_equal(convert_temp(98.6, from = "F"), 37)
  expect_error(convert_temp("hot"), "must be numeric")
})

testthat is not installed where this course is checked, so here is the same idea in base R, with a small test runner written from scratch. It is not something to use instead of testthat, but it shows exactly what a test framework does: run each expectation, catch failures, report, and count.

r
# The function under test: convert a temperature between scales.
convert_temp <- function(x, from = c("C", "F")) {
  from <- match.arg(from)
  if (!is.numeric(x)) stop("x must be numeric")
  if (from == "C") x * 9 / 5 + 32 else (x - 32) * 5 / 9
}

# A tiny test runner in base R. testthat does this, and much more, for real projects.
test <- function(name, expr) {
  ok <- tryCatch({ expr; TRUE }, error = function(e) {
    cat("FAIL:", name, "-", conditionMessage(e), "\n"); FALSE
  })
  if (ok) cat("ok:  ", name, "\n")
  invisible(ok)
}
expect_equal <- function(actual, expected) {
  if (!isTRUE(all.equal(actual, expected))) stop("got ", format(actual), ", expected ", format(expected))
}
expect_error <- function(expr) {
  failed <- tryCatch({ expr; FALSE }, error = function(e) TRUE)
  if (!failed) stop("expected an error, got none")
}

results <- c(
  test("freezing point", expect_equal(convert_temp(0), 32)),
  test("body temperature", expect_equal(convert_temp(98.6, from = "F"), 37)),
  test("vectorised", expect_equal(convert_temp(c(-40, 100)), c(-40, 212))),
  test("rejects text", expect_error(convert_temp("hot"))),
  test("rejects unknown scale", expect_error(convert_temp(1, from = "K"))),
  test("a deliberately wrong expectation", expect_equal(convert_temp(10), 50.5))
)
cat(sum(results), "of", length(results), "tests passed\n")
text
ok:   freezing point
ok:   body temperature
ok:   vectorised
ok:   rejects text
ok:   rejects unknown scale
FAIL: a deliberately wrong expectation - got 50, expected 50.5
5 of 6 tests passed

The runner relies on the lazy evaluation you met in Functions, control flow and the apply family: expr is not evaluated until tryCatch() forces it, so an error inside the expectation is caught and reported rather than stopping the script. all.equal() compares with a tolerance, which is why 98.6 °F converts to "37" despite floating-point rounding. The deliberately wrong expectation shows what a useful failure message looks like: what was obtained and what was expected.

How professionals check R code

When analysis code grows into a package, it gains a standard structure (a DESCRIPTION file listing dependencies, an R/ folder of functions, tests/, and documentation generated from #' comments by roxygen2), and a standard set of tools. usethis creates the structure, devtools builds, documents, tests and installs it, and R CMD check (run by devtools::check()) runs dozens of checks that CRAN also runs. lintr flags style problems and likely bugs, styler reformats code to the tidyverse style guide, and continuous-integration workflows such as the r-lib project's GitHub Actions run the checks on every change on Windows, macOS and Linux. Even for code that will never be a package, keeping functions in files, tests beside them and a linter running in the editor catches mistakes long before they reach a report.

Common misconceptionsH

Common confusions

Misconception

"library(pkg) downloads the package." install.packages("pkg") downloads and installs it, once per machine (or per renv project); library(pkg) attaches an installed package to the current session, every time. Scripts should call library() but not install.packages(), which changes the user's machine and needs a network connection; list the dependencies instead, or let renv restore them.

Misconception

"set.seed() makes an analysis reproducible." It makes the random numbers reproducible, given the same R version and the same code. Package versions, data versions and even the order of operations matter too. Reproducibility is the combination: raw data kept unchanged, code under version control, package versions recorded, seeds set, and a report rendered from scratch.

Misconception

"A screenshot of the plot window is good enough for a report." Screenshots have the resolution of your screen and the size of your window. Write figures with a device or ggsave() at a stated size: PNG with a high dpi for slides and web pages, and vector formats such as PDF or SVG for print, which stay sharp at any zoom.

Exercises

Exercises

1. Plots, packages and reproducible reports

CoreComputational

What does this print? Write it with single spaces.

x <- c(3, 10, 10, 14, 20, 29)
hist(x, breaks = seq(0, 30, by = 10), plot = FALSE)$counts

2. Plots, packages and reproducible reports

CoreComputational

A box plot draws points beyond the whiskers individually. How many values does this print?

boxplot.stats(c(10, 12, 13, 14, 15, 16, 2, 30))$out

3. Plots, packages and reproducible reports

Warm-upHuman

A colleague's analysis script begins with install.packages("ggplot2") followed by library(ggplot2). What is the best change?

Choose one

4. Plots, packages and reproducible reports

CoreHuman

The stats package, attached by default, has a function filter(). You then run library(dplyr), which also defines filter(). Which function does a plain call filter(...) now use?

Choose one

5. Plots, packages and reproducible reports

CoreHuman

You used renv in a project. Which file must you commit to Git so that a colleague can install exactly the package versions you used?

Choose one

6. Plots, packages and reproducible reports

Warm-upHuman

In the lesson's ToothGrowth plot, what do you change to draw violin plots instead of box plots, keeping everything else the same?

Choose one

7. Plots, packages and reproducible reports

StretchComputational

What does all.equal(1, 1.1) print? Write it exactly as R prints it, with single spaces.

Further reading and resources