Flipbooks

Flipbooks present code step-by-step and side-by-side with its output. The incremental code/result reveal help people digest longer manipulation and analysis pipelines as well as plot builds. Two helpful features are incrementalism and movie-like presentation.

Incrementalism

Long pipelines of code can produce attractive outputs. But when an observer knows only initial input and final output, a pipeline can feel like a long stretch of highway that has no exit or entry ramps. Flipbook are designed to give users a lot of on and off ramps even for long pipelines; in a flipbook, the users can isolate and gain insight about short stretches along the pipeline that are useful for their particular project – all the while engaged by the creativity brought by the author in pursuit of his or her original goal. Flipbooks enable us to isolate how individual functions work in context.

Movie-like presentation

The presentation of intermediate states on via slide-show presentation platform means that states can be aligned and superimposed. This way, the audience doesn’t need to engage in visual search which requires focus and concentration – but rather effortlessly observes changes via motion detection. Temporal rather than spatial offset makes it easy to notice changes to the code and the resultant changes to the output.

To get a sense of how they work, click once in the example box the below to initiate the session; then use the right and left arrow to “flip” through the book to see how to make an animated “racing” bar chart of the population size of the most populous countries over time.

Flipbook Topics

For easier reference, I’ve sorted instructive flipooks into three main categories. You can link to guides to further subtopics here:

Data Wrangling Data Visualization with ggplot2 Statistical Analysis

Mostly, I’ve created these resources while preparing for my classes at the Korbel School of International Studies at the University of Denver. So many thanks due to my students for being such an amazing and motivating bunch. These repositories are my teaching materials, and are constantly being updated and revised.

Create your own flipbook

Would you like to make a flipbook? We try to make that easy for you with {flipbookr}. To get started have a look at A minimal Flipbook, the template for which will be available once you install the flipbook building package {flipbookr}. The steps to building your first flipbook are as follows:

Install the slide show platform Xaringan - install.packages("xaringan")
Install flipbookr - remotes::install_github("EvaMaeRey/flipbookr")
Restart R
Get the template in RStudio via: File -> New File -> RMarkdown -> From Template -> A Minimal Flipbook
Use this template to get started or replace with your own pipelines
Compile your document - “Knit” in RStudio
Explore your flipbook!

