Chapter 6 Functions

This chapter will explore how to use functions in R to perform advanced capabilities and actually ask questions about data. After considering a function in an abstract sense, it will discuss using built-in R functions, accessing additional functions by loading R packages, and writing your own functions.

6.1 What are Functions?

In a broad sense, a function is a named sequence of instructions (lines of code) that you may want to perform one or more times throughout a program. They provide a way of encapsulating multiple instructions into a single “unit” that can be used in a variety of different contexts. So rather than needing to repeatedly write down all the individual instructions for “make a sandwich” every time you’re hungry, you can define a make_sandwich() function once and then just call (execute) that function when you want to perform those steps. Typically, functions also accept inputs so you can make the things slightly differently from time to time. For instance, sometimes you may want to call make_sandwich(cheese) while another time make_sandwich(chicken).

In addition to grouping instructions, functions in programming languages also allow to model the mathematical definition of function, i.e. perform certain operations on a number of inputs that lead to an output. For instance, look at the function max() that finds the largest value among numbers:

The inputs are numbers 1, 2, and 3 in parenthesis, usually called arguments or parameters, and we say that these arguments are passed to a function (like a football). We say that a function then returns a value, number “3” in this example, which we can either print or assign to a variable and use later.

Finally, the functions may also have side effects. An example case is the cat() function that just prints it’s arguments. For instance, in case of the following line of code

we call function cat() with three arguments: "The answer is", 2 (note: 1+1 will be evaluated to 2), and "\n" (the line break symbol). However, here we may not care about the return value but in the side effect—the message being printed on the screen.

6.2 How to Use Functions

R functions are referred to by name (technically, they are values like any other variable, just not atomic values). As in many programming languages, we call a function by writing the name of the function followed immediately (no space) by parentheses (). Sometimes this is enough, for instance

gives us the current date and that’s it.

But often we want the function to do something with our inputs. In this case we put the arguments (inputs) inside the parenthesis, separated by commas (,). Thus computer functions look just like multi-variable mathematical functions, although usually with fancier names than f().

To keep functions and ordinary variables distinct, we include empty parentheses () when referring to a function by name. This does not mean that the function takes no arguments, it is just a useful shorthand for indicating that something is a function.

Note: You always need to supply the parenthesis if you want to call the function (force it to do what it is supposed to do). If you leave the parenthesis out, you get the function definition printed on screen instead. So cat() is actually a function call while cat is the function. You can see that it is a function if you just print it as print(cat). However, we ignore this distinction here.

If you call any of these functions interactively, R will display the returned value (the output) in the console. However, the computer is not able to “read” what is written in the console—that’s for humans to view! If you want the computer to be able to use a returned value, you will need to give that value a name so that the computer can refer to it. That is, you need to store the returned value in a variable:

  • In the last example, the resulting value of the “inner” function (e.g., sqrt()) is immediately used as an argument for the middle function (i.e. min()), value of which is fed in turn to the outer function print(). Because that value is used immediately, we don’t have to assign it a separate variable name. It is known as an anonymous variable.
  • note also that in the last example, we are solely interested in the side effect of the print() function. It also returns it’s argument (min(1.5, sqrt(3)) here) but we do not store it in a variable.

R functions take two types of arguments: positional arguments and named arguments: the function has to know how to treat each of it’s arguments. For instance, we can round number e to 3 digits by round(2.718282, 3). But in order to do this, the round() function must know that 2.718282 is the number and 3 is the requested number of digits, and not the other way around. It understands this because it requires the number to be the first argument, and digits the second argument. This approach works well in case of known small number of inputs. However, this is not an option for functions with variable number of arguments, such as cat(). cat() just prints out all of it’s (potentially a large number of) inputs, except a limited number of special named arguments. One of these is sep, the string to be placed between the other pieces of output (by default just a space is printed). Note the difference in output between

