ppidest 0.1.0__py3-none-any.whl

ppidest/__init__.py

@@ -0,0 +1,199 @@
+"""Plotting Position-Information Divergence (PPID) framework.
+
+Parameter estimation for univariate distributions based on discretizing
+the cumulative distribution function with plotting positions and
+minimizing information divergences against the empirical gaps.
+
+Public API
+----------
+- Distributions: :func:`normal_cdf`, :func:`normal_pdf`, :func:`gev_cdf`,
+  :func:`gev_pdf`, :func:`gev_quantile`, :func:`gev_return_level`,
+  :func:`weibull_cdf`, :func:`weibull_pdf`.
+- Plotting positions: :func:`plotting_positions`.
+- Divergences: :func:`kl_divergence`, :func:`kl_generalized_divergence`,
+  :func:`kl_symmetric_divergence`, :func:`jensen_shannon_divergence`,
+  :func:`beta_divergence`, :func:`power_divergence`,
+  :func:`renyi_divergence`.
+- Estimators: :class:`ML`, :class:`PPID`
+  and the convenience wrapper :func:`find_ppid_min`.
+
+The ``calc_*`` names from earlier releases are re-exported here as
+backward-compatible aliases (e.g. :data:`calc_gev_cdf`).
+
+Command line
+------------
+The ``ppidest`` console script fits a distribution to sample values given
+on the command line::
+
+    ppidest 0.38 0.51 1.44 2.14
+    ppidest 0.38 0.51 1.44 2.14 --distribution normal
+    ppidest 0.38 0.51 1.44 2.14 --plotting-position Weibull \\
+        --information-divergence "Jensen-Shannon"
+"""
+
+import argparse
+
+import numpy as np
+
+from .distributions import (
+    gev_cdf,
+    gev_pdf,
+    gev_quantile,
+    gev_return_level,
+    normal_cdf,
+    normal_pdf,
+    weibull_cdf,
+    weibull_pdf,
+    calc_gev_cdf,
+    calc_gev_pdf,
+    calc_gev_quantile,
+    calc_norm_cdf,
+    calc_norm_pdf,
+    calc_return_level_gev,
+    calc_weibull_cdf,
+    calc_weibull_pdf,
+)
+from .divergences import (
+    beta_divergence,
+    jensen_shannon_divergence,
+    kl_divergence,
+    kl_generalized_divergence,
+    kl_symmetric_divergence,
+    power_divergence,
+    renyi_divergence,
+)
+from .estimators import (
+    ML,
+    PPID,
+    DIVERGENCE_NAMES,
+    find_ppid_min,
+)
+from .plotting import (
+    PLOTTING_POSITIONS,
+    plotting_position_coefficients,
+    plotting_positions,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # distributions
+    "normal_cdf", "normal_pdf",
+    "gev_cdf", "gev_pdf", "gev_quantile", "gev_return_level",
+    "weibull_cdf", "weibull_pdf",
+    # plotting positions
+    "PLOTTING_POSITIONS", "plotting_position_coefficients",
+    "plotting_positions",
+    # divergences
+    "kl_divergence", "kl_generalized_divergence", "kl_symmetric_divergence",
+    "jensen_shannon_divergence", "beta_divergence", "power_divergence",
+    "renyi_divergence",
+    # estimators
+    "ML", "PPID", "find_ppid_min",
+    # legacy aliases
+    "calc_norm_cdf", "calc_norm_pdf",
+    "calc_gev_cdf", "calc_gev_pdf", "calc_gev_quantile",
+    "calc_return_level_gev", "calc_weibull_cdf", "calc_weibull_pdf",
+]
+
+
+#: Name of the parameter vector entry for each supported distribution.
+_PARAMETER_NAMES = {
+    "gev": ("loc", "scale", "shape"),
+    "normal": ("loc", "scale"),
+    "weibull": ("threshold", "scale", "shape"),
+}
+
+#: CDF callable for each supported distribution.
+_DISTRIBUTIONS = {
+    "gev": gev_cdf,
+    "normal": normal_cdf,
+    "weibull": weibull_cdf,
+}
+
+
+def _initial_parameters(name, xs):
+    """Return a sensible parameter guess derived from the sample."""
+    loc = float(np.mean(xs))
+    scale = float(np.std(xs))
+    if name == "normal":
+        return [loc, scale]
+    if name == "gev":
+        return [loc, scale, 0.0]
+    # three-parameter Weibull: threshold below the minimum observation,
+    # scale on the order of the observed range.
+    mn, mx = float(xs.min()), float(xs.max())
+    threshold = mn - 0.1 * (mx - mn) - 1e-9
+    return [threshold, (mx - mn) + 1e-9, 2.0]
+
+
+def main(argv=None):
+    """Console entry point: fit a distribution to command-line sample data.
+
+    The parameters are fitted with the :class:`PPID` estimator using the
+    plotting position and information divergence given by
+    ``--plotting-position`` (default ``Hazen``) and
+    ``--information-divergence`` (default ``Kullback-Leibler``).
+    """
+    parser = argparse.ArgumentParser(
+        prog="ppidest",
+        description="Fit a univariate distribution by minimizing an "
+                    "information divergence between plotting-position "
+                    "empirical gaps and the candidate CDF gaps.")
+    parser.add_argument(
+        "xs", type=float, nargs="+", metavar="x",
+        help="sample values to fit")
+    parser.add_argument(
+        "-d", "--distribution", choices=sorted(_DISTRIBUTIONS),
+        default="gev",
+        help="distribution family to fit (default: gev)")
+    parser.add_argument(
+        "-p", "--plotting-position", choices=sorted(PLOTTING_POSITIONS),
+        default="Hazen",
+        help="plotting-position scheme (default: Hazen)")
+    parser.add_argument(
+        "-i", "--information-divergence", choices=sorted(DIVERGENCE_NAMES),
+        default="Kullback-Leibler",
+        help="information divergence to minimize (default: "
+             "Kullback-Leibler)")
+    parser.add_argument(
+        "--pdiv", type=float, default=0.5, metavar="VALUE",
+        help="order/index parameter for the beta, power or Renyi "
+             "divergences (default: 0.5)")
+    parser.add_argument(
+        "--initial", type=float, nargs="+", metavar="PAR",
+        help="initial parameters, overriding the data-driven defaults "
+             "(e.g. '--initial 0 1 0.25' for GEV)")
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}")
+    args = parser.parse_args(argv)
+
+    xs = np.asarray(args.xs)
+    if xs.size < 2:
+        parser.error("at least two sample values are required")
+
+    name = args.distribution
+    cdf = _DISTRIBUTIONS[name]
+    par_names = _PARAMETER_NAMES[name]
+    if args.initial is not None:
+        if len(args.initial) != len(par_names):
+            parser.error(
+                f"--initial must provide {len(par_names)} values for "
+                f"{name} ({', '.join(par_names)})")
+        par_0 = list(args.initial)
+    else:
+        par_0 = _initial_parameters(name, xs)
+
+    res = PPID(xs, cdf, plotposition=args.plotting_position,
+               divergence=args.information_divergence).find_min_div(
+                   par_0, pdiv=args.pdiv)
+
+    header = ("distribution", "plotting position", "information divergence")
+    values = (name, args.plotting_position, args.information_divergence)
+    for key, value in zip(header, values):
+        print(f"{key:26s}: {value}")
+    for pname, pvalue in zip(par_names, res.x):
+        print(f"{pname:26s}: {pvalue:.6g}")
+    print(f"{'minimum divergence':26s}: {res.fun:.6g}")
+    print(f"{'converged':26s}: {res.success}")
+    return res

