Chapter 11
Getting Help
In This Chapter
Using the built-in R help
Finding information online
Joining the R community
Making a reproducible example to get help
Even the best R programmers occasionally get stuck on a problem. In these situations, you need to know how to find help. Fortunately, R code is generally very well documented and has excellent help available. You just need to know how to access it. In this chapter, we show you how.
If the built-in help doesn’t solve your problem, you can search for information on the Internet and turn to the online R community. We end this chapter by walking you through how to create a minimal reproducible example, which you’ll find helpful in getting help.
Finding Information in the R Help Files
The R documentation (in the form of R Help files) is a phenomenally rich resource. Most of the time, if you read the Help files carefully, you’ll get a better understanding of why a function isn’t doing what you think it should or why you’re getting an error. Although some of the R Help files can look cryptic at first glance, if you persevere — and know what to look for — your investment will pay off.
When you know exactly what you’re looking for
By typing help(...) with the function name inside the brackets. For example, typing help(paste) returns help about the paste()
function.
By typing ? followed by the name of the function. For example, typing ?paste returns help about the paste()
function.
Typically, the R Help files follow a fairly standard outline. You find most of the following sections in every R Help file:
Title: A one-sentence overview of the function.
Description: An introduction to the high-level objectives of the function, typically about one paragraph long.
Usage: A description of the syntax of the function (in other words, how the function is called). This is where you find all the arguments that you can supply to the function, as well as any default values of these arguments.
Arguments: A description of each argument. Usually this includes a specification of the class (for example, character
, numeric
, list
, and so on). This section is an important one to understand, because supplying an argument of the wrong class is quite frequently a cause of errors in R.
Details: Extended details about how the function works, provides longer descriptions of the various ways to call the function (if applicable), and a longer discussion of the arguments.
Value: A description of the class of the value returned by the function.
See also: Links to other relevant functions. In most of the R editors, you can click these links to read the Help files for these functions.
Examples: Worked examples of real R code that you can paste into your console and run.
One of the most powerful ways of using R Help is to carefully study the examples in the Examples section. The documentation authors designed these examples to be reproducible, which means that you can copy the whole example to your R console and run it directly. Often, this can help you really understand the nature of the input that each function needs and the output the function gives.
When you don’t know exactly what you’re looking for
Sometimes you don’t know the exact function to use. Or maybe you know the name of the function but you can’t remember whether it’s spelled in all lowercase letters or with some uppercase letters. In these situations, you have to search the R Help files to find what you need.
You can search the R Help files by typing help.search(...) with a quoted search term inside the brackets. This gives a list of functions that are similar to the search term; it’s useful if you can’t remember the exact name of a function, because help.search()
makes use of fuzzy matching to return a list of matching Help topics. For example, typing help.search(“date”) in the console returns a long list of possible matches, including format.Date
, as.POSIXlt
, and DateTimeClasses
, among others.
When you search for R help, you get a list of topics that match the search term. For example, you may get the following result when typing ??date:
ada::update.ada Add more trees to an ada object
chron::chron Create a Chronological Object
chron::cut.dates Create a Factor from a Chron or Dates Object
chron::dates Generate Dates and Times Components from Input
....
base::Date Date Class
base::DateTimeClasses Date-Time Classes
base::diff Lagged Differences
...
From the description of ada::update
, it’s immediately apparent that this function has nothing to do with dates or times. Nonetheless, it was included in the search results because the function name contained the substring date
. In this case, if you scroll down the list, you’ll also find references to several date functions in the base
package, including Date()
, DateTimeClasses()
, and diff()
.
After you’ve identified a function that looks helpful, type ?functionName to open the relevant Help page. For example, typing ?Date opens the Help page for Date
.
Searching the Web for Help with R
Sometimes the built-in R Help simply doesn’t give you that moment of inspiration to solve your problem. When this happens, it’s time to tap into the information available on the web.
For example, to use RSiteSearch()
to search for the term cluster analysis, use the following:
> RSiteSearch(“cluster analysis”)
To use findFn
, you first have to install the sos
package:
> install.packages(“sos”)
Then you load the package using library(sos)
. Finally, you use findFn(“cluster”)
:
> library(sos)
> findFn(“cluster”)
found 2311 matches; retrieving 20 pages, 400 matches.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
This opens a new tab in your favorite web browser with the results in an easy-to-read table. Each row of the table contains a function, the name of the package, and a helpful description and link to the Help page for that function.
In addition to your favorite search engine, you also can use the dedicated R search site at http://search.r-project.org
to search through R functions, vignettes, and the R Help mailing lists. Or you can use the search engine www.rseek.org
, which is dedicated to R and will search first through all R-related websites for an answer.
Getting Involved in the R Community
Sometimes, no matter how hard you search for help in the mailing list archives, blogs, or other relevant material, you’re still stuck. If this ever happens to you, you may want to tap into the R community. R has a very active community made up of people who not only write and share code, but also are very willing to help other R users with their problems.
Using the R mailing lists
The R Development Core Team actively supports four different mailing lists. At www.r-project.org/mail.html
, you can find up-to-date information about these lists, as well as find links to subscribe or unsubscribe from the lists. When you subscribe to a mailing list, you can choose to receive either individual e-mail messages or a daily digest.
The four important mailing lists are
R-help: This is the main R Help mailing list. Anyone can register and post messages on this list, and people discuss a wide variety of topics (for example, how to install packages, how to interpret R’s output of statistical results, or what to do in response to warnings and error messages).
R-announce: This list is for announcements about significant developments in the R code base.
R-packages: This list is where package authors can announce news about their packages.
R-devel: This is a specialist mailing list aimed at developers of functions or new R packages — in other words, serious R developers! It’s more about programming than about general topics.
In addition to these general mailing lists, you also can participate in about 20 special interest group mailing lists. See the sidebar “Special interest group mailing lists” for more information.
Discussing R on Stack Overflow and Stack Exchange
Stack Exchange (www.stackexchange.com
) is a popular website where people can ask and answer questions on a variety of topics. It’s really a network of sites. Two of the Stack Exchange sites have substantial communities of people asking and answering questions about R:
Stack Overflow (www.stackoverflow.com
): Here, people discuss programming questions in a variety of programming languages, such as C++, Java, and R.
CrossValidated (http://stats.stackexchange.com
): Here, people discuss topics related to statistics and data visualization. Because R really excels at these tasks, there is a growing community of R coders on CrossValidated.
Tweeting about R
If you want to join the discussion about R on Twitter (www.twitter.com
), follow and use the hashtag #rstats. This hashtag attracts discussion from a wide variety of people, including bloggers, package authors, professional R developers, and other interested parties.
Making a Minimal Reproducible Example
When you ask the R community for help, you’ll get the most useful advice if you know how to make a minimal reproducible example. A reproducible example is a sample of code and data that any other user can run and get the same results as you do. A minimal reproducible example is the smallest possible example that illustrates the problem; it consists of the following:
A small set of sample data
A short snippet of code that reproduces the error
The necessary information on your R version, the system it’s being run on, and the packages you’re using
Creating sample data with random values
> set.seed(1)
> x <- rnorm(5)
> x
[1] -0.6264538 0.1836433 -0.8356286 1.5952808 0.3295078
> cards <- c(1:9, “J”, “Q”, “K”, “A”)
> suits <- c(“Spades”, “Diamonds”, “Hearts”, “Clubs”)
> deck <- paste(rep(suits, each=13), cards)
> set.seed(123)
> sample(deck, 7)
[1] “Diamonds 2” “Clubs 2” “Diamonds 8” “Clubs 5”
[5] “Clubs 7” “Spades 3” “Diamonds K”
By default, sample()
uses each value only once. But sometimes you want elements of this section to appear multiple times. In this case, you can use the argument replace=TRUE
. If you want to create a sample of size 12 consisting of the first three letters of the alphabet, you use the following:
> set.seed(5)
> sample(LETTERS[1:3], 12, replace=TRUE)
[1] “A” “C” “C” “A” “A” “C” “B” “C” “C” “A” “A” “B”
> set.seed(42)
> dat <- data.frame(
+ x = sample(1:5),
+ y = sample(c(“yes”, “no”), 5, replace = TRUE)
+ )
> dat
x y
1 5 no
2 4 no
3 1 yes
4 2 no
5 3 no
Producing minimal code
The hardest part of producing a minimal reproducible example is to keep it minimal. The challenge is to identify the smallest example (the fewest lines of code) that reproduces the problem or error.
Providing the necessary information
Including a little bit of information about your R environment helps people answer your questions. You should consider supplying the following:
Your R version (for example, R 2.13-1)
Your operating system (for example, Windows 7 64-bit)
> sessionInfo()
R version 2.14.1 (2011-12-22)
Platform: x86_64-pc-mingw32/x64 (64-bit)
locale:
[1] LC_COLLATE=English_United Kingdom.1252
[2] LC_CTYPE=English_United Kingdom.1252
[3] LC_MONETARY=English_United Kingdom.1252
[4] LC_NUMERIC=C
[5] LC_TIME=English_United Kingdom.1252
attached base packages:
[1] stats graphics grDevices utils datasets
[6] methods base
other attached packages:
[1] rj_1.0.2-5 devtools_0.5.1
loaded via a namespace (and not attached):
[1] RCurl_1.6-10.1 tools_2.14.1
The results tell you that this session is running R version 2.14 on 64-bit Windows, with a United Kingdom locale. You also can see that R has loaded two packages: package rj
(version 1.0.2-5) and package devtools
(version 0.5.1).
Sometimes it’s helpful to include the results of sessionInfo()
in your question, because other R users can then tell whether there could be an issue with your R installation.