shortintro.Rmd

---
title: "PUcopula"
author: "Andreas Mändle (University of Bremen)"
date: "`r Sys.Date()`"
output: pdf_document
---

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

## Short introduction to the PUcopula R-package

In this short introduction it will be shown how to use the PUcopula package. The following examples are based on:

*[1] Pfeifer, D., Mändle, A. & Ragulina, O., New copulas based on general partitions-of-unity and their applications to risk
management (part II). Dependence Modeling
(2017), 246 – 255. https://doi.org/10.1515/demo-2017-0014 *

### Install

So far the package *PUcopula* is not available on CRAN, but the development version can be installed from GitHub using the *install_github* function from the package *devtools*:

```{r, message=FALSE, warning=FALSE, eval=F}
library(devtools)
install_github("amaendle/PUcopula")
```

### Load the package

```{r, message=FALSE}
library(PUcopula)
```

In the following examples the data from the paper

*[2] Cottin, C. & Pfeifer, D. (2014)., From Bernstein polynomials to Bernstein copulas, Journal of
Applied Functional Analysis (2014), 277 – 288*

are considered. The data can be accessed directly from the package:
```{r, fig.width=3.4, fig.height=3.8, fig.align='center'}
data("stormflood")
# plot the data using R's plot function:
plot(stormflood, sub="Stormflood data from [2]", xlab="", ylab="", pch=4, col="red", lwd=2)
```

### Example: The NB-copula

At first a copula model has to be created:

```{r}
x <- PUCopula(family="nbinom", pars.a=c(40, 43), patch="lFrechet",data=stormflood)
```

This creates a copula model for a (asymmetric) NB-copula with parameters 40 and 43 with a lower Fréchet copula driver fitted to the stromflood data.

The above defined object can now be used to simulate from the above NB-copula model:

```{r, fig.width=3.4, fig.height=3.8, fig.align='center'}
sampledata <- x@rand(200)
plot(sampledata, sub="Simulations using lower Fréchet driver", xlab="", ylab="")
points(x@relRanks, xlab="", ylab="", pch=4, col="red", lwd=2)
```



Negative binomial copulas (see Examples 2 and 5) can easily be simulated through the alternative
representation formula (2) involving mixed Beta distributions here. 

Poisson copulas can be simulated using the transformation $z\mapsto 1-e^{-z}$ applied to Gamma distributed random variables Z with a random shape parameter $\alpha$ where $\alpha-1$ is generated by the geometric distribution shown in (7), and scale parameter $1+\gamma$.

### Example: The Poisson-copula

Create the Poisson-copula model has to be created:

```{r}
x <- PUCopula(family="poisson", pars.a=c(17, 17), patch="rook",data=stormflood)
```

Simulations with using a rook copula driver:

```{r, fig.width=3.4, fig.height=3.8, fig.align='center'}
sampledata <- x@rand(200)
plot(sampledata, sub="Poisson copula with rook copula driver", xlab="", ylab="")
points(x@relRanks, xlab="", ylab="", pch=4, col="red", lwd=2)
```

### Example: The Gamma-copula

At first a copula model has to be created:

```{r}
x <- PUCopula(family="gamma", pars.a=c(15, 15), patch="uFrechet",data=stormflood)
```

Simulations using an upper Fréchet copula driver:

```{r, fig.width=3.4, fig.height=3.8, fig.align='center'}
sampledata <- x@rand(200)
plot(sampledata, sub="Gamma copula with upper Fréchet driver", xlab="", ylab="")
points(x@relRanks, xlab="", ylab="", pch=4, col="red", lwd=2)
```

### Further help

The documentation of the package with further details is available via:

```{r, message=FALSE, echo=T, eval=FALSE, warning=FALSE, error=FALSE}
help("PUCopula")
```

Consider that the package is under development. Some of the functions included in the package might not work as expected. For further questions regarding the package contact maendle@uni-bremen.de.