Functions in R

An introduction to programming in R

NCEAS Learning Hub

Functions in R

A function groups a set of commands together to undertake a task in a reusable way.

R has a mind-blowing collection of built-in functions. To start, we will be using some built in R functions, and later learn to write our own.

When we execute or “call” a function, it includes the name of the function with parentheses around the arguments the function needs:

result_val <- function_name(argument1 = val1, argument2 = val2, ...)

Functions in R

Here are a few functions we’ve seen so far:

  • c() for combining elements into a vector
  • list() for creating a list
  • data.frame() for creating a data frame
  • mean() for calculating the mean value of a vector
  • head() for looking at the first few values of some object

Help pages for functions in R

RStudio provides an easy way to access the help documentation for functions.

Let’s look at the mean() function. To access the help page for mean(), enter the following into your console:

help(mean) ### `help` function to show a help page for a function
?mean      ### a more convenient shortcut
??mean     ### if you don't know the exact function name or package

Console vs. script panes

Most of the time you should be writing your code in scripts. But there are some things you should generally do in the console instead (things you don’t need to run every time you run the script):

  • help pages - you only need help as you are writing your script, not as you run it!
  • installing packages with install.packages()

Help pages for functions in R

The Help page is broken down into sections:

  • Description: An extended description of what the function does.
  • Usage: The arguments of the function(s) and their default values.
  • Arguments: An explanation of the data each argument is expecting.
  • Details: Any important details to be aware of.
  • Value: The data the function returns.
  • See Also: Any related functions you might find useful.
  • Examples: Some examples for how to use the function.

Help pages for functions in R

Not all functions have (or require) arguments

For example, check out the documentation or Help page for date().

?date()

Functions and packages in R

In addition to the built-in functions available in R, there are also many many packages available with other functions and/or datasets.

To install a new package into your library (a location on your computer where R will find the packages) (do this in the console, not script!):

### vetted packages from the CRAN package repository:
install.packages('<packagename here>')
### some packages are available through GitHub:
remotes::install_github('<username>/<packagename>')

Just because a package is installed doesn’t mean R has access to the functions yet! We need to load (“attach”) a package into R from your package library. Typically you do this at the top of a script.

library(packagename) ### note, no quotes needed!

Functions and packages in R

Two common error messages

Always carefully read any error messages!

Here are two common error messages associated with loading packages and functions:

  • Error in library(<packagename>) : there is no package called ‘<packagename>’
    • you probably either misspelled the package name or haven’t yet installed it.
  • Error in <functionname>(): could not find function "<functionname>"
    • you probably have the name wrong, or haven’t loaded the package (with library()) that contains the function.