Functions in R

An introduction to programming in R

NCEAS Learning Hub

Functions in R

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

R also has a mind-blowing collection of built-in functions ready to use. 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, usually it looks like the function name with parentheses around the “arguments” the function needs in order to do what it was built to do, like this:

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

There are thousands of built-in functions available when you first start up R, but 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 you get! Most of the time they are pretty helpful to let you know what you’ve done wrong. 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.