ppidest/distributions.py

@@ -0,0 +1,240 @@
+"""Probability distributions used by the estimation methods.
+
+Every distribution function in this module follows the same calling
+convention: the first argument is the evaluation point (a scalar or a
+NumPy array) and the second is the parameter vector ``par``.  Keeping the
+signature uniform lets estimators treat ``cdf`` and ``pdf`` callables as
+first-class objects.
+
+Parameters are supplied in plain tuples or lists so that they can be passed
+straight to an optimizer (e.g. ``scipy.optimize.minimize``).
+"""
+
+import numpy as np
+from scipy.special import ndtr
+
+SQRT_2PI = np.sqrt(2.0 * np.pi)
+
+
+################################################################################
+#   Normal distribution
+################################################################################
+
+
+def normal_cdf(x, par):
+    """Cumulative distribution function of the normal distribution.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(loc, scale)``.
+
+    Returns
+    -------
+    float or ndarray
+        ``Phi((x - loc) / scale)``.
+    """
+    return ndtr((x - par[0]) / par[1])
+
+
+def normal_pdf(x, par):
+    """Probability density function of the normal distribution.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(loc, scale)``.
+
+    Returns
+    -------
+    float or ndarray
+        Density at each evaluation point.
+    """
+    z = (x - par[0]) / par[1]
+    return np.exp(-0.5 * z ** 2) / (par[1] * SQRT_2PI)
+
+
+################################################################################
+#   Generalized extreme value (GEV) distribution
+################################################################################
+
+
+def gev_cdf(x, par):
+    """Cumulative distribution function of the GEV distribution.
+
+    The GEV distribution function is
+
+    .. math::
+
+        F(x) = \\exp\\left[-\\left(1 + \\xi \\frac{x - \\mu}{\\sigma}
+               \\right)^{-1/\\xi}\\right]
+
+    with the Gumbel limit :math:`F(x) = \\exp\\left[-\\exp(-y)\\right]`
+    taken when :math:`\\xi \\approx 0`.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(location, scale, shape)`` :math:`(\\mu, \\sigma, \\xi)`.
+        The shape parameter follows the convention in which
+        :math:`\\xi > 0` gives the Fréchet (heavy tail) family.
+
+    Returns
+    -------
+    float or ndarray
+        ``F(x)``.
+    """
+    y = (x - par[0]) / par[1]
+    xi = par[2]
+    if abs(xi) < 1e-10:
+        return np.exp(-np.exp(-y))
+    # During optimization the parameters may leave the support of the
+    # distribution; such evaluations legitimately yield NaN.
+    with np.errstate(invalid="ignore", over="ignore", divide="ignore"):
+        return np.exp(-(1.0 + xi * y) ** (-1 / xi))
+
+
+def gev_pdf(x, par):
+    """Probability density function of the GEV distribution.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(location, scale, shape)``.
+
+    Returns
+    -------
+    float or ndarray
+        Density at each evaluation point.
+    """
+    with np.errstate(invalid="ignore", over="ignore", divide="ignore"):
+        if abs(par[2]) < 1e-10:
+            t = np.exp(-(x - par[0]) / par[1])
+            return 1 / par[1] * t * np.exp(-t)
+        t = (1 + par[2] / par[1] * (x - par[0])) ** (-1 / par[2])
+        return 1 / par[1] * t ** (par[2] + 1) * np.exp(-t)
+
+
+def gev_quantile(ff, par):
+    """Quantile function (inverse CDF) of the GEV distribution.
+
+    Returns the value :math:`x` such that :math:`F(x) = ff`.
+
+    Parameters
+    ----------
+    ff : float or ndarray
+        Cumulative probabilities in :math:`(0, 1)`.
+    par : sequence of float
+        Parameters ``(location, scale, shape)``.
+
+    Returns
+    -------
+    float or ndarray
+        Quantile(s).
+    """
+    if abs(par[2]) < 1e-10:
+        return par[0] - par[1] * np.log(-np.log(ff))
+    return par[0] - par[1] / par[2] * (1 - (-np.log(ff)) ** (-par[2]))
+
+
+def gev_return_level(p, par):
+    """Return level of the GEV distribution for a given return period.
+
+    The return level :math:`z_p` associated with the return period
+    :math:`p` (given as multiples of the block length) satisfies
+    :math:`F(z_p) = 1 - 1 / p`.
+
+    Parameters
+    ----------
+    p : float
+        Return period, expressed as multiples of the block length.
+    par : sequence of float
+        Parameters ``(location, scale, shape)``.
+
+    Returns
+    -------
+    float
+        Return level.
+    """
+    ff = 1 - 1 / p
+    return gev_quantile(ff, par)
+
+
+################################################################################
+#   Three-parameter Weibull distribution
+################################################################################
+
+
+def weibull_cdf(x, par):
+    """Cumulative distribution function of the three-parameter Weibull
+    distribution with threshold :math:`\\gamma`.
+
+    .. math::
+
+        F(x) = 1 - \\exp\\left[-\\left(\\frac{x - \\gamma}{\\lambda}
+               \\right)^k\\right]
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(threshold, scale, shape)``
+        :math:`(\\gamma, \\lambda, k)`.
+
+    Returns
+    -------
+    float or ndarray
+        ``F(x)``.
+    """
+    return 1 - np.exp(-((x - par[0]) / par[1]) ** par[2])
+
+
+def weibull_pdf(x, par):
+    """Probability density function of the three-parameter Weibull
+    distribution.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Evaluation point(s).
+    par : sequence of float
+        Parameters ``(threshold, scale, shape)``.
+
+    Returns
+    -------
+    float or ndarray
+        Density at each evaluation point.
+    """
+    return par[2] / par[1] * ((x - par[0]) / par[1]) ** (par[2] - 1) \
+        * np.exp(-((x - par[0]) / par[1]) ** par[2])
+
+
+################################################################################
+#   Legacy aliases
+################################################################################
+
+#: Backward-compatible alias for :func:`normal_cdf`.
+calc_norm_cdf = normal_cdf
+#: Backward-compatible alias for :func:`normal_pdf`.
+calc_norm_pdf = normal_pdf
+#: Backward-compatible alias for :func:`gev_cdf`.
+calc_gev_cdf = gev_cdf
+#: Backward-compatible alias for :func:`gev_pdf`.
+calc_gev_pdf = gev_pdf
+#: Backward-compatible alias for :func:`gev_quantile`.
+calc_gev_quantile = gev_quantile
+#: Backward-compatible alias for :func:`gev_return_level`.
+calc_return_level_gev = gev_return_level
+#: Backward-compatible alias for :func:`weibull_cdf`.
+calc_weibull_cdf = weibull_cdf
+#: Backward-compatible alias for :func:`weibull_pdf`.
+calc_weibull_pdf = weibull_pdf

