funcsim 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.4
+Version: 0.2.6
 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 (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
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

{funcsim-0.2.4 → funcsim-0.2.6}/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 (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
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

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

@@ -10,6 +10,8 @@ from .dependence import CopulaClayton
 from .dependence import CopulaGumbel
 from .dependence import CopulaFrank
 
+from .copcompare import copcompare
+
 from .imanconover import imanconover
 
 from .shrinkage import shrink
@@ -46,6 +48,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.6').
     """
-    return "0.2.4"
+    return "0.2.6"

funcsim-0.2.6/funcsim/copcompare.py

@@ -0,0 +1,116 @@
+"""
+Information-criteria comparison of funcsim's copula families.
+"""
+
+import math
+
+import numpy as np
+import pandas as pd
+
+from . import conversions
+from . import copfit
+from .dependence import (CopulaGauss, CopulaStudent, CopulaClayton,
+                         CopulaGumbel, CopulaFrank)
+
+
+def _fmt(x: float) -> str:
+    return f"{x:.3f}"
+
+
+def _rho_label(rho: np.ndarray) -> str:
+    # a scalar for two variables, otherwise just the matrix size
+    K = rho.shape[0]
+    if K == 2:
+        return f"rho={_fmt(rho[0, 1])}"
+    return f"rho: {K}x{K} matrix"
+
+
+def copcompare(udata: conversions.ArrayLike) -> pd.DataFrame:
+    """
+    Compare fits of funcsim's copula families to pseudo-observations.
+
+    Each family (Gaussian, Student's t, Clayton, Gumbel, Frank) is fitted
+    to `udata` exactly as the corresponding copula class would fit it, its
+    copula log-likelihood (the pseudo-likelihood of Genest, Ghoudi, and
+    Rivest, 1995) is evaluated at those fitted parameters, and the Akaike
+    and Bayesian information criteria are computed from it.
+
+    Parameters
+    ----------
+    udata : ArrayLike
+        Pseudo-observations (marginal CDF values) with variables in columns
+        and observations in rows; every value must lie in (0, 1).
+
+    Returns
+    -------
+    pd.DataFrame
+        One row per family, indexed by family name and sorted by BIC from
+        best (smallest) to worst, with columns ``parameters`` (the fitted
+        values as text), ``n_params``, ``loglik``, ``AIC``, and ``BIC``.
+
+    Notes
+    -----
+    The parameters are the ones the copula classes use: normal-scores
+    correlation for the Gaussian copula, Kendall's-tau inversion plus a
+    profile likelihood for the degrees of freedom for the Student's t copula,
+    and maximum pseudo-likelihood for the Archimedean families.  The
+    Gaussian and Student's t log-likelihoods are therefore evaluated at
+    moment-type estimates rather than at the exact maximum, so their
+    criteria are conservative by a small amount.  Standard information
+    criteria applied to pseudo-likelihoods are approximate (Grønneberg and
+    Hjort, 2014); treat differences of a few points as ties.  Warnings
+    issued while fitting a family (for example, negative dependence in data
+    handed to an Archimedean family that represents only positive
+    dependence) are passed through.
+
+    References
+    ----------
+    Genest, C., Ghoudi, K., & Rivest, L.-P. (1995). A semiparametric
+    estimation procedure of dependence parameters in multivariate families
+    of distributions. Biometrika, 82(3), 543-552.
+
+    Grønneberg, S., & Hjort, N. L. (2014). The copula information criteria.
+    Scandinavian Journal of Statistics, 41(2), 436-459.
+
+    Examples
+    --------
+    >>> table = fs.copcompare(uh)
+    >>> print(table.round(2))
+    """
+    u = conversions.alToArray(udata)
+    if u.ndim != 2 or u.shape[1] < 2:
+        raise ValueError("udata must have at least two columns (variables)")
+    (M, K) = u.shape
+    npair = K * (K - 1) // 2
+
+    def row(name, parameters, n_params, loglik):
+        return {"copula": name,
+                "parameters": parameters,
+                "n_params": n_params,
+                "loglik": loglik,
+                "AIC": 2.0 * n_params - 2.0 * loglik,
+                "BIC": n_params * math.log(M) - 2.0 * loglik}
+
+    cg = CopulaGauss(u)
+    rho_g = cg.rho.to_numpy()
+    ct = CopulaStudent(u)
+    rho_t = ct.rho.to_numpy()
+    cc = CopulaClayton(u)
+    cgu = CopulaGumbel(u)
+    cf = CopulaFrank(u)
+    uc = copfit._clipu(u)
+
+    rows = [
+        row("Gaussian", _rho_label(rho_g), npair,
+            copfit.gauss_loglik(rho_g, u)),
+        row("Student", f"{_rho_label(rho_t)}, nu={_fmt(ct.nu)}", npair + 1,
+            copfit.student_loglik(rho_t, ct.nu, u)),
+        row("Clayton", f"theta={_fmt(cc.theta)}", 1,
+            copfit.clayton_loglik(cc.theta, uc)),
+        row("Gumbel", f"theta={_fmt(cgu.theta)}", 1,
+            copfit.gumbel_loglik(cgu.theta, uc)),
+        row("Frank", f"theta={_fmt(cf.theta)}", 1,
+            copfit.frank_loglik(cf.theta, uc)),
+    ]
+    table = pd.DataFrame(rows).set_index("copula")
+    return table.sort_values("BIC")

{funcsim-0.2.4 → funcsim-0.2.6}/funcsim/copfit.py

@@ -267,6 +267,31 @@ def fit_frank(u: np.ndarray) -> Tuple[float, float, bool]:
     return (theta, tb, False)
 
 
+def gauss_loglik(R: np.ndarray, u: np.ndarray) -> float:
+    # total Gaussian copula log-density over the rows of u for the
+    # correlation matrix R:
+    # log c(u) = -0.5 log|R| - 0.5 z' (R^-1 - I) z, with z = Phi^-1(u)
+    uc = _clipu(u)
+    z = stats.norm.ppf(uc)
+    (M, d) = z.shape
+    (sign, logdet) = np.linalg.slogdet(R)
+    if sign <= 0:
+        raise ValueError("R must be positive definite")
+    quad = np.einsum("ij,jk,ik->i", z, np.linalg.inv(R) - np.eye(d), z)
+    return float(-0.5 * M * logdet - 0.5 * np.sum(quad))
+
+
+def student_loglik(R: np.ndarray, nu: float, u: np.ndarray) -> float:
+    # total Student's t copula log-density over the rows of u for the
+    # correlation matrix R and degrees of freedom nu:
+    # log c(u) = log t_{nu,R}(x) - sum_k log t_nu(x_k), with x = t_nu^-1(u)
+    uc = _clipu(u)
+    x = stats.t.ppf(uc, df=nu)
+    d = R.shape[0]
+    joint = stats.multivariate_t(loc=np.zeros(d), shape=R, df=nu).logpdf(x)
+    return float(np.sum(joint) - np.sum(stats.t.logpdf(x, df=nu)))
+
+
 def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
     # fit a Student's t copula; returns (correlation matrix, deg. of freedom).
     # stage 1: pairwise Kendall's tau -> rho_ij = sin(pi tau_ij / 2),
@@ -281,17 +306,12 @@ def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
     R = R / np.outer(s, s)  # renormalize to unit diagonal
     np.fill_diagonal(R, 1.0)
 
-    mvt_dim = R.shape[0]
-
     def negll(lognu):
         nu = math.exp(lognu)
         try:
             with np.errstate(divide="ignore", invalid="ignore",
                              over="ignore"):
-                x = stats.t.ppf(uc, df=nu)
-                ll = (stats.multivariate_t(loc=np.zeros(mvt_dim), shape=R,
-                                           df=nu).logpdf(x).sum()
-                      - stats.t.logpdf(x, df=nu).sum())
+                ll = student_loglik(R, nu, uc)
         except Exception:
             return np.inf
         return -ll if np.isfinite(ll) else np.inf

{funcsim-0.2.4 → funcsim-0.2.6}/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
@@ -24,6 +24,75 @@ def _checkcov(cov, name):
     return cov
 
 
+def _cop_names(K: int,
+               names: Optional[Sequence[str]],
+               source: Optional[pd.Index] = None,
+               ) -> pd.Index:
+    # variable names for a copula built from parameters rather than data:
+    # the explicit `names` if given, else the labels carried by the
+    # parameter object (`source`, e.g. a DataFrame's columns), else v0, v1, ...
+    if names is not None:
+        nms = pd.Index(list(names))
+    elif source is not None:
+        nms = pd.Index(source)
+    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)}")
+    return nms
+
+
+def _corr_from_params(rho: conversions.ArrayLike) -> np.ndarray:
+    # validate a user-supplied correlation matrix for an elliptical copula:
+    # square, symmetric, unit diagonal.  If it is not positive definite the
+    # nearest positive definite matrix (Higham, 1988) is substituted and
+    # renormalized to a unit diagonal
+    if isinstance(rho, (list, tuple)):
+        R = np.asarray(rho, dtype=float)
+    else:
+        R = np.asarray(conversions.alToArray(rho), dtype=float)
+    if R.ndim != 2 or R.shape[0] != R.shape[1]:
+        raise ValueError(f"rho must be a square matrix; got shape {R.shape}")
+    if not np.allclose(R, R.T):
+        raise ValueError("rho must be symmetric")
+    if not np.allclose(np.diag(R), 1.0):
+        raise ValueError("rho must have ones on its diagonal")
+    Rpd = nearby.nearestpd(0.5 * (R + R.T))
+    s = np.sqrt(np.diag(Rpd))
+    Rn = Rpd / np.outer(s, s)
+    np.fill_diagonal(Rn, 1.0)
+    Rn = 0.5 * (Rn + Rn.T)
+    # Higham's projection of an indefinite matrix has a zero eigenvalue at
+    # machine precision, and rescaling can push it slightly negative, so the
+    # Cholesky factorization used for draws may fail.  Shrink toward the
+    # identity by the smallest power of ten that restores positive
+    # definiteness; the convex combination keeps the unit diagonal exactly
+    Id = np.eye(R.shape[0])
+    candidates = ((1.0 - eps) * Rn + eps * Id
+                  for eps in (0.0, *(10.0 ** p for p in range(-14, -3))))
+    Rout = next(filter(nearby.is_positive_definite, candidates), None)
+    if Rout is None:
+        raise ValueError("rho could not be repaired to a positive definite "
+                         "correlation matrix")
+    return Rout
+
+
+def _param_labels(rho: conversions.ArrayLike) -> Optional[pd.Index]:
+    # column labels carried by a parameter matrix, if any
+    if isinstance(rho, pd.DataFrame):
+        return rho.columns
+    return None
+
+
+def _positive_scalar(x: float, what: str, minimum: float = 0.0) -> float:
+    # validate a scalar copula parameter that must exceed `minimum`
+    xf = float(x)
+    if not (math.isfinite(xf) and xf > minimum):
+        raise ValueError(f"{what} must be a finite number greater than "
+                         f"{minimum}; got {x}")
+    return xf
+
+
 def _rand_int(u, M):
     # given a standard uniform draw "u", select a
     # random integer from a length "M" sequece: 0, 1, ..., M-1
@@ -284,10 +353,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 +394,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 +485,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))
@@ -410,6 +551,57 @@ class CopulaGauss():
         # cholesky decomposition of the correlation matrix, for draws
         self._A = np.linalg.cholesky(self._rho)
 
+    @classmethod
+    def from_params(cls,
+                    rho: conversions.ArrayLike,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "CopulaGauss":
+        """
+        Create a Gaussian copula object from a correlation matrix, rather
+        than from pseudo-observations.
+
+        Parameters
+        ----------
+        rho : ArrayLike
+            K-by-K correlation matrix (a nested list is also accepted).  It
+            must be symmetric with ones on its diagonal.  If it is not
+            positive definite, the nearest positive definite matrix
+            (Higham, 1988) is substituted and rescaled to a unit diagonal.
+        names : sequence of str, optional
+            Variable names, length K.  If omitted, the column labels of
+            `rho` (if it is a pandas DataFrame) are used; otherwise the
+            variables are named 'v0', 'v1', ....
+
+        Returns
+        -------
+        CopulaGauss
+            A copula object whose :meth:`draw` method returns joint standard
+            uniform draws with the given Gaussian dependence.
+
+        Examples
+        --------
+        >>> cop = fs.CopulaGauss.from_params([[1.0, 0.9], [0.9, 1.0]])
+        """
+        R = _corr_from_params(rho)
+        K = R.shape[0]
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._z = None
+        obj._names = _cop_names(K, names, _param_labels(rho))
+        (obj._M, obj._K) = (0, K)
+        obj._rho = R
+        obj._A = np.linalg.cholesky(obj._rho)
+        return obj
+
+    @property
+    def rho(self) -> pd.DataFrame:
+        """
+        The copula's correlation matrix parameter, as a DataFrame whose
+        index and columns are the variable names.
+        """
+        return pd.DataFrame(self._rho.copy(), index=self._names,
+                            columns=self._names)
+
     def draw(self,
              ugen: Generator[float, None, None]
              ) -> pd.Series:
@@ -480,6 +672,66 @@ class CopulaStudent():
         # cholesky decomposition of the correlation matrix, for draws
         self._A = np.linalg.cholesky(self._rho)
 
+    @classmethod
+    def from_params(cls,
+                    rho: conversions.ArrayLike,
+                    nu: float,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "CopulaStudent":
+        """
+        Create a Student's t copula object from a correlation matrix and a
+        degrees-of-freedom parameter, rather than from pseudo-observations.
+
+        Parameters
+        ----------
+        rho : ArrayLike
+            K-by-K correlation matrix (a nested list is also accepted).  It
+            must be symmetric with ones on its diagonal.  If it is not
+            positive definite, the nearest positive definite matrix
+            (Higham, 1988) is substituted and rescaled to a unit diagonal.
+        nu : float
+            Degrees of freedom, greater than zero.  As `nu` grows the copula
+            approaches the Gaussian copula with the same `rho`.
+        names : sequence of str, optional
+            Variable names, length K.  If omitted, the column labels of
+            `rho` (if it is a pandas DataFrame) are used; otherwise the
+            variables are named 'v0', 'v1', ....
+
+        Returns
+        -------
+        CopulaStudent
+            A copula object whose :meth:`draw` method returns joint standard
+            uniform draws with the given Student's t dependence.
+
+        Examples
+        --------
+        >>> cop = fs.CopulaStudent.from_params([[1.0, 0.9], [0.9, 1.0]], nu=4)
+        """
+        R = _corr_from_params(rho)
+        K = R.shape[0]
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._names = _cop_names(K, names, _param_labels(rho))
+        (obj._M, obj._K) = (0, K)
+        obj._rho = R
+        obj._nu = _positive_scalar(nu, "nu")
+        obj._A = np.linalg.cholesky(obj._rho)
+        return obj
+
+    @property
+    def rho(self) -> pd.DataFrame:
+        """
+        The copula's correlation matrix parameter, as a DataFrame whose
+        index and columns are the variable names.
+        """
+        return pd.DataFrame(self._rho.copy(), index=self._names,
+                            columns=self._names)
+
+    @property
+    def nu(self) -> float:
+        """The copula's degrees-of-freedom parameter."""
+        return float(self._nu)
+
     def draw(self,
              ugen: Generator[float, None, None]
              ) -> pd.Series:
@@ -565,6 +817,53 @@ class CopulaClayton():
                           f"representation for your data.",
                           UserWarning)
 
+    @classmethod
+    def from_params(cls,
+                    theta: float,
+                    K: int = 2,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "CopulaClayton":
+        """
+        Create a Clayton copula object from its dependence parameter,
+        rather than from pseudo-observations.
+
+        Parameters
+        ----------
+        theta : float
+            Dependence parameter, greater than zero.  Kendall's tau is theta / (theta + 2).
+        K : int, optional
+            Number of variables.  Default is 2.  Ignored when `names` is
+            given, in which case K is the number of names.
+        names : sequence of str, optional
+            Variable names.  If omitted, the variables are named 'v0',
+            'v1', ....
+
+        Returns
+        -------
+        CopulaClayton
+            A copula object whose :meth:`draw` method returns joint standard
+            uniform draws with the given Clayton dependence.
+
+        Examples
+        --------
+        >>> cop = fs.CopulaClayton.from_params(theta=2.0)
+        """
+        th = _positive_scalar(theta, "theta", 0.0)
+        k = len(names) if names is not None else int(K)
+        if k < 2:
+            raise ValueError("a copula needs at least two variables")
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._names = _cop_names(k, names)
+        (obj._M, obj._K) = (0, k)
+        obj._theta = th
+        return obj
+
+    @property
+    def theta(self) -> float:
+        """The copula's dependence parameter."""
+        return float(self._theta)
+
     def _Ftilde(self, t):
         return (1.0 + t)**(-1.0 / self._theta)
 
@@ -655,6 +954,53 @@ class CopulaGumbel():
                           f"representation for your data.",
                           UserWarning)
 
+    @classmethod
+    def from_params(cls,
+                    theta: float,
+                    K: int = 2,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "CopulaGumbel":
+        """
+        Create a Gumbel copula object from its dependence parameter,
+        rather than from pseudo-observations.
+
+        Parameters
+        ----------
+        theta : float
+            Dependence parameter, greater than one (one is independence, which this sampler cannot represent).  Kendall's tau is 1 - 1 / theta.
+        K : int, optional
+            Number of variables.  Default is 2.  Ignored when `names` is
+            given, in which case K is the number of names.
+        names : sequence of str, optional
+            Variable names.  If omitted, the variables are named 'v0',
+            'v1', ....
+
+        Returns
+        -------
+        CopulaGumbel
+            A copula object whose :meth:`draw` method returns joint standard
+            uniform draws with the given Gumbel dependence.
+
+        Examples
+        --------
+        >>> cop = fs.CopulaGumbel.from_params(theta=2.0)
+        """
+        th = _positive_scalar(theta, "theta", 1.0)
+        k = len(names) if names is not None else int(K)
+        if k < 2:
+            raise ValueError("a copula needs at least two variables")
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._names = _cop_names(k, names)
+        (obj._M, obj._K) = (0, k)
+        obj._theta = th
+        return obj
+
+    @property
+    def theta(self) -> float:
+        """The copula's dependence parameter."""
+        return float(self._theta)
+
     def _Ftilde(self, t):
         return math.exp(-(t**(1.0/self._theta)))
 
@@ -743,6 +1089,53 @@ class CopulaFrank():
                           f"representation for your data.",
                           UserWarning)
 
+    @classmethod
+    def from_params(cls,
+                    theta: float,
+                    K: int = 2,
+                    names: Optional[Sequence[str]] = None,
+                    ) -> "CopulaFrank":
+        """
+        Create a Frank copula object from its dependence parameter,
+        rather than from pseudo-observations.
+
+        Parameters
+        ----------
+        theta : float
+            Dependence parameter, greater than zero.  Kendall's tau is 1 - 4 (1 - D_1(theta)) / theta, with D_1 the first Debye function.
+        K : int, optional
+            Number of variables.  Default is 2.  Ignored when `names` is
+            given, in which case K is the number of names.
+        names : sequence of str, optional
+            Variable names.  If omitted, the variables are named 'v0',
+            'v1', ....
+
+        Returns
+        -------
+        CopulaFrank
+            A copula object whose :meth:`draw` method returns joint standard
+            uniform draws with the given Frank dependence.
+
+        Examples
+        --------
+        >>> cop = fs.CopulaFrank.from_params(theta=5.0)
+        """
+        th = _positive_scalar(theta, "theta", 0.0)
+        k = len(names) if names is not None else int(K)
+        if k < 2:
+            raise ValueError("a copula needs at least two variables")
+        obj = cls.__new__(cls)
+        obj._data = None
+        obj._names = _cop_names(k, names)
+        (obj._M, obj._K) = (0, k)
+        obj._theta = th
+        return obj
+
+    @property
+    def theta(self) -> float:
+        """The copula's dependence parameter."""
+        return float(self._theta)
+
     def draw(self,
              ugen: Generator[float, None, None]
              ) -> pd.Series:

{funcsim-0.2.4 → funcsim-0.2.6}/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.6}/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.6/funcsim.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.4
+Version: 0.2.6
 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 (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
 - plotly-based fan charts and diagnostic plots
 - highly flexible, and as simple as possible (but no more)

{funcsim-0.2.4 → funcsim-0.2.6}/funcsim.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ setup.py
 funcsim/__init__.py
 funcsim/addist.py
 funcsim/conversions.py
+funcsim/copcompare.py
 funcsim/copfit.py
 funcsim/core.py
 funcsim/cpt.py

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

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