Getting Help in R

Looking for Help

When programming, it is not a matter of if you get stuck, or even when you get stuck, but how much time will you spend stuck. Some problems can be resolved in minutes where as others may last weeks or even months. Thankfully R has a wide variety of tools to help you get unstuck, from built-in documentation, to mailing lists, to help groups like the Davis R Users Group.

If you have ever asked for coding help, you may have gotten the response “Have you checked the documentation”. This is the programming equivalent of asking if you have read the manual. And like many manuals, R documentation often seems like it was written for someone who already knows what they are doing. This is all well and good if you do know what you are doing. However, it doesn’t help much if the documentation itself is a source of confusion.

The basic unit of documentation in R is the R help file. While help files may be difficult to decipher at first, they are all difficult in the same way. That means once you understand one of them, understanding the rest is much easier. Most R help files focus on a particular function, like summary(), which summarizes various types of data in R. However, many packages and built-in data sets like mtcars also have help pages.

Opening R Documentation

You can access R help files in several ways. If you know the name of the function or package you are looking for information about, you can use the ? operator in the console with the name of the function to open the R help file. This will only open documentation for functions and packages you currently have loaded into R. This is also equivalent to using the help() function.

#these lines of code are equivalent
?summary

help('summary')

If you are using RStudio this will bring up documentation for that function in help window. If you use the GUI, it will open a separate help window. If you are running R in bash or zsh, R will open the help file in your default text editor.

