The copBasic package is heavily oriented around copula theory and mathematical operations of copulas closely following one of the standard texts in the field by Nelsen (2006) and from 2015$+$ increasely Joe (2015) as well. Another good text is by Salvadori et al. (2007) and is cited herein, but about half of that excellent book is on univariate applications. The primal objective of copBasic is to provide a basic application programming inferface (API) into numerous results shown by authoritative texts on copulas. It is hoped in part that the package will help new inductees to copulas in their self study or potential course work.A few comments on notation are needed. A bold math typeface is used to represent a copula such as $\mathbf{\Pi}$ (see P) for the independence copula. The syntax $\mathcal{R}\times\mathcal{R} \equiv \mathcal{R}^2$ denotes the orthogonal domain of two real numbers, and $\mathcal{I}\times\mathcal{I} \equiv \mathcal{I}^2$ denotes the orthogonal domain on the unit square of probabilities. Thus, limits of integration $[0,1]$ or $[0,1]^2$ are shown as $\mathcal{I}$ and $\mathcal{I}^2$, respectively.
The random variables $X$ and $Y$ respectively denote the horizontal and vertical directions in $\mathcal{R}^2$. Their probabilistic counterparts are uniformly distributed random variables on $[0,1]$, are respectively denoted as $U$ and $V$, and necessarily also are the directions in $\mathcal{I}^2$. Often realizations of these random variables are respectively $x$ and $y$ for $X$ and $Y$ and $u$ and $v$ for $U$ and $V$.
There is a distinction between nonexceedance probability $F$ and exceedance probability $1-F$. Both $u$ and $v$ are measures in nonexceedance (cumulative probability). Arguments to many functions herein are u $= u$ and v $= v$ and are almost exclusively nonexceedance but there are instances for which u $= 1 - u = u'$ and v $= 1 - v = v'$. The prime notation on the exceedance probabilities differs from the traditional $\overline{t}$ (overbar) notation that is used for survival distributions (e.g. $\overline{F}(x)$) because of a need to refer to these probabilities from time to time in the Examples sections---and thus nonmathematical typeface (e.g. v').
Italic typeface is used extensively and usually near the opening of function-by-function documentation to identify vocabulary words, such as survival copula (see surCOP). This syntax tries to mimic and accentuate Roger B. Nelsen's word usage in Nelsen (2006) and to a lesser extent Joe (2015). The italics then is used to highlight this vocabulary in order to draw connections between concepts.
Helpful Navigation of the copBasic Package
Some helpful guideposts into the package are listed in the following table:
lclr{
Name Symbol Function Concept
Copula $\mathbf{C}(u,v)$ COP copula theory
Survival copula $\hat\mathbf{C}(u',v')$ surCOP copula theory
Joint survival function $\overline{\mathbf{C}}(u,v)$ surfuncCOP copula theory
Co-copula $\mathbf{C}^\star(u',v')$ coCOP copula theory
Dual of a copula $\tilde\mathbf{C}(u,v)$ duCOP copula theory
Primary copula diagonal $\delta(t)$ diagCOP copula theory
Secondary copula diagonal $\delta^\star(t)$ diagCOP copula theory
Inverse copula diagonal $\delta^{(-1)}(f)$ diagCOPatf copula theory
Blomqvist’s Beta $\beta_\mathbf{C}$ blomCOP bivariate association
Gini's Gamma $\gamma_\mathbf{C}$ giniCOP bivariate association
Hoeffding's Phi $\phi_\mathbf{C}$ hoefCOP bivariate association
Lp distance $\phi_\mathbf{C} \rightarrow L_p$ LpCOP bivariate association
Kendall's Tau $\tau_\mathbf{C}$ tauCOP bivariate association
Semi-correlations $\rho_N^{-}(a)$ semicorCOP bivariate tail association
Semi-correlations $\rho_N^{+}(a)$ semicorCOP bivariate tail association
Spearman's Rho $\rho_\mathbf{C}$ rhoCOP bivariate association
Schweizer and Wolff's Sigma $\sigma_\mathbf{C}$ wolfCOP bivariate association
Lower-bounds copula $\mathbf{W}(u,v)$ W copula
Independence copula $\mathbf{\Pi}(u,v)$ P copula
Upper-bounds copula $\mathbf{M}(u,v)$ M copula
Fréchet{Frechet} Family copula $\mathbf{FF}(u,v)$ FRECHETcop copula
Gumbel-Hougaard copula $\mathbf{GH}(u,v)$ GHcop copula
Plackett copula $\mathbf{PL}(u,v)$ PLACKETTcop copula
PSP copula $\mathbf{PSP}(u,v)$ PSP copula
Empirical copula $\mathbf{C}_n(u,v)$ EMPIRcop copula
Parametric simulation ${-}{-}$ simCOP copula simulation
Parametric simulation ${-}{-}$ simCOPmicro copula simulation
Empirical simulation ${-}{-}$ EMPIRsim copula simulation
Empirical simulation ${-}{-}$ EMPIRsimv copula simulation
Parametric copulatic surface ${-}{-}$ gridCOP copulatic surface
Empirical copulatic surface ${-}{-}$ EMPIRgrid copulatic surface
Density $c(u,v)$ densityCOP copula density
Density visualization ${-}{-}$ densityCOPplot copula density
}
Many functions in the package make the distinction between $V$ with respect to (wrt) $U$ and $U$ wrt $V$, and a guide through the nomenclature involving wrt distinctions is listed in the following table:
lclr{
Name Symbol Function Concept
Copula inversion $V$ wrt $U$ COPinv copula operator
Copula inversion $U$ wrt $V$ COPinv2 copula operator
Copula derivative $\delta \mathbf{C}/\delta u$ derCOP copula operator
Copula derivative $\delta \mathbf{C}/\delta v$ derCOP2 copula operator
Copula derivative inversion $V$ wrt $U$ derCOPinv copula operator
Copula derivative inversion $U$ wrt $V$ derCOPinv2 copula operator
Level curves $t \mapsto \mathbf{C}(u=U, v)$ level.curvesCOP copula theory
Level curves $t \mapsto \mathbf{C}(u, v=V)$ level.curvesCOP2 copula theory
Level set $V$ wrt $U$ level.setCOP copula theory
Level set $U$ wrt $V$ level.setCOP2 copula theory
Median regression $V$ wrt $U$ med.regressCOP copula theory
Median regression $U$ wrt $V$ med.regressCOP2 copula theory
Quantile regression $V$ wrt $U$ qua.regressCOP copula theory
Quantile regression $U$ wrt $V$ qua.regressCOP2 copula theory
Copula section $t \mapsto \mathbf{C}(t,a)$ sectionCOP copula theory
Copula section $t \mapsto \mathbf{C}(a,t)$ sectionCOP copula theory
}
The two tables do not include all of the myriad of special functions to support similar operations on empirical copulas. All empirical copula operators and utilites are prepended with EMPIR in the function name. An additional note concerning package nomenclature is that an appended 2 to a function name uniquely indicates
$U$ wrt $V$ (e.g. EMPIRgridderinv2 for an inversion of the partial derivatives $\delta \mathbf{C}/\delta v$ across the grid of the empirical copula).
Some additional functions that compute often salient features or characteristics of a copulas include those listed in the following table:
lclr{
Name Symbol Function Concept
Left-tail decreasing $V$ wrt $U$ isCOP.LTD bivariate association
Left-tail decreasing $U$ wrt $V$ isCOP.LTD bivariate association
Right-tail increasing $V$ wrt $U$ isCOP.RTI bivariate association
Right-tail increasing $U$ wrt $V$ isCOP.RTI bivariate association
Tail (lower) dependency $\lambda^L_\mathbf{C}$ taildepCOP bivariate tail association
Tail (upper) dependency $\lambda^U_\mathbf{C}$ taildepCOP bivariate tail association
Tail (lower) order $\kappa^L_\mathbf{C}$ tailordCOP bivariate tail association
Tail (upper) order $\kappa^U_\mathbf{C}$ tailordCOP bivariate tail association
Negatively quadrant dependency NQD isCOP.PQD bivariate association
Positively quadrant dependency PQD isCOP.PQD bivariate association
Permutation symmetry $\mathrm{permsym}$ isCOP.permsym copula symmetry
Radial symmetry $\mathrm{radsym}$ isCOP.radsym copula symmetry
Skewness (Joe, 2015) $\eta(p; \psi)$ uvskewness bivariate skewness
Kullback-Leibler divergence $\mathrm{KL}(f|g)$ kullCOP bivariate inference
K-L sample size $n_{fg}$ kullCOP bivariate inference
Vuong's Procedure ${-}{-}$ vuongCOP bivariate inference
L-comoments (samp. distr.) ${-}{-}$ lcomCOPpv experimental bivariate inference
}
The following table lists some important relations between various joint probability concepts, the copula, nonexceedance probabilities $u$ and $v$, and exceedance probabilities $u'$ and $v'$. A compact summary of these probability relations has obvious usefulness.
rcl{
Probability and Symbol Convention
$\mathrm{Pr}[\,U \le u, V \le v\,]$ $=$ $\mathbf{C}(u,v)$
$\mathrm{Pr}[\,U < u, V < v\,]$ $=$ $\hat\mathbf{C}(u',v')$
$\mathrm{Pr}[\,U \le u, V > v\,]$ $=$ $u - \mathbf{C}(u,v)$
$\mathrm{Pr}[\,U > u, V \le v\,]$ $=$ $v - \mathbf{C}(u,v)$
$\mathrm{Pr}[\,U \le u \mid V \le v\,]$ $=$ $\mathbf{C}(u,v)/v$
$\mathrm{Pr}[\,V \le v \mid U \le u\,]$ $=$ $\mathbf{C}(u,v)/u$
$\mathrm{Pr}[\,U \le u \mid V > v\,]$ $=$ $(u - \mathbf{C}(u,v))/(1 - v)$
$\mathrm{Pr}[\,V \le v \mid U > u\,]$ $=$ $(v - \mathbf{C}(u,v))/(1 - u)$
$\mathrm{Pr}[\,V \le v \mid U = u\,]$ $=$ $\delta \mathbf{C}(u,v)/\delta u$
$\mathrm{Pr}[\,U \le u \mid V = v\,]$ $=$ $\delta \mathbf{C}(u,v)/\delta v$
$\mathrm{Pr}[\,U > u \mathrm{\ or\ } V > v\,]$ $=$ $1 - \mathbf{C}(u',v')$
$\mathrm{Pr}[\,U \le v \mathrm{\ or\ } V \le v\,]$ $=$ $u + v - \mathbf{C}(u,v)$
}
One or two copulas can be blended or composited in interesting ways to create highly unique joint probability relations. The package provides the following functions for copula composition. And these compositing functions are all compatible with joint probability simulation as supported by simCOP. Further functions composite2COP and composite3COP supporting two copulas each provide for each copula having its own parameter set.
ccl{
No. of copulas Compositing parameters Function
1 $\alpha, \beta$ composite1COP
2 $\alpha, \beta$ composite2COP
2 $\alpha, \beta, \kappa, \gamma$ composite3COP
}