ppidest/divergences.py

@@ -0,0 +1,185 @@
+"""Information divergences between discrete probability vectors.
+
+In the PPID framework a candidate parametric distribution is compared
+with the empirical discretization of the data: ``das`` holds the empirical
+gap probabilities derived from plotting positions and ``ddas`` holds the
+corresponding model gaps :math:`F(x_j) - F(x_{j-1})` from the candidate
+CDF.  Each function below quantifies the agreement of the two probability
+vectors.
+
+All functions accept the two probability vectors as 1-D NumPy arrays of
+equal length and return a non-negative scalar divergence.
+"""
+
+import numpy as np
+
+
+
+def kl_divergence(das, ddas):
+    """Kullback-Leibler divergence ``sum(das * log(das / ddas))``.
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+
+    Returns
+    -------
+    float
+        Kullback-Leibler divergence.
+    """
+    return np.sum(das * np.log(das / ddas))
+
+
+def kl_generalized_divergence(das, ddas):
+    """Generalized Kullback-Leibler divergence
+    ``sum(das * log(das / ddas) - das + ddas)``.
+
+    Unlike the plain KL divergence this variant is symmetric in its
+    treatment of the two vectors (it vanishes when they coincide even
+    when the vectors are not normalized).
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+
+    Returns
+    -------
+    float
+        Generalized Kullback-Leibler divergence.
+    """
+    return np.sum(das * np.log(das / ddas) - das + ddas)
+
+
+def kl_symmetric_divergence(das, ddas):
+    """Symmetric Kullback-Leibler divergence
+    ``sum((ddas - das) * log(ddas / das))``.
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+
+    Returns
+    -------
+    float
+        Symmetric Kullback-Leibler divergence.
+    """
+    return np.sum((ddas - das) * np.log(ddas / das))
+
+
+def jensen_shannon_divergence(das, ddas):
+    """Jensen-Shannon divergence based on the midpoint mixture
+    ``mas = 0.5 * (das + ddas)``.
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+
+    Returns
+    -------
+    float
+        Jensen-Shannon divergence.
+    """
+    mas = 0.5 * (das + ddas)
+    return 0.5 * np.sum(
+        das * np.log(das / mas) + ddas * np.log(ddas / mas))
+
+
+def beta_divergence(das, ddas, beta):
+    """Beta (Cichocki) divergence of order ``beta`` (with ``beta != 0, 1``).
+
+    .. math::
+
+        D_\\beta(d \\,||\\, \\hat d)
+            = \\sum_j \\left[
+                  \\frac{d_j (d_j^{\\beta - 1} - \\hat d_j^{\\beta - 1})}
+                       {\\beta - 1}
+                  - \\frac{d_j^{\\beta} - \\hat d_j^{\\beta}}{\\beta}
+              \\right]
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+    beta : float
+        Order parameter of the divergence.  The special cases
+        ``beta -> 1`` (Kullback-Leibler) and ``beta -> 2`` (Euclidean)
+        are approached only in the limit.
+
+    Returns
+    -------
+    float
+        Beta divergence.
+    """
+    aa = das * (das ** (beta - 1) - ddas ** (beta - 1)) / (beta - 1)
+    bb = (das ** beta - ddas ** beta) / beta
+    # NaN from out-of-support model gaps is expected while optimizing.
+    with np.errstate(invalid="ignore"):
+        return aa.sum() - bb.sum()
+
+
+def power_divergence(das, ddas, lmbd):
+    """Power divergence of index ``lmbd``.
+
+    .. math::
+
+        D_\\lambda(d \\,||\\, \\hat d)
+            = \\frac{1}{\\lambda (\\lambda + 1)}
+              \\sum_j d_j \\left[
+                  \\left(\\frac{d_j}{\\hat d_j}\\right)^{\\lambda} - 1
+              \\right]
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+    lmbd : float
+        Index of the divergence (``lmbd != 0, -1``).
+
+    Returns
+    -------
+    float
+        Power divergence.
+    """
+    return 1 / (lmbd * (lmbd + 1)) * np.sum(das * ((das / ddas) ** lmbd - 1))
+
+
+def renyi_divergence(das, ddas, alpha):
+    """Rényi divergence of order ``alpha``.
+
+    .. math::
+
+        D_\\alpha(d \\,||\\, \\hat d)
+            = \\frac{1}{\\alpha - 1}
+              \\log \\sum_j d_j^{\\alpha} \\hat d_j^{1 - \\alpha}
+
+    Parameters
+    ----------
+    das : ndarray
+        Empirical gap probabilities.
+    ddas : ndarray
+        Model gap probabilities.
+    alpha : float
+        Order of the divergence (``alpha != 1``).
+
+    Returns
+    -------
+    float
+        Rényi divergence.
+    """
+    return 1 / (alpha - 1) * np.log(np.sum(das ** alpha * ddas ** (1 - alpha)))

