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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
## 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 higher N to increase precision of p-value
gCopula(rge,ge,etechnique="ML",N=10)
# 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=10,ncores=2)
}

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

## 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