pyAssetCorr 0.1.1__py3-none-any.whl

pyassetcorr/__init__.py

@@ -0,0 +1,80 @@
+"""pyAssetCorr -- asset-correlation estimation under the Vasicek model.
+
+Estimate intra-cohort and inter-cohort asset correlation from historical
+default data using method-of-moments and maximum-likelihood estimators, with
+standard errors, information criteria, likelihood-ratio tests, and tools for
+overlapping multi-year cohorts.
+
+Clean-room implementation from the published equations; see ``docs/USER_GUIDE.md``
+and the per-function docstrings for formulas and references.
+"""
+
+from __future__ import annotations
+
+from ._accel import HAS_NUMBA
+from .mle import intra_mle
+from .moments import intra_amm, intra_fmm, intra_jdp1, intra_jdp2
+from .multicohort import (
+    multi_cohort_mle,
+    multi_cohort_single_factor,
+    multi_cohort_uniform,
+)
+from .overlap import (
+    GroupAverageResult,
+    group_average,
+    nonoverlap_subsample,
+    partition_groups,
+)
+from .results import LRTestResult, MLEResult, MomentResult, aic, bic, lr_test
+from .simulate import (
+    simulate_default_series,
+    simulate_multi_cohort,
+    simulate_overlapping_series,
+)
+
+__version__ = "0.1.1"
+
+# AssetCorr-style aliases for discoverability.
+intraAMM = intra_amm
+intraFMM = intra_fmm
+intraJDP1 = intra_jdp1
+intraJDP2 = intra_jdp2
+intraMLE = intra_mle
+
+__all__ = [
+    "__version__",
+    "HAS_NUMBA",
+    # moment estimators
+    "intra_amm",
+    "intra_fmm",
+    "intra_jdp1",
+    "intra_jdp2",
+    # mle
+    "intra_mle",
+    # multi-cohort
+    "multi_cohort_mle",
+    "multi_cohort_uniform",
+    "multi_cohort_single_factor",
+    # overlap handling
+    "group_average",
+    "partition_groups",
+    "nonoverlap_subsample",
+    "GroupAverageResult",
+    # simulation
+    "simulate_default_series",
+    "simulate_multi_cohort",
+    "simulate_overlapping_series",
+    # results & inference
+    "MomentResult",
+    "MLEResult",
+    "LRTestResult",
+    "aic",
+    "bic",
+    "lr_test",
+    # aliases
+    "intraAMM",
+    "intraFMM",
+    "intraJDP1",
+    "intraJDP2",
+    "intraMLE",
+]

pyassetcorr/_accel.py

@@ -0,0 +1,109 @@
+"""Optional numba acceleration with a pure-NumPy fallback.
+
+The single hot kernel shared by the likelihood code is the conditional
+log-likelihood of a binomial observation summed over Gauss-Hermite nodes.  We
+expose one function, :func:`gh_loglik`, with two interchangeable
+implementations selected at import time:
+
+* a vectorised NumPy version (always available), and
+* a numba-jitted version (used when ``numba`` imports successfully).
+
+Both must return identical values; ``tests/test_mle.py`` asserts parity when
+numba is present.  The local interpreter may be too new for numba, in which
+case the NumPy path is exercised transparently.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import gammaln
+
+__all__ = ["gh_loglik", "HAS_NUMBA"]
+
+
+def _log_binom_coeff(d, n):
+    """log C(n, d) via log-gamma; works on scalars or arrays."""
+    return gammaln(n + 1.0) - gammaln(d + 1.0) - gammaln(n - d + 1.0)
+
+
+def _gh_loglik_numpy(d, n, cond_pd, log_weights):
+    """Total log-likelihood over independent periods (NumPy).
+
+    Parameters
+    ----------
+    d, n : ndarray, shape (T,)
+        Default counts and obligor counts per period.
+    cond_pd : ndarray, shape (T, M)
+        Conditional default probability ``g(z_i)`` for each period (rows) and
+        Gauss-Hermite node (columns).
+    log_weights : ndarray, shape (M,)
+        ``log(w_i / sqrt(2 pi))`` from :func:`gauss_hermite`.
+
+    Returns
+    -------
+    float
+        ``sum_t log( sum_i exp(log_weights_i) * Binom(d_t; n_t, g(z_i)) )``.
+    """
+    d = d[:, None]
+    n = n[:, None]
+    p = np.clip(cond_pd, 1e-15, 1.0 - 1e-15)
+    log_pmf = _log_binom_coeff(d, n) + d * np.log(p) + (n - d) * np.log1p(-p)
+    log_terms = log_pmf + log_weights[None, :]
+    # logsumexp over nodes, then sum over periods.
+    m = np.max(log_terms, axis=1, keepdims=True)
+    per_period = m[:, 0] + np.log(np.sum(np.exp(log_terms - m), axis=1))
+    return float(np.sum(per_period))
+
+
+try:  # pragma: no cover - exercised only where numba is installed
+    import math
+
+    import numba
+
+    @numba.njit(cache=True)
+    def _gh_loglik_numba(d, n, cond_pd, log_weights):
+        T = d.shape[0]
+        M = log_weights.shape[0]
+        total = 0.0
+        for t in range(T):
+            lognc = (
+                math.lgamma(n[t] + 1.0)
+                - math.lgamma(d[t] + 1.0)
+                - math.lgamma(n[t] - d[t] + 1.0)
+            )
+            max_lt = -1e300
+            tmp = np.empty(M)
+            for i in range(M):
+                p = cond_pd[t, i]
+                if p < 1e-15:
+                    p = 1e-15
+                elif p > 1.0 - 1e-15:
+                    p = 1.0 - 1e-15
+                lt = (
+                    lognc
+                    + d[t] * math.log(p)
+                    + (n[t] - d[t]) * math.log(1.0 - p)
+                    + log_weights[i]
+                )
+                tmp[i] = lt
+                if lt > max_lt:
+                    max_lt = lt
+            s = 0.0
+            for i in range(M):
+                s += math.exp(tmp[i] - max_lt)
+            total += max_lt + math.log(s)
+        return total
+
+    HAS_NUMBA = True
+
+    def gh_loglik(d, n, cond_pd, log_weights):
+        return _gh_loglik_numba(
+            np.ascontiguousarray(d, dtype=np.float64),
+            np.ascontiguousarray(n, dtype=np.float64),
+            np.ascontiguousarray(cond_pd, dtype=np.float64),
+            np.ascontiguousarray(log_weights, dtype=np.float64),
+        )
+
+except Exception:  # numba unavailable or incompatible interpreter
+    HAS_NUMBA = False
+    gh_loglik = _gh_loglik_numpy

pyassetcorr/_quadrature.py

@@ -0,0 +1,126 @@
+"""Gauss-Hermite quadrature helpers for marginalising the systematic factor.
+
+The Vasicek likelihood integrates the conditional binomial against a standard
+normal density.  Using the *probabilists'* Hermite polynomials
+(``numpy.polynomial.hermite_e``) gives nodes ``z_i`` and weights ``w_i`` such
+that
+
+    E_{Z~N(0,1)}[f(Z)] = sum_i (w_i / sqrt(2 pi)) * f(z_i)
+
+with no change of variables required (the standard normal density is built in).
+
+This is faster and more accurate than the Simpson-rule grid used by the
+reference R implementation, and the same nodes/weights are reused across all
+periods and bootstrap resamples, so they are cached.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+from numpy.polynomial.hermite_e import hermegauss
+from scipy.special import gammaln, logsumexp
+
+from ._vasicek import pnorm, qnorm
+
+__all__ = ["gauss_hermite", "DEFAULT_NODES", "adaptive_binom_loglik"]
+
+DEFAULT_NODES = 32
+
+_INV_SQRT_2PI = 1.0 / np.sqrt(2.0 * np.pi)
+
+
+def _std_normal_pdf(x):
+    return _INV_SQRT_2PI * np.exp(-0.5 * x * x)
+
+
+@lru_cache(maxsize=None)
+def gauss_hermite(n: int = DEFAULT_NODES):
+    """Return ``(nodes, log_weights)`` for standard-normal expectation.
+
+    ``nodes`` are the abscissae ``z_i``; ``log_weights`` are
+    ``log(w_i / sqrt(2 pi))`` so that ``sum_i exp(log_weights_i) f(z_i)``
+    approximates ``E[f(Z)]`` for ``Z ~ N(0, 1)``.  Log-weights are returned
+    because the likelihood is evaluated in log-space via ``logsumexp``.
+    """
+    nodes, weights = hermegauss(int(n))
+    log_weights = np.log(weights) - 0.5 * np.log(2.0 * np.pi)
+    return nodes, log_weights
+
+
+def adaptive_binom_loglik(d, n, c_eff, coef, denom, z, logw, newton_iter=80):
+    """Adaptive (mode-centered) Gauss-Hermite log-likelihood of a binomial mixed
+    over a standard-normal latent factor ``t``.
+
+    Computes, elementwise over the broadcast of the inputs,
+
+        log integral phi(t) * Binom(d; n, Phi((c_eff - coef*t)/denom)) dt.
+
+    For large ``n`` the integrand is sharply peaked in ``t``; fixed-node
+    quadrature under-resolves it.  Here the nodes are recentered on the
+    per-element integrand mode (a few damped Newton steps) and rescaled by the
+    local curvature (Laplace/Liu-Pierce adaptive GH), so a small base grid
+    integrates accurately at any ``n``.
+
+    Parameters
+    ----------
+    d, n, c_eff, coef, denom : array_like
+        Broadcastable.  ``c_eff`` is the (possibly shifted) probit threshold,
+        ``coef`` the latent-factor loading, ``denom`` the conditional scale.
+        Single-cohort Vasicek: ``c_eff=Phi^{-1}(pd)``, ``coef=sqrt(rho)``,
+        ``denom=sqrt(1-rho)``.
+    z, logw : ndarray
+        Base probabilists' Gauss-Hermite nodes and log-weights from
+        :func:`gauss_hermite`.
+
+    Returns
+    -------
+    ndarray
+        Per-element log marginal likelihood (broadcast shape of the inputs).
+    """
+    d = np.asarray(d, dtype=float)
+    n = np.asarray(n, dtype=float)
+    c_eff = np.asarray(c_eff, dtype=float)
+    coef = np.asarray(coef, dtype=float)
+    denom = np.asarray(denom, dtype=float)
+    shape = np.broadcast_shapes(d.shape, n.shape, c_eff.shape, coef.shape, denom.shape)
+    d = np.broadcast_to(d, shape)
+    n = np.broadcast_to(n, shape)
+    c_eff = np.broadcast_to(c_eff, shape)
+    coef = np.broadcast_to(coef, shape)
+    denom = np.broadcast_to(denom, shape)
+    k = -coef / denom
+
+    def derivs(mu):
+        u = (c_eff - coef * mu) / denom
+        g = np.clip(pnorm(u), 1e-12, 1.0 - 1e-12)
+        pu = _std_normal_pdf(u)
+        gp = pu * k
+        gpp = -u * pu * k * k
+        ratio = d / g - (n - d) / (1.0 - g)
+        ratiop = -d * gp / g ** 2 - (n - d) * gp / (1.0 - g) ** 2
+        f1 = -mu + ratio * gp
+        f2 = -1.0 + ratiop * gp + ratio * gpp
+        return f1, f2
+
+    mu = np.zeros(shape)
+    for _ in range(newton_iter):
+        f1, f2 = derivs(mu)
+        f2 = np.minimum(f2, -1e-6)  # keep concave for a stable Newton step
+        mu = mu - np.clip(f1 / f2, -2.0, 2.0)
+
+    _, f2 = derivs(mu)
+    sigma = 1.0 / np.sqrt(np.clip(-f2, 1e-12, None))
+
+    t = mu[..., None] + sigma[..., None] * z  # (..., M)
+    u = (c_eff[..., None] - coef[..., None] * t) / denom[..., None]
+    g = np.clip(pnorm(u), 1e-15, 1.0 - 1e-15)
+    log_coeff = gammaln(n + 1.0) - gammaln(d + 1.0) - gammaln(n - d + 1.0)
+    binom = (
+        log_coeff[..., None]
+        + d[..., None] * np.log(g)
+        + (n - d)[..., None] * np.log1p(-g)
+    )
+    log_term = logw + np.log(sigma)[..., None] + 0.5 * z ** 2 - 0.5 * t ** 2 + binom
+    return logsumexp(log_term, axis=-1)