ppidest/estimators.py

@@ -0,0 +1,395 @@
+"""Parameter estimators based on CDF discretization.
+
+This module collects the estimators of the Plotting Position-Information
+Divergence (PPID) framework:
+
+- :class:`ML`      -- maximum likelihood (uses the PDF directly);
+- :class:`PPID`    -- PPID estimators minimizing one of several
+  information divergences between the empirical gaps (plotting positions)
+  and the model gaps;
+
+All estimators expose a ``find_*`` method that wraps
+``scipy.optimize.minimize`` and mirror its keyword arguments.
+"""
+
+import numpy as np
+import scipy.optimize
+
+from .divergences import (
+    beta_divergence,
+    jensen_shannon_divergence,
+    kl_divergence,
+    kl_generalized_divergence,
+    kl_symmetric_divergence,
+    power_divergence,
+    renyi_divergence,
+)
+from .plotting import (
+    _plotting_positions_from_order_stats,
+    plotting_position_coefficients,
+)
+
+
+#: Divergences that require an extra scalar parameter (``beta``, ``power``,
+#: ``Renyi``): mapping divergence name to the ``PPID`` objective method.
+_PARAMETRIC_DIVERGENCES = {
+    "beta": "beta_div",
+    "power": "power_div",
+    "Renyi": "renyi_div",
+}
+
+#: Divergences used directly on the gap vectors: mapping divergence name
+#: to the ``PPID`` objective method.
+_NONPARAMETRIC_DIVERGENCES = {
+    "Kullback-Leibler": "kld",
+    "KL_generalized": "kld_generalized",
+    "KL_symmetric": "kld_symmetric",
+    "Jensen-Shannon": "jensen_shannon_div",
+}
+
+#: Supported information divergences for :class:`PPID`.
+DIVERGENCE_NAMES = tuple(
+    _NONPARAMETRIC_DIVERGENCES) + tuple(_PARAMETRIC_DIVERGENCES)
+
+
+################################################################################
+#   Shared helpers
+################################################################################
+
+
+def _minimize(fun, x0, method="Nelder-Mead", jac=None, hess=None, hessp=None,
+              bounds=None, constraints=(), tol=None, callback=None,
+              options=None, args=()):
+    """Thin wrapper around ``scipy.optimize.minimize`` sharing the estimator
+    keyword interface."""
+    x0 = np.asarray(x0, dtype=float).ravel()
+    return scipy.optimize.minimize(
+        fun, x0, args=args, method=method, jac=jac, hess=hess, hessp=hessp,
+        bounds=bounds, constraints=constraints, tol=tol,
+        callback=callback, options=options)
+
+
+def _cdf_gaps(cdf, uniques, par, *args):
+    """Return the model gap probabilities on the augmented support
+    ``[0, uniques, 1]``.  Extra ``args`` are forwarded to ``cdf``."""
+    ffs = np.concatenate([np.array([0.0]), cdf(uniques, par, *args),
+                          np.array([1.0])])
+    return np.diff(ffs)
+
+
+################################################################################
+#   Maximum likelihood
+################################################################################
+
+
+class ML:
+    """Maximum-likelihood estimator based on a parametric PDF."""
+
+    def __init__(self, xs, pdf):
+        """Initialize the estimator.
+
+        Parameters
+        ----------
+        xs : array_like
+            Observed values.
+        pdf : callable
+            ``pdf(x, par)`` returning the density at ``x`` for the
+            parameter vector ``par``.
+        """
+        self.xs = np.sort(np.asarray(xs))
+        self.pdf = pdf
+
+    def nll(self, par):
+        """Negative log-likelihood at ``par``.
+
+        Parameters
+        ----------
+        par : sequence of float
+            Candidate parameters.
+
+        Returns
+        -------
+        float
+            ``- sum(log(pdf(x_i, par) + 1e-10))``.
+        """
+        return -np.sum(np.log(self.pdf(self.xs, par) + 1e-10))
+
+    def loglikelihood(self, par):
+        """Elementwise log-density of each observation at ``par``.
+
+        Parameters
+        ----------
+        par : sequence of float
+            Candidate parameters.
+
+        Returns
+        -------
+        ndarray
+            Log-density evaluated at every sample point.
+        """
+        return np.log(self.pdf(self.xs, par))
+
+    def find_mle(self, par_0, method="Nelder-Mead", jac=None, hess=None,
+                 hessp=None, bounds=None, constraints=(), tol=None,
+                 callback=None, options=None):
+        """Locate the maximum-likelihood estimate.
+
+        Parameters
+        ----------
+        par_0 : sequence of float
+            Initial parameter guess.
+        method, jac, hess, hessp, bounds, constraints, tol, callback, options
+            Forwarded to :func:`scipy.optimize.minimize`.
+
+        Returns
+        -------
+        OptimizeResult
+            Result of the minimization.
+        """
+        return _minimize(
+            self.nll, par_0, method=method, jac=jac, hess=hess, hessp=hessp,
+            bounds=bounds, constraints=constraints, tol=tol,
+            callback=callback, options=options)
+
+
+################################################################################
+#   PPID estimators
+################################################################################
+
+
+class PPID:
+    """Plotting Position-Information Divergence estimator.
+
+    The empirical cumulative distribution is discretized by plotting
+    positions (see :mod:`ppidest.plotting`) and a parametric CDF is fitted
+    by minimizing an information divergence between the empirical gaps and
+    the model gaps.
+    """
+
+    #: Parametric divergences (name to objective method).
+    _PARAMETRIC_DIVERGENCES = _PARAMETRIC_DIVERGENCES
+    #: Non-parametric divergences (name to objective method).
+    _NONPARAMETRIC_DIVERGENCES = _NONPARAMETRIC_DIVERGENCES
+
+    def __init__(self, xs, cdf, plotposition="Hazen",
+                 divergence="Kullback-Leibler"):
+        """Initialize the estimator.
+
+        Parameters
+        ----------
+        xs : array_like
+            Observed values.
+        cdf : callable
+            ``cdf(x, par)`` returning the CDF at ``x`` for the parameter
+            vector ``par``.
+        plotposition : str, optional
+            Plotting-position scheme; see :mod:`ppidest.plotting`.
+            Defaults to ``"Hazen"``.
+        divergence : str, optional
+            Information divergence minimized by :meth:`find_min_div`.
+            Defaults to ``"Kullback-Leibler"``.
+        """
+        self.xs = np.sort(np.asarray(xs))
+        self.cdf = cdf
+        self.uniques, self.idxs, self.counts = np.unique(
+            self.xs, return_index=True, return_counts=True)
+        self.n_xs = self.xs.size
+        self.n_uniques = self.counts.size
+        self.plotposition = plotposition
+        self.divergence = divergence
+
+    @property
+    def divergence(self):
+        """Information divergence minimized by :meth:`find_min_div`.
+
+        Assigning a new divergence validates the name against the
+        supported set.
+        """
+        return self._divergence
+
+    @divergence.setter
+    def divergence(self, name):
+        self._validate_divergence(name)
+        self._divergence = name
+
+    def _validate_divergence(self, name):
+        if (name not in self._NONPARAMETRIC_DIVERGENCES
+                and name not in self._PARAMETRIC_DIVERGENCES):
+            raise ValueError(
+                f"Unknown divergence {name!r}. "
+                f"Choose from: {sorted(DIVERGENCE_NAMES)}")
+
+    def set_divergence(self, divergence):
+        """Switch the divergence minimized by :meth:`find_min_div`."""
+        self.divergence = divergence
+
+    @property
+    def plotposition(self):
+        """Plotting-position scheme in use.
+
+        Assigning a new scheme recomputes :attr:`p_ast_s` and :attr:`das`
+        from the stored sample.
+        """
+        return self._plotposition
+
+    @plotposition.setter
+    def plotposition(self, name):
+        plotting_position_coefficients(name)
+        self._plotposition = name
+        self.p_ast_s, self.das = _plotting_positions_from_order_stats(
+            self.uniques, self.idxs, self.counts, self.n_xs, name)
+
+    @property
+    def plottingposition(self):
+        """Alias of :attr:`plotposition`."""
+        return self.plotposition
+
+    @plottingposition.setter
+    def plottingposition(self, name):
+        self.plotposition = name
+
+    def set_plotting_positions(self, plotposition):
+        """Switch the plotting-position scheme, recomputing the empirical
+        gaps from the stored sample."""
+        self.plotposition = plotposition
+
+    def get_plotting_positions(self):
+        """Return the empirical gaps of the current plotting-position scheme.
+
+        Returns
+        -------
+        p_ast_s : ndarray
+            Cumulative plotting probabilities (with boundary points).
+        d_ast_s : ndarray
+            Empirical gap probabilities.
+        """
+        return self.p_ast_s, self.das
+
+    def calc_dd_ast_s(self, par, *args):
+        """Model gap probabilities for the candidate parameters.
+
+        Parameters
+        ----------
+        par : sequence of float
+            Candidate parameters.
+        args : tuple, optional
+            Extra positional arguments forwarded to the CDF callable.
+
+        Returns
+        -------
+        ndarray
+            Gaps of ``[0, cdf(uniques, par, *args), 1]``.
+        """
+        return _cdf_gaps(self.cdf, self.uniques, par, *args)
+
+    def beta_div(self, par, beta, *args):
+        """Beta divergence between the empirical and model gaps."""
+        return beta_divergence(self.das, self.calc_dd_ast_s(par, *args), beta)
+
+    def power_div(self, par, lmbd, *args):
+        """Power divergence between the empirical and model gaps."""
+        return power_divergence(self.das, self.calc_dd_ast_s(par, *args), lmbd)
+
+    def renyi_div(self, par, alpha, *args):
+        """Rényi divergence between the empirical and model gaps."""
+        return renyi_divergence(self.das, self.calc_dd_ast_s(par, *args), alpha)
+
+    def kld(self, par, *args):
+        """Kullback-Leibler divergence between the empirical and model gaps."""
+        return kl_divergence(self.das, self.calc_dd_ast_s(par, *args))
+
+    def kld_generalized(self, par, *args):
+        """Generalized KL divergence between the empirical and model gaps."""
+        return kl_generalized_divergence(self.das, self.calc_dd_ast_s(par, *args))
+
+    def kld_symmetric(self, par, *args):
+        """Symmetric KL divergence between the empirical and model gaps."""
+        return kl_symmetric_divergence(self.das, self.calc_dd_ast_s(par, *args))
+
+    def jensen_shannon_div(self, par, *args):
+        """Jensen-Shannon divergence between the empirical and model gaps."""
+        return jensen_shannon_divergence(self.das, self.calc_dd_ast_s(par, *args))
+
+    def find_min_div(self, par, divergence=None, pdiv=0.5, args=(),
+                     method="Nelder-Mead", jac=None, hess=None, hessp=None,
+                     bounds=None, constraints=(), tol=None, callback=None,
+                     options=None):
+        """Minimize the chosen information divergence.
+
+        Parameters
+        ----------
+        par : sequence of float
+            Initial parameter guess.
+        divergence : str, optional
+            One of ``"Kullback-Leibler"``, ``"KL_generalized"``,
+            ``"KL_symmetric"``, ``"Jensen-Shannon"``, ``"beta"``,
+            ``"power"``, ``"Renyi"``.  Defaults to the estimator's
+            ``divergence`` (set at construction or via
+            :meth:`set_divergence`).
+        pdiv : float, optional
+            Order/index parameter used by the parametric divergences
+            (``beta``, ``power``, ``Renyi``).  Defaults to ``0.5``.
+        args : tuple, optional
+            Extra positional arguments forwarded to the CDF callable
+            (appended after ``pdiv`` for the parametric divergences).
+        method, jac, hess, hessp, bounds, constraints, tol, callback, options
+            Forwarded to :func:`scipy.optimize.minimize`.
+
+        Returns
+        -------
+        OptimizeResult
+            Result of the minimization.
+
+        Raises
+        ------
+        ValueError
+            If ``divergence`` is not supported.
+        """
+        if divergence is None:
+            divergence = self.divergence
+        if divergence in self._PARAMETRIC_DIVERGENCES:
+            func = getattr(self, self._PARAMETRIC_DIVERGENCES[divergence])
+            opt_args = (pdiv,) + tuple(args)
+        elif divergence in self._NONPARAMETRIC_DIVERGENCES:
+            func = getattr(
+                self, self._NONPARAMETRIC_DIVERGENCES[divergence])
+            opt_args = tuple(args)
+        else:
+            raise ValueError(
+                f"Unknown divergence {divergence!r}. "
+                f"Choose from: {sorted(DIVERGENCE_NAMES)}")
+        return _minimize(
+            func, par, args=opt_args, method=method, jac=jac, hess=hess,
+            hessp=hessp, bounds=bounds, constraints=constraints, tol=tol,
+            callback=callback, options=options)
+
+
+def find_ppid_min(xs, cdf, par, plotposition="Hazen",
+                  divergence="Kullback-Leibler"):
+    """Convenience wrapper around :class:`PPID`.
+
+    Builds a :class:`PPID` estimator for ``(xs, cdf)``, fits it with the
+    requested divergence and returns the raw minimization result.
+
+    Parameters
+    ----------
+    xs : array_like
+        Observed values.
+    cdf : callable
+        ``cdf(x, par)`` returning the CDF at ``x`` for the parameter
+        vector ``par``.
+    par : sequence of float
+        Initial parameter guess.
+    plotposition : str, optional
+        Plotting-position scheme.  Defaults to ``"Hazen"``.
+    divergence : str, optional
+        Information divergence to minimize.  Defaults to
+        ``"Kullback-Leibler"``.
+
+    Returns
+    -------
+    OptimizeResult
+        Result of the minimization.
+    """
+    inst = PPID(xs, cdf, plotposition=plotposition, divergence=divergence)
+    return inst.find_min_div(par)

