funcsim 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.2
+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.2 → 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.2"
+    return "0.2.4"

{funcsim-0.2.2 → 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.2 → 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.2 → 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