Forecast

polars_ts.metrics.forecast

Forecast error metrics for time series evaluation.

Implements standard metrics from Ch 19 of "Modern Time Series Forecasting with Python" (2nd Ed.): MAE, RMSE, MAPE, sMAPE, MASE, and CRPS.

mae(df, actual_col='y', predicted_col='y_hat', id_col=None)

Mean Absolute Error.

Parameters

df DataFrame with actual and predicted columns. actual_col Column name for actual values. predicted_col Column name for predicted values. id_col If provided, compute MAE per group and return a DataFrame with columns [id_col, "mae"]. Otherwise return a single float.

Returns

pl.DataFrame | float

rmse(df, actual_col='y', predicted_col='y_hat', id_col=None)

Root Mean Squared Error.

Parameters

df DataFrame with actual and predicted columns. actual_col Column name for actual values. predicted_col Column name for predicted values. id_col If provided, compute RMSE per group.

Returns

pl.DataFrame | float

mape(df, actual_col='y', predicted_col='y_hat', id_col=None)

Mean Absolute Percentage Error.

Undefined when actual values are zero. Rows where actual == 0 are excluded from the computation.

Parameters

df DataFrame with actual and predicted columns. actual_col Column name for actual values. predicted_col Column name for predicted values. id_col If provided, compute MAPE per group.

Returns

pl.DataFrame | float MAPE as a fraction (not percentage). Multiply by 100 for percent.

smape(df, actual_col='y', predicted_col='y_hat', id_col=None)

Symmetric Mean Absolute Percentage Error.

Uses the formula: mean(2 * |actual - predicted| / (|actual| + |predicted|)). Rows where both actual and predicted are zero are excluded.

Parameters

df DataFrame with actual and predicted columns. actual_col Column name for actual values. predicted_col Column name for predicted values. id_col If provided, compute sMAPE per group.

Returns

pl.DataFrame | float sMAPE as a fraction (0 to 2). Multiply by 100 for the 0–200 scale.

mase(df, actual_col='y', predicted_col='y_hat', id_col='unique_id', time_col='ds', season_length=1)

Mean Absolute Scaled Error.

Scales the MAE by the in-sample naive forecast error. A MASE < 1 means the model outperforms the naive (seasonal) baseline.

Parameters

df DataFrame with actual, predicted, and time columns. actual_col Column name for actual values. predicted_col Column name for predicted values. id_col Column identifying each time series. time_col Column with timestamps for ordering. season_length Seasonal period for the naive baseline. Use 1 for non-seasonal data (equivalent to random walk baseline).

Returns

pl.DataFrame | float If multiple series exist (via id_col), returns a DataFrame with columns [id_col, "mase"]. If only one series, returns a float.

crps(df, actual_col='y', quantile_cols=None, quantiles=None, id_col=None)

Continuous Ranked Probability Score (quantile approximation).

Approximates CRPS using a set of quantile forecasts via the pinball (quantile) loss, averaged across quantiles.

Parameters

df DataFrame with actual values and quantile forecast columns. actual_col Column name for actual values. quantile_cols List of column names containing quantile forecasts. If None, auto-detected as columns matching q_* pattern. quantiles List of quantile levels (e.g. [0.1, 0.5, 0.9]) corresponding to quantile_cols. If None, parsed from column names (e.g. "q_0.1" → 0.1). id_col If provided, compute CRPS per group.

Returns

pl.DataFrame | float