funcsim 0.2.4__tar.gz → 0.2.5__tar.gz

{funcsim-0.2.4/funcsim.egg-info → funcsim-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.4
+Version: 0.2.5
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -54,7 +54,7 @@ Features:
 - stratified/Latin hypercube sampling
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
-- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover
+- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover; covariance shrinkage
 - expected utility and cumulative prospect theory calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

{funcsim-0.2.4 → funcsim-0.2.5}/README.md

@@ -9,7 +9,7 @@ Features:
 - stratified/Latin hypercube sampling
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
-- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover
+- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover; covariance shrinkage
 - expected utility and cumulative prospect theory calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

{funcsim-0.2.4 → funcsim-0.2.5}/funcsim/__init__.py

@@ -46,6 +46,6 @@ def version():
     Returns
     -------
     str
-        The version string of the package (e.g., '0.2.4').
+        The version string of the package (e.g., '0.2.5').
     """
-    return "0.2.4"
+    return "0.2.5"

{funcsim-0.2.4 → funcsim-0.2.5}/funcsim/dependence.py

@@ -2,7 +2,7 @@ import math
 import numpy as np
 import pandas as pd
 from scipy import stats
-from typing import Generator, Optional, Tuple
+from typing import Generator, Optional, Sequence, Tuple
 import warnings
 from . import conversions
 from . import copfit
@@ -284,10 +284,12 @@ class MvKde():
 
 class MvNorm():
     """
-    A multivariate normal distribution object. A vector of means
-    and a covariance matrix are computed from the input data.  If the sample
-    covariance matrix is not positive definite, the Higham
-    method is used to calculate the nearest positive definite matrix.
+    A multivariate normal distribution object.  Constructed from data, a
+    vector of means and a covariance matrix are computed from the input.
+    Constructed with :meth:`from_params`, the mean vector and covariance
+    matrix are supplied directly.  Either way, if the covariance matrix is
+    not positive definite, the Higham method is used to calculate the
+    nearest positive definite matrix.
 
     Parameters
     ----------
@@ -323,10 +325,80 @@ class MvNorm():
             swp = shapiro.swtest(self._data[:, k])[1]
             if not swp > 0.05:
                 msg = (f"variable '{self._names[k]}' may not be "
-                       f" normally distributed. (Shapiro-Wilk p-value"
+                       f"normally distributed. (Shapiro-Wilk p-value"
                        f"={swp:.3f})")
                 warnings.warn(msg, UserWarning)
 
+    @classmethod
+    def from_params(cls,
+                    mu: conversions.VectorLike,
+                    sigma: conversions.ArrayLike,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "MvNorm":
+        """
+        Create a multivariate normal distribution object from a mean vector
+        and a covariance matrix, rather than from data.
+
+        Parameters
+        ----------
+        mu : VectorLike
+            Mean vector of length K.
+        sigma : ArrayLike
+            K-by-K covariance matrix (a nested list is also accepted).  It
+            must be symmetric.  If it is not positive definite, the nearest
+            positive definite matrix (Higham, 1988) is substituted with a
+            warning.
+        names : sequence of str, optional
+            Variable names, length K.  If omitted, the index of `mu` (if it
+            is a pandas Series) or the column labels of `sigma` (if it is a
+            pandas DataFrame) are used; otherwise the variables are named
+            'v0', 'v1', ....
+
+        Returns
+        -------
+        MvNorm
+            A distribution object whose :meth:`draw` method returns joint
+            draws with the given means and covariances.
+
+        Notes
+        -----
+        No normality check is performed, since there are no data to check.
+
+        Examples
+        --------
+        >>> dist = fs.MvNorm.from_params([3.0, 4.0], [[1.0, 0.5], [0.5, 1.0]])
+        """
+        muA = np.asarray(conversions.vlToArray(mu), dtype=float)
+        if isinstance(sigma, (list, tuple)):
+            sigmaA = np.asarray(sigma, dtype=float)
+        else:
+            sigmaA = np.asarray(conversions.alToArray(sigma), dtype=float)
+        K = muA.shape[0]
+        if sigmaA.shape != (K, K):
+            raise ValueError(f"sigma must be {K}-by-{K} to match mu; "
+                             f"got shape {sigmaA.shape}")
+        if not np.allclose(sigmaA, sigmaA.T):
+            raise ValueError("sigma must be symmetric")
+        if names is not None:
+            nms = pd.Index(list(names))
+        elif isinstance(mu, pd.Series):
+            nms = pd.Index(mu.index)
+        elif isinstance(sigma, pd.DataFrame):
+            nms = pd.Index(sigma.columns)
+        else:
+            nms = pd.Index([f"v{k}" for k in range(K)])
+        if len(nms) != K:
+            raise ValueError(f"names must have length {K}; got {len(nms)}")
+
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._names = nms
+        (obj._M, obj._K) = (0, K)
+        obj._mu = muA
+        obj._sigma = nearby.nearestpd(sigmaA)
+        obj._A = np.linalg.cholesky(obj._sigma)
+        return obj
+
     def draw(self,
              ugen: Generator[float, None, None]
              ) -> pd.Series:
@@ -344,9 +416,9 @@ class MvNorm():
             A pandas Series representing a joint draw from the multivariate
             normal distribution.  The index values are the variable names,
             and the values are the random values.  If no variable names were
-            provided in the input data,
-            the variables will be named 'v0', 'v1', ..., reflecting the
-            order of the columns in the input data.
+            provided (as column labels of the input data, or through the
+            `names` argument of :meth:`from_params`), the variables are
+            named 'v0', 'v1', ..., in column order.
         """
         uvec = [next(ugen) for i in range(self._K)]
         retA = self._mu + np.dot(self._A, stats.norm.ppf(uvec))

{funcsim-0.2.4 → funcsim-0.2.5}/funcsim/nearby.py

@@ -72,7 +72,7 @@ def nearestpd(array):
 
     if is_positive_definite(A3):
         msg = ("Higham's (1988) first method was employed to compute "
-               "the pos. def. matrix nearest to the sample covariance matrix.")
+               "the positive definite matrix nearest to the input matrix.")
         warnings.warn(msg, UserWarning)
         return repackage(array, A3)
 
@@ -94,6 +94,6 @@ def nearestpd(array):
         A3 += Id * (-mineig * k ** 2 + spacing)
         k += 1
     msg = ("Higham's (1988) second method was employed to compute "
-            "the pos. def. matrix nearest to the sample covariance matrix.")
+           "the positive definite matrix nearest to the input matrix.")
     warnings.warn(msg, UserWarning)
     return repackage(array, A3)

{funcsim-0.2.4 → funcsim-0.2.5}/funcsim/shrinkage.py

@@ -6,6 +6,7 @@ Genetics and Molecular Biology//, vol 4(2005), issue 1.
 """
 
 import itertools
+from typing import Tuple, Union
 import numpy as np
 import pandas as pd
 import xarray as xr
@@ -207,7 +208,10 @@ def _target_f(x):
 
 
 def shrink(data: conversions.ArrayLike,
-           target: str ) -> conversions.ArrayLike:
+           target: str,
+           return_intensity: bool = False
+           ) -> Union[conversions.ArrayLike,
+                      Tuple[conversions.ArrayLike, float]]:
     """
     Covariance shrinkage estimator.
 
@@ -229,11 +233,18 @@ def shrink(data: conversions.ArrayLike,
         Targets 'B', 'E', and 'F' originate in Ledoit and Wolf (2003,
         2004).  The shrinkage intensity is estimated analytically in each
         case.
+    return_intensity : bool, optional
+        If True, also return the estimated shrinkage intensity.  Default is
+        False.
 
     Returns
     -------
-    ArrayLike
-        The estimated covariance matrix, with a type matching the data array
+    ArrayLike or tuple
+        The estimated covariance matrix, with a type matching the data
+        array.  If `return_intensity` is True, a tuple ``(sigma, lam)``,
+        where ``lam`` is the shrinkage intensity, a float in [0, 1]: 0
+        leaves the sample covariance matrix unchanged and 1 replaces it
+        with the target.
 
     Raises
     ------
@@ -259,26 +270,30 @@ def shrink(data: conversions.ArrayLike,
                   'E': _target_e,
                   'F': _target_f}
 
-    sig = target_map[target](a_np)[0]
+    sig, lam = target_map[target](a_np)
 
     # return the same type of array that was passed.  the result is a
     # p-by-p covariance matrix, so both axes are labeled with the
     # variable (column) labels of the input, not the observation index
     if isinstance(data, pd.DataFrame):
-        df = pd.DataFrame(data=sig, index=data.columns, columns=data.columns)
-        return df
+        result = pd.DataFrame(data=sig, index=data.columns,
+                              columns=data.columns)
     elif isinstance(data, xr.DataArray):
         coldim = str(data.dims[-1])
         if coldim in data.coords:
             varnames = np.asarray(data.coords[coldim].values)
         else:
             varnames = np.arange(sig.shape[0])
-        da = xr.DataArray(sig,
-                          dims=(coldim, coldim + "_"),
-                          coords={coldim: varnames, coldim + "_": varnames})
-        return da
+        result = xr.DataArray(sig,
+                              dims=(coldim, coldim + "_"),
+                              coords={coldim: varnames,
+                                      coldim + "_": varnames})
     else:
-        return sig
+        result = sig
+
+    if return_intensity:
+        return result, float(lam)
+    return result
 
 
 if __name__ == '__main__':

{funcsim-0.2.4 → funcsim-0.2.5/funcsim.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.4
+Version: 0.2.5
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -54,7 +54,7 @@ Features:
 - stratified/Latin hypercube sampling
 - painless multi-core simulations
 - fitting and comparison of univariate distributions, kernel density estimates, and goodness-of-fit tests
-- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover
+- multivariate normal and KDE distributions; Gaussian, Student's t, Clayton, Gumbel, and Frank copulas (implemented natively, no additional packages required); Iman-Conover; covariance shrinkage
 - expected utility and cumulative prospect theory calculations
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

{funcsim-0.2.4 → funcsim-0.2.5}/setup.py

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