---
title: "Introduction to R"
author: "Emanuele Guidotti"
output:
  html_document:
    highlight: zenburn
    self_contained: no
    theme: yeti
    toc: yes
    toc_float: yes
  pdf_document:
    toc: yes
  word_document:
    toc: yes
---

```{css, echo = FALSE}
@media (max-width: 768px) {
 pre code, pre, code {
    white-space: pre !important;
    overflow-x: scroll !important;
    word-break: keep-all !important;
    word-wrap: initial !important;
  } 
}
```

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE, message = FALSE, cache = TRUE)
options(knitr.kable.NA = '')
Sys.setenv(LANG = "en")
set.seed(123)
```

# Quick Start

In this introduction to R, the reader will master the basics of this beautiful open source language with hands-on experience. With over 2 million users worldwide R is rapidly becoming the leading programming language in statistics and data science. Every year, the number of R users grows by 40% and an increasing number of organizations are using it in their day-to-day activities.

## Installation

Download and install __R__ at [this link](https://cloud.r-project.org/)

Download and install __Rstudio__ (free version) at [this link](https://www.rstudio.com/products/rstudio/download/)


## Comments

All text after the sign `#` within the same line is considered a comment.
```r
# this is a comment
this is NOT a comment 
```

## Variable Assignment

Values can be assigned to variables with the operators `<-`, `=` or `->`. 
```r
# assign 1 to variable x
x <- 1
# or
x = 1
# or
1 -> x
```

## Functions
R functions are invoked by their name, then followed by the parenthesis, and zero or more arguments. 
```r
# summing 1+2+3+4+5
sum(1,2,3,4,5)
```


## Extension Packages

Additional functionality beyond those offered by the core R library are available with R packages. In order to install an additional package, the `install.packages` function can be invoked. 

```r
# install the "xts" package
install.packages('xts')
```
There are two ways to invoke functions from add-on packages: using the package namespace or loading the package.

```r
# using the namespace. 
# Invoke the function as package_name::function_name
xts::is.xts(1)

# loading the package with the 'require' function.
# This makes its functions available without using namespaces
require(xts)
is.xts(1)
```

## Help

R provides extensive documentation. Enter `?function_name` to access the documentation of a function.
```r
# examples
?sum   
?mean
?rnorm
```

# Basic Data Types

There are several basic R data types that are of frequent occurrence in routine R calculations.

## Numeric

Decimal values are called numerics in R. It is the default computational data type. If a decimal value is assigned 
to a variable `x` as follows, `x` will be of __numeric__ type. 
```{r, message=TRUE}
x <- 10.5 # assign a decimal value 
class(x)  # class of x
```
Furthermore, even if an integer is assigned to a variable `x`, it is still being saved as a numeric value.
```{r, message=TRUE}
x <- 10        # assign an integer value 
is.integer(x)  # is integer?
```

## Integer

In order to create an integer variable in R, the `as.integer` function can be invoked.
```{r, message=TRUE}
x <- as.integer(10) # assign an integer data type 
is.integer(x)       # is integer?
```

Integers can also be declared by appending an `L` suffix.
```{r, message=TRUE}
x <- 10L       # assign an integer data type 
is.integer(x)  # is integer?
```

## Logical

A logical value is often created via comparison between variables.
```{r, message=TRUE}
x <- 2 > 1    # is 2 greater than 1? 
x
```
Standard logical operations are `&` (and), `|` (or), and `!` (negation).

```{r}
u <- TRUE
v <- FALSE 
```

```{r, message=TRUE}
u & v  
u | v  
!u     
```



## Character

A character object is used to represent string values in R. Two character values can be concatenated with the `paste` function.
```{r, message=TRUE}
address <- 'example'
domain <- 'gmail.com'
paste(address, domain, sep = '@')
```
However, it is often more convenient to create a readable string with the `sprintf` function, which has a C language syntax.
```{r, message=TRUE}
sprintf("%s has %d dollars", "Sam", 100) 
```
And to replace the first occurrence of the word "little" by another word "big" in the string, the `sub` function can be applied.
```{r, message=TRUE}
sub("little", "big", "Mary has a little lamb.") 
```
More functions for string manipulation can be found in the R documentation.
```r
?sub
```
# Basic Data Structures 

## Vector

The basic data structure in R is the vector. They are usually created with the `c()` function, short for combine:
```{r, message=TRUE}
c(1,2,3)
```

### Named Vector

