```{r}
#| label: setup
#| include: false

library(webexercises)
```

## Why R?

R can be used to **analyse all sorts of data**, from tabular data (also known as "spreadsheets"), textual data, geographic data and even images.

![](../img/what-r-for.png)

This course will focus on the analysis of tabular data, since all of the techniques relevant to this type of data also apply to the other types.

![](../img/inclusive-community.png)

The R community is a **very inclusive community** and it's easy to find help. There are several groups that promote R in minority/minoritised groups, like [R-Ladies](https://www.r-consortium.org/all-projects/r-ladies), [Africa R](https://r4africa.org), and [Rainbow R](https://rainbowr.netlify.app) just to mention a few.

Moreover, R is **open source and free**!

## R vs RStudio

Beginners usually have trouble understanding the difference between R and RStudio.

Let's use a car analogy.

What makes the car go is the **engine** and you can control the engine through the **dashboard**.

You can think of R as an engine and RStudio as the dashboard.

![](../img/R_vs_RStudio_1.png)

::: {.callout-tip icon="false"}
### R

-   R is a **programming language**.

-   We use programming languages to **interact** with computers.

-   You run **commands** written in a **console** and the related task is **executed**.
:::

::: {.callout-tip icon="false"}
### RStudio

-   RStudio is an Integrated Development Environment or **IDE**.

-   It helps you using R more **efficiently**.

-   It has a **graphical user interface** or GUI.
:::

The next section will give you a tour of RStudio.

## RStudio

When you open RStudio, you can see the window is divided into 3 panels:

-   Blue (left): the **Console**.

-   Green (top-right): the **Environment tab**.

-   Purple (bottom-right): the **Files tab**.

![](/img/rstudio-1-2.png)

The **Console** is where R commands can be executed. Think of this as the interface to R.

The **Environment tab** lists the objects created with R, while in the **Files tab** you can navigate folders on your computer to get to files and open them in the file Editor.

### RStudio projects

RStudio is an IDE (see above) which allows you to work efficiently with R, all in one place.

**Note** that files and data live in folders on your computer, outside of RStudio: do not think of RStudio as an app where you can save files in.

All the files that you see in the Files tab are files on your computer and you can access them from the Finder or File Explorer as you would with any other file.

In principle, you can open RStudio and then navigate to any folder or file on your computer.

However, there is a more efficient way of working with RStudio: **RStudio Projects**.

::: callout-tip
#### RStudio Projects

An **RStudio Project** is a folder on your computer that has an `.Rproj` file.
:::

You can create as many RStudio Projects as you wish, and I recommend to create one per project (your dissertation, a research project, a course, etc...).

We will create an RStudio Project for this course (meaning, you will create a folder for the course which will be the RStudio Project). You will have to use this project/folder throughout the semester.

To create a new RStudio Project, click on the button that looks like a transparent light blue box with a plus, in the top-left corner of RStudio. A window like the one below will pop up.

![](../img/rstudio-3.png)

Click on `New Directory` then `New Project`.

![](../img/rstudio-4.png)

Now, this will create a new folder (aka directory) on your computer and will make that an RStudio Project (meaning, it will add a file with the `.Rproj` extension to the folder; the name of the file will be the name of the project/folder).

Give a name to your new project, something like the name of the course and year (e.g. `qml-2023`).

Then you need to specify where to create this new folder/Project. Click on `Browse…` and navigate to the folder you want to create the new folder/Project in.

When done, click on `Create Project`. RStudio will automatically open your new project.

![](../img/rstudio-5.png)

::: callout-warning
#### Important

When working through these tutorials, always make sure you are in the course RStudio Project you just created.

You know you are in an RStudio Project because you can see the name of the Project in the top-right corner of RStudio, next to the light blue cube icon.

If you see `Project (none)` in the top-right corner, that means your **are not** in an RStudio Project.

To make sure you are in the RStudio project, go to the project folder in File Explorer or Finder and double click on the `.Rproj` file.
:::

There are several ways of opening an RStudio Project:

-   You can go to the RStudio Project folder in Finder or File Explorer and double click on the `.Rproj` file.

-   You can click on `File > Open Project` in the RStudio menu.

