TLMoments

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.

Short Introduction

Calculation of empirical TL-moments, parameter and quantile estimates.

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

Support for different data types:

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

Calculations using theoretical TL-moments and parameters

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.

Magrittr-Syntax

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