```{r, message=TRUE}
# Declaring a named vector   
c('first' = 1, 'second' = 2, 'third' = 3)
```
```{r, message=TRUE}
# Generating a named vector
x <- c(1,2,3)                       # vector 
n <- c('first','second','third')    # vector of names
names(x) <- n                       # assign names 
x                                   
```


## Matrix

A matrix is a collection of data elements arranged in a two-dimensional rectangular layout. They are usually created with the `matrix()` function:
```{r, message=TRUE}
matrix(data = c(1,2,3,4,5,6), # the data elements
       ncol = 3,              # number of columns
       nrow = 2,              # number of rows
       byrow = TRUE)          # fill matrix by rows
```

### Named Matrix
```{r, message=TRUE}
# Declaring a named matrix
matrix(data = c(1,2,3,4,5,6), # the data elements
       ncol = 3,              # number of columns
       nrow = 2,              # number of rows
       byrow = TRUE,          # fill matrix by rows
       dimnames = list(       # list containing names
         c('r1','r2'),           # rownames
         c('c1','c2','c3')       # colnames
       ))
```
```{r, message=TRUE}
# Generating a named matrix
M <- matrix(data = c(1,2,3,4,5,6), # the data elements
            ncol = 3,              # number of columns
            nrow = 2,              # number of rows
            byrow = TRUE)          # fill matrix by rows
rn <- c('r1','r2')       # vector of rownames
cn <- c('c1','c2','c3')  # vector of colnames
rownames(M) <- rn        # assign rownames
colnames(M) <- cn        # assign colnames
M
```

## Data Frame

A data frame is used for storing data tables. It is a list of vectors of equal length. They are usually created with the `data.frame()` function. Beware `data.frame()`'s default behaviour which turns strings into factors (a factor is a vector that can contain only predefined values, and is used to store categorical data). Use `stringsAsFactors = FALSE` to suppress this behaviour:
```{r, message=TRUE}
v1 <- c(10,20,30)                                # numeric vector
v2 <- c('a','b','c')                             # character vector
v3 <- c(TRUE,TRUE,FALSE)                         # logical vector
data.frame(v1, v2, v3, stringsAsFactors = FALSE) # data.frame
```

### Named Data Frame

```{r, message=TRUE}
# Declaring a named data.frame
v1 <- c(10,20,30)                           # numeric vector
v2 <- c('a','b','c')                        # character vector
v3 <- c(TRUE,TRUE,FALSE)                    # logical vector
data.frame('c1' = v1,                       # column named 'c1'
           'c2' = v2,                       # column named 'c2'
           'c3' = v3,                       # column named 'c3'
           row.names = c('r1', 'r2', 'r3'), # vector of rownames
           stringsAsFactors = FALSE)        # suppress character conversion
```
```{r, message=TRUE}
# Generating a named data.frame
v1 <- c(10,20,30)                                       # numeric vector
v2 <- c('a','b','c')                                    # character vector
v3 <- c(TRUE,TRUE,FALSE)                                # logical vector
rn <- c('r1','r2','r3')                                 # vector of rownames
cn <- c('c1','c2','c3')                                 # vector of colnames
df <- data.frame(v1, v2, v3,stringsAsFactors = FALSE)   # data.frame
rownames(df) <- rn                                      # assign rownames
colnames(df) <- cn                                      # assign colnames
df
```



## List

A list is the most generic structure containing other objects. They are usually created with the `list()` function:
```{r, message=TRUE}
list(matrix(100), 
     data.frame(1,2,3), 
     c('a','b','c','d'))
```


### Named List

```{r, message=TRUE}
# Declaring a named list
list('matrix' = matrix(100),           # matrix
     'data.frame' = data.frame(1,2,3), # data.frame
     'vector' = c('a','b','c','d'))    # vector
```
```{r, message=TRUE}
# Generating a named list
M <- matrix(100)                       # matrix
df <- data.frame(1,2,3)                # data.frame
v <- c('a','b','c','d')                # vector
n <- c('matrix','data.frame','vector') # vector of names
l <- list(M, df, v)                    # list
names(l) <- n                          # assign names
l
```


# Basic Operations

## Subsetting

### Vector

