TLMoments is a set of functions whose main functionality is the calculation of Trimmed L-moments and their parameter and quantile estimates. One of the goals is to reduce computation time compared to existing implementations (in packages like lmomco, Lmoments, Lmom), therefore the core functions are written in C++ (see vignette “comparison of computation time” for speed comparisons). Furthermore, the package expands the combinations of trimmings that can be used to estimate distribution parameters in comparison to existing packages (which mainly supports parameter estimation with L-moments). To ensure an easy usage, the package only contains a small set of functions. This vignette gives a short introduction to the most important ones and their usage.
First we have a look at the basic functionality of calculating TL-moments and parameter and quantile estimates. Let assume we have a simple random data vector generated from a GEV distribution:
xvec <- rgev(100, loc = 10, scale = 5, shape = .2)
TL-moments are calculated by the function TLMoments with arguments leftrim, rightrim, and max.order (generating an object of class TLMoments):
TLMoments(xvec)
## $lambdas
## L1 L2 L3 L4
## 14.0173473 4.0593659 1.3221238 0.9849437
##
## $ratios
## T1 T2 T3 T4
## NA 0.2895959 0.3256971 0.2426349
TLMoments(xvec, leftrim = 0, rightrim = 1, max.order = 2)
## $lambdas
## L1 L2
## 9.957981 2.052932
##
## $ratios
## T1 T2
## NA 0.2061594
We can generate parameters estimates by putting a TLMoments-object to the function parameters and specifying argument distr:
tlm <- TLMoments(xvec)
parameters(tlm, distr = "gev")
## loc scale shape
## 10.1085022 4.5048954 0.2296688
tlm <- TLMoments(xvec, rightrim = 1)
parameters(tlm, distr = "gev")
## loc scale shape
## 10.1635352 4.5531879 0.1981091
This generates an object of class parameters, which can be transmitted to quantiles to calculate quantile estimations:
tlm <- TLMoments(xvec)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
## 0.9 0.99 0.999
## 23.38218 46.91199 86.33208
tlm <- TLMoments(xvec, rightrim = 1)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
## 0.9 0.99 0.999
## 23.07477 44.35414 77.48191
These three functions, TLMoments, parameters, and quantiles, provide the main functionality of the package. In the code above we used single data vectors only, but the same functions can be used for data matrices, lists, and data.frames as well. To demonstrate this, let's generate sample data of these four types:
xmat <- matrix(rgev(100), nc = 4)
xvec <- xmat[, 3]
xlist <- lapply(1L:ncol(xmat), function(i) xmat[, i])
xdat <- data.frame(station = rep(1:4, each = 25), hq = as.vector(xmat))
Note that the type of the dimensions lambdas and ratios returned by TLMoments matches the input type:
TLMoments(xvec, leftrim = 0, rightrim = 1)
## $lambdas
## L1 L2 L3 L4
## -0.118853990 0.345356673 0.001151761 0.056987284
##
## $ratios
## T1 T2 T3 T4
## NA -2.905722163 0.003334991 0.165009942
TLMoments(xmat, leftrim = 0, rightrim = 1)
## $lambdas
## [,1] [,2] [,3] [,4]
## L1 0.02344548 -0.23776608 -0.118853990 -0.11898376
## L2 0.30767794 0.42364590 0.345356673 0.45702513
## L3 0.03664748 -0.02546122 0.001151761 0.10543062
## L4 0.06705632 0.08328394 0.056987284 0.08181004
##
## $ratios
## [,1] [,2] [,3] [,4]
## T1 NA NA NA NA
## T2 13.1231242 -1.78177604 -2.905722163 -3.8410715
## T3 0.1191099 -0.06010024 0.003334991 0.2306889
## T4 0.2179432 0.19658857 0.165009942 0.1790056
TLMoments(xlist, leftrim = 0, rightrim = 1)
## $lambdas
## $lambdas[[1]]
## L1 L2 L3 L4
## 0.02344548 0.30767794 0.03664748 0.06705632
##
## $lambdas[[2]]
## L1 L2 L3 L4
## -0.23776608 0.42364590 -0.02546122 0.08328394
##
## $lambdas[[3]]
## L1 L2 L3 L4
## -0.118853990 0.345356673 0.001151761 0.056987284
##
## $lambdas[[4]]
## L1 L2 L3 L4
## -0.11898376 0.45702513 0.10543062 0.08181004
##
##
## $ratios
## $ratios[[1]]
## T1 T2 T3 T4
## NA 13.1231242 0.1191099 0.2179432
##
## $ratios[[2]]
## T1 T2 T3 T4
## NA -1.78177604 -0.06010024 0.19658857
##
## $ratios[[3]]
## T1 T2 T3 T4
## NA -2.905722163 0.003334991 0.165009942
##
## $ratios[[4]]
## T1 T2 T3 T4
## NA -3.8410715 0.2306889 0.1790056
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
## $lambdas
## station L1 L2 L3 L4
## 1 1 0.02344548 0.3076779 0.036647475 0.06705632
## 2 2 -0.23776608 0.4236459 -0.025461222 0.08328394
## 3 3 -0.11885399 0.3453567 0.001151761 0.05698728
## 4 4 -0.11898376 0.4570251 0.105430617 0.08181004
##
## $ratios
## station T2 T3 T4
## 1 1 13.123124 0.119109857 0.2179432
## 2 2 -1.781776 -0.060100243 0.1965886
## 3 3 -2.905722 0.003334991 0.1650099
## 4 4 -3.841072 0.230688882 0.1790056
This holds when parameter and quantile estimations are calculated:
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## loc scale shape
## -0.01397485 0.80481126 -0.04136686
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [,1] [,2] [,3] [,4]
## loc 0.04889176 -0.05425236 -0.01397485 -0.1670314
## scale 0.67814071 0.99798598 0.80481126 0.9185783
## shape 0.21866118 -0.19640922 -0.04136686 0.4447258
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [[1]]
## loc scale shape
## 0.04889176 0.67814071 0.21866118
##
## [[2]]
## loc scale shape
## -0.05425236 0.99798598 -0.19640922
##
## [[3]]
## loc scale shape
## -0.01397485 0.80481126 -0.04136686
##
## [[4]]
## loc scale shape
## -0.1670314 0.9185783 0.4447258
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## station loc scale shape
## 1 1 0.04889176 0.6781407 0.21866118
## 2 2 -0.05425236 0.9979860 -0.19640922
## 3 3 -0.01397485 0.8048113 -0.04136686
## 4 4 -0.16703142 0.9185783 0.44472579
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## 0.99 0.999
## 3.35734 4.82140
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [,1] [,2] [,3] [,4]
## 0.99 5.427518 2.968302 3.35734 13.74486
## 0.999 10.991346 3.718393 4.82140 42.34384
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [[1]]
## 0.99 0.999
## 5.427518 10.991346
##
## [[2]]
## 0.99 0.999
## 2.968302 3.718393
##
## [[3]]
## 0.99 0.999
## 3.35734 4.82140
##
## [[4]]
## 0.99 0.999
## 13.74486 42.34384
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## station 0.99 0.999
## 1 1 5.427518 10.991346
## 2 2 2.968302 3.718393
## 3 3 3.357340 4.821400
## 4 4 13.744859 42.343836
TLMoments offers functions (distributions, density, quantile, random number generation) for the generalized extreme value distribution (gev), Gumbel distribution (gum), generalized Pareto distribution (gpd), and three-parameter lognormal distribution (ln3) in the common p|d|q|r-syntax. The parameter (and quantile) estimation functionality works for all of them, but more complex functionality like estimation of the covariance matrix of parameter or quantile estimators only works for GEV by now.
The functions as.TLMoments and as.parameters can be used to construct TLMoments- or parameters-objects of theoretical values (not calculated from data). These objects can be used in the same way like before (to convert between TL-moments and their parameters or to calculate the corresponding quantiles):
(tlm <- as.TLMoments(c(14.1, 4.3, 1.32)))
## $lambdas
## L1 L2 L3
## 14.10 4.30 1.32
##
## $ratios
## T1 T2 T3
## NA 0.3049645 0.3069767
parameters(tlm, distr = "gev")
## loc scale shape
## 10.0134305 4.9448851 0.2034746
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
## 0.9 0.99 0.999
## 24.12668 47.67693 84.80024
(param <- as.parameters(loc = 10, scale = 5, shape = .2, distr = "gev"))
## loc scale shape
## 10.0 5.0 0.2
quantiles(param, c(.9, .99, .999))
## 0.9 0.99 0.999
## 24.21069 47.73413 84.51684
TLMoments(param)
## $lambdas
## L1 L2 L3 L4
## 14.1057429 4.3279754 1.3204343 0.9436158
##
## $ratios
## T1 T2 T3 T4
## NA 0.3068236 0.3050928 0.2180271
TLMoments(param, rightrim = 1)
## $lambdas
## L1 L2 L3 L4
## 9.7777681 2.2556564 0.2512127 0.2553529
##
## $ratios
## T1 T2 T3 T4
## NA 0.2306924 0.1113701 0.1132056
Note, that we can simply use the TLMoments-function to calculate TL-moments corresponding to a parameters-object.
Objects of type TLMoments, parameters, or quantiles (i.e. results from the functions of the same name) feature summary-functions, which give confidence intervals and an overview of the data.
tlm <- TLMoments(rgev(100), leftrim = 0, rightrim = 1)
summary(tlm)
## 1 data row(s) with n = 100.
## TL(0,1) calculated.
##
## Approximate 0.9% confidence interval of TL moments:
## LCL lambda_hat UCL
## L1 -0.120675775 0.033253218 0.18718221
## L2 0.353034660 0.397368875 0.44170309
## L3 -0.031864235 -0.004586798 0.02269064
## L4 0.005323102 0.024067309 0.04281152
## Approximate 0.9% confidence interval of TL moment ratios:
## LCL tau_hat UCL
## T2 -43.08154521 11.94978699 66.98111919
## T3 -0.08012055 -0.01154292 0.05703471
## T4 0.01167740 0.06056667 0.10945594
summary(tlm, ci.level = .95, select = 3:4)
## 1 data row(s) with n = 100.
## TL(0,1) calculated.
##
## Approximate 0.95% confidence interval of TL moments:
## LCL lambda_hat UCL
## L3 -0.037089869 -0.004586798 0.02791627
## L4 0.001732209 0.024067309 0.04640241
## Approximate 0.95% confidence interval of TL moment ratios:
## LCL tau_hat UCL
## T3 -0.021148618 0.06056667 0.1422820
## T4 0.002311506 0.06056667 0.1188218
summary(parameters(tlm, "gev"))
## 1 data row(s) with n = 100.
## TL(0,1) used to generate GEV parameters.
##
## Approximate 0.9% confidence interval of parameters:
## LCL param UCL
## loc -0.01082746 0.1658265 0.34248044
## scale 0.80458149 0.9296128 1.05464414
## shape -0.23910542 -0.0768813 0.08534282
summary(quantiles(parameters(tlm, "gev"), .99))
## 1 data row(s) with n = 100.
## TL(0,1) used to generate GEV parameters to calculate 0.99 quantile estimates.
##
## Approximate 0.9% confidence interval of quantiles:
## LCL quantile UCL
## 0.99 2.564796 3.767776 4.970755
At the moment, the summary functions does not work for data in lists or data.frames.
TLMoments is built to support the use in magrittr syntax. The nesting of functions can be written more readable as:
library(magrittr)
TLMoments(xvec, leftrim = 0, rightrim = 1) %>%
parameters("gev") %>%
quantiles(c(.99, .999))
## 0.99 0.999
## 3.35734 4.82140