Chapter 7 Getting help
7.1 Introduction
R has a comprehensive built-in help system. This system is orientated around the base R functions and packages. Every good package comes with a set of help files. At a minimum these should provide information about the individual package functions and summaries of the data included with the package. They sometimes give descriptions of how different parts of the package should be used, and if we’re lucky, one or more “vignettes” that offer a practical demonstration of how to use a package. Other files are sometimes shipped with packages. For example, these might give an overview of the mathematical or computational theory a package relies on. We will not worry about these in this course.
We may as well get something out of the way early on. The word “help” in the phrase “help file” is a bit of a misnomer. It is probably more accurate to say R has an extensive documentation system. The reason we say this is that the majority of help files are associated with functions, and these kinds of files are designed first and foremost to document how a particular function or group of functions are meant to be used. For example, they describe what kinds of arguments a function can take and what kind of objects it will return to us. Help files are also written in a very precise, painful-to-read manner. They contain a lot of jargon which can be hard for new R users to decipher.
The take-home message is that R help files are aimed more at experienced users than novices. Their primary purpose is to carefully document the different elements of a package, rather than explain how a particular function or the package as whole should be used to achieve a given end. That said, help files often contain useful examples, and many package authors do try to make our life easier by providing functional demonstrations of their package (those “vignettes” we mentioned above are a vehicle for doing this). It’s important to try to get to grips with the built in help system. It contains a great deal of useful information which we need to really start using R effectively. The road to enlightenment is bumpy though.
7.2 Browsing the help system
How do we access the help system? Help files are a little like mini web pages, which means we can navigate among them using hyperlinks. This makes it very easy to explore the help system. One way to begin browsing the help system uses the help.start
function:
help.start()
If we type this now at the Console we should see the Package Index page open up in the Help tab of the bottom right pane in RStudio. This lists all the packages currently installed on a computer. We can view all the help files associated with a package by clicking on the appropriate link. For example, the functions that come with the base installation of R have a help file associated with them—click on the link to the R base package (base
) to see these. Though we know about a few of these already, there are a lot of functions listed here. R is huge.
The packages that come with the base R installation and those that we install separately from base R have their own set of associated help files. These can be viewed by following the appropriate link on the Package Index page. We will learn how to navigate these in a moment. Take note: it is up to the developer of a package to produce usable help files. Well-designed packages like dplyr and ggplot2 have an extensive help system that covers almost everything the package can do. This isn’t always the the case though, particularly with new or packages or packages that are not widely used. We will only ever use well-documented packages.
Notice that the help browser has Forward, Back, and Home buttons, just like a normal web browser. If we get lost in the mire of help pages we can always navigate backward until we get back to a familiar page. However, for some reason the Home button does not take us to the same page as help.start
. Clicking on the home button takes us to a page with three sections:
The Manuals section looks like it might be useful for novice users. Unfortunately, it isn’t really. Even the “Introduction to R” manual is only helpful for someone with a bit of programming experience because it assumes we understand what terms like “data structure” and “data type” mean. It is worth reading this manual after gaining a bit of experience with R. The others manuals are more or less impenetrable unless the reader already knows quite a bit about computing in general.
The Reference section is a little more helpful. The “Packages” link just takes us to the same page opened by
help.start
. From here we can browse the help pages on a package-specific basis. The “Search Engine & Keywords” link takes us to a search engine page (no surprises there). We can use this to search for specific help pages, either by supplying a search term or by navigating through the different keywords. We’ll discuss the built-in search engine in the next subsection.The Miscellaneous Material section has a couple of potentially useful links. The “User Manuals” link lists any user manuals supplied by package authors. These tend to be aimed at more experienced users and the packages we will learn to use in this course do not provide them. However, it is worth knowing these exist as they are occasionally useful. The “Frequently Asked Questions” link is definitely worth reviewing at some point, but again, most of the FAQs are a little difficult for novice users to fully understand.
7.3 Searching for help files
After browsing help files via help.start
for a bit it quickly becomes apparent that this way of searching for help is not very efficient. Quite often we know the name of the function we need to use and all we want to do is open that particular help file. We can do this with the help
function:
help(topic = Trig)
After we run this line RStudio opens up the help file for the trigonometry topic in the Help tab. This file provides information about the various trigonometric functions such as sin
or cos
. We’ll learn how to make sense of such help pages in the next subsection. For now, we just want to see how to use help
.
The help
function needs a minimum of one argument: the name of the topic or function of interest. When we use it like this the help function searches across packages, looking for a help file whose name gives an exact match to the name we supplied. In this case, we opened the help file associated with the Trig
topic. Most of the time we use the help
function to find the help page for a specific function, rather than a general topic. This is fine if we can remember the name of the topic associated with different functions. Most of us cannot. Luckily, the help function will also match help pages by the name of the function(s) they cover:
help(topic = sin)
Here we searched for help on the sin
function. This is part of the Trig
topic so help(topic = sin)
brings up the same page as the help(topic = Trig)
.
There are several arguments of help
that we can set to alter its behaviour. We will just consider one of these. By default, the help
function only searches for files associated with the base functions or with packages that we have loaded in the current session with the library
function. If we want to search for help on the mutate
function—part of the dplyr
package—but we haven’t run library(dplyr)
in the current session this will fail:
help(mutate)
## Help on topic 'mutate' was found in the following packages:
##
## Package Library
## plyr /Library/Frameworks/R.framework/Versions/3.5/Resources/library
## dplyr /Library/Frameworks/R.framework/Versions/3.5/Resources/library
##
##
## Using the first match ...
Instead, we need tell help
where to look by setting the package
argument:
help(mutate, package = dplyr)
It’s good practise to use help
every time we’re struggling with a particular function. Even very experienced R users regularly forget how to use the odd function and have to dive into the help. It’s for this reason that R has a built in shortcut for help
. This is accessed via ?
. For example, instead of typing help(topic = sin)
into the Console we can bring up the help page for the sin
function by using ?
like this:
?sin
This is just a convenient shortcut that does the same thing as help
. The only difference is that ?
does not allow us to set arguments such as package
.
7.5 Vignettes and demos
The Oxford English Dictionary defines a vignette as, “A brief evocative description, account, or episode.” The purpose of a package vignette in R is to provide a relatively brief, practical account of one or more of its features. Not all packages come with vignettes, though many of the best thought out packages do. We use the vignette
function to view all the available vignettes in Rstudio. This will open up a tab that lists each vignette under their associated package name along with a brief description. A package will often have more than one vignette. If we just want to see the vignettes associated with a particular package, we have to set the package
argument. For example, to see the vignettes associated with dplyr we use:
vignette(package = "dplyr")
Each vignette has a name (the “topic”) and is available either as a PDF or HTML file (or both). We can view a particular vignette by passing the vignette
function the package
and topic
arguments. For example, to view the “data_frames” vignette in the dplyr
package we would use:
vignette(topic = "data_frames", package = "dplyr")
The vignette
function is fine, though it is usually more convenient to browse the list of vignettes inside a web browser. This allows us to open a particular vignette directly by clicking on its link, rather than working at the Console. We can use the browseVignettes
function to do this:
browseVignettes()
This will open a page in our browser showing the vignettes we can view. As one should expect by now, we can narrow our options to a specific package by setting the package
argument.
In addition to vignettes, some packages also include one or more ‘demos’ (demonstrations). Demos are a little like vignettes, but instead of just opening a file for us to read, the demo function can actually runs a demonstration R scripts. We use the demo
function (without any arguments) to list the available demos:
demo()
When we use the demo
function like this it only lists the demos associated with packages that have been loaded in the current session (via library
). If we want to see all the demos we can run we need to use the somewhat cryptic demo(package = .packages(all.available = TRUE))
.
In order to actually run a demo we use the demo
function, setting the topic
and package
arguments. For example, to run the “colors” demo in the grDevices package we would use:
demo(colors, package = "grDevices", ask = FALSE)
This particular demo shows off some of the pre-defined colours we might use to customise the appearance of a plot. We’ve suppressed the output though because so much is produced.