copula (version 0.999-15)

archmCopula: 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".

Value

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

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=""

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

The maximum dimension for which the expression of the pdf is available is 6 for the Clayton, Gumbel and Frank families. The cdf expression is always available.

For $d > 2$, i.e. dim > 2, it is now recommended to work with the acopula-classed Archimedean copulas, as there is no restriction on the dimension there.

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)
dCopula(x, joe.cop)