6 min read

Use Flipbooks to Explain Your Code and Thought Process

Tags: dplyr tidyr purrr ggplot ggbeeswarm animatrixr emo rlang fs pagedown magick here pdftools officer flair flipbookr

2020-06-24

Learning R’s %>%

Using the pipe operator (%>%) is one of my favorite things about coding in R and the tidyverse. However when it was first shown to me, I couldn’t understand what the #rstats nut describing it was so enthusiastic about. They tried to explain, “It means and then do the next operation.” When that didn’t click for me, they continued (while becoming ever more excited) “It passes the previous steps output into the first argument of the next function,” still… 😐😐😕. Self-evident verbs in their code like select(), filter(), summarise() helped me nod along, partly following the operations. Though it wasn’t until I evaluated the code line-by-line that I recognized the pipe’s elegance, power, beauty, simplicity 😄!

Now, a few years and reads through R for Data Science later1, I will often share my work by keeping the code and output together and showing, line-by-line, what I am building towards. For example when…

… giving a 2019 talk on “Managing objects in analytics workflows, using lists as columns in dataframes”:

… giving a 2017 talk on “Getting started with ‘tidy’ data science in R”:

… promoting a recent blog post on “Tidy pairwise operations” (though in this case I removed the code):

However each of these examples were built using PowerPoint (and a lot of copy and pasting of code + output). The series of images cannot be easily reproduced. In this post I’ll point to resources on how to create these sorts of code communication materials in ways that are reproducible.

Flipbooks

When I started writing this post, I planned to call this type of output a “LEXPREX” for “Line-by-line EXecution with PRinted EXamples” (and a name evocative of the inspiring reprex package by Jenny Bryan2). But, thankfully, an excellent solution containing thorough explanations (and a much better name) already existed, flipbooks.

As described in the flipbookr documentation, “flipbooks are tools that present side-by-side, aligned, incremental code-output.”

(Example inspired by ‘Many Models’ chapter of ‘R For Data Science’ by Grolemund & Wickham.)

At this point you should stop reading this blog and instead go learn about flipbookr. My post was largely written before I learned about this package. Hence, starting at this presentation by Gina Reynolds or flipbookr’s about page will generally be a more productive use of your time. The remainder of this post discusses either tools adjacent to flipbooks or describes workflows that can also be found within flipbookr documentation.

Example with xaringan

The xaringan package for making slideshows contains highlighting features (and is what flipbookr is built-on). For highlighting code you can use the trailing comment #<<3. For highlighting output there is the highlight.output code chunk option.

Mitchell O’Hara-Wild’s 2019 presentation on “Flexible futures for fable functionality” contains a helpful example where he uses these features to walk-through his code.

See More sophisticated highlighting if your use-case requires more than line-level highlighting.

Animating a flipbook

I sometimes want to convert a flipbook into a gif, e.g. when sharing an example in a README or a snippet of a concept on social media. If you ignored my prior entreaty, this is a second reminder to stop and go read about flipbookr. The template file now shows how to create gifs using flipbookr (html) –> pagedown (pdf) –> magick (gif). I also describe this workflow and provide examples here, e.g.

(Example from a prior blog post, “Riddler Solutions: Pedestrian Puzzles”)

Closing note

I recommend exploring the Rstudio Education blog. The site contains helpful resources for improving your technical communication. It was here that I stumbled on the post Decorate your R code with flair. Reading this inspired me to make a first attempt at building a reproducible animation of line-by-line execution of R code (something I’d been wanting to do for ages). The positive response & feedback to my initial tweet led me to learn about flipbookr and motivated additional actions (described in Engagement & contributions) including the review and completion of this blog post.

Finally, please go enjoy the beautiful examples you can find at the flipbookr about page:

Appendix

More sophisticated highlighting

For more sophisticated highlighting of code, use the flair package. I’m not sure what to recommend for highlighting changes in output to the console… perhaps diffobj would be an option. You could also just explicitly format the output, e.g. using gt or kableExtra for tabular outputs, or using geoms, annotations, etc. in ggplots. And, of course, you can always dive into the html.

Engagement & contributions

Blogging is time consuming. Reaching out to package maintainers or making contributions (even small ones) on open-source software projects can be intimidating. As a tiny success story, I documented actions that stemmed (in some part) from engaging with the #rstats online communities while working on this blog post topic:

  • While this post was in draft form, I tweeted out my initial approach (that used the flair package).
    • The next step might have been trying to improve upon this. Thankfully, instead, Kelly Bodwin pointed me to flipbookr!
  • Kelly also created an issue to further discuss possible integrations between flair and flipbookr.
  • I remade my initial example using flipbookr (see issue).
    • I first created an issue showing how to print xaringan slides incrementally using pagedown::chrome_print().
      • Which helped to close a related issue on xaringan.
  • Gina Reynolds made a variety of updates to flipbookr, one of which included adding the html –> pdf –> gif workflow to the template 😄.

  1. See my notes and solutions here.↩︎

  2. I also considered names such as pexprex, sexprex, pripex, … I’ll let the reader guess at the acronyms.↩︎

  3. Which I prefer over the alternatives of using the leading * or wrapping the message in{{}}.↩︎