hfvol 0.1.0__py3-none-any.whl

hfvol/__init__.py

@@ -0,0 +1,85 @@
+"""hfvol: realized variance, bipower and jump variation, Hawkes intensity and HAR-RV.
+
+numpy functions live in :mod:`hfvol.realized`, :mod:`hfvol.har` and
+:mod:`hfvol.hawkes`. The sktime estimators (``RealizedVariance``,
+``BipowerVariation``, ``JumpVariation``, ``HawkesIntensity``, ``HARForecaster``)
+are loaded on first access and need ``pip install hfvol[sktime]``.
+
+Carved out of srfm-lab (https://github.com/Mattbusel/srfm-lab), MIT.
+"""
+
+from __future__ import annotations
+
+from hfvol.har import HARParams, fit_har, har_features, har_forecast, har_forecast_path
+from hfvol.hawkes import (
+    HawkesParams,
+    branching_ratio,
+    fit_hawkes_mle,
+    hawkes_compensator,
+    hawkes_intensity_path,
+    hawkes_log_likelihood,
+    hawkes_residual_analysis,
+    hawkes_simulate,
+)
+from hfvol.realized import (
+    bipower_variation,
+    bipower_variation_series,
+    jump_variation,
+    jump_variation_series,
+    realized_variance,
+    realized_variance_series,
+)
+
+__version__ = "0.1.0"
+
+_SKTIME = {
+    "RealizedVariance": "hfvol.transformers",
+    "BipowerVariation": "hfvol.transformers",
+    "JumpVariation": "hfvol.transformers",
+    "HawkesIntensity": "hfvol.transformers",
+    "HARForecaster": "hfvol.forecasting",
+}
+
+__all__ = [
+    "__version__",
+    "HARParams",
+    "HawkesParams",
+    "bipower_variation",
+    "bipower_variation_series",
+    "branching_ratio",
+    "fit_har",
+    "fit_hawkes_mle",
+    "har_features",
+    "har_forecast",
+    "har_forecast_path",
+    "hawkes_compensator",
+    "hawkes_intensity_path",
+    "hawkes_log_likelihood",
+    "hawkes_residual_analysis",
+    "hawkes_simulate",
+    "jump_variation",
+    "jump_variation_series",
+    "realized_variance",
+    "realized_variance_series",
+    *_SKTIME,
+]
+
+
+def __getattr__(name):
+    module = _SKTIME.get(name)
+    if module is None:
+        raise AttributeError(f"module 'hfvol' has no attribute {name!r}")
+    try:
+        import importlib
+
+        return getattr(importlib.import_module(module), name)
+    except ImportError as exc:
+        if "sktime" in str(exc):
+            raise ImportError(
+                f"hfvol.{name} is an sktime estimator; install it with pip install 'hfvol[sktime]'"
+            ) from exc
+        raise
+
+
+def __dir__():
+    return sorted(__all__)

hfvol/forecasting.py

@@ -0,0 +1,153 @@
+"""sktime forecaster for the HAR-RV model (Corsi 2009).
+
+Built from sktime's ``extension_templates/forecasting.py``. Requires sktime
+(``pip install hfvol[sktime]``); :mod:`hfvol.har` does the work.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sktime.forecasting.base import BaseForecaster
+
+from hfvol.har import fit_har, har_forecast_path
+
+__all__ = ["HARForecaster"]
+
+
+class HARForecaster(BaseForecaster):
+    """Heterogeneous autoregressive (HAR-RV) forecaster for realized variance.
+
+    ``RV_{t+1} = c + b_d RV_t + b_w mean(RV_{t-w+1..t}) + b_m mean(RV_{t-m+1..t})``
+
+    fitted by OLS. Multi-step forecasts iterate the recursion, feeding each
+    forecast back in as the newest observation. Forecasts are clipped at zero.
+
+    Feed it a daily (or other per-period) realized measure, for example the
+    output of :class:`hfvol.RealizedVariance`.
+
+    Parameters
+    ----------
+    window_w : int, default 5
+        Length of the "weekly" mean.
+    window_m : int, default 22
+        Length of the "monthly" mean. ``fit`` needs at least ``window_m + 4``
+        observations.
+
+    Attributes
+    ----------
+    params_ : hfvol.har.HARParams
+        Fitted coefficients.
+    coef_ : pd.Series
+        The same coefficients indexed by ``["const", "rv_d", "rv_w", "rv_m"]``.
+
+    References
+    ----------
+    Corsi, F. (2009). A simple approximate long-memory model of realized
+    volatility. Journal of Financial Econometrics 7(2), 174-196.
+
+    Examples
+    --------
+    >>> import numpy as np, pandas as pd
+    >>> from hfvol import HARForecaster
+    >>> rv = pd.Series(np.random.default_rng(0).gamma(2.0, 1e-4, 300))
+    >>> HARForecaster().fit(rv).predict(fh=[1, 2, 3]).shape
+    (3,)
+    """
+
+    _tags = {
+        "authors": ["Mattbusel"],
+        "maintainers": ["Mattbusel"],
+        "python_dependencies": None,
+        "y_inner_mtype": "pd.Series",
+        "X_inner_mtype": "pd.DataFrame",
+        "capability:multivariate": False,
+        "capability:exogenous": False,
+        "capability:insample": False,
+        "capability:pred_int": False,
+        "capability:missing_values": False,
+        "requires-fh-in-fit": False,
+        "X-y-must-have-same-index": True,
+        "enforce_index_type": None,
+        "fit_is_empty": False,
+        "capability:update": True,
+    }
+
+    def __init__(self, window_w=5, window_m=22):
+        self.window_w = window_w
+        self.window_m = window_m
+        super().__init__()
+
+    def _fit(self, y, X=None, fh=None):
+        """Fit the HAR coefficients by OLS.
+
+        Parameters
+        ----------
+        y : pd.Series
+            Realized variance (or another positive realized measure).
+        X : ignored
+        fh : ignored
+
+        Returns
+        -------
+        self
+        """
+        self._cur_y = y.copy()
+        self._refit()
+        return self
+
+    def _refit(self):
+        y = self._cur_y.to_numpy(dtype=float)
+        self.params_ = fit_har(y, self.window_w, self.window_m)
+        self.coef_ = pd.Series(self.params_.as_array(), index=["const", "rv_d", "rv_w", "rv_m"])
+
+    def _update(self, y, X=None, update_params=True):
+        """Append new observations; refit the coefficients if ``update_params``.
+
+        Parameters
+        ----------
+        y : pd.Series
+            New observations after the current cutoff.
+        X : ignored
+        update_params : bool, default True
+
+        Returns
+        -------
+        self
+        """
+        combined = pd.concat([self._cur_y, y])
+        self._cur_y = combined[~combined.index.duplicated(keep="last")].sort_index()
+        if update_params:
+            self._refit()
+        return self
+
+    def _predict(self, fh, X=None):
+        """Forecast the realized measure at ``fh``.
+
+        Parameters
+        ----------
+        fh : ForecastingHorizon
+            Out-of-sample horizon (steps after the cutoff).
+        X : ignored
+
+        Returns
+        -------
+        pd.Series
+        """
+        steps = np.asarray(fh.to_relative(self.cutoff), dtype=int)
+        if np.any(steps < 1):
+            raise NotImplementedError("HARForecaster does not make in-sample predictions")
+        path = har_forecast_path(
+            self.params_,
+            self._cur_y.to_numpy(dtype=float),
+            horizon=int(steps.max()),
+            window_w=self.window_w,
+            window_m=self.window_m,
+        )
+        index = fh.to_absolute_index(self.cutoff)
+        return pd.Series(path[steps - 1], index=index, name=self._cur_y.name)
+
+    @classmethod
+    def get_test_params(cls, parameter_set="default"):
+        """Return testing parameter settings for the estimator."""
+        return [{"window_w": 2, "window_m": 4}, {"window_w": 3, "window_m": 6}]

hfvol/har.py

@@ -0,0 +1,114 @@
+"""HAR-RV: the heterogeneous autoregressive model of realized volatility.
+
+``RV_{t+1} = c + b_d RV_t + b_w RV_t^{(w)} + b_m RV_t^{(m)} + e_{t+1}``
+
+where ``RV^{(w)}`` and ``RV^{(m)}`` are the means of the last ``window_w`` (5)
+and ``window_m`` (22) daily values, estimated by OLS.
+
+Reference: Corsi, F. (2009). A simple approximate long-memory model of realized
+volatility. Journal of Financial Econometrics 7(2), 174-196.
+
+Derived from srfm-lab ``lib/math/volatility_models.py`` (MIT). See docs/provenance.md.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = ["HARParams", "har_features", "fit_har", "har_forecast", "har_forecast_path"]
+
+
+@dataclass(frozen=True)
+class HARParams:
+    """Fitted HAR-RV coefficients."""
+
+    mu: float  #: intercept
+    beta_d: float  #: daily coefficient
+    beta_w: float  #: weekly (``window_w`` mean) coefficient
+    beta_m: float  #: monthly (``window_m`` mean) coefficient
+
+    def as_array(self) -> np.ndarray:
+        return np.array([self.mu, self.beta_d, self.beta_w, self.beta_m])
+
+
+def _check_windows(window_w: int, window_m: int) -> None:
+    if not (1 <= int(window_w) <= int(window_m)):
+        raise ValueError(f"need 1 <= window_w <= window_m, got {window_w}, {window_m}")
+
+
+def har_features(rv_series, window_w: int = 5, window_m: int = 22) -> np.ndarray:
+    """HAR design matrix ``[1, RV_d, RV_w, RV_m]``, shape ``(n - window_m, 4)``.
+
+    Row ``k`` holds the regressors known at the end of day ``window_m + k - 1``,
+    i.e. it is used to predict ``rv_series[window_m + k]``.
+    """
+    _check_windows(window_w, window_m)
+    rv = np.asarray(rv_series, dtype=float)
+    n = len(rv)
+    if n <= window_m:
+        return np.empty((0, 4))
+    c = np.concatenate([[0.0], np.cumsum(rv)])
+    i = np.arange(window_m, n)
+    rv_d = rv[i - 1]
+    rv_w = (c[i] - c[i - window_w]) / window_w
+    rv_m = (c[i] - c[i - window_m]) / window_m
+    return np.column_stack([np.ones(len(i)), rv_d, rv_w, rv_m])
+
+
+def fit_har(rv_series, window_w: int = 5, window_m: int = 22) -> HARParams:
+    """Estimate HAR-RV coefficients by ordinary least squares."""
+    rv = np.asarray(rv_series, dtype=float)
+    X = har_features(rv, window_w, window_m)
+    if X.shape[0] < 4:
+        raise ValueError(
+            f"HAR needs at least window_m + 4 = {window_m + 4} observations, got {len(rv)}"
+        )
+    y = rv[window_m:]
+    coef, *_ = np.linalg.lstsq(X, y, rcond=None)
+    return HARParams(*(float(v) for v in coef))
+
+
+def har_forecast_path(
+    params: HARParams,
+    rv_series,
+    horizon: int = 1,
+    window_w: int = 5,
+    window_m: int = 22,
+) -> np.ndarray:
+    """Forecasts for steps ``1..horizon``, iterating the HAR recursion.
+
+    Each step feeds the previous (unclipped) forecast back in as the newest
+    observation. Returned values are clipped at zero.
+    """
+    _check_windows(window_w, window_m)
+    horizon = int(horizon)
+    if horizon < 1:
+        raise ValueError(f"horizon must be >= 1, got {horizon}")
+    hist = list(np.asarray(rv_series, dtype=float)[-window_m:])
+    if len(hist) < window_m:
+        raise ValueError(f"need at least window_m = {window_m} observations")
+    out = np.empty(horizon)
+    for h in range(horizon):
+        arr = np.asarray(hist[-window_m:])
+        fc = (
+            params.mu
+            + params.beta_d * arr[-1]
+            + params.beta_w * arr[-window_w:].mean()
+            + params.beta_m * arr.mean()
+        )
+        out[h] = fc
+        hist.append(fc)
+    return np.maximum(out, 0.0)
+
+
+def har_forecast(
+    params: HARParams,
+    rv_series,
+    horizon: int = 1,
+    window_w: int = 5,
+    window_m: int = 22,
+) -> float:
+    """Forecast ``horizon`` steps ahead (the last value of :func:`har_forecast_path`)."""
+    return float(har_forecast_path(params, rv_series, horizon, window_w, window_m)[-1])

