Ending the Terror of R Errors

Post provided by Paul Mensink

Last year, I introduced R to petrified first-year biology students in a set of tutorials. I quickly realised that students were getting bogged down in error messages (even on very simple tasks), so most of my time was spent jumping between students like a wayward Markov chain. I would often find a desperate face at the end of a raised hand looking hopelessly towards their R console muttering some version of “What the $%# does this mean?”. I instantly morphed from teacher to translator and our class progress was slower than a for-loop caught in the second Circle.

Error messages are often not very helpful

Fast forward to Ecology Across Borders last December in Ghent, where rOpenSci and special interest groups from the BES, GfÖ and NecoV  and Methods in Ecology and Evolution  co-hosted a pre-conference R hackathon. I was elated to see that one of the challenges was focused on translating R error messages into “Plain English” (thanks to @DanMcGlinn for the original suggestion!).

My hackathon teammates (Laura Merritt, Patrick Jansen, Pei-Chi Ho) and I spent the day trying to develop code to capture errors as they were happening and replace them with more intuitive responses for beginners. Laura Merritt wrote a nifty wrapper function and we were on our way!

Later, Maëlle Salmon, who gave a lovely introduction to R packages and rOpenSci at the beginning of the hackathon, made her way over to talk about our progress.  She quickly realised that what we were trying to accomplish was essentially language translation – taking R errors and translating them into “simple English” as she called it. R already has the capacity to implement language changes (e.g., English to French). So all we really needed to do was write our own R dictionary of error translations that could be implemented just as easily!

erroR Dictionary

Dictionaries to the rescue!

Enter the erroR Dictionary. Our goal now is to create a dictionary of R errors and easy-to-understand translations that will be implemented by installing translation files (.po) directly to the package. Noam Ross did some very cool work looking at R errors in his Common errors in R: An Empirical Investigation (summarised by David Smith) and Devin Pastoor has a nice piece on common explanations for R errors on Noam’s github. Using some of this initial work as a starting point, Patrick Jansen and Pei-Chi Ho began making some simple translations for common errors (see example below), but we’d like to expand this out to include lots of errors that users might encounter from a variety of packages.

Many thanks to Nick Golding who pointed me towards the msgtools package that grabs all the messages and warnings from packages. I’ve used this to start our error dictionary using some of the most downloaded packages from CRAN (the msgtools package does pick up everything, so there are some fragments of messages in there which can safely be ignored).

Error	Translation
“could not find function…”	You misspelled the function, or the function is part of a package that did not load properly. Try loading the package again or searching for the correct spelling of the function you’re interested in.

Next steps…

Is 2018 the year we get rid of the uninterpretable R error? Things are definitely picking up speed! Steph Desilva has created a helpPlease package where she is also collecting R error messages. Hadley Wickham is starting an error message style guide for #rstats. What we need now is help to create error translations!

I’ve placed our dictionary over at erroR Dictionary where anyone can contribute. You can also contribute to the helpPlease explanations (we can merge up all the translations as we go!). If you want to relive the error messages that used to keep you up at night and help us make them easier to interpret (and improve sleep for thousands of new R users) please contribute! We’ve got a lot of error messages to sort through, translations to write and, hopefully, a lot of ambiguity to disentangle!