intro.Rmd

---
title: 'Introduction to R Functions'
subtitle: 'R Ladies Chicago and R Ladies East Lansing'
author: 'Stephanie Kirmer <br> <a href="http://github.com/skirmer">`r icon::fontawesome(name="github")` skirmer</a><br> <a href="http://twitter.com/data_stephanie"> `r icon::fontawesome(name="twitter")` @data_stephanie</a><br> <a href="http://www.stephaniekirmer.com"> `r icon::fontawesome(name="link")` stephaniekirmer.com</a>'
date: 'February 26, 2021'
output:
  xaringan::moon_reader:
    css: ['xaringan-themer.css', 'extracss.css'] 
    nature:
      highlightLines: true
    includes:
      in_header: header.html  
---
layout: true
.footer[<a href="https://github.com/skirmer/functions_r">`r icon::fontawesome(name="github")` github.com/skirmer/functions_r </a> | <a href="http://twitter.com/data_stephanie">`r icon::fontawesome(name="twitter")` @data_stephanie</a>]

---
```{r xaringan-themer, include=FALSE, warning=FALSE}
library(xaringanthemer)
library(countdown)
library(icon)

style_duo_accent(
  primary_color = "#23395b",
  secondary_color = "#136f63",
  header_font_google = google_font("Fira Sans"),
  text_font_google   = google_font("Droid Serif"),
  code_font_google   = google_font("Fira Mono")
)
```



# Overview

-   Lecture alternating with breakouts for hands-on examples   
--

-   Repo: https://github.com/skirmer/functions_r   
--

-   Support Team for questions/leading breakouts   
--

<img src="https://media.giphy.com/media/l46Cbqvg6gxGvh2PS/giphy.gif" style="width: 50%" />


???
Introductions for support team

---

## Breakout Sections
  - Work through examples in small groups
  - 5-ish minute chunks
  - Choose either Beginner or Advanced group
    - Beginners will read provided function, and gradually edit it
    - Advanced will write your own function, and fully develop it
    
    
<img src="https://media.giphy.com/media/3jN3GziOKUEmI/giphy.gif" style="width: 30%" />


???
If you have your own code, or some idea for a function, you can work with Advanced group to develop it into a full function   
If you don't have your own code or don't want to write it all yourself, work with Beginner   
You can change groups later!   

---
# What is a Function Anyway?

![](function_diagram.png)

???
You have one thing, and you want to have another thing, so the function is your path to get there.

---
# Why Functions?

-   Avoid repetition
-   Share code with others
-   Eventually build packages

<img src="https://media.giphy.com/media/20BoPFWiCG3K9GYABQ/giphy.gif" style="width: 40%" />


???
Those operations you want to run in order to get from what you have to what you need are useful to others!   
This framework is common to many programming languages

---
# Basic Structure

```{r, echo=TRUE, eval=FALSE}

myFunction <- function(){
  ...
  return()
}

myFunction()
```

???
This shell is what lets R know that you intend to create a function.   
Now we need to add in the contents.

---
# Basic Structure

```{r, echo=TRUE, eval=FALSE}

myFunction <- function(ARGUMENTS){
  {{...}}
  return(OUTPUT)
}

myFunction(ARGUMENTS)
```

---
# Basic Structure

```{r, echo=TRUE, eval=FALSE}

myFunction <- function(a, b){
  {{c <- a*b}}
  return(c)
}

myFunction(a = 2,b = 4)
```


---
class: inverse

# Practice Break 1
Open possible_dog_part1.R and follow the instructions.

- Beginner: Read the sample function, and interpret what it does.
  - Discuss the structure. Think about what might make it better or easier to use. 
- Advanced: Take a bit of your own code and place it in a function structure. Change function name to something appropriate.

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

---
# Types
- Logical or Boolean (TRUE, FALSE, 0, 1)
- Integer (Numeric) (3, 7, 108)
- Double or Float (Numeric) (1.6645, 3.14159, 987.99)
- Character or String ("Hello", "a")
- Closure (function) (`sum()`)

