# Numerical Rooting the Diagonal of a Copula 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 [REMOVE_ME]$$ F = \mathbf{C}(t,t) \rightarrow t = \delta_{\mathbf{C}}^{(-1)}(f)\mbox{,} [REMOVE_ME_2]$$ 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. utf8 ## 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. ```r 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 `tol`erance to pass to `uniroot`. The default here is much smaller than the default of the `uniroot()` function in because of possibility that `diagCOPatf` would be used at extremely large nonexceedance probabilities; and - `...`: Additional arguments to pass. ## Returns An `list` of the root by the `uniroot()` function in 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. ## References Nelsen, R.B., 2006, An introduction to copulas: New York, Springer, 269 p. ## Author(s) W.H. Asquith ## See Also `diagCOP`, `jointCOP`, `joint.curvesCOP` ## Examples ```r 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) ```

diagCOPatf function