# 2 Functions: Introductory concepts

## 2.1 Software requirements

### 2.1.1 R packages

• New: pbapply

We’ll be sticking mostly with base R functions in this chapter. But we’ll also show you a few extra features and considerations for the main data wrangling packages. As per usual, run the following code chunk to install (if necessary) and load everything.

if (!require("pacman")) install.packages("pacman")
pacman::p_load(pbapply, data.table, tidyverse)

## 2.2 Basic syntax

We have already seen and used a multitude of functions in R. Some of these functions come pre-packaged with base R (e.g. mean()), while others are from external packages (e.g. dplyr::filter()). Regardless of where they come from, functions in R all adopt the same basic syntax:

function_name(ARGUMENTS)

For much of the time, we will rely on functions that other people have written for us. However, you can — and should! — write your own functions too. This is easy to do with the generic function() function.5 The syntax will again look familiar to you:

function(ARGUMENTS) {
OPERATIONS
return(VALUE)
}

While it’s possible and reasonably common to write anonymous functions like the above, we typically write functions because we want to reuse code. For this typical use-case it makes sense to name our functions.6

my_func =
function(ARGUMENTS) {
OPERATIONS
return(VALUE)
}

For some short functions, you don’t need to invoke the curly brackets or assign an explicit return object (more on this below). In these cases, you can just write your function on a single line:

my_short_func = function(ARGUMENTS) OPERATION

Try to give your functions short, pithy names that are informative to both you and anyone else reading your code. This is harder than it sounds, but will pay off down the road.

## 2.3 A simple example

Let’s write out a simple example function, which gives the square of an input number.

square =        ## Our function name
function(x) { ## The argument(s) that our function takes as an input
x^2         ## The operation(s) that our function performs
}

Test it.

square(3)
#> [1] 9

Great, it works. Note that for this simple example we could have written everything on a single line; i.e. square = function(x) x^2 would work just as well. (Confirm this for yourself.) However, we’re about to add some extra conditions and options to our function, which will strongly favour the multi-line format.

Aside: We wish to emphasise that our little square() function is not exciting or, indeed, particularly useful. R’s built-in arithmetic functions already take care of (vectorised) exponentiation and do so very efficiently. (See ?Arithmetic.) However, we’re going to continue with this conceptually simple example, since it will provide a clear framework for demonstrating some general principles about functions in R.

### 2.3.1 Specifying return values

Notice that we didn’t specify a return value for our function. This will work in many cases because R’s default behaviour is to automatically return the final object that you created within the function. However, this won’t always be the case. Opinions on this differ, but our own recommendation is that you get into the habit of assigning the return object(s) explicitly with return(). Let’s modify our function to do exactly that.

square =
function(x) {
## Create an intermediary object (that will be returned)
x_sq = x^2

## The value(s) or object(s) that we want returned.
return(x_sq)
}

Again, test that it works.

square(5)
#> [1] 25

Specifying an explicit return value is also helpful when we want to return more than one object. For example, let’s say that we want to remind our user what variable they used as an argument in our function:

square =
function(x) {
x_sq = x^2

## The list of object(s) that we want returned.
return(list(value = x, value_squared = x_sq))
}
square(3)
#> $value #> [1] 3 #> #>$value_squared
#> [1] 9

Note that multiple return objects have to be combined in a list. We didn’t have to name these separate list elements — i.e. “value” and “value_squared” — but it will be helpful for users of our function. Nevertheless, remember that many objects in R contain multiple elements (vectors, data frames, and lists are all good examples of this). So we can also specify one of these “array”-type objects within the function itself if that provides a more convenient form of output. For example, we could combine the input and output values into a data frame:

square =
function(x) {
x_sq = x^2

## Bundle up our input and output values into a convenient dataframe.
d = data.frame(value=x, value_squared=x_sq)

return(d)
}

Test.

square(12)
#>   value value_squared
#> 1    12           144

### 2.3.2 Specifying default argument values

Another thing worth noting about R functions is that you can assign default argument values. You have already encountered some examples of this in action.7 We can add a default option to our own function pretty easily.

square =
function(x = 1) { ## Setting the default argument value
x_sq = x^2
d = data.frame(value = x, value_squared = x_sq)

return(d)
}
square()  ## Will take the default value of 1.
#>   value value_squared
#> 1     1             1
square(2) ## Now takes the explicit value that we give it.
#>   value value_squared
#> 1     2             4

We’ll return to the issues of specifying default values, handling invalid inputs, and general debugging in Section 3.2.

### 2.3.3 Aside: Environments and lexical scoping

