Diagnostics

Model diagnostic tools: residual plots, term importance, drop-term analysis, and spline redundancy checks.

Diagnostic plots

plot_diagnostics(model, X, y, sample_weight=None, offset=None, *, n_sim=100, figsize=None, max_points=50000, seed=42, residual_type='auto')

GLM/GAM diagnostic figure with simulation-based Q-Q envelope.

Four panels using quantile residuals (Dunn & Smyth 1996):

1. Q-Q with simulation envelope — observed quantile residuals vs simulated reference, with 95% pointwise envelope.
2. Calibration — exposure-weighted observed vs predicted frequency by equal-exposure bins.
3. Residuals vs Linear Predictor — quantile residuals vs eta.
4. Residual distribution — histogram with N(0,1) overlay.

Parameters:

Name	Type	Description	Default
model	SuperGLM	A fitted SuperGLM model.	required
X	pandas or eager Polars DataFrame	Design matrix.	required
y	NDArray	Response vector.	required
sample_weight	NDArray or None	Optional observation weights (exposure for frequency models).	None
offset	NDArray or None	Optional offset.	None
n_sim	int	Number of simulation replicates for the Q-Q envelope. Default 100.	100
figsize	tuple or None	Figure size (width, height) in inches. Defaults to (10, 8).	None
max_points	int	Threshold for scatter vs hexbin rendering. Default 50,000.	50000
seed	int	Random seed for quantile residuals, simulation, and subsampling.	42
residual_type	str	.. deprecated:: All panels now use quantile residuals. This parameter is ignored. Pass "auto" (default) to suppress the warning.	'auto'

Returns:

Type	Description
Figure	A figure with 4 diagnostic subplots.

Term diagnostics

term_importance(model, X, sample_weight=None)

Weighted variance of each term's contribution to eta.

For each group, computes the centered variance of X_g @ beta_g (the partial linear predictor). Aggregates subgroups at the feature level for select=True.

Parameters:

Name	Type	Description	Default
model	SuperGLM	A fitted model.	required
X	pandas or eager Polars DataFrame	Data to evaluate on (typically training data).	required
sample_weight	array - like	Frequency weights for weighted variance.	None
sample_weight	array - like	Frequency weights for weighted variance.	None

Returns:

Type	Description
DataFrame	Columns: term, feature, subgroup_type, variance_eta, sd_eta, edf, lambda, group_norm.

term_drop_diagnostics(model, X, y, sample_weight=None, offset=None, *, mode='refit', X_val=None, y_val=None)

Drop-term diagnostics wrapper.

Parameters:

Name	Type	Description	Default
mode	('refit', 'holdout')	"refit": calls drop1() and adds delta_aic, delta_bic columns. "holdout": zeros each term's contribution on validation set, computes loss delta without refitting.	"refit"

spline_redundancy(model, X, sample_weight=None)

Spline redundancy diagnostics for all spline features.

Diagnostic-only. No auto-pruning. Interpretation: "try lower k and refit".