Values in a `vector` are retrieved by using the single square bracket `[]` operator. 
```{r,message=TRUE}
s = c("aaa"="a", "bbb"="b", "ccc"="c", "ddd"="d", "eee"="e") 
s # print the full vector
```
```{r, message=TRUE}
# retrieve the 3rd element
s[3]
# drop the 3rd element
s[-3]
# out-of-range returns NA
s[10]
# retrieve the 2nd, 3rd, 5th and 5th element
i <- c(2,3,5,5)
s[i]
# drop the 1st and 3rd element
i <- c(1,3) 
s[-i]
# retrieve the elements named 'ddd' and 'bbb'
i <- c('ddd','bbb')
s[i]
# retrieve the 3rd element using a logical vector
i <- c(FALSE,FALSE,TRUE,FALSE,FALSE) 
s[i]
# the logical vector will be recycled if it is shorter than the vector to subset
i <- c(FALSE,TRUE)  # ->  c(FALSE,TRUE,FALSE,TRUE,FALSE)
s[i]
# select elements greater than 'b'
i <- s > 'b'
s[i]
```

### Matrix

Values in a `matrix` are retrieved by using the single square bracket `[]` operator. 

```{r,message=TRUE}
M <- matrix(1:12, nrow = 3, ncol = 4, byrow = TRUE) 
rownames(M) <- c('r1','r2','r3')
colnames(M) <- c('c1','c2','c3','c4')
M # print the full matrix
```
```{r,message=TRUE}
# retrieve the element in 2nd row, 3rd column
M[2,3]
# retrieve the 1st row
M[1,]
# retrieve the 1st column
M[,1]
# retrieve the 2nd and 3rd row
i <- c(2,3)
M[i,]
# drop the 1st and 3rd column
i <- c(1,3) 
M[,-i]
# retrieve the elements in 1st and 3rd row, 2nd and 4th column
M[c(1,3),c(2,4)]
# retrieve the rows named 'r1' and 'r3'
i <- c('r1','r3')
M[i,]
# retrieve the columns named 'c2' and 'c4'
i <- c('c2','c4')
M[,i]
# retrieve the 3rd row of the columns named 'c2' and 'c4'
i <- c('c2','c4')
M[3,i]
# retrieve the 1st row using a logical vector
i <- c(TRUE,FALSE,FALSE) 
M[i,]
# the logical vector will be recycled if it is shorter than the number of rows/columns to subset
i <- c(TRUE,FALSE)  # ->  c(TRUE,FALSE,TRUE)
M[i,]
# select the column named 'c4' where 'c3' is less than twice 'c1' 
i <- M[,'c3'] < 2*M[,'c1']
M[i,'c4']
```

### Data Frame

Values in a `data.frame` are retrieved by using the single square bracket `[]` operator as done in a `matrix` object (see above). Here, also the `$` or `[[]]` operators can be used to retrieve columns.
```{r,message=TRUE}
df <- data.frame('age' = c(48,18,51), 'sex' = c('M','F','M'))
df # print full data.frame
```
```{r,message=TRUE}
# retrieve the "age" column
df$age               # equivalent to df[["age"]] or df[,"age"]
# retrieve the age of males ("M")
i <- df$sex == "M"   # equivalent to df[["sex"]]=="M" or df[,"sex"]=="M"  
df$age[i]            # equivalent to df[["age"]][i] or df[i,"age"] 
```

### List

A list is subsetted using the single square bracket `[]` operator.

```{r,message=TRUE}
l <- list(
  'data' = data.frame('age' = c(48,18,51), 'sex' = c('M','F','M')),
  'letters' = c('a','b','c'),
  'extra' = c(1:5)
) 
l # print full list
```
```{r, message=TRUE}
# select the 1st and 3rd elements
i <- c(1,3)
l[i]
# select the elements named "extra" and "letters"
i <- c("extra","letters")
l[i]
# drop the "extra" element
l["extra"] <- NULL
l
```
Objects in a `list` are retrieved by using the operator `[[]]` or `$`.
```{r, message=TRUE}
# extract the 2nd object
l[[2]]
# extract the "data" object
l$data   # equivalent to l[["data"]]
```

## Arithmetics

Arithmetic operations of __vectors__ and __matrices__ are performed element-by-element, __data.frames__ are treated as __matrices__ when containing only numeric elements. If two vectors are of unequal length, the shorter one will be recycled in order to match the longer vector. For example, the following vectors `u` and `v` have different lengths, and their sum is computed by recycling values of the shorter vector `u`.
```{r, message=TRUE}
u <- c(10, 20, 30) 
v <- c(1, 2, 3, 4, 5, 6, 7, 8, 9) 
M <- matrix(c(1, 2, 3, 4, 5, 6, 7, 8, 9), ncol = 3, nrow = 3, byrow = TRUE)

# vector + vector
u + v
# vector + 1
u + 1
# vector * 2
u * 2
# matrix + 1 
M + 1
# matrix + vector
M + u
# matrix + matrix
M + M
# matrix * vector 
M * u
# matrix product (rows x columns)
M %*% u
```

