STM1001 Lecture 6

class: middle
background-image: url(data:image/png;base64,#LTU_logo.jpg)
background-position: top left
background-size: 30%

# STM1001 Lecture 
# Writing Functions in R
## Data Science stream
### La Trobe University

---

# Welcome!

### In this lecture we cover an introduction to writing functions in R.

* By the end of this lecture you will:

* understand the syntax and structure required to write your own custom functions in R
  
--

* be able to troubleshoot common errors that can arise when writing new functions in R
  
--

* be able to distinguish between poorly written and well written custom functions in R

*Reminder: We will use the RStudio interface to carry out R coding for all our STM1001 Data Science-stream work.*

---

# Overview

Over the following slides, we will cover:

* What are R functions and why do we use them?

* The fundamental structure of R functions

* Examples of well written and poorly written R functions

* Collaborative Coding

---

# 1. What are R functions and why do we use them?

By now, you should be familiar with the basics of R coding.

Having completed the previous weeks of STM1001 Core and Data Science-stream computer labs, you will have used several base R functions, as well as functions from various additional packages.

In simple terms, an R function is a selection of code that contains a specific set of coded instructions to produce specific output(s) based on one or more inputs.

Functions play a vital role in R coding and are fundamental to most (if not all) data analyses.

Our focus now is to build upon your informal knowledge of functions, and develop a strong understanding of what R functions are, and how they work.

---

class:middle

# A visual example of a simple function

* A function receives inputs aka arguments (e.g. .water_style[water] and .seed_style[seeds] here), and produces one or more outputs (e.g. .wheat_style[wheat] here), based on the details in the body of the function.
---

class:middle

"*The most important thing to understand about R is that functions are objects in their own right. You can work with them exactly the same way you work with any other type of object.*" (Wickham, 2019)

---

# A visual example of a complex function

* Functions can themselves be used in other functions, and sometimes you may need to have nested functions, to obtain your final desired output(s).

* Here, the initial 'simple' function produces .wheat_style[wheat], which through another function process is used to produce flour, and this in turn is used as an input to produce our final desired output, a .donut_style[donut]!
---

# 2. R function structure

R functions consist of three components (Wickham, 2019): `$^\star$`

* `body()`: The code inside the function

* `formals()`: The list of arguments which together control how you use the function

* `environment`: The layout of the location of the variables in the function

In STM1001, we focus predominantly on the `body` and `formals` components.

`$^\star$` *Primitive functions from the `base` R package - like `sum()` - are an exception to this, but not relevant here.*

---

# 2. R function structure

If we print a function (i.e. run the name of the function, without any arguments specified), R will return these three components.

#### .teal_style[Code Provided]

``` r
example_function <- function(x, y){
 x^3 + y
}
example_function
```

#### .teal_style[R Output]

```
## function(x, y){
##   x^3 + y
## }
```

*Note that if we don't see the environment listed, this means the function was created in the global environment, which will often be the case*.

---

# 2. R function structure

We can also manually check the components:

``` r
formals(example_function)
```

```
## $x
## 
## 
## $y
```

``` r
body(example_function)
```

```
## {
##     x^3 + y
## }
```

---

# 2. R function structure

Let's take a closer look at the composition of this function.

``` r
example_function <- function(x, y){
 x^3 + y
}
```

* The function has a user-specified name, `example_function`

* We use the R function `function` to (as expected) create a function

* The `formals` (all the arguments/inputs used for the function) are specified inside the open brackets `()` following `function`

* To begin the `body` of our function, we use a left curly brace, `{`, directly after the right open bracket `)` closing off our list of arguments

* Inside the `body` section, we specify the calculation(s) the function should perform - here it is simply `x^3 + y`

* We close off our function by using a right curly brace `}`

---

# 3. Examples of custom functions

R functions can be as simple

or as complex as you like:

*Note these are all comments, the actual code for the body of the function isn't shown*

---

# Suggestions

Remember, your code may need to be read and used by other people.

#### .teal_style[General]

* Use clear, meaningful names for your functions

* Compare e.g. `Cohens_d_effect_size` to `cdes_final_v3`
  
--

* Add comments to provide further information in the body of the function

* Remember to load all required packages

* Don't make a function unnecessarily complicated - consider if you can split your code into separate functions, in a logical way

---

# Suggestions

#### .teal_style[More Advanced]

* You can also add a comments section at the start of the body of the function, detailing:

* The purpose of the function

* What the different inputs are/should be
  
--

* What the variables used in the function represent
  
--

* If other functions are used inside your function

* Add safety checks with e.g. `require()`, `stop()` and `warning()` to ensure inputs and results are as expected, e.g.:

* `if (x >= 10) {warning("check input, x should be less than 10")}`

---

# 4. Writing our own functions

Now that we have a stronger understanding of what R functions are, and how they work, let's write our own functions together.

For this section of the lecture, we can collaborate to write some R functions together, and explore options, troubleshoot errors, and add details as we go.

You can find the .R script files used in this part of the lecture on the LMS:

You can download these and work on them in R yourself if you would like, or simply sit back and offer comments and suggestions in the chat or via your mics as we work through the code together.

* One script is riddled with errors
  
--

* The other script outlines what is desired, but has limited code

---

# End

That concludes our introduction to writing functions in R lecture.

What to do next:

* Please attend/complete Computer Lab 6B, in which we will practice writing R functions and further develop our R coding skills.

* If you have any questions, we can resolve them in the computer labs.

---

background-image: url(data:image/png;base64,#computerlab.jpg)
background-position: bottom
background-size: 75%
class: center

# See you in the computer labs!

---

# References

* Wickham, H. (2019). Advanced R (2nd ed.). Chapman & Hall/CRC.

* Images used in visual function examples by <a href="https://pixabay.com/users/pawe_d_browski-20233758/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=8102955">Paweł Dąbrowski</a> from <a href="https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=8102955">Pixabay</a>

---
class: middle

These notes have been prepared by Rupert Kuveke. The copyright for the material in these notes resides with the authors named above, with the Department of Mathematical and Physical Sciences and with La Trobe University. Copyright in this work is vested in La Trobe University including all La Trobe University branding and naming. Unless otherwise stated, material within this work is licensed under a Creative Commons Attribution-Non Commercial-Non Derivatives License 
<a href = "https://creativecommons.org/licenses/by-nc-nd/4.0/" target="_blank"> BY-NC-ND. </a>