Before continuing, take a second to note that none of the intermediate objects that we created inside the above functions (x_sq, df, etc.) have made their way into your global environment.8 R has a set of so-called lexical scoping rules, which govern where it stores and evaluates the values of different objects. Without going into too much depth, the practical implication of lexical scoping is that functions operate in a quasi-sandboxed environment. They don’t return or use objects in the global environment unless they are forced to (e.g. with a return() command). Similarly, a function will only look to outside environments (e.g. a level “up”) to find an object if it doesn’t see the object named within itself.

We’ll revisit the ideas of distinct object environments and lexical scoping when we get to functional programming in Section 2.5.3 below, and then again in Section 3.2.

## 2.4 Control flow

Now that we’ve got a good sense of the basic function syntax, it’s time to learn control flow. That is, we want to control the order (or “flow”) of statements and operations that our functions evaluate.

### 2.4.1 if and ifelse

We’ve already encountered conditional statements like if() and ifelse() numerous times in the book thus far.9 However, let’s see how they can work in our own bespoke functions by slightly modifying our square function. This time, instead of specifying a default input value of 1 in the function argument itself, we’ll specify a value of NULL. Then we’ll use an if() statement to reassign this default to one.

square =
function(x = NULL) {  ## Default value of NULL
if (is.null(x)) x = 1 ## Re-assign default to 1

x_sq = x^2
d = data.frame(value = x, value_squared = x_sq)

return(d)
}
square()
#>   value value_squared
#> 1     1             1

Why go through the rigmarole of specifying a NULL default inpute if we’re going to change it to 1 anyway? Admittedly, this is a pretty silly thing to do in the above example. However, consider what it buys us in the next code chunk:

square =
function(x = NULL) {

if (is.null(x)) { ## Start multi-line IF statement with {
x = 1
## Message to users:
message("No input value provided. Using default value of 1.")
}               ## Close multi-line if statement with }

x_sq = x^2
d = data.frame(value = x, value_squared = x_sq)

return(d)
}
square()
#> No input value provided. Using default value of 1.
#>   value value_squared
#> 1     1             1

This time, by specifying NULL in the argument — alongside the expanded if() statement — our function now both takes a default value and generates a helpful message.10 Note too the use of curly brackets for conditional operations that span multiple lines after an if() statement. This provides a nice segue to ifelse() statements. As we’ve already seen , these be written as a single conditional call where the format is:

ifelse(CONDITION, DO IF TRUE, DO IF FALSE)

Within our own functions, though we’re more likely to write them over several lines. Consider, for example a new function that evaluates whether our square() function is doing its job properly.

