---
title: "Lesson 1 - A short introduction to R"
author: "Jonathan Harrington / Ulrich Reubold"
date: "`r format(Sys.time(), '%d October %Y')`"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# 0 Current Versions of `R` and `RStudio`

Your `R` version should be 3.5.1.

Check this with
```{r}
getRversion()
```

```{r,echo=FALSE}
rm(list=ls())
```

In this is not true, please go to https://cran.r-project.org/ and downlowd Version 3.5.1.

The current version of `RStudio` should be Version 1.1.456. Check this via `Help`-->`Check for Updates` in the drop-down menu of RStudio.

# 1 General usage
## 1.01 Starting and closing `RStudio`, and the general usage of objects in your `R` workspace. 

Whenever you start `RStudio`, a new 'session' of `R` will be started. `RStudio` has several panels, and one of them, called `Console`, is your connection to `R` in which you can type. You could now e.g. calculate in `R`, e.g. by typing

```{r}
1+2
```
 and you will see the result immediatly.
 
 However, in most cases, we will not calculate in that way, because it is much more convenient to use so-called objects. An object is an entity that has a name and a value. E.g. you could create an object of the name `a` that has the value 17 by typing

```{r}
a = 17
```
 
 If you now type the name of the object
 
```{r}
a
```
 
you will get the object's value (in this case 17).

The reason for this is that `R` has temporarily saved this object (and its value) into `R`'s workspace.

We can check this by listing all objects by

```{r}
ls()
```

and we will see all the objects that are temporarily in our workspace. 

When we now want to close `RStudio` (and therefore our `R` session), `R` will check whether its workspace is empty or not (or: not changed or changed). If it is not empty (or if it is changed), we will be asked whether we wanted to save our current workspace (`Save workspace image to ~/.RData?`). 

If we click on `No`, our object `a` will be lost, and we would have to recreate it in the next session (at least in the unlikely case that we will need it again). 

If we click on `Yes`, however, the workspace image will be saved (into a file of the name '.RData'); this file will be loaded whenever we will start an `R` session in the future. If we then create new objects and continue with saving our workspace to the file '.RData', this file will grow; after some time, this may lead to a longer loading time whenever we try to start `R`, and we will probably get confused about objects that we had created a long time ago, and that are no longer needed.

Therefore, in most cases we will not want to save all objects in our workspace to the file '.RData'. We advise you to click on `No` whenever you will be asked whether you wanted to save your workspace. Instead, you can save certain objects in your workspace permanently into an RData-file with a name given by you, and reload these objects whenever (and only then) you are in need of them (see below).
The only exception to our advice is given whenever you really want to save a couple of objects that you will need in any future session. In our case, this is true for a few objects containing paths, from which we will be able to load speech and other data.

Before we create these path-objects and save them permanently, we should clean up our workspace. This can be done by simply closing `RStudio` and by answering `No`.

By the way, we could close the `R` session and `RStudio` also by typing

```{r eval=FALSE, echo=T, warnings=T, message=T}
q()
```

```{r eval=TRUE, echo=FALSE, warnings=T, message=T}
rm(list="a")
```


## 1.02	Data import and export

We will have to import data from an external source and to save data (including speech data) on our own computer. In order to to do so, the first step will be to create a folder on your computer. Please create (in your file browser) a folder called *myEMURdata* somewhere on your computer. Now find the correct path to this folder. This could be something like */Users/reubold/myEMURdata*.

Now reopen `RStudio` and create an object in `R` called `mypath` that contains your path (must be within `" "`):
```{r}
# 
mypath = "/Users/reubold/myEMURdata"
```

The object with your path can be listed by

```{r}
ls()
```

and you can call your path by

```{r}
mypath
```

However, this is just a confirmation of the existence of an object and its value. In order to confirm that the directory really exists, you need to type in
```{r}
dir.exists(mypath)
```

You can also use a "path" that is a
URL (Uniform Resource Locator). In this case, the function `dir.exists()` will fail.

For loading data, we will use a certain URL (already known to those users familiar with the statistics seminar) 

```{r}
pfadu = "http://www.phonetik.uni-muenchen.de/~jmh/lehre/Rdf"
dir.exists(pfadu)
```

Although `dir.exists()` fails, this URL is correct!

Now, you should close `RStudio` and save the current workspace into `~/.RData` by simply clicking on `Yes` (only this time!). `mypath` and `pfadu` should then be available whenever you open a new `R` session.


