gldpy-gpu

The Generalized Lambda Distribution for Python, with an optional PyTorch/CUDA backend and accurate tail probabilities.

This is a fork of gldpy by Aleksandra Alekseeva (MIT). It corrects 14 defects of the original and adds the GPU backend. The import name is gldpy_gpu, so it can be installed next to gldpy.

Install

pip install gldpy-gpu            # NumPy/SciPy only
pip install "gldpy-gpu[gpu]"     # adds PyTorch for the GPU backend
pip install "gldpy-gpu[plot]"    # adds matplotlib for plot_cdf, plot_pdf, plot_fitting

Pascal GPUs (GTX 10xx, compute capability 6.1) need a specific torch, because newer wheels dropped their kernels: pip install torch --index-url https://download.pytorch.org/whl/cu126. If the installed torch can't run on your GPU, gpu.GLD warns and uses torch on the CPU.

Usage

import torch
from gldpy_gpu import gpu

gld = gpu.GLD("FMKL")                 # CUDA when available, else CPU
p = torch.tensor([0.0, 1.0, 0.2, 0.3], device=gld.device)
x = gld.rand(p, size=10_000_000)      # sampling on the GPU
params = gld.fit_LMM(x)               # also fit_PM, fit_ML

The NumPy class has the same interface as upstream's, plus the tail methods: from gldpy_gpu import GLD. It also has mean, var, skewness, kurtosis, fit_MM, fit_MPS, fit_starship, fit_curve, GoF_tests and the plots, which the GPU class doesn't.

Without PyTorch, gpu.GLD warns and runs on NumPy: the same calls work, and return ndarrays. gpu.BACKEND is "torch" or "numpy". Arguments that only make sense for torch (device, dtype, n_grid, refine_steps, lr) are accepted and ignored, and fits use the slower SciPy optimizers.

Tail probabilities

Don't compute an upper tail as 1 - CDF_num(x), or as Q(1 - s): 1 - s rounds to 1 for small s.

Infinite tails keep a relative accuracy of about 1e-14 in float64 and 1e-6 in float32, down to the smallest representable number. Bounded tails run out sooner, for a reason no solver can fix: x becomes indistinguishable from the end of the support. Measurements are in docs/validation.md.

Precision

Every method takes dtype, and computes in that precision only:

gld.fit_LMM(data, dtype=torch.float64)    # or "float64"
gpu.GLD("FMKL", dtype=torch.float64)      # a default for this instance

The order is: the method's dtype, then the constructor's, then the widest float dtype among tensor or NumPy inputs, then float32 for plain Python numbers. Results have that dtype. Fits are as good in float32 as in float64 (median difference in KS distance about 2e-8, over 54 fits of known distributions). Use float64 for bounded tails below about 1e-6, or when the data have a large offset relative to their spread.

Speed

GTX 1070, FMKL, float32, median. CUDA loses below about 1e5 points because each operation pays a launch cost, and it wins by a growing margin above that:

docs/benchmarks.md explains the method and what acts on speed.

gldpy

gldpy is Python package that implements tools for using Generalized Lambda Distribution (GLD) of three different parameterization types.

GLD is flexible family of continuous probability distributions with wide variety of density shapes under one functional form. It specified by four parameters which determine location, scale and shape (skewness and kurtosis) of the distribution.

GLD is easily described in terms of quantile function which makes it easy to use in simulation studies.

It can approximate a lot of well-known distributions such as normal, uniform, exponential, Student's, gamma, some of beta distributions and many others.

GLD shapes can be symmetric or asymmetric and have different combination of finite and infinite tails, they include unimodal, U-shaped, J-shaped and monotone density functions. So it is particularly useful tool for data fitting applications.

For more information, see the documentation.

Usage examples

https://github.com/alexsandi/using_gldpy

References

1. Chalabi, Y., Scott, D.J., & Wuertz, D. 2012. Flexible distribution modeling with the generalized lambda distribution.

2. Cheng, R.C.H., & Amin, N.A.K. 1983. Estimating parameters in continuous univariate distributions with a shifted origin. Journal of the Royal Statistical Society: Series B (Methodological), 45(3), 394–403.

3. Freimer, M., Kollia, G., Mudholkar, G.S., & Lin, C.T. 1988. A study of the generalized Tukey lambda family. Communications in Statistics-Theory and Methods, 17, 3547–3567.

4. Karian, Z.A., Dudewicz, E.J. 2000. Fitting statistical distributions: the generalized lambda distribution and generalized bootstrap methods. Chapman and Hall/CRC.

5. Karvanen, J. and Nuutinen, A. 2008. Characterizing the generalized lambda distribution by L-moments. Computational Statistics & Data Analysis, 52(4):1971–1983.

6. King, R. A. R., and MacGillivray, H. L. 1999. "A Starship Estimation Method for the Generalized Lambda Distributions," Australian and New Zealand Journal of Statistics, 41, 353–374.

7. Ramberg, J.S., & Schmeiser, B.W. 1974. An approximate method for generating asymmetric random variables. Communications of the ACM, 17(2), 78–82

8. Ranneby, B. 1984. The maximum spacing method. an estimation method related to the maximum likelihood method. Scandinavian Journal of Statistics, 93–112.

9. Su, S. 2007. Numerical maximum log likelihood estimation for generalized lambda distributions. Computational Statistics & Data Analysis, 51(8), 3983–3998.

10. Van Staden, Paul J., & M.T. Loots. 2009. Method of L-moment estimation for generalized lambda distribution. Third Annual ASEARC Conference. Newcastle, Australia.