R: Archimax and generic copula distribution functions

xCopula {acopula}

R Documentation

Archimax and generic copula distribution functions

Description

Copula cumulative distribution function ('p'), probability density function ('d'), conditional probability cdf (c), quantile (q), random vector sampling ('r'), parameters estimation ('e'), goodness-of-fit test ('g'), checking copula properties ('is').

Usage

pCopula(data, generator=genGumbel(), depfun=dep1(), copula=NULL, 
  gpars=generator$parameters, dpars=depfun$parameters, 
  pars=if(is.null(copula)) list(gpars,dpars) else copula$parameters,
  subdivisions=50, quantile=NULL,probability=data[,quantile])
  
pCopulaEmpirical(data, base = data)

dCopula(data,generator=genGumbel(),depfun=dep1(),copula=NULL,
  gpars=generator$parameters, dpars=depfun$parameters,
  pars=if(is.null(copula)) list(gpars,dpars) else copula$parameters,
  difference=1e-4,area=c(0), shrinkdiff=FALSE)

cCopula(data, conditional.on=c(1), generator=genGumbel(), depfun=dep1(), copula=NULL, 
  gpars=generator$parameters, dpars=depfun$parameters, 
  pars=if(is.null(copula)) list(gpars,dpars) else copula$parameters, 
  difference=1e-4,area=c(0), quantile=NULL, probability=data[,quantile])

qCopula(data, quantile=1, probability=0.95, conditional.on=NULL,
  generator=genGumbel(), depfun=dep1(), copula=NULL, 
  gpars=generator$parameters, dpars=depfun$parameters, 
  pars=if(is.null(copula)) list(gpars,dpars) else copula$parameters, 
  difference=1e-4, area=c(0))

rCopula(n, dim=2, generator=genGumbel(), depfun=dep1(), copula=NULL, 
  gpars=generator$parameters, dpars=depfun$parameters,
  pars=if(is.null(copula)) list(gpars,dpars) else copula$parameters)
                    
rCopulaArchimax2D(n, generator=genLog(), depfun=dep1(), 
  gpars=generator$parameters, dpars=depfun$parameters, pars=list(gpars,dpars))

eCopula(data, generator=genGumbel(), depfun=dep1(), copula=NULL,
  glimits=list(generator$lower,generator$upper), dlimits=list(depfun$lower,depfun$upper),
  limits=list(copula$lower,copula$upper),
  ggridparameters=if(!is.null(unlist(glimits))) do.call(
    function(...) mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), glimits) else NULL, 
  dgridparameters=if(!is.null(unlist(dlimits))) do.call(
    function(...) mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), dlimits) else NULL, 
  gridparameters=if(!is.null(unlist(limits))) do.call(function(...) 
    mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), limits) else NULL,
  technique=c("ML","LS","icorr"), procedure=c("optim","nlminb","nls","grid"), 
  method="default", corrtype = c("kendall","spearman"), control=NULL, pgrid=10)

gCopula(data, generator, depfun=dep1(), copula=NULL,
  glimits=list(generator$lower,generator$upper), 
  dlimits=list(depfun$lower,depfun$upper),
  limits=list(copula$lower,copula$upper),
  etechnique=c("ML","LS","icorr"), eprocedure=c("optim","nlminb","nls"), 
  emethod="default", ecorrtype=c("kendall","spearman"), econtrol=NULL,  
  N=100, m=nrow(data), ncores=1)

gCopulaEmpirical(data,N=100,ncores=1)

isCopula(generator=genLog(),depfun=dep1(), copula=NULL,
  glimits=list(generator$lower,generator$upper), 
  dlimits=list(depfun$lower,depfun$upper),
  limits=list(copula$lower,copula$upper),  
  ggridparameters=if(!is.null(unlist(glimits))) do.call(
    function(...) mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), glimits) else NULL,
  dgridparameters=if(!is.null(unlist(dlimits))) do.call(
    function(...) mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), dlimits) else NULL, 
  gridparameters=if(!is.null(unlist(limits))) do.call(
    function(...) mapply(c,...,length.out=pgrid,SIMPLIFY=FALSE), limits) else NULL,
  dagrid=10, pgrid=10, dim=3, tolerance=1e-15)


