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