StochasticForceInference 2.0.0__py3-none-any.whl

SFI/diagnostics/__init__.py

@@ -0,0 +1,60 @@
+"""SFI diagnostics — residual-consistency checks for inference results.
+
+Top-level user-facing entry point::
+
+    from SFI.diagnostics import assess
+    report = assess(inferer, level="standard")
+    report.print_summary()
+
+The module reuses the fitted force and the inferred constant diffusion to
+recompute standardised residuals (innovations) and test whether they look
+like an independent ``N(0, 1)`` sample:
+
+* mean, variance, skewness and kurtosis (pooled and per spatial
+  component), plus the per-component covariance;
+* Ljung--Box autocorrelation of the residuals and their squares;
+* Kolmogorov--Smirnov normality against ``N(0, 1)``;
+* predicted-vs-realised normalised mean squared error of the force
+  (a sampling-noise-aware chi-square check).
+
+See :mod:`SFI.diagnostics.residual_tests`. Two preset levels are exposed:
+
+* ``"minimal"`` — residual moments only;
+* ``"standard"`` — adds autocorrelation, normality, and MSE consistency.
+
+All backends (overdamped / underdamped, single / multi-particle, SPDE)
+share a unified residual definition: the Euler--Maruyama innovation
+:math:`r_t = \\Delta x_t - F(x_t)\\,\\Delta t` (overdamped) or the
+secant-velocity innovation
+:math:`r_t = \\Delta v_t - F(x_t, v_t)\\,\\Delta t` (underdamped), both
+whitened by :math:`(2 \\bar D \\Delta t)^{-1/2}`.
+
+References
+----------
+Ljung & Box (1978); Diebold, Gunther & Tay (1998).
+"""
+
+from .assess import assess
+from .dynamics_order import DynamicsOrderReport, classify_dynamics
+from .plotting import (
+    plot_dynamics_order,
+    plot_qq,
+    plot_residual_acf,
+    plot_residual_histogram,
+    plot_summary,
+)
+from .report import DiagnosticsReport
+from .residual_tests import parametric_four_point_diagnostic
+
+__all__ = [
+    "assess",
+    "classify_dynamics",
+    "DiagnosticsReport",
+    "DynamicsOrderReport",
+    "parametric_four_point_diagnostic",
+    "plot_dynamics_order",
+    "plot_qq",
+    "plot_residual_acf",
+    "plot_residual_histogram",
+    "plot_summary",
+]

SFI/diagnostics/assess.py

@@ -0,0 +1,87 @@
+"""Top-level diagnostic dispatcher.
+
+See :func:`assess` for the user-facing entry point.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .report import DiagnosticsReport
+from .residual_tests import (
+    autocorrelation_tests,
+    mse_consistency,
+    normality_test,
+    residual_moments,
+)
+from .residuals import build_residuals
+
+_LEVELS = ("minimal", "standard")
+
+
+def assess(
+    inferer,
+    *,
+    level: str = "standard",
+    n_lags: Optional[int] = None,
+    data=None,
+) -> DiagnosticsReport:
+    """Run residual-consistency checks on a fitted inference object.
+
+    Recomputes the standardised residuals (Euler--Maruyama innovations,
+    whitened by the inferred constant diffusion) and tests whether they
+    look like an independent ``N(0, 1)`` sample.
+
+    Parameters
+    ----------
+    inferer :
+        A fitted ``OverdampedLangevinInference`` or
+        ``UnderdampedLangevinInference``. Must have a callable
+        ``force_inferred`` (run e.g. ``infer_force_linear`` first) and an
+        inferred constant diffusion (``A_inv``).
+    level :
+        ``"minimal"`` — pooled residual moments only;
+        ``"standard"`` (default) — adds autocorrelation, normality, and
+        predicted-vs-realised MSE consistency.
+    n_lags :
+        Number of autocorrelation lags. Default ``min(20, n_eff // 5)``.
+    data :
+        Optional independent :class:`~SFI.trajectory.TrajectoryCollection`
+        on which to evaluate the residuals (held-out diagnostics).
+        Default: the training data attached to the inferer.
+
+    Returns
+    -------
+    DiagnosticsReport
+        Container with a ``residuals`` section and ``meta``.
+
+    Notes
+    -----
+    The Euler-style residual is exact for the linear estimators; for the
+    parametric estimators it is an approximation that
+    is still asymptotically consistent under correct specification, so
+    the autocorrelation and normality tests remain valid for flagging
+    misspecification.
+    """
+    if level not in _LEVELS:
+        raise ValueError(f"level must be one of {_LEVELS!r}; got {level!r}.")
+
+    bundle = build_residuals(inferer, data=data)
+
+    residuals: dict = {"moments": residual_moments(bundle)}
+    if level == "standard":
+        residuals["autocorr"] = autocorrelation_tests(bundle, n_lags=n_lags)
+        residuals["normality"] = normality_test(bundle)
+        residuals["mse_consistency"] = mse_consistency(inferer, bundle)
+
+    meta = {
+        "backend": bundle.backend,
+        "regime": bundle.regime,
+        "n_obs": bundle.n_obs,
+        "n_particles": bundle.n_particles,
+        "d": bundle.d,
+        "level": level,
+        "inferer_class": type(inferer).__name__,
+    }
+
+    return DiagnosticsReport(residuals=residuals, meta=meta)