L-Moment Algorithms in Python

## Project description

"""
This library was designed to use L-moments to predict optimal parameters
for a number of distributions. Distributions supported in this file are
listed below, with their distribution suffix:
*Exponential (EXP)
*Gamma (GAM)
*Generalised Extreme Value (GEV)
*Generalised Logistic (GLO)
*Generalised Normal (GNO)
*Generalised Pareto (GPA)
*Gumbel (GUM)
*Kappa (KAP)
*Normal (NOR)
*Pearson III (PE3)
*Wakeby (WAK)
*Weibull (WEI)

The primary function in this file is the samlmu(x,nmom) function, which takes
an input dataset x and input of the number of moments to produce the log
moments of that dataset.

For Instance, given a list "Data", if 5 l-moments are needed, the function
would be called by lmoments.samlmu(Data,5)

In this file contains four different functions for using each distribution.
Each function can be called by the prefix FUN with the suffix DIS.

*PEL: (x,nmom):
Parameter Estimates. This takes the L-Moments calculated by samlmu()
and predicts the parameter estimates for that function.

EXAMPLE: Find Wakeby distribution that best fits dataset DATA:

import lmoments
para = lmoments.pelwak(lmoments.samlmu(DATA,5))

*QUA: (f,para)
Quantile Estimates. This takes the parameter estimates for a
distribution, and a given Quantile value to calculate the quantile for the
given function.

EXAMPLE: Find the Upper Quantile (75%) of the Kappa distribution that
best fits dataset DATA:

import lmoments
para = lmoments.pelkap(lmoments.samlmu(DATA,5))
UQ = lmoments.quakap(0.75,para)

*LMR: (para,nmom):
L-Moment Ratios. This takes the parameter estimates for a distribution
and calculates nmom L-Moment ratios.

EXAMPLE: Find 4 lmoment ratios for the Gumbel distribution that
best fits dataset DATA:

import lmoments
para = lmoments.pelgum(lmoments.samlmu(DATA,5))
LMR = lmoments.lmrgum(para,4)

*CDF: (x,para):
Cumulative Distribution Function. This takes the parameter estimates
for a distribution and calculates the quantile for a given value x.

EXAMPLE: Find the quantile of the datapoint 6.4 for the Weibull
Distribution that best fits the dataset DATA:

import lmoments
para = lmoments.pelwei(lmoments.samlmu(DATA,5))
quantile = lmoments.cdfwei(6.4,para)

*PDF: (x,para):
Probability Distribution Function. This takes the parameter estimates
for a distribution and calculates the p value for a given value x.

EXAMPLE: Find the p-value of the datapoint 6.4 for the Weibull
Distribution that best fits the dataset DATA:

import lmoments
para = lmoments.pelwei(lmoments.samlmu(DATA,5))
quantile = lmoments.pdfwei(6.4,para)

*LMOM: (para):
L-Moment Estimation from Parameters. This function takes the input
parameters for a given distribution, and attempt to calculate the
L-Moments that would correspond to this distribution.

EXAMPLE: Estimate the L-Moments of the Weibull Distribution that has
parameters (2.5,1.5,0.5)

import lmoments
Lmoments = lmoments.lmomwei([2.5,1.5,0.5])

#RAND: (n,para)
Random Number Generator for a given function. This takes a curve fit
and returns a list of random numbers generated from that distribution

EXAMPLE: Generate 10 numbers from the weibull distribution that makes
up the dataset "data"

import lmoments
weibullfit = lmoments.pelwei(lmoments.samlmu(data))
randnums = lmoments.randwei(10,weibullfit)

*NlogL: (data,dist,peldist):
Calculates the Negative Log Likelihood for use in AIC/AICc/BIC calculations.
Provide data, and distribution to calculate NlogL. Can also provide curve
fitting parameters, but if they aren't provided, then the function will
generate them via pelxxx(samlmu(data)). To specify the distribution, use the
three letters typically assigned.

EXAMPLE: Calculate the Negative Log Likelihood of a Gamma distribution
fitted to Data.

import lmoments
NLL = lmoments.NlogL(data,"GAM")

EXAMPLE: Calculate the Negative Log Likelihood of a Gamma distribution
with parameters [2.5,1.0] when fitted to Data.

import lmoments
NLL = lmoments.NlogL(data,"GAM",[2.5,1.0])

*AIC: (data,dist,*distfit):
Calculate the Akaike Information Criterion (AIC) using the chosen dataset
and distribution

EXAMPLE: Calculate the Akaike Information Criterion for the weibull
distribution using the input dataset data:

import lmoments
Akaike = AIC(data,"WEI")

*BIC: (data,dist,*distfit):
Calculate the Bayesian Information Criterion (AIC) using the chosen dataset
and distribution

EXAMPLE: Calculate the Bayesian Information Criterion for the weibull
distribution using the input dataset data:

import lmoments
Akaike = AIC(data,"WEI")

This file contains a Python implimentation of the lmoments.f library created by
J. R. M. HOSKING.

The base Fortran code is copyright of the IBM Corperation, and the licensing
information is shown below:

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
IBM software disclaimer

LMOMENTS: Fortran routines for use with the method of L-moments
Permission to use, copy, modify and distribute this software for any purpose
and without fee is hereby granted, provided that this copyright and permission
notice appear on all copies of the software. The name of the IBM Corporation
may not be used in any advertising or publicity pertaining to the use of the
software. IBM makes no warranty or representations about the suitability of the
software for any purpose. It is provided "AS IS" without any express or implied
warranty, including the implied warranties of merchantability, fitness for a
particular purpose and non-infringement. IBM shall not be liable for any direct,
indirect, _special or consequential damages resulting from the loss of use,
data or projects, whether in an action of contract or tort, arising out of or
in connection with the use or performance of this software.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Additional code from the R library "lmomco" has been converted into Python.
This library was developed by WILLIAM ASQUITH, and was released under the GPL-3

The Python translation was conducted by:
Sam Gillespie
Numerical Analyst
C&R Consulting
Townsville Australia
September 2013

sam.gillespie@my.jcu.edu.au

Licensing for Python Translation:
####################################################

This program is free software: you can redistribute it and/or modify
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.Version 0.1.0:
####################################################

Initial Release

Version 0.1.1:
Corrected Small Errors and Typos

Version 0.2.0:
Added Reverse Lmoment Estimation Functions (LMOM)
Added Negative Log Likelhood Function (NlogL)
Included Unit Tests
Implimented better version of PELWAK function
Support for lists as x inputs for all CDF functions
Bugfixes

VERSION 0.2.1:
Support for lists as F inputs for all QUA functions
Added Random Number Generator (rand) for all functions
Split the main lmoments.py file into several files, as the
project is getting to large to maintain as one single file.

VERSION 0.2.2:
Improved samlmu function to support any value of nmom
Added Bayesian Information Criterion (BIC) function
Fixed import glitch that allowed users to import container files
General Bugfixes

VERSION 0.2.3
A bug was found that negative floats would be incorrectly handled in some cases.
"""