Introduction

Define a function

The basic syntax of functions is given below:

FunctionName <- function(arg.1, arg.2, arg.3 = 2, ...) {
  new.var <- arg.1 + arg.2  # comment
  return(new.var / arg.3)
}

where

• FunctionName is the name of the function. This can be any valid variable name, but you should avoid using names that are used elsewhere in R, such as dir, function, plot, etc.

• function is a reserved word in R that is used to provide a mechanism for defining new functions in R.

• ( ) is used to contain function arguments. Parenthesis can also be used in mathematical expressions to denote modifications to normal order of operations (precedence rules).

• arg.1, arg.2, arg.3 are the arguments of the function. You can write a function with any number of arguments. These can be R objects: numbers, strings, arrays, data tables, or even pointers to other functions; anything that is needed for the function to run. Some arguments have default values specified, such as arg.3 = 2 in our example. Arguments without a default must have a value supplied for the function to run. You are not required to provide a value for those arguments with a default, as the function will use the default value.

• ... is a special argument called the ellipsis. This argument will match any arguments not otherwise matched, and can be easily passed on to other functions. This technique is often used in plotting, but also has uses in many other places. For this example function it was not used, but included in order to make you aware of its existence. An example of a function that uses the ellipsis argument is given in the “Ellipsis argument” section.

• { } is used to contain the function body, code that is run every time the function is called.

• <- is an assignment operator. In the example function, the first and second arguments are summed (arg.1 + arg.2) and the result is assigned to a new variable (new.var).

• # is the character defining comments, the rest of the line after this character is ignored.

• return is a function in R. If the end of a function is reached without calling this function, the value of the last evaluated expression is returned. Therefore, it was not needed in the example function.

Load a function

For R to be able to run your function, it needs first to be read into memory. There are two methods for loading functions into the memory:

1. copy the function text and paste it into the console, or
2. use the source(file) function to load your function(s) from a file.

The file argument in the source function is typically specified as a character string giving the pathname of the file or URL to read from. One could also specify the name of the file and the source function will assume the file is located in the working directory. Every R session has a default location on your OS’s file structure called the working directory. You need to keep track and deliberately set your working directory in each R session.

The getwd function tells you what the current working directory is. For my current R session the working directory is:

getwd()

## [1] "I:/HOME/Repos/r-workshop"

To change the working directory, use the setwd(dir) function, where dir is the pathname of the new working directory. Be sure to enter the new working directory as a character string (enclose it in quotes) and specify the separator between folders using a forward slash (/). For Windows users, the forward slash will look strange because you’re used to the backslash (\) separator used by File Explorer (previously known as Windows Explorer).

Exercise

This exercise will test your ability to define and load a function into R.

1. Copy (CTRL+C) the example function from above and paste (CTRL+V) it into a New File in your text editor, such as Notepad++.
2. Save the file to a folder of your choosing and name it “function.R”—the “.R” file extension indicates an R-source (script) file.
3. Set the working directory to the folder containing your R-source file.
4. Load the function into your current R session using the source function.
5. Confirm that your function is available for use by typing ls() to list all R objects you’ve created or loaded during your R session.
6. Run the function passing what you think are appropriate arguments.
7. Repeat the process by refining the function, loading it into the R session, and using it.

One trick for working in a console is to use the up and down arrows to recall previously used commands.

Ellipsis argument

The ellipsis argument ... is a way of passing an arbitrary number of arguments to a function inside another function. For example, suppose you wanted to define a function that adds noise to your data and plots the results. You can define the function as

PlotNoisyData <- function(x, y, ...) {
  new.y <- y + rnorm(length(y), 0, 5)
  plot(x, new.y, ...)
}

Notice that both the PlotNoisyData function and the embedded plot function include an ellipsis argument .... Now we can run the function and not only pass the required data arguments (x and y) but also a set of optional graphical arguments (type and col) that are accepted by the plot function and passed through ... . An argument specification of type = "b" indicates that both points and lines are desired, whereas col = "red" indicates that the drawn points and lines will be the color red.

PlotNoisyData(x = 1:50, y = rep(0, 50), type = "b", col = "red")

Installing packages

R packages only need to be installed once on your computer. Use the install.packages function to install packages from a CRAN-like repository. For example, to install the inlmisc package from CRAN, use the command

install.packages("inlmisc", dependencies = TRUE)

By default, install.packages also installs the packages which inlmisc depends on, links to, or imports; see the package description for its dependencies. If you wish to install a package from a different CRAN-like repository, such as the Geological survey R Archive Network (GRAN), the repos argument must be specified. For example, to install the smwrData package from GRAN, use

repos <- c(GRAN = "https://owi.usgs.gov/R", CRAN = "https://cran.r-project.org/")
install.packages("smwrData", repos = repos)

Notice that a CRAN repository was also included in the command, this ensures that any package dependencies residing on CRAN will also be installed. To install a package from a locally stored ZIP file, use

install.packages(file.choose(), repos = NULL)

Notice that the file.choose() command was used in place of a package name, this will allow you choose the “.zip” file interactively.

Sometimes a package of interest is only available on GitHub. To install a package directly from a GitHub repository, use the install_github function in the devtools package. For example, to install the AnomalyDetection package from its GitHub repository, use the command

devtools::install_github("twitter/AnomalyDetection")

Updating packages

Run the update.packages() command to ensure that all the packages in your local R library are up to date. It downloads the list of available packages and their current versions, compares it with those installed and offers to download and install any that have later versions on the repositories.

Load a package

Only when a package is loaded are its contents (functions, datasets, and documentation) available in your R session. The library function is used to load a package into the current R session. For example, to load the viridisLite package use the command

library(viridisLite)

Getting help from the console

To start R’s online documentation in a web browser, the command is

help.start()

To get more information on any specific package, such as the sp package, the command is

help(package = "sp")

And to open the help documentation for a specific function, such as the bbox function, the command is

?bbox

## No documentation for 'bbox' in specified packages and libraries:
## you could try '??bbox'

Wait a gosh-darn minute, that didn’t work! It appears that R is unable to find the help documentation for bbox because it belongs to the sp package. We never loaded the sp package, so it should come as no suprise that its documentation is unavailable for use. At this point, you can either (1) do a fuzzy match of the function name using the ??bbox command, as recommended in the error message and appropriate when you don’t know the package name; (2) load the sp package using the library function and rerun ?bbox; or (3) bypass the package loading step by running the command

?sp::bbox

Task views

CRAN Task Views are guides to the packages and functions useful for certain disciplines and methodologies. These guides are maintained by volunteers with expertise in a specified area. The maintainers provide annotated guidance to routines and packages. This is particularly helpful to track new packages or functionality.

Other resources

There are endless resources online, here’s just a few

• R for cats is a lighthearted introduction to the R-programming language.

• R-bloggers is a blog aggregator of content contributed by bloggers who write about R.

• StackOverflow is a discussion forum for all things related to programming.

• R for Data Science, a book by Hadley Wickham.

Exercise

1. Spend a little time exploring R’s online documentation.

2. Find a function in the stats package that can be used for fitting linear models.

3. Open the functions help documentation and run its example code.

4. Open the help documentation for Edgar Anderson’s iris dataset and run its example code.

5. Open a task view of your choosing and explore available packages.