ggplot2: field manual

Author

Martin Frigaard

Welcome!

Welcome to the ggplot2 field manual!

I created this book as a sort of online ‘quick reference’ to help me answer questions like:1

  • “What graph should I use?”

  • “What kind of graph is that?”

  • “Can (or should) I build that graph?”

What’s new in this edition

Previous versions of this book used datasets from data packages, and a single, consistent plot theme. I’ve rebuilt the examples in this manual around simulated data, and each section has its own theme.

Why simulated data?

Earlier versions borrowed datasets from packages like palmerpenguins, fivethirtyeight, and ggplot2movies. Those are great example datasets, but each one meant another package to install, and the shape of the data was whatever the real world handed us.

I’ve built many data visualizations since writing the first edition of this book, and found myself asking questions like, “What should this graph be showing? Or what if the data were collected under slightly different conditions??

Simulating the data gave me control over the distribution and structure, something I couldn’t do with real datasets. Building the distributions also forced me to think about each graph differently before I started drawing it. I highly recommend reviewing the code I used in each chapter to create the data. It’s usually only a few lines of code; most of it uses base R (like rnorm(), rpois(), and sample()) or a handful of user-written packages (like faux).

The simulated data connects the numbers to the picture in a new Distribution section, so you’ll see why a histogram is shaped like a bell and why a box plot shows so many outliers, not just how to build it.

ImportantWho actually wrote this

Given the landscape of LLMs and AI slop, I now feel it’s important to clarify the authorship of anything I write. It seems strange to include this note, but if I were reading a book/blog post/article, I’d want to know.

I used LLMs (only Claude from Anthropic) to research specific distribution topics and help write code to generate the simulated data. I’d typically write a ‘first draft’ of a code example, then ask Claude how to improve it. Sometimes I agreed with the suggestions (and included them). Other times I revised the code myself.

I wrote all of the narrative, description, and code explanations, so the thoughts in the book are my own. Hopefully, the typos and/or grammatical errors serve as a signature of authenticity.

I also wanted the examples to be fun to read, so every dataset is a late 90s throwback. You’ll find Talkboy messages, Blockbuster rentals, Pokémon starters, and Mario Kart 64 lap times, and each one is drawn with a matching theme (Windows 98, the original Game Boy, the Nintendo 64, and more). The themes live in the fmggp2 package, which also holds the helpers used throughout the book.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', 'fontSize': '14px', 'darkMode': false}}}%%

flowchart TB
    dist(["<strong>Distribution</strong><br>normal, Poisson,<br>gamma, ..."]) -->|"i. set.seed()"| sim["<strong>Simulate</strong><br>base R or <code>faux</code>"]
    sim --> dset[("<strong>90s dataset</strong><br>OK Soda, Pogs,<br>Happy Meals, ...")]
    dset -->|"ii. Distribution section"| connect["<strong>Connect</strong><br>count it, draw it,<br>name it"]
    connect -->|"iii. Grammar section"| gg[["<strong>ggplot2 graph</strong><br><code>fmggp2::theme_*()</code>"]]

    style dist fill:#4CBB9D,color:#FFFFFF,rx:5,ry:5
    style sim fill:#FFFFFF,color:#000000,stroke:#333
    style dset fill:#C0C0C0,color:#000000,stroke:#333
    style connect fill:#FFFFFF,color:#000000,stroke:#333
    style gg fill:#000080,color:#FFFFFF,rx:5,ry:5

How each chapter builds its example

Getting started

  • Option 1: install ggplot2 using the code below:

    install.packages("ggplot2")
library(ggplot2)

  • Option 2 (recommended): ggplot2 is also part of the tidyverse

    install.packages("tidyverse")
library(tidyverse)

  • Install fmggp2 to use the 90s themes from the book:

    install.packages("pak")
pak::pak("mjfrigaard/fmggp2")
library(fmggp2)

Who this book was written for

I created this resource with the following learner personas in mind:

  1. Garth is a data analyst putting together a slide deck for an upcoming meeting. He had a few statistics courses with R in college, and has picked up additional experience and skills from the different positions he’s held and various online tutorials. He’s currently building the graphs in his slides with ggplot2, but had grown tired of them and would like to customize his presentation to make it more engaging.

  2. Matilda is a data journalist hoping to add a few graphs to a piece she has been working on. She has 10 years of experience working with WordPress, writes and publishes on her own blog, and has an intermediate understanding of HTML & CSS. However, she has only been programming in R for about 6 months.

  3. Igor is a researcher who has been working in academia for 15 years. He’s comfortable writing R code, knows the kinds of graphs he’d like to build, but he only knows how to build these using the base R graphics. He’d like to learn how to duplicate the graphs he’s already created in base R using ggplot2.

Where to learn more

Because this is intended to be a field manual (and not a textbook), I’ve omitted most of the underlying principles and structure of the ggplot2 syntax.

If you’re looking for comprehensive resources on ggplot2, I recommend the excellent free text, the ggplot2 website, and Data Visualization: a practical guide by Kieran Healy.

If you know the graph you’d like to build, and you’re just looking for the code or package(s) to build it, I’d check out the R graph gallery or R graphics cookbook.

Another question to consider–but not covered in this manual–is, “who will the audience be for this graph?”

Great resources for this include the Insightful Data Visualizations for “Uncreative” R Users course by Albert Rapp, Communicating with Data: The Art of Writing for Data Science by Deborah Nolan and Sara Stoudt, and the Truthful Art, The: Data, Charts, and Maps for Communication, by Alberto Cairo.

  1. Most of these questions come from #TidyTuesday↩︎