---
title: "Plotting Time Series Data"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Plotting Time Series Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r, include = FALSE}
knitr::opts_chunk$set(
fig.width=8, 
fig.height=5,
collapse = TRUE,
comment = "#>"
)
```

## The ts_plot function

The plotting of time series object is most likely one of the steps of the analysis of time-series data. The \code{\link[TSstudio]{ts_plot} is a customized function for plotting time series data based on the [plotly](https://plotly.com/r/) package visualization engine. It supports the following time-series classes:

* ts
* mts
* zoo
* xts
* data.frame^1^ 
* tbl^1^ 

^1^ Must have a `Date` or `POSIXct/lt` column and at least on numeric column

For example let's load and plot the `USgas` series, a `ts` object:

```{r setup}
library(TSstudio)
```

```{r message=FALSE, warning=FALSE}
data(USgas)

ts_info(USgas)

ts_plot(USgas)
```

## Customization options

It is straightforward to customize the plot using the different arguments of the ts_plot function

### Adding titles

By default, the function sets the series name as the plot title. The `title` allows you to modify the plot title and the `Xtitle` and `Ytitle` enable you to add titles to the X-axis and Y-axis respectively:

```{r}
ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet")
```

### Adding slider

The `slider` argument allows you to add a slider on the bottom of the plot, which will enable you to customize the window length of the plot:

```{r}
ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet",
        slider = TRUE)
```


### Customize the line 

The `color`, `width`  arguments allow you to customize the line's color and width of the plot:

```{r}
ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet",
        color = "black",
        width = 3)
```

The `dash` argument enables to create a dashed or dotted line (as opposed to the default setting of a solid line):

```{r}
ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet",
        dash = "dash")
```

The `line.mode` enables to add to the solid line markers (by setting it to `lines+markers`) or just replace the solid one with markers (by setting it to `markers`):


```{r}
ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet",
        line.mode =  "lines+markers")
```



## Advance customization

The `ts_plot` is a wraper of the **plotly** package plotting functions for time series objects, therefore, the output of the `ts_plot` is a `plotly` object:

```{r}
class(ts_plot(USgas))
```


Advance customization of the `ts_plot` output can be done with plotly's `layout` function. For example, let's replot the `USgas` series and customize the background to black:

```{r message=FALSE, warning=FALSE}
library(plotly)

ts_plot(USgas,
        title = "US Monthly Natural Gas Consumption",
        Xtitle = "Time",
        Ytitle = "Billion Cubic Feet",
        color =  "pink",
        Xgrid = TRUE,
        Ygrid = TRUE) %>%
  layout(paper_bgcolor = "black",
         plot_bgcolor = "black",
         font = list(color = "white"),
         yaxis = list(linecolor = "#6b6b6b",
                      zerolinecolor = "#6b6b6b",
                      gridcolor= "#444444"),
         xaxis = list(linecolor = "#6b6b6b",
                      zerolinecolor = "#6b6b6b",
                      gridcolor= "#444444"))
```

**Note** that the `Xgrid` and `Ygrid` arguments, when set to `TRUE`, add the corresponding X and Y grid lines.


### Plotting multiple time series object

The plotting of a multiple time series object is straightforward.  Let's load the `Coffee_Prices` an `mts` object that represents the monthly prices of the Robusta and Arabica coffee prices (USD per Kg.):

```{r}
data("Coffee_Prices")

ts_info(Coffee_Prices)
```


```{r}
ts_plot(Coffee_Prices)
```

By default, the function will plot all the series in one plot. Plotting the different series on a separate plot can be done by setting the `type` argument to `multiple`:

```{r}
ts_plot(Coffee_Prices,
        type = "multiple")
```

**Note** that the `color`, `Ytitle`, and `Xtitle` arguments are not applicable when plotting multiple time series object.

## Working with other time series class

Working with other types of time series classes following the execute same process as the one demonstrated with the ts object above. 

The main advantage of plotting time series objects such as `xts`, `zoo`, `data.frame` and now `tsibble`, is that their index is more readable (e.g., support Date and other time classes).

### Plotting zoo and xts objects

Let's load the University of Michigan consumer sentiment index:

```{r}
data("Michigan_CS")

ts_info(Michigan_CS)
```


```{r}
ts_plot(Michigan_CS)
```

### Plotting data.frame object

Plotting `data.frame` or `tbl` objects must follow the following structure:

* Have a `Date` or `POSIXct/lt` column
* At least one numeric column

For example, let's convert the USgas series to `data.frame` with the `ts_to_prophet` function:

```{r}
USgas_df <- ts_to_prophet(USgas)

str(USgas_df)


ts_plot(USgas_df)
```