r4ds/functions.qmd

# Functions {#sec-functions}

```{r}
#| results: "asis"
#| echo: false
source("_common.R")
status("drafting")
```

## Introduction

One of the best ways to improve your reach as a data scientist is to write functions.
Functions allow you to automate common tasks in a more powerful and general way than copy-and-pasting.
Writing a function has three big advantages over using copy-and-paste:

1.  You can give a function an evocative name that makes your code easier to understand.

2.  As requirements change, you only need to update code in one place, instead of many.

3.  You eliminate the chance of making incidental mistakes when you copy and paste (i.e. updating a variable name in one place, but not in another).

Writing good functions is a lifetime journey.
Even after using R for many years we still learn new techniques and better ways of approaching old problems.
The goal of this chapter is to get you started on your journey with functions with two useful types of functions:

-   Vector functions take one or more vectors as input and return a vector as output.
-   Data frame functions take a data frame as input and return a data frame as output.

The chapter concludes with some also gives you some suggestions for how to style your functions.

### Prerequisites

```{r}
library(tidyverse)
```

## Vector functions

We'll begin with vector functions: functions that take one or more vectors and return a vector result.

### Getting started

You should consider writing a function whenever you've copied and pasted a block of code more than twice (i.e. you now have three copies of the same code).
For example, take a look at this code.
What does it do?

```{r}
df <- tibble::tibble(
  a = rnorm(10),
  b = rnorm(10),
  c = rnorm(10),
  d = rnorm(10)
)

df |> mutate(
  a = (a - min(a, na.rm = TRUE)) / 
    (max(a, na.rm = TRUE) - min(a, na.rm = TRUE)),
  b = (b - min(b, na.rm = TRUE)) / 
    (max(b, na.rm = TRUE) - min(a, na.rm = TRUE)),
  c = (c - min(c, na.rm = TRUE)) / 
    (max(c, na.rm = TRUE) - min(c, na.rm = TRUE)),
  d = (d - min(d, na.rm = TRUE)) / 
    (max(d, na.rm = TRUE) - min(d, na.rm = TRUE))  
)
```

You might be able to puzzle out that this rescales each column to have a range from 0 to 1.
But did you spot the mistake?
When Hadley wrote this code he made an error when copying-and-pasting and forgot to change an `a` to a `b`.
Preventing this type of mistake of is one very good reason to learn how to write functions.

To write a function you need to first analyse the code to figure out what's the same and what's different:

```{r}
#| eval: false

(a - min(a, na.rm = TRUE)) / (max(a, na.rm = TRUE) - min(a, na.rm = TRUE))
(b - min(b, na.rm = TRUE)) / (max(b, na.rm = TRUE) - min(b, na.rm = TRUE))
(c - min(c, na.rm = TRUE)) / (max(c, na.rm = TRUE) - min(c, na.rm = TRUE))
(d - min(d, na.rm = TRUE)) / (max(d, na.rm = TRUE) - min(d, na.rm = TRUE))  
```

The only thing that changes on each line is the name of the variable.
That will become the argument to our function: the arguments to a function are the things that can change each time you call it.

Creating function always looks like `name <- function(arguments) body`:

1.  You need to pick a **name** for the function.
    Here we used `rescale01` because this function rescales a vector to lie between 0 and 1.

2.  You list the inputs, or **arguments**, to the function inside `function`.
    Here we have just one argument.
    If we had more the call would look like `function(x, y, z)`.

3.  You place the code you have developed in the **body** of the function, a `{` block that immediately follows `function(...)`.

```{r}
rescale01 <- function(x) {
  (x - min(x, na.rm = TRUE)) / (max(x, na.rm = TRUE) - min(x, na.rm = TRUE))
}
```

At this point you might test with a few simple inputs:

```{r}
rescale01(c(-10, 0, 10))
rescale01(c(1, 2, 3, NA, 5))
```

Now we can rewrite the original code as:

