archmCopula {copula}

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 \theta, 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 \le \theta, and for Frank -\infty < \theta. The respective boundary cases are

AMH:

\tau(\theta = -1) = -0.1817258,

Clayton:

\tau(\theta = -1) = -1,

Frank:

\tau(\theta = -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)