Not all packages have help files the way functions do, but it is getting more common. To load the help file for a package, you need to add -package onto the name of the package. Since R does not view “sf-package” as a single word, you need to surround it in tick marks (`).

#load documentation for the sf package
?`sf-package`

If you are unsure of the function name, you can use the ?? operator to search all of your local R documentation for a term or set of terms. For multiple search terms, enclose them in tick marks. The ?? operator is equivalent to the function help.search(), but for help.search you enclose your search term in quotes. The help.search function also gives you more control over what you are searching for.

??`linear model` 

#look for linear model only in the title of the help file
help.search('linear model', fields='title')

This will search documentation for all packages you have installed. It will then provide a list links to documentation pages you can use to find the function that works best. Functions are labeled using the schema [PACKAGE NAME]::[FUNCTION NAME] so you can tell which package to load to access function you are interested in.

If you want to search documentation for packages that you haven’t installed yet, you have a couple of options. If you are only looking for packages that are available through CRAN or bioconductor, you can use the RSiteSearch() function, or rdocumentation.org if you prefer a web interface. CRAN itself contains a lot of documentation for each package on the package’s page (ex. dplyr), but the information isn’t searchable from the website and you have to know what package you want information on. If you also want to be able to search packages hosted on R-forge and Github in addition to CRAN and bioconductor, you can use rdrr.io.

Documentation Duplication

Sometimes you will have functions from different packages that share the same name. For example, the stats package and the dplyr package both have functions called filter, but one is used for filtering time series and the other subsets data.frames by row. If you use the ? operator to open the help file for one of these functions, a page will open with links to different documentation pages based on the package you are using. Be sure to click on the link that corresponds to the function you have questions about.

Definitions

R documentation uses a couple of terms that are sometimes glossed over at introductory levels. However, without them, many R help files are nigh impossible to read.

Functions

A function is a pre-programmed set of instructions that performs a certain task. For example, the sqrt function takes the square root of a given number or numbers. The length function tells you the number of elements in a vector or list. For more information on functions, see DataLab’s Calling Functions and Functions sections of the R Basics reader.

Arguments

An argument is an input to a function, the information the function needs in order to work. Not all functions require arguments, but most do. Almost all arguments in R have names. Ideally argument name would tell you something about what the argument does, but that is not always the case. The name of the first three arguments to the lm function are formula, data, and subset, which are relatively informative. On the other hand, sqrt()’s singular argument x doesn’t give us very much information, which is why the the Arguments section of help files are is important. There are a few functions with unnamed arguments, but we will discuss that later.

Objects

Everything you can interact with in R is an object. Whenever you create a variable, you create an object. All of the objects you create will appear in the Environment tab in RStudio. If you aren’t using RStudio, you can also get a list of objects you created using ls().

x = 5

ls()

[1] "x"

There are many more objects that R defines internally. R includes many built-in data sets (ex. mtcars), all of which are objects. Every function you use is also an object.

Classes

A class is the blueprint for the structure of an object. It defines how you can interact with the object and what types of information it can contain. To determine the class of an object, you can use the function class(). Common examples of classes include integers, characters, data.frames, lists, and functions. For more information on classes, see the Data Types and Classes section of DataLab’s R Basics reader.

Methods

A method is a function that is defined for a particular class of object. For example, the function st_area calculates the area of a set of shapes. However, it only works for objects of the sf class, a type of object that stores geographical information. R assumes that the first argument you provide to st_area has the class sf, and if it doesn’t you will get an error message.

Some functions may have methods defined for many different classes of objects. For example, you can use the summary function to summarize a vector of numbers or the columns of a data.frame. The internal code for the function automatically determines the class of the input data and applies the correct method for you.

summary(1:20)

   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
   1.00    5.75   10.50   10.50   15.25   20.00 

summary(iris)

  Sepal.Length    Sepal.Width     Petal.Length    Petal.Width   
 Min.   :4.300   Min.   :2.000   Min.   :1.000   Min.   :0.100  
 1st Qu.:5.100   1st Qu.:2.800   1st Qu.:1.600   1st Qu.:0.300  
 Median :5.800   Median :3.000   Median :4.350   Median :1.300  
 Mean   :5.843   Mean   :3.057   Mean   :3.758   Mean   :1.199  
 3rd Qu.:6.400   3rd Qu.:3.300   3rd Qu.:5.100   3rd Qu.:1.800  
 Max.   :7.900   Max.   :4.400   Max.   :6.900   Max.   :2.500  
       Species  
 setosa    :50  
 versicolor:50  
 virginica :50  
                
                
                

You can use the methods function to see what classes of objects have methods for a given function.

methods(summary) 

 [1] summary,ANY-method                  summary,DBIObject-method           
 [3] summary.aov                         summary.aovlist*                   
 [5] summary.aspell*                     summary.check_packages_in_dir*     
 [7] summary.connection                  summary.data.frame                 
 [9] summary.Date                        summary.default                    
[11] summary.ecdf*                       summary.factor                     
[13] summary.glm                         summary.infl*                      
[15] summary.lca*                        summary.lm                         
[17] summary.loess*                      summary.manova                     
[19] summary.matrix                      summary.mlm*                       
[21] summary.nls*                        summary.packageStatus*             
[23] summary.POSIXct                     summary.POSIXlt                    
[25] summary.ppr*                        summary.pr_DB*                     
[27] summary.prcomp*                     summary.princomp*                  
[29] summary.proc_time                   summary.proxy_registry*            
[31] summary.rlang_error*                summary.rlang_message*             
[33] summary.rlang_trace*                summary.rlang_warning*             
[35] summary.rlang:::list_of_conditions* summary.sfc*                       
[37] summary.srcfile                     summary.srcref                     
[39] summary.stepfun                     summary.stl*                       
[41] summary.svm*                        summary.table                      
[43] summary.tukeysmooth*                summary.tune*                      
[45] summary.units*                      summary.vctrs_sclr*                
[47] summary.vctrs_vctr*                 summary.warnings                   
see '?methods' for accessing help and source code

To look up documentation for a specific method, use the schema [FUNCTION NAME].[CLASS NAME]. For example, if we want to look up documentation for the summary method for the class lm, we would use the code ?summary.lm.

Advanced Topic

This system of objects, classes, and methods is called Object-Oriented Programming (OOP). Object oriented programming is not unique to R, but R does it a little differently. If you want a deeper understanding of methods in R, the S3 section of the Intermediate R reader describes the most widely used system of OOP in R. Additionally, Advanced R by Hadley Wickham provides a more complete description of the various OOP systems available in R as well as their trade-offs.