cross_val

Cross-validate a mixed model with group-aware splits. Supports leave-one-group-out (LOGO) and k-fold strategies, with pluggable scoring metrics.

cross_val

cross_val(formula, data, groups, cv='logo', k=5, scoring='rmse', return_models=False, **fit_kwargs)[source]

Cross-validate a mixed model with group-aware splits.

Parameters:

  • formula – Fixed-effects formula, e.g. "y ~ x1 + x2".

  • data – DataFrame (pandas, polars, or any narwhals-compatible frame).

  • groups – Column name of the grouping variable (used both as the random effect grouping factor and to define CV folds).

  • cv – "logo" for leave-one-group-out or "kfold" for k-fold.

  • k – Number of folds for cv="kfold".

  • scoring – "rmse" (default), "mae", or a callable scorer(y_true, y_pred) -> float.

  • return_models – If True, each fold’s fitted model and split metadata are stored in CVResult.fold_results.

  • **fit_kwargs – Extra keyword arguments forwarded to interlace.fit() (e.g. random, method, optimizer).

Return type:

CVResult

Returns:

CVResult – Container with .scores (per-fold array), .mean, and .std properties. When return_models=True, .fold_results holds per-fold dicts with "model", "y_true", "y_pred".

Parameters:

  • formula (str)

  • data (Any)

  • groups (str)

  • cv (str)

  • k (int)

  • scoring (str | Callable[[...], float])

  • return_models (bool)

  • fit_kwargs (Any)

Examples

>>> cv = interlace.cross_val("y ~ x", df, groups="g", cv="logo")
>>> cv.mean

CVResult

class CVResult(scores, fold_results=None)[source]

Result of a cross-validation run.

Parameters:

  • scores (ndarray)

  • fold_results (list[dict[str, Any]] | None)

scores

Per-fold scores as a 1-D numpy array.

fold_results

Optional list of per-fold dicts (returned when return_models=True). Each dict contains "model" (fitted result), "train_groups", "test_groups", "y_true", and "y_pred".

Examples

>>> cv = interlace.cross_val("y ~ x", df, groups="g")
>>> cv.mean
>>> cv.std
scores: ndarray
fold_results: list[dict[str, Any]] | None = None
property mean: float
property std: float

Example

import interlace

# Leave-one-group-out cross-validation
cv = interlace.cross_val(
    "rt ~ condition",
    data=df,
    groups="subject",
    cv="logo",
    scoring="rmse",
)
print(cv.mean_score)   # mean RMSE across folds
print(cv.scores)       # per-fold scores

# k-fold with MAE
cv_k = interlace.cross_val(
    "rt ~ condition",
    data=df,
    groups="subject",
    cv="kfold",
    k=5,
    scoring="mae",
)
print(cv_k.mean_score)

See also