R: Construction of Elliptical Copula Class Objects

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, df.min = 0.01)

    ## S4 method for signature 'matrix,normalCopula'
    pCopula(u, copula, algorithm = NULL, ...)

    ## S4 method for signature 'matrix,tCopula'
    pCopula(u, copula, algorithm = NULL, ...)

### 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`.
`df.min` | non-negative number; the strict lower bound for `df`, mainly during fitting when `df.fixed=FALSE`, with `fitCopula`.

`copula` | an R object of class `"Copula"`, in our case inheriting from `"ellipCopula"`.
`u` | a vector of the copula dimension d or a matrix with d columns, giving the points where the distribution function needs to be evaluated. Note that values outside of the cube [0,1]^d are treated equivalently to those on the cube boundary.
  `algorithm` | `NULL` or an `"algorithm"` object for package mvtnorm's `pmvt()` or `pmvnorm()` functions, see `algorithms`. Note that for larger dimensions, the monte-carlo based `GenzBretz(..)` must be used, consequently with slightly random results. By default, `algorithm = NULL`, `algorithm` is chosen separately for each row `x <- u[i,]`, for `normalCopula`: via hidden function `pmvnormAlgo(dim, x, ...)` which currently is defined as
       pmvnormAlgo <- function(dim, x, ...) {
          if(dim <= 3 && !anyNA(x) && (!any(xI <- x == Inf) || all(xI)))
              TVPACK(...)
          else if(dim <= 5)
              Miwa(...)
          else
              GenzBretz(...)
        }
`tCopula`: via (hidden) `pmvtAlgo(dim, x, ...)` which is the same as `pmvnormAlgo()` above, but as `Miwa()` is not applicable, without the `else if(dim <= 5) Miwa(...)` clause.
`...` | for the `pCopula()` methods, optional arguments to the corresponding algorithm.

### 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)
    stopifnot(all.equal(toeplitz(c(1, .5, .3)), getSigma(t.cop)))

    ## dispersion "AR1" :
    nC.7 <- normalCopula(0.8, dim = 7, dispstr = "ar1")
    getSigma(nC.7)
    stopifnot(all.equal(toeplitz(.8^(0:6)), getSigma(nC.7)))

    ## 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' :
    has_mvtn <- "package:mvtnorm" %in% search()
    if(!has_mvtn)
      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')
    if(!has_mvtn)
       detach("package:mvtnorm")# (revert)

    ## 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 1.0-1 Index]