Short introduction to TLMoments

TLMoments is a set of functions whose main functionality is the calculation of trimmed L-moments (TL-moments) and resulting estimates of distribution parameters and quantiles.
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++ using Rcpp (see vignette “comparison of computation time” for speed comparisons). The package expands the combinations of trimmings that can be used to estimate distribution parameters in comparison to existing packages (which currently mainly support 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 how to use them.

library(TLMoments)
sessionInfo()
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04.1 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] lmom_3.3          Lmoments_1.3-2    lmomco_2.5.7      TLMoments_0.7.5.3
## [5] Rcpp_1.1.2        rmarkdown_2.32   
## 
## loaded via a namespace (and not attached):
##  [1] cli_3.6.6        knitr_1.52       rlang_1.3.0      xfun_0.62       
##  [5] jsonlite_2.0.0   buildtools_1.0.0 htmltools_0.5.9  maketools_1.3.2 
##  [9] sys_3.4.3        sass_0.4.10      evaluate_1.0.5   jquerylib_0.1.4 
## [13] MASS_7.3-66      fastmap_1.2.0    yaml_2.3.12      lifecycle_1.0.5 
## [17] evd_2.3-7.1      compiler_4.6.1   goftest_1.2-3    digest_0.6.39   
## [21] R6_2.6.1         bslib_0.12.0     tools_4.6.1      cachem_1.1.0

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 
## 13.2864864  3.7842576  1.2557534  0.8417911 
## 
## $ratios
##        T1        T2        T3        T4 
##        NA 0.2848200 0.3318361 0.2224455
TLMoments(xvec, leftrim = 0, rightrim = 1, max.order = 2)
## $lambdas
##       L1       L2 
## 9.502229 1.896378 
## 
## $ratios
##        T1        T2 
##        NA 0.1995719

We can calculate parameter 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.6276342 4.1497928 0.2381798
tlm <- TLMoments(xvec, rightrim = 1)
parameters(tlm, distr = "gev")
##       loc     scale     shape 
## 9.5701200 4.1026256 0.2742225

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 
## 21.98299 44.31957 82.48835
tlm <- TLMoments(xvec, rightrim = 1)
quantiles(parameters(tlm, distr = "gev"), c(.9, .99, .999))
##      0.9     0.99    0.999 
## 22.33999 47.43009 94.05046

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 90% confidence interval of TL moments: 
##            LCL  lambda_hat        UCL
## L1 -0.33208192 -0.14726561 0.03755069
## L2  0.41998392  0.48968740 0.55939089
## L3  0.01541856  0.04750748 0.07959639
## L4  0.02464931  0.04296192 0.06127454
## Approximate 90% confidence interval of TL moment ratios: 
##            LCL     tau_hat       UCL
## T2 -7.76752261 -3.32519859 1.1171254
## T3  0.03134475  0.09701592 0.1626871
## T4  0.04429841  0.08773336 0.1311683
summary(parameters(tlm, "gev"))
## 1 data row(s) with n = 100.
## TL(0,1) used to generate GEV parameters. 
## 
## Approximate 90% confidence interval of parameters: 
##              LCL      param       UCL
## loc   -0.2950685 -0.0870274 0.1210137
## scale  0.9276246  1.0944716 1.2613186
## shape  0.0106701  0.1711629 0.3316558
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 90% confidence interval of quantiles: 
##           LCL quantile      UCL
## 0.99 4.329656 7.570946 10.81224

The default confidence interval level is 90%, but it can be set using the argument ci.level. The argument select can be used to subset the results, which can be handy when analysing large data matrices.

summary(tlm, ci.level = .95, select = 3:4)
## 1 data row(s) with n = 100.
## TL(0,1) calculated. 
## 
## Approximate 95% confidence interval of TL moments: 
##            LCL lambda_hat        UCL
## L3 0.009271174 0.04750748 0.08574378
## L4 0.021141097 0.04296192 0.06478275
## Approximate 95% confidence interval of TL moment ratios: 
##            LCL    tau_hat       UCL
## T3 0.009481338 0.08773336 0.1659854
## T4 0.035977420 0.08773336 0.1394893
summary(parameters(tlm, "gev"), select = "shape")
## 1 data row(s) with n = 100.
## TL(0,1) used to generate GEV parameters. 
## 
## Approximate 90% confidence interval of parameters: 
##             LCL     param       UCL
## shape 0.0106701 0.1711629 0.3316558

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

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)) %>% 
  summary()
## 1 data row(s) with n = 100.
## TL(0,1) used to generate GEV parameters to calculate 0.99, 0.999 quantile estimates. 
## 
## Approximate 90% confidence interval of quantiles: 
##            LCL quantile       UCL
## 0.99  29.65010 47.43009  65.21007
## 0.999 31.55462 94.05046 156.54630

In the following this syntax is used for a clearer presentation.

Support for different data types

