copBasic-package: Basic Theoretical Copula, Empirical Copula, and Various...
In copBasic: General Bivariate Copula Theory and Many Utility Functions
copBasic-package R Documentation
Basic Theoretical Copula, Empirical Copula, and Various Utility Functions
Description
The copBasic package is oriented around bivariate copula theory and mathematical operations closely follow the standard texts of Nelsen (2006) and Joe (2014) as well as select other references. Another recommended text is Salvadori et al. (2007) and is cited herein, but about half of that excellent book concerns univariate applications. The primal objective of copBasic is to provide a basic application programming interface (API) to numerous results shown by authoritative texts on copulas. It is intended that the package will help other copula students in self study, potential course work, and applied circumstances.
Notes on copulas that are supported. The author has focused on pedagogical aspects of copulas, and this package is a diary of sorts. Originally, the author did not implement many copulas in the copBasic in order to deliberately avoid redundancy to that support such as it exists on the R CRAN. Though as time has progressed, other copulas have been added occasionally based on needs of the user community, need to show some specific concept in the general theory, or test algorithms. For example, the Clayton copula (CLcop) is a late arriving addition to the copBasic package (c.2017), which was added to assist a specific user.
Helpful Navigation of Copulas Implemented in the copBasic Package
Some entry points to the copulas implemented are listed in the Table of Copulas:
Name Symbol Function Concept
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 Family copula \mathbf{FF}(u,v) FRECHETcop copula
Ali--Mikhail--Haq copula \mathbf{AMH}(u,v) AMHcop copula
Clayton copula \mathbf{CL}(u,v) CLcop copula
Farlie--Gumbel--Morgenstern (generalized) \mathbf{FGM}(u,v) FGMcop copula
Galambos copula \mathbf{GL}(u,v) GLcop copula
Gumbel--Hougaard copula \mathbf{GH}(u,v) GHcop copula
Hüsler--Reiss copula \mathbf{HR}(u,v) HRcop copula
Joe B5 copula \mathbf{B5}(u,v) JOcopB5 copula
Nelsen eq.4-2-12 copula \mathbf{N4212cop}(u,v) N4212cop copula
Pareto copula \mathbf{PA}(u,v) PLcop copula
Plackett copula \mathbf{PL}(u,v) PLcop copula
PSP copula \mathbf{PSP}(u,v) PSP copula
Raftery copula \mathbf{RF}(u,v) RFcop copula
g-EV copula (Gaussian extreme value) \mathbf{gEV}(u,v) gEVcop copula
t-EV copula (t-distribution extreme value) \mathbf{tEV}(u,v) tEVcop copula
The language and vocabulary of copulas is formidable. The author (Asquith) has often emphasized “vocabulary” words in italics, which 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 the word usage in Nelsen (2006) and Joe (2014).
The italics then are used to draw connections between concepts. In conjunction with the summary of functions in copBasic-package, the extensive cross referencing to functions and expansive keyword indexing should be beneficial. The author had no experience with copulas prior to a chance happening upon Nelsen (2006) in c.2008. The copBasic package is a personal tour de force in self-guided learning. Hopefully, this package and user's manual will be helpful to others.
A few comments on notation herein 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 [0,1]\times [0,1] \equiv \mathcal{I}\times\mathcal{I} \equiv \mathcal{I}^2 denotes the orthogonal domain on the unit square of probabilities. Limits of integration [0,1] or [0,1]^2 involving copulas are thus 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 respective directions in \mathcal{I}^2 (U denotes the horizontal, V denotes the vertical). 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 an obvious difference between nonexceedance probability F and its complement, which is exceedance probability defined as 1-F. Both u and v herein are in nonexceedance probability. Arguments to many functions herein are u = u and v = v and are almost exclusively nonexceedance but there are instances for which the probability arguments are u = 1 - u = u' and v = 1 - v = v'.
Helpful Navigation of the copBasic Package
Some other entry points into the package are listed in the following table:
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
Joint probability {-}{-} jointCOP copula theory
Bivariate L-moments \delta^{[\ldots]}_{k;\mathbf{C}} bilmoms and lcomCOP bivariate moments
Bivariate L-comoments \tau^{[\ldots]}_{k;\mathbf{C}} bilmoms and lcomCOP bivariate moments
Blomqvist Beta \beta_\mathbf{C} blomCOP bivariate association
Gini Gamma \gamma_\mathbf{C} giniCOP bivariate association
Hoeffding Phi \Phi_\mathbf{C} hoefCOP bivariate association
Nu-Skew \nu_\mathbf{C} nuskewCOP bivariate moments
Nu-Star (skew) \nu^\star_\mathbf{C} nustarCOP bivariate moments
Lp distance to independence \Phi_\mathbf{C} \rightarrow L_p LpCOP bivariate association
Permutation-Mu \mu_{\infty\mathbf{C}}^\mathrm{permsym} LzCOPpermsym permutation asymmetry
Kendall Tau \tau_\mathbf{C} tauCOP bivariate association
Kendall Measure K_\mathbf{C}(z) kmeasCOP copula theory
Kendall Function F_K(z) kfuncCOP copula theory
Inverse Kendall Function F_K^{(-1)}(z) kfuncCOPinv copula theory
An L-moment of F_K(z) \lambda_r(F_K) kfuncCOPlmom L-moment theory
L-moments of F_K(z) \lambda_r(F_K) kfuncCOPlmoms L-moment theory
Semi-correlations (negatives) \rho_N^{-}(a) semicorCOP bivariate tail association
Semi-correlations (positives) \rho_N^{+}(a) semicorCOP bivariate tail association
Spearman Footrule \psi_\mathbf{C} footCOP bivariate association
Spearman Rho \rho_\mathbf{C} rhoCOP bivariate association
Schweizer--Wolff Sigma \sigma_\mathbf{C} wolfCOP bivariate association
Density of a copula c(u,v) densityCOP copula density
Density visualization {-}{-} densityCOPplot copula density
Empirical copula \mathbf{C}_n(u,v) EMPIRcop copula
Empirical simulation {-}{-} EMPIRsim copula simulation
Empirical simulation {-}{-} EMPIRsimv copula simulation
Empirical copulatic surface {-}{-} EMPIRgrid copulatic surface
Parametric copulatic surface {-}{-} gridCOP copulatic surface
Parametric simulation {-}{-} simCOP or rCOP copula simulation
Parametric simulation {-}{-} simCOPmicro copula simulation
Maximum likelihood \mathcal{L}(\Theta_d) mleCOP copula fitting
Akaike information criterion \mathrm{AIC}_\mathbf{C} aicCOP goodness-of-fit
Bayesian information criterion \mathrm{BIC}_\mathbf{C} bicCOP goodness-of-fit
Root mean square error \mathrm{RMSE}_\mathbf{C} rmseCOP goodness-of-fit
Another goodness-of-fit T_n statTn goodness-of-fit
Several of the functions listed above are measures of “bivariate association.” Two of the measures (Kendall Tau, tauCOP; Spearman Rho, rhoCOP) are widely known. R provides native support for their sample estimation of course, but each function can be used to call the cor() function in R for parallelism to the other measures of this package. The other measures (Blomqvist Beta, Gini Gamma, Hoeffding Phi, Schweizer–Wolff Sigma, Spearman Footrule) support sample estimation by specially formed calls to their respective functions: blomCOP, giniCOP, hoefCOP, wolfCOP, and footCOP. Gini Gamma (giniCOP) documentation (also joeskewCOP) shows extensive use of theoretical and sample computations for these and other functions.
Concerning goodness-of-fit and although not quite the same as copula properties (such as “correlation”) per se as the coefficients aforementioned in the prior paragraph, three goodness-of-fit metrics of a copula compared to the empirical copula, which are all based the mean square error (MSE), are aicCOP, bicCOP, and rmseCOP. This triad of functions is useful for making decisions on whether a copula is more favorable than another to a given dataset. However, because they are genetically related by using MSE and if these are used for copula fitting by minimization, the fits will be identical. A statement of “not quite the same” is made because the previously described copula properties are generally defined as types of deviations from other copulas (such as P). Another goodness-of-fit statistic is statTn, which is based on magnitude summation of fitted copula difference from the empirical copula. These four (aicCOP, bicCOP, rmseCOP, and statTn) collectively are relative simple and readily understood measures. These bulk sample statistics are useful, but generally thought to not capture the nuances of tail behavior (semicorCOP and taildepCOP might be useful).
Bivariate skewness measures are supported in the functions joeskewCOP (nuskewCOP and nustarCOP) and uvlmoms (uvskew). Extensive discussion and example computations of bivariate skewness are provided in the joeskewCOP documentation. Lastly, so-called bivariate L-moments and bivariate L-comoments of a copula are directly computable in bilmoms (though that function using Monte Carlo integration is deprecated) and lcomCOP (direct numerical integration). The lcomCOP function is the theoretical counterpart to the sample L-comoments provided in the lmomco package.
Bivariate random simulation by several functions is identified in the previous table. The copBasic package explicitly uses only conditional simulation also known as the conditional distribution method for random variate generation following Nelsen (2006, pp. 40–41) (see also simCOPmicro, simCOP). The numerical derivatives (derCOP and derCOP2) and their inversions (derCOPinv and derCOPinv2) represent the foundation of the conditional simulation. There are other methods in the literature and available in other R packages, and a comparison of some methods is made in the Examples section of the Gumbel–Hougaard copula (GHcop).
Several functions in copBasic make the distinction between V with respect to (wrt) U and U wrt V, and a guide for the nomenclature involving wrt distinctions is listed in the following table:
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
Joint curves t \mapsto \mathbf{C}(u=U, v) joint.curvesCOP copula theory
Joint curves t \mapsto \mathbf{C}(u, v=V) joint.curvesCOP2 copula theory
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 previous two tables do not include all of the myriad of special functions to support similar operations on empirical copulas. All empirical copula operators and utilities are prepended with EMPIR in the function name. An additional note concerning package nomenclature is that an appended “2” to a function name 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 to compute often salient features or characteristics of copulas or bivariate data, including functions for bivariate inference or goodness-of-fit, are listed in the following table:
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
Pseudo-polar representation (\widehat{S},\widehat{W}) psepolar extremal dependency
Tail concentration function q_\mathbf{C}(t) tailconCOP bivariate tail 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
Neg'ly quadrant dependency NQD isCOP.PQD bivariate association
Pos'ly 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, 2014) \eta(p; \psi) uvskew bivariate skewness
Kullback--Leibler Divergence \mathrm{KL}(f|g) kullCOP bivariate inference
KL sample size n_{f\!g} kullCOP bivariate inference
The Vuong Procedure {-}{-} vuongCOP bivariate inference
Spectral measure H(w) spectralmeas extremal dependency inference
Stable tail dependence \widehat{l}(x,y) stabtaildepf extremal dependency inference
L-comoments (samp. distr.) {-}{-} lcomCOPpv experimental bivariate inference
The Table of Probabilities that follows lists 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. The notation [\ldots, \ldots] is to read as [\ldots \mathrm{\ and\ } \ldots], and the [\ldots | \ldots] is to be read as [\ldots \mathrm{\ given\ } \ldots].
Probability and Symbol Convention
\mathrm{Pr}[\,U \le u, V \le v\,] = \mathbf{C}(u,v) --- The copula, COP
\mathrm{Pr}[\,U > u, V > v\,] = \hat{\mathbf{C}}(u',v') --- The survival copula, surCOP
\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\,] = \bigl(u - \mathbf{C}(u,v)\bigr)/(1 - v)
\mathrm{Pr}[\,V \le v \mid U > u\,] = \bigl(v - \mathbf{C}(u,v)\bigr)/(1 - u)
\mathrm{Pr}[\,U > u \mid V > v\,] = \hat{\mathbf{C}}(u',v')/u' = \overline{\mathbf{C}}(u,v)/(1-u)
\mathrm{Pr}[\,V > v \mid U > u\,] = \hat{\mathbf{C}}(u',v')/v' = \overline{\mathbf{C}}(u,v)/(1-v)
\mathrm{Pr}[\,V \le v \mid U = u\,] = \delta \mathbf{C}(u,v)/\delta u --- Partial derivative, derCOP
\mathrm{Pr}[\,U \le u \mid V = v\,] = \delta \mathbf{C}(u,v)/\delta v --- Partial derivative, derCOP2
\mathrm{Pr}[\,U > u \mathrm{\ or\ } V > v\,] = \mathbf{C}^\star(u',v') = 1 - \mathbf{C}(u',v') --- The co-copula, coCOP
\mathrm{Pr}[\,U \le u \mathrm{\ or\ } V \le v\,] = \tilde{\mathbf{C}}(u,v) = u + v - \mathbf{C}(u,v) --- The dual of a copula, duCOP
The function jointCOP has considerable demonstration in its Note section of the joint and and joint or relations shown through simulation and counting scenarios. Also there is a demonstration in the Note section of function duCOP on application of the concepts of joint and conditions, joint or conditions, and importantly joint mutually exclusive or conditions.
Permutation asymmetry can be added to a copula by breveCOP. One, two, or more copulas can be “composited,” “combined,” or “multiplied” in interesting ways to create highly unique bivariate relations and as a result, complex dependence structures can be formed. The package provides three main functions for copula composition: composite1COP composites a single copula with two compositing parameters, composite2COP composites two copulas with two compositing parameters, and composite3COP composites two copulas with four compositing parameters. Also two copulas can be combined through a weighted convex combination using convex2COP with a single weighting parameter, and even N number of copulas can be combined by weights using convexCOP. So-called “gluing” two copula by a parameter is provided by glueCOP. Finally, multiplication of two copulas to form a third is supported by prod2COP. All seven functions for compositing, combining, or multipling copulas are compatible with joint probability simulation (simCOP), measures of association (e.g. \rho_\mathbf{C}), and presumably all other copula operations using copBasic features.
No. of copulas Combining Parameters Function Concept
1 \beta breveCOP adding permuation asymmetry
1 \alpha, \beta composite1COP copula combination
2 \alpha, \beta composite2COP copula combination
2 \alpha, \beta, \kappa, \gamma composite3COP copula combination
2 \alpha, (1-\alpha) convex2COP weighted copula combination
N \omega_{i \in N} convexCOP weighted copula combination
2 \gamma glueCOP gluing of coupla
2 \bigl(\mathbf{C}_1 \ast \mathbf{C}_2 \bigr) prod2COP copula multiplication
Useful Copula Relations by Visualization
There are a myriad of relations amongst variables computable through copulas, and these were listed in the Table of Probabilities earlier in this documentation. There is a script located in the inst/doc directory of the copBasic sources titled CopulaRelations_BaseFigure_inR.txt. This script demonstrates, using the PSP copula, relations between the copula (COP), survival copula (surCOP), joint survival function of a copula (surfuncCOP), co-copula (coCOP), and dual of a copula function (duCOP). The script performs simulation and manual counts observations meeting various criteria in order to compute their empirical probabilities. The script produces a base figure, which after extending in editing software, is suitable for educational description and is provided at the end of this documentation.
A Review of “Return Periods” using Copulas
Risk analyses of natural hazards are commonly expressed as annual return periods T in years, which are defined for a nonexceedance probability q as T = 1/(1-q). In bivariate analysis, there immediately emerge two types of return periods representing T_{q;\,\mathrm{coop}} and T_{q;\,\mathrm{dual}} conditions between nonexceedances of the two hazard sources (random variables) U and V. It is usual in many applications for T to be expressed equivalently as a probability q in common for both variables.
Incidentally, the \mathrm{Pr}[\,U > u \mid V > v\,] and \mathrm{Pr}[\,V > v \mid U > u\,] probabilities also are useful for conditional return period computations following Salvadori et al. (2007, pp. 159–160) but are not further considered here. Also the F_K(w) (Kendall Function or Kendall Measure of a copula) is the core tool for secondary return period computations (see kfuncCOP).
Let the copula \mathbf{C}(u,v; \Theta) for nonexceedances u and v be set for some copula family (formula) by a parameter vector \Theta. The copula family and parameters define the joint coupling (loosely meant the dependency/correlation) between hazards U and V. If “failure” occurs if either or both hazards U and V are at probability q threshold (u = v = 1 - 1/T = q) for T-year return period, then the real return period of failure is defined using either the copula \mathbf{C}(q,q; \Theta) or the co-copula \mathbf{C}^\star(q',q'; \Theta) for exceedance probability q' = 1 - q is
T_{q;\,\mathrm{coop}} = \frac{1}{1 - \mathbf{C}(q, q; \Theta)} = \frac{1}{\mathbf{C}^\star(1-q, 1-q; \Theta)}\mbox{\ and}
T_{q;\,\mathrm{coop}} \equiv \frac{1}{\mathrm{cooperative\ risk}}\mbox{.}
Or in words, the hazard sources collaborate or cooperate to cause failure. If failure occurs, however, if and only if both hazards U and V occur simultaneously (the hazards must “dually work together” or be “conjunctive”), then the real return period is defined using either the dual of a copula (function) \tilde{\mathbf{C}}(q,q; \Theta), the joint survival function \overline{\mathbf{C}}(q,q;\Theta), or survival copula \hat{\mathbf{C}}(q',q'; \Theta) as
T_{q;\,\mathrm{dual}} = \frac{1}{1 - \tilde{\mathbf{C}}(q,q; \Theta)} = \frac{1}{\overline{\mathbf{C}}(q,q;\Theta)} = \frac{1}{\hat{\mathbf{C}}(q',q';\Theta)} \mbox{\ and}
T_{q;\,\mathrm{dual}} \equiv \frac{1}{\mathrm{complement\ of\ dual\ protection}}\mbox{.}
Numerical demonstration is informative. Salvadori et al. (2007, p. 151) show for a Gumbel–Hougaard copula (GHcop) having \Theta = 3.055 and T = 1,000 years (q = 0.999) that T_{q;\,\mathrm{coop}} = 797.1 years and that T_{q;\,\mathrm{dual}} = 1,341.4 years, which means that average return periods between “failures” are
T_{q;\,\mathrm{coop}} \le T \le T_{q;\,\mathrm{dual}}\mbox{\ and thus}
797.1 \le T \le 1314.4\mbox{\ years.}
With the following code, these bounding return-period values are readily computed and verified using the prob2T() function from the lmomco package along with copBasic functions COP (generic functional interface to a copula) and duCOP (dual of a copula):
q <- T2prob(1000)
lmomco::prob2T( COP(q,q, cop=GHcop, para=3.055)) # 797.110
lmomco::prob2T(duCOP(q,q, cop=GHcop, para=3.055)) # 1341.438
An early source (in 2005) by some of those authors cited on p. 151 of Salvadori et al. (2007; their citation “[67]”) shows T_{q;\,\mathrm{dual}} = 798 years—a rounding error seems to have been committed. Finally just for reference, a Gumbel–Hougaard copula having \Theta = 3.055 corresponds to an analytical Kendall Tau (see GHcop) of \tau \approx 0.673, which can be verified through numerical integration available from tauCOP as:
tauCOP(cop=GHcop, para=3.055, brute=TRUE) # 0.6726542
Thus, a “better understanding of the statistical characteristics of [multiple hazard sources] requires the study of their joint distribution” (Salvadori et al., 2007, p. 150).
Interaction of copBasic to Copulas in Other Packages
Originally, the copBasic package was not intended to be a port of the numerous bivariate copulas or over re-implementation other bivariate copulas available in R though as the package passed its 10th year in 2018, the original intent changed. It is useful to point out a demonstration showing an implementation of the Gaussian copula from the copula package, which is shown in the Note section of med.regressCOP in a circumstance of ordinary least squares linear regression compared to median regression of a copula as well as prediction limits of both regressions. Another demonstration in context of maximum pseudo-log-likelihood estimation of copula parameters is seen in the Note section mleCOP, and also see “API to the copula package” or “package copula (comparison to)” entries in the Index of this user manual.
Author(s)
William Asquith william.asquith@ttu.edu
References
Cherubini, U., Luciano, E., and Vecchiato, W., 2004, Copula methods in finance: Hoboken, NJ, Wiley, 293 p.
Hernández-Maldonado, V., Díaz-Viera, M., and Erdely, A., 2012, A joint stochastic simulation method using the Bernstein copula as a flexible tool for modeling nonlinear dependence structures between petrophysical properties: Journal of Petroleum Science and Engineering, v. 90–91, pp. 112–123.
Joe, H., 2014, Dependence modeling with copulas: Boca Raton, CRC Press, 462 p.
Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p.
Salvadori, G., De Michele, C., Kottegoda, N.T., and Rosso, R., 2007, Extremes in nature—An approach using copulas: Dordrecht, Netherlands, Springer, Water Science and Technology Library 56, 292 p.
Examples
## Not run:
# Nelsen (2006, p. 75, exer. 3.15b) provides for a nice test of copBasic features.
"mcdurv" <- function(u,v, theta) {
ifelse(u > theta & u < 1-theta & v > theta & v < 1 - theta,
return(M(u,v) - theta), # Upper bounds copula with a shift
return(W(u,v))) # Lower bounds copula
}
"MCDURV" <- function(u,v, para=NULL) {
if(is.null(para)) stop("need theta")
if(para < 0 | para > 0.5) stop("theta ! in [0,1/2]")
return(asCOP(u, v, f=mcdurv, para))
}
"afunc" <- function(t) { # a sample size = 1,000 hard wired
return(cov(simCOP(n=1000, cop=MCDURV, para=t, ploton=FALSE, points=FALSE))[1,2])
}
set.seed(6234) # setup covariance based on parameter "t" and the "root" parameter
print(uniroot(afunc, c(0,0.5))) # "t" by simulation = 0.1023742
# Nelsen reports that if theta appox. 0.103 then covariance of U and V is zero.
# So, one will have mutually completely dependent uncorrelated uniform variables!
# Let us check some familiar measures of association:
rhoCOP( cop=MCDURV, para=0.1023742) # Spearman Rho = 0.005854481 (near zero)
tauCOP( cop=MCDURV, para=0.1023742) # Kendall Tau = 0.2648521
wolfCOP(cop=MCDURV, para=0.1023742) # S & W Sigma = 0.4690174 (less familiar)
D <- simCOP(n=1000, cop=MCDURV, para=0.1023742) # Plot mimics Nelsen (2006, fig. 3.11)
# Lastly, open research problem. L-comoments (matrices) measure high dimension of
# variable comovements (see lmomco package)---"method of L-comoments" for estimation?
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0), nmom=5) # Perfect neg. corr.
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0.1023742), nmom=5)
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0.5), nmom=5) # Perfect pos. corr.
# T2 (L-correlation), T3 (L-coskew), T4 (L-cokurtosis), and T5 matrices result. For
# Theta = 0 or 0.5 see the matrix symmetry with a sign change for L-coskew and T5 on
# the off diagonals (offdiags). See unities for T2. See near zero for offdiag terms
# in T2 near zero. But then see that T4 off diagonals are quite different from those
# for Theta 0.1024 relative to 0 or 0.5. As a result, T4 has captured a unique
# property of U vs V.
## End(Not run)
copBasic documentation built on Oct. 17, 2023, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| copBasic-package | R Documentation |
Basic Theoretical Copula, Empirical Copula, and Various Utility Functions
Description
The copBasic package is oriented around bivariate copula theory and mathematical operations closely follow the standard texts of Nelsen (2006) and Joe (2014) as well as select other references. Another recommended text is Salvadori et al. (2007) and is cited herein, but about half of that excellent book concerns univariate applications. The primal objective of copBasic is to provide a basic application programming interface (API) to numerous results shown by authoritative texts on copulas. It is intended that the package will help other copula students in self study, potential course work, and applied circumstances.
Notes on copulas that are supported. The author has focused on pedagogical aspects of copulas, and this package is a diary of sorts. Originally, the author did not implement many copulas in the copBasic in order to deliberately avoid redundancy to that support such as it exists on the R CRAN. Though as time has progressed, other copulas have been added occasionally based on needs of the user community, need to show some specific concept in the general theory, or test algorithms. For example, the Clayton copula (CLcop) is a late arriving addition to the copBasic package (c.2017), which was added to assist a specific user.
Helpful Navigation of Copulas Implemented in the copBasic Package Some entry points to the copulas implemented are listed in the Table of Copulas:
| Name | Symbol | Function | Concept |
| 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 Family copula | \mathbf{FF}(u,v) | FRECHETcop | copula |
| Ali--Mikhail--Haq copula | \mathbf{AMH}(u,v) | AMHcop | copula |
| Clayton copula | \mathbf{CL}(u,v) | CLcop | copula |
| Farlie--Gumbel--Morgenstern (generalized) | \mathbf{FGM}(u,v) | FGMcop | copula |
| Galambos copula | \mathbf{GL}(u,v) | GLcop | copula |
| Gumbel--Hougaard copula | \mathbf{GH}(u,v) | GHcop | copula |
| Hüsler--Reiss copula | \mathbf{HR}(u,v) | HRcop | copula |
| Joe B5 copula | \mathbf{B5}(u,v) | JOcopB5 | copula |
| Nelsen eq.4-2-12 copula | \mathbf{N4212cop}(u,v) | N4212cop | copula |
| Pareto copula | \mathbf{PA}(u,v) | PLcop | copula |
| Plackett copula | \mathbf{PL}(u,v) | PLcop | copula |
| PSP copula | \mathbf{PSP}(u,v) | PSP | copula |
| Raftery copula | \mathbf{RF}(u,v) | RFcop | copula |
| g-EV copula (Gaussian extreme value) | \mathbf{gEV}(u,v) | gEVcop | copula |
| t-EV copula (t-distribution extreme value) | \mathbf{tEV}(u,v) | tEVcop | copula |
The language and vocabulary of copulas is formidable. The author (Asquith) has often emphasized “vocabulary” words in italics, which 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 the word usage in Nelsen (2006) and Joe (2014).
The italics then are used to draw connections between concepts. In conjunction with the summary of functions in copBasic-package, the extensive cross referencing to functions and expansive keyword indexing should be beneficial. The author had no experience with copulas prior to a chance happening upon Nelsen (2006) in c.2008. The copBasic package is a personal tour de force in self-guided learning. Hopefully, this package and user's manual will be helpful to others.
A few comments on notation herein 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 [0,1]\times [0,1] \equiv \mathcal{I}\times\mathcal{I} \equiv \mathcal{I}^2 denotes the orthogonal domain on the unit square of probabilities. Limits of integration [0,1] or [0,1]^2 involving copulas are thus 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 respective directions in \mathcal{I}^2 (U denotes the horizontal, V denotes the vertical). 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 an obvious difference between nonexceedance probability F and its complement, which is exceedance probability defined as 1-F. Both u and v herein are in nonexceedance probability. Arguments to many functions herein are u = u and v = v and are almost exclusively nonexceedance but there are instances for which the probability arguments are u = 1 - u = u' and v = 1 - v = v'.
Helpful Navigation of the copBasic Package
Some other entry points into the package are listed in the following table:
| 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 |
| Joint probability | {-}{-} | jointCOP | copula theory |
| Bivariate L-moments | \delta^{[\ldots]}_{k;\mathbf{C}} | bilmoms and lcomCOP | bivariate moments |
| Bivariate L-comoments | \tau^{[\ldots]}_{k;\mathbf{C}} | bilmoms and lcomCOP | bivariate moments |
| Blomqvist Beta | \beta_\mathbf{C} | blomCOP | bivariate association |
| Gini Gamma | \gamma_\mathbf{C} | giniCOP | bivariate association |
| Hoeffding Phi | \Phi_\mathbf{C} | hoefCOP | bivariate association |
| Nu-Skew | \nu_\mathbf{C} | nuskewCOP | bivariate moments |
| Nu-Star (skew) | \nu^\star_\mathbf{C} | nustarCOP | bivariate moments |
| Lp distance to independence | \Phi_\mathbf{C} \rightarrow L_p | LpCOP | bivariate association |
| Permutation-Mu | \mu_{\infty\mathbf{C}}^\mathrm{permsym} | LzCOPpermsym | permutation asymmetry |
| Kendall Tau | \tau_\mathbf{C} | tauCOP | bivariate association |
| Kendall Measure | K_\mathbf{C}(z) | kmeasCOP | copula theory |
| Kendall Function | F_K(z) | kfuncCOP | copula theory |
| Inverse Kendall Function | F_K^{(-1)}(z) | kfuncCOPinv | copula theory |
An L-moment of F_K(z) | \lambda_r(F_K) | kfuncCOPlmom | L-moment theory |
L-moments of F_K(z) | \lambda_r(F_K) | kfuncCOPlmoms | L-moment theory |
| Semi-correlations (negatives) | \rho_N^{-}(a) | semicorCOP | bivariate tail association |
| Semi-correlations (positives) | \rho_N^{+}(a) | semicorCOP | bivariate tail association |
| Spearman Footrule | \psi_\mathbf{C} | footCOP | bivariate association |
| Spearman Rho | \rho_\mathbf{C} | rhoCOP | bivariate association |
| Schweizer--Wolff Sigma | \sigma_\mathbf{C} | wolfCOP | bivariate association |
| Density of a copula | c(u,v) | densityCOP | copula density |
| Density visualization | {-}{-} | densityCOPplot | copula density |
| Empirical copula | \mathbf{C}_n(u,v) | EMPIRcop | copula |
| Empirical simulation | {-}{-} | EMPIRsim | copula simulation |
| Empirical simulation | {-}{-} | EMPIRsimv | copula simulation |
| Empirical copulatic surface | {-}{-} | EMPIRgrid | copulatic surface |
| Parametric copulatic surface | {-}{-} | gridCOP | copulatic surface |
| Parametric simulation | {-}{-} | simCOP or rCOP | copula simulation |
| Parametric simulation | {-}{-} | simCOPmicro | copula simulation |
| Maximum likelihood | \mathcal{L}(\Theta_d) | mleCOP | copula fitting |
| Akaike information criterion | \mathrm{AIC}_\mathbf{C} | aicCOP | goodness-of-fit |
| Bayesian information criterion | \mathrm{BIC}_\mathbf{C} | bicCOP | goodness-of-fit |
| Root mean square error | \mathrm{RMSE}_\mathbf{C} | rmseCOP | goodness-of-fit |
| Another goodness-of-fit | T_n | statTn | goodness-of-fit |
Several of the functions listed above are measures of “bivariate association.” Two of the measures (Kendall Tau, tauCOP; Spearman Rho, rhoCOP) are widely known. R provides native support for their sample estimation of course, but each function can be used to call the cor() function in R for parallelism to the other measures of this package. The other measures (Blomqvist Beta, Gini Gamma, Hoeffding Phi, Schweizer–Wolff Sigma, Spearman Footrule) support sample estimation by specially formed calls to their respective functions: blomCOP, giniCOP, hoefCOP, wolfCOP, and footCOP. Gini Gamma (giniCOP) documentation (also joeskewCOP) shows extensive use of theoretical and sample computations for these and other functions.
Concerning goodness-of-fit and although not quite the same as copula properties (such as “correlation”) per se as the coefficients aforementioned in the prior paragraph, three goodness-of-fit metrics of a copula compared to the empirical copula, which are all based the mean square error (MSE), are aicCOP, bicCOP, and rmseCOP. This triad of functions is useful for making decisions on whether a copula is more favorable than another to a given dataset. However, because they are genetically related by using MSE and if these are used for copula fitting by minimization, the fits will be identical. A statement of “not quite the same” is made because the previously described copula properties are generally defined as types of deviations from other copulas (such as P). Another goodness-of-fit statistic is statTn, which is based on magnitude summation of fitted copula difference from the empirical copula. These four (aicCOP, bicCOP, rmseCOP, and statTn) collectively are relative simple and readily understood measures. These bulk sample statistics are useful, but generally thought to not capture the nuances of tail behavior (semicorCOP and taildepCOP might be useful).
Bivariate skewness measures are supported in the functions joeskewCOP (nuskewCOP and nustarCOP) and uvlmoms (uvskew). Extensive discussion and example computations of bivariate skewness are provided in the joeskewCOP documentation. Lastly, so-called bivariate L-moments and bivariate L-comoments of a copula are directly computable in bilmoms (though that function using Monte Carlo integration is deprecated) and lcomCOP (direct numerical integration). The lcomCOP function is the theoretical counterpart to the sample L-comoments provided in the lmomco package.
Bivariate random simulation by several functions is identified in the previous table. The copBasic package explicitly uses only conditional simulation also known as the conditional distribution method for random variate generation following Nelsen (2006, pp. 40–41) (see also simCOPmicro, simCOP). The numerical derivatives (derCOP and derCOP2) and their inversions (derCOPinv and derCOPinv2) represent the foundation of the conditional simulation. There are other methods in the literature and available in other R packages, and a comparison of some methods is made in the Examples section of the Gumbel–Hougaard copula (GHcop).
Several functions in copBasic make the distinction between V with respect to (wrt) U and U wrt V, and a guide for the nomenclature involving wrt distinctions is listed in the following table:
| 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 |
| Joint curves | t \mapsto \mathbf{C}(u=U, v) | joint.curvesCOP | copula theory |
| Joint curves | t \mapsto \mathbf{C}(u, v=V) | joint.curvesCOP2 | copula theory |
| 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 previous two tables do not include all of the myriad of special functions to support similar operations on empirical copulas. All empirical copula operators and utilities are prepended with EMPIR in the function name. An additional note concerning package nomenclature is that an appended “2” to a function name 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 to compute often salient features or characteristics of copulas or bivariate data, including functions for bivariate inference or goodness-of-fit, are listed in the following table:
| 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 |
| Pseudo-polar representation | (\widehat{S},\widehat{W}) | psepolar | extremal dependency |
| Tail concentration function | q_\mathbf{C}(t) | tailconCOP | bivariate tail 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 |
| Neg'ly quadrant dependency | NQD | isCOP.PQD | bivariate association |
| Pos'ly 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, 2014) | \eta(p; \psi) | uvskew | bivariate skewness |
| Kullback--Leibler Divergence | \mathrm{KL}(f|g) | kullCOP | bivariate inference |
| KL sample size | n_{f\!g} | kullCOP | bivariate inference |
| The Vuong Procedure | {-}{-} | vuongCOP | bivariate inference |
| Spectral measure | H(w) | spectralmeas | extremal dependency inference |
| Stable tail dependence | \widehat{l}(x,y) | stabtaildepf | extremal dependency inference |
| L-comoments (samp. distr.) | {-}{-} | lcomCOPpv | experimental bivariate inference |
The Table of Probabilities that follows lists 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. The notation [\ldots, \ldots] is to read as [\ldots \mathrm{\ and\ } \ldots], and the [\ldots | \ldots] is to be read as [\ldots \mathrm{\ given\ } \ldots].
| Probability | and | Symbol Convention |
\mathrm{Pr}[\,U \le u, V \le v\,] | = | \mathbf{C}(u,v) --- The copula, COP |
\mathrm{Pr}[\,U > u, V > v\,] | = | \hat{\mathbf{C}}(u',v') --- The survival copula, surCOP |
\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\,] | = | \bigl(u - \mathbf{C}(u,v)\bigr)/(1 - v) |
\mathrm{Pr}[\,V \le v \mid U > u\,] | = | \bigl(v - \mathbf{C}(u,v)\bigr)/(1 - u) |
\mathrm{Pr}[\,U > u \mid V > v\,] | = | \hat{\mathbf{C}}(u',v')/u' = \overline{\mathbf{C}}(u,v)/(1-u) |
\mathrm{Pr}[\,V > v \mid U > u\,] | = | \hat{\mathbf{C}}(u',v')/v' = \overline{\mathbf{C}}(u,v)/(1-v) |
\mathrm{Pr}[\,V \le v \mid U = u\,] | = | \delta \mathbf{C}(u,v)/\delta u --- Partial derivative, derCOP |
\mathrm{Pr}[\,U \le u \mid V = v\,] | = | \delta \mathbf{C}(u,v)/\delta v --- Partial derivative, derCOP2 |
\mathrm{Pr}[\,U > u \mathrm{\ or\ } V > v\,] | = | \mathbf{C}^\star(u',v') = 1 - \mathbf{C}(u',v') --- The co-copula, coCOP |
\mathrm{Pr}[\,U \le u \mathrm{\ or\ } V \le v\,] | = | \tilde{\mathbf{C}}(u,v) = u + v - \mathbf{C}(u,v) --- The dual of a copula, duCOP |
The function jointCOP has considerable demonstration in its Note section of the joint and and joint or relations shown through simulation and counting scenarios. Also there is a demonstration in the Note section of function duCOP on application of the concepts of joint and conditions, joint or conditions, and importantly joint mutually exclusive or conditions.
Permutation asymmetry can be added to a copula by breveCOP. One, two, or more copulas can be “composited,” “combined,” or “multiplied” in interesting ways to create highly unique bivariate relations and as a result, complex dependence structures can be formed. The package provides three main functions for copula composition: composite1COP composites a single copula with two compositing parameters, composite2COP composites two copulas with two compositing parameters, and composite3COP composites two copulas with four compositing parameters. Also two copulas can be combined through a weighted convex combination using convex2COP with a single weighting parameter, and even N number of copulas can be combined by weights using convexCOP. So-called “gluing” two copula by a parameter is provided by glueCOP. Finally, multiplication of two copulas to form a third is supported by prod2COP. All seven functions for compositing, combining, or multipling copulas are compatible with joint probability simulation (simCOP), measures of association (e.g. \rho_\mathbf{C}), and presumably all other copula operations using copBasic features.
| No. of copulas | Combining Parameters | Function | Concept |
| 1 | \beta | breveCOP | adding permuation asymmetry |
| 1 | \alpha, \beta | composite1COP | copula combination |
| 2 | \alpha, \beta | composite2COP | copula combination |
| 2 | \alpha, \beta, \kappa, \gamma | composite3COP | copula combination |
| 2 | \alpha, (1-\alpha) | convex2COP | weighted copula combination |
N | \omega_{i \in N} | convexCOP | weighted copula combination |
| 2 | \gamma | glueCOP | gluing of coupla |
| 2 | \bigl(\mathbf{C}_1 \ast \mathbf{C}_2 \bigr) | prod2COP | copula multiplication |
Useful Copula Relations by Visualization
There are a myriad of relations amongst variables computable through copulas, and these were listed in the Table of Probabilities earlier in this documentation. There is a script located in the inst/doc directory of the copBasic sources titled CopulaRelations_BaseFigure_inR.txt. This script demonstrates, using the PSP copula, relations between the copula (COP), survival copula (surCOP), joint survival function of a copula (surfuncCOP), co-copula (coCOP), and dual of a copula function (duCOP). The script performs simulation and manual counts observations meeting various criteria in order to compute their empirical probabilities. The script produces a base figure, which after extending in editing software, is suitable for educational description and is provided at the end of this documentation.
A Review of “Return Periods” using Copulas
Risk analyses of natural hazards are commonly expressed as annual return periods T in years, which are defined for a nonexceedance probability q as T = 1/(1-q). In bivariate analysis, there immediately emerge two types of return periods representing T_{q;\,\mathrm{coop}} and T_{q;\,\mathrm{dual}} conditions between nonexceedances of the two hazard sources (random variables) U and V. It is usual in many applications for T to be expressed equivalently as a probability q in common for both variables.
Incidentally, the \mathrm{Pr}[\,U > u \mid V > v\,] and \mathrm{Pr}[\,V > v \mid U > u\,] probabilities also are useful for conditional return period computations following Salvadori et al. (2007, pp. 159–160) but are not further considered here. Also the F_K(w) (Kendall Function or Kendall Measure of a copula) is the core tool for secondary return period computations (see kfuncCOP).
Let the copula \mathbf{C}(u,v; \Theta) for nonexceedances u and v be set for some copula family (formula) by a parameter vector \Theta. The copula family and parameters define the joint coupling (loosely meant the dependency/correlation) between hazards U and V. If “failure” occurs if either or both hazards U and V are at probability q threshold (u = v = 1 - 1/T = q) for T-year return period, then the real return period of failure is defined using either the copula \mathbf{C}(q,q; \Theta) or the co-copula \mathbf{C}^\star(q',q'; \Theta) for exceedance probability q' = 1 - q is
T_{q;\,\mathrm{coop}} = \frac{1}{1 - \mathbf{C}(q, q; \Theta)} = \frac{1}{\mathbf{C}^\star(1-q, 1-q; \Theta)}\mbox{\ and}
T_{q;\,\mathrm{coop}} \equiv \frac{1}{\mathrm{cooperative\ risk}}\mbox{.}
Or in words, the hazard sources collaborate or cooperate to cause failure. If failure occurs, however, if and only if both hazards U and V occur simultaneously (the hazards must “dually work together” or be “conjunctive”), then the real return period is defined using either the dual of a copula (function) \tilde{\mathbf{C}}(q,q; \Theta), the joint survival function \overline{\mathbf{C}}(q,q;\Theta), or survival copula \hat{\mathbf{C}}(q',q'; \Theta) as
T_{q;\,\mathrm{dual}} = \frac{1}{1 - \tilde{\mathbf{C}}(q,q; \Theta)} = \frac{1}{\overline{\mathbf{C}}(q,q;\Theta)} = \frac{1}{\hat{\mathbf{C}}(q',q';\Theta)} \mbox{\ and}
T_{q;\,\mathrm{dual}} \equiv \frac{1}{\mathrm{complement\ of\ dual\ protection}}\mbox{.}
Numerical demonstration is informative. Salvadori et al. (2007, p. 151) show for a Gumbel–Hougaard copula (GHcop) having \Theta = 3.055 and T = 1,000 years (q = 0.999) that T_{q;\,\mathrm{coop}} = 797.1 years and that T_{q;\,\mathrm{dual}} = 1,341.4 years, which means that average return periods between “failures” are
T_{q;\,\mathrm{coop}} \le T \le T_{q;\,\mathrm{dual}}\mbox{\ and thus}
797.1 \le T \le 1314.4\mbox{\ years.}
With the following code, these bounding return-period values are readily computed and verified using the prob2T() function from the lmomco package along with copBasic functions COP (generic functional interface to a copula) and duCOP (dual of a copula):
q <- T2prob(1000) lmomco::prob2T( COP(q,q, cop=GHcop, para=3.055)) # 797.110 lmomco::prob2T(duCOP(q,q, cop=GHcop, para=3.055)) # 1341.438
An early source (in 2005) by some of those authors cited on p. 151 of Salvadori et al. (2007; their citation “[67]”) shows T_{q;\,\mathrm{dual}} = 798 years—a rounding error seems to have been committed. Finally just for reference, a Gumbel–Hougaard copula having \Theta = 3.055 corresponds to an analytical Kendall Tau (see GHcop) of \tau \approx 0.673, which can be verified through numerical integration available from tauCOP as:
tauCOP(cop=GHcop, para=3.055, brute=TRUE) # 0.6726542
Thus, a “better understanding of the statistical characteristics of [multiple hazard sources] requires the study of their joint distribution” (Salvadori et al., 2007, p. 150).
Interaction of copBasic to Copulas in Other Packages
Originally, the copBasic package was not intended to be a port of the numerous bivariate copulas or over re-implementation other bivariate copulas available in R though as the package passed its 10th year in 2018, the original intent changed. It is useful to point out a demonstration showing an implementation of the Gaussian copula from the copula package, which is shown in the Note section of med.regressCOP in a circumstance of ordinary least squares linear regression compared to median regression of a copula as well as prediction limits of both regressions. Another demonstration in context of maximum pseudo-log-likelihood estimation of copula parameters is seen in the Note section mleCOP, and also see “API to the copula package” or “package copula (comparison to)” entries in the Index of this user manual.
Author(s)
William Asquith william.asquith@ttu.edu
References
Cherubini, U., Luciano, E., and Vecchiato, W., 2004, Copula methods in finance: Hoboken, NJ, Wiley, 293 p.
Hernández-Maldonado, V., Díaz-Viera, M., and Erdely, A., 2012, A joint stochastic simulation method using the Bernstein copula as a flexible tool for modeling nonlinear dependence structures between petrophysical properties: Journal of Petroleum Science and Engineering, v. 90–91, pp. 112–123.
Joe, H., 2014, Dependence modeling with copulas: Boca Raton, CRC Press, 462 p.
Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p.
Salvadori, G., De Michele, C., Kottegoda, N.T., and Rosso, R., 2007, Extremes in nature—An approach using copulas: Dordrecht, Netherlands, Springer, Water Science and Technology Library 56, 292 p.
Examples
## Not run:
# Nelsen (2006, p. 75, exer. 3.15b) provides for a nice test of copBasic features.
"mcdurv" <- function(u,v, theta) {
ifelse(u > theta & u < 1-theta & v > theta & v < 1 - theta,
return(M(u,v) - theta), # Upper bounds copula with a shift
return(W(u,v))) # Lower bounds copula
}
"MCDURV" <- function(u,v, para=NULL) {
if(is.null(para)) stop("need theta")
if(para < 0 | para > 0.5) stop("theta ! in [0,1/2]")
return(asCOP(u, v, f=mcdurv, para))
}
"afunc" <- function(t) { # a sample size = 1,000 hard wired
return(cov(simCOP(n=1000, cop=MCDURV, para=t, ploton=FALSE, points=FALSE))[1,2])
}
set.seed(6234) # setup covariance based on parameter "t" and the "root" parameter
print(uniroot(afunc, c(0,0.5))) # "t" by simulation = 0.1023742
# Nelsen reports that if theta appox. 0.103 then covariance of U and V is zero.
# So, one will have mutually completely dependent uncorrelated uniform variables!
# Let us check some familiar measures of association:
rhoCOP( cop=MCDURV, para=0.1023742) # Spearman Rho = 0.005854481 (near zero)
tauCOP( cop=MCDURV, para=0.1023742) # Kendall Tau = 0.2648521
wolfCOP(cop=MCDURV, para=0.1023742) # S & W Sigma = 0.4690174 (less familiar)
D <- simCOP(n=1000, cop=MCDURV, para=0.1023742) # Plot mimics Nelsen (2006, fig. 3.11)
# Lastly, open research problem. L-comoments (matrices) measure high dimension of
# variable comovements (see lmomco package)---"method of L-comoments" for estimation?
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0), nmom=5) # Perfect neg. corr.
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0.1023742), nmom=5)
lmomco::lcomoms2(simCOP(n=1000, cop=MCDURV, para=0.5), nmom=5) # Perfect pos. corr.
# T2 (L-correlation), T3 (L-coskew), T4 (L-cokurtosis), and T5 matrices result. For
# Theta = 0 or 0.5 see the matrix symmetry with a sign change for L-coskew and T5 on
# the off diagonals (offdiags). See unities for T2. See near zero for offdiag terms
# in T2 near zero. But then see that T4 off diagonals are quite different from those
# for Theta 0.1024 relative to 0 or 0.5. As a result, T4 has captured a unique
# property of U vs V.
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.