5  Getting Help

Because we work with functions all the time, it’s important to know certain details about how to use them, their required input(s), and their returned output.

So how do you find all this information technically known as a function’s documentation? There are several ways to access this type of information.

5.1 Function help()

If you know the name of a function you are interested in knowing more about, you can use the function help() and pass it the name of the function you are looking for. Here’s an example to obtain the documentation of the absolute value function abs()

# documentation about the 'abs' function
help(abs)

# equivalent command
help("abs")

When using help(), notice that the name of the input function can be written with or without quotes.

Here’s an another simple example in which we use help() to obtain the documentation of the function mean():

# documentation about the 'mean' function
help(mean)

5.2 Shorthand ?

Alternatively, instead of utilizing help(), you can also use the question mark ? followed by the name of the function, like in the following example:

# documentation about the 'abs' function
?abs

# documentation about the 'mean' function
?mean

5.3 Function help.search()

help() and ? only work if you know the name of the function your are looking for. Sometimes, however, you don’t know the name of the function but you may know some keyword(s). To look for related functions associated to a keyword, use help.search() or simply type double question marks ??

# search for 'absolute'
help.search("absolute")

# alternatively you can also search like this:
??absolute

Notice the use of quotes surrounding the input name inside help.search()

5.4 Anatomy of a function’s documentation

Often overlooked by beginners but extremely helpful is to understand the anatomy of the information displayed in the technical documentation. The content is typically organized into seven sections listed below (although sometimes there may be less or more sections)

  • Title
  • Description
  • Usage of function
  • Arguments
  • Details
  • See Also
  • Examples

The three screenshots below show the “Help” or technical documentation of the log() function. This information is in RStudio’s Help tab, located in the pane that contains other tabs such as Files, Plots, Packages.

5.4.1 Name, Title, Description, Usage

Figure 5.1: Help documentation for the log function (part 1).

Name: In first place we have the name of the function as well as the name of the package it is part of. In the above screenshot, the name of the function is log and its associated package is the "base" package.

Title: Then we have the title of the documentation, e.g.  Logarithms and Exponentials.

Description: Below the title comes the Description, which is basically one or more paragraphs with text about the function does.

Notice there are several functions that are part of this example. In addition to log(), there is also logb(), log10(), log2(), log1p(), exp(), and expm1().

Usage: The fourth component thas to do with the Usage section, which shows basic syntax for how to call or invoke any of the listed functions.


5.4.2 Arguments, Details, Value

Figure 5.2: Help documentation for the log function (part 2).

Arguments: The next element is the arguments of the function, one of the most fundamental parts of any function’s documentation. Simply put, this is the list of inputs that the function uses.

Details: An optional section is the Details. Keep in mind that not every function’s documentation includes this part. As the name indicates, it is there to provide additional information and details about the arguments, the output, the involved computations, and things like that.

Value: This element describes the output returned by the function.


5.4.3 Source, References, See Also, Examples

Figure 5.3: Help documentation for the log function (part 3).

Source: Another optional section is the Source which contains information about where the source code is based, or the source for the formulas behind the function’s code.

References: This is another optional part of a function’s documentation, listing important bibliographic references for the interested user.

See Also: This is yet another optional section and it lists one or more related functions.

Examples: Finally, the last section contains examples of how to invoke the function. This can be extremely helpful, especially in cases when it is the first time you have to use the function and you are not sure how to invoke it.

5.5 Exercises

1) Refer to the help documentation of mean() function, e.g. help(mean). Scroll down to the Examples section:

  1. Click on the link Run examples

  2. Copy-paste the sample commands in R’s console to see what happens.


2) Find out how to look for information about math binary operators like + or ^ (without using ?Arithmetic). Tip: quotes are your friend.

Show answer 
?`+`

# also
?"+"


3) Like in the previous exercise, use quotes or backticks to get the documentation of the value matching operator %in%.

Show answer 
?`%in%`


4) Use the function help.search() to obtain a list of suggested functions about "linear model"

Show answer 
help.search("linear model")