---
title: "Introduction for the TSstudio Package"
author: "Rami Krispin"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## **Overview**

The TSstudio package provides a set of tools for descriptive analysis of a time series data supporting “ts”, “mts”, “zoo” and “xts” objects. That includes rich and interactive visualization plots, based on the engine of the [Plotly](https://plot.ly/r/) package, for seasonality, correlations, residuals, and forecasting performance plots. In addition, the TSstudio package supports the time series visualization functions of the [MLstudio](https://github.com/RamiKrispin/MLstudio) package.


## **Installation**

Install the stable version from [CRAN](https://CRAN.R-project.org/package=TSstudio):
```{r message=FALSE, warning=FALSE, eval=FALSE, echo=TRUE}
install.packages("TSstudio")
```


or install the development version from [Github](https://github.com/RamiKrispin/TSstudio):
```{r message=FALSE, warning=FALSE, eval=FALSE, echo=TRUE}
# install.packages("devtools")
devtools::install_github("RamiKrispin/TSstudio")
```


## **Key Features**

### Visualization of time series objects with the ts_plot function

```{r fig.height=5, fig.width=8 , message=FALSE, warning=FALSE}
library(TSstudio)
library(xts)
library(zoo)
library(quantmod)
# Loading the stock price of key technology companies:
tckrs <- c("GOOGL", "FB", "AAPL", "MSFT")
getSymbols(tckrs, 
           from = "2013-01-01",
           src = "yahoo")

# Visual Google closing price since 2013
Google <- GOOGL$GOOGL.Close
class(Google)

# Basic plot
ts_plot(Google)


# Adding titles and slider
ts_plot(Google, 
        title = "Google Stock Prices Since 2013",
        Xtitle = "Sourch: Yahoo Finance", 
        Ytitle = "Closing Price in USD",
        slider = TRUE
        )


```

#### Available formats

In addition for the “ts” object, the function supports “mts”, “zoo” and “xts” objects, including multiple time series objects: 

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
closing <- cbind(GOOGL$GOOGL.Close, FB$FB.Close, AAPL$AAPL.Close, MSFT$MSFT.Close)
names(closing) <- c("Google", "Facebook", "Apple", "Microsoft")

class(closing)
dim(closing)

# You can plot all the series in one plot using the type option:
ts_plot(closing, 
        title = "Top Technology Companies Stocks Prices Since 2013",
        type = "single")

# or use the default option - "multiple" and plot series on separate plots:
ts_plot(closing,
        title = "Top Technology Companies Stocks Prices Since 2013")

```

### Seasonality analysis

The TSstudio provides a variety of tools for seasonality analysis, currently supporting only monthly or quarterly data. The monthly consumption of natural gas in the US (USgas dataset) is a good example of a seasonal pattern within time series data:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
# Load the US monthly natural gas consumption
data("USgas")

class(USgas)

ts_plot(USgas,
        title = "US Natural Gas Consumption",
        Xtitle = "Year",
        Ytitle = "Billion Cubic Feet"
        )

```

#### The ts_seasonal function

The ts_seasonal function provides 3 types of seasonal plots:

1. "normal" - break of a series by year, this allows identifying a seasonal pattern within the year 

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_seasonal(USgas, type = "normal")

```

2. "cycle" - break of a series by the cycle units (i.e. months or quarters), it can be used to identify trends and patterns between the cycle units:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_seasonal(USgas, type = "cycle")
```

3. "box" - for representing the cycle units with a box plot:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_seasonal(USgas, type = "box")
```


Alternatively, setting the type = “all”, print the three options above together in one plot:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_seasonal(USgas, type = "all")
```

#### The ts_heatmap and ts_surface functions

Another useful visualization tool for seasonality analysis is the ts_heatmap function for time series objects, where the y axis represents the cycle units and x axis represents the years:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_heatmap(USgas)
```

Similarly, the heatmap could be represented by a surface 3d plot:  

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_surface(USgas)
```

#### Polar plot

The ts_polar function provides a polar plot demonstrative of time series data where the year is represented by color and the magnitude is represented by the size of the cycle unit layer:
```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_polar(USgas)
```


#### Decomposing time series

The ts_decompose function transforms the decompose function output(of the stats package) to an interactive format. In addition to the "additive" and the "multiplicative" options of the original decompose function, there is the "both" option which represents both options side by side:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_decompose(USgas, type = "both")
```

### Correlation Analysis

Similarly to the decompose function, the TSstudio transforms the acf and pacf functions into a colorful version with the ts_acf and ts_pacf:

```{r, fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_acf(USgas, lag.max = 36)
ts_pacf(USgas, lag.max = 36)

```

Another intuitive method to identify correlation between the series and its lags is with lag plot:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
ts_lags(USgas)
```


### Applications for forecasting

#### Splitting time series object for training and testing partitions

The TSstudio package provides a set of supporting tools for training and testing forecasting models. The ts_split function splits the series into training and testing partitions based on a given horizon:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
# set the forecast horizon for 12 months
h <- 12

# Split the data into training and testing sets (leaving the last 12 months for testing)
split_USgas <- ts_split(USgas, sample.out = h)

train <- split_USgas$train
test <- split_USgas$test


head(train, 5)
head(test, 5)

```

#### Residuals analysis

The check_res function visualize the traditional plot of the residuals over time, and the corresponding auto correlation function and the histogram (of the residuals):

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
library(forecast)
# Building a model on the training set
fit <- auto.arima(train, lambda = BoxCox.lambda(train))

# Checking the residuals
check_res(fit)

```

#### Forecast evaluation with the test_forecast

The test_forecast function visualizes the fitted values vs the training partition values and the forecasted values vs the testing partitions values. In addition, the tooltip of the plot provides information about the model performance (MAPE and RMSE of the training and testing partitions):

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
fc <- forecast(fit, h = h)

test_forecast(actual = USgas, forecast.obj = fc, test = test)

```

### Other utility tools

#### ts to data frame format

The ts_reshape function transforms time series data ("ts", "zoo" and "xts" classes) into a friendly data frame format using the years as the columns and the cycle units as rows (currently supporting only monthly and quarterly frequencies):

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
# Loading the Total US Vehicle Sales data 
data("USVSales")

ts_plot(USVSales, title = "Total US Vehicle Sales",
        Ytitle = "Thousands of Units",
        Xtitle = "Source: U.S. Bureau of Economic Analysis")

head(ts_plot)

USVSales_df <- ts_reshape(USVSales)

library(DT)

datatable(USVSales_df, filter = 'top', options = list(
  pageLength = nrow(USVSales_df), autoWidth = TRUE
))
```


#### Converting "zoo" or "xts" objects to "ts" class

The xts_to_ts or the zoo_to_ts functions convert "zoo" or "xts" objects into "ts" class:

```{r fig.height=5, fig.width= 8, message=FALSE, warning=FALSE}
# Loading the University of Michigan Consumer Sentiment 
data("Michigan_CS")

Michigan_CS_ts <- xts_to_ts(Michigan_CS)

ts_plot(Michigan_CS, title = "University of Michigan Consumer Sentiment - 'xts' format")
ts_plot(Michigan_CS_ts, title = "University of Michigan Consumer Sentiment - 'ts' format")

class(Michigan_CS)
class(Michigan_CS_ts)

head(Michigan_CS)
head(Michigan_CS_ts)

head(index(Michigan_CS))
head(time(Michigan_CS_ts))

periodicity(Michigan_CS)
frequency(Michigan_CS_ts)


cycle(Michigan_CS_ts)
```




