cross_val_score¶

def cross_val_score(
    forecaster: BaseForecaster,
    y: pl.DataFrame,
    X_actual: pl.DataFrame | None = None,
    forecasting_horizon: int = 1,
    *,
    X_future: pl.DataFrame | None = None,
    X_forecast: pl.DataFrame | None = None,
    scoring: BaseScorer,
    cv: int | BaseSplitter | None = 5,
    predict_forecasting_horizon: int | None = None,
    predict_stride: int | None = None,
    n_jobs: int | None = None,
    verbose: int = 0,
    pre_dispatch: str | int = "2*n_jobs",
    error_score: float | str = np.nan,
) -> pl.DataFrame:
    """Evaluate a forecaster by cross-validation and return test scores.

    Parameters
    ----------
    forecaster : BaseForecaster
        The forecaster to evaluate.
    y : pl.DataFrame
        Target time series with a ``"time"`` column.
    X_actual : pl.DataFrame or None, default=None
        Actual feature observations with a ``"time"`` column.
    forecasting_horizon : int, default=1
        Number of time steps to forecast.
    X_future : pl.DataFrame or None, default=None
        Known future features with a ``"time"`` column.
    X_forecast : pl.DataFrame or None, default=None
        External forecasts with ``"vintage_time"`` and ``"time"``
        columns.
    scoring : BaseScorer
        Single scorer used to evaluate predictions.  Dicts of scorers
        are rejected; use ``cross_validate`` for multi-metric
        evaluation.
    cv : int, BaseSplitter, or None, default=5
        Cross-validation splitting strategy. ``None`` or int creates
        an ``ExpandingWindowSplitter``.
    predict_forecasting_horizon : int or None, default=None
        Override forecasting horizon for ``observe_predict``.
        ``None`` uses the forecaster's fit-time default.
    predict_stride : int or None, default=None
        Override stride for ``observe_predict``.
        ``None`` uses the forecaster's default.
    n_jobs : int or None, default=None
        Number of parallel jobs.
    verbose : int, default=0
        Verbosity level.
    pre_dispatch : str or int, default="2*n_jobs"
        Controls pre-dispatched jobs for parallel execution.
    error_score : float or "raise", default=np.nan
        Value to assign if an error occurs during fitting or scoring.
        If ``"raise"``, the error is re-raised immediately.

    Returns
    -------
    pl.DataFrame
        DataFrame with columns ``split`` (int, 0-indexed fold
        identifier) and ``score`` (float, test score per fold).

        Scores from lower-is-better scorers (e.g. MAE, RMSE) are negated
        so that higher values always indicate better performance,
        following the sklearn sign convention.
    """
    if isinstance(scoring, dict):
        raise ValueError(
            "cross_val_score does not accept dict scoring. Use cross_validate for multi-metric evaluation."
        )

    cv_results = cast(
        pl.DataFrame,
        cross_validate(
            forecaster,
            y,
            X_actual=X_actual,
            forecasting_horizon=forecasting_horizon,
            X_future=X_future,
            X_forecast=X_forecast,
            scoring=scoring,
            cv=cv,
            n_jobs=n_jobs,
            verbose=verbose,
            pre_dispatch=pre_dispatch,
            predict_forecasting_horizon=predict_forecasting_horizon,
            predict_stride=predict_stride,
            error_score=error_score,
        ),
    )
    return cv_results.select("split", pl.col("test_score").alias("score"))