levy-stable 2.0.0__py3-none-any.whl

levy/__init__.py

@@ -0,0 +1,277 @@
+#    Copyright (C) 2005 Paul Harrison
+#    Copyright (C) 2017 José M. Miotto
+#    This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    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, write to the Free Software
+#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+r"""Calculation and maximum-likelihood fitting of Levy alpha-stable distributions.
+
+Direct computation of these distributions requires a lengthy numerical
+integration, so the package interpolates values from a precomputed table
+instead. That is what makes fitting by maximum likelihood fast enough to be
+practical.
+
+Notes
+-----
+**Parametrizations.** The parameters of a Levy stable distribution can be
+written down in several ways. Available here are 0 and 1 in the notation of
+Nolan [Nolan2020]_, and M, A and B from Zolotarev [Zolotarev1986]_.
+
+Nolan's are the easier two to reason about. Parametrization 0 is typically
+preferred for numerical calculations and has
+:math:`E(X)=\delta_0-\beta\gamma\tan(\pi\alpha/2)`, while 1 is preferred for
+intuition, since :math:`E(X)=\delta_1`.
+
+Parametrizations are handled by the module; you only say which one you are
+using. :meth:`~levy.parametrization.Parameters.convert` moves a parameter array
+between any two of them. Internally everything runs in parametrization 0, which
+is what the lookup tables are built in.
+
+``alpha`` below 0.5 is not supported: the tables do not cover it, and passing a
+smaller value raises :exc:`ValueError`.
+
+**Module layout.** The implementation used to be a single 800-line
+``__init__.py``. It is now split by concern, and this module re-exports the
+whole public surface, so ``import levy`` behaves exactly as before:
+
+===================== =========================================================
+``constants``         grid geometry, fit bounds, parametrization metadata
+``interpolation``     Catmull-Rom interpolation and bound folding
+``tables``            locating, loading, caching and repairing the tables
+``parametrization``   the five parametrizations and the ``Parameters`` wrapper
+``distribution``      ``levy`` and ``neglog_levy``
+``fitting``           ``fit_levy``
+``sampling``          ``random``
+``api``               the typed API: ``pdf``/``cdf``/``logpdf``/``rvs``/``fit``
+``backends``          which array library evaluates: NumPy, or optional torch
+``_build``            offline table generation (only the CLI imports it)
+===================== =========================================================
+
+References
+----------
+.. [Nolan2020] J. P. Nolan, "Univariate Stable Distributions", Springer, 2020.
+   https://edspace.american.edu/jpnolan/stable/
+.. [Zolotarev1986] V. M. Zolotarev, "One-dimensional Stable Distributions",
+   AMS, 1986.
+
+Examples
+--------
+>>> import numpy as np
+>>> import levy
+>>> np.round(levy.cdf(np.array([1.0, 2.0]), alpha=1.5, beta=0.0), 6)
+array([0.756342, 0.89496 ])
+>>> x = levy.rvs(alpha=1.5, beta=0.0, size=200, random_state=0)
+>>> bool(np.allclose(levy.fit(x).params.as_tuple(), [1.525, -0.078, 0.048, 0.986], atol=5e-3))
+True
+"""
+
+import importlib
+import warnings
+
+from levy._logging import logger  # noqa: F401  (re-exported)
+from levy.constants import _lower, _upper  # noqa: F401  (re-exported)
+from levy.distribution import (  # noqa: F401  (re-exported)
+    _approximate,
+    _check_alpha_beta,
+    _grid_index,
+    _grid_shape,
+)
+from levy.interpolation import _interpolate, _reflect  # noqa: F401  (re-exported)
+from levy.parametrization import _phi, _psi  # noqa: F401  (re-exported)
+from levy.sampling import _ALPHA_1_RADIUS  # noqa: F401  (re-exported)
+from levy.tables import (  # noqa: F401  (re-exported)
+    _CDF_TOLERANCE,
+    _TABLE_NAMES,
+    PACKAGED_DATA,
+    ROOT,
+    _data_cache,
+    _has_complete_tables,
+    _load_table,
+    _read_from_cache,
+    _repair_table,
+    data_dir,
+    user_cache_dir,
+)
+
+__version__ = "2.0.0"
+
+#: The 2.0 surface.
+_CURRENT = [
+    'pdf',
+    'cdf',
+    'logpdf',
+    'rvs',
+    'fit',
+    'StableParams',
+    'FitResult',
+    'api',
+    'backends',
+    'set_backend',
+    'using',
+    'data_dir',
+    'user_cache_dir',
+    'PACKAGED_DATA',
+    'ROOT',
+    'logger',
+    '__version__',
+]
+
+# The 1.x names. Every one of them still works and still returns exactly what
+# it returned in 1.1; each maps to (module, attribute, what to use instead).
+#
+# They are resolved through the module __getattr__ below rather than imported
+# up here, which is the whole point: the warning fires when a name is *used*,
+# not when levy is imported. An import-time warning storm -- one line for every
+# deprecated name, on every `import levy`, whether or not the caller touches
+# any of them -- is the fastest way to get a deprecation reverted.
+_DEPRECATED = {
+    'levy': (
+        'levy.distribution', 'levy',
+        'levy.pdf() for a density and levy.cdf() for a distribution '
+        'function; the cdf= flag is gone',
+    ),
+    'neglog_levy': (
+        'levy.distribution', 'neglog_levy',
+        'levy.logpdf(), which returns log(pdf) -- note the opposite sign',
+    ),
+    'fit_levy': (
+        'levy.fitting', 'fit_levy',
+        'levy.fit(), which returns a FitResult and rejects a misspelt '
+        'parameter name instead of ignoring it',
+    ),
+    'random': (
+        'levy.sampling', 'random',
+        'levy.rvs(), which takes size= rather than shape=',
+    ),
+    'Parameters': (
+        'levy.parametrization', 'Parameters',
+        'levy.StableParams to carry parameters, or '
+        'levy.parametrization.Parameters if you need the fitting wrapper that '
+        'tracks which components are held fixed',
+    ),
+    'convert_to_par0': (
+        'levy.parametrization', 'convert_to_par0',
+        'levy.StableParams.from_par(), which validates the result',
+    ),
+    'convert_from_par0': (
+        'levy.parametrization', 'convert_from_par0',
+        'levy.StableParams.to_par()',
+    ),
+    'size': ('levy.constants', 'size', 'levy.constants.size'),
+    'par_bounds': ('levy.constants', 'par_bounds', 'levy.constants.par_bounds'),
+    'par_names': ('levy.constants', 'par_names', 'levy.constants.par_names'),
+    'default': ('levy.constants', 'default', 'levy.constants.default'),
+    'f_bounds': ('levy.constants', 'f_bounds', 'levy.constants.f_bounds'),
+}
+
+# The typed API. Defined in levy.api and reached here as `levy.pdf(...)`,
+# `levy.fit(...)` and so on, which is the spelling the documentation uses;
+# `levy.pdf` is the same object. Resolved lazily for the same reason `api`
+# itself is below: pydantic stays off the critical path of `import levy` until
+# a caller actually uses this surface.
+_API = ('pdf', 'cdf', 'logpdf', 'rvs', 'fit', 'StableParams', 'FitResult')
+
+# Submodules, resolved on attribute access by __getattr__ below. Several of
+# them do also become attributes as a side effect of the re-exports above, but
+# relying on that would make `import levy; levy.sampling.random(...)` work by
+# accident: it would break the moment a re-export moved. `api` is here for a
+# second reason -- resolving it lazily keeps pydantic off the critical path of
+# `import levy`.
+_SUBMODULES = (
+    'api',
+    'backends',
+    'constants',
+    'distribution',
+    'fitting',
+    'interpolation',
+    'parametrization',
+    'sampling',
+    'tables',
+)
+
+# The table-generation helpers moved to levy._build. Resolved lazily too, so
+# importing levy does not pull in scipy.integrate for the sake of code only a
+# maintainer regenerating tables ever runs.
+_MOVED_TO_BUILD = {
+    '_calculate_levy': 'calculate_levy',
+    '_int_levy': 'interpolated_levy',
+}
+
+__all__ = _CURRENT + sorted(_DEPRECATED)
+
+
+def __getattr__(name):
+    """Resolve the typed API, the 1.x names, the submodules and the ``levy._build`` helpers.
+
+    Parameters
+    ----------
+    name : str
+        Attribute being looked up.
+
+    Returns
+    -------
+    object
+        The requested object, unchanged. A deprecated name additionally emits a
+        :exc:`DeprecationWarning` naming its replacement.
+
+    Raises
+    ------
+    AttributeError
+        For any other name, as a module lookup normally would.
+
+    Notes
+    -----
+    PEP 562 module-level lookup. Nothing here is a wrapper: a deprecated name
+    resolves to the very same object 1.1 exported, so numbers cannot drift
+    between the old spelling and the new one. Only the lookup is intercepted.
+    """
+    if name in _API:
+        return getattr(importlib.import_module('levy.api'), name)
+
+    if name in _SUBMODULES:
+        return importlib.import_module(f'levy.{name}')
+
+    if name in ('set_backend', 'using'):
+        # levy.backends imports nothing heavier than levy._compat, so this
+        # costs nothing for a caller who never selects a backend.
+        return getattr(importlib.import_module('levy.backends'), name)
+
+    if name in _DEPRECATED:
+        module_name, attribute, replacement = _DEPRECATED[name]
+        warnings.warn(
+            f'levy.{name} is deprecated since 2.0 and will be removed in a future '
+            f'major release; '
+            f'use {replacement}. It still lives at {module_name}.{attribute} '
+            f'if you want the 1.x behavior without the warning.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(importlib.import_module(module_name), attribute)
+
+    if name in _MOVED_TO_BUILD:
+        return getattr(importlib.import_module('levy._build'), _MOVED_TO_BUILD[name])
+
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
+def __dir__():
+    """List the package's attributes, deprecated names included.
+
+    Returns
+    -------
+    list of str
+        Sorted names, so tab completion and ``dir(levy)`` still show the 1.x
+        spellings that lazy resolution keeps out of the module dictionary.
+    """
+    return sorted(set(globals()) | set(__all__) | set(_SUBMODULES)
+                  | set(_MOVED_TO_BUILD))

levy/__main__.py

@@ -0,0 +1,29 @@
+"""Entry point for ``python -m levy``.
+
+This file did not exist before, which means ``python -m levy build`` -- the
+command the module docstring gave for regenerating the lookup tables -- never
+actually worked: for a package, ``-m`` requires ``__main__.py``, and the
+``if __name__ == "__main__"`` block in ``__init__.py`` is only reachable by
+running that file directly (``python levy/__init__.py build``).
+
+Prefer the ``levy-tables`` console script; this exists so the documented
+invocation does what it says.
+"""
+
+import sys
+
+from levy._build.cli import main
+
+if __name__ == "__main__":
+    argv = sys.argv[1:]
+    if argv and argv[0] == "build":
+        # The documented 1.x spelling. Keep it working, and say what
+        # replaced it -- and where it writes now. Written to stderr rather
+        # than logged: logging is only configured inside main(), so a log
+        # record emitted here would go to the library's NullHandler.
+        sys.stderr.write(
+            "`python -m levy build` is superseded by the `levy-tables` command; "
+            "the tables go to the user cache directory, not into the package.\n"
+        )
+        sys.exit(main(argv))
+    sys.exit(main(argv or ["where"]))

levy/_build/__init__.py

@@ -0,0 +1,27 @@
+"""Offline generation of the lookup tables pylevy interpolates from.
+
+Nothing here is needed to *use* the package. It is imported only by the
+``levy-tables`` command and by tests, which is the point: the previous
+arrangement kept the quadrature code in ``levy/__init__.py``, so importing the
+library pulled in ``scipy.integrate`` and ~90 lines that only a maintainer
+regenerating the tables would ever run.
+
+The tables take roughly 25 minutes of CPU to rebuild at the shipped
+(200, 76, 101) resolution, and the crossover limits another 30, so the builders
+here support parallel execution.
+"""
+
+from levy._build.quadrature import calculate_levy, interpolated_levy
+from levy._build.tables import (
+    build_crossover_tables,
+    build_density_tables,
+    write_manifest,
+)
+
+__all__ = [
+    "build_crossover_tables",
+    "build_density_tables",
+    "calculate_levy",
+    "interpolated_levy",
+    "write_manifest",
+]

levy/_build/cli.py

@@ -0,0 +1,299 @@
+"""``levy-tables``: regenerate the lookup tables.
+
+    levy-tables build                    # into the user cache directory
+    levy-tables build --out ./tables     # somewhere explicit
+    levy-tables build --size 40,16,21 --jobs 6
+    levy-tables where                    # which tables are actually in use
+
+Previously the only way to do this was ``python -m levy build``, which wrote
+24 MB straight into the installed package -- impossible on a read-only or
+system install, and silently destructive on a partial run.
+"""
+
+import argparse
+import logging
+import os
+import sys
+import time
+
+logger = logging.getLogger("levy._build")
+
+
+def _default_size():
+    """Return the grid size of the tables shipped with the package.
+
+    Returns
+    -------
+    tuple of int
+        ``levy.constants.size``.
+    """
+    from levy.constants import size
+
+    return size
+
+
+def _parse_size(text):
+    """Parse an ``x,alpha,beta`` grid size from the command line.
+
+    Parameters
+    ----------
+    text : str
+        Three comma-separated integers, e.g. ``"200,76,101"``.
+
+    Returns
+    -------
+    tuple of int
+        The grid shape.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If there are not three of them, or any is below 8, which is the
+        smallest grid cubic interpolation can use.
+    """
+    parts = [int(p) for p in text.split(",")]
+    if len(parts) != 3:
+        raise argparse.ArgumentTypeError(
+            "expected three comma-separated integers, e.g. 200,76,101")
+    if any(p < 8 for p in parts):
+        raise argparse.ArgumentTypeError(
+            "each dimension must be at least 8 for cubic interpolation")
+    return tuple(parts)
+
+
+def _parse_what(text):
+    """Parse the comma-separated list of tables to build.
+
+    Parameters
+    ----------
+    text : str
+        Any of ``pdf``, ``cdf`` and ``limits``, comma-separated.
+
+    Returns
+    -------
+    list of str
+        The requested tables, in the order given.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If any name is not one of the three.
+    """
+    allowed = {"pdf", "cdf", "limits"}
+    what = [p.strip() for p in text.split(",") if p.strip()]
+    unknown = set(what) - allowed
+    if unknown:
+        raise argparse.ArgumentTypeError(
+            "unknown table(s): {}".format(", ".join(sorted(unknown))))
+    return what
+
+
+# Which files each `--what` item rewrites, in either limits layout.
+_WRITES = {
+    "pdf": ("pdf.npz",),
+    "cdf": ("cdf.npz",),
+    "limits": ("lower_limit.npz", "upper_limit.npz", "limits.npz"),
+}
+
+
+def _tables_left_over(out_dir, size, what):
+    """Find tables in `out_dir` that this run would leave at another size.
+
+    Parameters
+    ----------
+    out_dir : str
+        Directory the build writes to.
+    size : tuple of int
+        Grid shape being built.
+    what : list of str
+        The ``--what`` items, i.e. which tables this run rewrites.
+
+    Returns
+    -------
+    list of str
+        One description per offending file, ``"name is AxBxC"``; empty when
+        the directory holds nothing that would clash.
+
+    Notes
+    -----
+    ``data_dir()`` takes a directory on the strength of which files exist, so
+    a partial rebuild at a new size would leave the untouched tables at the
+    old one and the set would be used together: the grid index comes from
+    the pdf's shape, and the other tables would be read with it. Refusing
+    here keeps a cache internally consistent by construction.
+    """
+    import numpy as np
+
+    kept = set()
+    for item in ("pdf", "cdf", "limits"):
+        if item not in what:
+            kept.update(_WRITES[item])
+    wrong = []
+    for name in sorted(kept):
+        path = os.path.join(out_dir, name)
+        if not os.path.exists(path):
+            continue
+        with np.load(path) as archive:
+            shapes = {tuple(archive[key].shape) for key in archive.files}
+        expected = tuple(size) if name in ("pdf.npz", "cdf.npz") else tuple(size[1:])
+        if shapes != {expected}:
+            wrong.append("{} is {}".format(name, ", ".join("x".join(map(str, s)) for s in shapes)))
+    return wrong
+
+
+def build(args):
+    """Run the ``build`` subcommand.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments: ``out``, ``size``, ``what`` and ``jobs``.
+
+    Returns
+    -------
+    int
+        Process exit status.
+    """
+    from levy._build.tables import build_crossover_tables, build_density_tables, write_manifest
+    from levy.tables import data_dir
+
+    out_dir = args.out or data_dir(writable=True)
+    logger.info("Writing tables to %s", out_dir)
+
+    wrong = _tables_left_over(out_dir, args.size, args.what)
+    if wrong:
+        logger.error(
+            "%s already holds tables at another size that this run would leave in "
+            "place (%s); a set of mixed sizes is unusable. Rebuild everything "
+            "(--what pdf,cdf,limits), or use a different --out.",
+            out_dir, "; ".join(wrong),
+        )
+        return 2
+
+    started = time.time()
+    densities = [w for w in args.what if w in ("pdf", "cdf")]
+    cdf_table = None
+    if densities:
+        results = build_density_tables(out_dir, args.size, jobs=args.jobs, what=densities)
+        if "cdf" in results:
+            cdf_table = results["cdf"][0]
+
+    if "limits" in args.what:
+        # Without a cdf from this run, build_crossover_tables takes the one
+        # already in out_dir (that is how limits get recomputed for a table
+        # built earlier), and refuses any cdf that is not the requested size.
+        try:
+            build_crossover_tables(out_dir, args.size, jobs=args.jobs, cdf_table=cdf_table)
+        except ValueError as error:
+            logger.error("%s", error)
+            return 2
+
+    manifest = write_manifest(
+        out_dir, args.size, extra={"seconds": round(time.time() - started, 1)})
+    logger.info("Done in %.1fs. Manifest: %s",
+                time.time() - started, os.path.join(out_dir, "manifest.json"))
+    for name, entry in sorted(manifest["tables"].items()):
+        logger.info("  %-12s %8.2f MB  %s", name, entry["bytes"] / 1e6, entry["sha256"][:16])
+    return 0
+
+
+def where(args):
+    """Run the ``where`` subcommand, reporting which tables are in use.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed arguments. Unused; present for the subcommand dispatch.
+
+    Returns
+    -------
+    int
+        Process exit status.
+    """
+    import levy
+
+    print(f"tables in use : {levy.data_dir()}")
+    print(f"packaged      : {levy.PACKAGED_DATA}")
+    print(f"user cache    : {levy.user_cache_dir()}")
+    print("LEVY_DATA_DIR : {}".format(os.environ.get("LEVY_DATA_DIR", "(unset)")))
+    directory = levy.data_dir()
+    if not os.path.isdir(directory):
+        print(f"  {directory} is not a directory")
+        return 1
+
+    # The required set, each marked present or MISSING, rather than whatever
+    # happens to be in the directory: an override or cache that is incomplete
+    # should say which file is the problem. The crossover limits are one
+    # merged file; tables built by an older version have two.
+    expected = ["pdf.npz", "cdf.npz"]
+    legacy = ("lower_limit.npz", "upper_limit.npz")
+    # Either legacy file, not both: a split layout missing one half should be
+    # reported as that half missing, not as limits.npz missing.
+    if any(os.path.exists(os.path.join(directory, n)) for n in legacy) and \
+            not os.path.exists(os.path.join(directory, "limits.npz")):
+        expected.extend(legacy)
+    else:
+        expected.append("limits.npz")
+    missing = 0
+    for name in expected + ["manifest.json"]:
+        path = os.path.join(directory, name)
+        if os.path.exists(path):
+            print(f"  {name:<16} {os.path.getsize(path) / 1e6:8.2f} MB")
+        elif name == "manifest.json":
+            print(f"  {name:<16} (none: not built by levy-tables)")
+        else:
+            print(f"  {name:<16} MISSING")
+            missing += 1
+    return 1 if missing else 0
+
+
+def main(argv=None):
+    """Entry point for the ``levy-tables`` console script.
+
+    Parameters
+    ----------
+    argv : sequence of str, optional
+        Command-line arguments. Read from ``sys.argv`` when omitted.
+
+    Returns
+    -------
+    int
+        Process exit status.
+    """
+    parser = argparse.ArgumentParser(prog="levy-tables", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("-v", "--verbose", action="store_true",
+                        help="verbose (DEBUG) logging")
+    subparsers = parser.add_subparsers(dest="command")
+
+    build_parser = subparsers.add_parser("build", help="regenerate the lookup tables")
+    build_parser.add_argument(
+        "--out", help="output directory (default: the user cache directory)")
+    build_parser.add_argument("--size", type=_parse_size, default=None,
+                              help="grid as x,alpha,beta (default: 200,76,101)")
+    build_parser.add_argument("--what", type=_parse_what, default=["pdf", "cdf", "limits"],
+                              help="which tables to build (default: pdf,cdf,limits)")
+    build_parser.add_argument("--jobs", type=int, default=1,
+                              help="worker processes; a full build is ~55 CPU-minutes")
+    build_parser.set_defaults(func=build)
+
+    where_parser = subparsers.add_parser(
+        "where", help="show which tables are in use; exit status 1 if any is missing")
+    where_parser.set_defaults(func=where)
+
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(message)s",
+    )
+    if args.command == "build" and args.size is None:
+        args.size = tuple(_default_size())
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())