## S3 method for class 'eCopulaArchimax'
print(x,...)
## S3 method for class 'eCopulaGeneric'
print(x,...)
## S3 method for class 'gCopula'
print(x,...)
## S3 method for class 'isCopula'
print(x,...)

Arguments

`data`	vector, matrix or data frame with as many columns as variables. List of two such objects in case of `gCopulaEmpirical`.
`generator`	list containing archimedean generator, it's inverse, parameter bounds and possibly derivatives. See `generator`.
`depfun`	list containing Pickand's dependence function, parameter bounds and possibly derivatives. See `depfun`.
`copula`	list containing generic copula CDF and/or PDF, parameter values and bounds. See `copula`.
`pars`	either numeric vector of generic copula parameters, or list of two vectors: generator parameters and dependence function parameters.
`gpars`	numeric vector of `generator` parameters, `NULL` in trivial case.
`dpars`	numeric vector of `depfun` parameters, `NULL` in trivial case.
`quantile`	numeric. Index of the quantile variable among other variables; if `NULL` (default) then no quantile is computed.
`probability`	numeric. Probability corresponding to the wanted quantile. Replicated to length of the data. By default `quantile`-th column of `data`.
`subdivisions`	integer. Parameter passed to `nintegrate`.
`difference`	parameter passed to `nderive`.
`base`	data.frame or matrix. Data set from which an empirical copula is constructed.
`area`	parameter passed to `nderive`.
`shrinkdiff`	logical. Whether to shrink `difference` if [0,1] interval is exceeded. By default, `area` is changed instead.
`conditional.on`	numeric. Index of variables to be conditioned on.
`n`	number of random observations to be generated.
`dim`	number of dimensions of copula = number of variables.
`glimits`, `dlimits`, `limits`	list of two vectors: lower and upper bound of `generator`, `depfun` and generic copula parameters, respectively.
`technique`, `etechnique`	copula parameters estimation method: Maximum pseudo-likelihood `"ML"`, Least square distance to empirical copula `"LS"` and Inversion of correlation coefficient relation to copula parameter `"icorr"`.
`procedure`, `eprocedure`	R optimization routine to estimate parameters (`"optim"`, `"nlminb"`, `"nls"`) or "brute force" search over parameter grid (`"grid"`). The last one is useful when the other methods give unsatisfactory results. `"nls"` cannot be used with ML technique. Ignored with "icorr" technique.
`method`, `emethod`	optimisation algorithm used by `optim` procedure.
`corrtype`, `ecorrtype`	character. Correlation coeficient used by `icorr` technique, either "kendall" and "spearman".
`control`, `econtrol`	list of control settings passed to optimization routines.
`ggridparameters`, `dgridparameters`, `gridparameters`	list of parameters values to create a grid from; any list item can be vector of elements named to match `seq()` arguments; by default the sequence is constructed from `glimits`,`dlimits`,`limits`, respectively, and `pgrid`.
`pgrid`	number of grid points in each dimension of parameters space. Used when `gparameters, dparameters` are not supplied.
`N`	number of bootstrap cycles.
`m`	number of Monte Carlo cyles needed in approximation of parametric function if there is no analytical expression available.
`ncores`	number of cores to be used for p-value simulation. Parallelization requires package `parallel` or `multicore` and may not work on Windows OS.
`dagrid`	integer. Number of data grid nodes used to check copula properties in.
`tolerance`	numeric. How much to tolerate departure of numeric results from theoretical values/limits.
`x`	an object used to select a method.
`...`	further arguments passed to or from other methods.

Value

Numeric vector, in case of p,d,c and qCopula.

Matrix from rCopula.

eCopula returns list containing

`parameters`	list of numeric vectors. Generator, depfu or generic copula parameters.
`approach`	character vector of length 3 describing estimation and optimization method.
`fvalue`	numeric. Value of the optimized function.
`procedure.output`	list. Full outcome of an optimization function.

gCopula and gCopulaEmpirical return list containing