-   You can click on the project name in the top-right corner of RStudio, which will bring up a list of projects. Click on the desired project to open it.

### A few important settings

Before moving on, there are a few important settings that you need to change.

![](../img/rstudio-6.png)

1.  Open the RStudio preferences (`Tools > Global options...`).

2.  Un-tick `Restore .RData into workspace at startup`.

    -   This mean that every time you start RStudio you are working with a clean Environment. Not restoring the workspace ensures that the code you write is fully reproducible.

3.  Select `Never` in `Save workspace to .RData on exit`.

    -   Since we are not restoring the workspace at startup, we don't need to save it. Remember that as long as you save the code, you will not lose any of your work! You will learn how to save code from next week.

4.  Click `OK` to confirm the changes.

::: callout-note
#### Quiz 1

```{r}
#| label: quiz-1
#| results: asis
#| echo: false

cat("**True or false?**", "\n\n")
cat("a. RStudio executes the code.", torf(FALSE), "\n\n")
cat("b. R is a programming language.", torf(TRUE), "\n\n")
cat("c. An IDE is necessary to run R.", torf(FALSE), "\n\n")
cat("d. RStudio projects are folders with an `.Rproj` file.", torf(TRUE), "\n\n")
cat("f. The project name is shown in the top-right corner of RStudio.", torf(TRUE))
```
:::

## R basics

In this part of the tutorial you will learn the very basics of R.

If you have prior experience with programming, you should find all this familiar. If not, not to worry! Make sure you understand the concept highlighted in the green boxes and practice the related skills.

For this tutorial, you will just run code directly in the R Console in RStudio, i.e. you will type code in the Console and press `ENTER` to run it.

In future tutorials, you will learn how to save your code in a script file, so that you can keep track of which code you have run and make your work reproducible.

### R as a calculator

Write this code `1 + 2` in the `Console`, then press `ENTER/RETURN` to run the code.

Fantastic! You should see that the answer of the addition has been printed in the `Console`, like this:

```         
[1] 3
```

(Never mind the `[1]` part for now).

Now, try some more operations (write each of the following in the Console and press `ENTER`). Feel free to add your own operations to the mix!

```{r}
#| label: operations
#| eval: false

67 - 13
2 * 4
268 / 43
```

You can also chain multiple operations.

```{r}
#| label: operations-2
#| eval: false

6 + 4 - 1 + 2
4 * 2 + 3 * 2
```

::: callout-note
#### Quiz 2

```{r}
#| label: quiz-2
#| results: asis
#| echo: false

cat("**Are the following pairs of operations equivalent?**", "\n\n")
cat("a. `3 * 2 / 4` = `3 * (2 / 4)`", torf(TRUE), "\n\n")
cat("b. `10 * 2 + 5 * 0.2` = `(10 * 2 + 5) * 0.2`", torf(FALSE), "\n\n")
```
:::

::: {.callout-important collapse="true"}
## Extra: Arithmetics

If you need a maths refresher, I recommend checking the following pages:

-   <https://www.mathsisfun.com/definitions/order-of-operations.html>

-   <https://www.mathsisfun.com/algebra/introduction.html>
:::

### Variables

> Forget-me-not.

Most times, we want to store a certain value so that we can use it again later.

We can achieve this by creating **variables**.

::: callout-tip
#### Variable

A **variable** holds one or more values and it's stored in the computer memory for later use.
:::

You can create a variable by using the **assignment operator** `<-`.

Let's assign the value `156` to the variable `my_num`.

```{r}
#| label: my-num

my_num <- 156
```

Now, check the list of variables in the `Environment` tab of the top-right panel of RStudio. You should see the `my_num` variable and its value there.

Now, you can just call the variable back when you need it! Write the following in the Console and press `ENTER`.

```{r}
#| label: print-my-num

my_num
```

A variable like `my_num` is also called a **numeric vector**: i.e. a vector that contains a number (hence numeric).

::: callout-tip
#### Vector

A **vector** is an R object that contains one or more values of the same type.
:::

A vector is a type of variable and a numeric vector is a type of vector. However, it's fine in most cases to use the word variable to mean vector (just note that a variable can also be something else than a vector; you will learn about other R objects from next week).

