If you’re asking for R help, reporting a bug, or requesting a new feature, you’re more likely to succeed if you include a good reprex.
Use the smallest, simplest, most built-in data possible.
mtcars. Bore me.
- If you must make some objects, minimize their size and complexity.
- Get just a bit of something with
head() or by indexing with the result of
sample(). If anything is random, consider using
set.seed() to make it repeatable.
dput() is a good way to get the code to create an object you have lying around, if you simply cannot make do with built-in or simulated data. Copy and paste the result of this into your reprex.
- Look at official examples and try to write in that style. Consider adapting one.
Include commands on a strict “need to run” basis.
- Ruthlessly strip out anything unrelated to the specific matter at hand.
- Include every single command that is required, e.g. loading specific packages via
Consider including so-called “session info”, i.e. your OS and versions of R and add-on packages, if it’s conceivable that it matters.
Whitespace rationing is not in effect.
Pack it in, pack it out, and don’t take liberties with other people’s computers. You are asking people to run this code!
- Don’t start with
rm(list = ls()). It is anti-social to clobber other people’s workspaces.
- Don’t start with
setwd("C:\Users\jenny\path\that\only\I\have"), because it won’t work on anyone else’s computer.
- Don’t mask built-in functions, i.e. don’t define a new function named
If you change options, store original values at the start, do your thing, then restore them:
If you create files, delete them when you’re done:
- Don’t delete files or objects that you didn’t create in the first place.
Take advantage of R’s built-in ability to create temporary files and directories. Read up on
This seems like a lot of work!
Yes, creating a great reprex requires work. You are asking other people to do work too. It’s a partnership.
80% of the time you will solve your own problem in the course of writing an excellent reprex. YMMV.
The remaining 20% of the time, you will create a reprex that is more likely to elicit the desired behavior in others.
The reprex code:
Must run and, therefore, should be run by the person posting. No faking it.
Should be easy for others to digest, so they don’t necessarily have to run it. You are encouraged to include selected bits of output. :scream:
Should be easy for others to copy + paste + run, iff they so choose. Don’t let inclusion of output break executability.
Accomplished like so:
rmarkdown::render() to run the code and capture output that you would normally see on your screen. This is done in a separate R process, via callr, to guarantee it is self-contained.
Use chunk option
comment = "#>" to include the output while retaining executability.
Sometimes you want to mingle rendered code and prose. Put the embedded prose in as roxygen comments, i.e. comment lines that start with
#'. This reprex code:
## a regular comment
x <- 1:100
#' Here is some embedded prose, as a roxygen comment.
renders to this this result:
Here is some embedded prose, as a roxygen comment.
If I had known about
formatR::tidy_eval(), I probably would never had made reprex! But alas I did not. AFAICT here are the main differences:
reprex() accepts an expression as primary input, in addition to code on the clipboard, in a character vector, or in a file.
reprex() runs the reprex in a separate R process, via callr.
tidy_eval() uses the existing R process and offers an
reprex() writes the code to a
.R file and calls
tidy_eval() runs the code line-by-line via
capture.output(eval(..., envir = envir)).
reprex() uploads figures to imgur and inserts the necessary link.