Building Code Movies With flipbookr
This is a guest post from Gina Reynolds with contributions from Rachel Goodman, Luca Picci, Conner Surrency, and Brit Woodrum, who provided research assistance while completing their Masters’ at the University of Denver’s Josef Korbel School of International Studies. Gina taught research methodology at University of Denver from 2018 to 2020 and currently teaches statistics and probability at West Point. Her research focuses on tools for proximate comparison and translation for data analysis and visualization.
Have you heard of “code movies” or “code flipbooks”? Maybe not? This blog post will tell you what they are, introduce the flipbookr package to help build them in R, and showcase student work as examples.
I use the terms ‘code movies’ and ‘flipbooks’ interchangeably.
What Are Flipbooks?
Flipbooks help you demonstrate how to get from ‘A’ to ‘B’ in data manipulation, analysis, or visualization code pipelines. When using R Markdown or Jupyter notebooks, we usually only see the initial input and final output for a pipeline of steps. Having the inputs and outputs close to one another helps communicate the big picture of what is being accomplished with a chunk of code.
But you might have trouble figuring out what the individual steps in a pipeline accomplish. This is where flipbooks come in! They seek to illuminate what’s going on in each step of the pipeline or plot. Flipbooks show the within-pipeline output for every line of code.
Here’s an example where we build a ggplot with the mtcars dataset. We build the plot and then add an annotation to describe the components of a boxplot.
Click in the frame below and use arrows or swipe to go through the slideshow and see the plot build with each new line of code.
Code Movie Examples
You may have seen code movies in coding presentations. Presenting pipelines as a movie helps audiences digest workflows, so it’s worth choreographing a set of slides to break down them. If the alignment between slides is good — and if we don’t have disruptive slide transitions (wipes, spins, fades) — we get to enjoy a little movie: the coordinated evolution of code and output! Here are some examples:
Building Flipbooks Quickly and Reliably With flipbookr
While code movies deliver helpful insight to audiences, it can be time consuming to put together the experience. There’s a lot of copy-and-paste that has to happen to create the right partial code sequence — and you can mix yourself up trying to coordinate it (I’ve been there!).
The flipbookr package’s goal is to help create these easy-to-follow, step-by-step experiences — without the copy-and-paste pain! All you need to do is write your pipeline once. Then, you can let flipbookr take over to create a flipbook that shows the code and its corresponding output.
Together with the R Markdown slideshow package xaringan, flipbookr does four things:
- Parses an .Rmd code pipeline from the chunk you indicate (you name the chunk),
- Identifies good break points in that code chunk pipeline (the default is finding balanced parentheses at the ends of lines),
- Spawns a bunch of code chunks with these partial builds of code, separated by slide breaks, and
- Displays partial code in HTML slides.
The slides are shown side-by-side and sequentially, giving us a movie-like experience.
There is so much decision-making packed into our code pipelines. The flipbookr project makes it easy to bring those decisions to light so they can be appreciated, examined, and discussed!
Taking flipbookr for a Spin
After installing flipbookr with install.packages("flipbookr"), there are a couple of ways to get started:
- Use the Easy Flipbook Recipes guide. You can put together a basic flipbook with step-by-step instructions.
- Use the “A Minimal Flipbook” template that comes with the flipbookr package. After installation, you can request the basic template in the RStudio IDE by going to
File -> New File -> R Markdown -> From Template -> A Minimal Flipbook.
What to Expect: flipbookr Examples
Before you start building your own flipbooks, it might also be useful to see some examples from some other folks.
Four of my graduate research assistants at the University of Denver’s Korbel School of International Studies, with the support of an R Consortium grant, have built excellent flipbooks that showcase ggplot2 mapping, tmap, magick, and gganimate.
Rachel demos how to build maps with ggplot2 by looking at the political landscape in Idaho. She uses several thematic elements with the theme() function. Her flipbook displays the incremental effect of each thematic decision.
Rachel also contributed this comment about how building plots intended for a flipbook differs from the usual build:
“The process of producing a flipbook pushed me to think differently about both data wrangling and data visualization. It required me to be more deliberate in how I wrote and ordered my code, and it revealed redundancies and other inefficiencies in my script. The process also deepened my understanding of the commands that I employed by allowing me to see the output of each individual line of code.”
Conner explores the tmap package by showing city population sizes in Australia. He also dives into world map projections, cycling through various tmap projection options.
Brit demos the magick package, showing how image manipulation pipelines unfold.
Finally, Luca visualizes changes in youth unemployment in Europe, first by faceting in ggplot2 by year and then using gganimate.
Acknowledgments
The flipbookr package builds code movies using the wonderful xaringan, knitr, and R Markdown tools. It’s inspired by data manipulation and visualization tools that let you work incrementally, particularly ggplot2, dplyr, and magrittr.
Lots of folks have helped build flipbookr, especially Emi Tanaka and Garrick Aden-Buie. Garrick’s code movie in ‘A Gentle Guide to the Grammar of Graphics’ is the first one I noticed and is not to be missed! Both Garrick and Emi Tanaka were inspired to work on automating the code movie build and helped get the flipbookr project off the ground.