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

If you know the name of the function you need help with, you can access the R Help files in two ways:

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.

Typing two question marks followed by the search term is a shortcut for help.search(). For example, typing ??date returns the same list of functions as typing help.search(“date”) does.

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

...

The left-hand column contains the functions that match your search term, and the right-hand column contains the R Help file title for this function. Notice that each function consists of two elements separated by two colons (for example, ada::update.ada). This means, for example, that in the package ada, there is a function called update.ada().

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.

When you use help() or ?, you also can specify a topic name, not just a function name. Some really useful Help pages describe the effect of many functions at once, and because they have a unique topic name, you can access these directly. For example, try reading the Help for ?Syntax, ?Quotes, or ?DateTimeClasses.

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.

You can search the Internet directly from your R console, by using the RSiteSearch() function. This function enables you to search for keywords in the R documentation, as well as the R Help mailing list archives (for more on the R mailing lists, see “Using the R mailing lists,” later in this chapter). RSiteSearch() takes your search term and passes it to the search engine at http://search.r-project.org. Then you can view the search results in your web browser.

For example, to use RSiteSearch() to search for the term cluster analysis, use the following:

> RSiteSearch(“cluster analysis”)

Another way of searching the web directly from your console is to use the add-on package called sos and the search function findFn(). This function is a wrapper around RSiteSearch() that combines all the RSiteSearch() results into tabular form on a single page, which may make the results easier to digest.

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.

If you’re trying to search for R topics in your favorite search engine, you may find that the results tend to be unrelated to the programming language. One way of improving the accuracy of your search results is to enclose the R in square brackets. For example, to search for the topic of regression in R, use [R] regression as your search term. This technique seems to work because the R mailing lists tend to have [R] in the topic for each message. In addition, on the Stack Overflow website (www.stackoverflow.com), questions that are related to R are tagged with [r].

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.

Before posting a message to any of the R mailing lists, make sure that you read the posting guidelines, available at www.r-project.org/posting-guide.html. In particular, make sure you include a good, small, reproducible example (see “Making a Minimal Reproducible Example,” later in this chapter).

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.

Both of these sites use tags to identify topics that are discussed. Both sites use the [r] tag to identify questions about R. To find these questions, navigate to the Tags section on the page and type r in the search box.

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

If you want to know what a minimal reproducible example looks like, take a look at the examples in the R Help files. In general, all the code given in the R Help files fulfills the requirements of a minimal reproducible example.

Creating sample data with random values

In most cases, you can use random data to illustrate a problem. R has some useful built-in functions to generate random numbers and other random data. For example, to make a vector of random numbers, use rnorm() for the normal distribution or runif() for a uniform distribution. To make a random vector with five elements, try the following:

> set.seed(1)

> x <- rnorm(5)

> x

[1] -0.6264538  0.1836433 -0.8356286  1.5952808  0.3295078

You can use the set.seed() function to specify a starting seed value for generating random numbers. By setting a seed value, you guarantee that the random numbers are the same each time you run the code. This sounds a bit pointless, doesn’t it? It may be pointless in production code, but it’s essential for a reproducible example. By setting a seed, you guarantee that your code will produce the same results as another person running your code.

If you want to generate random values of a predetermined set, use the sample() function. This function is a bit like dealing from a deck of playing cards. In a card game, you have 52 cards and you know exactly which cards are in the deck. But each deal will be different. You can simulate dealing a hand of seven cards using the following code:

> 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”

Creating a data.frame with sample data is straightforward:

> 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.

Before you submit your code, make sure to describe clearly which packages you use. In other words, remember to include the library() statements. Also, test your code in a new, empty R session to make sure it runs without error. People should be able to just copy and paste your data and your code in the console and get exactly the same results as you get.

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)

The function sessionInfo() prints information about your version of R and some locale information, as well as attached or loaded packages. Sometimes the output of this function can help you determine whether there are conflicts between your loaded packages. Here’s an example of the results of sessionInfo():

> 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.