What Does It Mean for Code to Fail?

Two simple criteria must be met in order to recognize trouble with your code (Peng et al. 2017):

1. You expect your code to behave in a certain way
2. Your code doesn’t behave as expected

Oftentimes, the best case scenario is that R will throw an error message. Error messages signal that R has encountered some fatal flaw in your code and, in consequence, nothing happens.

The next best scenario is that R will throw a warning message. Warning messages signal that R has successfully evaluated and executed code, but something unexpected happened, and R wants you to know about it.

The worst and most pernicious scenario is when your code runs perfectly fine, without error or warning messages, yet the output isn’t exactly what you’d wanted. If you recognize this, that’s great. If you don’t recognize this, errors flow downstream and can be difficult to detect and fix. Always inspect your output.

Oftentimes, users place too much emphasis on fixing their expected results and fail to consider their original expectations. Never neglect revisiting your expectations, as it’s possible that they, not your code, may explain an error (Peng et al. 2017).

Documentation

When you’re in a jam, the foremost strategy for resolving said jam is to read any relevant documentation.

Built-In Documentation

All base R functions, as well as packages, functions, and datasets downloaded from CRAN (Comprehensive R Archie Network) contain documentation that can be accessed via the help() or ? functions.

When called, the Help pane displays built-in documentation, which typically contains names, descriptions, templates, arguments, values, references, related objects, and examples.

Observe the following calls to help() on function median():

help(median)
?median

Built-in documentation is displayed with function help() and an object name.

External Documentation

Datasets found “in the wild” often have documentation containing metadata, variable definitions, and other helpful information, while many functions have external documentation outside of CRAN.

Documentation for RStudio’s “dplyr” Package

More stylized documentation on package dplyr from the Tidyverse website.

Documentation for the Pheonix Fire Department Data

Documentation on operational statistics data on the City of Phoenix Open Data portal.

Vignettes

“A vignette is like a book chapter or an academic paper: It can describe the problem that your package is designed to solve, and then show the reader how to solve it.” (Hadley Wickham)

Some R packages have vignettes, or more comprehensive and thorough overviews than typical documentation. Vignettes are written for the express purpose of learning how to use a package. While vignettes are easy to find in a conventional search engine, you can open a vignette from within R by calling function browseVignettes() and a quotes package name. For example:

browseVignettes("tidyr")

Available vignettes appear in your browser with browseVignettes()

Troubleshooting: Web Searches & Forums

While documentation tends to require a bit more reading, there’s a good chance that someone has run into the same problem you’ve encounters. The internet has a long memory and the following strategies show how to exploit it.

Quoting Your Console

You can take advantage of error and warning messages by copying them from your console and pasting them directly into an online search engine, verbatim and quoted. It often helps to include the function or package name outside of the quoted console message.

Quoting Error Messages in Search Engines

Quoting your console’s error message in a search engine often yields helpful results.

Forums & Archives

One of the best troubleshooting strategies is to search for answers in online forums like Stack Overflow or Cross Validated. Archives like the “R-help” mailing list are also searchable.

Potential Solutions as Seen on Stack Overflow

Stack Overflow often provides multiple potential solutions. The best rise to the top.

Consulting Humans

Asking for help from another human should always be your last recourse after exhausted all of the above strategies. That said, if you’re still in a jam, there are several sources for human help:

• Mailing lists like “R-help” and forums like Stack Overflow
• Message boards in universities and MOOCs (massive open online classes)
• R user communities, e.g. Reddit’s r/Rstats
• Email and in-person inquiries

There is an incredible amount of good will in the R community, but try to be respectful.

Importantly, there are established best practices in asking R-related questions. Make sure to:

1. Comply with any and all forum, community, and mailing list rules
2. In email headers or topic threads, label with a succinct but detailed description
3. Clearly state the expected behavior and unexpected result of your code
4. Provide a reproducible example, including code and imitation data
5. Include real or imitation output, e.g. error messages
6. If using random number generation, include the seed
7. Ensure your code is legible and organized
8. Include your R and RStudio versions
9. Include your operating system
10. Be polite

Further Resources

The following resources may prove valuable for both learning how to learn R and troubleshooting:

I) Full-Length Text

• “Intro to R: Nuts & Bolts” (Crawford, 2018)

II) Documentation & Vignettes

• “Vignettes: Long-Form Documentation” (Wickham, 2019)

III) Forums, Email Lists, & Communities

• Stack Overflow
• Cross Validated
• R Mailing Lists
• Reddit’s r/Rstats
• Twitter’s #Rstats

IV) Asking R-Related Questions

• “Hot to Ask Questions the Smart Way” (Raymond, 2014)
• “How to Make a Great R Reproducible Example” (Stack Overflow, 2018)
• “Posting Guide: Hot to Ask Good Questions that Prompt Useful Answers” (Plate, 2013)
• Errors vs Warnings (Rex Analytics)

V) More ASCII Dragons

• danadaldoss
• Doug
• Ahmad