fusionlab.nn.utils.generate_forecast¶

fusionlab.nn.utils.generate_forecast(xtft_model, train_data, dt_col, dynamic_features, future_features=None, static_features=None, test_data=None, mode='quantile', spatial_cols=None, forecast_horizon=4, time_steps=3, q=None, tname=None, forecast_dt=None, savefile=None, verbose=3, **kw)[source]¶

Generate forecast using the XTFT model.

This function uses a pre-trained Keras model to forecast future values based on provided historical data. The model receives three inputs: X_static, X_dynamic, and X_future re-built from train_data, and outputs predictions over a specified forecast horizon.

See more in User Guide.

Parameters:

xtft_model (object) – A validated Keras model instance. It is processed by the validate_keras_model method [1].
train_data (pandas.DataFrame) – The training data containing historical records. Must include the dt_col and all required feature columns.
dt_col (str) – Name of the column representing time. It may be a datetime or numeric column (e.g. "year").
dynamic_features (list of str) – List of dynamic feature column names. They are formatted via columns_manager.
future_features (list of str, optional) – List of future feature names. These columns are tiled over the forecast horizon.
static_features (list of str, optional) – List of static feature names. If not provided, a dummy input is used.
test_data (pandas.DataFrame, optional) – DataFrame containing actual values used for evaluation. If provided, it is used to compute the R² and coverage score for mode='quantile'.
mode (str, optional) – Forecast mode. Must be either "quantile" or "point". In quantile mode, predictions for multiple quantiles (default: [0.1, 0.5, 0.9]) are computed.
spatial_cols (list of str, optional) – List of spatial column names for grouping the data. When provided, forecasts are computed per location; otherwise, a global forecast is performed.
forecast_horizon (int, optional) – Number of future periods to forecast. Default is 4.
time_steps (int, optional) – Number of past time steps to use as input for the model. Default is 3.
q (list of float, optional) – List of quantiles for use in quantile mode. Default is [0.1, 0.5, 0.9]. Each quantile is validated by the assert_ratio function.
tname (str, optional) – Target variable name used for constructing forecast result columns. Defaults to "target".
forecast_dt (list or str, optional) – List of forecast dates or "auto" to derive dates from dt_col. In auto mode, if dt_col is datetime, frequency is inferred using pd.infer_freq.
savefile (str, optional) – Path to the CSV file where forecast results will be saved. If not provided, a default filename is generated.
verbose (int, optional) – Verbosity level (0-7). Controls the amount of execution output.

Returns:

A DataFrame containing the forecast results. In quantile mode, each forecast period includes columns for each quantile; in point mode, a single prediction column is provided.

Return type:

pandas.DataFrame

Examples

Example refering to Train data only

>>> import os
>>> import pandas as pd
>>> import numpy as np
>>> from fusionlab.nn.transformers import XTFT
>>> from fusionlab.nn.losses import combined_quantile_loss
>>> from fusionlab.nn.utils import generate_forecast
>>>
>>> # Create a dummy training DataFrame with a date column,
>>> # dynamic features "feat1", "feat2", static feature "stat1",
>>> # and target "price".
>>> date_rng = pd.date_range(start="2020-01-01", periods=50, freq="D")
>>> train_df = pd.DataFrame({
...     "date": date_rng,
...     "feat1": np.random.rand(50),
...     "feat2": np.random.rand(50),
...     "stat1": np.random.rand(50),
...     "price": np.random.rand(50)
... })
>>>
>>> # Prepare a dummy XTFT model with example parameters.
>>> # Note: The model expects the following input shapes:
>>> # - X_static: (n_samples, static_input_dim)
>>> # - X_dynamic: (n_samples, time_steps, dynamic_input_dim)
>>> # - X_future:  (n_samples, time_steps, future_input_dim)
>>> my_model = XTFT(
...     static_input_dim=1,           # "stat1"
...     dynamic_input_dim=2,          # "feat1" and "feat2"
...     future_input_dim=1,           # features provided for dim1
...     forecast_horizon=5,           # Forecasting 5 periods ahead
...     quantiles=[0.1, 0.5, 0.9],
...     embed_dim=16,
...     max_window_size=3,
...     memory_size=50,
...     num_heads=2,
...     dropout_rate=0.1,
...     lstm_units=32,
...     attention_units=32,
...     hidden_units=16
... )
>>> my_model.compile(optimizer="adam")
>>>
>>> # Create dummy input arrays for model fitting.
>>> # For simplicity, assume time_steps = 3 and use random data.
>>> X_static = train_df[["stat1"]].values      # shape: (50, 1)
>>> # Create a dummy dynamic input array of shape (50, 3, 2)
>>> X_dynamic = np.random.rand(50, 3, 2)
>>> # Create a dummy features
>>> X_future = np.random.rand(50, 3, 1)
>>> # Create dummy target output from "price"
>>> y_array = train_df["price"].values.reshape(50, 1, 1)
>>>
>>> # Fit the model on the dummy data.
>>> my_model.fit(
...     x=[X_static, X_dynamic, X_future],
...     y=y_array,
...     epochs=1,
...     batch_size=8
... )
>>>
>>> # Generate forecast using the generate_forecast function.
>>> forecast = generate_forecast(
...     xtft_model=my_model,
...     train_data=train_df,
...     dt_col="date",
...     dynamic_features=["feat1", "feat2"],
...     static_features=["stat1"],
...     forecast_horizon=5,
...     time_steps=3,
...     tname="price",
...     mode="quantile",
...     verbose=3
... )
>>> print(forecast.head())

Example refering to Test data included.

