Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

ellipCopula

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.

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")
copula

Multivariate Dependence with Copulas

v1.0-1
GPL (>= 3) | file LICENCE
Authors
Marius Hofert [aut] (<https://orcid.org/0000-0001-8009-4665>), Ivan Kojadinovic [aut] (<https://orcid.org/0000-0002-2903-1543>), Martin Maechler [aut, cre] (<https://orcid.org/0000-0002-8685-9910>), Jun Yan [aut] (<https://orcid.org/0000-0003-4401-7296>), Johanna G. Nešlehová [ctb] (evTestK(), <https://orcid.org/0000-0001-9634-4796>), Rebecca Morger [ctb] (fitCopula.ml(): code for free mixCopula weight parameters)
Initial release
2020-12-07

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.