Now, restart `RStudio`, and verify the existence of `mypath` and `pfadu`

```{r}
ls()
```

From now on, we are able to load data from both paths, and to save data to `mypath` (`pfadu` is read-only).

```{r}
ai = read.table(file.path(pfadu, "ai.txt"))
```

An explanation:

```{r}
file.path(pfadu, "ai.txt") #creates a new path, by adding '/' to "pfadu" and then concatenating this to "ai.txt" 

```
`read.table()` reads a table (related commands loading data see below...) from a file and creates a so-called data.frame

You can now work with this table (in its present format 'data.frame') in `R`

```{r}
ai
```

and/or you can now save this object as a table-like txt-document via

```{r}
write.table(ai, file.path(mypath, "my_ai.txt"))
```

Please confirm externally the existence of a file calles 'my_ai.txt' in your personal folder `mypath`!

### Download of (speech) data

In most cases, however, we will have to load (speech) data not directly in R, but externally following hyperlinks; you could do this from within R via the function `system(command)`, however, the `command` part is depending on your operating system. Therefore, simply click directly onto the link in the present html document in order to download (speech) data. E.g., try to download [testsample.zip](http://www.phonetik.uni-muenchen.de/~jmh/lehre/Rdf/testsample.zip)!    

Please save the zip-file 'testsample.zip' in your personal directory given in `mypath`. Unzip it, and confirm the existence of the folder 'testsample' containing two sub-folders, 'german' and 'nze' (each of these sub-folders contains wav and txt files). We will work with this data soon.


## 1.03 Types of objects
You can create an object and assign a value with it using '=' or '<-'

```{r}
# numerical objects
a = 3
b <- 4

# objects containing characters and/or character strings need " "
c = "etwas"

# objects can contain more than one entity; assignment has then to be done with function 'c()':

d = c(3,4)
e = c("drei","vier")

# Objects can be tables; these can be of type 'matrix' (= all elements are of the same type, e.g. numeric)
# or of the type 'data.frame' (= its elements may have mixed types; columns have column names ...), e.g.
ai
```

To see an object's value(s), simply type its name

```{r}
a
```

To see an object's type, do

```{r}
is(a)
```

Create new objects with the same contents:

```{r}
x = y = z = 4
```

Objects can easily become overridden; you need to be careful, as you will get no warning:

```{r}
y = 4
y
y ="Phonetik"
y
```

## 1.04 Saving objects in `R`'s workspace permanently
Save objects with `save()`. You need to define the objects to be saved via `list =` and path and filename via `file =`

To save everything in your workspace, you can use the function `ls()`, which lists all objects in your workspace.
However, this is identical to closing `RStudio` and replying `Yes`to the question `Save workspace image to ~/.RData? [y/n/c]: `:

```{r}
save(list = ls(), file = file.path(mypath, "objects.RData"))
save(list = ls(), file = file.path(mypath, "objects"))
```

The filename (here: 'objects') is up to you! You have now created two files in your folder, one without any extension, one with the extension '.RData'. Both have identical file sizes, and both can be loaded into `R` with the function `load()` or `attach()`. The advantage of extension '.RData' is that you can load its contents into `R` via a double click on the file (corresponds to `load()`).

## 1.05 `attach()` or `load()` objects

```{r eval=TRUE, echo=FALSE, warnings=FALSE, message=FALSE}
rm(list = c("ai","a","b","c","d","e","x","y","z"))
```

Close `RStudio`/`R` (do NOT save the workspace), and restart it again, and then: 

```{r}
attach(file.path(mypath, "objects"))
```


```{r}
a
x
y
```
I.e., you can call the objects' contents; however, the objects will not be listed by `ls()`
```{r}
ls()
```

Attached files containing objects can, however, be seen by typing

```{r}
search()
```
`detach()` can remove certain entities (here: the second entry = path to the file) in the search-path:
```{r}
detach(2)
search()
```

Objects' contents like that of x are now no longer available:

```{r,eval=FALSE}
x
# Error: object 'x' not found
```

Alternatively: `load()` 'objects' or 'objects.RData' or simply double click on 'objects.RData'

```{r}
load(file.path(mypath, "objects.RData"))
ls()
```

The saved objects are now in your workspace. In order to remove certain objects, use `rm()`, e.g.:

```{r}
rm(list=c("x","y","z"))
ls()
```

In order to remove all objects, you could do: 

`rm(list=ls())`

However, this would also delete `mypath` and `pfadu`; so you should better simply close `RStudio` (again: without saving the workspace!) and reopen it.

### 1.06 Libraries (packages)
Functions in R have a name, followed by `(...)`; `...` stands for object names and/or certain parameters; most function names are more or less telling (`save()`, `load()`, `read.table()` and the like): some of them need a bit more of a good guess, e.g. in order to *list* objects, use the function `ls()`: 
```{r eval=TRUE, echo=FALSE, warnings=FALSE, message=FALSE}
rm(list = c("ai","a","b","c","d","e"))
```
```{r,error=TRUE}
ls()
```


`R` comes with many functions (see e.g. http://cran.r-project.org/doc/contrib/Short-refcard.pdf for an overview over the most common ones). 

However, many functions that we will need are not available in `base R`, especially none for working with speech databases, of course. However, many  more specialized functions have been made available by developers of so-called packages or libraries. To make these functions available to us, we need to install the corresponding packages. 


In `RStudio`:

**Tools-->Install Packages**

or `install.packages("packagename")`; we will need "emuR" for speech database creation an analysis, "dplyr" for the manipulation of data, and "ggplot2" for plotting data:

```{r,eval=FALSE}
install.packages("emuR")
install.packages("dplyr")
install.packages("ggplot2")
```
After the installation process (which might take a while), you still have to attach the functions to `R`'s search path; e.g. function `geom_boxplot()` will not be available, unless you attached it to the search path by using `library(ggplot2)`
```{r, error=TRUE}
geom_boxplot() 
library(ggplot2)
geom_boxplot() 
```

Use `search()` and `detach()` in order to remove function names of certain packages from `R`'s search path:

```{r,error=TRUE}
search()
```
ggplot2 is listed as number 2, so remove it by
```{r,error=TRUE}
detach(2)
geom_boxplot()
```

This may be necessary, whenever `R` tries to apply the 'wrong' function; this may happen whenever you have more than one package loaded, and functions of these packages accidentally share the same name. 

Alternatively, you could also try to call the function by adding the correct package's name with `package::function`, like e.g.

```{r}
ggplot2::geom_boxplot()
```

Another advantage of this procedure is - as you can see above - that the function will be available although you haven't loaded the package (ggplot2 is NOT in the `R` search path right now...)

## 1.07 Help

### General Introduction

See 'An Introduction to R' in:
```{r,eval=FALSE}
help.start()
```

### Help about certain functions

You want to know more about a certain function, like `pnorm()`?
```{r,eval=FALSE}
help(pnorm)
# oder
?pnorm

example(density)

apropos("spline")

help.search("norm")
```

Of course, you need to know the function's name in order to call for help. In order to get a list of all functions of a package, type `library(help=PACKAGE)`, e.g.

```{r}
library(help=emuR)
```

A document will open; go to 'Index' and find a list of names of functions (and possibly objects) and a short description of what the function does (or what the object contains). For a closer examination, copy a function's name and paste it into one of `?FUNCTIONNAME` or `help(FUNCTIONNAME)` or `help("FUNCTIONNAME")`

You could also use the packages' reference manuals, e.g.

https://cran.r-project.org/web/packages/emuR/emuR.pdf

https://cran.r-project.org/web/packages/dplyr/dplyr.pdf

https://cran.r-project.org/web/packages/ggplot2/ggplot2.pdf

### Vignettes

Another possibility which is closer to an in-depth introduction (but possibly missing some of the package's functions) is given in some packages by the so-called vignettes. They usually deliver an exemplary workflow (and therefore usually explain more than one function at once); vignettes are delivered in html format, and can be viewed externally or in `RStudio`'s *Viewer*; in order to look for all available vignettes (of all packages), call

```{r}
vignette()
```

Read these vignettes by typing `vignette("VIGNETTENAME")`, e.g.
```{r, eval= FALSE}
vignette("dplyr")
```

VIGNETTENAMEs are not necessarily identical to the name of the package.

### The EMU-SDMS-Manual
The best way to get help about emuR is to be found here: 
https://ips-lmu.github.io/The-EMU-SDMS-Manual/index.html

[Next document](http://www.phonetik.uni-muenchen.de/~jmh/lehre/sem/ws1819/emuR/LESSON2/EMU-SDMS-databases.html)