pyassetcorr/_vasicek.py

@@ -0,0 +1,94 @@
+"""Core Vasicek one-factor model primitives.
+
+The single-factor Gaussian copula (Vasicek) model assumes that, for an obligor
+with unconditional default probability ``PD`` and asset correlation ``rho``, the
+latent asset return is
+
+    A = sqrt(rho) * X + sqrt(1 - rho) * eps
+
+with ``X`` the systematic factor and ``eps`` idiosyncratic, both standard
+normal.  The obligor defaults when ``A < Phi^{-1}(PD)``.  Conditional on ``X``,
+defaults are independent, so the conditional default probability is
+
+    g(x) = Phi( (Phi^{-1}(PD) - sqrt(rho) * x) / sqrt(1 - rho) ).
+
+Reference
+---------
+Vasicek, O. (2002). *The Distribution of Loan Portfolio Value.* Risk.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import ndtr, ndtri
+from scipy.stats import multivariate_normal
+
+__all__ = [
+    "qnorm",
+    "pnorm",
+    "conditional_pd",
+    "bvn_cdf",
+    "EPS",
+]
+
+# Numerical floor used to keep probabilities strictly inside (0, 1) so that
+# Phi^{-1} stays finite.
+EPS = 1e-12
+
+
+def qnorm(p):
+    """Standard-normal quantile (inverse CDF), ``Phi^{-1}``."""
+    p = np.clip(p, EPS, 1.0 - EPS)
+    return ndtri(p)
+
+
+def pnorm(x):
+    """Standard-normal CDF, ``Phi``."""
+    return ndtr(x)
+
+
+def conditional_pd(x, pd, rho):
+    """Conditional default probability ``g(x)`` given the systematic factor.
+
+    Parameters
+    ----------
+    x : array_like
+        Realisation(s) of the systematic factor.
+    pd : float
+        Unconditional probability of default.
+    rho : float
+        Asset correlation in ``[0, 1)``.
+
+    Returns
+    -------
+    ndarray
+        ``Phi((Phi^{-1}(pd) - sqrt(rho) x) / sqrt(1 - rho))``.
+    """
+    x = np.asarray(x, dtype=float)
+    rho = float(rho)
+    c = qnorm(pd)
+    denom = np.sqrt(max(1.0 - rho, EPS))
+    return pnorm((c - np.sqrt(max(rho, 0.0)) * x) / denom)
+
+
+def bvn_cdf(a, b, rho):
+    """Bivariate standard-normal CDF ``P(Z1 <= a, Z2 <= b)`` with correlation ``rho``.
+
+    This is the joint default probability ``BVN(Phi^{-1}(p), Phi^{-1}(p); rho)``
+    used by the method-of-moments estimators.
+    """
+    rho = float(np.clip(rho, -1.0 + EPS, 1.0 - EPS))
+    cov = np.array([[1.0, rho], [rho, 1.0]])
+    return float(multivariate_normal.cdf([a, b], mean=[0.0, 0.0], cov=cov))
+
+
+def bvn_pdf(a, b, rho):
+    """Bivariate standard-normal density at ``(a, b)`` with correlation ``rho``.
+
+    Used for the analytic derivative ``d/drho BVN(a, b; rho) = phi_2(a, b; rho)``
+    (Plackett's identity), which appears in the delta-method standard errors.
+    """
+    rho = float(np.clip(rho, -1.0 + EPS, 1.0 - EPS))
+    det = 1.0 - rho * rho
+    quad = (a * a - 2.0 * rho * a * b + b * b) / det
+    return float(np.exp(-0.5 * quad) / (2.0 * np.pi * np.sqrt(det)))

pyassetcorr/mle.py

@@ -0,0 +1,199 @@
+"""Single-cohort Vasicek-Binomial maximum-likelihood estimator.
+
+For each period ``t`` the likelihood marginalises the systematic factor:
+
+    L_t(rho, PD) = integral Binom(d_t; n_t, g(x)) phi(x) dx,
+
+with ``g`` the Vasicek conditional default probability.  The integral is
+evaluated by *adaptive* (mode-centered) Gauss-Hermite quadrature in log-space --
+accurate at any ``n`` with a small node grid -- and the total log-likelihood
+``sum_t log L_t`` is maximised.  ``pd="plug_in"`` fixes ``PD = mean(d/n)`` and
+optimises ``rho`` only; ``pd="joint"`` estimates ``PD`` as well.
+
+Standard errors come from the inverse observed Fisher information (numerical
+Hessian of the negative log-likelihood); with ``lag > 0`` a Newey-West HAC
+sandwich is used for autocorrelated (overlapping-cohort) data.
+
+References
+----------
+Gordy, M. & Heitfield, E. (2010). *Small-sample estimation of models of
+portfolio credit risk.*
+Duellmann, K. & Gehde-Trapp, M. (2004). *Probability of default estimation.*
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import minimize, minimize_scalar
+
+from ._quadrature import DEFAULT_NODES, adaptive_binom_loglik, gauss_hermite
+from .results import MLEResult, normal_ci
+
+__all__ = ["intra_mle"]
+
+
+def _validate(d, n):
+    d = np.asarray(d, dtype=float)
+    n = np.asarray(n, dtype=float)
+    if d.shape != n.shape or d.ndim != 1:
+        raise ValueError("d and n must be equal-length 1-D arrays")
+    if np.any(n <= 0) or np.any(d < 0) or np.any(d > n):
+        raise ValueError("require positive n and 0 <= d <= n")
+    return d, n
+
+
+def _logL_periods(d, n, pd, rho, z, logw):
+    """Per-period log-likelihood ``log L_t`` (shape ``(T,)``)."""
+    from ._vasicek import qnorm
+
+    rho = min(max(float(rho), 1e-9), 1.0 - 1e-9)
+    return adaptive_binom_loglik(
+        d, n, qnorm(pd), np.sqrt(rho), np.sqrt(1.0 - rho), z, logw
+    )
+
+
+def _num_hessian(f, x, rel=1e-4):
+    x = np.asarray(x, dtype=float)
+    k = x.size
+    h = rel * (np.abs(x) + rel)
+    H = np.zeros((k, k))
+    for i in range(k):
+        for j in range(i, k):
+            xpp = x.copy(); xpp[i] += h[i]; xpp[j] += h[j]
+            xpm = x.copy(); xpm[i] += h[i]; xpm[j] -= h[j]
+            xmp = x.copy(); xmp[i] -= h[i]; xmp[j] += h[j]
+            xmm = x.copy(); xmm[i] -= h[i]; xmm[j] -= h[j]
+            H[i, j] = H[j, i] = (f(xpp) - f(xpm) - f(xmp) + f(xmm)) / (
+                4.0 * h[i] * h[j]
+            )
+    return H
+
+
+def _score_series(periods_fn, theta, rel=1e-4):
+    """Per-period score rows ``(T, k)`` by central differences."""
+    theta = np.asarray(theta, dtype=float)
+    k = theta.size
+    h = rel * (np.abs(theta) + rel)
+    cols = []
+    for i in range(k):
+        tp = theta.copy(); tp[i] += h[i]
+        tm = theta.copy(); tm[i] -= h[i]
+        cols.append((periods_fn(tp) - periods_fn(tm)) / (2.0 * h[i]))
+    return np.stack(cols, axis=1)
+
+
+def _hac_meat(S, lag):
+    """Newey-West meat matrix from per-period score rows ``S`` (T x k)."""
+    T = S.shape[0]
+    B = S.T @ S
+    for z in range(1, min(lag, T - 1) + 1):
+        Gz = S[z:].T @ S[:-z]
+        B += (1.0 - z / T) * (Gz + Gz.T)
+    return B
+
+
+def intra_mle(d, n, *, pd="plug_in", nodes=DEFAULT_NODES, lag=0, ci=False, ci_level=0.95):
+    """Single-cohort Vasicek-Binomial MLE.
+
+    Parameters
+    ----------
+    d, n : array_like
+        Per-period default counts and obligor counts (equal length).
+    pd : {"plug_in", "joint"}, default "plug_in"
+        ``"plug_in"`` fixes ``PD = mean(d/n)`` and optimises ``rho`` only;
+        ``"joint"`` estimates ``PD`` jointly with ``rho``.
+    nodes : int, default 32
+        Base Gauss-Hermite nodes for the adaptive quadrature.  Because the
+        quadrature is mode-centered (adaptive), the estimate should already be
+        stable at this default; refit with a larger ``nodes`` and confirm
+        ``rho``/``loglik`` are unchanged to verify convergence.
+    lag : int, default 0
+        HAC lag for an autocorrelation-robust sandwich SE (overlapping cohorts).
+        ``lag=0`` uses the plain inverse observed information.
+    ci : bool, default False
+        Attach Wald confidence intervals.
+    ci_level : float, default 0.95
+        Confidence level.
+
+    Returns
+    -------
+    MLEResult
+        ``params`` holds ``{"rho": ...}`` and, when ``pd="joint"``, ``"pd"``.
+    """
+    d, n = _validate(d, n)
+    z, logw = gauss_hermite(nodes)
+    T = d.size
+    pbar = float(np.mean(d / n))
+
+    if pd == "plug_in":
+        def periods(theta):
+            return _logL_periods(d, n, pbar, theta[0], z, logw)
+
+        def neg(rho):
+            return -float(np.sum(_logL_periods(d, n, pbar, rho, z, logw)))
+
+        res = minimize_scalar(neg, bounds=(1e-6, 1.0 - 1e-6), method="bounded")
+        rho_hat = float(res.x)
+        loglik = -float(res.fun)
+        params = {"rho": rho_hat}
+        theta = np.array([rho_hat])
+        success = bool(res.success)
+    elif pd == "joint":
+        def periods(theta):
+            return _logL_periods(d, n, theta[1], theta[0], z, logw)
+
+        def neg_vec(th):
+            return -float(np.sum(periods(th)))
+
+        x0 = np.array([0.1, pbar])
+        res = minimize(
+            neg_vec, x0, method="L-BFGS-B",
+            bounds=[(1e-6, 1.0 - 1e-6), (1e-9, 1.0 - 1e-9)],
+        )
+        rho_hat, pd_hat = float(res.x[0]), float(res.x[1])
+        loglik = -float(res.fun)
+        params = {"rho": rho_hat, "pd": pd_hat}
+        theta = np.array([rho_hat, pd_hat])
+        success = bool(res.success)
+    else:
+        raise ValueError("pd must be 'plug_in' or 'joint'")
+
+    n_params = theta.size
+    keys = list(params.keys())
+
+    def neg_theta(th):
+        return -float(np.sum(periods(th)))
+
+    se = None
+    cov = None
+    ci_out = None
+    try:
+        A = _num_hessian(neg_theta, theta)  # observed information
+        if lag > 0:
+            S = _score_series(periods, theta)
+            B = _hac_meat(S, lag)
+            Ainv = np.linalg.inv(A)
+            cov = Ainv @ B @ Ainv
+        else:
+            cov = np.linalg.inv(A)
+        diag = np.diag(cov)
+        if np.all(diag > 0):
+            se_vec = np.sqrt(diag)
+            se = {k: float(se_vec[i]) for i, k in enumerate(keys)}
+            if ci:
+                ci_out = {k: normal_ci(params[k], se[k], ci_level) for k in keys}
+    except np.linalg.LinAlgError:
+        pass
+
+    return MLEResult(
+        params=params,
+        loglik=loglik,
+        n_params=n_params,
+        n_obs=T,
+        method="intra_mle",
+        se=se,
+        cov=cov,
+        ci=ci_out,
+        pd=pd,
+        converged=success,
+    )