400_functions.Rmd

<!-- 
This file by Martin Monkman 
is licensed under a Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/  
-->

# (PART) Week 4 {-} 



# Write your own functions {#functions}



## Objectives

* Understand and describe when and why a function is of value

* Understand the components of a function


![_`function()` function, what's your function?_](static/img/shr_function.jpg)



## Setup

This chunk of R code loads the packages that we will be using.


```{r eval = FALSE}
library(tidyverse)
```


## Introduction to functions

Functions are an important part of programming in R. You have already used many functions—now it's time to write your own.

Functions have particular value in making your code DRY (don't repeat yourself).^[The opposite is WET (we enjoy typing).] If you need to do the same thing over and over again, whether in a single script or to create the a report with the same calculations when next month's data arrives, you can either copy-and-paste with some find-and-replace, or take the time to write a generalized function. 

Using functions has the following benefits: 

* there's fewer opportunities for error (say you miss a replacement)

* your code will be better organized and easier to read


There are three parts to any function:

* function name  

* inputs, which are called "arguments"  

* code statement(s) that do something with/to the argument(s)  

In R, the function to create a function is `function()`.


The code looks like this:

```
my.function.name <- function(my_argument_1, my_argument_2, ...) {
  code_statement
}
```

## A basic example

(from ["Writing your own Functions" in _Hands-on Programming with R_](https://rstudio-education.github.io/hopr/basics.html#write-functions), by Garrett Grolemund)


Let's say you want to simulate rolling 2 six-sided dice. Here's some code that does that:

```{r}

# define the possible outcomes
die <- 1:6

# a random pair of numbers from the `die` object
dice <- sample(die, size = 2, replace = TRUE)

# then add them up
sum(dice)

```


To do this more than once, you would need to write the last two lines of code in again and again:

```{r}

dice <- sample(die, size = 2, replace = TRUE)
sum(dice)

dice <- sample(die, size = 2, replace = TRUE)
sum(dice)

dice <- sample(die, size = 2, replace = TRUE)
sum(dice)

```


_Or_ you could write a function.

In this case, our _code_statement_ is the three lines of code:


```{r}

roll <- function() {
  die <- 1:6
  dice <- sample(die, size = 2, replace = TRUE)
  sum(dice)
}

```


Note that when we run this chunk, the function gets stored in our environment, and appears under Functions.

To run the function we just need the following:

```{r}

roll()

# and if we want to assign the result of the function to an object:
my_roll <- roll()

```


And then if we want to get the distribution of values from rolling a pair of dice 100 times, we can use the `replicate()` function:

```{r}

replicate(100, roll())

```



## Another example

Let's write an equation that converts 50 pounds to the equivalent in kilograms.

1 kilogram (kg) is equal to 2.2046226218488 pounds (lb) (and conversely, 1 pound is equal to 0.45359237 kilograms).

$$ 1 kg = 2.2046226218488 lb $$

When we translate that formula into code that will convert the number of pounds into kilograms, it looks like this, where `kg` is "kilograms" and `lb` is "pounds":

```{r}
lb <- 50

kg <- lb / 2.2046226218488

kg

```

But what if we want to convert the weight of many items of different size? Time for a function.

We call the function with `lb_to_kg_conversion()`, and pass the value of pounds `lb`. The function returns the value of `kg` after calculating the value.

```{r}

lb_to_kg_conversion <- function(lb) {
  kg <- lb / 2.2046226218488
  return(kg)
}

```


Let's test it with our weight of 50 pounds:

```{r}

lb_to_kg_conversion(lb = 50)

```


Now we can use that function to convert any number of weights. Let's make a tibble with 10 weights, where `weight_lb` is each weight in pounds.

```{r}
# the `set.seed()` function ensures that our pseudo-random number generation
# always returns the same values
set.seed(1)

my_weights <- tibble(
  weight_name = letters[1:10],    # the letters from a to j
  weight_lb = round(runif(n=10, min=1, max=20), 3)
    )      # a random sequence of numbers between 1 and 20

my_weights

```

What is the weight of those items in kilograms? I can apply my function...

```{r}

my_weights |>
  mutate(weight_kg = lb_to_kg_conversion(lb = weight_lb))

```

That's good. But what if we want our result to be rounded to 2 decimal places?

We could rewrite our function to add that additional line of code:

* note that in the 2nd line of the function's code, we are rounding `kg` before returning it.


```{r}

lb_to_kg_conversion <- function(lb) {
  kg <- lb / 2.2046226218488
  kg <- round(kg, 2)
  return(kg)
}

```

Now re-run the `mutate()`:


```{r}

my_weights |>
  mutate(weight_kg = lb_to_kg_conversion(lb = weight_lb))

```


What if we want want to have some flexibility in our rounding? We can add a second argument to our function call—`rnd`—which will be then applied in `round()`


```{r}

lb_to_kg_conversion <- function(lb, rnd) {
  kg <- lb / 2.2046226218488
  kg <- round(kg, rnd)
  return(kg)
}

```


And rerun with the area to 3 decimals:

```{r}

my_weights |>
  mutate(weight_kg = lb_to_kg_conversion(lb = weight_lb, rnd = 3))

```



### Setting default values

What if we usually want to round to 2, but want to have some flexibility? We can assign the default value of 2 to the rounding argument. If `rnd` doesn't get specified, it will be 2...but we can over-ride that with a specific value assignment.

```{r}

lb_to_kg_conversion <- function(lb, rnd = 2) {
  kg <- lb * 2.2046226218488
  kg <- round(kg, rnd)
  return(kg)
}

```


With no specification:

* note that we don't have to be explicit in telling the function how to use the variable `weight_lb`—it assumes that since it is the first argument passed, it is `lb`. And because we don't pass a second argument, the function will use the default value we've specified, in this case "2".

```{r}

my_weights |>
  mutate(weight_kg = lb_to_kg_conversion(weight_lb))

```


Or override with rounding to 3 decimals:


```{r}

my_weights |>
  mutate(weight_kg = lb_to_kg_conversion(weight_lb, 3))

```



## Exercises


::: {.rmdtip}
### Temperature

Write a function that converts temperature from degrees Celsius (C) to Fahrenheit (F), using the formula 

$$\ F = (C * 9/5) + 32 $$

Now, write and test a function to calculate the temperature in Fahrenheit, where it is automatically rounded to 1 decimal place. 


<details>

<summary>
Solution
</summary>


The function for conversion from pounds to kilograms is pasted below:


```{r}

# example
lb_to_kg_conversion <- function(lb, rnd = 1) {
  kg <- lb / 2.2046226218488
  kg <- round(kg, rnd)
  return(kg)
}

```

Now let's edit the code above, but to work with the formula for temperature:

```{r}

# solution
Cel_to_Fah_conversion <- function(Cel, rnd = 2) {
  Fah <- (Cel * 9/5) + 32
  Fah <- round(Fah, rnd)
  return(Fah)
}

```


Now, generate a tibble with the name `my_temperatures`:

```{r}

set.seed(42)

my_temperatures <- tibble(
  temp_name = letters[1:10], 
  temp_Cel = round(runif(10, min = 1, max = 20), 2))

my_temperatures

```

And use the function to convert each temperature to Fahrenheit in the tibble:


```{r}

my_temperatures |> 
  mutate(temp_Fah = Cel_to_Fah_conversion(temp_Cel))

```


Now round to the nearest integer (zero decimals).

```{r}

my_temperatures |> 
  mutate(temp_Fah = Cel_to_Fah_conversion(temp_Cel, rnd = 0))

```

</details>
:::


::: {.rmdtip}

### Multiple dice rolls



The dice rolling function we wrote above assumes we are always rolling 2 dice. Modify the function so that the default is 2, but that the number of dice can be varied. 


<details>

<summary>
Solution
</summary>

In this solution, an argument `number_of_dice` is added to the `function()`, and specified as "2". Then within the `sample()` function, the `size = ` is specified as `number_of_dice`.

```{r}

roll2 <- function(number_of_dice = 2) {
  die <- 1:6
  dice <- sample(die, size = number_of_dice, replace = TRUE)
  sum(dice)
}
 
```

Testing our function, first relying on the default of 2:

```{r}

roll2()

```


Then specifying 3 dice:

```{r}

roll2(number_of_dice = 3)

```




</details>
:::


## Readings and reference

["Functions" in _R for Data Science_, 2nd ed.](https://r4ds.hadley.nz/functions) by Hadley Wickham, Mine Çetinkaya-Rundel, and Garrett Grolemund

["Writing your own Functions" in _Hands-on Programming with R_](https://rstudio-education.github.io/hopr/basics.html#write-functions), by Garrett Grolemund


["Functions", from _Introduction to the R Language_](https://www.stat.berkeley.edu/~statcur/Workshop2/Presentations/functions.pdf), Berkley, Biostatistics 140.776


["Creating Functions", from _Programming with R_](https://swcarpentry.github.io/r-novice-inflammation/02-func-R/), Software Carpentry


["Writing simple functions"](http://environmentalcomputing.net/writing-simple-functions/) at Environmental Computing


["Mathematics in R Markdown"](https://rpruim.github.io/s341/S19/from-class/MathinRmd.html) by R Pruim (2016-10-19)



-30-