kfuncCOPlmoms: The L-moments of the Kendall Function of a Copula

Description

Compute the L-moments of the Kendall Function ($F_K(z; \mathbf{C})$) of a copula $\mathbf{C}(u,v)$ where the $z$ is the joint probability of the $\mathbf{C}(u,v)$. The Kendall Function is the cumulative distribution function (CDF) of the joint probability $Z$ of the coupla. The expected value of the $z(F_K)$ (mean, first L-moment $\lambda_1$), because $Z$ has nonzero probability for $0 \le Z \le \infty$, is

$$\mathrm{E}[Z] = \lambda_1 = \int_0^\infty [1 - F_K(t)]\,\mathrm{d}t = \int_0^1 [1 - F_K(t)] \,\mathrm{d}t\mbox{,}$$

where for circumstances here $0 \le Z \le 1$. The $\infty$ is mentioned only because expectations of such CDFs are usually shown using $(0,\infty)$ limits, whereas integration of quantile functions (CDF inverses) use limits $(0,1)$. Because the support of $Z$ is $(0,1)$, like the probability $F_K$, showing just it ($\infty$) as the upper limit could be confusing---statements such as ``probabilities of probabilities'' are rhetorically complex so pursuit of word precision is made herein.

An expression for $\lambda_r$ for $r \ge 2$ in terms of the $F_K(z)$ is $$ \lambda_r = \frac{1}{r}\sum_{j=0}^{r-2} (-1)^j {r-2 \choose j}{r \choose j+1} \int_{0}^{1} \! [F_K(t)]^{r-j-1}\times [1 - F_K(t)]^{j+1}\, \mathrm{d}t\mbox{,} $$ where because of these circumstances the limits of integration are $(0,1)$ and not $(-\infty, \infty)$ as in the usual definition of L-moments in terms of a distribution's CDF.

The mean, L-scale, coefficient of L-variation ($\tau_2$, LCV, L-scale/mean), L-skew ($\tau_3$, TAU3), L-kurtosis ($\tau_4$, TAU4), and $\tau_5$ (TAU5) are computed. In usual nomenclature, the L-moments are $ \lambda_1 = \mbox{mean,}$ $ \lambda_2 = \mbox{L-scale,}$ $ \lambda_3 = \mbox{third L-moment,}$ $ \lambda_4 = \mbox{fourth L-moment, and}$ $ \lambda_5 = \mbox{fifth L-moment,}$ whereas the L-moment ratios are $ \tau_2 = \lambda_2/\lambda_1 = \mbox{coefficient of L-variation, }$ $ \tau_3 = \lambda_3/\lambda_2 = \mbox{L-skew, }$ $ \tau_4 = \lambda_4/\lambda_2 = \mbox{L-kurtosis, and}$ $ \tau_5 = \lambda_5/\lambda_2 = \mbox{not named.}$ It is common amongst practitioners to lump the L-moment ratios into the general term “L-moments” and remain inclusive of the L-moment ratios. For example, L-skew then is referred to as the 3rd L-moment when it technically is the 3rd L-moment ratio. There is no first L-moment ratio (meaningless) so results from this function will canoncially show a NA in that slot. The coefficient of L-variation is $\tau_2$ (subscript 2) and not Kendall Tau ($\tau$). Sample L-moments are readily computed by several packages in R (e.g. lmomco, lmom, Lmoments, POT).

Usage

kfuncCOPlmom(r, cop=NULL, para=NULL, ...)
kfuncCOPlmoms(cop=NULL, para=NULL, nmom=5, begin.mom=1, ...)

Arguments

The $r$th order of a single L-moment to compute;

cop

A copula function;

para

Vector of parameters or other data structure, if needed, to pass to the copula;

nmom

The number of L-moments to compute;

begin.mom

The $r$th order to begin the sequence lambegr:nmom for L-moment computation. The rarely used argument is means to bypass the computation of the mean if the user has an alternative method for the mean or other central tendency characterization in which case begin.mom = 2; and

