Model Selection

Cross-validation for SuperGLM models with pluggable splitters, multiple scoring metrics, and out-of-fold prediction support.

cross_validate(model, X, y, *, cv, sample_weight=None, offset=None, groups=None, fit_mode='fit', scoring=('deviance',), return_estimators=False, return_oof=False, error_score=np.nan)

Cross-validate a SuperGLM model with a pluggable splitter.

Parameters:

Name	Type	Description	Default
model	SuperGLM	An unfitted (or fitted) model. A fresh clone is created for each fold; the input model is never mutated.	required
X	pandas or eager Polars DataFrame	Feature matrix.	required
y	array - like	Response variable.	required
cv	splitter	Object with a .split(X, y, groups) method yielding (train_idx, test_idx) tuples. Any sklearn splitter works.	required
sample_weight	array - like	Frequency weights, sliced per fold.	None
offset	array - like	Offset term, sliced per fold.	None
groups	array - like	Group labels forwarded to cv.split().	None
fit_mode	('fit', 'fit_reml')	Which fit method to call on each fold estimator.	"fit"
scoring	str, callable, or sequence thereof	Metrics to evaluate. Built-in: "deviance", "nll", "gini". Callables must follow scorer(model, X, y, *, sample_weight, offset) -> float | dict.	('deviance',)
return_estimators	bool	If True, keep the fitted model from each fold.	False
return_oof	bool	If True, collect out-of-fold predictions.	False
error_score	float or 'raise'	Value to assign when a fold fails. "raise" propagates the error.	nan

Returns:

Type	Description
CrossValidationResult	Per-fold scores, mean/std aggregates, and optionally out-of-fold predictions and fitted estimators.

CrossValidationResult dataclass

Structured result from :func:cross_validate.

Attributes:

Name	Type	Description
fold_scores	DataFrame	One row per fold with columns: fold, n_train, n_test, fit_time_s, score_time_s, converged, n_iter, effective_df, plus one column per requested metric.
mean_scores	dict	Equal-weight mean of each metric across folds.
pooled_scores	dict	Supported overall pooled metrics, computed as ratio-of-sums rather than mean-of-fold-ratios.
std_scores	dict	Standard deviation of each metric across folds.
fold_indices	list[tuple[ndarray, ndarray]] or None	Per-fold (train_idx, test_idx) pairs from the CV splitter.
curve_similarity	dict or None	Fold-by-fold term similarity diagnostics for comparable main effects.
oof_predictions	ndarray or None	Out-of-fold predictions (response scale), same length as y. None unless return_oof=True.
estimators	list or None	Fitted model per fold. None unless return_estimators=True.

plot_terms_by_fold(X, *, sample_weight=None, terms=None, engine='plotly', **kwargs)

Plot fold-specific main effects using the shared comparison engine.