xCopula: Archimax and generic copula distribution functions

In acopula: Modelling Dependence with Multivariate Archimax (or any User-Defined Continuous) Copulas

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.

See Also

generator, depfun, pCopula

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

acopula documentation built on Sept. 11, 2023, 1:08 a.m.