funcsim 0.2.3__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.3
+Version: 0.2.4
 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
+- 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.4/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
+- 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.4}/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.4').
     """
-    return "0.2.3"
+    return "0.2.4"

{funcsim-0.2.3 → funcsim-0.2.4}/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.4}/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.4}/funcsim/dependence.py

@@ -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,
@@ -287,8 +292,14 @@ class MvNorm():
     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,
@@ -330,11 +341,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,
+            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
-            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)]
         retA = self._mu + np.dot(self._A, stats.norm.ppf(uvec))
@@ -353,10 +365,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 +429,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 +449,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 +499,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 +522,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 +555,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 +587,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 +612,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 +645,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 +677,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 +700,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 +733,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 +762,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.4}/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.4}/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.4}/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.4}/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.4}/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.4}/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.4}/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.4}/funcsim/shrinkage.py

@@ -216,12 +216,19 @@ 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.
 
     Returns
     -------
@@ -232,6 +239,13 @@ def shrink(data: conversions.ArrayLike,
     ------
     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") 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.3
+Version: 0.2.4
 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
+- 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.4}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="funcsim",
-    version="0.2.3",
+    version="0.2.4",
     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
-```