copFamilies {copula}

Specific Archimedean Copula Families ("acopula" Objects)

Description

Specific Archimedean families ("acopula" objects) implemented in the package copula.

These families are “classical” as from p. 116 of Nelsen (2007). More specifially, see Table 1 of Hofert (2011).

Usage

copAMH
copClayton
copFrank
copGumbel
copJoe

Details

All these are objects of the formal class "acopula".

copAMH:

Archimedean family of Ali-Mikhail-Haq with parametric generator

\psi(t)=(1-\theta)/(\exp(t)-\theta),\ t\in[0,\infty],

with \theta\in[0,1). The range of admissible Kendall's tau is [0,1/3).

Note that the lower and upper tail-dependence coefficients are both zero, that is, this copula family does not allow for tail dependence.

copClayton:

Archimedean family of Clayton with parametric generator

\psi(t)=(1+t)^{-1/\theta},\ t\in[0,\infty],

with \theta\in(0,\infty). The range of admissible Kendall's tau, as well as that of the lower tail-dependence coefficient, is (0,1). For dimension d = 2, \theta\in(-1,\infty) is admissible where negative \theta allow negative Kendall's taus. Note that this copula does not allow for upper tail dependence.

copFrank:

Archimedean family of Frank with parametric generator

-\log(1-(1-e^{-\theta})\exp(-t))/\theta,\ t\in[0,\infty]

with \theta\in(0,\infty). The range of admissible Kendall's tau is (0,1). Note that this copula family does not allow for tail dependence.

copGumbel:

Archimedean family of Gumbel with parametric generator

\exp(-t^{1/\theta}),\ t\in[0,\infty]

with \theta\in[1,\infty). The range of admissible Kendall's tau, as well as that of the upper tail-dependence coefficient, is [0,1). Note that this copula does not allow for lower tail dependence.

copJoe:

Archimedean family of Joe with parametric generator

1-(1-\exp(-t))^{1/\theta},\ t\in[0,\infty]

with \theta\in[1,\infty). The range of admissible Kendall's tau, as well as that of the upper tail-dependence coefficient, is [0,1). Note that this copula does not allow for lower tail dependence.

Note that staying within one of these Archimedean families, all of them can be nested if two (generic) generator parameters \theta_0, \theta_1 satisfy \theta_0\le\theta_1.

Value

A "acopula" object.

References

Nelsen, R. B. (2007). An Introduction to Copulas (2nd ed.). Springer.

Hofert, M. (2010). Sampling Nested Archimedean Copulas with Applications to CDO Pricing. Suedwestdeutscher Verlag fuer Hochschulschriften AG & Co. KG.

Hofert, M. (2011). Efficiently sampling nested Archimedean copulas. Computational Statistics & Data Analysis 55, 57–70.

Hofert, M. and Mächler, M. (2011). Nested Archimedean Copulas Meet R: The nacopula Package. Journal of Statistical Software 39(9), 1–20. https://www.jstatsoft.org/v39/i09/.

See Also

The class definition, "acopula". onacopula and setTheta for such Archimedean copulas with specific parameters.
getAcop accesses these families “programmatically”.

Examples

## Print a copAMH object and its structure
copAMH
str(copAMH)

## Show admissible parameters for a Clayton copula
copClayton@paraInterval

## Generate random variates from a Log(p) distribution via V0 of Frank
p <- 1/2
copFrank@V0(100, -log(1-p))

## Plot the upper tail-dependence coefficient as a function in the
## parameter for Gumbel's family
curve(copGumbel@lambdaU(x), xlim = c(1, 10), ylim = c(0,1), col = 4)

## Plot Kendall's tau as a function in the parameter for Joe's family
curve(copJoe@tau(x), xlim = c(1, 10), ylim = c(0,1), col = 4)

## ------- Plot psi() and tau() - and properties of all families ----

## The copula families currently provided:
(famNms <- ls("package:copula", patt="^cop[A-Z]"))

op <- par(mfrow= c(length(famNms), 2),
          mar = .6+ c(2,1.4,1,1), mgp = c(1.1, 0.4, 0))
for(nm in famNms) { Cf <- get(nm)
   thet <- Cf@iTau(0.3)
   curve(Cf@psi(x, theta = thet), 0, 5,
         xlab = quote(x), ylab="", ylim=0:1, col = 2,
         main = substitute(list(NAM ~~~ psi(x, theta == TH), tau == 0.3),
                           list(NAM=Cf@name, TH=thet)))
   I <- Cf@paraInterval
   Iu <- pmin(10, I[2])
   curve(Cf@tau(x), I[1], Iu, col = 3,
         xlab = bquote(theta %in% .(format(I))), ylab = "",
         main = substitute(NAM ~~ tau(theta), list(NAM=Cf@name)))
}
par(op)

## Construct a bivariate Clayton copula with parameter theta
theta <- 2
C2 <- onacopula("Clayton", C(theta, 1:2))
C2@copula # is an "acopula" with specific parameter theta

curve(C2@copula@psi(x, C2@copula@theta),
      main = quote("Generator" ~~ psi ~~ " of Clayton A.copula"),
      xlab = quote(theta1), ylab = quote(psi(theta1)),
      xlim = c(0,5), ylim = c(0,1), col = 4)

## What is the corresponding Kendall's tau?
C2@copula@tau(theta) # 0.5

## What are the corresponding tail-dependence coefficients?
C2@copula@lambdaL(theta)
C2@copula@lambdaU(theta)

## Generate n pairs of random variates from this copula
U <- rnacopula(n = 1000, C2)
## and plot the generated pairs of random variates
plot(U, asp=1, main = "n = 1000 from  Clayton(theta = 2)")