# Extra

## Custom Functions

Abstracting code into many small functions is key for writing nice R code. Functions are defined by code with a specific format:
```{r}
function.name <- function(arg1, arg2, arg3=NULL, ...) {
  # code here...
  return(...)  
}
```
where

- `function.name`: the name of the function
- `arg1`, `arg2`, `arg3`, `...`: input values
- `arg3=NULL`: default value. If `arg3` is not provided when calling the function, `NULL` will be used instead
- `return()`: the output value

Define a function to compute the sum of the first `n` integer numbers.
```{r}
sum.int <- function(n){
  s <- sum(1:n)
  return(s)
}
```
Compute the sum of the first 10 integers
```{r, message=TRUE}
sum.int(10)
```
Define a function to compute the `p` norm of a vector `x`. By default, compute the Euclidean norm (`p = 2`). 
```{r}
norm <- function(x, p = 2){
  d <- sum(x^p)^(1/p)
  return(d)
}
```
Compute the Euclidean norm of the vector `c(1,1)`
```{r, message=TRUE}
norm(x = c(1,1))  # equivalento to norm(x = c(1,1), p = 2)
```
Compute the 3-norm of the vector `c(1,1)`
```{r, message=TRUE}
norm(x = c(1,1), p = 3) 
```
Compute the $\infty$-norm of the vector `c(1,1)`
```{r, message=TRUE}
norm(x = c(1,1), p = Inf) 
```
## Time Series 

### Time Index

A time series is a series of data points indexed in time order. In R, all data types for which an order is defined can be used to index a time series. If the operator `<` is defined for a data type, then the data type can be used to index a time series.

__Date__
```{r, message=TRUE}
today <- Sys.Date()     # current Date
yesterday <- today - 1  # subtract 1 day 
yesterday < today       # the order is defined for Date
```
__POSIXct__
```{r, message=TRUE}
now <- Sys.time()       # current time 
ago <- now - 3600       # subtract 3600 seconds 
ago <  now              # the order is defined for POSIXct 
```
__Character__
```{r, message=TRUE}
'a' < 'b'               # the order is defined for character
```
__Numeric__
```{r, message=TRUE}
1 < 2                   # the order is defined for numeric
```
__Complex__
```{r, error=TRUE}
2+0i < 1+3i             # the order is NOT defined for complex 
```


### The 'zoo' Package

The `zoo` package consists of the methods for totally ordered indexed observations. All indexes discussed above can be used. The package aims at performing calculations containing irregular time series of numeric vectors, matrices and factors. The package is an infrastructure that tries to do all basic things well, but it doesn't provide modeling functionality. 
```r
# install the package 
install.packages('zoo') 
```
```{r}
# load the package
require(zoo)            
```
The below set of exercises shows some of zoo concepts.

