Short introduction to TLMoments

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.

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 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.175897  4.593334  1.491481  1.034456 
## 
## $ratios
##        T1        T2        T3        T4 
##        NA 0.3240242 0.3247056 0.2252081

TLMoments(xvec, leftrim = 0, rightrim = 1, max.order = 2)

## $lambdas
##       L1       L2 
## 9.582564 2.326389 
## 
## $ratios
##        T1        T2 
##        NA 0.2427732

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 
## 9.7558451 5.1072380 0.2282905

tlm <- TLMoments(xvec, rightrim = 1)
parameters(tlm, distr = "gev")

##       loc     scale     shape 
## 9.7255709 5.0861270 0.2437654

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 
## 24.77902 51.32549 95.65719

tlm <- TLMoments(xvec, rightrim = 1)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))

##       0.9      0.99     0.999 
##  24.97280  52.89529 101.23281

Support for different data types:

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.20084000  0.38902525 -0.07521962  0.03285787 
## 
## $ratios
##          T1          T2          T3          T4 
##          NA -1.93699087 -0.19335407  0.08446205

TLMoments(xmat, leftrim = 0, rightrim = 1)

## $lambdas
##            [,1]       [,2]        [,3]        [,4]
## L1 -0.127345075 0.07081477 -0.20084000 -0.16445982
## L2  0.414878772 0.50279046  0.38902525  0.54005116
## L3 -0.008674911 0.09075507 -0.07521962 -0.08261982
## L4  0.051442252 0.03593831  0.03285787  0.02176060
## 
## $ratios
##           [,1]      [,2]        [,3]       [,4]
## T1          NA        NA          NA         NA
## T2 -3.25790983 7.1000789 -1.93699087 -3.2837878
## T3 -0.02090951 0.1805028 -0.19335407 -0.1529852
## T4  0.12399345 0.0714777  0.08446205  0.0402936

TLMoments(xlist, leftrim = 0, rightrim = 1)

## $lambdas
## $lambdas[[1]]
##           L1           L2           L3           L4 
## -0.127345075  0.414878772 -0.008674911  0.051442252 
## 
## $lambdas[[2]]
##         L1         L2         L3         L4 
## 0.07081477 0.50279046 0.09075507 0.03593831 
## 
## $lambdas[[3]]
##          L1          L2          L3          L4 
## -0.20084000  0.38902525 -0.07521962  0.03285787 
## 
## $lambdas[[4]]
##          L1          L2          L3          L4 
## -0.16445982  0.54005116 -0.08261982  0.02176060 
## 
## 
## $ratios
## $ratios[[1]]
##          T1          T2          T3          T4 
##          NA -3.25790983 -0.02090951  0.12399345 
## 
## $ratios[[2]]
##        T1        T2        T3        T4 
##        NA 7.1000789 0.1805028 0.0714777 
## 
## $ratios[[3]]
##          T1          T2          T3          T4 
##          NA -1.93699087 -0.19335407  0.08446205 
## 
## $ratios[[4]]
##         T1         T2         T3         T4 
##         NA -3.2837878 -0.1529852  0.0402936

TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)

## $lambdas
##   station          L1        L2           L3         L4
## 1       1 -0.12734508 0.4148788 -0.008674911 0.05144225
## 2       2  0.07081477 0.5027905  0.090755070 0.03593831
## 3       3 -0.20084000 0.3890253 -0.075219616 0.03285787
## 4       4 -0.16445982 0.5400512 -0.082619820 0.02176060
## 
## $ratios
##   station        T2          T3         T4
## 1       1 -3.257910 -0.02090951 0.12399345
## 2       2  7.100079  0.18050277 0.07147770
## 3       3 -1.936991 -0.19335407 0.08446205
## 4       4 -3.283788 -0.15298517 0.04029360

This holds when parameter and quantile estimations are calculated:

tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")

##         loc       scale       shape 
##  0.07669342  0.88834601 -0.55582859

tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")

##              [,1]       [,2]        [,3]       [,4]
## loc    0.01895169 0.05873485  0.07669342  0.1748716
## scale  0.97254487 1.05793970  0.88834601  1.2554293
## shape -0.09950163 0.34579467 -0.55582859 -0.4417294

tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")

## [[1]]
##         loc       scale       shape 
##  0.01895169  0.97254487 -0.09950163 
## 
## [[2]]
##        loc      scale      shape 
## 0.05873485 1.05793970 0.34579467 
## 
## [[3]]
##         loc       scale       shape 
##  0.07669342  0.88834601 -0.55582859 
## 
## [[4]]
##        loc      scale      shape 
##  0.1748716  1.2554293 -0.4417294

tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
parameters(tlm, "gev")

##   station        loc     scale       shape
## 1       1 0.01895169 0.9725449 -0.09950163
## 2       2 0.05873485 1.0579397  0.34579467
## 3       3 0.07669342 0.8883460 -0.55582859
## 4       4 0.17487156 1.2554293 -0.44172941

tlm <- TLMoments(xvec, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))

##     0.99    0.999 
## 1.550995 1.640553

tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))

##           [,1]     [,2]     [,3]     [,4]
## 0.99  3.608775 12.01265 1.550995 2.644437
## 0.999 4.877290 30.33821 1.640553 2.882505

tlm <- TLMoments(xlist, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))

## [[1]]
##     0.99    0.999 
## 3.608775 4.877290 
## 
## [[2]]
##     0.99    0.999 
## 12.01265 30.33821 
## 
## [[3]]
##     0.99    0.999 
## 1.550995 1.640553 
## 
## [[4]]
##     0.99    0.999 
## 2.644437 2.882505

tlm <- TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
quantiles(parameters(tlm, "gev"), c(.99, .999))

##   station      0.99     0.999
## 1       1  3.608775  4.877290
## 2       2 12.012651 30.338209
## 3       3  1.550995  1.640553
## 4       4  2.644437  2.882505

Distributions

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.

TL-moment ratio diagram

Version 0.7.4 added functionality to plot TL-moment ratio diagrams of arbitrary trimming orders. Simply plot an object of TLMoments. Argument distr can be used to specify displayed theoretical distributions. Note that ggplot2 is used. Therefore changes or additions have to be made by adding ggplot2-specific functions.

tlm <- TLMoments(xmat, leftrim = 0, rightrim = 1)
plot(tlm)

## Registered S3 methods overwritten by 'ggplot2':
##   method         from 
##   [.quosures     rlang
##   c.quosures     rlang
##   print.quosures rlang

plot(tlm, distr = c("gev", "gpd", "exp", "gum"))

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 a parameters-object.

Summary functions

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.42230940 -0.24968601 -0.07706261
## L2  0.37551613  0.44454828  0.51358044
## L3 -0.01294081  0.02099133  0.05492347
## L4  0.05157234  0.07233439  0.09309644
## Approximate 0.9% confidence interval of TL moment ratios: 
##            LCL     tau_hat        UCL
## T2 -3.10753596 -1.78042929 -0.4533226
## T3 -0.02752871  0.04721946  0.1219676
## T4  0.11107689  0.16271436  0.2143518

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.01944131 0.02099133 0.06142397
## L4  0.04759488 0.07233439 0.09707390
## Approximate 0.95% confidence interval of TL moment ratios: 
##           LCL   tau_hat       UCL
## T3 0.07364642 0.1627144 0.2517823
## T4 0.10118451 0.1627144 0.2242442

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.3468062 -0.15311979 0.04056666
## scale  0.8738651  1.01958354 1.16530200
## shape -0.0989867  0.06050999 0.22000667

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 3.201525 5.254921 7.308317

At the moment, the summary functions does not work for data in lists or data.frames.