---
title: "Initial setup"
author: "Jonathan Harrington, Johanna Cronenberg"
output: 
  bookdown::html_document2:
    number_sections: TRUE
    toc: true
    theme: flatly
    highlight: pygments
---

<style>
div.col {background-color: #ffd5c0; border-radius: 5px; padding: 20px;}
body {font-size: 16pt;}
h1 {font-size: 24pt;}
h2 {font-size: 22pt;}
p.caption {font-size: 12pt; text-align: justify;}
code.sourceCode {font-size: 16pt;}
</style>

# The software package and Rstudio
- Download and install [the Software Package R](https://ftp.fau.de/cran/). 

- Also download and install [RStudio](https://rstudio.com/products/rstudio/download/#download).

# Create a directory on your hard drive
Create a directory on your hard drive to be used on this course. Here I have created one on my desktop called ipsR -- but any directory name is fine.

![](img/setup1.png)

# Startup Rstudio
by clicking the Rstudio icon.

# Create a project
Choose the directory that you just created under step 1. See the figure below:


![](img/setup2.png)
You only need to create the project once. When you startup Rstudio the next time, the system should automatically open up inside this project that you created. If not, or if you closed the project, you can open it again:

![](img/setup2b.png)

You can get back to your default directory (if you were using R before then) any time by selecting close project in the above menu. If you have any difficulty with project installation 
[watch this introductory video.](https://www.youtube.com/watch?v=hKoSJGWnFFA)

# Install packages
In the Rstudio console window, install the following packages (may take a few minutes). *You only need to do this once*:

```{r, eval = F}
# install the following packages
install.packages(c("Rcpp", "remotes", "knitr", 
                   "tidyverse", "magrittr",
                   "rmarkdown", "emuR", "gridExtra", 
                   "emmeans", "broom", "lmerTest", 
                   "pbkrtest", "MuMIn", "wrassp", "ezANOVA"))
```

<div class="col">
**More information: installation of R packages**

Should the above result in the error message `installation of package had non-zero exit status`, then it means that installation has failed. For Windows, you might then additionally have to install  [Rtools](https://cran.r-project.org/bin/windows/Rtools/). Für MacOS you might need to install/reset the *XCode command-line tools*. For this purpose, open a Mac terminal window and execute the following:

```{bash, eval = F}
xcode-select --install
# Should the R packages installation still not work:
xcode-select --reset
```

</div>

# Starting and quitting Rstudio
A session starts when RStudio is opened. A session is terminated with `Session > Quit Session` in the main toolbar or with `q()` or  `Strg+Q` or `Ctrl+Q`. The session also ends automatically when you quit RStudio. Verify that you can start and quit from Rstudio. You will then be asked whether you want to save the workspace image. For this course, **please never save the workspace i.e. `Don't save`**.

# For students of P 12.1 Programmiersprache R und P 12.2 Statistik
From [this website](https://www.phonetik.uni-muenchen.de/studium_lehre/lehrmaterialien/R_speech_processing/R_prog_intro/index.html), download the `Rmd` file under `1.1 Objects and their manipulation` and save it to an easily accessible  directory of your choice on your computer. After starting up Rstudio, load this file with filename `01_Rintro.Rmd` into Rstudio. One of ways to do this is with `File -> Open File`. You should now be able to see the file `01_Rintro.Rmd` in `Rstudio`. 

# Learning R: the community

There is a very large and helpful R community that will make learning R easier for you. Here are a few useful links and commands in case you get stuck:

- [Stack Overflow](https://stackoverflow.com/questions/tagged/r): A blog where you can often find an answer to your questions about R. The easiest way is to google your question in English; a stack overflow member's answer will be included in the first search results.

- [Hadley Wickham's "R for Data Science"](https://r4ds.had.co.nz/): 
Hadley Wickham is the chief programmer of "tidyverse". His books are very readable, well structured, and entertaining.

- Cheatsheets: those are pdfs that provide an overview of functions with explanations and examples in a very compact form. You will find some cheatsheets in the main toolbar via `Help > Cheatsheets`. The first three are especially useful. You can also find cheatsheets by googling see e.g. [Data Transformation with dplyr](https://raw.githubusercontent.com/rstudio/cheatsheets/master/data-transformation.pdf) or this very comprehensive [Reference Card](https://cran.r-project.org/doc/contrib/Short-refcard.pdf).

- Vignettes: For some packages there are so-called "vignettes", which are mostly HTMLs or PDFs that have been written by the package's authors. You can search for vignettes using the following input to the console:

```{r, eval = F}
# for e.g. one of the libraries from tidyverse
vignette("dplyr")
```

- You can get information about a function by entering its name in the RStudio `Help` toolbar. You'll then get information about the function's arguments and often some examples. You can also get help via the console, as follows (e.g. here for `getwd()`): 

```{r, eval = F}
?getwd
help("getwd")
```

- If you're not sure of the name of a function and want to enter a keyword (e.g. for functions that have the name 'spline' in them somewhere):

```{r, eval = F}
apropos("spline")
```

- The following provides further question-and-answer practice for R:

```{r, eval = F}
install.packages('swirl')
library(swirl)
swirl()
```

`ggplot2` is both a well-known and popular program for creating plots. There's plenty of help available for `ggplot2` from the R community. Here are some useful links for creating graphics:

- The chapter [Data Visualisation](https://r4ds.had.co.nz/data-visualisation.html) in Hadley Wickham's "R for Data Science"

- [Cookbook for R](http://www.cookbook-r.com/Graphs/)

- [Cheatsheet ggplot2](https://rstudio.com/wp-content/uploads/2015/03/ggplot2-cheatsheet.pdf)

- [Stack Overflow](https://stackoverflow.com/questions/tagged/ggplot2?sort=faq)

# Statistics in R: Literature

If you need more information using statistics in R, the following are recommended:

- Johanna Cronenberg: Programming in R: An Introduction for Phoneticians [en](https://www.phonetik.uni-muenchen.de/~jmh/lehre/basic_r/english/book-output/) 
[de](https://www.phonetik.uni-muenchen.de/~jmh/lehre/basic_r/deutsch/book-output/)

- Bodo Winter's "Statistics for Linguists: An Introduction using R": A book with excellent explanations to all major themes in inferential statistics. It's available online via the LMU library.

- Stefan Gries' "Statistics for Linguistics with R: A Practical Introduction": Useful for decision makng about which model to use for which type of question. Although the code is a bit out of date (given that the book was published in 2009) the statistical content is still up-to-date. Also online via the LMU library.

- Harald Baayen's "Analyzing Linguistic Data: A Practical Introduction to Statistics": Introduction for advanced readers. Although the R code is a bit out of date, the explanations and examples of statistics foundations are very helpful. Available as a hard copy from the LMU library.

# R Markdown

R Markdown is a type of text document in which so called code snippets can be embedded and executed. Typically R Markdown files contain more text than code. An R markdown file can be created with `File > New File > R Markdown` and should be saved with the extension `.Rmd`. It can then be converted or *knitted* into other formats including HTML. This conversion is done by clicking on the wool icon next to *Knit*. Alternatively:

```{r, eval = F}
library(rmarkdown)
# where x.Rmd is the document to be knitted
render("x.Rmd")
```

This entire course makes use of R markdown. You can convert the `.Rmd` files into HTML as follows. 

For example, download and copy `setup.Rmd` (the file you are currently reading) into your project directory from [here](https://www.phonetik.uni-muenchen.de/studium_lehre/lehrmaterialien/R_speech_processing/index.html) into your project directory.

Also download and unpack into the same directory [the images that are needed for this conversion](https://www.phonetik.uni-muenchen.de/studium_lehre/lehrmaterialien/R_speech_processing/img.zip).

Your project directory should now include a folder called `img` and any number of `.Rmd` files as shown here:

![](img/setup4.png)

Open `setup.Rmd` in Rstudio (e.g. from the toolbar, `File > Open File` and choose `setup.Rmd`) and then click the Knit button as shown below in order to create the corresponding HTML file which will also be stored in your project directory:

![](img/setup5.png)
You should be able to create HTML files yourself for any `.Rmd` files on this course. This is also a useful verification that all the code can be executed on your computer.

<div class="col">
Here are a few further brief pointers on using Markdown.

You can run pieces of code known as code-snippets using the green arrow on the right as shown in the figure below. 

![](img/setup6.png)

Some information about creating text for your own markdown document is as follows:

\# Heading: One hashtag gives the largest heading; the greater the number of hashtags the smaller (the more embedded) heading.

\*\*bold\*\*: can be marked with double asterisks before and after the text to be placed in bold.

\*italics\*: as above but with a single asterisk

\`code\`: single backslashes can be used to denote variables or code within running text.

\`\`\`: Three backslashes mark the beginning and end of code - see the above figure. 

More information see the [Cheatsheet for R Markdown](https://www.rstudio.org/links/r_markdown_cheat_sheet) (esp. p. 2, left column).

</div>

# For users of EmuR

## Libraries

Load the `emuR` and `wrassp` libraries:

```{r, eval = F}
library(emuR)
library(wrassp)
```

## Default browser 

Set your default browser to Google Chrome. This is necessary in order to display the Emu web application from R.

![](img/setup0.png)

## Verification

Verify that everything works by entering the following commands to the console.

```{r, eval=F}
# download a demo database
create_emuRdemoData(dir = tempdir())
# load it
ae = load_emuDB(file.path(tempdir(), "emuR_demoData", "ae_emuDB"))
# look at it
serve(ae, useViewer=F)
# close the browser window to carry on
```

The third command `serve(ae, useViewer=F)` should produce the following image in your browser:

![](img/setup3.png)