More info in help: `?type` or `?mode`

Plus: list, complex, special, etc

<img src="https://media.giphy.com/media/ouE6OPO1MADM4/giphy.gif" style="width: 40%" />



???
Before we deep dive into these pieces, we have to make sure we understand types just a little.   
While we aren't going to go deep in today, your arguments can be things like lists and dataframes as well as single items - you can get creative!

---
# Arguments, or What Goes In

- Order and naming are important
- Defaults can be set, not required

```{r, echo=TRUE, eval=FALSE}

{{myFunction <- function(a=1, b=1){}}
  ...
myFunction(a = 2,b = 4)
```

<img src="https://media.giphy.com/media/XhAQgt6ytc6E8/giphy.gif" style="width: 40%" />


???
You can set default values for the arguments as shown   
Your arguments need to observe a specific type usually (best practices)

---
class: inverse

# Practice Break 2
Open possible_dog_part2.R and follow the instructions.

- Beginner: Identify the changes in the example function. Try running it, and change the arguments. 
  - Discuss what change you made and what the effects were. What type/s can the function accept? What happens if you pass something else?
- Advanced: Add an argument to your function, and make it change the output. 

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

???
If you weren't comfortable or were not challenged in the group you picked last time, you can switch!
---

# Returns, or What Comes Out

- Object (single) that you'll be able to use elsewhere
- May be any of the types we previously discussed
- Not required! Functions can do things besides return

```{r, echo=TRUE, eval=FALSE}
myFunction <- function(a, b){
...
  {{return(c)}}
}
```

<img src="https://media.giphy.com/media/ZaoNH308FHz7a/giphy.gif" style="width: 40%" />


???
Key - make sure the user of this function gets something they are reasonably expecting   
A function could change the state of an existing object without using a return (global env, will discuss)   
Single object return only in R

---
class: inverse

# Practice Break 3
Open possible_dog_part3.R and follow the instructions.

- Beginner: Identify the changes in the example function. What is it returning?
  - Try changing the return, see what it does.
- Advanced: Add a two-element return to your function. Remember that R does not allow multi-argument returns.

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

---

# Guardrails: Documentation

- Explain what the arguments and returns are
- Demonstrate how the function is meant to be used
- May include `@description` or other additional items 

```{r, echo=TRUE, eval=FALSE}
#' Explain what my function does
#'
#' @param a Type. Description of what it represents.
#' @param b Type. Description of what it represents.
#'
#' @return Type. Description of what it represents.
#'
#' @examples
#' \dontrun{myFunction(a = 5, b = 3)}
```

<img src="https://media.giphy.com/media/lkdpUMrVSG9D9xiFt0/giphy.gif" style="width: 25%" />


???
Be clear, but not too wordy   
Tell the user what they need to know in order to use the function and understand

---
class: inverse

# Practice Break 4
Open possible_dog_part4.R and follow the instructions.

- Beginner: Fill in the blanks in the provided function documentation.
- Advanced: Add documentation for your function, including arguments and returns.

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

---
# Guardrails: Type Check

- Setting an informative error helps the user
- Checks can look at be more than just type

```{r, echo=TRUE, eval=FALSE}

myFunction <- function(a, b){
  {{if(!is.double(a)) stop("a must be a number")}}
  c <- a*b
  return(c)
}

myFunction(a = 2,b = 4)
#myFunction(a = TRUE, b = 4)
```



<img src="https://media.giphy.com/media/zCpYQh5YVhdI1rVYpE/giphy.gif" style="width: 25%" />


???
User might be future you! 

---

class: inverse

# Practice Break 5
Open possible_dog_part5.R and follow the instructions.

- Beginner: Examine the type check included in the function. Pass arguments to the function that will violate it.
  - Is the error informative? 
