R: Density, Evaluation, and Random Number Generation for Copula...

Copula {copula} | R Documentation

## Density, Evaluation, and Random Number Generation for Copula Functions

### Description

Density (`dCopula`), distribution function (`pCopula`), and random generation (`rCopula`) for a `copula` object.

### Usage

    dCopula(u, copula, log=FALSE, ...)
    pCopula(u, copula, ...)
    rCopula(n, copula, ...)

### Arguments

`copula` | an R object of class `"Copula"`, (i.e., `"copula"` or `"nacopula"`).
`u` | a vector of the copula dimension d or a matrix with d columns, giving the points where the density or distribution function needs to be evaluated. Note that in all cases, values outside of the cube [0,1]^d are treated equivalently to those on the cube boundary. So, e.g., the density is zero.
`log` | logical indicating if the log(f(.)) should be returned instead of f(.).
`n` | (for `rCopula()`:) number of observations to be generated.
`...` | further optional arguments for some methods, e.g., `method`.

### Details

The density (`dCopula`) and distribution function (`pCopula`) methods for Archimedean copulas now use the corresponding function slots of the Archimedean copula objects, such as `copClayton`, `copGumbel`, etc.

If an u[j] is outside (0,1) we declare the density to be zero, and this is true even when another u[k], k != j is `NA` or `NaN`; see also the “outside” example.

The distribution function of a `t` copula uses `pmvt` from package mvtnorm; similarly, the density (`dCopula`) calls `dmvt` from mvtnorm. The `normalCopula` methods use `dmvnorm` and `pmvnorm` from the same package.

The random number generator for an Archimedean copula uses the conditional approach for the bivariate case and the Marshall-Olkin (1988) approach for dimension greater than 2.

### Value

`dCopula()` gives the density, `pCopula()` gives the distribution function, and `rCopula()` generates random variates.

### References

Frees, E. W. and Valdez, E. A. (1998). Understanding relationships using copulas. North American Actuarial Journal 2, 1–25.

Genest, C. and Favre, A.-C. (2007). Everything you always wanted to know about copula modeling but were afraid to ask. Journal of Hydrologic Engineering 12, 347–368.

Joe, H. (1997). Multivariate Models and Dependence Concepts. Chapman and Hall, London.

Marshall, A. W. and Olkin, I. (1988) Families of multivariate distributions. Journal of the American Statistical Association 83, 834–841.

Nelsen, R. B. (2006) An introduction to Copulas. Springer, New York.

### See Also

the `copula` and `acopula` classes, the acopula families, `acopula-families`. Constructor functions such as `ellipCopula`, `archmCopula`, `fgmCopula`.

### Examples

    norm.cop <- normalCopula(0.5)
    norm.cop
    ## one d-vector =^= 1-row matrix, works too :
    dCopula(c(0.5, 0.5), norm.cop)
    pCopula(c(0.5, 0.5), norm.cop)

    u <- rCopula(100, norm.cop)
    plot(u)
    dCopula(u, norm.cop)
    pCopula(u, norm.cop)
    persp  (norm.cop, dCopula)
    contour(norm.cop, pCopula)

    ## a 3-dimensional normal copula
    u <- rCopula(1000, normalCopula(0.5, dim = 3))
    if(require(scatterplot3d))
      scatterplot3d(u)

    ## a 3-dimensional clayton copula
    cl3 <- claytonCopula(2, dim = 3)
    v <- rCopula(1000, cl3)
    pairs(v)
    if(require(scatterplot3d))
      scatterplot3d(v)

    ## Compare with the "nacopula" version :
    fu1 <- dCopula(v, cl3)
    fu2 <- copClayton@dacopula(v, theta = 2)
    Fu1 <- pCopula(v, cl3)
    Fu2 <- pCopula(v, onacopula("Clayton", C(2.0, 1:3)))
    ## The density and cumulative values are the same:
    stopifnot(all.equal(fu1, fu2, tolerance= 1e-14),
              all.equal(Fu1, Fu2, tolerance= 1e-15))

    ## NA and "outside" u[]
    u <- v[1:12,]
    ## replace some by values outside (0,1) and some by NA/NaN
    u[1, 2:3] <- c(1.5, NaN); u[2, 1] <- 2; u[3, 1:2] <- c(NA, -1)
    u[cbind(4:9, 1:3)] <- c(NA, NaN)
    f <- dCopula(u, cl3)
    cbind(u, f) # note: f(.) == 0 at [1] and [3] inspite of NaN/NA
    stopifnot(f[1:3] == 0, is.na(f[4:9]), 0 < f[10:12])

[Package copula version 1.0-1 Index]