funcsim 0.2.7__tar.gz → 0.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.7
+Version: 0.2.8
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant

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

@@ -48,6 +48,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.8').
     """
-    return "0.2.7"
+    return "0.2.8"

{funcsim-0.2.7 → funcsim-0.2.8}/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.8}/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.7 → funcsim-0.2.8/funcsim.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.7
+Version: 0.2.8
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant

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

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