__Declaration__
```{r, message=TRUE}
# create a unidimensional zoo object indexed by default
zoo(x = c(100,123,43,343,22))
# create a unidimensional zoo object indexed by numeric
x <- c(100, 123, 43, 343, 22)
i <- c(0, 0.2, 0.4, 0.5, 1)
zoo(x = x, order.by = i)
# create a unidimensional zoo object indexed by character
x <- c(100, 123, 43, 343, 22)
i <- c('z', 'b', 'd', 'c', 'a')
zoo(x = x, order.by = i)
# create a multidimensional zoo object indexed by Date
x <- data.frame('price' = c(100,99.3,100.2), 'volume' = c(9.9,1.3,3.6))
i <- as.Date(c('2018/01/01', '2018/02/23', '2018/05/01'), format = "%Y/%m/%d")
zoo(x = x, order.by = i)
# create a multidimensional zoo object indexed by POSIXct
x <- data.frame('price' = c(100,99.3,100.2), 'volume' = c(9.9,1.3,3.6))
i <- as.POSIXct(c('20180101 120631', '20180223 085145', '20180501 182309'), format = "%Y%m%d %H%M%S")
zoo(x = x, order.by = i)
```
__Manipulation__
```{r, message=TRUE}
# assign colnames
x <- data.frame(c(100,99.3,100.2), c(9.9,1.3,3.6)) 
z <- zoo(x = x)                                   
colnames(z) <- c('p','v')                          
z
# assign indexes
index(z) <- as.Date(c('2018/01/01', '2018/02/23', '2018/05/01'), format = "%Y/%m/%d") 
z
# starting index
start(z) 
# ending index
end(z)   
# select specific indexes
i <- as.Date(c('2018-01-01', '2018-05-01'))
z[i]
# select specific columns
z$p                # equivalent to z[,'p']
# change the 2nd observation 'p' value
z$p[2] <- 105      # equivalent to z[2,'p'] <- 105
z
# subset the series
window(z, start = '2018-01-01', end = '2018-03-1')
# increments
diff(z) 
# lag the series
lag(z, k = 1)      # shift the time base back 
# lag the series
lag(z, k = -1)     # shift the time base forward 
# merge series
z.next   <- lag(z, k =  1)  
z.prev   <- lag(z, k = -1)  
z.merged <- merge(z, z.next, z.prev) 
z.merged
# handle missing data. Approx with previous non-NA value
na.locf(z.merged)
# handle missing data. Approx with next non-NA value
na.locf(z.merged, fromLast = TRUE)
# handle missing data. Drop NA
z.merged[complete.cases(z.merged),]
```
__Arithmetic__ operations are performed element-by-element on matching indexes of the two zoo obejcts. If the operation involves a zoo and a vector object, then the operation is performed on the whole zoo object.
```{r, message=TRUE}
x <- matrix(101:112, nrow = 3, ncol = 4, byrow = TRUE)
z <- zoo(x)
# add 1 to the whole series
z + 1
# multiply the first observation by 0, the second one by 1 and the third one by 2
z * c(0,1,2)
# compute the increments
z - lag(z, -1)  # equivalent to diff(z)
# compute the percentage increments
z / lag(z, -1) - 1
# compute the rolling mean on a 2-observation window 
rollapply(z, width = 2, FUN = mean)  
```


### The 'xts' Package

The `xts` package provides an extensible time series class, enabling uniform handling of many R time series classes by extending `zoo`. An `xts` object can be indexed by the `Date`, `POSIXct`, `chron`, `yearmon`, `yearqtr`, `DateTime` data types but not by `numeric` or `character`.

```r
# install the package 
install.packages('xts') 
```
```{r}
# load the package
require(xts)            
```
The methods seen for `zoo` objects can be applied to `xts`. The below set of exercises shows some of additional xts specific concepts.
```{r, message=TRUE}
# create an xts object         
dates <- seq(as.Date("2017-05-01"), length=1000, by="day")          # generate a sequence of dates
data  <- c(price = cumprod(1+rnorm(1000, mean = 0.001, sd = 0.01))) # generate some random data
x <- xts(x = data, order.by = dates)                                # create the xts object
colnames(x) <- 'price'                                              # assign colnames
head(x)                                                             # print the first observations
# change format of time display
indexFormat(x) <- "%Y/%m/%d"                                        
head(x)
# estimate frequency of observations
periodicity(x)
# first observation
first(x)
# last observation
last(x)
# first 3 days of the last week of data
first(last(x, '1 week'), '3 days') 
# convert to OHLC
# valid periods are "seconds", "minutes", "hours", "days", "weeks", "months", "quarters","years"
x.ohlc <- to.period(x, period = 'quarters')
head(x.ohlc)
# calculate the yearly mean 
ep <- endpoints(x.ohlc, on = "years")          
period.apply(x.ohlc , INDEX = ep, FUN = mean)  
```








# Code Download

Download the full code to generate this document and reproduce the examples. The file is in [R Markdown](https://rmarkdown.rstudio.com/), format for making dynamic documents with R. An R Markdown document is written in markdown, an easy-to-write plain text format, and contains chunks of embedded R code. \
[Download](https://storage.googleapis.com/emanueleguidotti/R/introduction-to-R.Rmd) 


__Exercise__: create the pdf version of this web page \
__Hint__: download the file above and have a look at the introductory 1-min video of the [official Rmarkdown guide](https://rmarkdown.rstudio.com/lesson-1.html)


Find more R tutorials [here](https://emanueleguidotti.dev/category/r-tutorials/)

[_by [Emanuele Guidotti](https://emanueleguidotti.dev)_]{style="float:right"}