copula (version 0.999-19)

khoudrajiCopula: Construction of copulas using Khoudraji's device

Description

Creates an object representing a copula constructed using Khoudraji's device (Khoudraji, 1995). The resulting R object is either of class "'>khoudrajiBivCopula", "'>khoudrajiExplicitCopula" or "'>khoudrajiCopula".

In the bivariate case, given two copulas \(C_1\) and \(C_2\), Khoudraji's device consists of defining a copula whose c.d.f. is given by:

$$C_1(u_1^{1 - a_1}, u_2^{1 - a_2}) C_2(u_1^{a_1}, u_2^{a_2})$$

where \(a_1\) and \(a_2\) are shape parameters in [0,1].

The construction principle (see also Genest et al. 1998) is a special case of that considered in Liebscher (2008).

Usage

khoudrajiCopula(copula1 = indepCopula(), copula2 = indepCopula(dim = d),
                shapes = rep(NA_real_, dim(copula1)))

Arguments

copula1, copula2

each a '>copula (possibly generalized, e.g., also a "'>rotCopula") of the same dimension \(d\). By default independence copulas, where copula2 gets the dimension from copula1.

shapes

numeric vector of length \(d\), with values in \([0,1]\).

Value

A new object of class "'>khoudrajiBivCopula" in dimension two or of class "'>khoudrajiExplicitCopula" or "'>khoudrajiCopula" when \(d > 2\).

Details

If the argument copulas are bivariate, an object of class "'>khoudrajiBivCopula" will be constructed. If they are exchangeable and \(d\)-dimensional with \(d > 2\), and if they have explicit p.d.f. and c.d.f. expressions, an object of class "'>khoudrajiExplicitCopula" will be constructed. For the latter two classes, density evaluation is implemented, and fitting and goodness-of-fit testing can be attempted. If \(d > 2\) but one of the argument copulas does not have explicit p.d.f. and c.d.f. expressions, or is not exchangeable, an object of class "'>khoudrajiCopula" will be constructed, for which density evaluation is not possible.

References

Genest, C., Ghoudi, K., and Rivest, L.-P. (1998), Discussion of "Understanding relationships using copulas", by Frees, E., and Valdez, E., North American Actuarial Journal 3, 143--149.

Khoudraji, A. (1995), Contributions <U+00E0> l'<U+00E9>tude des copules et <U+00E0>la mod<U+00E9>lisation des valeurs extr<U+00EA>mes bivari<U+00E9>es, PhD thesis, Universit<U+00E9> Laval, Qu<U+00E9>bec, Canada.

Liebscher, E. (2008), Construction of asymmetric multivariate copulas, Journal of Multivariate Analysis 99, 2234--2250.

Examples

Run this code
# NOT RUN {
## A bivariate Khoudraji-Clayton copula
kc <- khoudrajiCopula(copula2 = claytonCopula(6),
                      shapes = c(0.4, 0.95))
class(kc) # "kh..._Biv_Copula"
kc
contour(kc, dCopula, nlevels = 20, main = "dCopula(<khoudrajiBivCopula>)")

## A Khoudraji-Clayton copula with second shape parameter fixed
kcf <- khoudrajiCopula(copula2 = claytonCopula(6),
                       shapes = fixParam(c(0.4, 0.95), c(FALSE, TRUE)))
kcf. <- setTheta(kcf, c(3, 0.2)) # (change *free* param's only)
validObject(kcf) & validObject(kcf.)

## A "nested" Khoudraji bivariate copula
kgkcf <- khoudrajiCopula(copula1 = gumbelCopula(3),
                         copula2 = kcf,
                         shapes = c(0.7, 0.25))
kgkcf # -> 6 parameters (1 of 6 is 'fixed')
contour(kgkcf, dCopula, nlevels = 20,
        main = "dCopula(<khoudrajiBivC.(nested)>)")

(Xtras <- copula:::doExtras()) # determine whether examples will be extra (long)
n <- if(Xtras) 300 else 64 # sample size (realistic vs short for example)
# }
# NOT RUN {
<!-- % reproducibility -->
# }
# NOT RUN {
u <- rCopula(n, kc)
plot(u)

## For likelihood (or fitting), specify the "free" (non-fixed) param's:
##           C1:  C2c C2s1    sh1  sh2
loglikCopula(c(3,   6, 0.4,   0.7, 0.25),
             u = u, copula = kgkcf)

## Fitting takes time (using numerical differentiation) and may be difficult:

## Starting values are required for all parameters
f.IC <- fitCopula(khoudrajiCopula(copula2 = claytonCopula()),
                  start = c(1.1, 0.5, 0.5), data = pobs(u),
                  optim.method = "Nelder-Mead")
summary(f.IC)
confint(f.IC) # (only interesting for reasonable sample size)

## Because of time,  don't run these by default :
# }
# NOT RUN {
## Second shape parameter fixed to 0.95
kcf2 <- khoudrajiCopula(copula2 = claytonCopula(),
                        shapes = fixParam(c(NA_real_, 0.95), c(FALSE, TRUE)))
system.time(
f.ICf <- fitCopula(kcf2, start = c(1.1, 0.5), data = pobs(u),
                   optim.method = "Nelder-Mead")
) # ~ 7-8 sec
confint(f.ICf) # !
coef(f.ICf, SE=TRUE)

## With a different optimization method
system.time(
f.IC2 <- fitCopula(kcf2, start = c(1.1, 0.5), data = pobs(u),
                   optim.method = "BFGS")
)
printCoefmat(coef(f.IC2, SE=TRUE), digits = 3) # w/o unuseful extra digits


if(Xtras >= 2) { # really S..L..O..W... --------

## GOF example
optim.method <- "Nelder-Mead" #try "BFGS" as well
gofCopula(kcf2, x = u, start = c(1.1, 0.5), optim.method = optim.method)
gofCopula(kcf2, x = u, start = c(1.1, 0.5), optim.method = optim.method,
          sim = "mult")
## The goodness-of-fit tests should hold their level
## but this would need to be tested

## Another example under the alternative
u <- rCopula(n, gumbelCopula(4))
gofCopula(kcf2, x = u, start = c(1.1, 0.5), optim.method = optim.method)
gofCopula(kcf2, x = u, start = c(1.1, 0.5), optim.method = optim.method,
          sim = "mult")

}## ------ end { really slow gofC*() } --------

## Higher-dimensional constructions

## A three dimensional Khoudraji-Clayton copula
kcd3 <- khoudrajiCopula(copula1 = indepCopula(dim=3),
                        copula2 = claytonCopula(6, dim=3),
                        shapes = c(0.4, 0.95, 0.95))

n <- if(Xtras) 1000 else 100 # sample size (realistic vs short for example)
u <- rCopula(n, kcd3)
splom2(u)
v <- matrix(runif(15), 5, 3)
dCopula(v, kcd3)

## A four dimensional Khoudraji-Normal copula
knd4 <- khoudrajiCopula(copula1 = indepCopula(dim=4),
                        copula2 = normalCopula(.9, dim=4),
                        shapes = c(0.4, 0.95, 0.95, 0.95))
knd4
stopifnot(class(knd4) == "khoudrajiCopula")
u <- rCopula(n, knd4)
splom2(u)
## TODO :
## dCopula(v, knd4) ## not implemented
# }

Run the code above in your browser using DataCamp Workspace