```{r}
df |> mutate(
  a = rescale01(a),
  b = rescale01(b),
  c = rescale01(c),
  d = rescale01(d)  
)
```

(In @sec-iteration, you'll learn how to use `across()` to reduce the duplication even further so you can write `df |> mutate(across(a:d, rescale))`).

You might notice that our function contains some duplication in this code.
We're computing the range of the data three times, so it makes sense to do it in one step using `range()` with computes both the minimum and maximum in one step:

```{r}
rescale01 <- function(x) {
  rng <- range(x, na.rm = TRUE)
  (x - rng[1]) / (rng[2] - rng[1])
}
```

Pulling out intermediate calculations into named variables is a good practice because it makes it more clear what the code is doing.

Another advantage of functions is that if our requirements change, we only need to make the change in one place.
For example, we might discover that some of our variables include infinite values, and `rescale01()` fails:

```{r}
x <- c(1:10, Inf)
rescale01(x)
```

Because we've extracted the code into a function, we only need to make the fix in one place:

```{r}
rescale01 <- function(x) {
  rng <- range(x, na.rm = TRUE, finite = TRUE)
  (x - rng[1]) / (rng[2] - rng[1])
}
rescale01(x)
```

This is an important part of the "do not repeat yourself" (or DRY) principle.
The more repetition you have in your code, the more places you need to remember to update when things change (and they always do!), and the more likely you are to create bugs over time.

### Mutate functions

When thinking about your own functions it's useful to think about functions that return vectors of the same length as their input.
These are the sorts of functions that you'll use in `mutate()` and `filter()`.

For example, maybe instead of rescaling to 0-1 you want to rescale to mean 0 sd 1:

```{r}
rescale_z <- function(x) {
  (x - mean(x, na.rm = TRUE)) / sd(x, na.rm = TRUE)
}
```

Sometimes your functions are highly specialised for one data analysis.
For example, you might have a bunch of variables that record missing values as 997, 998, or 999:

```{r}
fix_na <- function(x) {
  if_else(x %in% c(997, 998, 999), NA, x)
}
```

Other cases, you might be wrapping up a simple a `case_when()` to give it a standard name:

```{r}
clamp <- function(x, min, max) {
  case_when(
    x < min ~ min,
    x > max ~ max,
    .default = x
  )
}
```

Or maybe wrapping up some standardised string manipulation:

```{r}
first_upper <- function(x) {
  str_sub(x, 1, 1) <- str_to_upper(str_sub(x, 1, 1))
  x
}

# https://twitter.com/neilgcurrie/status/1571607727255834625
mape <- function(actual, predicted) {
  sum(abs((actual - predicted) / actual)) / length(actual)
}
```

Another useful string manipulation function comes from NV Labor Analysis:

```{r}
# https://twitter.com/NVlabormarket/status/1571939851922198530

clean_number <- function(x) {
  is_pct <- str_detect(x, "%")
  num <- num |> 
    str_remove_all("%") |> 
    str_remove_all(x, ",") |> 
    str_remove_all(x, fixed("$")) |> 
    as.numeric(num)
  if_else(is_pct, num / 100, num)
}
```

### Summary functions

In other cases you want a function that returns a single value for use in `summary()`.
Sometimes this can just be a matter of setting a default argument:

```{r}
commas <- function(x) {
  str_flatten(x, collapse = ", ")
}
```

Or some very simple computation, for example to compute the coefficient of variation, which standardises the standard deviation by dividing it by the mean:

```{r}
cv <- function(x, na.rm = FALSE) {
  sd(x, na.rm = na.rm) / mean(x, na.rm = na.rm)
}
```

Or maybe you just want to give a common pattern a name that's easier to remember:

```{r}
# https://twitter.com/gbganalyst/status/1571619641390252033
n_missing <- function(x) {
  sum(is.na(x))
} 
```

### Exercises

1.  Why is `TRUE` not a parameter to `rescale01()`?
    What would happen if `x` contained a single missing value, and `na.rm` was `FALSE`?

2.  In the second variant of `rescale01()`, infinite values are left unchanged.
    Can you rewrite `rescale01()` so that `-Inf` is mapped to 0, and `Inf` is mapped to 1?

3.  Practice turning the following code snippets into functions.
    Think about what each function does.
    What would you call it?
    How many arguments does it need?
    Can you rewrite it to be more expressive or less duplicative?

    ```{r}
    #| eval: false

    mean(is.na(x))

    x / sum(x, na.rm = TRUE)

    ```

4.  Write your own functions to compute the variance and skewness of a numeric vector.
    Variance is defined as $$
    \mathrm{Var}(x) = \frac{1}{n - 1} \sum_{i=1}^n (x_i - \bar{x}) ^2 \text{,}
    $$ where $\bar{x} = (\sum_i^n x_i) / n$ is the sample mean.
    Skewness is defined as $$
    \mathrm{Skew}(x) = \frac{\frac{1}{n-2}\left(\sum_{i=1}^n(x_i - \bar x)^3\right)}{\mathrm{Var}(x)^{3/2}} \text{.}
    $$

5.  Write `both_na()`, a function that takes two vectors of the same length and returns the number of positions that have an `NA` in both vectors.

6.  What do the following functions do?
    Why are they useful even though they are so short?

    ```{r}
    is_directory <- function(x) file.info(x)$isdir
    is_readable <- function(x) file.access(x, 4) == 0
    ```

7.  Read the [complete lyrics](https://en.wikipedia.org/wiki/Little_Bunny_Foo_Foo) to "Little Bunny Foo Foo".
    There's a lot of duplication in this song.
    Extend the initial piping example to recreate the complete song, and use functions to reduce the duplication.

## Data frame functions

Tidy evaluation is hard to notice because it's the air that you breathe in this book.
Writing funtions with it is hard, because you have to explicitly think about things that you haven't had to before.
Things that the tidyverse has been designed to help you avoid thinking about so that you can focus on your analysis.

### Introduction to tidy evaluation

The second common form of function takes a data frame as the first argument, some extra arguments that say what to do with it, and returns a data frame.

```{r}
mutate_y <- function(data) {
  mutate(data, y = a + x)
}
```

These sorts of functions often wrap up other tidyverse functions, and so inevitably encounter the challenge of what's called tidy evaluation.
Let's illustrate the problem with a function so simple that you'd never both writing it yourself:

```{r}
my_select <- function(df, var) {
  df |> 
    select(var)
}
```

What's going to happen if I run the following code?

```{r}
df <- tibble(var = 1, rav = 2)
df |> my_select(rav)
```

The problem is one of ambiguity.
Inside the function, should `var` refer directly to the literal variable called `var` inside the data frame you've passed in, or should it refer to the code you've supplied in the `var` argument.
dplyr prefers directs of indirect so we get an undesirably response.
To resolve this problem, we need a tool: `{{ }}`, called embracing:

```{r}
my_select <- function(df, var) {
  df |> 
    select({{ var }})
}
df |> my_select(rav)
```

This tells dplyr you want to select not `var` directly, but use the contents of `var` that the user has provided.
One way to remember what's happening is to think of `{{ }}` like looking down a tunnel --- it's going to look inside of `var`.

There's much more to learn about tidy evaluation , but this should be enough to get you started writing functions.

### Which arguments need embracing?

Not ever argument needs to be embraced --- only those arguments that are evaluated in the context of the data.
These fail into two main groups:

-   Arguments that select variables, like `select()`, `relocate()`, and `rename()`.
    The technical name for these arguments is "tidy-select" arguments, and if you look at the documentation you'll see these arguments thus labelled.

-   Arguments that compute with variables: `arrange()`, `filter()`, and `summarise()`.
    The technical name for these argument is "data-masking"

It's usually easier to tell which is which, but there are some that are harder because you usually supply just a single variable name.

-   All the arguments to `aes()` is are computing arguments because you can write `aes(x  * 2, y / 10)` etc
-   The arguments to `group_by()`, `count()`, and `distinct()` are computing arguments because they can all create new variables.
-   The `names_from` arguments to `pivot_wider()` is a selecting function because you can take the names from multiple variables with `names_from = c(x, y, z)`.

### Selection arguments

In @sec-across you'll learn more about `across()` which is a really powerful selecting function that you can use inside of computing arguments.

### Computing arguments

```{r}
my_summarise2 <- function(data, expr) {
  data %>% summarise(
    mean = mean({{ expr }}),
    sum = sum({{ expr }}),
    n = n()
  )
}
```

A common use case is to modify `count()`, for example to compute percents:

```{r}
# https://twitter.com/Diabb6/status/1571635146658402309
count_pct <- function(df, var) {
  df |>
    count({{ var }}, sort = TRUE) |>
    mutate(pct = n / sum(n))
}

mtcars |> count_pct(cyl)
```

Or to pivot the output:

```{r}
#| eval: false

# Inspired by https://twitter.com/pollicipes/status/1571606508944719876
count_wide <- function(data, rows, cols) {
  data |> 
    count(pick(c({{rows}}, {{cols}}))) |> 
    pivot_wider(names_from = {{cols}}, values_from = n)
}
mtcars |> count_wide(vs, cyl)
mtcars |> count_wide(c(vs, am), cyl)
```

This requires use `pick()` to use tidy-select inside a data-masking (`count()`) function.

```{r}
# https://twitter.com/JustinTPriest/status/1571614088329048064
# https://twitter.com/FBpsy/status/1571909992139362304
# https://twitter.com/ekholm_e/status/1571900197894078465

enrich_join <- function(x, y, ..., by = NULL) { 
 left_join(x, y %>% select(...), by = by)
}
```

## Style

It's important to remember that functions are not just for the computer, but are also for humans.
R doesn't care what your function is called, or what comments it contains, but these are important for human readers.
This section discusses some things that you should bear in mind when writing functions that humans can understand.

Excerpt from <https://style.tidyverse.org/functions.html>

### Names

The name of a function is important.
Ideally, the name of your function will be short, but clearly evoke what the function does.
That's hard!
But it's better to be clear than short, as RStudio's autocomplete makes it easy to type long names.

Generally, function names should be verbs, and arguments should be nouns.
There are some exceptions: nouns are ok if the function computes a very well known noun (i.e. `mean()` is better than `compute_mean()`), or accessing some property of an object (i.e. `coef()` is better than `get_coefficients()`).
A good sign that a noun might be a better choice is if you're using a very broad verb like "get", "compute", "calculate", or "determine".
Use your best judgement and don't be afraid to rename a function if you figure out a better name later.

```{r}
#| eval: false

# Too short
f()

# Not a verb, or descriptive
my_awesome_function()

# Long, but clear
impute_missing()
collapse_years()
```

### Indenting

Both `if` and `function` should (almost) always be followed by squiggly brackets (`{}`), and the contents should be indented by two spaces.
This makes it easier to see the hierarchy in your code by skimming the left-hand margin.

An opening curly brace should never go on its own line and should always be followed by a new line.
A closing curly brace should always go on its own line, unless it's followed by `else`.
Always indent the code inside curly braces.

```{r}
#| eval: false

# Good
if (y < 0 && debug) {
  message("Y is negative")
}

if (y == 0) {
  log(x)
} else {
  y ^ x
}

# Bad
if (y < 0 && debug)
message("Y is negative")

if (y == 0) {
  log(x)
} 
else {
  y ^ x
}
```

### Exercises

1.  What's the difference between `if` and `ifelse()`?
    Carefully read the help and construct three examples that illustrate the key differences.

2.  Write a greeting function that says "good morning", "good afternoon", or "good evening", depending on the time of day.
    (Hint: use a time argument that defaults to `lubridate::now()`.
    That will make it easier to test your function.)

3.  Implement a `fizzbuzz` function.
    It takes a single number as input.
    If the number is divisible by three, it returns "fizz".
    If it's divisible by five it returns "buzz".
    If it's divisible by three and five, it returns "fizzbuzz".
    Otherwise, it returns the number itself.
    Make sure you first write working code before you create the function.

4.  How could you use `cut()` to simplify this set of nested if-else statements?

    ```{r}
    #| eval: false

    if (temp <= 0) {
      "freezing"
    } else if (temp <= 10) {
      "cold"
    } else if (temp <= 20) {
      "cool"
    } else if (temp <= 30) {
      "warm"
    } else {
      "hot"
    }
    ```

    How would you change the call to `cut()` if we used `<` instead of `<=`?
    What is the other chief advantage of `cut()` for this problem?
    (Hint: what happens if you have many values in `temp`?)

5.  What happens if you use `switch()` with numeric values?

6.  What does this `switch()` call do?
    What happens if `x` is "e"?

    ```{r}
    #| eval: false

    switch(x, 
      a = ,
      b = "ab",
      c = ,
      d = "cd"
    )
    ```

    Experiment, then carefully read the documentation.

### Exercises

1.  Read the source code for each of the following three functions, puzzle out what they do, and then brainstorm better names.

    ```{r}
    f1 <- function(string, prefix) {
      substr(string, 1, nchar(prefix)) == prefix
    }
    f2 <- function(x) {
      if (length(x) <= 1) return(NULL)
      x[-length(x)]
    }
    f3 <- function(x, y) {
      rep(y, length.out = length(x))
    }
    ```

2.  Take a function that you've written recently and spend 5 minutes brainstorming a better name for it and its arguments.

3.  Compare and contrast `rnorm()` and `MASS::mvrnorm()`.
    How could you make them more consistent?

4.  Make a case for why `norm_r()`, `norm_d()` etc would be better than `rnorm()`, `dnorm()`.
    Make a case for the opposite.

## Learning more

### Conditional execution {#sec-conditional-execution}

An `if` statement allows you to conditionally execute code.
It looks like this:

```{r}
#| eval: false

if (condition) {
  # code executed when condition is TRUE
} else {
  # code executed when condition is FALSE
}
```

To get help on `if` you need to surround it in backticks: `` ?`if` ``.
The help isn't particularly helpful if you're not already an experienced programmer, but at least you know how to get to it!

Here's a simple function that uses an `if` statement.
The goal of this function is to return a logical vector describing whether or not each element of a vector is named.

```{r}
has_name <- function(x) {
  nms <- names(x)
  if (is.null(nms)) {
    rep(FALSE, length(x))
  } else {
    !is.na(nms) & nms != ""
  }
}
```

You can use `||` (or) and `&&` (and) to combine multiple logical expressions.
These operators are "short-circuiting": as soon as `||` sees the first `TRUE` it returns `TRUE` without computing anything else.
As soon as `&&` sees the first `FALSE` it returns `FALSE`.

This function takes advantage of the standard return rule: a function returns the last value that it computed.
Here that is either one of the two branches of the `if` statement.

The `condition` must evaluate to either `TRUE` or `FALSE`.
If it's not; you'll get an error.

```{r}
#| error: true

if (c(TRUE, FALSE)) {}

if (NA) {}
```

You should never use `|` or `&` in an `if` statement: these are vectorised operations that apply to multiple values (that's why you use them in `filter()`).
If you do have a logical vector, you can use `any()` or `all()` to collapse it to a single value.
Be careful when testing for equality.
`==` is vectorised, which means that it's easy to get more than one output.
Either check the length is already 1, collapse with `all()` or `any()`.

You can chain multiple if statements together:

```{r}
#| eval: false

if (this) {
  # do that
} else if (that) {
  # do something else
} else {
  # 
}
```

###