In the first case cat() prints 1, 2, "-", and the line break "\n", all separated by a space. In the second case the name sep ensures that "-" is not printed out but instead treated as the separator between 1, 2 and "\n".

6.3 Built-in R Functions

As you have likely noticed, R comes with a variety of functions that are built into the language. In the above example, we used the print() function to print a value to the console, the min() function to find the smallest number among the arguments, and the sqrt() function to take the square root of a number. Here is a very limited list of functions you can experiment with (or see a few more here).

Function Name Description Example
sum(a,b,...) Calculates the sum of all input values sum(1, 5) returns 6
round(x,digits) Rounds the first argument to the given number of digits round(3.1415, 3) returns 3.142
toupper(str) Returns the characters in uppercase toupper("hi there") returns "HI THERE"
paste(a,b,...) Concatenate (combine) characters into one value paste("hi", "there") returns "hi there"
nchar(str) Counts the number of characters in a string nchar("hi there") returns 8 (space is a character!)
c(a,b,...) Concatenate (combine) multiple items into a vector (see chapter 7) c(1, 2) returns 1, 2
seq(a,b) Return a sequence of numbers from a to b seq(1, 5) returns 1, 2, 3, 4, 5

To learn more about any individual function, look them up in the R documentation by using ?FunctionName account as described in the previous chapter.

“Knowing” how to program in a language is to some extent simply “knowing” what provided functions are available in that language. Thus you should look around and become familiar with these functions… but do not feel that you need to memorize them! It’s enough to simply be aware “oh yeah, there was a function that sums up numbers”, and then be able to look up the name and argument for that function.

6.4 Loading Functions

Although R comes with lots of built-in functions, you can always use more! Packages (also known as libraries) are additional sets of R functions (and data and variables) that are written and published by the R community. Because many R users encounter the same data management/analysis challenges, programmers are able to use these libraries and thus benefit from the work of others (this is the amazing thing about the open-source community—people solve problems and then make those solutions available to others). Popular packages include dplyr for manipulating data, ggplot2 for visualizations, and data.table for handling large datasets.

Most of the R packages do not ship with the R software by default, and need to be downloaded (once) and then loaded into your interpreter’s environment (each time you wish to use them). While this may seem cumbersome, it is a necessary trade-off between speed and size. R software would be huge and slow if it would include all available packages.

Luckily, it is quite simple to install and load R packages from within R. To do so, you’ll need to use the built-in R functions install.packages and library. Below is an example of installing and loading the stringr package (which contains many handy functions for working with character strings):

We stress here that you need to install each package only once per computer. As installation may be slow and and resource-demanding, you should not do it repeatedly inside your script!. Even more, if your script is also run by other users on their computers, you should get their explicit consent before installing additional software for them! The easiest remedy is to solely rely on manual installation.

Exactly the same syntax—install.packages("stringr")—is also used for re-installing it. You may want to re-install it if a newer version comes out, of if you upgrade your R and receive warnings about the package being built under a previous version of R.

After installation, the easiest way to get access to the functions is by loading the package:

This makes all functions in the stringr package available for R (see the documentation for a list of functions included with the stringr library). For instance, if we want to pad the word “justice” from left with tildes to create a width-10 string, we can do

We can use str_pad function without any additional hassle because library() command made it available.

This is an easy and popular approach. However, what happens if more than one package call a function by the same name? For instance, many packages implement function filter(). In this case the more recent package will mask the function as defined by the previous package. You will also see related warnings when you load the library. In case you want to use a masked function you can write something like package::function() in order to call it. For instance, we can do the example above with

This approach—specifying namespace in front of the function—ensures we access the function in the right package. If we call all functions in this way, we don’t even need to load the package with library() command. This is the preferred approach if you only need few functions from a large library.

6.5 Writing Functions

Even more exciting than loading other peoples’ functions is writing your own. Any time you have a task that you may repeat throughout a script—or sometimes when you just want to organize your code better—it’s a good practice to write a function to perform that task. This will limit repetition and reduce the likelihood of errors as well as make things easier to read and understand (and thus identify flaws in your analysis).

