R: Specific Archimedean Copula Families ("acopula" Objects)

copFamilies {copula} | R Documentation

## 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,Inf],

  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,Inf],

  with theta in (0,Inf). 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,Inf) is admissible where negative θ 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,Inf],

  with theta in (0,Inf). 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,Inf],

  with theta in [1,Inf). 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,Inf],

  with theta in [1,Inf). 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 theta0, theta1 satisfy theta0 <= theta1.

### 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)")

[Package copula version 1.0-1 Index]