R: Construction of Archimedean Copula Class Object

archmCopula {copula} | R Documentation

## Construction of Archimedean Copula Class Object

### Description

Constructs an Archimedean copula class object with its corresponding parameter and dimension.

### Usage

    archmCopula(family, param = NA_real_, dim = 2, ...)

    claytonCopula(param = NA_real_, dim = 2,
              use.indepC = c("message", "TRUE", "FALSE"))
    frankCopula(param = NA_real_, dim = 2,
              use.indepC = c("message", "TRUE", "FALSE"))
    gumbelCopula(param = NA_real_, dim = 2,
              use.indepC = c("message", "TRUE", "FALSE"))
    amhCopula(param = NA_real_, dim = 2,
              use.indepC = c("message", "TRUE", "FALSE"))
    joeCopula(param = NA_real_, dim = 2,
              use.indepC = c("message", "TRUE", "FALSE"))

### Arguments

`family` | a character string specifying the family of an Archimedean copula. Currently supported families are "clayton", "frank", "amh", "gumbel", and "joe".
`param` | number (`numeric`) specifying the copula parameter.
`dim` | the dimension of the copula.
`...` | further arguments, passed to the individual creator functions (`claytonCopula()`, etc).
`use.indepC` | a string specifying if the independence copula `indepCopula`, should be returned in the case where the parameter θ, `param`, is at the boundary or limit case where the corresponding Archimedean copula is the independence copula. The default does return `indepCopula()` with a message, using `"TRUE"` does it without a message. This makes the resulting object more useful typically, but does not return a formal Archimedean copula of the desired family, something needed e.g., for fitting purposes, where you'd use `use.indepC="FALSE"`.

### Details

`archmCopula()` is a wrapper for `claytonCopula()`, `frankCopula()`, `gumbelCopula()`, `amhCopula()` and `joeCopula`.

For the mathematical definitions of the respective Archimedean families, see `copClayton`.

For d = 2, i.e. `dim = 2`, the AMH, Clayton and Frank copulas allow to model negative Kendall's tau (`tau`) behavior via negative theta, for AMH and Clayton -1 <= theta, and for Frank -Inf < theta. The respective boundary cases are

AMH:

  τ(θ = -1) = -0.1817258,

Clayton:

  τ(θ = -1) = -1,

Frank:

  τ(θ = -Inf) = -1 (as limit).

For the Ali-Mikhail-Haq copula family (`"amhCopula"`), only the bivariate case is available; however `copAMH` has no such limitation.

Note that in all cases except for Frank and AMH, and d = 2 and theta < 0, the densities (`dCopula()` methods) are evaluated via the `dacopula` slot of the corresponding `acopula`-classed Archimedean copulas, implemented in a numeric stable way without any restriction on the dimension d.
Similarly, the (cumulative) distribution function (“"the copula"” C()) is evaluated via the corresponding `acopula`-classed Archimedean copula's functions in the `psi` and `iPsi` slots.

### Value

An Archimedean copula object of class `"claytonCopula"`, `"frankCopula"`, `"gumbelCopula"`, `"amhCopula"`, or `"joeCopula"`.

### References

R.B. Nelsen (2006), An introduction to Copulas, Springer, New York.

### See Also

`acopula`-classed Archimedean copulas, such as `copClayton`, `copGumbel`, etc, notably for mathematical definitions including the meaning of `param`.

`fitCopula` for fitting such copulas to data.

`ellipCopula`, `evCopula`.

### Examples

    clayton.cop <- claytonCopula(2, dim = 3)
    ## scatterplot3d(rCopula(1000, clayton.cop))

    ## negative param (= theta) is allowed for dim = 2 :
    tau(claytonCopula(-0.5)) ## = -1/3
    tauClayton <- Vectorize(function(theta) tau(claytonCopula(theta, dim=2)))
    plot(tauClayton, -1, 10, xlab=quote(theta), ylim = c(-1,1), n=1025)
    abline(h=-1:1,v=0, col="#11111150", lty=2); axis(1, at=-1)

    tauFrank <- Vectorize(function(theta) tau(frankCopula(theta, dim=2)))
    plot(tauFrank, -40, 50, xlab=quote(theta), ylim = c(-1,1), n=1025)
    abline(h=-1:1,v=0, col="#11111150", lty=2)

    ## tauAMH() is function in our package
    iTau(amhCopula(), -1) # -1 with a range warning
    iTau(amhCopula(), (5 - 8*log(2)) / 3) # -1 with a range warning

    ic <- frankCopula(0) # independence copula (with a "message")
    stopifnot(identical(ic,
       frankCopula(0, use.indepC = "TRUE")))# indep.copula  withOUT message
    (fC <- frankCopula(0, use.indepC = "FALSE"))
    ## a Frank copula which corresponds to the indep.copula (but is not)

    frankCopula(dim = 3)# with NA parameters
    frank.cop <- frankCopula(3)# dim=2
    persp(frank.cop, dCopula)

    gumbel.cop <- archmCopula("gumbel", 5)
    stopifnot(identical(gumbel.cop, gumbelCopula(5)))
    contour(gumbel.cop, dCopula)

    amh.cop <- amhCopula(0.5)
    u. <- as.matrix(expand.grid(u=(0:10)/10, v=(0:10)/10, KEEP.OUT.ATTRS=FALSE))
    du <- dCopula(u., amh.cop)
    stopifnot(is.finite(du) | apply(u. == 0, 1,any)| apply(u. == 1, 1,any))

    ## A 7-dim Frank copula
    frank.cop <- frankCopula(3, dim = 7)
    x <- rCopula(5, frank.cop)
    ## dCopula now *does* work:
    dCopula(x, frank.cop)

    ## A 7-dim Gumbel copula
    gumbelC.7 <- gumbelCopula(2, dim = 7)
    dCopula(x, gumbelC.7)

    ## A 12-dim Joe copula
    joe.cop <- joeCopula(iTau(joeCopula(), 0.5), dim = 12)
    x <- rCopula(5, joe.cop)
    dCopula(x, joe.cop)

[Package copula version 1.0-1 Index]