Once you have completed steps 1-3, you can also follow along with the live demo that I presented at the RStudio Conference, 2020 (the demo is at 6’25") — but consider using the setup code chunk in the template — I don’t do this in the demo!

The template (step 4) will create the following book, which contains examples of flipbooking modes:

But we’ve all got issues

Here are a few known issues to watch for:

You will need an internet connection to build Xaringan output, unless you use this set up:
- within a project execute xaringan::xaringan::summon_remark() in your console
- then in the YAML right after your css declaration, add, chakra: libs/remark-latest.min.js
Comments in flipbooked pipelines should not contain parentheses
Quoted text may not span lines (quoted text must be on a single line)
Xaringan produces an html file and associated files. This means:
- The output is not one, self-contained file
- Output to be displayed in the flipbook must be supported in Xaringan and html
{flipbookr} is a development package and is subject to change.

Contributing Feedback

We’d love to hear from you! How is your flipbook building experience? You can contribute feedback via Twitter @EvaMaeRey and via issues on Github.com/EvaMaeRey/flipbookr.

Implementation

If you are interested in contributing to {flipbookr}, you might consider getting some of the intuition of the internal functions by browsing through the resource below, or link to it here:

Origins

In mid 2018 Garrick Aden-Buie, a data scientist at the Moffitt Cancer Center, created and debuted a side-by-side format for code and figure output in the slide-show tool, Xaringan, an RMarkdown tool. He demonstrated in incremental steps how someone might build up a plot using the popular R visualization package ggplot2. In August 2018, I emulated this work, but using a code style I developed which I called “slowggplot2”, which is entirely sequential and more incremental than typical workflows. This style uses one ggplot function for every plotting decision that is made (when possible); this format is ideal for automatically parsing and reconstructing partial builds of the plots; and reconstructions clearly connect the coding decision and associated behavior because differences between states is small. In September, Emi Tanaka, a Lecturer in Statistics at the University of Sydney, implemented a similar sequential workflow demonstration, which she partially automated.

I approached Garrick and Emi in October about working together on “flipbooks”. We soon had a fully automated framework to parse ggplot2 code, and present the code reconstruction along with associated output!

The procedure to automatically parse and reconstruct code was tested and refined on small projects. Then, I created a “flipbook” of a sizable collection of my portfolio of data visualizations, originally created for the initiative #MakeoverMonday. I publicized the work in February, 2019; the ggplot flipbook was met an enthusiastic reception.

Since then, there have been a number of changes to the fundamental code to improve the tool and to extend use cases. Many of the capabilities that have been added are also discussed in the template.

Adding more “connection” operators as break points for code (%>%, ->, %+%, %$%) to enable presentation beyond data visualization (initially we only used the +)
Allowing code wrapping (breaks occur not necessarily at the end of lines)
Determining partial code completeness based on parentheses balancing
Using code parser rather than regular expressions to identify role of text segments
Allowing the user to define the reveal points (with the special #BREAK comment)
Allowing the user to define non-sequential reveal (with #BREAK2, #BREAK3 etc)
Allowing code to be multiply revealed (multiple realizations of same code)
Allowing for output only or code only display (as opposed to just side by side)
Tracking objects created with left assignment
Separating the parsing, code reconstruction, and presentation platform delivery steps, to make code more flexible, and robust.

Featured examples

You can link to some flipbooks here:

If you need a theoretical exploration of the grammar of graphics and its use with ggplot2, see a ggplot2 grammar guide.

The geom pile on is a suppliment to the ggplot grammar guide and shows you a lot of “geoms” that you can use to communicate about your data. Piling up the geoms allows you to see how plot types relate to one another.

ggplot themes takes you through logic of the ggplot2 theme adjustments.

For examples of data wrangling/manipulation with pipelines and pipes (%>%), check out The Tidyverse in Action.

geom_sf gives you an example of using geom_sf with ggplot to create coordinate plots and choropleths.

ggtext gives you an example of the how the new ggtext package can be used; this example by Klaus Schulte.

the data cleaning flipbook gives you some life-changing, magical, and real-life examples of reading data into R and cleaning it (aka “tidying up”). Demonstrates uses of {janitor}, {countrycode}, and {lubridate} as well as regex with {stringr}.

the ggplot flipbook is a gallery example plots built using ggplot2.

Galton Board shows you how to build your own Galton Board with R, ggplot2, and gganimate.

leaflet for R (interactive maps) walk through some interactive map builds using the {leaflet} package (loads slow!).

the racing barchart will give you a chance to flex your ggplot2 and gganimate muscles.

easing gallery for gganimate

D’Hondt/Jefferson Allocation helps to explain just how seats are allocated under this common political decision rule.

UNGA voting data is a flipbook that looks at the number of votes taken in the UN General Assembly. It also shows how you can make a lot of lateral moves and even backward steps with your decisions in ggplot2 - like with facet_null() and overwriting aesthetic decisions with NULL - aes(color = NULL).

a data.table flipbook is an introduction to the popular data manipulation package, {data.table}.

#TidyTuesday walk through showcases a few of the beautiful contributions to the #TidyTuesday initiative

Stacked Column -> Pie Chart reveals some of the deep logic of the grammar of graphics — Stacked column plots, and pie plots and donut plots are related by choices in coordinate systems and extent of axes.

Reception

The feedback on the flipbook format has been very encouraging (thank you if you were a part of this!) and a big motivation to keep working on this project. The ggplot flipbook was a top story on Hacker News and was featured as a highlight in the R Weekly newsletter.

Some of the most encouraging feedback about flipbooks has come from individuals, via Twitter. Their comments can be viewed here. Feedback comes from individuals around the world including the following locations: