The ML.EXPLAIN_FORECAST function

This document describes the ML.EXPLAIN_FORECAST function, which lets you generate forecasts that are based on a trained time series model. It only works on ARIMA_PLUS models with the training option decompose_time_series enabled or on ARIMA_PLUS_XREG models. The ML.EXPLAIN_FORECAST function encompasses the ML.FORECAST function because its output is a superset of the results of ML.FORECAST.

Syntax

# `ARIMA_PLUS` models:
ML.EXPLAIN_FORECAST(
  MODEL `project_id.dataset.model_name`,
  STRUCT(
    [horizon AS horizon]
    [, confidence_level AS confidence_level]))

# `ARIMA_PLUS_XREG` model:
ML.EXPLAIN_FORECAST(
  MODEL `project_id.dataset.model_name`,
  STRUCT(
    [horizon AS horizon]
    [, confidence_level AS confidence_level]),
    { TABLE `project_id.dataset.table` | (query_statement) })

Arguments

ML.EXPLAIN_FORECAST takes the following arguments:

Output

The ML.EXPLAIN_FORECAST function returns the following columns:

Mathematical explanation

The mathematical relationship of the output columns is described in the following sections.

time_series_data

The time_series_data value is decomposed into several components to get better explainability. For ARIMA_PLUS models, the component list includes the following components for better explainability:

For ARIMA_PLUS_XREG models, this list also includes the feature contribution attribution_feature_name. For future data, the spikes_and_dips, step_changes, and residuals values aren't applicable.

The following formulas show what components make up the time_series_data value for historical and forecast data for time series models

time_series_adjusted_data

The time_series_adjusted_data value is the value that remains after cleaning spikes and dips, adjusting the step changes, and removing the residuals. Its formula is the same for both historical and forecast data.

holiday_effect

The holiday_effect_holiday_name value is a subcomponent . The holiday_effect value is the sum of all the holiday_effect_holiday_name values. For example, if you specify holidays xmas and mlk, the formula is holiday_effect = holiday_effect_xmas + holiday_effect_mlk.

ARIMA_PLUS example

The following example forecasts 30 time points with a confidence level of 0.8:

SELECT
  *
FROM
  ML.EXPLAIN_FORECAST(MODEL `mydataset.mymodel`,
    STRUCT(30 AS horizon, 0.8 AS confidence_level))

ARIMA_PLUS_XREG example

The following example forecasts 30 time points with a confidence level of 0.8 with future features:

SELECT
  *
FROM
  ML.EXPLAIN_FORECAST(MODEL `mydataset.mymodel`,
    STRUCT(30 AS horizon, 0.8 AS confidence_level),
    (SELECT * FROM `mydataset.mytable`))

What's next