...

Additional arguments to pass.

Value

An R list is returned by kfuncCOPlmoms and only the scalar value of $\lambda_r$ by kfuncCOPlmom.

lambdas

Vector of the L-moments. First element is $\lambda_1$, second element is $\lambda_2$, and so on;

ratios

Vector of the L-moment ratios. Second element is $\tau$, third element is $\tau_3$ and so on; and

source

An attribute identifying the computational source of the L-moments: “kfuncCOPlmoms”.

References

Asquith, W.H., 2011, Distributional analysis with L-moment statistics using the R environment for statistical computing: Createspace Independent Publishing Platform, ISBN 978--146350841--8.

Examples

Run this code

# NOT RUN {
kfuncCOPlmom(1, cop=P) # 0.5 * 0.5 = 0.25 is expected joint prob. of independence
#[1] 0.2499999  (in agreement with theory)

ls.str(kfuncCOPlmoms(cop=GHcop, para=4.21)) # Gumbel-Hougaard copula
# lambdas :  num [1:5] 0.440617 0.169085 0.011228 -0.000797 0.000249
# ratios  :  num [1:5]       NA 0.38375  0.0664   -0.00472  0.00147
# source  :  chr "kfuncCOPlmoms"  # e.g. L-skew = 0.0664
# }
# NOT RUN {
# }
# NOT RUN {
UV <- simCOP(200, cop=PLcop, para=1/pi, graphics=FALSE)
theta <- PLpar(UV[,1], UV[,2]); zs <- seq(0.01,0.99, by=.01) # for later

# Take the sample estimated parameter and convert to joint probabilities Z
# Convert the Z to the Kendall Function estimates again with the sample parameter
Z  <- PLcop(UV[,1], UV[,2], para=theta); KF <- kfuncCOP(Z, cop=PLcop, para=theta)

# Compute L-moments of the "Kendall function" and the sample versions
# Note again though that the L-moment are for the distribution of the Z!
KNFlmr <- kfuncCOPlmoms(cop=PLcop, para=theta); SAMlmr <- lmomco::lmoms(Z)
knftxt <- paste0("Kendall L-moments: ",
                 paste(round(KNFlmr$lambdas, digits=4), collapse=", "))
samtxt <- paste0("Sample L-moments: " ,
                 paste(round(SAMlmr$lambdas, digits=4), collapse=", "))

plot(Z, KF, xlim=c(0,1), ylim=c(0,1), lwd=0.8, col=1,
     xlab="COPULA(u,v) VALUE [JOINT PROBABILITY]",
     ylab="KENDALL FUNCTION, AS NONEXCEEDANCE PROBABILITY")
rug(Z,  side=1, col=2, lwd=0.2); rug(KF, side=2, col=2, lwd=0.2) # rug plots
lines(zs, kfuncCOP(zs, cop=PLcop, para=1/pi), col=3)
knf_meanZ <- KNFlmr$lambdas[1]; sam_meanZ <- SAMlmr$lambdas[1]
knf_mean  <- kfuncCOP(knf_meanZ, cop=PLcop, para=theta) # theo. Kendall function
sam_mean  <- kfuncCOP(sam_meanZ, cop=PLcop, para=theta) # sam. est. of Kendall func
points(knf_meanZ, knf_mean, pch=16, col=4, cex=4) # big blue dot
points(sam_meanZ, sam_mean, pch=16, col=5, cex=2) # smaller pale blue dot
lines(zs, zs-zs*log(zs), lty=2, lwd=0.8) # dash ref line for independence
text(0.2, 0.30, knftxt, pos=4, cex=0.8); text(0.2, 0.25, samtxt, pos=4, cex=0.8)
text(0.2, 0.18, paste0("Note the uniform distribution of the ",
                       "vertical axis rug."), cex=0.7, pos=4) #
# }