---
title: "Basic Time Series Copula Processes"
author: "Alexander J. McNeil and Martin Bladt"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Basic Time Series Copula Processes}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(tscopula)
```
This library currently implements 3 basic kinds of time series copula process: ARMA copula processes and d-vine copula processes of type 1 and type 2. These are described in the next 3 sections.

## 1. ARMA Copula Processes

### AR(1) Example
An ARMA copula is specified by a list of two vectors, the first named `ar` and the second `ma`. The following example creates an AR(1) copula process specification and then displays the spec.

```{r setup-tscopula}
ar1 <- armacopula(list(ar = 0.7))
ar1
```

A realization can be generated with the generic command `sim`.

```{r simulate-copula, fig.show='hold', fig.width = 6, fig.height = 3, dev.args =list(pointsize=9)}
set.seed(13)
data1 <- sim(ar1, 1000)
ts.plot(data1)
```

A model specification can be fitted to data with the generic command `fit`.

```{r fit-copula}
ar1spec <- armacopula(list(ar = 0))
ar1fit <- fit(ar1spec, data1)
ar1fit
```

### ARMA(1,1) Example

The next example simulates and fits an ARMA(1,1) copula process, giving standard errors for the parameter estimates.

```{r arma11example, fig.show='hold', fig.width = 6, fig.height = 3, dev.args =list(pointsize=9)}
arma11 <- armacopula(list(ar = 0.95, ma = -0.85))
data2 <- sim(arma11, 1000)
ts.plot(data2)

arma11spec <- armacopula(list(ar = 0.1, ma = 0.1))
arma11fit <- fit(arma11spec, data2, tsoptions = list(hessian = TRUE))
arma11fit
```

Coefficients of the fitted model are obtained with the command `coef`, residuals with the command `resid` and various plots are generated by the generic command `plot`. 

```{r arma11plots, fig.show='hold'}
coef(arma11fit)
res <- resid(arma11fit)
acf(res)
acf(abs(res))
plot(arma11fit)
plot(arma11fit, plottype = "kendall")
mu_t <- resid(arma11fit, trace = TRUE)
ts.plot(mu_t)
```

The data for these plots come from applying the Kalman filter command `kfilter`.
```{r kalman}
head(kfilter(arma11fit@tscopula, data2))
```

## 2. D-Vine Copula Processes (type 1)

### Construction

We construct a copula of order $p = 3$ in which the copulas are respectively Clayton, Frank, and Gauss. The parameters are given in a list. Individual copulas can be rotated through 180 degrees.

```{r dvinecopula-setup}
copmod <- dvinecopula(
  family = c("Clayton","Frank", "Gaussian"),
  pars = list(1.2, 2, 0.15),
  rotation = c(180,0, 0)
)
copmod
```

### Simulation

A realization can be generated with the generic command `sim`.

```{r dvinecopula-sim, fig.show='hold', fig.width = 6, fig.height = 3, dev.args =list(pointsize=9)}
set.seed(29)
data1 <- sim(copmod, n = 2000)
hist(data1)
ts.plot(data1)
```

### Estimation 

A model spec can be fitted to data with the generic command `fit`.

```{r dvinecopula-est}
copspec <- dvinecopula(
  family = c("Clayton","Frank", "Gaussian"),
  pars = list(0.5, 1, 0),
  rotation = c(180, 0, 0)
)
copfit <- fit(copspec, data1, 
              tsoptions = list(hessian = TRUE),
              control = list(maxit = 2000))
copfit
coef(copfit)
coef(copmod)
```

### Plotting

Various plots are generated by the generic command `plot`. 

```{r dvinecopula-fit, fig.show='hold', dev.args =list(pointsize=9)}
plot(copfit)
plot(copfit, plottype = "kendall")
```

Here is the generalized lag plot.

```{r genlagplot, fig.show='hold', fig.width = 6, fig.height = 6, dev.args =list(pointsize=9)}
plot(copfit, plottype = "glag")
```

## 3. D-Vine Copula Processes (type 2)

### Construction

We construct a model using the Joe copula and the Kendall partial autocorrelation function (KPACF) of a Gaussian ARMA process with autogressive (ar) parameter 0.9 and moving average (ma) parameter -0.85. The KPACF is truncated at lag 20, so this is a process of finite order. We can also set $\text{maxlag} = \inf$ but this leads to much slower simulation.

```{r dvinecopula2-setup}
copmod <- dvinecopula2(family = "joe",
                       kpacf = "kpacf_arma",
                       pars = list(ar = 0.9, ma = -0.85),
                       maxlag = 20)
copmod
```

### Simulation

A realization can be generated with the generic command `sim`.

```{r dvinecopula2-sim, fig.show='hold', fig.width = 6, fig.height = 3, dev.args =list(pointsize=9)}
set.seed(13)
data1 <- sim(copmod, n = 2000)
hist(data1)
ts.plot(data1)
```

### Estimation 

A model spec can be fitted to data with the generic command `fit`.

```{r dvinecopula2-est}
copspec_Gauss <- dvinecopula2(family = "gauss",
                              pars = list(ar = 0, ma = 0),
                              maxlag = 20)
fitGauss <- fit(copspec_Gauss, data1)
fitGauss

copspec_Joe <- dvinecopula2(family = "joe",
                            pars = list(ar = 0, ma = 0),
                            maxlag = 20)
fitJoe <- fit(copspec_Joe, data1)
fitJoe

AIC(fitGauss, fitJoe)
```

### Plotting

Various plots are generated by the generic command `plot`. 

```{r dvinecopula2-plot, fig.show='hold', dev.args =list(pointsize=9)}
plot(fitJoe)
plot(fitJoe, plottype = "kendall")
```