reprex 1.0.0

We’re exhilarated to announce the release of reprex 1.0.0 ( reprex.tidyverse.org). reprex is a package that helps you prepare REPRoducible EXamples to share in places where people talk about code, e.g., on GitHub, on Stack Overflow, and in Slack or email messages.

You can install the current version of reprex from CRAN with¹:

install.packages("reprex")

It turns out we’ve never blogged about reprex here on tidyverse.org, so we start with a general overview for newcomers, then close with a summary of recent changes of interest to existing users.

You can see a full list of changes in the release notes.

Why reprex exists

reprex is a convenience package that combines the power of R Markdown with conventional wisdom about what makes a good reproducible example. We believe that conversations about code are more productive with:

• Code that actually runs
• Code that the reader doesn’t necessarily have to run
• Code that the reader can easily run

Someone new to R might be puzzled by this code and want to discuss it:

x <- factor("Hello, ")
y <- factor("world!")
x
#> [1] Hello, 
#> Levels: Hello,
y
#> [1] world!
#> Levels: world!
c(x, y)
#> [1] 1 1

You, as a reader, just benefited from a few things:

1. The code was actually executed by the R interpreter, because this post is generated from an .Rmd document. I am probably not misleading you, intentionally or by accident, with fictional or incomplete code.

2. You got to see the actual result without firing up R yourself and executing this code locally. Many R veterans will instantly recognize what’s going on and be able to provide some useful explanation at this point.

3. If you do want to execute the code yourself, you can easily copy the entire chunk, paste it into R, and press enter². Compare that with the fussy edits you’d have to make with this copy/paste from the R Console:

   > x <- factor("Hello, ")
   > y <- factor("world!")
   > x
   [1] Hello, 
   Levels: Hello, 
   > y
   [1] world!
   Levels: world!
   > c(x, y)
   [1] 1 1
   

   You need to remove the > prompts and delete all output. And don’t get me started on the problem of screenshots.

All of this is entirely possible without reprex. People just need to create a suitable .R or .Rmd file, render it to an appropriate output format, in a fresh R session, with working directory set to session temp directory. And also send me a pony!

For any given code snippet, this feels like way too much work. But if you read, write, and talk about R often, this problem can easily come up multiple times per day. reprex::reprex() aims to make doing the right thing so easy that people stop taking photos of broken code with their cell phone.

reprex::reprex()

reprex::reprex() is the main function in the package. It takes a little bit of R code, probably from the clipboard or current selection, and does all the fiddly things we mentioned:

• Writes it to a file. By default, to a file below the session temp directory.
• Sets various R and knitr options that are especially favorable for reprexes, such as the error = TRUE chunk option.
• Renders the code in a fresh R session to ruthlessly expose missing library() calls and the use of objects that haven’t been defined.
• Ensures the output is optimized for the target venue, e.g. GitHub-flavored Markdown vs. commented R code vs. Rich Text Format.

By default, the result is waiting on your clipboard and you’ll also see an HTML preview of it.

Here is a 50 second video that shows an entire roundtrip: copying local code, reprex()ing, opening a GitHub issue, copying reprex from the issue, and re-executing the code in a local R session:

There are many other handy features:

• Optionally include session info
• Post a figure to imgur.com and embed its link in the reprex
• Handy RStudio addin and gadget for even more convenience
• More ways to provide input and get output

Head over to reprex.tidyverse.org to learn more. In addition to the articles there, reprex — as a lifestyle 🤓 and a package 📦 — features in my rstudio::global(2020) keynote about debugging. The reprex section starts around the 14:11 mark in the video.

What’s new in v1.0.0

For those who have been using reprex for a while, here are the most exciting developments in v1.0.0

Venues

We’ve added venue-specific convenience wrappers. Instead of reprex(..., venue = "r"), you can now do reprex_r(...). This makes non-default venues easier to access with IDE autocompletion.

