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
## 15.219920 4.941218 1.652363 1.081890
##
## $ratios
## T1 T2 T3 T4
## NA 0.3246547 0.3344040 0.2189521
TLMoments(xvec, leftrim = 0, rightrim = 1, max.order = 2)
## $lambdas
## L1 L2
## 10.278702 2.466641
##
## $ratios
## T1 T2
## NA 0.2399759
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.4344285 5.3913349 0.2417284
tlm <- TLMoments(xvec, rightrim = 1)
parameters(tlm, distr = "gev")
## loc scale shape
## 10.3298814 5.3015073 0.2921439
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
## 26.55627 55.94187 106.57196
tlm <- TLMoments(xvec, rightrim = 1)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
## 0.9 0.99 0.999
## 27.20339 61.75799 128.69494
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.114550426 0.302534338 -0.009140531 0.014693476
##
## $ratios
## T1 T2 T3 T4
## NA -2.64105817 -0.03021320 0.04856796
TLMoments(xmat, leftrim = 0, rightrim = 1)
## $lambdas
## [,1] [,2] [,3] [,4]
## L1 -0.28719594 -0.39713828 -0.114550426 -0.02706065
## L2 0.51186550 0.32856443 0.302534338 0.59561193
## L3 0.03895049 -0.02397237 -0.009140531 0.05600763
## L4 0.03460784 0.04688214 0.014693476 0.01426871
##
## $ratios
## [,1] [,2] [,3] [,4]
## T1 NA NA NA NA
## T2 -1.78228667 -0.82733005 -2.64105817 -22.01026230
## T3 0.07609516 -0.07296095 -0.03021320 0.09403376
## T4 0.06761120 0.14268782 0.04856796 0.02395639
TLMoments(xlist, leftrim = 0, rightrim = 1)
## $lambdas
## $lambdas[[1]]
## L1 L2 L3 L4
## -0.28719594 0.51186550 0.03895049 0.03460784
##
## $lambdas[[2]]
## L1 L2 L3 L4
## -0.39713828 0.32856443 -0.02397237 0.04688214
##
## $lambdas[[3]]
## L1 L2 L3 L4
## -0.114550426 0.302534338 -0.009140531 0.014693476
##
## $lambdas[[4]]
## L1 L2 L3 L4
## -0.02706065 0.59561193 0.05600763 0.01426871
##
##
## $ratios
## $ratios[[1]]
## T1 T2 T3 T4
## NA -1.78228667 0.07609516 0.06761120
##
## $ratios[[2]]
## T1 T2 T3 T4
## NA -0.82733005 -0.07296095 0.14268782
##
## $ratios[[3]]
## T1 T2 T3 T4
## NA -2.64105817 -0.03021320 0.04856796
##
## $ratios[[4]]
## T1 T2 T3 T4
## NA -22.01026230 0.09403376 0.02395639
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
## $lambdas
## station L1 L2 L3 L4
## 1 1 -0.28719594 0.5118655 0.038950487 0.03460784
## 2 2 -0.39713828 0.3285644 -0.023972374 0.04688214
## 3 3 -0.11455043 0.3025343 -0.009140531 0.01469348
## 4 4 -0.02706065 0.5956119 0.056007631 0.01426871
##
## $ratios
## station T2 T3 T4
## 1 1 -1.7822867 0.07609516 0.06761120
## 2 2 -0.8273301 -0.07296095 0.14268782
## 3 3 -2.6410582 -0.03021320 0.04856796
## 4 4 -22.0102623 0.09403376 0.02395639
This holds when parameter and quantile estimations are calculated:
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## loc scale shape
## -0.002128798 0.710392201 -0.122173557
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [,1] [,2] [,3] [,4]
## loc -0.2042494 -0.2460226 -0.002128798 0.04949174
## scale 1.1576443 0.7742447 0.710392201 1.33357424
## shape 0.1252941 -0.2290299 -0.122173557 0.16467822
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## [[1]]
## loc scale shape
## -0.2042494 1.1576443 0.1252941
##
## [[2]]
## loc scale shape
## -0.2460226 0.7742447 -0.2290299
##
## [[3]]
## loc scale shape
## -0.002128798 0.710392201 -0.122173557
##
## [[4]]
## loc scale shape
## 0.04949174 1.33357424 0.16467822
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")
## station loc scale shape
## 1 1 -0.204249380 1.1576443 0.1252941
## 2 2 -0.246022619 0.7742447 -0.2290299
## 3 3 -0.002128798 0.7103922 -0.1221736
## 4 4 0.049491742 1.3335742 0.1646782
tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## 0.99 0.999
## 2.497817 3.311986
tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [,1] [,2] [,3] [,4]
## 0.99 6.99852 1.955756 2.497817 9.224853
## 0.999 12.50963 2.439579 3.311986 17.208323
tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## [[1]]
## 0.99 0.999
## 6.99852 12.50963
##
## [[2]]
## 0.99 0.999
## 1.955756 2.439579
##
## [[3]]
## 0.99 0.999
## 2.497817 3.311986
##
## [[4]]
## 0.99 0.999
## 9.224853 17.208323
tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))
## station 0.99 0.999
## 1 1 6.998520 12.509627
## 2 2 1.955756 2.439579
## 3 3 2.497817 3.311986
## 4 4 9.224853 17.208323
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
## 2.497817 3.311986