funcsim 0.2.6__tar.gz → 0.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: funcsim
-Version: 0.2.6
+Version: 0.2.8
 Summary: functional, simple stochastic simulation
 Home-page: https://github.com/h-bryant/funcsim
 Author: Henry Bryant

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

@@ -48,6 +48,6 @@ def version():
     Returns
     -------
     str
-        The version string of the package (e.g., '0.2.6').
+        The version string of the package (e.g., '0.2.8').
     """
-    return "0.2.6"
+    return "0.2.8"

{funcsim-0.2.6 → funcsim-0.2.8}/funcsim/copcompare.py

@@ -56,7 +56,11 @@ def copcompare(udata: conversions.ArrayLike) -> pd.DataFrame:
     and maximum pseudo-likelihood for the Archimedean families.  The
     Gaussian and Student's t log-likelihoods are therefore evaluated at
     moment-type estimates rather than at the exact maximum, so their
-    criteria are conservative by a small amount.  Standard information
+    criteria 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

{funcsim-0.2.6 → funcsim-0.2.8}/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)
@@ -284,7 +392,10 @@ def gauss_loglik(R: np.ndarray, u: np.ndarray) -> float:
 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)
+    # 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]
@@ -292,12 +403,15 @@ def student_loglik(R: np.ndarray, nu: float, u: np.ndarray) -> float:
     return float(np.sum(joint) - np.sum(stats.t.logpdf(x, df=nu)))
 
 
-def fit_student(u: np.ndarray) -> Tuple[np.ndarray, float]:
-    # fit a Student's t copula; returns (correlation matrix, deg. of freedom).
+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)
@@ -321,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.6 → funcsim-0.2.8}/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)}