Module diagnostics 

Analytic diagnostic helpers for LAML/REML optimization.

Production diagnostics inspect analytic invariants only. Runtime fitting, prediction, and diagnostic APIs must consume quantities the optimizer already computes. This module implements diagnostic strategies that identify root causes of gradient pathologies from those analytic quantities:

1. KKT Audit (Envelope Theorem Check): Detects violations of the stationarity assumption used in implicit differentiation.

2. Spectral Bleed Trace: Detects when truncated eigenspace corrections are inconsistent with the penalty’s energy in that subspace.

3. Dual-Ridge Consistency Check: Verifies that the ridge used by the inner solver (PIRLS) matches what the outer gradient calculation assumes.

Structs

ClassificationPredictionMetrics

Production classification scores computed from one prediction vector.

DiagnosticConfig

Configuration for gradient diagnostics

DualRidgeResult

Result of dual-ridge consistency check

EnvelopeAudit

Result of envelope theorem (KKT) audit

GradientDiagnosticReport

Complete diagnostic report for a gradient evaluation

PredictionDiagnostics

Residual diagnostics for observed values and predicted means.

SpectralBleedResult

Result of spectral bleed trace diagnostic

Enums

KktRefusalDiagnosis

Three-way classification of why the cert refused, computed from the H_pen spectrum and the projected residual at the refusing iterate. RankDeficientHPen is the regression canary the nullspace lead’s smooth-construction rework is intended to eliminate; keep this variant intact when extending — it doubles as the user-facing signal for “an unconstrained polynomial null space slipped past absorption.”

Constants

DEFAULT_CALIBRATION_BINS

Number of equal-width probability bins in the bundled expected-calibration error diagnostic.

DEFAULT_GAUSSIAN_SCALE_FLOOR

Smallest standard deviation used by the bundled Gaussian score panel.

DEFAULT_PROBABILITY_CLIP

Probability clipping used by the bundled classification diagnostic panel. Individual log-loss and Nagelkerke APIs accept an explicit clipping value; this named policy keeps the combined Rust/Python diagnostic contract in one core location.

MIN_EIG_DIAG_EVERY

Repeat period within a magnitude bucket for the Hessian-minimum-eigenvalue diagnostic: after the first emission for a bucket, every Nth subsequent invocation also emits.

MIN_EIG_DIAG_THRESHOLD

Threshold below which a positive Hessian minimum eigenvalue is treated as nearly-singular and routed through the rate-limited diagnostic.

Statics

H_MIN_EIG_LOG_BUCKET

Rate-limited diagnostic for Hessian minimum eigenvalue warnings

H_MIN_EIG_LOG_COUNT

Count of should_emit_h_min_eig_diag invocations that have ever been considered for emission; used together with H_MIN_EIG_LOG_BUCKET to rate-limit one diagnostic per decade-magnitude bucket and per MIN_EIG_DIAG_EVERY repeats within the same bucket.

Functions

auc_from_predictions

Tie-aware Mann-Whitney AUC. Observations greater than 0.5 are the positive class, matching the package’s binomial response convention.

binary_log_loss_from_predictions

Mean Bernoulli log loss with a caller-selected probability clip.

brier_from_predictions

Mean squared probability error.

classification_metrics_from_predictions

The package’s standard classification diagnostic panel.

compute_dualridge_check

Check consistency between the ridge used in different stages of computation.

compute_envelopeaudit

Compute the inner KKT residual to detect envelope theorem violations.

diagnostics_from_predictions

Compute prediction residual diagnostics from observed values and predicted means.

expected_calibration_error_from_predictions

Equal-width-bin expected calibration error.

format_top_abs

Diagnostic formatter shared across the outer optimizer and the custom-family fitter: shows the max_items entries of values with largest absolute value, formatted as label=[i:value, ...].

gaussian_log_loss_from_predictions

Gaussian negative log predictive density, allowing either one shared standard deviation or one per observation.

nagelkerke_r_squared_from_log_likelihoods

Nagelkerke’s rescaling of Cox-Snell R² from model/null log likelihoods. Returns None when the null normalization is undefined.

nagelkerke_r_squared_from_predictions

Nagelkerke R² for binomial predictions against an explicit null mean.

precision_recall_auc_from_predictions

Trapezoidal area under the precision-recall curve. Equal predicted scores enter as one threshold group, so row order within a tie cannot change the score.

should_emit_h_min_eig_diag

Rate-limited check for Hessian minimum eigenvalue diagnostics. Returns true if this eigenvalue warrants a diagnostic message.

weighted_auc_from_predictions

Weighted tie-aware Mann-Whitney AUC. Each positive/negative pair carries weight w_positive * w_negative; None is exactly the unit-weight score.