funcsim 0.2.7__tar.gz → 0.2.9__tar.gz

{funcsim-0.2.7/funcsim.egg-info → funcsim-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.7
+Version: 0.2.9
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -55,7 +55,7 @@ Features:
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
 - multivariate normal (fitted to data or specified by a mean vector and covariance matrix) and multivariate KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas, fitted to pseudo-observations or specified by their parameters (implemented natively, no additional packages required); information-criterion comparison of copula families; Iman-Conover; covariance shrinkage
-- expected utility and cumulative prospect theory calculations
+- expected utility, cumulative prospect theory, and regret-theoretical expected utility calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)
 - functional paradigm

{funcsim-0.2.7 → funcsim-0.2.9}/README.md

@@ -10,7 +10,7 @@ Features:
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
 - multivariate normal (fitted to data or specified by a mean vector and covariance matrix) and multivariate KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas, fitted to pseudo-observations or specified by their parameters (implemented natively, no additional packages required); information-criterion comparison of copula families; Iman-Conover; covariance shrinkage
-- expected utility and cumulative prospect theory calculations
+- expected utility, cumulative prospect theory, and regret-theoretical expected utility calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)
 - functional paradigm

{funcsim-0.2.7 → funcsim-0.2.9}/funcsim/__init__.py

@@ -39,6 +39,8 @@ from .cpt import weightPrelec2, cptBV
 
 from .eut import eut, utilIsoelastic, eutIsoelastic
 
+from .rteu import rteu, regretPower
+
 from .plotting import fan, twofuncs, histpdf, dblscat, qqplot, show
 
 def version():
@@ -48,6 +50,6 @@ def version():
     Returns
     -------
     str
-        The version string of the package (e.g., '0.2.7').
+        The version string of the package (e.g., '0.2.9').
     """
-    return "0.2.7"
+    return "0.2.9"

{funcsim-0.2.7 → funcsim-0.2.9}/funcsim/dependence.py

@@ -324,17 +324,44 @@ class MvKde():
         in rows.
     bw : str or ArrayLike, optional
         Bandwidth selection method ('scott' or 'silverman'), or a K-by-K
-        bandwidth covariance matrix in the units of the data.
-        Default is 'scott'.
+        bandwidth covariance matrix in the units of the data, given as
+        anything :func:`numpy.asarray` accepts (a nested list, a NumPy
+        array, or a DataFrame).  Default is 'scott'.  The matrix in use is
+        available as :attr:`bandwidth`.
 
     Notes
     -----
     Each call to :meth:`draw` consumes K + 1 values from ``ugen``, where K
     is the number of variables.
+
+    Both rules of thumb give a diagonal bandwidth matrix whose entries are
+    a common factor times the variance of each variable, with M
+    observations and K variables:
+
+    - Scott's rule: ``H = M ** (-2 / (K + 4)) * diag(s_1 ** 2, ..., s_K ** 2)``
+    - Silverman's rule:
+      ``H = ((K + 2) * M / 4) ** (-2 / (K + 4)) * diag(s_1 ** 2, ..., s_K ** 2)``
+
+    where ``s_k`` is the standard deviation of variable k, computed with
+    ``ddof=0`` (dividing by M).  The two rules coincide when K = 2.  These
+    are the normal-reference rules of Scott (1992, eq. 6.42) and Silverman
+    (1986, eq. 4.14), and the same expressions as
+    :class:`scipy.stats.gaussian_kde`'s ``scotts_factor`` and
+    ``silverman_factor``.  Before version 0.2.8 the Silverman factor was
+    computed as ``(4 * M / (K + 2)) ** (-1 / (K + 4))``, which is correct
+    only at K = 2.
+
+    References
+    ----------
+    Scott, D.W. (1992). Multivariate Density Estimation: Theory, Practice,
+    and Visualization. John Wiley & Sons.
+
+    Silverman, B.W. (1986). Density Estimation for Statistics and Data
+    Analysis. Chapman and Hall.
     """
     def __init__(self,
                  data: conversions.ArrayLike,
-                 bw: str = 'scott'
+                 bw: Union[str, conversions.ArrayLike, None] = 'scott'
                 ) -> None:
         self._data = conversions.alToArray(data)
         self._names = conversions.alColNames(data)
