Overview of R and RStudio
2.8 How to Find Help in RStudio
Due to the complexity of a programming language – and the almost endless number of software libraries that can be installed adding to the functions and resources available to you – it can become difficult to keep track of how functions are called, what arguments they take, and what output they provide. Packages have a range of files that are designed to document and demonstrate the use of the functions they provide. These files take the form of R documentation, vignettes, and demonstration files. In this section, we discuss how to access information on using a function by inspecting these documents.
All packages submitted to CRAN are required to have sufficient documenta- tion to describe the functions they add to your software library. For each function,
2.8 · How to Find Help in RStudio
2
there should be a matching R documentation file that can be accessed. R documen- tation describes the purpose, input, implementation, and output of a function and provides examples applying the syntax. The contents of an R document are described in .Table 2.3. This documentation can be accessed in the help tab in the lower right window of the RStudio IDE. Help topics and functions can be
.Table 2.3 Excerpt of contents of the R documentation for read.csv()
Section Description Example Descrip-
tion
A brief description of the function’s purpose
Reads a file in table format and creates a data frame from it, which includes cases corresponding to lines and variables to fields
Usage The usage of the
function read.csv(file, header = TRUE, sep =“,”,quote
=“\””,
dec=“.”,fill = TRUE, comment.char=“”,...) Argu-
ments
The arguments that must be assigned to the function to execute and their
corresponding description
File The name of the file, which the data are to be read from
header A logical value indicating whether the file contains the names of the variables as its first line. If missing, the value is determined from the file format:
header is set to TRUE if, and only if, the first row contains one fewer field than the number of columns Sep The field separator character. Values
on each line of the file are separated by this character. If sep = “” (the default for read.table), the separator is “white space” that is one or more spaces, tabs, new lines, or carriage returns
quote The set of quoting characters. To disable quoting altogether, use quote
= “”
Dec The character used in the file for decimal points
… Further arguments to be passed to read table
Exam- ples
An example for executing the function
## using count.fields to handle unknown maximum number of fields
## when fill = TRUE
test1 <- c(1:5, “6,7”, “8,9,10”) tf <- tempfile()
writeLines(test1, tf)
read.csv(tf, fill = TRUE) # 1 column Source: authors’ own table
43
2
searched for in the search field of the help window or from the command line in the console window using the ? operator. For example, we can search for help on the read.csv() function by typing the following into the console window in RStudio:
# Searching for help using the ? operator
?read.csv
In .Fig. 2.6, we can see an excerpt of the contents of the R documentation for read.csv(). This information will be displayed in the help tab in the lower right window of the RStudio IDE and provides us with details on the purpose, argu- ments, and usage of the function and a demonstration example. When encounter- ing a new function or an error, the R documentation is the first place to look in.
For a full list of available R documentation topics for a package, click on the Pack-
.Fig. 2.6 R documentation for the read.csv() function. (Source: authors’ screenshot from RStudio) 2.8 · How to Find Help in RStudio
2
ages tab in the bottom right window and select the package name (highlighted in blue). The Help tab will then open with the full list of documentation available for that package.
Another very important document to consult for help using a package or func- tion is the vignette. Vignettes are designed as an all-purpose user’s guide for the package – they describe the problem that the package seeks to solve and how it is used. This document usually describes the functioning of the package in detail and provides examples and demonstrations of the problems and solutions. You can access a list of vignettes installed by calling the vignette() function. This will output a list of available vignettes to an R vignette tab in the top left window of RStudio. You can then run vignette(“SEMinR”) to access a particular vignette – in this case, the vignette for the package SEMinR (.Fig. 2.7).
# Check all vignettes available in R vignette()
# Load the SEMinR vignette vignette(“SEMinR”)
.Fig. 2.7 The SEMinR vignette. (Source: authors’ screenshot from RStudio)
45
2
Another source of help is using the demonstration code that comes bundled with most R packages. These demonstration files typically include an example dataset and model to demonstrate the purpose of the package’s functions. To check all available demonstration files, use the demo() function. For the specific demonstra- tion of the European Customer Satisfaction Index (ECSI) model (Eklöf & West- lund, 2002) in the SEMinR package, as originally presented by Tenenhaus, Esposito Vinzi, Chatelin, and Lauro (2005), use demo(“seminr-pls-ecsi”).
# Check all demos available in R demo()
# Load the SEMinR ECSI demo demo(“seminr-pls-ecsi”)
A final invaluable source of help can be found by accessing the greater R commu- nity on platforms such as Stack Overflow (7https://stackoverflow. com/). These ask-and-answer forums put you in touch with seasoned veterans who can provide useful tips and other options for executing all your favorite R packages and func- tions. Members of these communities typically respond quickly and can provide excellent advice and solutions (.Fig. 2.8).
.Fig. 2.8 Finding help online using Stack Overflow. (Source: authors’ screenshot from 7https://
stackoverflow. com/)
2.8 · How to Find Help in RStudio
2
Summary
In this chapter, we introduced the R statistical programming language and its popu- lar development environment, RStudio. You should now be familiar with the layout and functionality of RStudio, creating, downloading, and managing projects and RScript files. If you encounter a bug or a function that is unfamiliar, you should now have the requisite tools (and knowledge) for seeking out appropriate help. We strongly recommend the careful study of an introductory program to learning the R language. We also recommend the swirl package for learning R and provide some ideas to assist you in finding supplementary resources and gaining access to useful material.
?Exercise
In this chapter, we recommend the use of the swirl package to learn basic coding concepts and become familiar with the popular functions in R (see 7Sects. 2.6 and 2.7 on installing and loading swirl). Please complete the following lessons in the swirl package:
1. Basic building blocks 2. Workspaces and files 3. Sequences of numbers 4. Vectors
5. Missing values 6. Subsetting vectors 7. Matrices and data frames 8. Logic
9. Functions