ppidest/plotting.py

@@ -0,0 +1,106 @@
+"""Plotting positions used to discretize the empirical CDF.
+
+Plotting positions assign a plotting probability :math:`p_{(i)}` to the
+i-th order statistic.  The PPID framework converts these into a discrete
+probability vector (the "empirical gaps") by aggregating the positions
+shared by tied observations and augmenting the support with the boundary
+bin at :math:`0` and :math:`1`.
+"""
+
+import numpy as np
+
+#: Registry of plotting-position coefficients ``(alpha, beta)`` such that
+#: ``p_i = (i - alpha) / (n + 1 - alpha - beta)``.
+PLOTTING_POSITIONS = {
+    "Weibull": (0.0, 0.0),       # i / (n + 1); unbiased for the uniform CDF
+    "median": (0.3, 0.3),        # (i - 0.3) / (n + 0.4); estimates the median
+    "Gringorten": (0.44, 0.44),  # (i - 0.44) / (n + 0.12); optimal for Gumbel
+    "Hazen": (0.5, 0.5),         # (i - 0.5) / n; piecewise linear approximation
+}
+
+
+def plotting_position_coefficients(name):
+    """Return the ``(alpha, beta)`` coefficients of a named plotting position.
+
+    Parameters
+    ----------
+    name : str
+        One of ``"Weibull"``, ``"median"``, ``"Gringorten"``, ``"Hazen"``.
+
+    Returns
+    -------
+    tuple of float
+        ``(alpha, beta)`` coefficients.
+
+    Raises
+    ------
+    ValueError
+        If ``name`` is not a registered plotting position.
+    """
+    if name not in PLOTTING_POSITIONS:
+        raise ValueError(
+            f"Unknown plotting position {name!r}. "
+            f"Choose from: {list(PLOTTING_POSITIONS)}"
+        )
+    return PLOTTING_POSITIONS[name]
+
+
+def plotting_positions(xs, name="Hazen"):
+    """Discretize a sample into empirical gap probabilities.
+
+    Each gap :math:`d^*_j` is the aggregated plotting probability of a
+    unique value, so the cumulative vector :math:`p^*_s` has mass
+    ``[0, p1, ..., pk, 1]`` and the gaps sum to one.
+
+    Parameters
+    ----------
+    xs : array_like
+        Observed values (not necessarily sorted).
+    name : str, optional
+        Plotting-position scheme.  Defaults to ``"Hazen"``.
+
+    Returns
+    -------
+    p_ast_s : ndarray of shape (k + 2,)
+        Cumulative plotting probabilities including the boundary points
+        ``0`` and ``1``.
+    d_ast_s : ndarray of shape (k + 1,)
+        Empirical gap probabilities, ``diff(p_ast_s)``.
+    """
+    xs = np.sort(np.asarray(xs))
+    uniques, idxs, counts = np.unique(xs, return_index=True, return_counts=True)
+    return _plotting_positions_from_order_stats(
+        uniques, idxs, counts, xs.size, name)
+
+
+def _plotting_positions_from_order_stats(uniques, idxs, counts, n_xs, name):
+    """Aggregate plotting positions from already-computed order statistics.
+
+    Parameters
+    ----------
+    uniques : ndarray
+        Sorted unique values.
+    idxs : ndarray
+        Indices of the first occurrence of each unique value in the
+        sorted sample.
+    counts : ndarray
+        Number of occurrences of each unique value.
+    n_xs : int
+        Sample size.
+    name : str
+        Plotting-position scheme.
+
+    Returns
+    -------
+    p_ast_s, d_ast_s : ndarray
+        Same shapes and semantics as :func:`plotting_positions`.
+    """
+    alpha, beta = plotting_position_coefficients(name)
+    n_e = n_xs + 1 - alpha - beta
+    ps = (np.arange(1, n_xs + 1) - alpha) / n_e
+    # cum_sum[i:j] == ps[i:j].sum() (prefix sum with a leading zero).
+    cum_sum = np.cumsum(np.insert(ps, 0, 0))
+    pre_p_ast = (cum_sum[idxs + counts] - cum_sum[idxs]) / counts
+    p_ast_s = np.concatenate([np.array([0.0]), pre_p_ast, np.array([1.0])])
+    d_ast_s = np.diff(p_ast_s)
+    return p_ast_s, d_ast_s

