funcsim 0.2.3__tar.gz → 0.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.3
+Version: 0.2.5
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -46,35 +46,43 @@ Dynamic: summary
 # funcsim
 Lightweight, functional stochastic simulation
 
+Documentation: https://funcsim.readthedocs.io/
+
 Features:
-- cross-sectional and recursive dynamic simulations
-- pseudo-random numbers (so that results are comparable across multiple runs or scenarios)
+- static (cross-sectional) and recursive-dynamic simulations from a single user-written function
+- pseudo-random numbers with an explicit seed (so that results are reproducible and comparable across runs or scenarios)
 - 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; 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)
 - functional paradigm
 
-Developed using:
-- python >= 3.10
-- numpy 2.2.0
-- scipy 1.16.0
-- pandas 2.2.0 (pandas 2.2+ and 3.x are both supported)
-- xarray 2025.4.0
-
-Copulas (Gaussian, Student's t, Clayton, Gumbel, and Frank) are supported
-natively; no additional packages are required.
+Requirements:
+- python >= 3.11
+- numpy >= 2.2.0
+- scipy >= 1.16.0
+- pandas >= 2.2.0 (pandas 2.2+ and 3.x are both supported)
+- xarray >= 2025.4.0
 
-For optional functionality, additinoal packages are needed:
-- plotting: plotly
+For optional functionality, additional packages are needed:
+- plotting: plotly (`pip install "funcsim[plotting]"`); kaleido for static image export
 
-Additionally, to run the demos, run tests, and build docs:
+Additionally, to run the tests and build the docs:
 - pytest
-- sphinx, sphinx-autodoc-typehints
+- sphinx, sphinx-autodoc-typehints (`pip install "funcsim[docs]"`)
+
+### installation
+```bash
+pip install funcsim
+```
 
 ### building html docs
 From the top-level funcsim directory...
 ```bash
-sphinx-build -b html docs/source/ docs/build/
+sphinx-build -W -b html docs/source/ docs/build/
 ```
 
 ### running tests

funcsim-0.2.5/README.md

@@ -0,0 +1,47 @@
+# funcsim
+Lightweight, functional stochastic simulation
+
+Documentation: https://funcsim.readthedocs.io/
+
+Features:
+- static (cross-sectional) and recursive-dynamic simulations from a single user-written function
+- pseudo-random numbers with an explicit seed (so that results are reproducible and comparable across runs or scenarios)
+- 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; 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)
+- functional paradigm
+
+Requirements:
+- python >= 3.11
+- numpy >= 2.2.0
+- scipy >= 1.16.0
+- pandas >= 2.2.0 (pandas 2.2+ and 3.x are both supported)
+- xarray >= 2025.4.0
+
+For optional functionality, additional packages are needed:
+- plotting: plotly (`pip install "funcsim[plotting]"`); kaleido for static image export
+
+Additionally, to run the tests and build the docs:
+- pytest
+- sphinx, sphinx-autodoc-typehints (`pip install "funcsim[docs]"`)
+
+### installation
+```bash
+pip install funcsim
+```
+
+### building html docs
+From the top-level funcsim directory...
+```bash
+sphinx-build -W -b html docs/source/ docs/build/
+```
+
+### running tests
+From the top-level funcsim directory...
+```bash
+python3 -m pytest
+```

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

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

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/core.py

