Search Results:

Showing results 1 to 10 of 10.


Function ms [lubridate v1.7.10]
keywords
period
title
Parse periods with hour, minute, and second components
description
Transforms a character or numeric vector into a period object with the specified number of hours, minutes, and seconds. hms() recognizes all non-numeric characters except '-' as separators ('-' is used for negative durations). After hours, minutes and seconds have been parsed, the remaining input is ignored.
Function pplot.pcp [precintcon v2.3.0]
keywords
period
title
Plot Precipitation Concentration Period per Year
description
Plots the Precipitation Concentration Period per year of a precipitation serie.
Function GMLTimePeriod [geometa v0.6-3]
keywords
period
title
GMLTimePeriod
description
GMLTimePeriod
Function ISOTimePeriod [geometa v0.6-3]
keywords
period
title
ISOTimePeriod
description
ISOTimePeriod
Function time_length [lubridate v1.7.10]
keywords
period
title
Compute the exact length of a time span
description
Compute the exact length of a time span
Function surfuncCOP [copBasic v2.1.5]
keywords
conditional return period
title
The Joint Survival Function
description
Compute the joint survival function for a copula (Nelsen, 2006, p. 33), which is defined as $$\overline{\mathbf{C}}(u,v) = \mathrm{Pr}[U > u, V > v] = 1 - u - v + \mathbf{C}(u,v) = \hat\mathbf{C}(1-u, 1-v)\mbox{,}$$ where \(\hat\mathbf{C}(u',v')\) is the survival copula (see surCOP), which is defined by $$\hat{\mathbf{C}}(u',v') = \mathrm{Pr}[U > u, V > v] = u' + v' - 1 + \mathbf{C}(1-u',1-v')\mbox{.}$$ Although the joint survival function is an expression of the probability that both \(U > v\) and \(U > v\), \(\overline{\mathbf{C}}(u,v)\) not a copula.
Function copBasic-package [copBasic v2.1.5]
keywords
return period (conditional),return period (secondary)
title
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 hoped in part 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 occassionally 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<U+00E9>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<U+00FC>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 bivariate moments Bivariate L-comoments \(\tau^{[\ldots]}_{k;\mathbf{C}}\) bilmoms bivariate moments Bivariate L-comoments \(\tau^{[\ldots]}_{k;\mathbf{C}}\) 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 \(\Phi_\mathbf{C} \rightarrow L_p\) LpCOP bivariate association 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 compuations 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, and that function is the theoretical counterpart to the sample L-comoments long 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 utilites 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)\) \(\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\,]\) \(=\) \(\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\) \(\mathrm{Pr}[\,U \le u \mid V = v\,]\) \(=\) \(\delta \mathbf{C}(u,v)/\delta v\) \(\mathrm{Pr}[\,U > u \mathrm{\ or\ } V > v\,]\) \(=\) \(\mathbf{C}^\star(u',v') = 1 - \mathbf{C}(u',v')\) \(\mathrm{Pr}[\,U \le u \mathrm{\ or\ } V \le v\,]\) \(=\) \(\tilde\mathbf{C}(u,v) = u + v - \mathbf{C}(u,v)\) 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. One, two, or more copulas can be “composited,” “combined,” or “multiplied” in interesting ways to create highly unique bivariate relationsm and as a result, complex dependence structures can be formed. copBasic 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. Finally, multiplication of two copulas to form a third is supported by prod2COP. All six 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 \(\alpha, \beta\) composite1COP copula combination 2 \(\alpha, \beta\) composite2COP copula combination 2 \(\alpha, \beta, \kappa, \gamma\) composite3COP copula combination 2 \(\alpha\) convex2COP copula combination \(N\) \(\omega_{i \in N}\) convexCOP copula combination 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 copBasic 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 herein. 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. Incidently, 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, p. 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 a 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. However, if failure only occurs 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{.}$$ A 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 and “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 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's 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 As mentioned elsewhere, copBasic was not originally intended to be a port of the numerous bivariate copulas or over re-implementation other bivariate copulas available in R. (Though as the package passes its 10th year in 2018, this has gradually changed.) It is useful to point out a demonstration showing an implemention 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.
Function segMGarch-package [segMGarch v1.2]
keywords
multiple change-point detection, multivariate GARCH, stress period selection, Double CUSUM Binary Segmentation, high dimensionality, nonstationarity
title
Multiple Change-Point Detection for High-Dimensional GARCH Processes
description
Implements a segmentation algorithm for multiple change-point detection in high-dimensional GARCH processes described in Cho and Korkas (2018) ("High-dimensional GARCH process segmentation with an application to Value-at-Risk." arXiv preprint arXiv:1706.01155). It simultaneously segments GARCH processes by identifying 'common' change-points, each of which can be shared by a subset or all of the component time series as a change-point in their within-series and/or cross-sectional correlation structure. We adopt the Double CUSUM Binary Segmentation procedure Cho (2016), which achieves consistency in estimating both the total number and locations of the multiple change-points while permitting within-series and cross-sectional correlations, for simultaneous segmentation of the panel data of transformed time series. It also provides additional functions and methods that relate to risk management measures and backtests.
Function cpgeeSWD [geeCRT v0.0.1]
keywords
cluster-period-means
title
Cluster-Period GEE for Estimating the Mean and Correlation Parameters in Cross-Sectional SW-CRTs
description
cpgeeSWD implements the cluster-period GEE developed for cross-sectional stepped wedge cluster randomized trials (SW-CRTs). It provides valid estimation and inference for the treatment effect and intraclass correlation parameters within the GEE framework, and is computationally efficient for SW-CRTs with large cluster sizes. The program currently only allows for a marginal mean model with discrete period effects and the intervention indicator without additional covariates. The program offers bias-corrected ICC estimates as well as bias-corrected sandwich variances for both the treatment effect parameter and the ICC parameters. The technical details of the cluster-period GEE approach are provided in Li et al. (2020+).
Function kfuncCOP [copBasic v2.1.5]
keywords
return period (secondary)
title
The Kendall (Distribution) Function of a Copula
description
To begin, there are at least three terms in the literature for what appear as the same function supported by the kfuncCOP function. The Kendall Function also is known as Kendall Distribution Function (Nelsen, 2006, p. 163) and Kendall Measure (Salvadori et al., 2007, p. 148). Each of these is dealt with in sequel to set the manner of the rather lengthy documentation for this function. KENDALL FUNCTION---The Kendall Function (\(F_K\)) (Joe, 2014, pp. 419--422) is the cumulative distribution function (CDF) of the vector \(\mathbf{U} = (U_1, U_2, \ldots)\) or \(\mathbf{U} = (u,v)\) (bivariate) where \(\mathbf{U}\) is distributed as the copula: \(\mathbf{U} \sim \mathbf{C}(u,v)\). Letting \(Z\) be the random variable for \(\mathbf{C}(u,v): Z = \mathbf{C}(u,v)\), the Kendall Function is defined as $$F_K(z; \mathbf{C}) = \mathrm{Pr}[Z \le z; \mathbf{U} \sim \mathbf{C}(u,v)]\mbox{,}$$ where \(F_K\) is the nonexceedance probability of the joint probability \(z\) stemming from the \(\mathbf{C}\). Note that unlike its univariate counterpart, \(F_K(z)\) is rarely uniformly distributed (Nelsen et al., 2001, p. 278). The inverse \(F_K^{(-1)}(z)\) is implemented by the kfuncCOPinv function, which could be used for simulation of the correct joint probability using a single unformly distributed \(\sim\) U(0,1) random variable. A reminder is needed that \(Z\) is the joint probability and \(F_K(z)\) is the Kendall Function. Joe (2014) and others as cited list various special cases of \(F_K(z)\), inequalities, and some useful identities suitable for validation study: \(\mbox{}\quad\bullet\quad\mbox{}\)For \(\mathbf{M}(u,v)\) (see M): \(F_K(z) = z\) for all \(0 < z < 1\) for all \(d \ge 2\) dimensions; \(\mbox{}\quad\bullet\quad\mbox{}\)For \(\mathbf{W}(u,v)\) (see W): \(F_K(z) = 1\) for all \(0 < z < 1\) for \(d = 2\) (bivariate only); \(\mbox{}\quad\bullet\quad\mbox{}\)For \(\mathbf{\Pi}(u,v)\) (see P): \(F_K(z) = z - z \log z\) for \(0 < z < 1\) for \(d = 2\) (bivariate only); \(\mbox{}\quad\bullet\quad\mbox{}\)For any \(\mathbf{C}\): \(z \le F_K(z)\) for \(0 < z < 1\); and \(\mbox{}\quad\bullet\quad\mbox{}\)For any \(\mathbf{C}\): \(\mathrm{E}[Z] = 1 - \int_0^1 F_K(t)\,\mathrm{d}t \ge z\) (Nelsen, 2001, p. 281) --- Z expectation, not \(F_K\)! \(\mbox{}\quad\bullet\quad\mbox{}\)For any \(\mathbf{C}\): \(\tau_\mathbf{C} = 3 - 4\int_0^1 F_K(t)\,\mathrm{d}t\) (Nelsen, 2006, p. 163; see tauCOP [Examples]). \(\mbox{}\quad\bullet\quad\mbox{}\)For any \(\mathbf{C}\): \(F_K(t)\) does not uniquely determine the copula. This last item is from Durante and Sempi (2015, p. 118), and later discussion herein will concern an example of theirs. By coincidence within a few days before receipt of the Durante and Sempi book, experiments using kfuncCOP suggested that numerically the Galambos (GLcop), Gumbel--Hougaard (GHcop), and H<U+00FC>sler--Reiss (HRcop) extreme value copulas for the same Kendall Tau (\(\tau_\mathbf{C}\)) all have the same \(F_K(t)\). Therefore, do all EV-copulas have the same Kendall Function? Well in fact, they do and Durante and Sempi (2015, p. 207) show that \(F_K(z) = z - (1 - \tau_\mathbf{C})z \log(z)\) for an EV-copula. Joe (2014, p. 420) also indicates that strength of lower-tail dependence (taildepCOP) affects \(F_K(z)\) as \(z \rightarrow 0^{+}\), whereas strength of upper-tail dependence affects \(F_K(z)\) as \(z \rightarrow 1^{-}\). (A demonstration of tail dependence dependence is made in section Note.) Also compared to comonotonicity copula [\(\mathbf{M}\)] there are no countermonotonicity copula (\(\mathbf{W}_{d > 2}\)) for dimensions greater the bivariate (Joe, 2014, p. 214) Joe (2014) does not explicitly list an expression of \(F_K(z)\) that is computable directly for any \(\mathbf{C}(u,v)\), and Nelsen (2006, p. 163) only lists a form (see later in documentation) for Archimedean copulas. Salvadori et al. (2007, eq. 3.47, p. 147) also list the Archimedean form; however, Salvadori et al. (2007, eq. 3.49, p. 148) also list a form computable directly for any \(\mathbf{C}(u,v)\). Considerable numerical experiments and derivations involving the \(\mathbf{\Pi}(u,v)\) copula and results for \(K_\mathbf{C}(z)\) shown later, indicate that the correct Kendall form for any \(\mathbf{C}(u,v)\) is $$F_K(z) \equiv z + \int_z^1 \frac{\delta\mathbf{C}(u,t)}{\delta u}\,\mathrm{d}u\mbox{,}$$ where \(t = \mathbf{C}^{(-1)}(u,z)\) for \(0 \le z \le 1\), \(t\) can be computed by the COPinv function, and the partial derivative \(\delta\mathbf{C}(u,t)/\delta u\) can be computed by the derCOP function. It is a curiosity that this form is not in Joe (2014), Nelsen et al. (2001, 2003), Nelsen (2006), or actually in Salvadori et al. (2007). KENDALL MEASURE---The actual expression for any \(\mathbf{C}(u,v)\) by Salvadori et al. (2007, eq. 3.49, p. 148) is for Kendall Measure (\(K_\mathbf{C}\)) of a copula: $$K_\mathbf{C}(z) = z - \int_z^1 \frac{\delta\mathbf{C}(u,t)}{\delta u}\,\mathrm{d}u\mbox{,}$$ where \(t = \mathbf{C}^{(-1)}(u,z)\) for \(0 \le z \le 1\). Those authors report that \(K_\mathbf{C}(z)\) is the CDF of a random variable \(Z\) whose distribution is \(\mathbf{C}(u,v)\). This is clearly appears to be the same meaning as Joe (2014) and Nelsen (2006). The minus “\(-\)” in the above equation is very important. Salvadori et al. (2007, p. 148) report that “the function \(K_\mathbf{C}(z)\) represents a fundamental tool for calculating the return period of extreme events.” The complement of \(K_\mathbf{C}(z)\) is \(\overline{K}_\mathbf{C}(z) = 1 - K_\mathbf{C}(z)\), and the \(\overline{K}_\mathbf{C}(z)\) inverse $$\frac{1}{1 - K_\mathbf{C}(z)} = \frac{1}{\overline{K}_\mathbf{C}(z)} = T_{\mathrm{KC}}$$ is referred to as a secondary return period (Salvadori et al., 2007, pp. 161--170). KENDALL DISTRIBUTION FUNCTION---Nelsen (2006, p. 163) defines the Kendall Distribution Function (say \(K^\star_\mathbf{C}(t)\)) as $$K^\star_\mathbf{C}(t) = t - \frac{\phi(t)}{\phi'(t^{+})}\mbox{,}$$ where \(\phi(t)\) is a generator function of an Archimedean copula and \(\phi'(t^{+})\) is a one-sided derivative (Nelsen, 2006, p. 125), and \(\phi(t)\) is \(\phi(\mathbf{C}(u,v)) = \phi(u) + \phi(v)\). This same form is listed by Salvadori et al. (2007, eq. 3.47). Nelsen (2006) does not seem to list a more general definition for any \(\mathbf{C}(u,v)\). Because there is considerable support for Archimedean copulas in R, copBasic has deliberately been kept from being yet another Archimedean-based package. This is made for more fundamental theory and pedogogic reasons without the algorithmic efficiency relative to the many convenient properties of Archimedean copulas. The similarity of \(F_K(z)\), \(K_\mathbf{C}(z)\), and \(K^\star_\mathbf{C}(t)\), however, is obvious---research shows that there are no syntatic differences between \(F_K(z)\) and \(K_\mathbf{C}(t)\) and \(K^\star_\mathbf{C}(z)\)---they all are the CDF of the joint probability \(Z\) of the copula. Consider now that Salvadori et al. show \(K_\mathbf{C}\) having the form \(a - b\) and not a form \(a + b\) as previously shown for \(F_K(z)\). Which form is thus correct? The greater bulk of this documentation seeks to answer that question, and it must be concluded that Salvadori et al. (2007, eq. 3.49) definition for \(K_\mathbf{C}(z)\) has a typesetting error.