7  Using Help

RStudio makes it fairly easy to find documentation on most R functions. However, R documentation takes some practice to read.

The help documentation is generally organized so that each function is documented on one page, but often a single page will contain several functions.

Of course, be sure to make use of the other materials published on the SSCC Website. If you are a member of the SSCC, you can also make an appointment with one of the statistical consultants to discuss your issue further.

7.1 RStudio’s Help Pane

The main way to navigate help is to search. You can either search for the name of a specific function (if you already know it), or you can do a keyword search.

The RStudio Help pane is in the lower right of the workspace, tabbed with Files and Plots. It has two search boxes. The box in the upper-right corner is used to find documentation pages, by function or keyword. The box toward the middle is used to find keywords within the page you are currently looking at.

Let’s use the t.test() function as an example.

If we did not already know the name of the function, we might search by typing in “t-test” in the search box (and hitting the Enter key). This brings up a list of documentation pages, including help pages. Scanning the list, we see stats::t.test Student's t-Test (the stats in front of the function name is the name of a package, but more on packages later). From here we can click on the link and go to the documentation page.

Alternatively, if we know the function name, we can type “t.test” directly in the search box. As we type, we see a list of possible functions, and we can click on the one we want at any time.

An even quicker way of accessing the help page for a function of which we know the name is to enter ?t.test or help(t.test) in the Console.

7.2 Reading a Help Page

A single help page may document more than one function, and a function may work with several kinds of objects (methods). This means that not everything documented on a given page is relevant to the task at hand: a big part of reading help is figuring out which details matter, and which ones do not.

The basic elements of a help page are always the same:

• The function and the package it comes from. t.test() comes from the stats package, one of the packages that comes with a basic installation of R.

  t.test {stats}

• Description: a brief description

  Description
  Performs one and two sample t-tests on vectors of data.

• Usage: a syntax diagram, showing argument names and default values

  Usage
  
  t.test(x, ...)
  
  ## Default S3 method:
  t.test(x, y = NULL,
         alternative = c("two.sided", "less", "greater"),
         mu = 0, paired = FALSE, var.equal = FALSE,
         conf.level = 0.95, ...)
  
  ## S3 method for class 'formula'
  t.test(formula, data, subset, na.action = na.pass, ...)

• Arguments: a more detailed description of the argument options

  Arguments
  
  x             a (non-empty) numeric vector of data values.
  
  y             an optional (non-empty) numeric vector of data values.
  
  alternative   a character string specifying the alternative hypothesis, 
                must be one of "two.sided" (default), "greater" or "less". 
                You can specify just the initial letter.
  . . .

• Value: the kind of data returned by the function

  Value
  
  A list with class "htest" containing the following components:
  
  statistic       the value of the t-statistic.
  
  parameter       the degrees of freedom for the t-statistic.
  
  p.value         the p-value for the test.
  . . .

Most help pages also include:

• Details: some usage or arguments may require more detailed explanation

  Details
  
  alternative = "greater" is the alternative that x has a larger mean than 
  y. For the one-sample case: that the mean is positive.
  . . .

• See Also: related functions

  See Also
  
  prop.test

• Examples: working examples that you can try

  Examples
  
  ## Two-sample t-test
  t.test(1:10, y = c(7:20))      # P = .00001855
  t.test(1:10, y = c(7:20, 200)) # P = .1245    -- NOT significant anymore
  . . .

Once we have the t.test() help page open, we can use the second search box at the top of the Help pane to find information on a specific argument. For example, we can search for “var.equal” to find discussions of this argument further down in the Details section.

7.3 Exercises

1. Look up the help for pbirthday(), a function that calculates the probability that some number of people share the same birthday. How many people are needed for a 50-50 chance that two share the same birthday?

2. Look up the help for penguins, an example dataset. penguins_raw is also documented on this page. What are some of the differences between the two datasets?