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.

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.

`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

```

[Package acopula version 0.9.3 Index]