@@ -183,17 +183,20 @@ def simulate(f: Callable[[Generator[int, float, None],
 
     Parameters
     ----------
-    f : function
-        Function that performs a single trial in a static simulation or a s
-        single step through time in a recursive dynamic simulation.  Should take
-        'ugen' as a first argument in either case, where 'ugen' will be a
-        generator that emits standard uniform draws (or standard normal draws,
-        if `stdnorm` is True) that will be passed to f by ``simulate``.
-        In the case of a recursive dynamic simulation that employs past values,
-        f should take 'data' as a second argument, where this will be a type of
-        array that is also provided by ``simulate.`` This function should return
-        a dict with variable names (as strings) as keys and values for those
-        variables (as floats) as values.
+    f : callable
+        Function that performs a single trial in a static simulation, or a
+        single step through time in a recursive-dynamic simulation.  Its first
+        argument (conventionally ``ugen``) receives a generator that emits
+        independent standard uniform draws (or standard normal draws, if
+        `stdnorm` is True); obtain each draw with ``next(ugen)``.  If `f`
+        takes a second argument (conventionally ``hist``), it receives a
+        per-trial history object whose ``recall(varname, lag)`` method returns
+        the value of a variable `lag` steps earlier; see
+        :class:`funcsim.rdarrays.RDdata`.  `f` must return a dict with
+        variable names (strings) as keys and floats as values.  The number of
+        times `f` calls ``next(ugen)`` must be the same in every trial and
+        step, because draws are pre-allocated across trials for stratified
+        sampling.
     ntrials : int, optional
         The number of trials to perform.  Default is 500.
     nsteps : int, optional
@@ -207,12 +210,14 @@ def simulate(f: Callable[[Generator[int, float, None],
         Use multiple processes/cores for the simulation. Default is False.
         When True, `f` must be picklable (e.g., defined at the top level of
         a module, not inside another function), because worker processes
-        are spawned on most platforms.
+        are spawned on most platforms.  For the same reason, a script that
+        calls ``simulate(..., multi=True)`` must guard the call with
+        ``if __name__ == "__main__":``.
     seed : int, optional
         Seed for pseudo-random number generation. Default is 6.
-    stdnorm : book, optional
-        If False, ``next(draw)`` within `trialf` will return standard uniform
-        random draws. If True, ``next(draw)`` will return standard normal draws.
+    stdnorm : bool, optional
+        If False, ``next(ugen)`` within `f` returns standard uniform random
+        draws. If True, ``next(ugen)`` returns standard normal draws.
         Default is False.
     sampling : {'lh', 'mc'}, optional
         If 'lh', Latin Hypercube sampling is employed.  If 'mc', simple
@@ -221,7 +226,22 @@ def simulate(f: Callable[[Generator[int, float, None],
     Returns
     -------
     xarray.DataArray
-        3-D xarray.DataArray with dimensions 'trials', 'variables', and 'steps'.
+        3-D xarray.DataArray with dimensions 'trials', 'variables', and
+        'steps'.  The 'steps' coordinate continues the index of `hist0` (or
+        counts from 0 when `hist0` is not given), and includes any historical
+        steps from `hist0` ahead of the `nsteps` simulated steps.
+
+    Raises
+    ------
+    ValueError
+        If `hist0` is malformed, `f` is not callable or takes more than two
+        arguments, `f` does not return a dict keyed by strings, or `sampling`
+        is not one of 'lh' or 'mc'.
+    RuntimeError
+        If `f` consumes a different number of draws in some trial or step
+        than it did when first probed.
+    funcsim.rdarrays.MissingValue
+        If `f` recalls a lagged value that is not available.
     """
     if hist0 is not None:
         _checkhist0(hist0)

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/cpt.py

@@ -315,7 +315,7 @@ def cpt(utilFunc: Callable,
         Sequence of possible stochastic outcomes.
     refOutcome : float
         Reference point for gains and losses.
-    probabilities : float or Iterable, optional
+    probabilities : Iterable of float, optional
         Probabilities for each outcome. If None, outcomes are assumed
         equally likely.
     precision : float, optional
@@ -436,7 +436,7 @@ def cptBV(outcomes: Iterable,
         Sequence of possible stochastic outcomes.
     refOutcome : float
         Reference point for gains and losses.
-    probabilities : float or Iterable, optional
+    probabilities : Iterable of float, optional
         Probabilities for each outcome. If None, outcomes are assumed equally
         likely.
 

{funcsim-0.2.3 → 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
@@ -191,12 +191,17 @@ class MvKde():
     Parameters
     ----------
     data : ArrayLike
-        Input data array of with variables in columns and observations
+        Input data array with variables in columns and observations
         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'.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K + 1 values from ``ugen``, where K
+    is the number of variables.
     """
     def __init__(self,
                  data: conversions.ArrayLike,
@@ -279,16 +284,24 @@ 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
     ----------
     data : ArrayLike
-        Input data array of with variables in columns and observations
+        Input data array with variables in columns and observations
         in rows.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K values from ``ugen``, where K is
+    the number of variables.  A warning is issued for any variable whose
+    Shapiro-Wilk test rejects normality at the 5% level.
     """
     def __init__(self,
                  data: conversions.ArrayLike,
@@ -312,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:
@@ -330,11 +413,12 @@ class MvNorm():
         Returns
         -------
         pd.Series
-            A pandas Series representing a joint draw from the KDE.  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
-            oreder of the columns in the input data.
+            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 (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))
@@ -353,10 +437,15 @@ class CopulaGauss():
         columns and observations in rows.  That is, each column
         represents the result of applying the fitted CDF of some marginal
         distribution to the raw data for that variable.  The
-        values in each column should be in the range [0, 1]. The parameters
-        are fit using the method of moments.  If the sample covariance
-        matrix is not positive definite, the Higham method is used to
-        calculate the nearest positive definite matrix.
+        values in each column should be in the range (0, 1). The correlation
+        matrix is fit using the method of moments on the normal scores of
+        the pseudo-observations.  If it is not positive definite, the Higham
+        method is used to calculate the nearest positive definite matrix.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K values from ``ugen``, where K is
+    the number of variables.
     """
 
     def __init__(self,
@@ -412,7 +501,7 @@ class CopulaGauss():
             standard uniform draws are the values in the Series.
             If no variable names were provided in the input data,
             the variables will be named 'v0', 'v1', ..., reflecting the
-            oreder of the columns in the input data.
+            order of the columns in the input data.
 
         """
         uvec = [next(ugen) for i in range(self._K)]
@@ -432,9 +521,14 @@ class CopulaStudent():
         columns and observations in rows.  That is, each column
         represents the result of applying the fitted CDF of some marginal
         distribution to the raw data for that variable.  The
-        values in each column should be in the range [0, 1]. The correlation
+        values in each column should be in the range (0, 1). The correlation
         matrix is fit by pairwise Kendall's-tau inversion, and the degrees
-        of freedom are then fit by profile maximum likelihood.
+        of freedom are then fit by profile maximum pseudo-likelihood.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K + 1 values from ``ugen``, where K
+    is the number of variables.
     """
 
     def __init__(self,
@@ -477,7 +571,7 @@ class CopulaStudent():
             standard uniform draws are the values in the Series.
             If no variable names were provided in the input data,
             the variables will be named 'v0', 'v1', ..., reflecting the
-            oreder of the columns in the input data.
+            order of the columns in the input data.
         
         """
         uvec = [next(ugen) for i in range(self._K)]
@@ -500,10 +594,18 @@ class CopulaClayton():
         columns and observations in rows.  That is, each column
         represents the result of applying the fitted CDF of some marginal
         distribution to the raw data for that variable.  The
-        values in each column should be in the range [0, 1]. Parameters are
-        fit using maximum likelihood.  This implementation accomodates
+        values in each column should be in the range (0, 1). The dependence
+        parameter theta is fit by maximum pseudo-likelihood, starting from
+        the Kendall's-tau inversion estimate.  This implementation accommodates
         only positive dependence, so the fitted value for theta is
         constrained to be > 0.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K + 1 values from ``ugen``, where K
+    is the number of variables.  If the data exhibit negative dependence
+    (mean pairwise Kendall's tau <= 0), theta is set to its minimum
+    (near independence) and a warning is issued.
     """
 
     def __init__(self,
@@ -525,7 +627,7 @@ class CopulaClayton():
         (self._theta, taub, clamped) = copfit.fit_clayton(self._data)
         if clamped:
             warnings.warn(f"The Clayton copula implementation in funcsim "
-                          f"accomodates only positive dependence, but the "
+                          f"accommodates only positive dependence, but the "
                           f"data exhibit negative dependence (mean pairwise "
                           f"Kendall's tau = {taub:.3f}).  A theta value of "
                           f"{copfit.THETA_MIN_CLAYTON} is being used rather "
@@ -557,7 +659,7 @@ class CopulaClayton():
             standard uniform draws are the values in the Series.
             If no variable names were provided in the input data,
             the variables will be named 'v0', 'v1', ..., reflecting the
-            oreder of the columns in the input data.
+            order of the columns in the input data.
         
         """
         # floor the gamma frailty: for large theta the shape parameter is
@@ -582,10 +684,18 @@ class CopulaGumbel():
         columns and observations in rows.  That is, each column
         represents the result of applying the fitted CDF of some marginal
         distribution to the raw data for that variable.  The
-        values in each column should be in the range [0, 1]. Parameters are
-        fit using maximum likelihood.  This implementation accomodates
+        values in each column should be in the range (0, 1). The dependence
+        parameter theta is fit by maximum pseudo-likelihood, starting from
+        the Kendall's-tau inversion estimate.  This implementation accommodates
         only positive dependence, so the fitted value for theta is
         constrained to be > 1.0.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K + 2 values from ``ugen``, where K
+    is the number of variables.  If the data exhibit negative dependence
+    (mean pairwise Kendall's tau <= 0), theta is set to its minimum
+    (near independence) and a warning is issued.
     """
 
     def __init__(self,
@@ -607,7 +717,7 @@ class CopulaGumbel():
         (self._theta, taub, clamped) = copfit.fit_gumbel(self._data)
         if clamped:
             warnings.warn(f"The Gumbel copula implementation in funcsim "
-                          f"accomodates only positive dependence, but the "
+                          f"accommodates only positive dependence, but the "
                           f"data exhibit negative dependence (mean pairwise "
                           f"Kendall's tau = {taub:.3f}).  A theta value of "
                           f"(approximately) 1.0 is being used rather than a "
@@ -639,7 +749,7 @@ class CopulaGumbel():
             standard uniform draws are the values in the Series.
             If no variable names were provided in the input data,
             the variables will be named 'v0', 'v1', ..., reflecting the
-            oreder of the columns in the input data.
+            order of the columns in the input data.
 
         """
         gamma = math.cos(0.5 * math.pi / self._theta)**self._theta
@@ -662,10 +772,18 @@ class CopulaFrank():
         columns and observations in rows.  That is, each column
         represents the result of applying the fitted CDF of some marginal
         distribution to the raw data for that variable.  The
-        values in each column should be in the range [0, 1]. Parameters are
-        fit using maximum likelihood.  This implementation accomodates
+        values in each column should be in the range (0, 1). The dependence
+        parameter theta is fit by maximum pseudo-likelihood, starting from
+        the Kendall's-tau inversion estimate.  This implementation accommodates
         only positive dependence, so the fitted value for theta is
         constrained to be > 0.
+
+    Notes
+    -----
+    Each call to :meth:`draw` consumes K + 2 values from ``ugen``, where K
+    is the number of variables.  If the data exhibit negative dependence
+    (mean pairwise Kendall's tau <= 0), theta is set to its minimum
+    (near independence) and a warning is issued.
     """
 
     def __init__(self,
@@ -687,7 +805,7 @@ class CopulaFrank():
         (self._theta, taub, clamped) = copfit.fit_frank(self._data)
         if clamped:
             warnings.warn(f"The Frank copula implementation in funcsim "
-                          f"accomodates only positive dependence, but the "
+                          f"accommodates only positive dependence, but the "
                           f"data exhibit negative dependence (mean pairwise "
                           f"Kendall's tau = {taub:.3f}).  A theta value of "
                           f"{copfit.THETA_MIN_FRANK} is being used rather "
@@ -716,7 +834,7 @@ class CopulaFrank():
             standard uniform draws are the values in the Series.
             If no variable names were provided in the input data,
             the variables will be named 'v0', 'v1', ..., reflecting the
-            oreder of the columns in the input data.
+            order of the columns in the input data.
         
         """
         # Generate d uniform random variables

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/distfit.py

@@ -414,7 +414,8 @@ def fit(data: conversions.VectorLike,
     scipydist : scipy.stats.rv_continuous
         The scipy.stats distribution object to fit (e.g., stats.norm).
     distName : str, optional
-        Name of the distribution. If None, the distribution's name is used.
+        Name recorded in the ``distName`` field of the result (for example,
+        the label used by ``compare``).  Default None.
     lowerBound : float, optional
         If given, the lower bound of the support of the fitted distribution
         is fixed at this value rather than estimated.  The distribution must
@@ -446,6 +447,8 @@ def fit(data: conversions.VectorLike,
             The frozen fitted distribution object.
         distName : str
             Name of the fitted distribution.
+        warnings : list
+            Warnings captured during fitting (empty for a clean fit).
 
     Raises
     ------

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/ecdfgof.py

@@ -118,10 +118,14 @@ def kstest(data: conversions.VectorLike,
     ----------
     data : VectorLike
         Sample data vector.
-    dist : str or frozen distribution object
-        Scipy distribution name or frozen distribution object.
+    dist : str, scipy.stats distribution, or frozen distribution
+        The hypothesized distribution: the name of a ``scipy.stats``
+        distribution (e.g., ``"norm"``), an unfrozen distribution object
+        (e.g., ``stats.norm``), or a frozen distribution (e.g.,
+        ``stats.norm(0.0, 1.0)``).
     args : tuple, optional
-        Parameters for the distribution if it is not a string.
+        Shape, location, and scale parameters, applied when `dist` is a name
+        or an unfrozen distribution.  Ignored for a frozen distribution.
     assume_sorted : bool, optional
         If True, assumes that `data` is already sorted.  Defaults to False.
 
@@ -146,10 +150,14 @@ def cvmtest(data: conversions.VectorLike,
     ----------
     data : VectorLike
         Sample data vector.
-    dist : str or frozen distribution object
-        Scipy distribution name or frozen distribution object.
+    dist : str, scipy.stats distribution, or frozen distribution
+        The hypothesized distribution: the name of a ``scipy.stats``
+        distribution (e.g., ``"norm"``), an unfrozen distribution object
+        (e.g., ``stats.norm``), or a frozen distribution (e.g.,
+        ``stats.norm(0.0, 1.0)``).
     args : tuple, optional
-        Parameters for the distribution if it is not a string.
+        Shape, location, and scale parameters, applied when `dist` is a name
+        or an unfrozen distribution.  Ignored for a frozen distribution.
     assume_sorted : bool, optional
         If True, assumes that `data` is already sorted.  Defaults to False.
 
@@ -173,10 +181,14 @@ def adtest(data: conversions.VectorLike,
     ----------
     data : VectorLike
         Sample data vector.
-    dist : str or frozen distribution object
-        Scipy distribution name or frozen distribution object.
+    dist : str, scipy.stats distribution, or frozen distribution
+        The hypothesized distribution: the name of a ``scipy.stats``
+        distribution (e.g., ``"norm"``), an unfrozen distribution object
+        (e.g., ``stats.norm``), or a frozen distribution (e.g.,
+        ``stats.norm(0.0, 1.0)``).
     args : tuple, optional
-        Parameters for the distribution if it is not a string.
+        Shape, location, and scale parameters, applied when `dist` is a name
+        or an unfrozen distribution.  Ignored for a frozen distribution.
     assume_sorted : bool, optional
         If True, assumes that `data` is already sorted.  Defaults to False.
 

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/eut.py

@@ -53,7 +53,7 @@ def eut(util: Callable[[float], float],
     Compute expected utility and certainty equivalent income.
 
     This can operate on an arbitrary utility function, numerically solving
-    for the certainty equivalent.  For isoelastic expected utiliy and
+    for the certainty equivalent.  For isoelastic expected utility and
     certainty equivalents, the function "eutIsoelastic" will be less
     likely to suffer from numerical problems.
 
@@ -74,7 +74,7 @@ def eut(util: Callable[[float], float],
         Named tuple with fields:
 
         ExpectedValue : float
-            The mean isoelastic utility of the outcomes.
+            The mean utility of the outcomes.
         CertaintyEquiv : float
             The certainty equivalent income.
     """

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/imanconover.py

@@ -40,12 +40,12 @@ def imanconover(spear: conversions.ArrayLike,
                 )-> pd.DataFrame:
 
     """
-    Induce a Spearman correlation stucture using the Iman & Conover method.
+    Induce a Spearman correlation structure using the Iman & Conover method.
 
     Parameters
     ----------
     spear : ArrayLike
-        Desired Spearman correlation matrix (must be symetric and
+        Desired Spearman correlation matrix (must be symmetric and
         positive definite).
     vectors : list of VectorLike
         List of vectors, each representing draws for one variable.
@@ -59,7 +59,7 @@ def imanconover(spear: conversions.ArrayLike,
     -------
     pandas.DataFrame
         DataFrame with one column for each vector/variable, where the
-        data refelct the desired Spearman correlation structure.
+        data reflect the desired Spearman correlation structure.
 
     References
     ----------

{funcsim-0.2.3 → 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.3 → funcsim-0.2.5}/funcsim/plotting.py

@@ -51,15 +51,18 @@ def fan(da: xr.DataArray,
     varname : str
         Name of the variable to plot from the "variables" dimension.
     filepath : str, optional
-        Path to save the chart. Supports HTML and image formats. Default None.
+        Path to save the chart.  A ``.html`` extension writes an interactive
+        HTML file; ``.png``, ``.jpg``, ``.jpeg``, ``.webp``, ``.svg``, and
+        ``.pdf`` write a static image, which requires the optional
+        ``kaleido`` package.  Default None (do not save).
     line_color : str, optional
         Color of the mean line. Default is 'blue'.
     title : str, optional
         Title for the figure. Default is "" (no title).
     width : int, optional
-        Width of the chart in pixels. Default is 800.
+        Width of the chart in pixels. Default is 750.
     height : int, optional
-        Height of the chart in pixels. Default is 500.
+        Height of the chart in pixels. Default is 400.
 
     Returns
     -------
@@ -244,12 +247,12 @@ def twofuncs(f0: Callable[[float], float],
         Label for the first function. Default is "f0".
     name1 : str, optional
         Label for the second function. Default is "f1".
-    title : str, optinal
-        Title for the top of the figure.  Defaults to None.
+    title : str, optional
+        Title for the figure. Default is "" (no title).
     width : int, optional
-        Width of the chart in pixels. Default is 800.
+        Width of the chart in pixels. Default is 750.
     height : int, optional
-        Height of the chart in pixels. Default is 500.
+        Height of the chart in pixels. Default is 400.
 
     Returns
     -------
@@ -309,9 +312,9 @@ def histpdf(data: conversions.VectorLike,
     title : str, optional
         Title for the figure. Default is "" (no title).
     width : int, optional
-        Width of the chart in pixels. Default is 800.
+        Width of the chart in pixels. Default is 750.
     height : int, optional
-        Height of the chart in pixels. Default is 500.
+        Height of the chart in pixels. Default is 400.
 
     Returns
     -------
@@ -389,7 +392,7 @@ def dblscat(a0: conversions.ArrayLike,
     title : str, optional
         Title for the figure. Default is "" (no title).
     width : int, optional
-        Width of the chart in pixels. Default is 800.
+        Width of the chart in pixels. Default is 500.
     height : int, optional
         Height of the chart in pixels. Default is 500.
 
@@ -530,8 +533,10 @@ def show(fig):
     """
     Flexibly display a plotly plot in a Jupyter notebook.
 
-    Invokes plotly's fig.show() with a `renderer` argument set to the value
-    in the environment variable FUNCSIM_PLOTLY_RENDERER.
+    Invokes plotly's ``fig.show()`` with a `renderer` argument set to the
+    value of the environment variable ``FUNCSIM_PLOTLY_RENDERER`` (for
+    example ``"notebook"``, ``"vscode"``, ``"browser"``, or ``"png"``).
+    If the variable is not set, plotly's default renderer is used.
 
     Parameters
     ----------

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/rdarrays.py

@@ -3,10 +3,21 @@ import xarray as xr
 
 
 class MissingValue(Exception):
+    """Raised by :meth:`RDdata.recall` when a requested value is unavailable."""
     pass
 
 
 class RDdata():
+    """
+    Per-trial history for a recursive-dynamic simulation.
+
+    ``simulate`` passes an instance of this class as the second argument
+    (conventionally ``hist``) to a step function that accepts two
+    arguments.  It holds the historical values supplied via ``hist0``
+    followed by the values the step function has returned so far in the
+    current trial.  Step functions should only call :meth:`recall`; the
+    class is not meant to be instantiated by users.
+    """
     # container for an np array with pre-allocated memory for future values
     # for a single trial in an RD sim
     def __init__(self, a, steps, namePositions):
@@ -48,7 +59,9 @@ class RDdata():
         varname : str
             Name of the variable to recall.
         lag : int, optional
-            Number of steps to lag (default is 0).
+            Number of steps to look back.  ``lag=1`` is the previous step
+            (the most recent value available while a step is being
+            computed).  Default is 0.
 
         Returns
         -------
@@ -73,7 +86,7 @@ class RDdata():
                                    f'simulation, no (non-NaN) value for the '
                                    f'variable "{varname}" with {lag} lag(s) is '
                                    f'available. Be sure that you passed a '
-                                   f'a "data0" array to "simulate" and that it '
+                                   f'"hist0" array to "simulate" and that it '
                                    f'contains this value.')
             else:
                 raise MissingValue(f'In time step {self._currStep} in the '

{funcsim-0.2.3 → funcsim-0.2.5}/funcsim/screen.py

@@ -351,8 +351,17 @@ def screen(data: conversions.VectorLike,
     Returns
     -------
     str
-        A formatted string summarizing the results of stationarity, 
+        A formatted string summarizing the results of stationarity,
         heteroskedasticity, autocorrelation, and randomness tests.
+
+    Notes
+    -----
+    Line A is an augmented Dickey-Fuller (ADF) test whose equation includes
+    a constant, so its alternative is stationarity around a constant
+    (possibly nonzero) mean.  Line B adds a linear time trend, so its
+    alternative is trend stationarity.  Lines C (White) and D (Ljung-Box)
+    are applied to the residuals from a regression of the series on the
+    observation number.  Lines E and F test the overall i.i.d. null.
     """
 
     if alpha <= 0 or alpha >= 1:
@@ -369,9 +378,13 @@ def screen(data: conversions.VectorLike,
     y_hat = X @ beta
     resid = y - y_hat
 
-    # ADF tests: line A has no deterministic terms; line B includes a
-    # constant and linear trend, so it is a genuine trend-stationarity test
-    p_adf = adf_test_no_const(seriesA, max_lag=2, n_sim=1000, seed=42)[1]
+    # ADF tests: line A includes a constant, so it tests for stationarity
+    # around a constant mean (a no-constant equation has zero-mean
+    # stationarity as its alternative, so it fails to reject the unit root,
+    # and the report warns, for an i.i.d. series whose mean is large
+    # relative to its standard deviation); line B includes a constant and
+    # a linear trend, so it is a genuine trend-stationarity test
+    p_adf = adf_test_with_const(seriesA, max_lag=2, n_sim=1000, seed=42)[1]
     p_adf_t = adf_test_const_trend(seriesA, max_lag=2, n_sim=1000, seed=42)[1]
 
     # White test for heteroskedasticity (constant is added inside

{funcsim-0.2.3 → 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.
 
@@ -216,22 +220,43 @@ def shrink(data: conversions.ArrayLike,
     data : ArrayLike
         Data array with variables in columns and observations in rows.
     target : str
-        Shrinkage target, one of: 'A', 'B', 'C', 'D', 'E', 'F'.  These
-        correspond to different shrinkage estimation methods as defined in
-        Shafer & Strimmer, "A shrinkage approach to large-scale covariance
-        matrix estimation and implications for Functional Genomics."
-        //Statistical Applications in Genetics and Molecular Biology//,
-        vol 4(2005), issue 1.
+        Shrinkage target, one of 'A' through 'F', following Table 2 of
+        Schafer and Strimmer (2005):
+
+        - 'A': diagonal, unit variance
+        - 'B': diagonal, common variance
+        - 'C': common variance and common covariance
+        - 'D': diagonal, unequal variance
+        - 'E': perfect positive correlation
+        - 'F': constant correlation
+
+        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
     ------
     ValueError
         If target is not one of: 'A', 'B', 'C', 'D', 'E', 'F'.
+
+    References
+    ----------
+    Schafer, J., & Strimmer, K. (2005). A shrinkage approach to large-scale
+    covariance matrix estimation and implications for functional genomics.
+    Statistical Applications in Genetics and Molecular Biology, 4(1),
+    Article 32.
     """
     if target not in ['A', 'B', 'C', 'D', 'E', 'F']:
         raise ValueError("target must be one of: A, B, C, D, E, F") 
@@ -245,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.3 → funcsim-0.2.5/funcsim.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.3
+Version: 0.2.5
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant
@@ -46,35 +46,43 @@ Dynamic: summary
 # funcsim
 Lightweight, functional stochastic simulation
 
+Documentation: https://funcsim.readthedocs.io/
+
 Features:
-- cross-sectional and recursive dynamic simulations
-- pseudo-random numbers (so that results are comparable across multiple runs or scenarios)
+- static (cross-sectional) and recursive-dynamic simulations from a single user-written function
+- pseudo-random numbers with an explicit seed (so that results are reproducible and comparable across runs or scenarios)
 - 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; 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)
 - functional paradigm
 
-Developed using:
-- python >= 3.10
-- numpy 2.2.0
-- scipy 1.16.0
-- pandas 2.2.0 (pandas 2.2+ and 3.x are both supported)
-- xarray 2025.4.0
-
-Copulas (Gaussian, Student's t, Clayton, Gumbel, and Frank) are supported
-natively; no additional packages are required.
+Requirements:
+- python >= 3.11
+- numpy >= 2.2.0
+- scipy >= 1.16.0
+- pandas >= 2.2.0 (pandas 2.2+ and 3.x are both supported)
+- xarray >= 2025.4.0
 
-For optional functionality, additinoal packages are needed:
-- plotting: plotly
+For optional functionality, additional packages are needed:
+- plotting: plotly (`pip install "funcsim[plotting]"`); kaleido for static image export
 
-Additionally, to run the demos, run tests, and build docs:
+Additionally, to run the tests and build the docs:
 - pytest
-- sphinx, sphinx-autodoc-typehints
+- sphinx, sphinx-autodoc-typehints (`pip install "funcsim[docs]"`)
+
+### installation
+```bash
+pip install funcsim
+```
 
 ### building html docs
 From the top-level funcsim directory...
 ```bash
-sphinx-build -b html docs/source/ docs/build/
+sphinx-build -W -b html docs/source/ docs/build/
 ```
 
 ### running tests

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

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

funcsim-0.2.3/README.md

@@ -1,39 +0,0 @@
-# funcsim
-Lightweight, functional stochastic simulation
-
-Features:
-- cross-sectional and recursive dynamic simulations
-- pseudo-random numbers (so that results are comparable across multiple runs or scenarios)
-- stratified/Latin hypercube sampling
-- painless multi-core simulations
-- highly flexible, and as simple as possible (but no more)
-- functional paradigm
-
-Developed using:
-- python >= 3.10
-- numpy 2.2.0
-- scipy 1.16.0
-- pandas 2.2.0 (pandas 2.2+ and 3.x are both supported)
-- xarray 2025.4.0
-
-Copulas (Gaussian, Student's t, Clayton, Gumbel, and Frank) are supported
-natively; no additional packages are required.
-
-For optional functionality, additinoal packages are needed:
-- plotting: plotly
-
-Additionally, to run the demos, run tests, and build docs:
-- pytest
-- sphinx, sphinx-autodoc-typehints
-
-### building html docs
-From the top-level funcsim directory...
-```bash
-sphinx-build -b html docs/source/ docs/build/
-```
-
-### running tests
-From the top-level funcsim directory...
-```bash
-python3 -m pytest
-```