eval_square =
function(x) {

y = input_df$y[n] ## Apply our function on the the extracted values multi_func(x, y) }) return(d) } There are three conceptual steps to the above code chunk: 1. First, we create a new function called parent_func(), which takes a single input: a data frame containing x and y columns (and potentially other columns too). 2. This input data frame is then passed to a second (nested) function, which will iterate over the rows of the data frame. 3. During each iteration, the x and y values for that row are passed to our original multi_func() function. This will return a data frame containing the desired output. Let’s test that it worked using two different input data frames. ## Case 1: Iterate over x=1:5 and y=6:10 input_df1 = data.frame(x = 1:5, y = 6:10) parent_func(input_df1) #> x y z #> 1 1 6 7.000000 #> 2 2 7 6.363961 #> 3 3 8 6.350853 #> 4 4 9 6.500000 #> 5 5 10 6.708204 ## Case 2: Iterate over *all possible combinations* of x=1:5 and y=6:10 input_df2 = expand.grid(x = 1:5, y = 6:10) parent_func(input_df2) #> x y z #> 1 1 6 7.000000 #> 2 2 6 5.656854 #> 3 3 6 5.196152 #> 4 4 6 5.000000 #> 5 5 6 4.919350 #> 6 1 7 8.000000 #> 7 2 7 6.363961 #> 8 3 7 5.773503 #> 9 4 7 5.500000 #> 10 5 7 5.366563 #> 11 1 8 9.000000 #> 12 2 8 7.071068 #> 13 3 8 6.350853 #> 14 4 8 6.000000 #> 15 5 8 5.813777 #> 16 1 9 10.000000 #> 17 2 9 7.778175 #> 18 3 9 6.928203 #> 19 4 9 6.500000 #> 20 5 9 6.260990 #> 21 1 10 11.000000 #> 22 2 10 8.485281 #> 23 3 10 7.505553 #> 24 4 10 7.000000 #> 25 5 10 6.708204 ## 2.6 Further resources In Chapters 3 and 4, we’ll dive into more advanced programming and function topics (debugging, parallel implementation, etc.). However, we hope that this chapter has given you solid grasp of the fundamentals. We highly encourage you to start writing some of your own functions. You will be doing this a lot as your career progresses. Establishing an early mastery of function writing will put you on the road to awesome data science successTM. Here are some additional resources for both inspiration and reference: • Garrett Grolemund and Hadley Wickham’s R for Data Science book — esp. chapters 19 (“Functions)”) and 21 (“Iteration)”) — covers much of the same ground as we have here, with particular emphasis on the purrr package for iteration. • If you’re looking for an in-depth treatment, then we can highly recommend Hadley’s Advanced R (2nd ed.) He provides a detailed yet readable overview of all the concepts that we touched on in this chapter, including more on his (and R’s) philosophy regarding functional programming (see Section ||). • If you’re in the market for a more concise overview of the different *apply() functions, then we recommend this blog post by Neil Saunders. • On the other end of the scale, Jenny Bryan (all hail) has created a fairly epic purrr tutorial mini-website. (Bonus: She goes into more depth about working with lists and list columns.) ## 2.7 Addendum: Inspecting function source code Looking inside a function is not only important for debugging — a subject covered in 3.2 — but is also a great way to pick up programming tips and tricks. We refer to this as inspecting a function’s source code. For some functions, viewing the source code is a simple matter of typing the function name into your R console (without the parentheses!) and letting R print the object to screen. Try this yourself with the num_to_alpha function that we created earlier. Or, here’s the source code for replace(), arguably the simplest base R function around: replace #> function (x, list, values) #> { #> x[list] <- values #> x #> } #> <bytecode: 0x55ea810d2338> #> <environment: namespace:base> Unfortunately, the simple print-function-to-screen approach doesn’t work once you start getting into functions that have different dispatch “methods” (e.g. associated with S3 or S4 classes), or rely on compiled code underneath the hood (e.g. written in C or Fortran). The good news is that you can still view the source code, although it does require a bit more legwork. As a quick example, consider what happens if we try to look at the source code for R’s generic summary function. summary #> function (object, ...) #> UseMethod("summary") #> <bytecode: 0x55ea7c0bd208> #> <environment: namespace:base> The UseMethod("summary") part is telling us that R will invoke different methods for summarising different objects, depending on their class. Obviously, this makes sense. We wouldn’t expect a data frame to be summarised in the same way as a regression object. To see which methods are available to summary in our current R session, we can use the methods() function: methods(summary) #> [1] summary,ANY-method summary,DBIObject-method #> [3] summary.aov summary.aovlist* #> [5] summary.aspell* summary.check_packages_in_dir* #> [7] summary.connection summary.data.frame #> [9] summary.Date summary.default #> [11] summary.Duration* summary.ecdf* #> [13] summary.factor summary.ggplot* #> [15] summary.glm summary.haven_labelled* #> [17] summary.hcl_palettes* summary.infl* #> [19] summary.Interval* summary.lm #> [21] summary.loess* summary.manova #> [23] summary.matrix summary.mlm* #> [25] summary.nls* summary.packageStatus* #> [27] summary.Period* summary.POSIXct #> [29] summary.POSIXlt summary.ppr* #> [31] summary.prcomp* summary.princomp* #> [33] summary.proc_time summary.rlang_error* #> [35] summary.rlang_trace* summary.srcfile #> [37] summary.srcref summary.stepfun #> [39] summary.stl* summary.table #> [41] summary.tukeysmooth* summary.vctrs_sclr* #> [43] summary.vctrs_vctr* summary.warnings #> see '?methods' for accessing help and source code Here we see the list of possible summary methods, which all take the form summary.OBJECTCLASS. Behind the scenes, when we call summary(x), R first determines the class of x and then dispatches to the appropriate summary method. If x is a data frame, it will invoke summary.data.frame(). If x is an lm object, it will invoke summary.lm. And so forth.17 Accessing the source code of a particular summary method is then a straightforward matter of being explicit about object class. For example: summary.data.frame #> function (object, maxsum = 7L, digits = max(3L, getOption("digits") - #> 3L), ...) #> { #> ncw <- function(x) { #> z <- nchar(x, type = "w") #> if (any(na <- is.na(z))) { #> z[na] <- nchar(encodeString(z[na]), "b") #> } #> z #> } #> z <- lapply(X = as.list(object), FUN = summary, maxsum = maxsum, #> digits = 12L, ...) #> nv <- length(object) #> nm <- names(object) #> lw <- numeric(nv) #> nr <- if (nv) #> max(vapply(z, function(x) NROW(x) + !is.null(attr(x, #> "NAs")), integer(1))) #> else 0 #> for (i in seq_len(nv)) { #> sms <- z[[i]] #> if (is.matrix(sms)) { #> cn <- paste(nm[i], gsub("^ +", "", colnames(sms), #> useBytes = TRUE), sep = ".") #> tmp <- format(sms) #> if (nrow(sms) < nr) #> tmp <- rbind(tmp, matrix("", nr - nrow(sms), #> ncol(sms))) #> sms <- apply(tmp, 1L, function(x) paste(x, collapse = " ")) #> wid <- sapply(tmp[1L, ], nchar, type = "w") #> blanks <- paste(character(max(wid)), collapse = " ") #> wcn <- ncw(cn) #> pad0 <- floor((wid - wcn)/2) #> pad1 <- wid - wcn - pad0 #> cn <- paste0(substring(blanks, 1L, pad0), cn, substring(blanks, #> 1L, pad1)) #> nm[i] <- paste(cn, collapse = " ") #> } #> else { #> sms <- format(sms, digits = digits) #> lbs <- format(names(sms)) #> sms <- paste0(lbs, ":", sms, " ") #> lw[i] <- ncw(lbs[1L]) #> length(sms) <- nr #> } #> z[[i]] <- sms #> } #> if (nv) { #> z <- unlist(z, use.names = TRUE) #> dim(z) <- c(nr, nv) #> if (anyNA(lw)) #> warning("probably wrong encoding in names(.) of column ", #> paste(which(is.na(lw)), collapse = ", ")) #> blanks <- paste(character(max(lw, na.rm = TRUE) + 2L), #> collapse = " ") #> pad <- floor(lw - ncw(nm)/2) #> nm <- paste0(substring(blanks, 1, pad), nm) #> dimnames(z) <- list(rep.int("", nr), nm) #> } #> else { #> z <- character() #> dim(z) <- c(nr, nv) #> } #> attr(z, "class") <- c("table") #> z #> } #> <bytecode: 0x55ea81648b50> #> <environment: namespace:base> By the way, it’s also possible to go the other way around; you can view all of the generic methods associated with a particular object class. For example, there are lots of valid methods associated with data frames: methods(class = "data.frame") #> [1] [ [[ [[<- [<- #> [5]$<-               add_count         aggregate         anti_join
#>   [9] anyDuplicated     anyNA             arrange_          arrange
#>  [13] as_factor         as_tibble         as.col_spec       as.data.frame
#>  [17] as.data.table     as.list           as.matrix         as.tbl
#>  [21] auto_copy         by                cbind             coerce
#>  [25] coerce<-          collapse          collect           complete_
#>  [29] complete          compute           count             dim
#>  [33] dimnames          dimnames<-        distinct_         distinct
#>  [37] do_               do                dplyr_col_modify  dplyr_reconstruct
#>  [41] dplyr_row_slice   drop_na_          drop_na           droplevels
#>  [45] duplicated        edit              expand_           expand
#>  [49] extract_          extract           fill_             fill
#>  [53] filter_           filter            format            formula
#>  [57] fortify           full_join         gather_           gather
#>  [61] ggplot_add        glimpse           group_by_         group_by
#>  [65] group_data        group_indices_    group_indices     group_keys
#>  [69] group_map         group_modify      group_nest        group_size
#>  [73] group_split       group_trim        group_vars        groups
#>  [77] head              initialize        inner_join        intersect
#>  [81] is.na             left_join         Math              merge
#>  [85] mutate_           mutate            n_groups          na.exclude
#>  [89] na.omit           nest_by           nest_join         nest_legacy
#>  [93] nest              Ops               pivot_longer      pivot_wider
#>  [97] plot              print             prompt            pull
#> [101] rbind             relocate          rename_           rename_with
#> [105] rename            replace_na        right_join        row.names
#> [109] row.names<-       rows_delete       rows_insert       rows_patch
#> [113] rows_update       rows_upsert       rowsum            rowwise
#> [117] same_src          sample_frac       sample_n          select_
#> [121] select            semi_join         separate_         separate_rows_
#> [125] separate_rows     separate          setdiff           setequal
#> [129] show              slice_            slice_head        slice_max
#> [133] slice_min         slice_sample      slice_tail        slice
#> [137] slotsFromS3       split             split<-           spread_
#> [141] spread            stack             str               subset
#> [145] summarise_        summarise         summary           Summary
#> [149] t                 tail              tally             tbl_vars
#> [153] transform         transmute_        transmute         type.convert
#> [157] ungroup           union_all         union             unique
#> [161] unite_            unite             unnest_legacy     unnest
#> [165] unstack           within            xtfrm
#> see '?methods' for accessing help and source code

In this brief addendum, we’ve focused on the source code for different dispatch methods. Accessing compiled source code (e.g. written in C or Fortran) is a bit more complicated and, frankly, beyond the scope of what we want to show you here. You are already well-equipped to peruse many of the key R functions that you are likely to be using. For a full length treatment of how to access source code of R functions, we recommend any of the three sources: