## Quick repetition of lesson 1

-   Assigning numeric values or strings to objects, then using the objects:

```{r}
x <- 5
y <- "string"
x*2
print(y)
```

-   Using whitespaces to organize your code
-   Removing objects in the environment

```{r}
rm(list = ls())
```

-   Functions & arguments

```{r}
rnorm(20, mean = 100, sd = 10)
```

-   Function help

```{r}
?rnorm
```

-   Installing & loading packages

```{r}
# install.packages("tidyverse")
library(ggplot2)
library(dplyr)
library(readr)
```

## Goals for lesson 2

-   Commit to Git
-   Push to GitHub
-   Organize a project (folder, files, R-project)
-   Read in & manipulate data
-   Make a figure & save it to PDF
-   Create a Quarto document

## File names and system

Before we create our first R-project, we need to talk about how to name files and folders, and how the file system and file paths on your PC work, and how you navigate your way through it.

### Naming things

-   Use names that work well for computers & people
-   No spaces
-   Be consistent with capitalisation (set a rule to make it easy to remember, like always use lowercase)
-   A full stop only before the file extension `data_file.csv`
-   Use underscores (`_`) to separate parts of the file name, and dashes (`-`) to separate words in a section `"data_questionnaire_2021-11-15.xls"`
-   Prefix a file name with an underscore to move it to the top of the list, or prefix all files with numbers to control their order
-   Use YYYY-MM-DD format for dates so files sort in chronological order.

#### Bad examples

-   `Data (Participants) 11-15.xls`
-   `final report2.doc`
-   `Participants Data Nov 12.xls`
-   `project notes.txt`
-   `Questionnaire Data November 15.xls`
-   `report final.doc`
-   `report final 2.doc`

#### Good examples

-   `_project-notes.txt`
-   `data_participants_2021-11-12.xls`
-   `data_participants_2021-11-15.xls`
-   `report_v1.doc`
-   `report_v2.doc`
-   `report_v3.doc`

### Navigating the file system: Terminal & bash

-   File paths: forward or backward slash to divide sub folders: `directory/subdirectory/`
    -  / on Linux and Mac
    -  \\ on Windows
-   Your user accounts' main directory: `/Users/UserName/`, or on Windows: `C:\Users\Username\`
-   A file on your Desktop: `/Users/UserName/Desktop/datafile.csv`
-   You can navigate your file system via the **Terminal**.
    -   On Mac & Linux (Unix-based systems) this software is called Terminal or Console outside of Rstudio
    -   On Windows, the software we need is called: PowerShell or Git Bash.
    -   Try to find the program in the same way you would find any other program, then close it again.
-   You can access the Terminal from within R-studio (next to the Console at the bottom left in Rstudio).
    -   On Windows, make sure you use the right Terminal in the Global Options:
    -   Choose Git Bash or PowerShell here.
    -   The default Terminal of some older Windows systems is `Command Prompt` - it won't work in the same way.

```{r, echo = F}
knitr::include_graphics('images/change_default_terminal.png')
```

-   In the Terminal, we will use the coding language `bash`.
-   Unlike in R, white spaces have a meaning in `bash`, so make sure you get them all right!
-   In `bash`, you can use these commands to navigate between folders:
    -   `cd` change directory, e.g., to move to my user directory: `cd /Users/Hannah/`
    -   `~` shortcut for the user account directory \``/Users/UserName/`, e.g., to move to the user directory: `cd ~`
    -   `..` move one directory upwards: `cd ..`
    -   Note how there is always a white space after the function `cd`. In R, we would have `()` instead: `function()`

```{r, echo = FALSE}
knitr::include_graphics('images/Terminal_in_Rstudio.png')
```

::: callout-tip
I find it useful to have all my analysis projects in a common folder directly in my user directory: `~/AnalysisProjects/`. In it, you could then have a folder `R_introduction` for this course.
:::

### Working Directory

-   Folder of the project you are currently working on
-   Never change the working directory in a script
-   Your scripts should only reference three types of locations:

| Where | Example |
|----------------------|--------------------------------------------------|
| on the web | "https://hannahmetzler.eu/R_intro/Lesson_2/data/datafile.csv" |
| in the working directory | "datafile.csv" |
| in a subdirectory | "data/datafile.csv" |

-   Typing `pwd` (print working directory) in the Terminal shows you the directory you are currently in.

::: callout-caution
#### Exercise

-   In Rstudio, go to the `Terminal`
-   Check which directory you are in
-   Navigate to your user directory
-   Move back up one folder
-   Move back to your user directory using the shortcut
:::

## Setup Git & GitHub repository for your project

- We cover the absolute basics here, for more: <http://happygitwithr.com/>
- Do you all have Git Setup & a GitHub account?

### What for?

- Keeping your coding projects organized in one place
- Backup your code & data
- Version control: edits over time
- Sharing & collaborating on code

### How Git works

<!-- ![](images/how_git_works.svg) -->

- Committing: creating a named/time stamped version on your PC
- Pushing: Uploading to GitHub
- Repository: directory/folder registered by Git


::: callout-tip
You don't technically need to use Git and GitHub to code your data analysis. You could just store your files locally. BUT: I strongly recommend you make a Git repository for every data analysis project. It really helps to keep things organized in one place, not lose your code, go back to earlier versions, share it, collaborate on it, and so on. To practice, we will create a repository for every lesson. 
:::

### Create a remote git repository

We will now create a remote repository on Github, copy it to our local PCs, and then continue Lesson 2 in that local repository.

-   On <https://github.com/> click on `New` on the top left.
- For later: you can navigate to your repositories via clicking on your profile and then choose `Your repositories` or `Repositories`. 

As shown in the screenshot below:

-   Name the repository
-   Make it private
-   Add a README file
-   Choose the template R for the .gitignore file
-   (No License needed)
-   Click `Create repository`:

```{r echo=FALSE}
knitr::include_graphics('images/create_repo.png')
```

-   `README.md`: where you describe the project (folder structure, content, etc.)
-   `.gitignore`: Hidden file that tells Git what not to upload to GitHub (e.g., figures)

### Clone the remote Git Repository to your laptop

1.  Copy the SSH link of your repository (for connecting it to Rstudio):

```{r echo=FALSE}
knitr::include_graphics('images/copy_SSH_repo_link.png')
```

2.  In Rstudio, in the Terminal:

-   Navigate to the directory where you put the R_introduction folder using `cd`. (I want it in my folder `AnalysisProjects`)
-   `git clone` and paste your repository link:

```{r echo=FALSE}
knitr::include_graphics('images/git_clone.png')
```

There is now a folder with the name of the remote repository in the directory you "cloned" it to. (For me, in the `AnalysisProjects/` folder.) In that folder, let's start our first R-project!

## Organize your project

### R-projects

-   Useful to organize your coding projects
-   Group all files of a project in a directory
-   Allows using Git for version control
-   R-project automatically sets working directory to the R-project folder
-   In the top right corner in Rstudio, you can see that we are not currently in any project.
-   Let's create a project for this lesson:

::: callout-caution
#### Exercise

1.  Create a project in Rstudio: Choose `Create a project` (or `New Project ` in the `File` menu).

```{r, echo=FALSE}
knitr::include_graphics('images/create_project.png')
```

2.  Choose `Existing Directory`
3.  Use `Browse` to navigate to our folder `R_intro_lesson_2` and click `Create Project`

```{r, echo=FALSE}
knitr::include_graphics('images/new_project.png')
```
:::

From now on, you can double click this Rproject file in your `R_intro_lesson2` folder to directly open Rstudio from this folder.

### Folder structure

::: callout-caution
#### To do

Create these folders inside the main project directory `R_intro_lesson2`: 

-   data
-   code
-   figures
-   write_up

Download this [data file](https://github.com/hannahmetzler/R_intro/Lesson_2/data/pets.csv) from the course website and put it into the data folder. We'll be writing a script to analyse it during this session. If needed, you can also download it [here](https://github.com/hannahmetzler/R_intro_lesson2/blob/main/code/rintro_lesson2.R).
:::


-   Alternative/additional folder names in future projects could be:
    -   tables
    -   reports
    -   output (tables, reports, ...)
    -   raw_data: I recommend having a separate folder for the raw data
    -   code = scripts
-   Plus any other project specific folders


## Backup your project on GitHub

### Commit to Git

We can now back up the project and data to a "remote repository" on GitHub.

1.  Click on **Git** in the upper right pane.
2.  You see 2 files to commit:

```{r echo=FALSE}
knitr::include_graphics('images/files_for_commit.png')
```

3.  Add them to git by checking the box

```{r echo=FALSE}
knitr::include_graphics('images/add_commit_files.png')
```

4.  Click commit
5.  Write a commit message (describe what the commit contains)

```{r echo=FALSE}
knitr::include_graphics('images/commit_message.png')
```

6.  Click Commit again, then Close.

### Upload to GitHub

-   Click **Push**.
-   Go to your remote repository on GitHub. Do you see the folder and files you added?

## Read in and manipulate data

We will finally start coding!

::: callout-caution
#### To do

-   Open an R-script by clicking on the green plus below `File` (top left)
-   Save it in the code folder, e.g. with the name `rintro_lesson2`
:::

-   At the top of the script, we load all required packages.
-   Lines with \# are comments, so R does not read them as code.
    -   Keyboard shortcut to (un)comment a line or selection: `Ctrl+Shift+C` / `Cmd+Shift+C`
-   Lines ending with \#### are code blocks, that can be opened and closed. Use them to organize your script!
-   To run a line in a script, press `Ctrl + Enter`
-   To run an entire R-script: `Ctrl + Shift + Enter`

::: callout-caution
# To do
Write and run the code below:

```{r, results = FALSE, eval = F}
## LOAD PACKAGES ####
library(tidyverse)
```

-   To read in the data, we use `read_csv()` from the package readr.

```{r, results=FALSE}
## READ IN DATA AND ORGANIZE ####
# Read in data
data = readr::read_csv("data/pets.csv",  col_types = "cffiid")
```
:::

-   The working directory is in the root folder, so we need to first indicate that the datafile is in the data folder: `"data/pets.csv"`
-   The last part `col_types = "cffiid"` defines the type of variable - we will get to this below.


### Look at the data

The first and last rows of the data frame:

```{r, echo = FALSE}
head(data) # first rows
tail(data) # last rows
```

-   `data` is our data frame (the whole data table with variables as columns and observations as rows)
-   `id, pet, score, age, weight` are variables
-   `dog` and `ferret` are levels of the variable `pet`
-   `UK` and `NL` are levels of the variable `country`

Now, we'll have a look at the data using these functions (from basic R):

-   dim(): number of rows and columns
-   head(): print the first 6 rows
-   tail(): print the last 6 rows
-   xtabs(): how many data points exist for each level of a variable

::: callout-caution
# To do
Write and then run the code below. After each written line, use `Ctrl + Enter` to run it.

```{r, results=FALSE}
# Look at data
dim(data) 
head(data) 
tail(data) 
xtabs(~pet, data) 
```
:::

All of this is basic R. In addition, we can use functions from packages. Using `glimpse()` from dplyr gives you an overview of the data:

```{r}
dplyr::glimpse(data)
```

Here, you can see that the data frame contains different types of variables:

-   `chr` (character): for variables with text (can contain any character: letter, numbers, symbols, spaces)
-   `fct`(factor): for categorical variables
-   `int` (integer): numeric, stores whole numbers
-   `dbl` (double): numeric, numbers with decimals

### Select a part of the data

**There are always lots of ways to do the same thing in R.**

Let's say we want to create a new data frame that contains only cats data. Here are some ways to do that, which all produce exactly the same result. (Just examples, no need to understand this yet):

```{r, eval=FALSE, results=FALSE}
# basic R to extract specific rows from a dataframe
data_cats = data[data$pet == 'cat',] 

# the function subset
data_cats = subset(data, pet == 'cat') 

# using the function filter from the package dplyr
data_cats = data %>% 
  dplyr::filter(pet == 'cat')
```

We'll use dplyr (the third way). dplyr is a package from the Tidyverse for 


```{r}
# Select only cats
data_cats <- data %>%
  dplyr::filter(pet == "cat")
```

Here is a step by step explanation:

-   `data_cats`: new data frame
-   `<-` (or `=`) is used to assign
-   `data`: original data frame
-   `%>% (or \|\>)\`: a "pipe" in dplyr - let's R know you are not done writing code, it waits until it gets a line not ending with `%>%` before executing the code.
-   `filter( )`: verb
-   `pet`: variable
-   `cat`: level of the variable
-   `==` is a marker of relationship (like \<, \>)

::: callout-caution
# Write down and run the code for selecting only cats data. 

You can use these keyboard shortcuts:

-   `<-` for assigning: `Alt + -` or `Option + -`
-   Keyboard shortcut:`%>%` pipe: `Shift + Ctrl + M` or `Cmd + Shift + M`
:::

Let's look at the top rows:

```{r}
head(data_cats)
```


There are only rows with cats left.

::: callout-caution
#### Exercise

Look at the new data frame `data_cats` with all the functions you used above for `data`.
:::

## Make a figure with ggplot2

We'll make a box plot showing the weight of the different pets. `ggplot2` is a package from the Tidyverse that is very flexible for making pretty plots.

Plots in ggplot are created by adding elements on top of each other. See the vignette: We will use data, mapping and a layer for a box plot for now.  

```{r, eval = F}
vignette("ggplot2")
```


Start again with a section header (####).

```{r}
## MAKE FIGURES ####
# Weight by pet
data.plot <- ggplot(data, aes(x = pet, y = weight)) +
  geom_boxplot()
data.plot
```

Step by step explanations:

-   Every plot in ggplot2 is initiated with the call `ggplot()`
-   Next comes the data frame (here `data`)
-   Then we map the data to the aesthetics (`aes()`) of the figure: here only which variable onto the x- and y-axis.
-   For ggplot2, we use `+` to connect lines (like `%>%` above for dplyr)
-   In line 2 comes the type of plot (box plot). Most plots in ggplot2 with `geom_` plus the type of plot, so here `geom_boxplot`.
-   We store the plot in the variable `data.plot`.
-   We print out `data.plot` to see the plot.

It is very easy to make this plot pretty. With the code below: 

-   We fill each box with a colour by including `fill = pet` in the aesthetics.
-   We change the design of the entire plot using one of the default themes: `theme_bw()`
-   We add a title using `ggtitle()`

```{r}
# Pretty plot
data.plot <- ggplot(data, aes(x = pet, y = weight, fill = pet)) +
  geom_boxplot()+
  theme_bw()+
  ggtitle("Weight by pet")
data.plot
```

To save the plot to a file to use in your paper, use `ggsave` to save it in our subfolder for figures:

```{r, eval=FALSE}
# save the plot
ggsave('figures/boxplot_pets_weight.png', plot = data.plot, width = 6, height = 4, dpi = 300)
```

-   Arguments in order:
    1.  file name including the paths to the file
    2.  plot you want to save
    3.  width
    4.  height
    5.  resolution (300 dpi is often required for papers)
-   Instead of .png, you could use other formats: .pdf, .jpg, .tiff and more.
-   Check the figure in your `figures/` folder.

## Commit your work to Git

-   Go back to the **Git** menu at the top right and choose `Commit`
-   Once again check all of the boxes of changed files (Select all files at once using Shift)
    -   Write a message (e.g., "Looked at data, made boxplot").
-   Click `Commit` to store a new version of your project, then `Close`.
-   To upload to GitHub, click `Push`.
-   To confirm that it worked, go to your remote repository on github.com and refresh the page. Do you see the new files?

## Create a report using Quarto

### What is Quarto?

-   Quarto enables you to create reproducible reports, presentations, publications & websites
-   Output in various formats: HTML (websites & slides), PDF, Word
-   From a variety of coding lanugages: R, Python, Julia, Observable Java Script
    -   Quarto builds on R Markdown, which did the same but only for R.
-   R script: only code (comments in lines starting with #)
-   Quarto Document allows to combine text and code
-   Useful to have automated reports about your results
-   You could write entire papers (see [Data Skills for Reproducible Research](https://psyteachr.github.io/reprores-v3/intro.html))

### Let's make a Quarto Report of our results!

-   Save the objects in your **Environment** to the `write_up` folder, naming them `lesson2_environment`.

```{r,echo=FALSE}
knitr::include_graphics('images/save_environment.png')
```

-   Open a Quarto Document

```{r,echo=FALSE}
knitr::include_graphics('images/script_types.png')
```

-   Enter a title and your name
-   Choose HTML as output
-   Click `Create`

```{r,echo=FALSE}
knitr::include_graphics('images/open_quarto.png')
```

-   Save the Quarto document in your write_up folder `Lesson2_Report`

-   You can see that your R-script ends with .R, the Quarto file with .qmd

```{r,echo=FALSE}
knitr::include_graphics('images/quarto_source_visual.png')
```

-   By clicking on `Source`, you will see the content written in "Markdown" language.

-   **Markdown** is

    (1) a plain text formatting syntax, and
    (2) a software tool that converts text to HTML.

Let's start writing in our Quarto Document:

-   Delete the example text after the heading **Quarto** (including the heading, but not everything above)
-   Use `Ctrl+Alt+I` to insert a code chunk. \`\`\`{r} ` lets R know that the following is code.
-   In this code chunk, we load the data we have saved before.
-   Quarto files directly run in the folder where they are saved, so here directly in the write_up folder.


