Use Flipbooks to Explain Your Code and Thought Process
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
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):
What is your #tidyverse (or other #rstats ) approach for doing arbitrary pairwise operations across variables? Mine is frequently something like:
— Bryan Shalloway (@brshallo) June 11, 2020
I. nest…
II. expand combos…
III. filter…
IV. map fun(s)…
…
I wrote a post walking through this: https://t.co/xRnRf5yh3m pic.twitter.com/Zvxey2gm3H
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.”
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.
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
!
- The next step might have been trying to improve upon this. Thankfully, instead, Kelly Bodwin pointed me to
P.S.
— Kelly Bodwin (@KellyBodwin) June 16, 2020
Theflair_lines()
function lets you highlight whole line(s) if you want!
{flipbookr} is a better option for making gifs/slides like this, but {flair} + {pagedown} + {magick} might help if you want specialty or layered highlighting.
- Kelly also created an issue to further discuss possible integrations between
flair
andflipbookr
. - I remade my initial example using
flipbookr
(see issue). - Gina Reynolds made a variety of updates to
flipbookr
, one of which included adding the html –> pdf –> gif workflow to the template ?.
Big thanks to @grrrck and @statsgen for helps and @xieyihui because {xaringan}! And to @brshallo and @KellyBodwin for new ideas about how to share flipbooks, html -> pdf -> gif. Guidance now included in template update on this - this gif created w/ that workflow!??
— Gina Reynolds (@EvaMaeRey) June 21, 2020
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.