diagCOPatf: Numerical Rooting the Diagonal of a Copula

In copBasic: General Bivariate Copula Theory and Many Utility Functions

Numerical Rooting the Diagonal of a Copula

Description

Compute a numerical root along the primary diagonal (Nelsen, 2006, pp. 12 and 16) of copula \mathbf{C}(u,v) = F = \mathbf{C}(t,t) having joint probability F. The diagonals treat the nonexceedance probabilities u and v as equals (u=v=t). The primary diagonal is defined for a joint nonexceedance probability t as

F = \mathbf{C}(t,t) \rightarrow t = \delta_{\mathbf{C}}^{(-1)}(f)\mbox{,}

where the function solves for t. Examples using the concept behind diagCOPatf are available under duCOP and jointCOP, thus the diagCOPatf function can be also called by either jointCOP and joint.curvesCOP. Internally, the function uses limits of the root finder that are not equal to the anticipated interval [0,1], but equal to “small” (see description for argument interval). The function does trap for f = 0 by returning zero and f = 1 by returning unity.

Usage

diagCOPatf(f, cop=NULL, para=NULL, interval=NULL, silent=TRUE, verbose=FALSE,
                                   tol=.Machine$double.eps/10, ...)
diagCOPinv(f, cop=NULL, para=NULL, interval=NULL, silent=TRUE, verbose=FALSE,
                                   tol=.Machine$double.eps/10, ...)

Arguments

f	Joint probability values as a nonexceedance probability F for which to compute the root t;
cop	A copula function;
para	Vector of parameters, if needed, to pass to the copula;
interval	An optional interval for the root search. The default is interval=c(lo, 1-lo) for lo=.Machine$double.eps because of difficulties for an interval on [0,1];
silent	The argument of the same name given over to try() wrapping the uniroot() operation;
verbose	If TRUE then the whole output of the numerical root is returned using only the first value provided by argument f;
tol	The tolerance to pass to uniroot. The default here is much smaller than the default of the uniroot() function in R because of possibility that diagCOPatf would be used at extremely large nonexceedance probabilities; and
...	Additional arguments to pass.

Value

An R list of the root by the uniroot() function in R is returned if verbose is TRUE, otherwise the roots (diagonal inverses) for t are returned, and if an individual inverse operation fails, then a NA is returned instead.

Author(s)

W.H. Asquith

References

Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p.

See Also

diagCOP, jointCOP, joint.curvesCOP

Examples

diagCOPatf(0.67, cop=PSP) # 0.8023879
diagCOPatf(0.99, cop=M)   # 0.99 (now see the example below)

## Not run: 
# Several functions from the lmomco package are needed.
# Suppose we have two phenomena with these log10 L-moments:
lmrA <- lmomco::vec2lmom(c(3.97, 0.485, -0.1178, 0.06857))
lmrB <- lmomco::vec2lmom(c(3.77, 0.475, -0.1377, 0.08280))
# Suppose we think that the Gumbel-Hougaard copula is appropriate with a Tau=0.45
Tau <- 0.45 #  Kendall Tau between A and B.
# Suppose that the F=0.99 for either A and B provides a common risk level when they
# are considered in isolation. But what if A and B are rivers that join and joint
# FF=0.99 at their union is of interest?
FF <- 0.99
parA   <- lmomco::lmom2par(lmrA, type="kap")
parB   <- lmomco::lmom2par(lmrB, type="kap")
EventA <- lmomco::qlmomco(FF, parA)
EventB <- lmomco::qlmomco(FF, parB)
ApB <- 10^(EventA) + 10^(EventB) # Purely an additive conceptualization
# The FF=0.99 event is assumed to occur simultaneously on both streams, which is
# equivalent to saying that the correlation between the two is absolute 1-to-1.

# Now consider including the association as measured by Kendall Tau:
Fjoint  <- diagCOPatf(FF, cop=GHcop, para=GHcop(tau=Tau)$para)
EventAj <- lmomco::qlmomco(Fjoint, parA)
EventBj <- lmomco::qlmomco(Fjoint, parB)
AcB <- 10^(EventAj) + 10^(EventBj) # Joint probability 0.99 at the union

# Now consider the association if the rivers are INDEPENDENT:
Fjoint  <- diagCOPatf(FF, cop=GHcop, para=GHcop(tau=0)$para)
EventAj <- lmomco::qlmomco(Fjoint, parA)
EventBj <- lmomco::qlmomco(Fjoint, parB)
AiB <- 10^(EventAj) + 10^(EventBj) # Joint probability 0.99 at the union

# ApB = 312,000 # The perfectly simultaneous addition makes too little.
# AcB = 323,000 # The copula preserves at least the known association.
# AiB = 330,000 # The independence conceptualization makes too much.
## End(Not run)

copBasic documentation built on June 28, 2025, 1:08 a.m.