```{r, eval=F}
load("lesson2_environment.RData")
```

-   Start writing normal text (as below) in your document. Using \# turns text into a title in Markdown.

```{Markdown, eval = F}
# Data

Here is a look at our two data frames. First is the one we read in, the second is our subset with just the cat's data. 


# Figure


Here's a figure of the weight of different pets in the dataset.

```

-   Now, we will fill in code chunks to present our data and figure. Use `Ctrl+Alt+I` to insert them in the right places.
-   Use `head(data)` and `head(data_cats)` to present your data sets under \# Data.\
-   Use the object in which you stored the plot for the figure (`data.plot`) under \# Figure.
-   This is how it should look like:
  
```{r, echo=F}
knitr::include_graphics('images/quarto_report.png')
```

-   If you click on **Render** at the top, you will get a HTML file with your report. Open it from the folder.

```{r, echo=F}
knitr::include_graphics('images/render.png')
```

-   You can simply switch the format to `format: docx` at the top, then render again as a Word document.
-   PDF would also work, but requires installing a version of Latex (software that renders PDFs) the first time you render as PDF. Via your Terminal, you need to run this code to install a tiny version of Latex: `quarto install tinytex`

::: callout-tip
You can write a lot of your code directly in Quarto Documents, allowing to combine your results (tables, figures) with interpretations directly in the same document. Lead through your entire analyses step by step. If a step needs a lot of code, move that code to a script in the code folder, and call the script from your Quarto document using the function `source()`. For example, you could first call a script that cleans the data, then make figures and run statistical tests directly in the Quarto Document.
:::
  
## References
  
- The completed code for the lesson can be found [here](https://github.com/hannahmetzler/R_intro_lesson2).
  
This lesson is based on:
  
- Page Piccinini, R-Course, [Lesson 1: R Basics](https://pagepiccinini.com/r-course/lesson-1-r-basics/).
  
- Chapter 2 of: Lisa DeBruine & Dale Barr. (2022). [Data Skills for Reproducible Research](https://psyteachr.github.io/reprores-v3/intro.html): (3.0) Zenodo. doi:10.5281/zenodo.6527194.

