ellipCopula {copula} | R Documentation

## Construction of Elliptical Copula Class Objects

### Description

Constructs an elliptical copula class object with its corresponding parameters and dimension.

### Usage

    ellipCopula (family, param, dim = 2, dispstr = "ex", df = 4, ...)
    normalCopula(param, dim = 2, dispstr = "ex")
        tCopula (param, dim = 2, dispstr = "ex", df = 4, df.fixed = FALSE)

### Arguments

`family` | a character string specifying the family of an elliptical copula. Must be `"normal"` (the default) or `"t"`.
`param` | a numeric vector specifying the parameter values; `P2p()` accesses this vector, whereas `p2P()` and `getSigma()` provide the corresponding “P” matrix, see below.
`dim` | the dimension of the copula.
`dispstr` | a character string specifying the type of the symmetric positive definite matrix characterizing the elliptical copula. Currently available structures are `"ex"` for exchangeable, `"ar1"` for AR(1), `"toep"` for Toeplitz (`toeplitz`), and `"un"` for unstructured.
`df` | integer value specifying the number of degrees of freedom of the multivariate t distribution used to construct the t copulas.
`df.fixed` | logical specifying if the degrees of freedom `df` will be considered as a parameter (to be estimated) or not. The default, `FALSE`, means that `df` is to be estimated if the object is passed as argument to `fitCopula`.
`...` | currently nothing.

### Value

An elliptical copula object of class `"normalCopula"` or `"tCopula"`.

### Note

`ellipCopula()` is a wrapper for `normalCopula()` and `tCopula()`.

The `pCopula()` methods for the normal- and t-copulas accept optional arguments to be passed to the underlying (numerical integration) algorithms from package mvtnorm's `pmvnorm` and `pmvt`, respectively, notably `algorithm`, see `GenzBretz`, or `abseps` which defaults to `0.001`. ## For smaller copula dimension 'd', alternatives are available and ## non-random, see ?GenzBretz from package 'mvtnorm'

### See Also

`p2P()`, and `getSigma()` for construction and extraction of the dispersion matrix P or Sigma matrix of (generalized) correlations.

`archmCopula`, `fitCopula`.

### Examples

    norm.cop <- normalCopula(c(0.5, 0.6, 0.7), dim = 3, dispstr = "un")
    t.cop <- tCopula(c(0.5, 0.3), dim = 3, dispstr = "toep",
                     df = 2, df.fixed = TRUE)
    getSigma(t.cop) # P matrix (with diagonal = 1)

    ## from the wrapper
    norm.cop <- ellipCopula("normal", param = c(0.5, 0.6, 0.7),
                            dim = 3, dispstr = "un")
    if(require("scatterplot3d") && dev.interactive(orNone=TRUE)) {
      ## 3d scatter plot of 1000 random observations
      scatterplot3d(rCopula(1000, norm.cop))
      scatterplot3d(rCopula(1000, t.cop))
    }
    set.seed(12)
    uN <- rCopula(512, norm.cop)
    set.seed(2); pN1 <- pCopula(uN, norm.cop)
    set.seed(3); pN2 <- pCopula(uN, norm.cop)
    stopifnot(all.equal(pN1, pN2, 1e-4))# see 5.711e-5
    (Xtras <- copula:::doExtras())
    if(Xtras) { ## a bit more accurately:
      set.seed(4); pN1. <- pCopula(uN, norm.cop, abseps = 1e-9)
      set.seed(5); pN2. <- pCopula(uN, norm.cop, abseps = 1e-9)
      stopifnot(all.equal(pN1., pN2., 1e-5))# see 3.397e-6
      ## but increasing the required precision (e.g., abseps=1e-15) does *NOT* help
    }

    ## For smaller copula dimension 'd', alternatives are available and
    ## non-random, see ?GenzBretz from package 'mvtnorm' :
    require("mvtnorm")# -> GenzBretz(), Miva(), and TVPACK() are available
    ## Note that Miwa() would become very slow for dimensions 5, 6, ..
    set.seed(4); pN1.M <- pCopula(uN, norm.cop, algorithm = Miwa(steps = 512))
    set.seed(5); pN2.M <- pCopula(uN, norm.cop, algorithm = Miwa(steps = 512))
    stopifnot(all.equal(pN1.M, pN2.M, tol= 1e-15))# *no* randomness
    set.seed(4); pN1.T <- pCopula(uN, norm.cop, algorithm = TVPACK(abseps = 1e-10))
    set.seed(5); pN2.T <- pCopula(uN, norm.cop, algorithm = TVPACK(abseps = 1e-14))
    stopifnot(all.equal(pN1.T, pN2.T, tol= 1e-15))# *no* randomness (but no effect of 'abseps')

    ## Versions with unspecified parameters:
    tCopula()
    allEQ <- function(u,v) all.equal(u, v, tolerance=0)
    stopifnot(allEQ(ellipCopula("norm"), normalCopula()),
              allEQ(ellipCopula("t"), tCopula()))
    tCopula(dim=3)
    tCopula(dim=4, df.fixed=TRUE)
    tCopula(dim=5, disp = "toep", df.fixed=TRUE)
    normalCopula(dim=4, disp = "un")

[Package copula version 0.999-15 Index]