Functions are values like numbers and characters, so we use the assignment operator (<-) to store a function into a variable.

Although “values” (more precisely objects), functions are not atomic objects. But they can still be stored and manipulated in many ways like other objects.

Tidyverse style guide we follow in this books suggests to use verbs as function names, written in snake_case just like other variables.

The best way to understand the syntax for defining a function is to look at an example:

Function definition contains several important pieces:

  • The value assigned to the function variable uses the syntax function(....) to indicate that you are creating a function (as opposed to a number or character string).

  • If you want to feed your function with certain inputs, these must be referred somehow inside of your function. You list these names between the parentheses in the function(....) declaration. These are called formal arguments. Formal arguments will contain the values passed in when calling the function (called actual arguments). For example, when we call make_full_name("Alice", "Kim"), the value of the first actual argument ("Alice") will be assigned to the first formal argument (first_name), and the value of the second actual argument ("Kim") will be assigned to the second formal argument (last_name). Inside the function’s body, both of these formal arguments behave exactly as ordinary variables with values “Alice” and “Kim” respectively.

    Importantly, we could have made the formal argument names anything we wanted (name_first, xyz, etc.), just as long as we then use these formal argument names to refer to the argument while inside the function.

    Moreover, the formal argument names only apply while inside the function. You can think of them like “nicknames” for the values. The variables first_name, last_name, and full_name only exist within this particular function.

  • Body: The body of the function is a block of code that falls between curly braces {} (a “block” is represented by curly braces surrounding code statements). Note that cleanest style is to put the opening { immediately after the arguments list, and the closing } on its own line.

    The function body specifies all the instructions (lines of code) that your function will perform. A function can contain as many lines of code as you want—you’ll usually want more than 1 to make it worth while, but if you have more than 20 you might want to break it up into separate functions. You can use the formal arguments here as any other variables, you can create new variables, call other functions, you can even declare functions inside functions… basically any code that you would write outside of a function can be written inside of one as well!

    All the variables you create in the function body are local variables. These are only visible from within the function and “will be forgotten” as soon as you return from the function. However, variables defined outside of the function are still visible from within.

  • Return value is what your function produces. You can specify this by calling the return() function and passing that the value that you wish your function to return. It is typically the last line of the function. Note that even though we returned a variable called full_name, that variable was local to the function and so doesn’t exist outside of it; thus we have to store the returned value into another variable if we want to use it later (as with name <- make_full_name("Alice", "Kim")).

return() statement is usually unnecessary as R implicitly returns the last object it evaluated anyway. So we may shorten the function definition into

or even not store the concatenated names into full_name:

The last evaluation was concatenating the first and last name, and hence the full name will be implicitly returned.

We can call (execute) a function we defined exactly in the same way we call built-in functions. When we do so, R will take the actual arguments we passed in (e.g., "Alice" and "Kim") and assign them to the formal arguments. Then it executes each line of code in the function body one at a time. When it gets to the return() call, it will end the function and return the given value, which can then be assigned to a different variable outside of the function.

6.6 Conditional Statements

Functions are one way to organize and control the flow of execution (e.g., what lines of code get run in what order). There are other ways. In all languages, we can specify that different instructions will be run based on a different set of conditions. These are Conditional statements which specify which chunks of code will run depending on which conditions are true. This is valuable both within and outside of functions.

In an abstract sense, an conditional statement is saying:

IF something is true
  do some lines of code
OTHERWISE
  do some other lines of code

In R, we write these conditional statements using the keywords if and else and the following syntax:

(Note that the the else needs to be on the same line as the closing } of the if block. It is also possible to omit the else and its block).

The condition can be any variable or expression that resolves to a logical value (TRUE or FALSE). Thus both of the conditional statements below are valid:

Note, we can extend the set of conditions evaluated using an else if statement. For example:

See more about if, else and other related constructs in Appendix C.