copula (version 0.999-15)

cCopula: Conditional Copula Function and Its Inverse

Description

Compute the conditional distribution aka conditional copula function, $C(u[d] | u[1],..., u[d-1])$ of $u[d]$ given $u[1],..., u[d-1]$.

Usage

cCopula(u, copula, indices = 1:dim(copula), inverse = FALSE, log = FALSE, ...)
## Deprecated (use cCopula() instead):
rtrafo(u, copula, indices = 1:dim(copula), inverse = FALSE, log = FALSE)
cacopula(u, cop, n.MC = 0, log = FALSE)

Arguments

u

A data matrix in $[0,1]^(n, d)$ of $U(0,1)^d$ samples if inverse = FALSE and (pseudo-/copula-)observations if inverse = TRUE.

copula, cop

An object of class "Copula" with specified parameters; currently only Archimedean and elliptical copulas are provided.

indices

A vector of indices $j$ (in ${1,..,d}$ ($d =$ copula dimension); unique; sorted in increasing order) for which $C_{j|1,\dots,j-1}(u[j]|u[1],...,u[j-1])$ (or, if inverse = TRUE, $C^-_{j|1,\dots,j-1}(u[j]|u[1],...,u[j-1])$) is computed.

inverse

A logical indicating whether the inverse $C^-_{j|1,\dots,j-1}(u[j]|u[1],...,u[j-1])$ is returned.

n.MC

Monte Carlo sample size; for Archimedean copulas only, used if positive.

log

A logical indicating whether the logarithmic values are returned.

...

Additional arguments (currently only used if inverse = TRUE in which case they are passed on to the underlying uniroot()).

Value

An $(n, k)$-matrix where $k$ denotes the length of indices. This matrix contains the conditional copula function values $C_{j|1,\dots,j-1}(u[j]|u[1],...,u[j-1])$ or, if inverse = TRUE, their inverses $C^-_{j|1,\dots,j-1}(u[j]|u[1],...,u[j-1])$ for all $j$ in indices.

Details

By default, cCopula() computes the Rosenblatt transform; see Rosenblatt (1952). The involved high-order derivatives for Archimedean copulas were derived in Hofert et al. (2012).

Sampling, that is, random number generation, can be achieved by using inverse=TRUE. In this case, the inverse Rosenblatt transformation is used, which, for sampling purposes, is also known as conditional distribution method. Note that, for Archimedean copulas not being Clayton, this can be slow as it involves numerical root finding in each (but the first) component.

References

Genest, C., Rémillard, B., and Beaudoin, D. (2009). Goodness-of-fit tests for copulas: A review and a power study. Insurance: Mathematics and Economics 44, 199--213.

Rosenblatt, M. (1952). Remarks on a Multivariate Transformation, The Annals of Mathematical Statistics 23, 3, 470--472.

Hofert, M., Mächler, M., and McNeil, A. J. (2012). Likelihood inference for Archimedean copulas in high dimensions under known margins. Journal of Multivariate Analysis 110, 133--150.

See Also

htrafo; acopula-families.

Examples

## 1) Sampling a conditional Clayton copula given u_1

## Define the copula
tau <- 0.5
theta <- iTau(claytonCopula(), tau = tau)
d <- 2
cc <- claytonCopula(theta, dim = d)
n <- 1000
set.seed(271)

## A small u_1
u1 <- 0.05
U <- cCopula(cbind(u1, runif(n)), copula = cc, inverse = TRUE)
plot(U[,2], ylab = expression(U[2]))

## A large u_1
u1 <- 0.95
U <- cCopula(cbind(u1, runif(n)), copula = cc, inverse = TRUE)
plot(U[,2], ylab = expression(U[2]))


## 2) Sample via conditional distribution method and then apply the
##    Rosenblatt transform
##    Note: We choose the numerically more involved (and thus slower)
##          Gumbel case here

## Define the copula
tau <- 0.5
theta <- iTau(gumbelCopula(), tau = tau)
d <- 5
gc <- gumbelCopula(theta, dim = d)
n <- 200
set.seed(271)
U. <- matrix(runif(n*d), ncol = d) # U(0,1)^d


## Transform to Gumbel sample via conditional distribution method
U <- cCopula(U., copula = gc, inverse = TRUE) # slow for ACs except Clayton
splom2(U) # scatter-plot matrix copula sample

## Rosenblatt transform back to U(0,1)^d (as a check)
U. <- cCopula(U, copula = gc)
splom2(U.) # U(0,1)^d again


## 3) cCopula() for elliptical copulas

tau <- 0.5
theta <- iTau(claytonCopula(), tau = tau)
d <- 5
cc <- claytonCopula(theta, dim = d)
set.seed(271)
n <- 1000
U <- rCopula(n, copula = cc)
X <- qnorm(U) # X now follows a meta-Clayton model with N(0,1) marginals
U <- pobs(X) # build pseudo-observations
fN <- fitCopula(normalCopula(dim = d), data = U) # fit a Gauss copula
U.RN <- cCopula(U, copula = fN@copula)
splom2(U.RN, cex = 0.2) # visible but not so clearly
f.t <- fitCopula(tCopula(dim = d), U)
tc <- f.t@copula
U.Rt <- cCopula(U, copula = tc) # transform with a fitted t copula
splom2(U.Rt, cex = 0.2) # still visible but not so clear
tol <- 1e-14
stopifnot(
    all.equal(log(U.RN),
              cCopula(U, copula = fN@copula, log = TRUE), tolerance = tol),
    all.equal(log(U.Rt),
              cCopula(U, copula = tc, log = TRUE), tolerance = tol),
    TRUE)