- Advanced: Add a type check to your function's arguments. Make sure the error message is clear.

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

---

# Guardrails: Tests

- Vital for making packages later
- Helps you ensure that changes have not broken expected behavior

```{r, echo=TRUE, eval=TRUE}

library(testthat)
myFunction <- function(a, b){
  if(!is.numeric(a)) stop("a must be a number")
  c <- a*b
  return(c)
}
```


```{r, echo=TRUE, eval=TRUE}
test_that("Function returns correct value",
          {
            product = myFunction(a = 2,b = 4)#<<
            expect_equal(product, 8)#<<
          })
```

???
If the return is not in line with expectations, you can easily find out. 

---
# Guardrails: Tests

```{r, echo=TRUE, eval=TRUE}

library(testthat)

test_that("Function returns expected error",
          {
           {{ expect_error(myFunction(a = TRUE, b = 4))}}
          })
```


<img src="https://media.giphy.com/media/LycfkVG4L6x0Y/giphy.gif" style="width: 50%" />

???

Tests can check that it fails or errors when it's supposed to as well!

---

class: inverse

# Practice Break 6
Open possible_dog_part6.R and follow the instructions.

- Beginner: Fill in the argument value that will make the test pass, or change the test.
  - Discuss whether it is more sensible to change the argument or the test. 
- Advanced: Write a test for your function.
  - Do you want to test for expected error or for expected return?

```{r, echo=FALSE}
countdown(minutes = 5, seconds = 0, left=0)
```

---


# Environments

The function knows what exists inside itself, and what exists in the "global" environment.
Outside the function only knows what exists in the "global".
Here, a, b, and c do not exist in the world outside our function.

```{r, echo=TRUE, eval=FALSE}

print(environment())
print(objects())
myFunction <- function(a, b){
  {{c <- a*b}}
  print(environment())
  print(objects())
  return(c)
}

myFunction(a = 2,b = 4)
```
---
# Global Environment

- No a, b, or c

```{r, echo=TRUE, eval=TRUE}

print(environment())
print(objects())

```

---
# Function Environment

- Here they are!

```{r, echo=TRUE, eval=TRUE}

myFunction <- function(a, b){
  {{c <- a*b}}
  print(environment())
  print(objects())
  return(c)
}

myFunction(a = 2,b = 4)
```
---
# Mixing Environments

```{r, echo=TRUE, eval=TRUE}
myFunction <- function(a, b){
  {{d <<- a*b}}
  print(environment())
  print(objects())
  return(d)
}
myFunction(a = 2,b = 4)
print(environment())
print(objects())

```

???
Watch out how you use the double arrow!

---
# Exploring a Function

- Just omit the parentheses
```{r, echo=TRUE, eval=TRUE}
dplyr::top_n
```

---
# Combining Functions
- A function can be an argument to another function
- This way you can chain together elements powerfully
- Helps readability to use functions!

```{r, echo=TRUE, eval=TRUE}

a <- sum(1, 5, 3)
b <- max(a, 4)
b

c <- max(sum(1, 5, 3), 4)
c
```


---
# Conclusion

- Functions are a way of packaging small sections of code to reuse later
- Functions accept input and return output, and contain code
- Documentation and internal tests make functions more useful and easier to work with

<img src="https://media.giphy.com/media/f7rDDvcOV9n8I/giphy.gif" style="width: 50%" />

`r icon::fontawesome("link")` [www.stephaniekirmer.com](http://www.stephaniekirmer.com)  |  `r icon::fontawesome("twitter")` @[data_stephanie](http://www.twitter.com/data_stephanie)


---
# Further Reading
* http://adv-r.had.co.nz/Functions.html
* https://r4ds.had.co.nz/functions.html
* https://nicercode.github.io/guides/functions/
* https://cran.r-project.org/doc/manuals/r-release/R-intro.html#Writing-your-own-functions
* https://r-pkgs.org/man.html