"slack" is a new venue that tweaks the default Markdown output for pasting into Slack messages. Slack’s markup is a frustrating variant of the Markdown we use elsewhere and it’s important to remove the r language identifier from the opening code fence. We also simplify image links and, by default, suppress the ad. Note that venue = "slack" or reprex_slack() work best for people who opt-out of the WYSIWYG message editor³. While working on this, I appreciated for the first time that the default behaviour for figures (uploading to imgur.com and auto-linking) actually works pretty well for Slack messages. Who knew? 🤷‍♀ This is also a good time to remind everyone that venue = "r" or reprex_r() are great ways to create larger Slack code snippets. Before you finish by clicking “Create snippet”, select R from the “Type” dropdown to get nice syntax highlighting.

Stack Overflow now supports fenced code blocks, which means that the "so" venue is no longer necessary. You can still request it, but it’s just an alias for the default GitHub ("gh") venue and we’re going to tell you that every time you do it.

The experimental-but-oh-so-handy venue = "rtf" now works about as well on Windows as it does on macOS. It is experimental (and shall remain so) because we still shell out to the highlight command line tool, the installation of which is left as an exercise for the motivated user. This is a great way to get (un)rendered, syntax-highlighted code snippets into applications like PowerPoint, Keynote, and Word, when you aren’t generating the whole document with R Markdown. This special venue is documented in its own article.

Internal changes

This should have no impact on most users, but reprex() has been internally refactored to achieve its goals by applying the new reprex_render() to an .Rmd file that uses the new reprex_document() output format. The motivation was mostly to make maintenance easier by using more official mechanisms for extending R Markdown and knitr.

We have eagerly followed knitr’s lead and use UTF-8 everywhere internally.

The tidyverse_quiet argument and reprex.tidyverse_quiet option, which default to TRUE, also suppress startup messages from the tidymodels meta-package.

Remember you can see a full list of changes in the release notes.

Acknowledgements

We’ve never blogged about reprex here, so we’ll take this chance to thank all 116 people who have helped get reprex to this point. There have been 47 contributors since the previous release (v0.3.0).

@1029YanMa, @Abhijitsj, @aegerton, @alexpghayes, @alistaire47, @andresrcs, @assignUser, @atusy, @baptiste, @barryrowlingson, @batpigandme, @billdenney, @blairj09, @brshallo, @brunocarlin, @carlmorgenstern, @cderv, @chester-gan, @chris-prener, @chsafouane, @coatless, @ColinFay, @cooknl, @crew102, @cstepper, @cwickham, @daattali, @david-romano, @davidbody, @DavisVaughan, @dchiu911, @dgrtwo, @dpprdan, @dskard, @ellessenne, @emiltb, @filipwastberg, @franknarf1, @friendly, @gaborcsardi, @GegznaV, @gergness, @gvdr, @hadley, @harrismcgehee, @HeidiSeibold, @helix123, @Henrik-P, @HughParsonage, @IndrajeetPatil, @isteves, @j450h1, @jasonmtroos, @jayhesselberth, @jemus42, @jennformatics, @jennybc, @JiaxiangBU, @jimhester, @joelgombin, @JohnMount, @jooyoungseo, @juliasilge, @jzadra, @karawoo, @kevinushey, @krlmlr, @lbusett, @lionel-, @lizhiwei1994, @llrs, @lorenzwalthert, @maelle, @marionlouveaux, @markdly, @mattfidler, @maurolepore, @mcanouil, @mdlincoln, @mine-cetinkaya-rundel, @missaugustina, @moodymudskipper, @mrchypark, @mrdwab, @njtierney, @no-reply, @noamross, @npjc, @paleolimbot, @pat-s, @paternogbc, @PeteHaitch, @pgensler, @PiotrKoller, @PMassicotte, @prosoitos, @PublicHealthDataGeek, @r2evans, @rcorty, @restonslacker, @RLesur, @robjhyndman, @romainfrancois, @rpruim, @sckott, @scottcame, @sfirke, @sjspielman, @Tugsdelger, @tungmilan, @uribo, @wlandau, @yonicd, @yutannihilation, @zkamvar, and @zx8754.