NPKit v2025.09.0 — First Stable Release
Summary
NPKit is a lightweight toolkit providing robust frequentist inference utilities tailored to particle physics and related fields. It offers a clean API for Gaussian models, profile-likelihood ratios, and Neyman belt construction (including Chernoff-bound-aware boundary handling), all built in pure Python with numpy and optional scipy.
⸻
Highlights & Features
Core Functionality
• GaussianModel: Define models y \sim N(\mu(\mathbf{θ}), V) with flexible covariance inputs (scalar, 1D, or 2D), with automated covariance coercion and positive-definite checking.
• GaussianLikelihood: Fast construction of -2\log L for a given dataset and parameter set.
Frequentist Inference Tools
• Profile-likelihood (q_profile): Computes -2\log\Lambda(C) including robust 1D scalar fallback to handle flat likelihoods or stationary points near starting values.
• Neyman Belt Construction:
• build_belt efficiently builds critical-value curves across parameter grids, with optimized reuse of covariance inverse and toy statistics.
• Handles the 1-parameter boundary case correctly—matching the Chernoff ½-mixture distribution at C=0 and recovering Wilks \chi^2 behavior away from boundaries.
Statistical Tools & Testing
• invert_belt: Inverts the belt for observed data to produce Neyman confidence intervals.
• check_coverage: Estimates empirical coverage via repeated toy experiments.
• Automated unit tests for:
• Wilks-regime behavior in identifiable linear models (CI ~ ±1, q_\text{crit} \approx 1).
• Chernoff boundary behavior in non-identifiable C^2 models (quantiles ~ 0.22/2.89 for 1σ/2σ).
Developer Experience & Tooling
• Fully type-annotated, mypy-compatible code:
• Flexible covariance types (CovInput) with internal NDArray[np.float64] casting to satisfy static typing.
• CI support (GitHub Actions): linting with ruff, type-checks with mypy, and unit tests via pytest across Python 3.11–3.12.
• Structural setup courtesy of the Python library template (src layout, pre-commit, formatter config, CalVer versioning).