Let's now try some operations using variables.

```{r}
#| label: variables

income <- 1200
expenses <- 500
income - expenses
```

See? You can use operations with variables too!

And you can also go all the way with variables.

```{r}
#| label: variables-2

savings <- income - expenses
```

And check the value...

```{r}
#| label: variables-3

savings
```

Vectors can hold more than one item or value.

Just use the combine `c()` function to create a vector containing multiple values.

The following are all numeric vectors.

```{r}
#| label: numeric

one_i <- 6
# Vector with 2 values
two_i <- c(6, 8)
# Vector with 3 values
three_i <- c(6, 8, 42)
```

Check the list of variables in the `Environment` tab. You will see now that before the values of `two_i` and `three_i` you get the vector type `num` for numeric. (If the vector has only one value, you don't see the type in the `Enviroment` list but it is still of a specific type).

::: callout-tip
#### Numeric vector

A **numeric vector** is a vector that holds one or more numeric values.
:::

Note that the following are the same:

```{r}
#| label: numeric-2

one_i <- 6
one_i
one_ii <- c(6)
one_ii
```

Another important aspect of variables is that they are... **variable**! Meaning that once you assign a value to one variable, you can overwrite the value by assigning a new one to the same variable.

```{r}
#| label: numeric-3

my_num <- 88
my_num <- 63
my_num
```

::: callout-note
#### Quiz 3

```{r}
#| label: quiz-3
#| results: asis
#| echo: false

cat("**True or false?**", "\n\n")
cat("a. A vector is a type of variable.", torf(TRUE), "\n\n")
cat("b. Not all variables are vectors.", torf(TRUE), "\n\n")
cat("c. A numeric vector can only hold numeric values.", torf(TRUE), "\n\n")
```
:::

### Functions

> R cannot function without... functions.

::: callout-tip
#### Function

A **function** usually runs an operation on one or more specified **arguments**.
:::

A function in R has the form `function()` where:

-   `function` is the name of the function, like `sum`.
-   `()` are round parentheses, inside of which you write arguments, separated by commas.

Let's see an example:

```{r}
#| label: sum

sum(3, 5)
```

The `sum()` function sums the number listed as arguments. Above, the arguments are `3` and `5`.

And of course arguments can be vectors!

```{r}
#| label: sum-2

my_nums <- c(3, 5, 7)

sum(my_nums)
mean(my_nums)
```

::: callout-note
#### Quiz 4

```{r}
#| label: quiz-4
#| results: asis
#| echo: false

cat("**True or false?**", "\n\n")
cat("a. Functions can take other functions as arguments.", torf(TRUE), "\n\n")
cat("b. All function arguments must be specified.", torf(FALSE), "\n\n")
cat("c. All functions need at least one argument.", torf(FALSE), "\n\n")
```
:::

::: {.callout-tip collapse="true"}
#### Hint

The `Sys.Date()` function and other functions like it don't take any arguments.
:::

::: {.callout-important collapse="true"}
#### Extra: R vs Python

If you are familiar with Python, you will soon realise that R and Python, although they share many concepts and types of objects, they can differ substantially. This is because R is a **functional** programming language (based on *functions*) while Python is an **Object Oriented** programming language (based on *methods* applied on objects).

Generally speaking, functions look like `print(x)` while methods look like `x.print()`
:::

### String and logical vectors

> Not just numbers.

We have seen that variables can hold numeric vectors. But vectors are not restricted to being numeric. They can also store **strings**.

A string is basically a set of characters (a word, a sentence, a full text).

In R, strings have to be **quoted** using double quotes `" "`.

Change the following strings to your name and surname. Remember to keep the double quotes

```{r}
#| label: strings

name <- "Stefano"
surname <- "Coretta"

name
```

Strings can be used as arguments in functions, like numbers can.

```{r}
#| label: cat

cat("My name is", name, surname)
```

Remember that you can reuse the same variable name to override the variable value.

```{r}
#| label: cat-2

name <- "Raj"

cat("My name is", name, surname)
```

You can combine multiple strings into a **character vector**, using `c()`.

::: callout-tip
#### Character vector

A **character vector** is a vector that holds one or more strings.
:::

```{r}
#| label: character

fruit <- c("apple", "oranges", "bananas")
fruit
```

Check the Environment tab. Character vectors have `chr` before the values.

Another type of vector is one that contains either `TRUE` or `FALSE`. Vectors of this type are called **logical vectors** and they are listed as `logi` in the `Environment` tab.

::: callout-tip
#### Logical vector

A **logical vector** is a vector that holds one or more `TRUE` or `FALSE` values.
:::

```{r}
#| label: logical

groceries <- c("apple", "flour", "margarine", "sugar")
in_pantry <- c(TRUE, TRUE, FALSE, TRUE)

data.frame(groceries, in_pantry)
```

`TRUE` and `FALSE` values must be written in all capitals and *without* double quotes (they are not strings!).

(We will talk about data frames, another type of object in R, in the following weeks.)

::: callout-note
#### Quiz 5

```{r}
#| label: quiz-5
#| results: asis
#| echo: false

opts_5a <- c(
  '`c(1, 2, "43")`',
  '`"s"`',
  answer = '`c(apple)` (assuming `apple <- 45`)',
  "`c(letters)`"
)

cat("a. Which of the following is **not** a character vector.", longmcq(opts_5a))

opts_5b <- c(
  '`c(T, T, F)`',
  '`TRUE`',
  answer = '`"FALSE"`',
  "`c(FALSE)`"
)

cat("b. Which of the following is **not** a logical vector.", longmcq(opts_5b))
```

::: {.callout-tip collapse="true"}
#### Hint

You can use the `class()` function to check the type ("class") of a vector.

```{r}
class(FALSE)
class(c(1, 45))
class(c("a", "b"))
```
:::

::: {.callout-warning collapse="true"}
#### Explanation

**5a**

-   `c(1, 2, "43")` is a character vector because the last number `"43"` is a string (it's between double quotes!). A vector cannot have a mix of types of elements: they have to be all numbers or all strings or else, but not some numbers and some strings. Numbers are special in that if you include a number in a character vector without quoting it, it is automatically converted into a string. Try the following:

```{r}
#| eval: false

char <- c("a", "b", "c")
char <- c(char, 1)
char
class(char)
```

-   `c(letters)` is a character vector because `letters` contains the letters of the alphabet as strings (this vector comes with base R).

-   `c(apple)` is not a character vector because the variable `apple` holds a number, `45`!

**5b**

-   `"FALSE"` is **not** a logical vector because `FALSE` has been quoted (anything that is quoted is a string!).
:::
:::

::: {.callout-important collapse="true"}
#### Extra: For-loops and if-else statements

This course does not cover programming in R in the strict sense, but if you are curious here's a short primer on for-loops and if-else statements in R.

**For-loops**

```{r for-loops}
fruits <- c("apples", "mangos", "durians")

for (fruit in fruits) {
  cat("I like", fruit, "\n")
}
```

**If-else**

```{r if-else}
for (fruit in fruits) {
  if (grepl("n", fruit)) {
    cat(fruit, "has an 'n'", "\n")
  } else {
    cat(fruit, "does not have an 'n'", "\n")
  }
}
```
:::

## Summary

You made it! You completed this week's tutorial.

Here's a summary of what you learnt.

::: {.callout-note appearance="minimal"}
-   **R** is a programming language while **RStudio** is an IDE.

-   **RStudio projects** are folders with an `.Rproj` file (you can see the name of the project you are currently in in the top-right corner of RStudio).

-   You can perform mathematical operations with `+, -, *, /.`

-   You can store values in **variables**.

-   A typical object to be stored in a variable is a **vector**: there are different type of vectors, like **numeric**, **character** and **logical**.

-   Functions are used to perform an operation on its arguments: `sum()` sums it's arguments, `mean()` calculates the mean and `cat()` prints the arguments.
:::

::: {.callout-important collapse="true"}
#### Extra: Programming in R

If you are interested in learning about programming in R, I recommend you go through Chapters 26-28 of the [R4DS](https://r4ds.hadley.nz/functions) book and the [Advanced R](https://adv-r.hadley.nz) book.

Note that these topics are not covered in the course, nor will be assessed.
:::