>>> # Create a dummy DataFrame with a date column,
>>> # two dynamic features ("feat1", "feat2"), one static feature ("stat1"),
>>> # and target "price".
>>> date_rng = pd.date_range(start="2020-01-01", periods=60, freq="D")
>>> data = {
...     "date": date_rng,
...     "feat1": np.random.rand(60),
...     "feat2": np.random.rand(60),
...     "stat1": np.random.rand(60),
...     "price": np.random.rand(60)
... }
>>> df = pd.DataFrame(data)
>>>
>>> # Split the DataFrame into training and test sets.
>>> # Training data: dates before 2020-02-01
>>> # Test data: dates from 2020-02-01 onward.
>>> train_df = df[df["date"] < "2020-02-01"].copy()
>>> test_df  = df[df["date"] >= "2020-02-01"].copy()
>>>
>>> # Create dummy input arrays for model fitting.
>>> # Assume time_steps = 3.
>>> X_static = train_df[["stat1"]].values      # Shape: (n_train, 1)
>>> X_dynamic = np.random.rand(len(train_df), 3, 2)
>>> X_future  = np.random.rand(len(train_df), 3, 1)
>>> # Create dummy target output from "price".
>>> y_array   = train_df["price"].values.reshape(len(train_df), 1, 1)
>>>
>>> # Instantiate a dummy XTFT model.
>>> my_model = XTFT(
...     static_input_dim=1,           # "stat1"
...     dynamic_input_dim=2,          # "feat1" and "feat2"
...     future_input_dim=1,           # For the provided future feature
...     forecast_horizon=5,           # Forecasting 5 periods ahead
...     quantiles=[0.1, 0.5, 0.9],
...     embed_dim=16,
...     max_window_size=3,
...     memory_size=50,
...     num_heads=2,
...     dropout_rate=0.1,
...     lstm_units=32,
...     attention_units=32,
...     hidden_units=16
... )
>>> loss_fn = combined_quantile_loss(my_model.quantiles)
>>> my_model.compile(optimizer="adam", loss=loss_fn)
>>>
>>> # Fit the model on the training data.
>>> my_model.fit(
...     x=[X_static, X_dynamic, X_future],
...     y=y_array,
...     epochs=1,
...     batch_size=8,
...     callbacks = [early_stopping, model_checkpoint]
... )
>>>
>>> # Generate forecast using the generate_forecast function.
>>> # This example uses test_df for evaluation, which will compute
>>> # metrics like R² Score and Coverage Score.
>>> forecast = generate_forecast(
...     xtft_model=my_model,
...     train_data=train_df,
...     dt_col="date",
...     dynamic_features=["feat1", "feat2"],
...     static_features=["stat1"],
...     test_data=test_df.iloc[:5, :], # to fit the first horizon forecasting.
...     forecast_horizon=5,
...     time_steps=3,
...     tname="price",
...     mode="quantile",
...     verbose=3
... )
>>> print(forecast.head())

Example of Point forecasting

>>> # Create a dummy training DataFrame with a date column,
>>> # two dynamic features ("feat1", "feat2"), one static feature ("stat1"),
>>> # and target "price".
>>> date_rng = pd.date_range(start="2020-01-01", periods=50, freq="D")
>>> train_df = pd.DataFrame({
...     "date": date_rng,
...     "feat1": np.random.rand(50),
...     "feat2": np.random.rand(50),
...     "stat1": np.random.rand(50),
...     "price": np.random.rand(50)
... })
>>>
>>> # Create dummy input arrays for model fitting.
>>> # X_static is derived from the static feature "stat1".
>>> X_static = train_df[["stat1"]].values      # shape: (50, 1)
>>>
>>> # X_dynamic is a dummy dynamic array for "feat1" and "feat2".
>>> # For time_steps = 3, its shape is (50, 3, 2).
>>> X_dynamic = np.random.rand(50, 3, 2)
>>>
>>> # X_future is a dummy array for future features.
>>> # Here, we assume a single future feature with shape (50, 3, 1).
>>> X_future = np.random.rand(50, 3, 1)
>>>
>>> # Create dummy target output from "price".
>>> y_array = train_df["price"].values.reshape(50, 1, 1)
>>>
>>> # Instantiate a dummy XTFT model.
>>> my_model = XTFT(
...     static_input_dim=1,           # "stat1"
...     dynamic_input_dim=2,          # "feat1" and "feat2"
...     future_input_dim=1,           # Provided future feature
...     forecast_horizon=5,           # Forecast 5 periods ahead
...     quantiles=None,    # [0.1, 0.5, 0.9] Not used in point mode
...     embed_dim=16,
...     max_window_size=3,
...     memory_size=50,
...     num_heads=2,
...     dropout_rate=0.1,
...     lstm_units=32,
...     attention_units=32,
...     hidden_units=16
... )
>>> my_model.compile(optimizer="adam")
>>>
>>> # Fit the model on the dummy data.
>>> my_model.fit(
...     x=[X_static, X_dynamic, X_future],
...     y=y_array,
...     epochs=1,
...     batch_size=8
... )
>>>
>>> # Generate forecast using the generate_forecast function in point mode.
>>> forecast = generate_forecast(
...     xtft_model=my_model,
...     train_data=train_df,
...     dt_col="date",
...     dynamic_features=["feat1", "feat2"],
...     static_features=["stat1"],
...     forecast_horizon=5,
...     time_steps=3,
...     tname="price",
...     mode="point",
...     verbose=3
... )
>>> print(forecast.head())

Notes

The function groups data by spatial_cols if provided, and formats features via columns_manager. It validates the time column using check_datetime and uses dummy inputs for missing static or future features. The forecast is produced by invoking xtft_model.predict on a list containing static, dynamic, and future inputs. The predictions are generated as follows:

\[\hat{y}_{t+i} = f\Bigl(X_{\text{static}},\; X_{\text{dynamic}},\; X_{\text{future}}\Bigr)\]

where \(i\) denotes the forecast period.