@@ -352,18 +379,27 @@ class MvKde():
         mult = self._M**(-1.0/(self._K+4.0))
         self._scott =  np.square(mult * np.diagflat(stdevs))
 
-        # rule-of-thumb silverman bandwidth
-        smult = ((4.0 * self._M)/ (self._K+2.0))**(-1.0 / (self._K+4.0))
+        # rule-of-thumb silverman bandwidth (Silverman, 1986, eq. 4.14;
+        # the same expression as scipy's gaussian_kde.silverman_factor).
+        # Before 0.2.8 the (K + 2) / 4 factor was inverted, which agrees
+        # with this only at K = 2
+        smult = ((self._K+2.0) * self._M / 4.0)**(-1.0 / (self._K+4.0))
         self._silverman = np.square(smult * np.diagflat(stdevs))
 
-        if bw is None or bw == 'scott':
-            self._bw = self._scott
-        elif bw == 'silverman':
-            self._bw = self._silverman
-        elif isinstance(bw, str):
-            raise ValueError(f"unknown bandwidth method '{bw}'; expected "
-                             f"'scott', 'silverman', or a "
-                             f"{self._K}-by-{self._K} bandwidth matrix")
+        # dispatch on the type of bw before comparing it with anything: a
+        # NumPy array compared with a string evaluates elementwise under
+        # NumPy 2, and its truth value is ambiguous
+        if bw is None:
+            bw = 'scott'
+        if isinstance(bw, str):
+            if bw == 'scott':
+                self._bw = self._scott
+            elif bw == 'silverman':
+                self._bw = self._silverman
+            else:
+                raise ValueError(f"unknown bandwidth method '{bw}'; "
+                                 f"expected 'scott', 'silverman', or a "
+                                 f"{self._K}-by-{self._K} bandwidth matrix")
         else:
             H = np.asarray(bw, dtype=float)
             if H.shape != (self._K, self._K):
@@ -373,9 +409,32 @@ class MvKde():
             Dinv = np.diag(1.0 / self._stds)
             self._bw = Dinv @ H @ Dinv
 
+        # a bandwidth matrix that is not positive definite is repaired to
+        # the nearest one, and the repaired matrix is the one reported by
+        # the bandwidth property (nearestpd returns a positive definite
+        # input unchanged)
+        self._bw = nearby.nearestpd(self._bw)
+
         # cholesky decomp of the bandwidth (covariance) matrix, so that
         # draws apply covariance H (not H @ H.T)