`statistic`	numeric. GOF test statistic.
`q95`	numeric. 95% quantile or critical value from bootstrap simulations.
`p.value`	numeric. p-value from bootstrap simulations.
`estimate`	numeric vector. Copula parameters estimates.
`data.name`	character. Name of the supplied data object.
`method`	character. Identification of GoF test used.
`fitting_method`	character vector of length 3. Sumarizes estimation and optimiztion method.
`copula_id`	character. Generator and depfu id, or copula id.

isCopula returns list containing

`is.copula`	logical. FALSE if any of copula properties is violated.
`issues`	data frame. Consists of 1) index of variable, 2) violated property, 3) deviation from allowed range, 4) copula parameters for which the issue emerged.

Author(s)

Tomas Bacigal

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.

Rémillard, B., Scaillet, O. (2009): Testing for equality between two copulas. Journal of Multivariate Analysis 100(3), 377–386.

Examples

## assign generator definition list with specific parameter
ge <- genGumbel(parameters=4)

## probability P(U<0.3,V<0.5)
pCopula(c(0.3,0.5),ge)  #0.2906142
## quantile q for which P(U<q,V<0.5)=0.2906142
pCopula(c(0.2906142,0.5),ge,quantile=1)  #0.3000175
pCopula(c(NA,0.5),ge,quantile=1,probability=0.2906142)
qCopula(c(0.5),quantile=1,probability=0.2906142,generator=ge)

## conditional probability P(U<0.3|V=0.5)
cCopula(c(0.3,0.5),ge,conditional.on=2)  #0.1025705
## quantile q for which conditional probability P(U<q|V=0.5)=0.1025705
cCopula(c(0.1025705,0.5),conditional.on=2,generator=ge,quantile=1)  #0.2999861
cCopula(c(NA,0.5),conditional.on=2,generator=ge,quantile=1,probability=0.1025705)
qCopula(c(0.5),quantile=1,probability=0.1025705,conditional.on=2,generator=ge)

## copula density
dCopula(c(0.3,0.5),ge) #1.083797
local({
x <- y <- seq(0,1,length.out=20)
persp(x,y,matrix(dCopula(expand.grid(x,y),ge),nrow=length(x)),r=2,zlab="density")
})

## simulate random vector
rge <- rCopula(100,dim=2,ge) 
plot(rge)
# Observe that using rCopula(100,dim=2,cop=copGumbel(parameters=4)) 
# would take much more time to sample, since numerical derivative needs to be employed. 

## --- fit copula to data set
# maximum likelihood (using density)
eCopula(rge,ge,technique="ML")
# some methods has no support for parameters bounds (do not mind a warning message)
eCopula(rge,ge,technique="ML",method="BFGS")  
# least-square fit to empirical copula
eCopula(rge,ge,technique="LS",procedure="nlminb")  
# maximizing discretized likelihood function
eCopula(rge,ge,technique="ML",procedure="grid",glimits=list(2.,6.),pgrid=20)  
# specify nodes of the grid
eCopula(rge,ge,tech="ML",proc="grid",ggridparameters=list(c(2.,6.,length.out=20))) 
# without naming, it won't create sequence
eCopula(rge,ge,technique="ML",procedure="grid",ggridparameters=list(c(2.,6.,20)))
# inversion of Kendall's tau
eCopula(rge,ge,technique="icorr",corrtype="kendall")

## --- GoF test, set substantially higher N to increase precision of p-value
gCopula(rge,ge,etechnique="ML",N=5)
# parallel computing takes lesser time, but the progress is not displayed
# not available on Windows OS
if(.Platform$OS.type!="windows") {
  gCopula(rge,ge,etechnique="ML",N=5,ncores=2)
}

## testing if two data sets has equal copulas
rge1 <- rCopula(80,dim=2,genClayton(),gpars=3)
gCopula(list(rge,rge1),N=5)

## check whether some hypotheticaly-copula function does not violate  
## copula properties (over data and parameters grid)
isCopula(genGumbel(),dagrid=10,pgrid=10,tolerance=1e-15)

## all the above functions are ready for archimax or generic copulas 
## as well as for higher dimensions
pCopula(c(0.3,0.5,1.0),genClayton(),depGumbel(),gpars=0.01,dpars=4.)  #0.2907613
pCopula(c(0.3,0.5,1.0),copula=copGumbel(),pars=4.)  #0.2906142

[Package acopula version 0.9.4 Index]