R: Conditional Distributions and Their Inverses from Copulas

cCopula {copula} | R Documentation

## Conditional Distributions and Their Inverses from Copulas

### Description

Compute the conditional distribution 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, drop = 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` | 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` | copula, i.e., an object of class `"Copula"` with specified parameters; currently, the conditional distribution is only provided for Archimedean and elliptical copulas.
`indices` | vector of indices j (in {1,..,d} (d = copula dimension); unique; sorted in increasing order) for which C_{j|1,…,j-1}(u[j]|u[1],...,u[j-1]) (or, if `inverse = TRUE`, C^-_{j|1,…,j-1}(u[j]|u[1],...,u[j-1])) is computed.
`inverse` | `logical` indicating whether the inverse C^-_{j|1,…,j-1}(u[j]|u[1],...,u[j-1]) is returned.
`n.MC` | integer Monte Carlo sample size; for Archimedean copulas only, used if positive.
`log` | a `logical` indicating whether the logarithmic values are returned.
`drop` | a `logical` indicating whether a vector should be returned (instead of a 1–row matrix) when `n` is 1.
`...` | additional arguments (currently only used if `inverse = TRUE` in which case they are passed on to the underlying `uniroot()`).

### Details

By default and if fed with a sample of the corresponding copula, `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.

### Value

An (n, k)-`matrix` (unless `n == 1` and `drop` is true, where a k-vector is returned) where k is the length of `indices`. This matrix contains the conditional copula function values C_{j|1,…,j-1}(u[j]|u[1],...,u[j-1]) or, if `inverse = TRUE`, their inverses C^-_{j|1,…,j-1}(u[j]|u[1],...,u[j-1]) for all j in `indices`.

### Note

For some (but not all) families, this function also makes sense on the boundaries (if the corresponding limits can be computed).

### 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 from a conditional distribution of a 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 = quote(U[2]))

    ## A large u_1
    u1 <- 0.95
    U <- cCopula(cbind(u1, runif(n)), copula = cc, inverse = TRUE)
    plot(U[,2], ylab = quote(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)
    U.Rt <- cCopula(U, copula = f.t@copula) # transform with a fitted t copula
    splom2(U.Rt, cex = 0.2) # still visible but not so clear

    ## Inverse (and check consistency)
    U.N <- cCopula(U.RN, copula = fN @copula, inverse = TRUE)
    U.t <- cCopula(U.Rt, copula = f.t@copula, inverse = TRUE)

    tol <- 1e-14
    stopifnot(
        all.equal(U, U.N),
        all.equal(U, U.t),
        all.equal(log(U.RN),
                  cCopula(U, copula = fN @copula, log = TRUE), tolerance = tol),
        all.equal(log(U.Rt),
                  cCopula(U, copula = f.t@copula, log = TRUE), tolerance = tol)
    )

    ## 4) cCopula() for a more sophisticated mixture copula (bivariate case only!)

    tau <- 0.5
    cc <- claytonCopula(iTau(claytonCopula(), tau = tau)) # first mixture component
    tc <- tCopula(iTau(tCopula(), tau = tau), df = 3) # t_3 copula
    tc90 <- rotCopula(tc, flip = c(TRUE, FALSE)) # t copula rotated by 90 degrees
    wts <- c(1/2, 1/2) # mixture weights
    mc <- mixCopula(list(cc, tc90), w = wts) # mixture copula with one copula rotated

    set.seed(271)
    U <- rCopula(n, copula = mc)
    U. <- cCopula(U, copula = mc) # Rosenblatt transform back to U(0,1)^2 (as a check)
    plot(U., xlab = quote(U*"'"[1]), ylab = quote(U*"'"[2])) # check for uniformity

[Package copula version 1.0-1 Index]