-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
executable file
·203 lines (149 loc) · 6.95 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
---
output: github_document
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "inst/README-"
)
```
kdecopula
=========
[](https://travis-ci.org/tnagler/kdecopula)
[](https://ci.appveyor.com/project/tnagler/kdecopula)
[](https://codecov.io/github/tnagler/kdecopula?branch=master)
[](https://cran.r-project.org/package=kdecopula)
[](https://cran.r-project.org/package=kdecopula)
[](http://www.gnu.org/licenses/gpl-3.0)
This package provides fast implementations of kernel estimators for the copula
density. Due to its several plotting options it is particularly useful for the
exploratory analysis of dependence structures. It can be further used for flexible
nonparametric estimation of copula densities and resampling.
For detailed documentation, see the
[package vignette](https://arxiv.org/pdf/1603.04229.pdf) and the
[API documentation](https://tnagler.github.io/kdecopula/reference/index.html).
## Table of contents
- [How to install](#how-to-install)
- [Functions](#functions)
- [kdecopula in action](#kdecopula-in-action)
- [Estimation of bivariate copula densities](#estimation-of-bivariate-copula-densities)
- [Plotting bivariate copula densities](#plotting-bivariate-copula-densities)
- [Working with a kdecopula object](#working-with-a-kdecopula-object)
- [References](#references)
----------------------------------------------------------------
## How to install
You can install:
* the stable release on CRAN:
``` r
install.packages("kdecopula")
```
* the latest development version:
``` r
devtools::install_github("tnagler/kdecopula")
```
## Functions
The package provides the following functions:
* `kdecop`: Kernel estimation of a copula density. By default, estimation
method and bandwidth are selected automatically. Returns an object of class
`kdecopula`.
* `dkdecop`: Evaluates the density of a `kdecopula` object.
* `pkdecop`: Evaluates the distribution function of a `kdecopula` object.
* `rkdecop`: Simulates synthetic data from a `kdecopula` object.
* Methods for class `kdecopula`:
* `plot`, `contour`: Surface and contour plots of the density estimate.
* `print`, `summary`: Displays further information about the density
estimate.
* `logLik`, `AIC`, `BIC`: Extracts fit statistics.
See the [package documentation](https://cran.r-project.org/web/packages/kdecopula/kdecopula.pdf)
for more details on arguments and options.
----------------------------------------------------------------
## kdecopula in action
```{r echo = FALSE}
set.seed(2)
```
Below, we demonstrate the main capabilities of the `kdecopula`
package. All user-level functions will be introduced with small examples.
Let's consider some variables of the *Wiscon diagnostic breast cancer* data
included in this package. The data are transformed to pseudo-observations of
the copula by the empirical probability integral/rank transform:
```{r fig.width=4, fig.height=4}
library(kdecopula)
data(wdbc) # load data
u <- apply(wdbc[, c(2, 8)], 2, rank) / (nrow(wdbc) + 1) # empirical PIT
plot(u) # scatter plot
```
We see that the data are slightly asymmetric w.r.t. both diagonals. Common
parametric copula models are usually not flexible enough to reflect this. Let's
see how a kernel estimator does.
#### Estimation of bivariate copula densities
We start by estimating the copula density with the `kdecop` function. There is
a number of options for the smoothing parameterization, estimation method and
evaluation grid, but it is only required to provide a data-matrix.
```{r}
kde.fit <- kdecop(u) # kernel estimation (bandwidth selected automatically)
summary(kde.fit)
```
The output of the function `kdecop` is an object of class `kdecopula` that
contains all information collected during the estimation process and summary
statistics such as *AIC* or the *effective number of parameters/degrees of
freedom*. These can also be accessed directly, e.g.
```{r}
logLik(kde.fit)
AIC(kde.fit)
```
#### Plotting bivariate copula densities
The most interesting part for most people is probably to make exploratory plots.
The class `kdecopula` has its own generic for plotting. In general, there are
two possible types of plots: *contour* and *surface* (or perspective) plots.
Additionally, the `margins` argument allows to choose between plots of the
original copula density and a meta-copula density with standard normal margins
(default for `type = contour`).
```{r fig.width=4, fig.height=4}
plot(kde.fit)
```
```{r fig.width=4, fig.height=4}
contour(kde.fit)
```
```{r fig.width=4, fig.height=4}
contour(kde.fit, margins = "unif")
```
You can also pass further arguments to the `...` argument to refine the
aesthetics. The arguments are forwaded to
`lattice::wireframe` or `graphics::contour`, respectively.
```{r fig.width=4, fig.height=4}
plot(kde.fit,
zlim = c(0, 10), # z-axis limits
screen = list(x = -75, z = 45), # rotate screen
xlab = list(rot = 25), # labels can be rotated as well
ylab = list(label = "other label", rot = -25))
```
```{r fig.width=4, fig.height=4}
contour(kde.fit, col = terrain.colors(30), levels = seq(0, 0.3, by = 0.01))
```
#### Working with a `kdecopula` object
The density and *cdf* can be computed easily:
```{r}
dkdecop(c(0.1, 0.2), kde.fit) # estimated copula density
pkdecop(cbind(c(0.1, 0.9), c(0.1, 0.9)), kde.fit) # corresponding copula cdf
```
Furthermore, we can simulate synthetic data from the estimated density:
```{r fig.width=4, fig.height=4}
unew <- rkdecop(655, kde.fit)
plot(unew)
```
We see that the asymmetries observed in the data are adequately reflected by
the estimated model.
## References
Gijbels, I. and Mielniczuk, J. (1990). Estimating the density of a copula
function. *Communications in Statistics - Theory and Methods*, 19(2):445-464.
Charpentier, A., Fermanian, J.-D., and Scaillet, O. (2006). The estimation of
copulas: Theory and practice. In Rank, J., editor, Copulas: From theory to
application in finance. Risk Books.
Geenens, G., Charpentier, A., and Paindaveine, D. (2014). Probit transformation
for nonparametric kernel estimation of the copula density.
[*arXiv:1404.4414 (stat.ME)*](arxiv.org/abs/1404.4414).
Nagler, T. (2014). Kernel Methods for Vine Copula Estimation. [*Master's Thesis,
Technische Universität München*](https://mediatum.ub.tum.de/node?id=1231221)
Wen, K. and Wu, X. (2015). Transformation-Kernel Estimation of the Copula
Density, Working paper, [preprint](http://agecon2.tamu.edu/people/faculty/wu-ximing/agecon2/public/copula.pdf)