ppidest-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: ppidest
+Version: 0.1.0
+Summary: Plotting Position-Information Divergence framework for parameter estimation of univariate distributions
+Keywords: statistics,parameter-estimation,information-divergence,plotting-positions,extremes
+Author: Takuya Kawanishi
+Author-email: Takuya Kawanishi <takuya@exanalytics.sakura.ne.jp>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: scipy>=1.18.1
+Requires-Python: >=3.13
+Project-URL: Repository, https://codeberg.org/takuya_kawanishi/ppidest
+Project-URL: Homepage, https://codeberg.org/takuya_kawanishi/ppidest
+Description-Content-Type: text/markdown
+
+# ppidest
+
+**Plotting Position — Information Divergence** framework for parameter
+estimation of univariate distributions.
+
+The empirical cumulative distribution function of a sample is discretized
+using *plotting positions*, and a parametric distribution is fitted by
+minimizing an *information divergence* between the empirical gaps and the
+gaps implied by the candidate CDF.
+
+## Installation
+
+Requires Python ≥ 3.13.
+
+```bash
+uv sync          # create the environment and install the package
+uv run python -m unittest discover -s tests   # run the test suite
+```
+
+Dependencies: `numpy`, `scipy`.  The package is also installable from a
+source checkout with `pip install .` or `uv pip install .`, and the
+distributions on PyPI ship a `ppidest` console script (see
+[Command line](#command-line)).
+
+## Quick start
+
+Fit a GEV model to a small sample using the default (Kullback-Leibler)
+divergence:
+
+```python
+import numpy as np
+import ppidest
+
+xs = np.array([0.38, 0.51, 1.44, 2.14])
+
+# Plotting Position – Information Divergence estimator
+res = ppidest.find_ppid_min(xs, ppidest.gev_cdf, [0.0, 1.0, 0.25])
+print(res.x)   # fitted (loc, scale, shape)   -> [0.5600, 0.3639, 1.0585]
+print(res.fun) # minimized divergence         -> 0.17543
+
+# Compute a return level from the fitted model
+ppidest.gev_return_level(100.0, res.x)
+```
+
+Comparison across estimation methods (`scipy.stats` is used only to
+generate the data / provide the density here):
+
+```python
+import scipy.stats
+
+xs = np.sort(scipy.stats.norm.rvs(loc=1.0, scale=2.0, size=8))
+
+# Density/CDF callables must use the (x, par) convention
+def norm_pdf(x, par):
+    return scipy.stats.norm.pdf(x, loc=par[0], scale=par[1])
+
+# Maximum likelihood from the PDF
+ml = ppidest.ML(xs, norm_pdf).find_mle([1.0, 2.0])
+
+# PPID with a different divergence and plot position
+ppid = ppidest.PPID(xs, ppidest.normal_cdf, plotposition="Weibull")
+res = ppid.find_min_div([1.0, 2.0], divergence="Jensen-Shannon")
+
+# Forward extra positional arguments to the CDF callable
+def norm_cdf_given_mu(x, par, mu):
+    return ppidest.normal_cdf(x, [mu, par[0]])
+
+ppid = ppidest.PPID(xs, norm_cdf_given_mu)
+res = ppid.find_min_div([1.0, 2.0], args=(0.0,))   # scale only, mu fixed
+```
+```
+
+## Background
+
+For a sorted sample `x_(1) <= ... <= x_(n)` a plotting position assigns a
+probability to the i-th order statistic:
+
+```
+p_i = (i - alpha) / (n + 1 - alpha - beta)
+```
+
+`alpha` and `beta` are fixed by the chosen scheme:
+
+| Scheme       | alpha | beta |
+|--------------|-------|------|
+| Weibull      | 0.0   | 0.0  |
+| median       | 0.3   | 0.3  |
+| Gringorten   | 0.44  | 0.44 |
+| Hazen        | 0.5   | 0.5  |
+
+Ties are aggregated so each unique value carries the summed probability
+of the order statistics sharing it, and the support is augmented with two
+boundary bins at `0` and `1`.  The result is an empirical probability
+vector `d*` (the "empirical gaps").  A candidate distribution with
+parameters `θ` gives model gaps
+
+```
+dd_j(θ) = F(x_j; θ) - F(x_{j-1}; θ),   with x_0 = -inf, x_{k+1} = +inf
+```
+
+The estimator minimizes an information divergence `D(d* || dd(θ))` over
+`θ`:
+
+- **Kullback-Leibler** —
+  `Σ d* log(d*/dd)`
+- **generalized KL** —
+  `Σ d* log(d*/dd) - d* + dd`
+- **symmetric KL** —
+  `Σ (dd - d*) log(dd/d*)`
+- **Jensen-Shannon** —
+  `½ Σ d* log(d*/m) + dd log(dd/m)`, `m = (d* + dd)/2`
+- **beta** (order `β`) —
+  `Σ d*(d*^(β-1) - dd^(β-1))/(β-1) - (d*^β - dd^β)/β`
+- **power** (index `λ`) —
+  `1/(λ(λ+1)) Σ d*[(d*/dd)^λ - 1]`
+- **Rényi** (order `α`) —
+  `1/(α-1) log Σ d*^α dd^(1-α)`
+
+## Package layout
+
+```
+src/ppidest/
+  distributions.py   distribution cdf/pdf/quantile functions
+                     (normal, GEV, three-parameter Weibull)
+  plotting.py        plotting-position schemes and empirical gaps
+  divergences.py     information divergences between probability vectors
+  estimators.py      ML, PPID estimators
+  __init__.py        public API and legacy calc_* aliases
+```
+
+### Distributions
+
+All distribution functions share the signature `f(x, par)` with
+`par = (loc, scale, shape)` (normal and Weibull parameters differ, see
+their docstrings):
+
+- `normal_cdf`, `normal_pdf`
+- `gev_cdf`, `gev_pdf`, `gev_quantile`, `gev_return_level`
+  (GEV shape `ξ` uses the convention `ξ > 0` → heavy tail)
+- `weibull_cdf`, `weibull_pdf`
+
+### Divergences
+
+`ppidest.kl_divergence`, `kl_generalized_divergence`,
+`kl_symmetric_divergence`, `jensen_shannon_divergence`,
+`beta_divergence(das, ddas, beta)`, `power_divergence(das, ddas, lmbd)`,
+`renyi_divergence(das, ddas, alpha)` — all take the empirical gaps
+`das` and model gaps `ddas` as 1-D arrays.
+
+### Estimators
+
+| Estimator | Objective | Fit method |
+|-----------|-----------|------------|
+| `ML(xs, pdf)`     | negative log-likelihood             | `find_mle`    |
+| `PPID(xs, cdf)`   | chosen information divergence       | `find_min_div` |
+
+Every `find_*` method mirrors the keyword arguments of
+`scipy.optimize.minimize` (`method`, `jac`, `hess`, `bounds`, ...).
+`PPID.find_min_div` accepts `divergence` and, for the parametric
+divergences, `pdiv`.  The parametric divergence arguments are passed as
+singular floats (the pre-1.0 API required a length-one list).
+
+The legacy `calc_gev_cdf`, ... names are exported from the package root as
+aliases for backward compatibility, e.g. `ppidest.calc_gev_cdf` is the
+same object as `ppidest.gev_cdf`.
+
+## Notes on optimization
+
+Nelder–Mead is the default solver because the objective only needs
+CDF evaluation.  During the search the parameters may leave the support
+of the distribution, producing `NaN`; these evaluations are harmless and
+the corresponding warnings are suppressed inside the distribution and
+divergence functions.  Careful initial values (e.g. from the method of
+moments) are recommended for the scale and shape parameters.

ppidest-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ppidest/__init__.py,sha256=uRXTqJGA6puAoEwFiTFmgto8uL6TbcC3-pSTrXi78PA,6680
+ppidest/distributions.py,sha256=Z130id3V2h42rN8Jlqjrms21Ouealn003gu0bXESlGU,6857
+ppidest/divergences.py,sha256=6Ho8GIkSo5a9dHLQGzhOqKgYcsoTaRobhWOtkBIcPzU,4780
+ppidest/estimators.py,sha256=SLqoChKY70X3NduldcDdrqGvtPEbKxcG1DzSEKW40gE,13702
+ppidest/plotting.py,sha256=Klwr5iAonoMrj7E_ucb6tUsaeeWWCC4jbcTq51h8gVs,3568
+ppidest-0.1.0.dist-info/WHEEL,sha256=_d8F1e7SqtoW6CDj4Gi8lFC26a_7I17R7zPLCKTp4Fg,81
+ppidest-0.1.0.dist-info/entry_points.txt,sha256=oDABWj4ndH6xJvBVI26yx7sZyBvOWi2OPSzdjMhctyM,42
+ppidest-0.1.0.dist-info/METADATA,sha256=ddZiWjhbZzxcpIvBAJl44OjeMzAFBdtwpl2cVzIp1ws,6788
+ppidest-0.1.0.dist-info/RECORD,,

ppidest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.15
+Root-Is-Purelib: true
+Tag: py3-none-any

ppidest-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ppidest = ppidest:main
+