• 1. Functions

Motivating scenario: You are getting up and running in R and want to get started with a major workhorse of working in R — functions (how R does stuff).

Learning goals: By the end of this sub-chapter you should be able to

  1. Use R functions.
    • Understand that R functions take (zero or more) arguments
    • And that they return something.
  2. “Pipe” output from one R function into the next R function with the pipe |> operator.

R Functions

R functions: See Posit’ss recipe for R functions for more detail.

R comes with tons of built-in functions that do everything from basic math to advanced statistical modeling. So not only can we calculate the mean and variance in Clarkia xantiana petal lengths with the mean() and var() functions, respectively, but we can test the null hypothesis that mean petal size in xantiana is equal to that of parviflora with the t.test() function. Functions are the foundation of how we do things in R – they save time and ensure consistency across your analyses.

Functions take arguments

We put arguments in parentheses. For example, when typing sqrt(25), sqrt() is the function, 25 is the argument, and 5 is the output. Figure 1 A shows the log function, taking the argument, 1000, and returning 6.9077.

Panel A is titled "A function taking one argument." It shows the code log(1000) in a green box, with arrows labeling “function” pointing to log and “argument” pointing to 1000. Below, the output [1] 6.9077 is shown, with an arrow labeled "output." Panel B is titled "A function taking two arguments." It shows log(1000, base = 10) in a green box. Arrows label log as the function, 1000 as argument 1, and base = 10 as a named second argument. Below, the output [1] 3 is shown with an arrow labeled "output."
Figure 1: A) A function taking one argument: log(1000) uses the default base (e), returning 6.9077. B) A function taking two arguments: log(1000, base = 10), explicitly supplies the base (10) as the second argument, returning 3.

Functions can take multiple arguments:

If you don’t specify them all, R will either tell you to provide them, or assumes default values. For example, the log function defaults to the natural log (base e), so log(1000) returns 6.908. If you want the logarithm with base 10, you need to specify it explicitly as log(1000, 10), which returns 3 (Figure 1 A). Note that argument order matters: log(10, 1000) returns 0.3333333, while log(1000, 10) returns 3 (Figure 1 B).

Tips for using functions in R

Use named arguments in functions.

For example, typing log(1000, base = 10) makes what each value represents obvious (improving code readability), and allows flexibility in argument order (e.g. log(base = 10, 1000) gives the same value as log(1000, base = 10)). Thus, using named arguments makes your code readable and robust.

Use = to assign arguments in functions

When specifying arguments inside a function, always use = (e.g., log(1000, base = 10)). Do not use <-, which is for assigning values to variables. Otherwise, R might mistakenly store the argument as a variable, leading to unexpected results.

Pipe together functions with |>

The pipe, |>, provides a clean way to pass the output of one function into another. For example, we can find the square root of the \(\text{log}_{10}\) of 1000, rounded to two decimal places, as follows:

log(1000, base = 10)   |>  
    sqrt()             |>  
    round(digits = 2)
[1] 1.73

Notice that we did not explicitly provide an argument to sqrt() — it simply used the output of log(1000, base = 10). Similarly, the round() function then rounded the square root of 3 to two decimal places.