TLMoments is a set of functions which main functionality is the calculation of Trimmed L-moments and their parameter and quantile estimates. One of the main goals is to reduce computation time compared to existing implementations (like lmomco, Lmoments, Lmom), therefore the core functions are written in C++ (see vignette “comparison of computation time” for speed comparisons). 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 data vector:
xvec <- evd::rgev(100, loc = 10, scale = 5, shape = .2)
To calculate TL-moments we can use the function TLMoments with arguments leftrim, rightrim, and max.order (generating an object of class TLMoments):
TLMoments(xvec)
## $lambdas
## L1 L2 L3 L4
## 16.126145 5.718887 2.565133 2.203902
##
## $ratios
## T1 T2 T3 T4
## NA 0.3546345 0.4485372 0.3853725
TLMoments(xvec, leftrim = 0, rightrim = 1, max.order = 2)
## $lambdas
## L1 L2
## 10.407258 2.365315
##
## $ratios
## T1 T2
## NA 0.2272755
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.2584823 4.8724640 0.3929233
tlm <- TLMoments(xvec, rightrim = 1)
parameters(tlm, distr = "gev")
## loc scale shape
## 10.6773283 5.2712489 0.1815583
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
## 27.88089 73.44206 184.98014
tlm <- TLMoments(xvec, rightrim = 1)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
## 0.9 0.99 0.999
## 25.32957 48.57354 83.39360
These basic functions can not only be used for simple vectors of data, but for matrix-type data, list-type data, and data.frames as well. To demonstrate this, let's generate sample data of these four types:
xmat <- matrix(evd::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))
The type of lambdas and ratios returned by TLMoments matches the input type:
TLMoments(xvec, leftrim = 0, rightrim = 1)
## $lambdas
## L1 L2 L3 L4
## 0.29096370 0.33247496 0.06313653 0.02529157
##
## $ratios
## T1 T2 T3 T4
## NA 1.14266816 0.18989861 0.07607061
TLMoments(xmat, leftrim = 0, rightrim = 1)
## $lambdas
## [,1] [,2] [,3] [,4]
## L1 0.33880926 -0.12420371 0.29096370 0.211534716
## L2 0.40994525 0.53657150 0.33247496 0.391885938
## L3 -0.05142481 -0.07326315 0.06313653 0.071872452
## L4 0.06086067 0.05417065 0.02529157 -0.007922799
##
## $ratios
## [,1] [,2] [,3] [,4]
## T1 NA NA NA NA
## T2 1.2099588 -4.3200922 1.14266816 1.8525845
## T3 -0.1254431 -0.1365394 0.18989861 0.1834015
## T4 0.1484605 0.1009570 0.07607061 -0.0202171
TLMoments(xlist, leftrim = 0, rightrim = 1)
## $lambdas
## $lambdas[[1]]
## L1 L2 L3 L4
## 0.33880926 0.40994525 -0.05142481 0.06086067
##
## $lambdas[[2]]
## L1 L2 L3 L4
## -0.12420371 0.53657150 -0.07326315 0.05417065
##
## $lambdas[[3]]
## L1 L2 L3 L4
## 0.29096370 0.33247496 0.06313653 0.02529157
##
## $lambdas[[4]]
## L1 L2 L3 L4
## 0.211534716 0.391885938 0.071872452 -0.007922799
##
##
## $ratios
## $ratios[[1]]
## T1 T2 T3 T4
## NA 1.2099588 -0.1254431 0.1484605
##
## $ratios[[2]]
## T1 T2 T3 T4
## NA -4.3200922 -0.1365394 0.1009570
##
## $ratios[[3]]
## T1 T2 T3 T4
## NA 1.14266816 0.18989861 0.07607061
##
## $ratios[[4]]
## T1 T2 T3 T4
## NA 1.8525845 0.1834015 -0.0202171
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
## $lambdas
## station L1 L2 L3 L4
## 1 1 0.3388093 0.4099452 -0.05142481 0.060860673
## 2 2 -0.1242037 0.5365715 -0.07326315 0.054170648
## 3 3 0.2909637 0.3324750 0.06313653 0.025291574
## 4 4 0.2115347 0.3918859 0.07187245 -0.007922799
##
## $ratios
## station T2 T3 T4
## 1 1 1.209959 -0.1254431 0.14846049
## 2 2 -4.320092 -0.1365394 0.10095700
## 3 3 1.142668 0.1898986 0.07607061
## 4 4 1.852585 0.1834015 -0.02021710
This holds when parameter and quantile estimations are calculated:
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## loc scale shape
## 0.2777838 0.6939624 0.3646478
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [,1] [,2] [,3] [,4]
## loc 0.5725407 0.1942973 0.2777838 0.2002232
## scale 0.9604546 1.2536894 0.6939624 0.8225573
## shape -0.3665712 -0.3965968 0.3646478 0.3516276
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [[1]]
## loc scale shape
## 0.5725407 0.9604546 -0.3665712
##
## [[2]]
## loc scale shape
## 0.1942973 1.2536894 -0.3965968
##
## [[3]]
## loc scale shape
## 0.2777838 0.6939624 0.3646478
##
## [[4]]
## loc scale shape
## 0.2002232 0.8225573 0.3516276
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## station loc scale shape
## 1 1 0.5725407 0.9604546 -0.3665712
## 2 2 0.1942973 1.2536894 -0.3965968
## 3 3 0.2777838 0.6939624 0.3646478
## 4 4 0.2002232 0.8225573 0.3516276
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## 0.99 0.999
## 8.559723 21.997221
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [,1] [,2] [,3] [,4]
## 0.99 2.707383 2.845484 8.559723 9.652509
## 0.999 2.984347 3.151178 21.997221 24.400251
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [[1]]
## 0.99 0.999
## 2.707383 2.984347
##
## [[2]]
## 0.99 0.999
## 2.845484 3.151178
##
## [[3]]
## 0.99 0.999
## 8.559723 21.997221
##
## [[4]]
## 0.99 0.999
## 9.652509 24.400251
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## station 0.99 0.999
## 1 1 2.707383 2.984347
## 2 2 2.845484 3.151178
## 3 3 8.559723 21.997221
## 4 4 9.652509 24.400251
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 an quantiles-object.
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
## 8.559723 21.997221