-        self._chol = np.linalg.cholesky(nearby.nearestpd(self._bw))
+        self._chol = np.linalg.cholesky(self._bw)
+
+    @property
+    def bandwidth(self) -> pd.DataFrame:
+        """
+        The bandwidth matrix ``H`` in use, in the units of the data, as a
+        K-by-K covariance DataFrame whose index and columns are the
+        variable names.
+
+        For ``bw='scott'`` or ``bw='silverman'`` this is diagonal, the
+        rule's factor squared times the variance of each variable with
+        ``ddof=0`` (see the class notes); for a user-supplied matrix it is
+        that matrix, or the nearest positive definite matrix to it if it
+        was not positive definite.
+        """
+        D = np.diag(self._stds)
+        return pd.DataFrame(D @ self._bw @ D, index=self._names,
+                            columns=self._names)
 
     def draw(self,
              ugen: Generator[float, None, None]

{funcsim-0.2.7 → funcsim-0.2.9}/funcsim/kde.py

@@ -69,7 +69,8 @@ class Kde():
         Bandwidth selection method ('scott', 'silverman') or a positive
         float to use as the bandwidth (the standard deviation of the
         Gaussian kernel), in the same units as the data.
-        Default is 'scott'.
+        Default is 'scott'.  The bandwidth in use is available as
+        :attr:`bandwidth`.
     exact_ppf : bool, optional
         If True, :meth:`ppf` finds every value by root finding on
         :meth:`cdf`, as funcsim did before version 0.2.7 (about 0.3 ms per
@@ -82,6 +83,14 @@ class Kde():
     argument and a NumPy array of the same shape for an array-like argument
     (a pandas Series or a list gives an array).
 
+    The two rules of thumb set the bandwidth to a factor times the sample
+    standard deviation ``s`` of the M observations, computed with
+    ``ddof=1`` (dividing by M - 1, as :class:`scipy.stats.gaussian_kde`
+    does): Scott's rule gives ``M ** (-1 / 5) * s`` and Silverman's rule
+    ``(3 * M / 4) ** (-1 / 5) * s``.  (:class:`funcsim.MvKde` applies the
+    same factors to a ``ddof=0`` standard deviation, so on the same single
+    column its bandwidth is smaller by the factor ``sqrt((M - 1) / M)``.)
+
     The inverse-CDF table evaluates the CDF on 4096 points spanning the data
     range plus eight kernel standard deviations on each side, and
     interpolates x against the normal score of the CDF with a
@@ -129,6 +138,18 @@ class Kde():
         self._exact_ppf = bool(exact_ppf)
         self._table = None  # inverse-CDF table, built on first use
 
+    @property
+    def bandwidth(self) -> float:
+        """
+        The bandwidth in use, the standard deviation of the Gaussian
+        kernel, in the units of the data.
+
+        For ``bw='scott'`` or ``bw='silverman'`` this is the rule's factor
+        (``gkde.factor``) times the sample standard deviation of the data
+        with ``ddof=1``; for a float ``bw`` it is that value.
+        """
+        return math.sqrt(float(self.gkde.covariance[0, 0]))
+
     @staticmethod
     def _apply(func, x):
         # evaluate a 1-D-array function on scalar or array-like input:

funcsim-0.2.9/funcsim/rteu.py

@@ -0,0 +1,222 @@
+"""regret-theoretical expected utility (RTEU) and certainty equivalents"""
+
+import math
+from collections import namedtuple
+from typing import Callable, Union
+import numpy as np
+from numpy.typing import NDArray
+import scipy
+from . import conversions
+
+
+# container for results
+RteuResult = namedtuple("RteuResult", "ExpectedValue CertaintyEquiv")
+
+
+def regretPower(x: Union[float, NDArray],
+                exponent: float,
+                ) -> Union[float, NDArray]:
+    """
+    Compute power regret for a utility gap.
+
+    Parameters
+    ----------
+    x : float or numpy.ndarray
+        The utility gap psi(y_max) - psi(y), non-negative; an array is
+        evaluated elementwise.
+    exponent : float
+        Curvature of regret, at least 1.0.  Values above one make the regret
+        function strictly convex, so a few large regrets weigh more than
+        many small ones; at exactly one, regret is linear in the gap and the
+        choice between scenarios coincides with expected utility's, although
+        the certainty equivalents do not.
+
+    Returns
+    -------
+    float or numpy.ndarray
+        ``x ** exponent``, a float for a float and an array for an array.
+
+    Raises
+    ------
+    ValueError
+        If ``x`` (or any element of it) is negative or ``exponent`` is below
+        1.0.
+
+    Notes
+    -----
+    This is the one ready-made regret function; any function of one
+    non-negative float with g(0) = 0 may be passed as ``regretFunc``.  It
+    accepts arrays as well as floats so that a user's own per-state code can
+    call it on whole vectors; ``rteu`` evaluates it through
+    ``numpy.vectorize`` like any other ``regretFunc``.  There is no
+    canonical parameterization in the literature comparable to Tversky and
+    Kahneman's for cumulative prospect theory, so no preset analogous to
+    ``cptBV`` is provided.
+    """
+    if exponent < 1.0:
+        raise ValueError(f"exponent (={exponent}) must be at least 1.0")
+    xa = np.asarray(x, dtype=float)
+    if np.any(xa < 0.0):
+        raise ValueError(f"x (={x}) must be non-negative: the argument of "
+                         "a regret function is a utility gap")
+    powered = xa ** exponent
+    return float(powered) if powered.ndim == 0 else powered
+
+
+def _rtu(psiY, psiBest, vg, k):
+    # psi(y) - k g(psi(best) - psi(y)), elementwise, from utilities that
+    # have already been evaluated; vg is the vectorized regret function.
+    # psiY may be a scalar (a sure amount), in which case it broadcasts
+    return psiY - k * vg(psiBest - psiY)
+
+
+def _finite_or_raise(values, where, label):
+    # raise if any evaluated utility is not finite, naming the first culprit
+    bad = ~np.isfinite(values)
+    if np.any(bad):
+        i = int(np.argmax(bad))
+        raise ValueError(f"utilFunc is not finite at {label} {where[i]} "
+                         f"(position {i})")
+
+
+def rteu(utilFunc: Callable[[float], float],
+         regretFunc: Callable[[float], float],
+         regretCoeff: float,
+         outcomes: conversions.VectorLike,
+         best: conversions.VectorLike,
+         ) -> RteuResult:
+    """
+    Compute regret-theoretical expected utility (RTEU) and the certainty
+    equivalent of one scenario, given the best attainable outcome in each
+    state of nature across the decision maker's menu.
+
+    Parameters
+    ----------
+    utilFunc : Callable
+        Utility function of the monetary outcome, psi, taking a float and
+        returning a float.  It must be strictly increasing; the theory also
+        assumes it concave.  See ``utilIsoelastic``.
+    regretFunc : Callable
+        Regret function of the utility gap, g, taking a non-negative float
+        and returning a float, with g(0) = 0, g' > 0, and g'' > 0.  See
+        ``regretPower``.
+    regretCoeff : float
+        Regret coefficient k, non-negative.  At zero the results are those
+        of expected utility theory.
+    outcomes : VectorLike
+        The scenario's outcome in each state of nature (one value per
+        simulation trial).
+    best : VectorLike
+        The best attainable outcome in the same state of nature across every
+        scenario in the menu, the same length as ``outcomes`` and no smaller
+        than it in any state: typically the row-wise maximum across the
+        scenario columns, which includes this scenario's own outcome.
+        Element n of ``outcomes`` and of ``best`` must belong to the same
+        state of nature, which ``simulate`` delivers when every scenario is
+        run at the same seed and number of trials.
+
+    Returns
+    -------
+    RteuResult
+        Named tuple with fields:
+
+        ExpectedValue : float
+            The regret-theoretical expected utility of the scenario, the
+            mean over states of psi(y) - k g(psi(best) - psi(y)).
+        CertaintyEquiv : float
+            The certainty equivalent of the scenario within the menu: the
+            sure amount c such that the decision maker is indifferent
+            between c and the scenario when both are in the menu, each
+            evaluated against the best attainable outcome max(best, c) in
+            every state.
+
+    Raises
+    ------
+    ValueError
+        If ``outcomes`` and ``best`` differ in length, ``best`` is smaller
+        than ``outcomes`` in any state, ``regretCoeff`` is negative,
+        ``regretFunc(0.0)`` is not zero, or ``utilFunc`` is not finite at
+        every outcome (for example a logarithmic psi applied to a
+        non-positive outcome).
+
+    Notes
+    -----
+    The per-state index follows Braun and Muermann (2004); measuring regret
+    against the best attainable outcome in each state is the form implied
+    by Quiggin's (1994) irrelevance of statewise dominated alternatives,
+    and it is why the rest of the menu enters only through ``best``.  The
+    certainty equivalent is the menu-based definition of the regret theory
+    literature (Loomes and Sugden, 1983; Diecidue and Somasundaram, 2017;
+    Gollier, 2020).  It is found by Brent's method between the scenario's
+    smallest outcome and the largest value of ``best``, where the
+    indifference condition has opposite signs; the sure-amount side is
+    strictly increasing in c and the scenario side non-increasing, so the
+    root is unique.  At ``regretCoeff`` = 0 the certainty equivalent is the
+    expected utility certainty equivalent, psi^-1(E[psi(y)]), and
+    ``ExpectedValue`` is E[psi(y)].  States are equally likely.  Passing the
+    scenario's own outcomes as ``best`` describes a menu of the scenario
+    and the sure amount alone, the two-element setting of Loomes and Sugden
+    (1983).  Because a sure amount is itself regret-prone within the menu,
+    the gap between a scenario's expected outcome and its certainty
+    equivalent is not the risk premium of expected utility theory (Gollier,
+    2020), and the certainty equivalents can order two scenarios
+    differently from the choice between them; the choice rests on
+    ``ExpectedValue``.  The scale of ``utilFunc`` matters: k weights regret
+    measured in utility units, so k is not comparable across differently
+    scaled psi.  The utility and regret functions are evaluated through
+    ``numpy.vectorize``, so any function of one float works.
+    """
+    if regretCoeff < 0.0:
+        raise ValueError(f"regretCoeff (={regretCoeff}) must be non-negative")
+    g0 = float(regretFunc(0.0))
+    if not math.isclose(g0, 0.0, abs_tol=1e-12):
+        raise ValueError(f"regretFunc(0.0) must be zero (got {g0})")
+
+    y = conversions.vlToArray(outcomes).astype(float)
+    b = conversions.vlToArray(best).astype(float)
+    if len(y) != len(b):
+        raise ValueError(f"outcomes (length {len(y)}) and best (length "
+                         f"{len(b)}) must have the same length")
+    below = b < y
+    if np.any(below):
+        i = int(np.argmax(below))
+        raise ValueError("best must be the best attainable outcome in each "
+                         "state, so no smaller than outcomes; at position "
+                         f"{i} best={b[i]} is below outcomes={y[i]}")
+
+    vpsi = np.vectorize(utilFunc, otypes=[float])
+    vg = np.vectorize(regretFunc, otypes=[float])
+    with np.errstate(invalid="ignore", divide="ignore"):
+        psiY = vpsi(y)
+        psiB = vpsi(b)
+    _finite_or_raise(psiY, y, "outcome")
+    _finite_or_raise(psiB, b, "best")
+    k = float(regretCoeff)
+
+    expected = float(np.mean(_rtu(psiY, psiB, vg, k)))
+
+    # certainty equivalent: the sure amount c at which the decision maker is
+    # indifferent between c and the scenario, both in the menu, so that the
+    # best attainable outcome is max(best, c) in every state.  Because psi
+    # is increasing, psi(max(best, c)) = max(psi(best), psi(c)), so psi is
+    # evaluated on one scalar per iteration and g on the vector
+    def gap(c):
+        psiC = float(utilFunc(c))
+        psiBC = np.maximum(psiB, psiC)
+        sure = np.mean(_rtu(psiC, psiBC, vg, k))
+        scenario = np.mean(_rtu(psiY, psiBC, vg, k))
+        return float(sure - scenario)
+
+    # the gap is <= 0 at the scenario's worst outcome and >= 0 at the menu's
+    # best, so the root lies between them; a sure scenario (constant
+    # outcomes) has gap(lo) == 0 exactly, which brentq would reject
+    lo = float(np.min(y))
+    hi = float(np.max(b))
+    if gap(lo) >= 0.0:
+        certequiv = lo
+    elif gap(hi) <= 0.0:
+        certequiv = hi
+    else:
+        certequiv = scipy.optimize.brentq(f=gap, a=lo, b=hi, maxiter=200)
+
+    return RteuResult(expected, float(certequiv))

{funcsim-0.2.7 → funcsim-0.2.9/funcsim.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.7
+Version: 0.2.9
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -55,7 +55,7 @@ Features:
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
 - multivariate normal (fitted to data or specified by a mean vector and covariance matrix) and multivariate KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas, fitted to pseudo-observations or specified by their parameters (implemented natively, no additional packages required); information-criterion comparison of copula families; Iman-Conover; covariance shrinkage
-- expected utility and cumulative prospect theory calculations
+- expected utility, cumulative prospect theory, and regret-theoretical expected utility calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)
 - functional paradigm

{funcsim-0.2.7 → funcsim-0.2.9}/funcsim.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ funcsim/multicore.py
 funcsim/nearby.py
 funcsim/plotting.py
 funcsim/rdarrays.py
+funcsim/rteu.py
 funcsim/screen.py
 funcsim/shapiro.py
 funcsim/shrinkage.py

{funcsim-0.2.7 → funcsim-0.2.9}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="funcsim",
-    version="0.2.7",
+    version="0.2.9",
     license="bsd-3-clause",
     author="Henry Bryant",
     author_email="henry@tamu.edu",