Package 'VineCopula'

Description

Provides tools for the statistical analysis of regular vine copula models, see Aas et al. (2009) <doi:10.1016/j.insmatheco.2007.02.001> and Dissman et al. (2013) <doi:10.1016/j.csda.2012.08.010>. The package includes tools for parameter estimation, model selection, simulation, goodness-of-fit tests, and visualization. Tools for estimation, selection and exploratory data analysis of bivariate copula models are also provided.

Details

Vine copulas are a flexible class of dependence models consisting of bivariate building blocks (see e.g., Aas et al., 2009). This package is primarily made for the statistical analysis of vine copula models. The package includes tools for parameter estimation, model selection, simulation, goodness-of-fit tests, and visualization. Tools for estimation, selection and exploratory data analysis of bivariate copula models are also provided.

The DESCRIPTION file:

Remark

The package VineCopula is a continuation of the package CDVine by U. Schepsmeier and E. C. Brechmann (see Brechmann and Schepsmeier (2013)). It includes all functions implemented in CDVine for the bivariate case (BiCop-functions).

Author(s)

Maintainer: Thomas Nagler [email protected]

Authors:

• Ulf Schepsmeier [email protected]

• Jakob Stoeber

• Eike Christian Brechmann

• Benedikt Graeler

• Tobias Erhardt [email protected]

Other contributors:

• Carlos Almeida [contributor]

• Aleksey Min [contributor, thesis advisor]

• Claudia Czado [contributor, thesis advisor]

• Mathias Hofmann [contributor]

• Matthias Killiches [contributor]

• Harry Joe [contributor]

• Thibault Vatter [contributor]

References

