funcsim 0.2.5__tar.gz → 0.2.7__tar.gz

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

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

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

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

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

@@ -10,6 +10,8 @@ from .dependence import CopulaClayton
 from .dependence import CopulaGumbel
 from .dependence import CopulaFrank
 
+from .copcompare import copcompare
+
 from .imanconover import imanconover
 
 from .shrinkage import shrink
@@ -46,6 +48,6 @@ def version():
     Returns
     -------
     str
-        The version string of the package (e.g., '0.2.5').
+        The version string of the package (e.g., '0.2.7').
     """
-    return "0.2.5"
+    return "0.2.7"

funcsim-0.2.7/funcsim/copcompare.py

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

{funcsim-0.2.5 → funcsim-0.2.7}/funcsim/copfit.py

@@ -41,9 +41,13 @@ THETA_MIN_FRANK = 1e-6
 # largest admissible theta (tau approx. 0.96-0.99 depending on family)
 _THETA_MAX = 100.0
 
-# search bounds for the Student's t degrees of freedom
+# search bounds for the Student's t degrees of freedom.  An optimum within
+# _NU_GAUSS_FRAC of the ceiling is reported as nu = inf (the Gaussian
+# copula with the same correlation matrix): the profile likelihood is flat
+# there and the ceiling itself is an artifact of the search, not an estimate
 _NU_MIN = 2.0
 _NU_MAX = 200.0
+_NU_GAUSS_FRAC = 0.99
 
 
 def _clipu(u: np.ndarray) -> np.ndarray:
@@ -135,12 +139,45 @@ def _eulerian(n: int) -> list:
     return row
 
 
+def _log_expm1(x: np.ndarray) -> np.ndarray:
+    # log(exp(x) - 1) for x > 0, without overflow for large x
+    x = np.asarray(x, dtype=float)
+    small = np.log(np.expm1(np.minimum(x, 30.0)))
+    large = x + np.log1p(-np.exp(-np.maximum(x, 30.0)))
+    return np.where(x > 30.0, large, small)
+
+
+def _frank_loglik_neg2(theta: float, u: np.ndarray) -> float:
+    # total bivariate Frank log-density for theta < 0.  The density is the
+    # same expression as for theta > 0 (Nelsen, 2006, table 4.1, family 5);
+    # with s = -theta > 0 it reads, every factor positive,
+    #   c(u, v) = s (e^s - 1) e^{s(u+v)}
+    #             / [(e^s - 1) + (e^{su} - 1)(e^{sv} - 1)]^2,
+    # which is evaluated in log space
+    s = -theta
+    (M, d) = u.shape
+    log_es1 = float(_log_expm1(np.array(s)))
+    log_den = np.logaddexp(log_es1,
+                           _log_expm1(s * u[:, 0]) + _log_expm1(s * u[:, 1]))
+    return float(M * (math.log(s) + log_es1) + s * np.sum(u)
+                 - 2.0 * np.sum(log_den))
+
+
 def frank_loglik(theta: float, u: np.ndarray) -> float:
-    # total Frank copula log-density over the rows of u, for theta > 0:
+    # total Frank copula log-density over the rows of u.  theta = 0 is the
+    # independence limit (log-density zero); theta < 0 is admissible for two
+    # variables only.  For theta > 0 and any d:
     # log c = (d-1) log(theta) + log Li_{-(d-1)}(z)
     #         + sum_j [-theta u_j - log(1 - exp(-theta u_j))]
     # with log z = sum_j log(1 - exp(-theta u_j)) - (d-1) log(1 - exp(-theta))
     # and Li_{-n}(z) evaluated via Eulerian numbers, in log space
+    if theta == 0.0:
+        return 0.0
+    if theta < 0.0:
+        if u.shape[1] != 2:
+            raise ValueError("the Frank copula with theta < 0 (negative "
+                             "dependence) is defined only for two variables")
+        return _frank_loglik_neg2(theta, u)
     (M, d) = u.shape
     n = d - 1
     log1me_u = np.log(-np.expm1(-theta * u))  # log(1 - exp(-theta u))
@@ -160,11 +197,72 @@ def _debye1(x: float) -> float:
     # Debye function of order 1: (1/x) * integral_0^x t/(e^t - 1) dt
     if x < 1e-8:
         return 1.0 - x / 4.0
+    if x > 200.0:
+        # beyond the quadrature's range (never reached by the fitting code):
+        # the integrand's mass lies below t ~ 40, so the integral is pi^2/6
+        # less the tail integral_x^inf t/(e^t - 1) dt = (x + 1) e^-x (to
+        # within e^-2x).  This agrees with the quadrature to one ulp at
+        # x = 200 and stays finite where expm1 would overflow
+        return (math.pi ** 2 / 6.0 - (x + 1.0) * math.exp(-x)) / x
     val = integrate.quad(lambda t: t / math.expm1(t) if t > 0.0 else 1.0,
                          0.0, x)[0]
     return val / x
 
 
+# Bernoulli numbers B_2, B_4, ..., B_14, for the small-theta series of
+# Frank's Kendall's tau
+_BERNOULLI_EVEN = (1.0 / 6.0, -1.0 / 30.0, 1.0 / 42.0, -1.0 / 30.0,
+                   5.0 / 66.0, -691.0 / 2730.0, 7.0 / 6.0)
+
+
+def frank_tau(theta: float) -> float:
+    # Kendall's tau of the Frank copula, tau = 1 - (4/theta)(1 - D_1(theta)),
+    # an odd function of theta with tau(0) = 0 (Nelsen, 2006, eq. 5.1.5).
+    # Below |theta| = 0.5 the direct formula loses digits to cancellation
+    # (1 - D_1 ~ theta/4), so the power series
+    #   tau = 4 sum_k B_2k theta^(2k-1) / ((2k+1)(2k)!)
+    #       = theta/9 - theta^3/900 + theta^5/52920 - ...
+    # is used there; its truncation error is below 1e-16 at |theta| = 0.5
+    s = abs(float(theta))
+    if s == 0.0:
+        return 0.0
+    if s <= 0.5:
+        t = 4.0 * sum(b * s ** (2 * k - 1)
+                      / ((2 * k + 1) * math.factorial(2 * k))
+                      for k, b in enumerate(_BERNOULLI_EVEN, start=1))
+    else:
+        t = 1.0 - (4.0 / s) * (1.0 - _debye1(s))
+    return math.copysign(t, theta)
+
+
+def frank_theta_from_tau(tau: float) -> float:
+    # exact inverse of frank_tau for tau in (-1, 0) or (0, 1): theta takes
+    # the sign of tau, and |theta| is found by bracketed root-finding on
+    # |tau|.  tau(theta) is concave with slope 1/9 at the origin, so
+    # theta = 9 |tau| is a lower bracket; the upper bracket is doubled until
+    # it overshoots.  Unlike frank_theta0 (the fitting start value, which
+    # clamps tau at 0.96 and theta at _THETA_MAX) nothing is clamped here
+    t = abs(float(tau))
+    if not (0.0 < t < 1.0):
+        raise ValueError("Kendall's tau for a Frank copula must lie strictly "
+                         "between -1 and 1 and be nonzero (tau = 0 is "
+                         "independence, which the Frank copula reaches only "
+                         f"as theta -> 0); got {tau}")
+
+    def f(th):
+        return frank_tau(th) - t
+
+    lo = 9.0 * t
+    hi = max(2.0 * lo, 1.0)
+    while f(hi) < 0.0:
+        hi *= 2.0
+        if hi > 1e300:
+            raise ValueError(f"cannot represent a Frank copula with "
+                             f"Kendall's tau {tau}")
+    theta = optimize.brentq(f, lo, hi, xtol=1e-14, maxiter=500)
+    return math.copysign(theta, tau)
+
+
 def clayton_theta0(tau: float) -> float:
     # Kendall's-tau inversion for Clayton: theta = 2 tau / (1 - tau)
     t = min(tau, 0.97)
@@ -257,9 +355,19 @@ def fit_gumbel(u: np.ndarray) -> Tuple[float, float, bool]:
 
 
 def fit_frank(u: np.ndarray) -> Tuple[float, float, bool]:
-    # fit Frank theta; returns (theta, mean pairwise tau, clamped flag)
+    # fit Frank theta; returns (theta, mean pairwise tau, clamped flag).
+    # With two variables negative dependence is admissible (theta < 0): the
+    # log-likelihood is mirrored so that the positive-side machinery (start
+    # value, bracket, floor and ceiling) applies to -theta.  With more
+    # variables the Frank copula exists only for theta > 0, and non-positive
+    # dependence is clamped to the floor
     uc = _clipu(u)
     tb = taubar(uc)
+    if tb < 0.0 and uc.shape[1] == 2:
+        theta0 = frank_theta0(-tb)
+        theta = _fit_theta(lambda th, uu: frank_loglik(-th, uu), uc, theta0,
+                           THETA_MIN_FRANK, _THETA_MAX)
+        return (-theta, tb, False)
     if tb <= 0.0:
         return (THETA_MIN_FRANK, tb, True)
     theta0 = frank_theta0(tb)
@@ -267,12 +375,43 @@ def fit_frank(u: np.ndarray) -> Tuple[float, float, bool]:
     return (theta, tb, False)
 
 
-def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
-    # fit a Student's t copula; returns (correlation matrix, deg. of freedom).
+def gauss_loglik(R: np.ndarray, u: np.ndarray) -> float:
+    # total Gaussian copula log-density over the rows of u for the
+    # correlation matrix R:
+    # log c(u) = -0.5 log|R| - 0.5 z' (R^-1 - I) z, with z = Phi^-1(u)
+    uc = _clipu(u)
+    z = stats.norm.ppf(uc)
+    (M, d) = z.shape
+    (sign, logdet) = np.linalg.slogdet(R)
+    if sign <= 0:
+        raise ValueError("R must be positive definite")
+    quad = np.einsum("ij,jk,ik->i", z, np.linalg.inv(R) - np.eye(d), z)
+    return float(-0.5 * M * logdet - 0.5 * np.sum(quad))
+
+
+def student_loglik(R: np.ndarray, nu: float, u: np.ndarray) -> float:
+    # total Student's t copula log-density over the rows of u for the
+    # correlation matrix R and degrees of freedom nu:
+    # log c(u) = log t_{nu,R}(x) - sum_k log t_nu(x_k), with x = t_nu^-1(u).
+    # nu = inf is the Gaussian copula with the same R
+    if math.isinf(nu):
+        return gauss_loglik(R, u)
+    uc = _clipu(u)
+    x = stats.t.ppf(uc, df=nu)
+    d = R.shape[0]
+    joint = stats.multivariate_t(loc=np.zeros(d), shape=R, df=nu).logpdf(x)
+    return float(np.sum(joint) - np.sum(stats.t.logpdf(x, df=nu)))
+
+
+def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float, float]:
+    # fit a Student's t copula; returns (correlation matrix, deg. of freedom,
+    # log-likelihood gain of the fitted nu over the Gaussian limit nu = inf
+    # at the same correlation matrix).
     # stage 1: pairwise Kendall's tau -> rho_ij = sin(pi tau_ij / 2),
     # corrected to the nearest positive definite correlation matrix.
     # stage 2: profile maximum pseudo-likelihood for nu, searching on a
-    # log scale (the likelihood is flat in nu near the Gaussian limit)
+    # log scale (the likelihood is flat in nu near the Gaussian limit).  An
+    # optimum at the search ceiling is reported as nu = inf, with zero gain
     uc = _clipu(u)
     R = np.sin(0.5 * np.pi * taumatrix(uc))
     np.fill_diagonal(R, 1.0)
@@ -281,17 +420,12 @@ def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
     R = R / np.outer(s, s)  # renormalize to unit diagonal
     np.fill_diagonal(R, 1.0)
 
-    mvt_dim = R.shape[0]
-
     def negll(lognu):
         nu = math.exp(lognu)
         try:
             with np.errstate(divide="ignore", invalid="ignore",
                              over="ignore"):
-                x = stats.t.ppf(uc, df=nu)
-                ll = (stats.multivariate_t(loc=np.zeros(mvt_dim), shape=R,
-                                           df=nu).logpdf(x).sum()
-                      - stats.t.logpdf(x, df=nu).sum())
+                ll = student_loglik(R, nu, uc)
         except Exception:
             return np.inf
         return -ll if np.isfinite(ll) else np.inf
@@ -301,4 +435,8 @@ def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
                                            math.log(_NU_MAX)),
                                    method="bounded")
     nu = float(math.exp(res.x)) if res.success else _NU_MAX
-    return (R, nu)
+    if nu > _NU_GAUSS_FRAC * _NU_MAX:
+        return (R, math.inf, 0.0)
+    ll_gauss = gauss_loglik(R, uc)
+    gain = -negll(math.log(nu)) - ll_gauss
+    return (R, nu, float(gain) if np.isfinite(gain) else math.nan)

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

@@ -12,18 +12,55 @@ from typing import Optional
 import inspect
 
 
-def _get_arg_count(func):
-    sig = inspect.signature(func)
-    params = sig.parameters.values()
-
-    # Count only parameters that are positional or keyword
-    # (excluding *args and **kwargs)
-    return sum(
-        1 for p in params
-        if p.kind in (inspect.Parameter.POSITIONAL_ONLY,
-                      inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                      inspect.Parameter.KEYWORD_ONLY)
-    )
+def _stepf_arity(func):
+    # how many positional arguments simulate passes to the user's trial or
+    # step function: 1 (the draw generator) or 2 (the generator and the
+    # per-trial history).  The rule, stated in the simulate docstring:
+    #   * the first parameter receives the generator;
+    #   * a second parameter receives the history if it has no default or
+    #     is named 'hist'.  A second parameter with a default and another
+    #     name is a setting (e.g., 'scale=1.0') left at its default, and the
+    #     function is called with the generator alone;
+    #   * any further parameters must have defaults; keyword-only
+    #     parameters (as functools.partial produces) must have defaults;
+    #   * a parameter named 'hist' anywhere but second is ambiguous.
+    # Formerly every parameter was counted, so 'def f(ugen, scale=1.0)'
+    # received the history object as 'scale' and failed far from the cause
+    P = inspect.Parameter
+    try:
+        params = list(inspect.signature(func).parameters.values())
+    except (TypeError, ValueError):
+        raise ValueError('"f" must be a function whose signature can be '
+                         'inspected') from None
+    positional = [p for p in params
+                  if p.kind in (P.POSITIONAL_ONLY, P.POSITIONAL_OR_KEYWORD)]
+    required_kw = [p.name for p in params
+                   if p.kind is P.KEYWORD_ONLY and p.default is P.empty]
+    if required_kw:
+        raise ValueError(f'"f" has keyword-only parameter(s) without a '
+                         f'default ({", ".join(required_kw)}); simulate '
+                         f'supplies only the draw generator and the history, '
+                         f'positionally.  Bind such parameters with '
+                         f'functools.partial or give them defaults')
+    if not positional:
+        raise ValueError('"f" must take the draw generator as its first '
+                         'parameter')
+    required = [p.name for p in positional if p.default is P.empty]
+    if len(required) > 2:
+        raise ValueError(f'"f" has {len(required)} parameters without '
+                         f'defaults ({", ".join(required)}); simulate '
+                         f'supplies at most two: the draw generator and the '
+                         f'history.  Give the others defaults or bind them '
+                         f'with functools.partial')
+    if any(p.name == "hist" and i != 1 for i, p in enumerate(positional)):
+        raise ValueError('a parameter of "f" named "hist" receives the '
+                         'per-trial history and must therefore be the second '
+                         'parameter')
+    if len(required) == 2:
+        return 2
+    if len(positional) >= 2 and positional[1].name == "hist":
+        return 2
+    return 1
 
 
 def _checkhist0(hist0):
@@ -197,6 +234,17 @@ def simulate(f: Callable[[Generator[int, float, None],
         times `f` calls ``next(ugen)`` must be the same in every trial and
         step, because draws are pre-allocated across trials for stratified
         sampling.
+
+        Which parameters receive what is decided from the signature of `f`:
+        the first parameter receives the generator; a second parameter
+        receives the history if it has no default or is named ``hist``,
+        whereas a second parameter with a default and another name (for
+        example ``scale=1.0``) is treated as a setting, left at its default,
+        and `f` is called with the generator alone.  Any further parameters
+        must have defaults, as must keyword-only parameters (which is what
+        :func:`functools.partial` produces when binding a scenario
+        parameter by name).  A parameter named ``hist`` in any position but
+        the second is rejected as ambiguous.
     ntrials : int, optional
         The number of trials to perform.  Default is 500.
     nsteps : int, optional
@@ -234,14 +282,37 @@ def simulate(f: Callable[[Generator[int, float, None],
     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'.
+        If `hist0` is malformed; if `f` is not callable, has more than two
+        parameters without defaults, has a keyword-only parameter without a
+        default, or has a parameter named ``hist`` that is not its second;
+        if `f` does not return a dict keyed by strings; or if `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.
+
+    Notes
+    -----
+    **Draw allocation and common random numbers.**  Before any trial runs,
+    the draws are allocated as one column of `ntrials` values per uniform
+    that `f` consumes over all steps of a trial, generated in consumption
+    order from a single :class:`numpy.random.Generator` seeded with `seed`
+    (stratified across trials when `sampling` is ``'lh'``).  The j-th
+    uniform consumed in trial r therefore depends only on `seed`, `ntrials`,
+    `sampling`, j, and r: not on how many uniforms `f` consumes in total,
+    on what `f` computes from them, or on `multi`.  This is a documented
+    guarantee.  Its consequence is common random numbers across scenarios:
+    two trial functions that consume K and K + 1 uniforms (with `nsteps` of
+    1) receive identical first K uniforms in every trial under the same
+    `seed` and `ntrials`, so differences in their outputs are due to the
+    extra draw and the model alone.  With several steps, step s of trial r
+    receives uniforms sK + 1 through (s + 1)K of that trial's stream, where
+    K is the number consumed per step; two step functions with different
+    per-step counts therefore share their draws only in the first step.
+    With `stdnorm` True the same statements hold for the standard normal
+    draws, which are an elementwise transform of the uniforms.
     """
     if hist0 is not None:
         _checkhist0(hist0)
@@ -276,16 +347,13 @@ def simulate(f: Callable[[Generator[int, float, None],
     if not isinstance(f, Callable):
         raise ValueError('"f" must be a callable function')
 
-    # infer number of arguments in 'f'.  If it takes only a single arg, wrap it
-    # in an outer func that takes "hist" as a second arg
-    numb_f_args = _get_arg_count(f)
-    if numb_f_args == 1:
-        stepf = functools.partial(_stepf_1arg, f)
-    elif numb_f_args == 2:
+    # decide from the signature of 'f' whether it takes the history as a
+    # second argument; if not, wrap it in an outer func that does
+    if _stepf_arity(f) == 2:
         stepf = f
     else:
-        raise ValueError('"f" should take two arguments at most')
-     
+        stepf = functools.partial(_stepf_1arg, f)
+
     # indexes for the final output xr.DataArray
     varNames = hist0.indexes['variables']
     namePositionsPrelim = {nm: i for i, nm in enumerate(varNames)}