hfvol/hawkes.py

@@ -0,0 +1,323 @@
+"""Univariate Hawkes process with an exponential kernel.
+
+Intensity::
+
+    lambda(t) = mu + sum_{t_i < t} alpha * exp(-beta * (t - t_i))
+
+``alpha`` is the jump in intensity per event and ``n = alpha / beta`` is the
+branching ratio (the expected number of direct offspring per event). The process
+is stationary when ``n < 1`` and then has mean rate ``mu / (1 - n)``.
+
+Everything here runs in O(n) using the standard recursion for exponential
+kernels (Ozaki 1979), so no C++ build is needed.
+
+References
+----------
+Hawkes, A. G. (1971). Spectra of some self-exciting and mutually exciting point
+processes. Biometrika 58(1), 83-90.
+
+Ozaki, T. (1979). Maximum likelihood estimation of Hawkes' self-exciting point
+processes. Annals of the Institute of Statistical Mathematics 31, 145-155.
+
+Ogata, Y. (1981). On Lewis' simulation method for point processes. IEEE
+Transactions on Information Theory 27(1), 23-31.
+
+Derived from srfm-lab ``lib/math/hawkes_process.py`` (MIT). See docs/provenance.md.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Tuple, Union
+
+import numpy as np
+
+__all__ = [
+    "HawkesParams",
+    "hawkes_simulate",
+    "hawkes_intensity_path",
+    "hawkes_compensator",
+    "hawkes_log_likelihood",
+    "fit_hawkes_mle",
+    "branching_ratio",
+    "hawkes_residual_analysis",
+]
+
+RandomState = Union[None, int, np.random.Generator]
+
+
+def _rng(random_state: RandomState) -> np.random.Generator:
+    if isinstance(random_state, np.random.Generator):
+        return random_state
+    return np.random.default_rng(random_state)
+
+
+@dataclass(frozen=True)
+class HawkesParams:
+    """Parameters of a univariate exponential-kernel Hawkes process."""
+
+    mu: float = 0.5  #: baseline intensity
+    alpha: float = 0.6  #: jump in intensity per event
+    beta: float = 1.0  #: decay rate
+
+    @property
+    def branching_ratio(self) -> float:
+        """``alpha / beta``; must be < 1 for stationarity."""
+        return self.alpha / self.beta if self.beta > 0 else float("inf")
+
+    @property
+    def is_stationary(self) -> bool:
+        return self.branching_ratio < 1.0
+
+    @property
+    def unconditional_intensity(self) -> float:
+        """Mean event rate ``mu / (1 - n)`` (``inf`` if not stationary)."""
+        n = self.branching_ratio
+        return self.mu / (1.0 - n) if n < 1 else float("inf")
+
+    def _validate(self) -> None:
+        if not (self.mu > 0 and self.alpha >= 0 and self.beta > 0):
+            raise ValueError(f"need mu > 0, alpha >= 0, beta > 0; got {self}")
+
+
+def _as_events(events) -> np.ndarray:
+    ev = np.asarray(events, dtype=float).ravel()
+    if ev.size > 1 and np.any(np.diff(ev) < 0):
+        raise ValueError("event times must be sorted in non-decreasing order")
+    return ev
+
+
+def _excitation_at_events(events: np.ndarray, beta: float) -> np.ndarray:
+    """``R_i = sum_{t_j < t_i} exp(-beta (t_i - t_j))`` for every event ``i``.
+
+    Only strictly earlier events count, so events sharing a time stamp do not
+    excite each other. With tied stamps (binned data) counting them would make
+    the likelihood unbounded: ``alpha, beta -> inf`` with ``alpha / beta`` fixed
+    sends ``log(mu + alpha)`` to infinity at every tie.
+    """
+    n = len(events)
+    R = np.zeros(n)
+    if n > 1:
+        prev_t = events[0]
+        m = 1  # events at prev_t
+        for i in range(1, n):
+            t = events[i]
+            if t == prev_t:
+                R[i] = R[i - 1]
+                m += 1
+            else:
+                R[i] = math.exp(-beta * (t - prev_t)) * (R[i - 1] + m)
+                prev_t = t
+                m = 1
+    return R
+
+
+def _excitation_after_events(events: np.ndarray, beta: float) -> np.ndarray:
+    """``A_k = sum_{j <= k} exp(-beta (t_k - t_j))``: excitation just after event ``k``.
+
+    Only meaningful at the last event of each tie group, which is where
+    ``searchsorted`` lands.
+    """
+    R = _excitation_at_events(events, beta)
+    first = np.searchsorted(events, events, side="left")
+    return R + (np.arange(len(events)) - first + 1)
+
+
+def hawkes_simulate(
+    params: HawkesParams,
+    T: float,
+    rng: RandomState = None,
+) -> np.ndarray:
+    """Simulate event times on ``[0, T]`` with Ogata's thinning algorithm.
+
+    ``rng`` may be a seed or a ``numpy.random.Generator``.
+    """
+    params._validate()
+    if not params.is_stationary:
+        raise ValueError("branching ratio alpha / beta must be < 1 for simulation")
+    gen = _rng(rng)
+    mu, alpha, beta = params.mu, params.alpha, params.beta
+
+    events = []
+    t = 0.0
+    t_last = 0.0
+    excite = 0.0  # sum_j alpha * exp(-beta (t_last - t_j)), evaluated just after t_last
+    lam_bar = mu
+    while True:
+        t += gen.exponential(1.0 / lam_bar)
+        if t > T:
+            break
+        lam_t = mu + excite * math.exp(-beta * (t - t_last))
+        if gen.uniform(0.0, lam_bar) <= lam_t:
+            events.append(t)
+            excite = lam_t - mu + alpha
+            t_last = t
+            lam_bar = lam_t + alpha
+        else:
+            lam_bar = lam_t
+    return np.asarray(events)
+
+
+def hawkes_intensity_path(
+    events,
+    params: HawkesParams,
+    times,
+    include_current: bool = True,
+) -> np.ndarray:
+    """Intensity ``lambda(t)`` on an arbitrary time grid.
+
+    With ``include_current=True`` (the srfm-lab behaviour) an event at exactly
+    ``t`` is counted, which gives the right-continuous intensity. Use
+    ``include_current=False`` for the predictable (left-continuous) intensity,
+    the one to use as a forecasting feature since it has no look-ahead.
+    """
+    ev = _as_events(events)
+    t = np.asarray(times, dtype=float)
+    out = np.full(t.shape, float(params.mu))
+    if ev.size == 0:
+        return out
+    A = _excitation_after_events(ev, params.beta)
+    side = "right" if include_current else "left"
+    k = np.searchsorted(ev, t, side=side) - 1
+    has = k >= 0
+    kk = k[has]
+    out[has] += params.alpha * A[kk] * np.exp(-params.beta * (t[has] - ev[kk]))
+    return out
+
+
+def hawkes_compensator(events, params: HawkesParams, times) -> np.ndarray:
+    """Integrated intensity ``Lambda(t) = int_0^t lambda(s) ds`` on a time grid."""
+    ev = _as_events(events)
+    t = np.asarray(times, dtype=float)
+    out = params.mu * t
+    if ev.size == 0:
+        return out
+    A = _excitation_after_events(ev, params.beta)
+    k = np.searchsorted(ev, t, side="right") - 1
+    has = k >= 0
+    kk = k[has]
+    # sum_{t_i <= t} (1 - exp(-beta (t - t_i))) = (k + 1) - A_k exp(-beta (t - t_k))
+    remaining = A[kk] * np.exp(-params.beta * (t[has] - ev[kk]))
+    out[has] += (params.alpha / params.beta) * ((kk + 1) - remaining)
+    return out
+
+
+def hawkes_log_likelihood(events, T: float, params: HawkesParams) -> float:
+    """Exact log-likelihood on ``[0, T]``.
+
+    ``LL = sum_i log lambda(t_i) - mu T - (alpha / beta) sum_i (1 - exp(-beta (T - t_i)))``
+
+    ``lambda(t_i)`` counts only events strictly before ``t_i``, so events that
+    share a time stamp (binned data) do not excite each other.
+
+    Returns ``-1e12`` for invalid or non-stationary parameters (convenient for
+    unconstrained optimisers), as in srfm-lab.
+    """
+    p = params
+    if not (p.mu > 0 and p.alpha >= 0 and p.beta > 0) or not p.is_stationary:
+        return -1e12
+    ev = _as_events(events)
+    if ev.size == 0:
+        return float(-p.mu * T)
+    lam = p.mu + p.alpha * _excitation_at_events(ev, p.beta)
+    log_lk = np.sum(np.log(np.maximum(lam, 1e-300)))
+    integral = p.mu * T + (p.alpha / p.beta) * np.sum(1.0 - np.exp(-p.beta * (T - ev)))
+    return float(log_lk - integral)
+
+
+def _unpack(x) -> HawkesParams:
+    log_mu, log_beta, logit_n = x
+    beta = math.exp(log_beta)
+    n = 1.0 / (1.0 + math.exp(-logit_n))
+    return HawkesParams(mu=math.exp(log_mu), alpha=n * beta, beta=beta)
+
+
+def fit_hawkes_mle(
+    events,
+    T: float,
+    n_restarts: int = 10,
+    rng: RandomState = None,
+) -> Tuple[HawkesParams, float]:
+    """Maximum-likelihood fit of ``(mu, alpha, beta)``.
+
+    Nelder-Mead over ``(log mu, log beta, logit n)``, which keeps every candidate
+    stationary, from ``n_restarts`` random starts scaled to the observed event
+    rate. Returns ``(params, log_likelihood)``. Requires scipy.
+    """
+    try:
+        from scipy.optimize import minimize
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("fit_hawkes_mle needs scipy: pip install hfvol[scipy]") from exc
+
+    ev = _as_events(events)
+    if T <= 0:
+        raise ValueError(f"T must be positive, got {T}")
+    gen = _rng(rng)
+    rate = max(len(ev), 1) / T
+
+    def neg_ll(x):
+        if not np.all(np.isfinite(x)) or np.any(np.abs(x) > 50):
+            return 1e12
+        return -hawkes_log_likelihood(ev, T, _unpack(x))
+
+    best_params, best_ll = HawkesParams(mu=rate, alpha=0.0, beta=1.0), -np.inf
+    for k in range(max(int(n_restarts), 1)):
+        if k == 0:
+            n0, beta0 = 0.5, 2.0 * rate
+        else:
+            n0 = gen.uniform(0.05, 0.9)
+            beta0 = rate * math.exp(gen.uniform(-2.0, 3.0))
+        mu0 = max(rate * (1.0 - n0), 1e-12)
+        x0 = [math.log(mu0), math.log(beta0), math.log(n0 / (1.0 - n0))]
+        res = minimize(
+            neg_ll,
+            x0=x0,
+            method="Nelder-Mead",
+            options={"maxiter": 4000, "xatol": 1e-8, "fatol": 1e-10},
+        )
+        ll = -float(res.fun)
+        if np.isfinite(ll) and ll > best_ll:
+            best_ll, best_params = ll, _unpack(res.x)
+    return best_params, float(best_ll)
+
+
+def branching_ratio(events, T: float, n_restarts: int = 10, rng: RandomState = None) -> float:
+    """MLE branching ratio ``alpha / beta`` clipped to ``[0, 1]``.
+
+    Values near 1 mean most events are triggered by earlier events rather than
+    by the baseline (high reflexivity).
+    """
+    params, _ = fit_hawkes_mle(events, T, n_restarts=n_restarts, rng=rng)
+    return float(np.clip(params.branching_ratio, 0.0, 1.0))
+
+
+def hawkes_residual_analysis(events, T: float, params: HawkesParams) -> dict:
+    """Time-rescaling goodness of fit.
+
+    If the model is right, the compensator increments
+    ``Lambda(t_i) - Lambda(t_{i-1})`` (with ``Lambda(t_0) = 0``) are iid Exp(1).
+    Returns the Kolmogorov-Smirnov statistic and p-value against Exp(1) plus the
+    residual mean and standard deviation (both 1 under the model). Requires scipy.
+    """
+    ev = _as_events(events)
+    if ev.size < 2:
+        return {
+            "ks_statistic": float("nan"),
+            "ks_pvalue": float("nan"),
+            "mean_residual": float("nan"),
+            "std_residual": float("nan"),
+            "well_fit": False,
+        }
+    from scipy.stats import kstest
+
+    lam_cum = hawkes_compensator(ev, params, ev)
+    residuals = np.diff(np.concatenate([[0.0], lam_cum]))
+    ks_stat, ks_pvalue = kstest(residuals, "expon")
+    return {
+        "ks_statistic": float(ks_stat),
+        "ks_pvalue": float(ks_pvalue),
+        "mean_residual": float(residuals.mean()),
+        "std_residual": float(residuals.std()),
+        "well_fit": bool(ks_pvalue > 0.05),
+    }