Aas, K., C. Czado, A. Frigessi, and H. Bakken (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics 44 (2), 182-198.

Bedford, T. and R. M. Cooke (2001). Probability density decomposition for conditionally dependent random variables modeled by vines. Annals of Mathematics and Artificial intelligence 32, 245-268.

Bedford, T. and R. M. Cooke (2002). Vines - a new graphical model for dependent random variables. Annals of Statistics 30, 1031-1068.

Brechmann, E. C., C. Czado, and K. Aas (2012). Truncated regular vines in high dimensions with applications to financial data. Canadian Journal of Statistics 40 (1), 68-85.

Brechmann, E. C. and C. Czado (2011). Risk management with high-dimensional vine copulas: An analysis of the Euro Stoxx 50. Statistics & Risk Modeling, 30 (4), 307-342.

Brechmann, E. C. and U. Schepsmeier (2013). Modeling Dependence with C- and D-Vine Copulas: The R Package CDVine. Journal of Statistical Software, 52 (3), 1-27. doi:10.18637/jss.v052.i03.

Czado, C., U. Schepsmeier, and A. Min (2012). Maximum likelihood estimation of mixed C-vines with application to exchange rates. Statistical Modelling, 12(3), 229-255.

Dissmann, J. F., E. C. Brechmann, C. Czado, and D. Kurowicka (2013). Selecting and estimating regular vine copulae and application to financial returns. Computational Statistics & Data Analysis, 59 (1), 52-69.

Eschenburg, P. (2013). Properties of extreme-value copulas Diploma thesis, Technische Universitaet Muenchen https://mediatum.ub.tum.de/node?id=1145695

Joe, H. (1996). Families of m-variate distributions with given margins and m(m-1)/2 bivariate dependence parameters. In L. Rueschendorf, B. Schweizer, and M. D. Taylor (Eds.), Distributions with fixed marginals and related topics, pp. 120-141. Hayward: Institute of Mathematical Statistics.

Joe, H. (1997). Multivariate Models and Dependence Concepts. London: Chapman and Hall.

Knight, W. R. (1966). A computer method for calculating Kendall's tau with ungrouped data. Journal of the American Statistical Association 61 (314), 436-439.

Kurowicka, D. and R. M. Cooke (2006). Uncertainty Analysis with High Dimensional Dependence Modelling. Chichester: John Wiley.

Kurowicka, D. and H. Joe (Eds.) (2011). Dependence Modeling: Vine Copula Handbook. Singapore: World Scientific Publishing Co.

Nelsen, R. (2006). An introduction to copulas. Springer

Schepsmeier, U. and J. Stoeber (2014). Derivatives and Fisher information of bivariate copulas. Statistical Papers, 55 (2), 525-542.
https://link.springer.com/article/10.1007/s00362-013-0498-x.

Schepsmeier, U. (2013) A goodness-of-fit test for regular vine copula models. Preprint https://arxiv.org/abs/1306.0818

Schepsmeier, U. (2015) Efficient information based goodness-of-fit tests for vine copula models with fixed margins. Journal of Multivariate Analysis 138, 34-52.

Stoeber, J. and U. Schepsmeier (2013). Estimating standard errors in regular vine copula models. Computational Statistics, 28 (6), 2679-2707
https://link.springer.com/article/10.1007/s00180-013-0423-8#.

White, H. (1982) Maximum likelihood estimation of misspecified models, Econometrica, 50, 1-26.

See Also

Useful links:

• https://github.com/tnagler/VineCopula

• Report bugs at https://github.com/tnagler/VineCopula/issues

Description

The function as.copuladata coerces an object (data.frame, matrix, list) to a copuladata object.

Usage

as.copuladata(data)

Arguments

Author(s)

Tobias Erhardt

See Also

pobs(), pairs.copuladata()

Examples

data(daxreturns)

data <- as.matrix(daxreturns)
class(as.copuladata(data))

data <- as.data.frame(daxreturns)
class(as.copuladata(data))

data <- as.list(daxreturns)
names(data) <- names(daxreturns)
class(as.copuladata(data))

Description

This function computes the empirical Blomqvist's beta.

Usage

BetaMatrix(data)

Arguments

Value

Matrix of the empirical Blomqvist's betas.

Author(s)

Ulf Schepsmeier

References

Blomqvist, N. (1950). On a measure of dependence between two random variables. The Annals of Mathematical Statistics, 21(4), 593-600.

Nelsen, R. (2006). An introduction to copulas. Springer

See Also

TauMatrix(), BiCopPar2Beta(), RVinePar2Beta()

Examples

data(daxreturns)
data <- as.matrix(daxreturns)

# compute the empirical Blomqvist's betas
BetaMatrix(data)

Description

This function creates an object of class BiCop and checks for family/parameter consistency.

Usage

BiCop(family, par, par2 = 0, tau = NULL, check.pars = TRUE)

Arguments

Value

An object of class BiCop(). It is a list containing information about the bivariate copula. Its components are:

Objects of this class are also returned by the BiCopEst() and BiCopSelect() functions. In this case, further information about the fit is added.

Note

For a comprehensive summary of the model, use summary(object); to see all its contents, use str(object).

Author(s)

Thomas Nagler

See Also

BiCopPDF(), BiCopHfunc(), BiCopSim(), BiCopEst(), BiCopSelect(), plot.BiCop(), contour.BiCop()

Examples

## create BiCop object for bivariate t-copula
obj <- BiCop(family = 2, par = 0.4, par2 = 6)
obj

## see the object's content or a summary
str(obj)
summary(obj)

## a selection of functions that can be used with BiCop objects
simdata <- BiCopSim(300, obj)  # simulate data
BiCopPDF(0.5, 0.5, obj) # evaluate density in (0.5,0.5)
plot(obj)  # surface plot of copula density
contour(obj)  # contour plot with standard normal margins
print(obj)  # brief overview of BiCop object
summary(obj)  # comprehensive overview of BiCop object

Description

This function evaluates the cumulative distribution function (CDF) of a given parametric bivariate copula.

Usage

BiCopCDF(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopCDF(u1, u2, obj)

can be used.

Value

A numeric vector of the bivariate copula distribution function

• of the copula family

• with parameter(s) par, par2

• evaluated at u1 and u2.

Note

The calculation of the cumulative distribution function (CDF) of the Student's t copula (family = 2) is only approximate. For numerical reasons, the degree of freedom parameter (par2) is rounded to an integer before calculation of the CDF.

Author(s)

Eike Brechmann

See Also

BiCopPDF(), BiCopHfunc(), BiCopSim(), BiCop()

Examples

## simulate from a bivariate Clayton copula
set.seed(123)
cop <- BiCop(family = 3, par = 3.4)
simdata <- BiCopSim(300, cop)

## evaluate the distribution function of the bivariate Clayton copula
u1 <- simdata[,1]
u2 <- simdata[,2]
BiCopCDF(u1, u2, cop)

## select a bivariate copula for the simulated data
cop <- BiCopSelect(u1, u2)
summary(cop)
## and evaluate its CDF
BiCopCDF(u1, u2, cop)

Description

The function checks if a certain combination of copula family and parameters can be used within other functions of this package.

Usage

BiCopCheck(family, par, par2 = 0, ...)

Arguments

Value

A logical indicating whether the family can be used with the parameter specification.

Author(s)

Thomas Nagler

Examples

## check parameter of Clayton copula
BiCopCheck(3, 1)  # works

## Not run: BiCopCheck(3, -1)  # does not work (only positive parameter is allowed)

Description

This function creates a chi-plot of given bivariate copula data.

Usage

BiCopChiPlot(u1, u2, PLOT = TRUE, mode = "NULL", ...)

Arguments

Details

For observations $u_{i,j},\ i=1,...,N,\ j=1,2,$ the chi-plot is based on the following two quantities: the chi-statistics

$\chi_i = \frac{\hat{F}_{1,2}(u_{i,1},u_{i,2}) - \hat{F}_{1}(u_{i,1})\hat{F}_{2}(u_{i,2})}{ \sqrt{\hat{F}_{1}(u_{i,1})(1-\hat{F}_{1}(u_{i,1})) \hat{F}_{2}(u_{i,2})(1-\hat{F}_{2}(u_{i,2}))}},$

and the lambda-statistics

$\lambda_i = 4 sgn\left( \tilde{F}_{1}(u_{i,1}),\tilde{F}_{2}(u_{i,2}) \right) \cdot \max\left( \tilde{F}_{1}(u_{i,1})^2,\tilde{F}_{2}(u_{i,2})^2 \right),$

where $\hat{F}_{1}$, $\hat{F}_{2}$ and $\hat{F}_{1,2}$ are the empirical distribution functions of the uniform random variables $U_1$ and $U_2$ and of $(U_1,U_2)$, respectively. Further, $\tilde{F}_{1}=\hat{F}_{1}-0.5$ and $\tilde{F}_{2}=\hat{F}_{2}-0.5$.

These quantities only depend on the ranks of the data and are scaled to the interval $[0,1]$. $\lambda_i$ measures a distance of a data point $\left(u_{i,1},u_{i,2}\right)$ to the center of the bivariate data set, while $\chi_i$ corresponds to a correlation coefficient between dichotomized values of $U_1$ and $U_2$. Under independence it holds that $\chi_i \sim \mathcal{N}(0,\frac{1}{N})$ and $\lambda_i \sim \mathcal{U}[-1,1]$ asymptotically, i.e., values of $\chi_i$ close to zero indicate independence—corresponding to $F_{1, 2}=F_{1}F_{2}$.

When plotting these quantities, the pairs of $\left(\lambda_i, \chi_i \right)$ will tend to be located above zero for positively dependent margins and vice versa for negatively dependent margins. Control bounds around zero indicate whether there is significant dependence present.

If mode = "lower" or "upper", the above quantities are calculated only for those $u_{i,1}$'s and $u_{i,2}$'s which are smaller/larger than the respective means of u1$=(u_{1,1},...,u_{N,1})$ and u2$=(u_{1,2},...,u_{N,2})$.

Value

Author(s)

Natalia Belgorodski, Ulf Schepsmeier

References

Abberger, K. (2004). A simple graphical method to explore tail-dependence in stock-return pairs. Discussion Paper, University of Konstanz, Germany.

Genest, C. and A. C. Favre (2007). Everything you always wanted to know about copula modeling but were afraid to ask. Journal of Hydrologic Engineering, 12 (4), 347-368.

See Also

BiCopMetaContour(), BiCopKPlot(), BiCopLambda()

Examples

## chi-plots for bivariate Gaussian copula data

# simulate copula data
fam <- 1
tau <- 0.5
par <- BiCopTau2Par(fam, tau)
cop <- BiCop(fam, par)
set.seed(123)
dat <- BiCopSim(500, cop)

# create chi-plots
op <- par(mfrow = c(1, 3))
BiCopChiPlot(dat[,1], dat[,2], xlim = c(-1,1), ylim = c(-1,1),
             main="General chi-plot")
BiCopChiPlot(dat[,1], dat[,2], mode = "lower", xlim = c(-1,1),
             ylim = c(-1,1), main = "Lower chi-plot")
BiCopChiPlot(dat[,1], dat[,2], mode = "upper", xlim = c(-1,1),
             ylim = c(-1,1), main = "Upper chi-plot")
par(op)

Description

The function starts a shiny app which visualizes copula data and allows to compare it with overlays of density contours or simulated data from different copula families with fitted parameters. Several specifications for the margins are available.

Usage

BiCopCompare(u1, u2, familyset = NA, rotations = TRUE)

Arguments

Value

A BiCop() object containing the model selected by the user.

Author(s)

Matthias Killiches, Thomas Nagler

Examples

# load data
data(daxreturns)

# find a suitable copula family for the first two stocks
## Not run: fit <- BiCopCompare(daxreturns[, 1], daxreturns[, 2])

Description

This function simulates from a parametric bivariate copula, where on of the variables is fixed. I.e., we simulate either from $C_{2|1}(u_2|u_1;\theta)$ or $C_{1|2}(u_1|u_2;\theta)$, which are both conditional distribution functions of one variable given another.

Usage

BiCopCondSim(
  N,
  cond.val,
  cond.var,
  family,
  par,
  par2 = 0,
  obj = NULL,
  check.pars = TRUE
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopCondSim(N, cond.val, cond.var, obj)

can be used.

Value

A length N vector of simulated from conditional distributions related to bivariate copula with family and parameter(s) par, par2.

Author(s)

Thomas Nagler

See Also

BiCopCDF(), BiCopPDF(), RVineSim()

Examples

# create bivariate t-copula
obj <- BiCop(family = 2, par = -0.7, par2 = 4)

# simulate 500 observations of (U1, U2)
sim <- BiCopSim(500, obj)
hist(sim[, 1])  # data have uniform distribution
hist(sim[, 2])  # data have uniform distribution

# simulate 500 observations of (U2 | U1 = 0.7)
sim1 <- BiCopCondSim(500, cond.val = 0.7, cond.var = 1, obj)
hist(sim1)  # not uniform!

# simulate 500 observations of (U1 | U2 = 0.1)
sim2 <- BiCopCondSim(500, cond.val = 0.1, cond.var = 2, obj)
hist(sim2)  # not uniform!

Description

This function evaluates the derivative of a given parametric bivariate copula density with respect to its parameter(s) or one of its arguments.

Usage

BiCopDeriv(
  u1,
  u2,
  family,
  par,
  par2 = 0,
  deriv = "par",
  log = FALSE,
  obj = NULL,
  check.pars = TRUE
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopDeriv(u1, u2, obj, deriv = "par", log = FALSE)

can be used.

Value

A numeric vector of the bivariate copula derivative

• of the copula family

• with parameter(s) par, par2

• with respect to deriv,

• evaluated at u1 and u2.

Author(s)

Ulf Schepsmeier

References

Schepsmeier, U. and J. Stoeber (2014). Derivatives and Fisher information of bivariate copulas. Statistical Papers, 55 (2), 525-542.
https://link.springer.com/article/10.1007/s00362-013-0498-x.

See Also

RVineGrad(), RVineHessian(), BiCopDeriv2(), BiCopHfuncDeriv(), BiCop()

Examples

## simulate from a bivariate Student-t copula
set.seed(123)
cop <- BiCop(family = 2, par = -0.7, par2 = 4)
simdata <- BiCopSim(100, cop)

## derivative of the bivariate t-copula with respect to the first parameter
u1 <- simdata[,1]
u2 <- simdata[,2]
BiCopDeriv(u1, u2, cop, deriv = "par")

## estimate a Student-t copula for the simulated data
cop <- BiCopEst(u1, u2, family = 2)
## and evaluate its derivative w.r.t. the second argument u2
BiCopDeriv(u1, u2, cop, deriv = "u2")

Description

This function evaluates the second derivative of a given parametric bivariate copula density with respect to its parameter(s) and/or its arguments.

Usage

BiCopDeriv2(
  u1,
  u2,
  family,
  par,
  par2 = 0,
  deriv = "par",
  obj = NULL,
  check.pars = TRUE
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopDeriv2(u1, u2, obj, deriv = "par")

can be used.

Value

A numeric vector of the second-order bivariate copula derivative

• of the copula family

• with parameter(s) par, par2

• with respect to deriv

• evaluated at u1 and u2.

Author(s)

Ulf Schepsmeier, Jakob Stoeber

References

Schepsmeier, U. and J. Stoeber (2014). Derivatives and Fisher information of bivariate copulas. Statistical Papers, 55 (2), 525-542.
https://link.springer.com/article/10.1007/s00362-013-0498-x.

See Also

RVineGrad(), RVineHessian(), BiCopDeriv(), BiCopHfuncDeriv(), BiCop()

Examples

## simulate from a bivariate Student-t copula
set.seed(123)
cop <- BiCop(family = 2, par = -0.7, par2 = 4)
simdata <- BiCopSim(100, cop)

## second derivative of the Student-t copula w.r.t. the first parameter
u1 <- simdata[,1]
u2 <- simdata[,2]
BiCopDeriv2(u1, u2, cop, deriv = "par")

## estimate a Student-t copula for the simulated data
cop <- BiCopEst(u1, u2, family = 2)
## and evaluate its second derivative w.r.t. the second argument u2
BiCopDeriv2(u1, u2, cop, deriv = "u2")

Description

This function estimates the parameter(s) of a bivariate copula using either inversion of empirical Kendall's tau (for one parameter copula families only) or maximum likelihood estimation for implemented copula families.

Usage

BiCopEst(
  u1,
  u2,
  family,
  method = "mle",
  se = FALSE,
  max.df = 30,
  max.BB = list(BB1 = c(5, 6), BB6 = c(6, 6), BB7 = c(5, 6), BB8 = c(6, 1)),
  weights = NA
)

Arguments

Details

If method = "itau", the function computes the empirical Kendall's tau of the given copula data and exploits the one-to-one relationship of copula parameter and Kendall's tau which is available for many one parameter bivariate copula families (see BiCopPar2Tau() and BiCopTau2Par()). The inversion of Kendall's tau is however not available for all bivariate copula families (see above). If a two parameter copula family is chosen and method = "itau", a warning message is returned and the MLE is calculated.

For method = "mle" copula parameters are estimated by maximum likelihood using starting values obtained by method = "itau". If no starting values are available by inversion of Kendall's tau, starting values have to be provided given expert knowledge and the boundaries max.df and max.BB respectively. Note: The MLE is performed via numerical maximization using the L_BFGS-B method. For the Gaussian, the t- and the one-parametric Archimedean copulas we can use the gradients, but for the BB copulas we have to use finite differences for the L_BFGS-B method.

A warning message is returned if the estimate of the degrees of freedom parameter of the t-copula is larger than max.df. For high degrees of freedom the t-copula is almost indistinguishable from the Gaussian and it is advised to use the Gaussian copula in this case. As a rule of thumb max.df = 30 typically is a good choice. Moreover, standard errors of the degrees of freedom parameter estimate cannot be estimated in this case.

Value

An object of class BiCop(), augmented with the following entries:

Note

For a comprehensive summary of the fitted model, use summary(object); to see all its contents, use str(object).

Author(s)

Ulf Schepsmeier, Eike Brechmann, Jakob Stoeber, Carlos Almeida

References

Joe, H. (1997). Multivariate Models and Dependence Concepts. Chapman and Hall, London.

See Also

BiCop(), BiCopPar2Tau(), BiCopTau2Par(), RVineSeqEst(), BiCopSelect(),

Examples

## Example 1: bivariate Gaussian copula
dat <- BiCopSim(500, 1, 0.7)
u1 <- dat[, 1]
v1 <- dat[, 2]

# estimate parameters of Gaussian copula by inversion of Kendall's tau
est1.tau <- BiCopEst(u1, v1, family = 1, method = "itau")
est1.tau  # short overview
summary(est1.tau)  # comprehensive overview
str(est1.tau)  # see all contents of the object

# check if parameter actually coincides with inversion of Kendall's tau
tau1 <- cor(u1, v1, method = "kendall")
all.equal(BiCopTau2Par(1, tau1), est1.tau$par)

# maximum likelihood estimate for comparison
est1.mle <- BiCopEst(u1, v1, family = 1, method = "mle")
summary(est1.mle)


## Example 2: bivariate Clayton and survival Gumbel copulas
# simulate from a Clayton copula
dat <- BiCopSim(500, 3, 2.5)
u2 <- dat[, 1]
v2 <- dat[, 2]

# empirical Kendall's tau
tau2 <- cor(u2, v2, method = "kendall")

# inversion of empirical Kendall's tau for the Clayton copula
BiCopTau2Par(3, tau2)
BiCopEst(u2, v2, family = 3, method = "itau")

# inversion of empirical Kendall's tau for the survival Gumbel copula
BiCopTau2Par(14, tau2)
BiCopEst(u2, v2, family = 14, method = "itau")

# maximum likelihood estimates for comparison
BiCopEst(u2, v2, family = 3, method = "mle")
BiCopEst(u2, v2, family = 14, method = "mle")

Description

This function allows to compare bivariate copula models across a number of families w.r.t. the fit statistics log-likelihood, AIC, and BIC. For each family, the parameters are estimated by maximum likelihood.

Usage

BiCopEstList(u1, u2, familyset = NA, weights = NA, rotations = TRUE, ...)

Arguments

Details

First all available copulas are fitted using maximum likelihood estimation. Then the criteria are computed for all available copula families (e.g., if u1 and u2 are negatively dependent, Clayton, Gumbel, Joe, BB1, BB6, BB7 and BB8 and their survival copulas are not considered) and the family with the minimum value is chosen. For observations $u_{i,j},\ i=1,...,N,\ j=1,2,$ the AIC of a bivariate copula family $c$ with parameter(s) $\boldsymbol{\theta}$ is defined as

$AIC := -2 \sum_{i=1}^N \ln[c(u_{i,1},u_{i,2}|\boldsymbol{\theta})] + 2k,$

where $k=1$ for one parameter copulas and $k=2$ for the two parameter t-, BB1, BB6, BB7 and BB8 copulas. Similarly, the BIC is given by

$BIC := -2 \sum_{i=1}^N \ln[c(u_{i,1},u_{i,2}|\boldsymbol{\theta})] + \ln(N)k.$

Evidently, if the BIC is chosen, the penalty for two parameter families is stronger than when using the AIC.

Value

A list containing

Author(s)

Thomas Nagler

References

Akaike, H. (1973). Information theory and an extension of the maximum likelihood principle. In B. N. Petrov and F. Csaki (Eds.), Proceedings of the Second International Symposium on Information Theory Budapest, Akademiai Kiado, pp. 267-281.

Schwarz, G. E. (1978). Estimating the dimension of a model. Annals of Statistics 6 (2), 461-464.

See Also

BiCop(), BiCopEst()

Examples

## compare models
data(daxreturns)
comp <- BiCopEstList(daxreturns[, 1], daxreturns[, 4])

Description

This function performs a goodness-of-fit test for bivariate copulas, either based on White's information matrix equality (White, 1982) as introduced by Huang and Prokhorov (2011) or based on Kendall's process (Wang and Wells, 2000; Genest et al., 2006). It computes the test statistics and p-values.

Usage

BiCopGofTest(
  u1,
  u2,
  family,
  par = 0,
  par2 = 0,
  method = "white",
  max.df = 30,
  B = 100,
  obj = NULL
)

Arguments

Details

method = "white":
This goodness-of fit test uses the information matrix equality of White (1982) and was investigated by Huang and Prokhorov (2011). The main contribution is that under correct model specification the Fisher Information can be equivalently calculated as minus the expected Hessian matrix or as the expected outer product of the score function. The null hypothesis is

$H_0: \boldsymbol{H}(\theta) + \boldsymbol{C}(\theta) = 0$

against the alternative

$H_0: \boldsymbol{H}(\theta) + \boldsymbol{C}(\theta) \neq 0 ,$

where $\boldsymbol{H}(\theta)$ is the expected Hessian matrix and $\boldsymbol{C}(\theta)$ is the expected outer product of the score function. For the calculation of the test statistic we use the consistent maximum likelihood estimator $\hat{\theta}$ and the sample counter parts of $\boldsymbol{H}(\theta)$ and $\boldsymbol{C}(\theta)$. The correction of the covariance-matrix in the test statistic for the uncertainty in the margins is skipped. The implemented tests assumes that where is no uncertainty in the margins. The correction can be found in Huang and Prokhorov (2011). It involves two-dimensional integrals.
WARNING: For the t-copula the test may be unstable. The results for the t-copula therefore have to be treated carefully.

method = "kendall":
This copula goodness-of-fit test is based on Kendall's process as proposed by Wang and Wells (2000). For computation of p-values, the parametric bootstrap described by Genest et al. (2006) is used. For rotated copulas the input arguments are transformed and the goodness-of-fit procedure for the corresponding non-rotated copula is used.

Value

For method = "white":

For method ="kendall"

Author(s)

Ulf Schepsmeier, Wanling Huang, Jiying Luo, Eike Brechmann

References

Huang, W. and A. Prokhorov (2014). A goodness-of-fit test for copulas. Econometric Reviews, 33 (7), 751-771.

Wang, W. and M. T. Wells (2000). Model selection and semiparametric inference for bivariate failure-time data. Journal of the American Statistical Association, 95 (449), 62-72.

Genest, C., Quessy, J. F., and Remillard, B. (2006). Goodness-of-fit Procedures for Copula Models Based on the Probability Integral Transformation. Scandinavian Journal of Statistics, 33(2), 337-366. Luo J. (2011). Stepwise estimation of D-vines with arbitrary specified copula pairs and EDA tools. Diploma thesis, Technische Universitaet Muenchen.
https://mediatum.ub.tum.de/?id=1079291.

White, H. (1982) Maximum likelihood estimation of misspecified models, Econometrica, 50, 1-26.

See Also

BiCopDeriv2(), BiCopDeriv(), BiCopIndTest(), BiCopVuongClarke()

Examples

# simulate from a bivariate Clayton copula

simdata <- BiCopSim(100, 3, 2)
u1 <- simdata[,1]
u2 <- simdata[,2]

# perform White's goodness-of-fit test for the true copula
BiCopGofTest(u1, u2, family = 3)

# perform White's goodness-of-fit test for the Frank copula
BiCopGofTest(u1, u2, family = 5)

# perform Kendall's goodness-of-fit test for the true copula
BiCopGofTest(u1, u2, family = 3, method = "kendall", B=50)

# perform Kendall's goodness-of-fit test for the Frank copula
BiCopGofTest(u1, u2, family = 5, method = "kendall", B=50)

Description

Evaluate the conditional distribution function (h-function) of a given parametric bivariate copula.

Usage

BiCopHfunc(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

BiCopHfunc1(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

BiCopHfunc2(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

Arguments

Details

The h-function is defined as the conditional distribution function of a bivariate copula, i.e.,

$h_1(u_2|u_1;\boldsymbol{\theta}) := P(U_2 \le u_2 | U_1 = u_1) = \frac{\partial C(u_1, u_2; \boldsymbol{\theta})}{\partial u_1},$

$h_2(u_1|u_2;\boldsymbol{\theta}) := P(U_1 \le u_1 | U_2 = u_2) = \frac{\partial C(u_1, u_2; \boldsymbol{\theta})}{\partial u_2},$

where $(U_1, U_2) \sim C$, and $C$ is a bivariate copula distribution function with parameter(s) $\boldsymbol{\theta}$. For more details see Aas et al. (2009).

If the family and parameter specification is stored in a BiCop() object obj, the alternative versions

BiCopHfunc(u1, u2, obj)
BiCopHfunc1(u1, u2, obj)
BiCopHfunc2(u1, u2, obj)

can be used.

Value

BiCopHfunc returns a list with

BiCopHfunc1 is a faster version that only calculates hfunc1; BiCopHfunc2 only calculates hfunc2.

Author(s)

Ulf Schepsmeier

References

Aas, K., C. Czado, A. Frigessi, and H. Bakken (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics 44 (2), 182-198.

See Also

BiCopHinv(), BiCopPDF(), BiCopCDF(), RVineLogLik(), RVineSeqEst(), BiCop()

Examples

data(daxreturns)

# h-functions of the Gaussian copula
cop <- BiCop(family = 1, par = 0.5)
h <- BiCopHfunc(daxreturns[, 2], daxreturns[, 1], cop)

# or using the fast versions
h1 <- BiCopHfunc1(daxreturns[, 2], daxreturns[, 1], cop)
h2 <- BiCopHfunc2(daxreturns[, 2], daxreturns[, 1], cop)
all.equal(h$hfunc1, h1)
all.equal(h$hfunc2, h2)

Description

This function evaluates the derivative of a given conditional parametric bivariate copula (h-function) with respect to its parameter(s) or one of its arguments.

Usage

BiCopHfuncDeriv(
  u1,
  u2,
  family,
  par,
  par2 = 0,
  deriv = "par",
  obj = NULL,
  check.pars = TRUE
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopHfuncDeriv(u1, u2, obj, deriv = "par")

can be used.

Value

A numeric vector of the conditional bivariate copula derivative

• of the copula family,

• with parameter(s) par, par2,

• with respect to deriv,

• evaluated at u1 and u2.

Author(s)

Ulf Schepsmeier

References

Schepsmeier, U. and J. Stoeber (2014). Derivatives and Fisher information of bivariate copulas. Statistical Papers, 55 (2), 525-542.
https://link.springer.com/article/10.1007/s00362-013-0498-x.

See Also

RVineGrad(), RVineHessian(), BiCopDeriv2(), BiCopDeriv2(), BiCopHfuncDeriv(), BiCop()

Examples

## simulate from a bivariate Student-t copula
set.seed(123)
cop <- BiCop(family = 2, par = -0.7, par2 = 4)
simdata <- BiCopSim(100, cop)

## derivative of the conditional Student-t copula
## with respect to the first parameter
u1 <- simdata[,1]
u2 <- simdata[,2]
BiCopHfuncDeriv(u1, u2, cop, deriv = "par")

## estimate a Student-t copula for the simulated data
cop <- BiCopEst(u1, u2, family = 2)
## and evaluate the derivative of the conditional copula
## w.r.t. the second argument u2
BiCopHfuncDeriv(u1, u2, cop, deriv = "u2")

Description

This function evaluates the second derivative of a given conditional parametric bivariate copula (h-function) with respect to its parameter(s) and/or its arguments.

Usage

BiCopHfuncDeriv2(
  u1,
  u2,
  family,
  par,
  par2 = 0,
  deriv = "par",
  obj = NULL,
  check.pars = TRUE
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopHfuncDeriv2(u1, u2, obj, deriv = "par")

can be used.

Value

A numeric vector of the second-order conditional bivariate copula derivative

• of the copula family

• with parameter(s) par, par2

• with respect to deriv

• evaluated at u1 and u2.

Author(s)

Ulf Schepsmeier, Jakob Stoeber

References

Schepsmeier, U. and J. Stoeber (2014). Derivatives and Fisher information of bivariate copulas. Statistical Papers, 55 (2), 525-542.
https://link.springer.com/article/10.1007/s00362-013-0498-x.

See Also

RVineGrad(), RVineHessian(), BiCopDeriv(), BiCopDeriv2(), BiCopHfuncDeriv(), BiCop()

Examples

## simulate from a bivariate Student-t copula
set.seed(123)
cop <- BiCop(family = 2, par = -0.7, par2 = 4)
simdata <- BiCopSim(100, cop)

## second derivative of the conditional bivariate t-copula
## with respect to the first parameter
u1 <- simdata[,1]
u2 <- simdata[,2]
BiCopHfuncDeriv2(u1, u2, cop, deriv = "par")

## estimate a Student-t copula for the simulated data
cop <- BiCopEst(u1, u2, family = 2)
## and evaluate the derivative of the conditional copula
## w.r.t. the second argument u2
BiCopHfuncDeriv2(u1, u2, cop, deriv = "u2")

Description

Evaluate the inverse conditional distribution function (inverse h-function) of a given parametric bivariate copula.

Usage

BiCopHinv(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

BiCopHinv1(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

BiCopHinv2(u1, u2, family, par, par2 = 0, obj = NULL, check.pars = TRUE)

Arguments

Details

The h-function is defined as the conditional distribution function of a bivariate copula, i.e.,

$h_1(u_2|u_1;\boldsymbol{\theta}) := P(U_2 \le u_2 | U_1 = u_1) = \frac{\partial C(u_1, u_2; \boldsymbol{\theta})}{\partial u_1},$

$h_2(u_1|u_2;\boldsymbol{\theta}) := P(U_1 \le u_1 | U_2 = u_2) = \frac{\partial C(u_1, u_2; \boldsymbol{\theta})}{\partial u_2},$

where $(U_1, U_2) \sim C$, and $C$ is a bivariate copula distribution function with parameter(s) $\boldsymbol{\theta}$. For more details see Aas et al. (2009).

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopHinv(u1, u2, obj),
BiCopHinv1(u1, u2, obj),
BiCopHinv2(u1, u2, obj)

can be used.

Value

BiCopHinv returns a list with

BiCopHinv1 is a faster version that only calculates hinv1; BiCopHinv2 only calculates hinv2.

Author(s)

Ulf Schepsmeier, Thomas Nagler

References

Aas, K., C. Czado, A. Frigessi, and H. Bakken (2009). Pair-copula constructions of multiple dependence. Insurance: Mathematics and Economics 44 (2), 182-198.

See Also

BiCopHfunc(), BiCopPDF(), BiCopCDF(), RVineLogLik(), RVineSeqEst(), BiCop()

Examples

# inverse h-functions of the Gaussian copula
cop <- BiCop(1, 0.5)
hi <- BiCopHinv(0.1, 0.2, cop)

# or using the fast versions
hi1 <- BiCopHinv1(0.1, 0.2, cop)
hi2 <- BiCopHinv2(0.1, 0.2, cop)
all.equal(hi$hinv1, hi1)
all.equal(hi$hinv2, hi2)

# check if it is actually the inverse
cop <- BiCop(3, 3)
all.equal(0.2, BiCopHfunc1(0.1, BiCopHinv1(0.1, 0.2, cop), cop))
all.equal(0.1, BiCopHfunc2(BiCopHinv2(0.1, 0.2, cop), 0.2, cop))

Description

This function returns the p-value of a bivariate asymptotic independence test based on Kendall's $\tau$.

Usage

BiCopIndTest(u1, u2)

Arguments

Details

The test exploits the asymptotic normality of the test statistic

$\texttt{statistic} := T = \sqrt{\frac{9N(N - 1)}{2(2N + 5)}} \times |\hat{\tau}|,$

where $N$ is the number of observations (length of u1) and $\hat{\tau}$ the empirical Kendall's tau of the data vectors u1 and u2. The p-value of the null hypothesis of bivariate independence hence is asymptotically

$\texttt{p.value} = 2 \times \left(1 - \Phi\left(T\right)\right),$

where $\Phi$ is the standard normal distribution function.

Value

Author(s)

Jeffrey Dissmann

References

Genest, C. and A. C. Favre (2007). Everything you always wanted to know about copula modeling but were afraid to ask. Journal of Hydrologic Engineering, 12 (4), 347-368.

See Also

BiCopGofTest(), BiCopPar2Tau(), BiCopTau2Par(), BiCopSelect(),
RVineCopSelect(), RVineStructureSelect()

Examples

## Example 1: Gaussian copula with large dependence parameter
cop <- BiCop(1, 0.7)
dat <- BiCopSim(500, cop)

# perform the asymptotic independence test
BiCopIndTest(dat[, 1], dat[, 2])

## Example 2: Gaussian copula with small dependence parameter
cop <- BiCop(1, 0.01)
dat <- BiCopSim(500, cop)

# perform the asymptotic independence test
BiCopIndTest(dat[, 1], dat[, 2])

Description

A kernel density estimate of the copula density is visualized. The function provides the same options as plot.BiCop(). Further arguments can be passed to kdecopula::kdecop() to modify the estimate. The kdecopula::kdecopula-package() must be installed to use this function.

Usage

BiCopKDE(u1, u2, type = "contour", margins, size, kde.pars = list(), ...)

Arguments

Details

For further details on estimation see kdecopula::kdecop().

Author(s)

Thomas Nagler

Examples

# simulate data from Joe copula
cop <- BiCop(3, tau = 0.3)
u <- BiCopSim(1000, cop)
contour(cop)  # true contours

# kernel contours with standard normal margins
BiCopKDE(u[, 1], u[, 2])
BiCopKDE(u[, 1], u[, 2], kde.pars = list(mult = 0.5))  # undersmooth
BiCopKDE(u[, 1], u[, 2], kde.pars = list(mult = 2))  # oversmooth

# kernel density with uniform margins
BiCopKDE(u[, 1], u[, 2], type = "surface", zlim = c(0, 4))
plot(cop, zlim = c(0, 4))  # true density

# kernel contours are also used in pairs.copuladata
data(daxreturns)
data <- as.copuladata(daxreturns)
pairs(data[c(4, 5, 14, 15)])

Description

This function creates a Kendall's plot (K-plot) of given bivariate copula data.

Usage

BiCopKPlot(u1, u2, PLOT = TRUE, ...)

Arguments

Details

For observations $u_{i,j},\ i=1,...,N,\ j=1,2,$ the K-plot considers two quantities: First, the ordered values of the empirical bivariate distribution function $H_i:=\hat{F}_{U_1U_2}(u_{i,1},u_{i,2})$ and, second, $W_{i:N}$, which are the expected values of the order statistics from a random sample of size $N$ of the random variable $W=C(U_1,U_2)$ under the null hypothesis of independence between $U_1$ and $U_2$. $W_{i:N}$ can be calculated as follows

$W_{i:n}= N {N-1 \choose i-1} \int\limits_{0}^1 \omega k_0(\omega) ( K_0(\omega) )^{i-1} ( 1-K_0(\omega) )^{N-i} d\omega,$

where

$K_0(\omega) = \omega - \omega \log(\omega),$

and $k_0(\cdot)$ is the corresponding density.

K-plots can be seen as the bivariate copula equivalent to QQ-plots. If the points of a K-plot lie approximately on the diagonal $y=x$, then $U_1$ and $U_2$ are approximately independent. Any deviation from the diagonal line points towards dependence. In case of positive dependence, the points of the K-plot should be located above the diagonal line, and vice versa for negative dependence. The larger the deviation from the diagonal, the stronger is the degree of dependency. There is a perfect positive dependence if points $\left(W_{i:N},H_i\right)$ lie on the curve $K_0(\omega)$ located above the main diagonal. If points $\left(W_{i:N},H_i\right)$ however lie on the x-axis, this indicates a perfect negative dependence between $U_1$ and $U_2$.

Value

Author(s)

Natalia Belgorodski, Ulf Schepsmeier

References

Genest, C. and A. C. Favre (2007). Everything you always wanted to know about copula modeling but were afraid to ask. Journal of Hydrologic Engineering, 12 (4), 347-368.

See Also

BiCopMetaContour(), BiCopChiPlot(), BiCopLambda(), BiCopGofTest()

Examples

## Gaussian and Clayton copulas
n <- 500
tau <- 0.5

# simulate from Gaussian copula
fam <- 1
par <- BiCopTau2Par(fam, tau)
cop1 <- BiCop(fam, par)
set.seed(123)
dat1 <- BiCopSim(n, cop1)

# simulate from Clayton copula
fam <- 3
par <- BiCopTau2Par(fam, tau)
cop2 <- BiCop(fam, par)
set.seed(123)
dat2 <- BiCopSim(n, cop2)

# create K-plots
op <- par(mfrow = c(1, 2))
BiCopKPlot(dat1[,1], dat1[,2], main = "Gaussian copula")
BiCopKPlot(dat2[,1], dat2[,2], main = "Clayton copula")
par(op)

Description

This function plots/returns the lambda-function of given bivariate copula data.

Usage

BiCopLambda(
  u1 = NULL,
  u2 = NULL,
  family = "emp",
  par = 0,
  par2 = 0,
  PLOT = TRUE,
  obj = NULL,
  ...
)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative versions

BiCopLambda(obj, PLOT = TRUE, ...)

and

BiCopLambda((u1, u2, obj, PLOT = TRUE, ...)

can be used.

Value

Note

The $\lambda$-function is characteristic for each bivariate copula family and defined by Kendall's distribution function $K$:

$\lambda(v,\theta) := v - K(v,\theta)$

with

$K(v,\theta) := P(C_{\theta}(U_1,U_2) \leq v),\ \ v\in [0,1].$

For Archimedean copulas one has the following closed form expression in terms of the generator function $\varphi$ of the copula $C_{\theta}$:

$\lambda(v,\theta) = \frac{\varphi(v)}{\varphi '(v)},$

where $\varphi '$ is the derivative of $\varphi$. For more details see Genest and Rivest (1993) or Schepsmeier (2010).

For the bivariate Gaussian and Student-t copula no closed form expression for the theoretical $\lambda$-function exists. Therefore it is simulated based on samples of size 1000. For all other implemented copula families there are closed form expressions available.

The plot of the theoretical $\lambda$-function also shows the limits of the $\lambda$-function corresponding to Kendall's tau $=0$ and Kendall's tau $=1$ ($\lambda=0$).

For rotated bivariate copulas one has to transform the input arguments u1 and/or u2. In particular, for copulas rotated by 90 degrees u1 has to be set to 1-u1, for 270 degrees u2 to 1-u2 and for survival copulas u1 and u2 to 1-u1 and 1-u2, respectively. Then $\lambda$-functions for the corresponding non-rotated copula families can be considered.

Author(s)

Ulf Schepsmeier

References

Genest, C. and L.-P. Rivest (1993). Statistical inference procedures for bivariate Archimedean copulas. Journal of the American Statistical Association, 88 (423), 1034-1043.

Schepsmeier, U. (2010). Maximum likelihood estimation of C-vine pair-copula constructions based on bivariate copulas from different families. Diploma thesis, Technische Universitaet Muenchen.
https://mediatum.ub.tum.de/?id=1079296.

See Also

BiCopMetaContour(), BiCopKPlot(), BiCopChiPlot(), BiCop()

Examples

# simulate from Clayton copula
cop <- BiCop(3, tau = 0.5)
dat <- BiCopSim(1000, cop)

# create lambda-function plots
op <- par(mfrow = c(1, 3))
BiCopLambda(dat[, 1], dat[, 2])  # empirical lambda-function
BiCopLambda(cop)	# theoretical lambda-function
BiCopLambda(dat[, 1], dat[, 2], cop)	# both
par(op)

Description

Note: This function is deprecated and only available for backwards compatibility. See contour.BiCop() for contour plots of parametric copulas, and BiCopKDE() for kernel estimates.

Usage

BiCopMetaContour(
  u1 = NULL,
  u2 = NULL,
  bw = 1,
  size = 100,
  levels = c(0.01, 0.05, 0.1, 0.15, 0.2),
  family = "emp",
  par = 0,
  par2 = 0,
  PLOT = TRUE,
  margins = "norm",
  margins.par = 0,
  xylim = NA,
  obj = NULL,
  ...
)

Arguments

Value

Note

The combination family = 0 (independence copula) and margins = "unif" (uniform margins) is not possible because all z-values are equal.

Author(s)

Ulf Schepsmeier, Alexander Bauer

See Also

BiCopChiPlot(), BiCopKPlot(), BiCopLambda()

Examples

## meta Clayton distribution  with Gaussian margins
cop <- BiCop(family = 1, tau = 0.5)
BiCopMetaContour(obj = cop, main = "Clayton - normal margins")
# better:
contour(cop, main = "Clayton - normal margins")

## empirical contour plot with standard normal margins
dat <- BiCopSim(1000, cop)
BiCopMetaContour(dat[, 1], dat[, 2], bw = 2, family = "emp",
                 main = "empirical - normal margins")
# better:
BiCopKDE(dat[, 1], dat[, 2],
        main = "empirical - normal margins")

## empirical contour plot with exponential margins
BiCopMetaContour(dat[, 1], dat[, 2], bw = 2,
                 main = "empirical - exponential margins",
                 margins = "exp", margins.par = 1)
# better:
BiCopKDE(dat[, 1], dat[, 2],
         main = "empirical - exponential margins",
         margins = "exp")

Description

This function transforms the bivariate copula family number into its character expression and vice versa.

Usage

BiCopName(family, short = TRUE)

Arguments

Value

The transformed bivariate copula family (see table above).

Author(s)

Ulf Schepsmeier

See Also

RVineTreePlot()

Examples

## family number to character expression
family <- 1
BiCopName(family, short = TRUE)	 # short version
BiCopName(family, short = FALSE)	 # long version

## family character expression (short version) to number
family <- "C"
BiCopName(family)	# as number

## family character expression (long version) to number
family <- "Clayton"
BiCopName(family)	# as number

## vectors of families
BiCopName(1:10)    # as character expression
BiCopName(c("Clayton","t","J"))    # as number

Description

This function computes the theoretical Blomqvist's beta value of a bivariate copula for given parameter values.

Usage

BiCopPar2Beta(family, par, par2 = 0, obj = NULL, check.pars = TRUE)

Arguments

Details

If the family and parameter specification is stored in a BiCop() object obj, the alternative version

BiCopPar2Beta(obj)

can be used.

Value

Theoretical value of Blomqvist's beta corresponding to the bivariate copula family and parameter(s) par, par2.

Note

The number n can be chosen arbitrarily, but must agree across arguments.

Author(s)

Ulf Schepsmeier

References

Blomqvist, N. (1950). On a measure of dependence between two random variables. The Annals of Mathematical Statistics, 21(4), 593-600.

Nelsen, R. (2006). An introduction to copulas. Springer

Examples

## Example 1: Gaussian copula
BiCopPar2Beta(family = 1, par = 0.7)
BiCop(1, 0.7)$beta  # alternative

## Example 2: Clayton copula
BiCopPar2Beta(family = 3, par = 2)

## Example 3: different copula families
BiCopPar2Beta(family = c(3,4,6), par = 2:4)

Description

This function computes the theoretical tail dependence coefficients of a bivariate copula for given parameter values.

Usage

BiCopPar2TailDep(family, par, par2 = 0, obj = NULL, check.pars = TRUE)

Arguments

Details

If the family and parameter specification is stored in a BiCop object obj, the alternative version

BiCopPar2TailDep(obj)

can be used.

Value

Lower and upper tail dependence coefficients for bivariate copula families and parameters ($\theta$ for one parameter families and the first parameter of the t-copula with $\nu$ degrees of freedom, $\theta$ and $\delta$ for the two parameter BB1, BB6, BB7 and BB8 copulas) are given in the following table.