The 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.32804478  0.46134441  0.00312229  0.09081376 
## 
## $ratios
##           T1           T2           T3           T4 
##           NA -1.406345847  0.006767807  0.196845900
TLMoments(xmat, leftrim = 0, rightrim = 1)
## $lambdas
##           [,1]        [,2]        [,3]        [,4]
## L1 -0.22535128 -0.33251339 -0.32804478 -0.09462640
## L2  0.54767360  0.34289272  0.46134441  0.48237577
## L3  0.07447293  0.02133457  0.00312229  0.01064174
## L4  0.02155501  0.03628193  0.09081376  0.11665715
## 
## $ratios
##          [,1]        [,2]         [,3]        [,4]
## T1         NA          NA           NA          NA
## T2 -2.4303105 -1.03121476 -1.406345847 -5.09768709
## T3  0.1359805  0.06221936  0.006767807  0.02206109
## T4  0.0393574  0.10581132  0.196845900  0.24183874
TLMoments(xlist, leftrim = 0, rightrim = 1)
## $lambdas
## $lambdas[[1]]
##          L1          L2          L3          L4 
## -0.22535128  0.54767360  0.07447293  0.02155501 
## 
## $lambdas[[2]]
##          L1          L2          L3          L4 
## -0.33251339  0.34289272  0.02133457  0.03628193 
## 
## $lambdas[[3]]
##          L1          L2          L3          L4 
## -0.32804478  0.46134441  0.00312229  0.09081376 
## 
## $lambdas[[4]]
##          L1          L2          L3          L4 
## -0.09462640  0.48237577  0.01064174  0.11665715 
## 
## 
## $ratios
## $ratios[[1]]
##         T1         T2         T3         T4 
##         NA -2.4303105  0.1359805  0.0393574 
## 
## $ratios[[2]]
##          T1          T2          T3          T4 
##          NA -1.03121476  0.06221936  0.10581132 
## 
## $ratios[[3]]
##           T1           T2           T3           T4 
##           NA -1.406345847  0.006767807  0.196845900 
## 
## $ratios[[4]]
##          T1          T2          T3          T4 
##          NA -5.09768709  0.02206109  0.24183874
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1)
## $lambdas
##   station         L1        L2         L3         L4
## 1       1 -0.2253513 0.5476736 0.07447293 0.02155501
## 2       2 -0.3325134 0.3428927 0.02133457 0.03628193
## 3       3 -0.3280448 0.4613444 0.00312229 0.09081376
## 4       4 -0.0946264 0.4823758 0.01064174 0.11665715
## 
## $ratios
##   station        T2          T3        T4
## 1       1 -2.430311 0.135980507 0.0393574
## 2       2 -1.031215 0.062219361 0.1058113
## 3       3 -1.406346 0.006767807 0.1968459
## 4       4 -5.097687 0.022061093 0.2418387

This holds when parameter and quantile estimations are calculated:

TLMoments(xvec, leftrim = 0, rightrim = 1) %>% 
  parameters("gev")
##         loc       scale       shape 
## -0.19110992  1.07402544 -0.03324403
TLMoments(xmat, leftrim = 0, rightrim = 1) %>% 
  parameters("gev")
##             [,1]        [,2]        [,3]        [,4]
## loc   -0.1965523 -0.26791939 -0.19110992 0.033893609
## scale  1.1931216  0.78099578  1.07402544 1.117403419
## shape  0.2542957  0.09437988 -0.03324403 0.002622815
TLMoments(xlist, leftrim = 0, rightrim = 1) %>% 
  parameters("gev")
## [[1]]
##        loc      scale      shape 
## -0.1965523  1.1931216  0.2542957 
## 
## [[2]]
##         loc       scale       shape 
## -0.26791939  0.78099578  0.09437988 
## 
## [[3]]
##         loc       scale       shape 
## -0.19110992  1.07402544 -0.03324403 
## 
## [[4]]
##         loc       scale       shape 
## 0.033893609 1.117403419 0.002622815
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1) %>% 
  parameters("gev")
##   station         loc     scale        shape
## 1       1 -0.19655233 1.1931216  0.254295683
## 2       2 -0.26791939 0.7809958  0.094379884
## 3       3 -0.19110992 1.0740254 -0.033244027
## 4       4  0.03389361 1.1174034  0.002622815
TLMoments(xvec, leftrim = 0, rightrim = 1) %>% 
  parameters("gev") %>% 
  quantiles(c(.99, .999))
##     0.99    0.999 
## 4.390328 6.437330
TLMoments(xmat, leftrim = 0, rightrim = 1) %>% 
  parameters("gev") %>%
  quantiles(c(.99, .999))
##           [,1]     [,2]     [,3]     [,4]
## 0.99  10.22569 4.230948 4.390328 5.205250
## 0.999 22.28708 7.338443 6.437330 7.822421
TLMoments(xlist, leftrim = 0, rightrim = 1) %>% 
  parameters("gev") %>% 
  quantiles(c(.99, .999))
## [[1]]
##     0.99    0.999 
## 10.22569 22.28708 
## 
## [[2]]
##     0.99    0.999 
## 4.230948 7.338443 
## 
## [[3]]
##     0.99    0.999 
## 4.390328 6.437330 
## 
## [[4]]
##     0.99    0.999 
## 5.205250 7.822421
TLMoments(xdat, hq ~ station, leftrim = 0, rightrim = 1) %>% 
  parameters("gev") %>% 
  quantiles(c(.99, .999))
##   station      0.99     0.999
## 1       1 10.225690 22.287079
## 2       2  4.230948  7.338443
## 3       3  4.390328  6.437330
## 4       4  5.205250  7.822421

Distributions

TLMoments offers distribution functions (cdf, pdf, 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.

data <- matrix(rgev(25 * 10, shape = .2), ncol = 10)
plot(TLMoments(data))
## Warning: `aes_()` was deprecated in ggplot2 3.0.0.
## ℹ Please use tidy evaluation idioms with `aes()`
## ℹ The deprecated feature was likely used in the TLMoments package.
##   Please report the issue to the authors.
## This warning is displayed once per session.
## Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
## generated.

plot(TLMoments(data)) + ggplot2::theme_minimal()

plot(TLMoments(data, rightrim = 1), distr = c("gev", "gpd", "exp", "gum"))

Calculations using theoretical/given TL-moments and parameters

The functions as.TLMoments and as.parameters can be used to construct TLMoments- or parameters-objects of given 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.