fusionlab.nn.utils.forecast_single_step¶

fusionlab.nn.utils.forecast_single_step(xtft_model, inputs, y=None, dt_col=None, mode='quantile', spatial_cols=None, q=None, tname=None, forecast_dt=None, apply_mask=False, mask_values=None, mask_fill_value=None, savefile=None, verbose=3, **kws)[source]¶

Generate a single-step forecast using the XTFT model.

This function generates a forecast for a single future time step using a pre-trained XTFT deep learning model. The model takes three inputs: X_static, X_dynamic, and X_future, and produces a prediction according to the formulation:

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

where \(f\) is the trained XTFT model. The predictions can be either quantile-based or point-based, as determined by the mode parameter.

Parameters:

xtft_model (object) – A validated Keras model instance. The model is expected to be verified via validate_keras_model.
inputs (list or tuple of numpy.ndarray) – A list containing three elements: X_static, X_dynamic, and X_future. If spatial_cols is provided, it is assumed that the first column of X_static corresponds to the first spatial coordinate and the second column to the second spatial coordinate of the original training data.
y (numpy.ndarray, optional) – Actual target values. If provided, evaluation metrics such as R² Score and (in quantile mode) the coverage score are computed.
dt_col (str, optional) – Name of the time column (e.g. "year"). If provided, a column with this name is added to the output DataFrame. The actual time values must be supplied externally.
mode (str, optional) – Forecast mode. Must be either "quantile" or "point". In quantile mode, predictions are generated for multiple quantiles (default: 0.1, 0.5, and 0.9).
spatial_cols (list of str, optional) – List of spatial column names. If provided, it must contain at least two elements and correspond to the first and second columns of the original training data’s X_static.
q (list of float, optional) – List of quantiles for quantile forecasting. Default is [0.1, 0.5, 0.9] when mode is "quantile".
tname (str, optional) – Target variable name for predictions. This name is used to construct output column names (e.g. "subsidence"). Default is "target".
forecast_dt (any, optional) – Forecast datetime information. Not used in this function but may be provided for compatibility.
apply_mask (bool, optional) – If True, applies a masking function (mask_by_reference) to replace predictions in non-subsiding areas. Requires that both mask_values and mask_fill_value are provided.
mask_values (scalar, optional) – Reference value(s) used for masking. Must be provided if apply_mask is True.
mask_fill_value (scalar, optional) – Value used to fill masked predictions. Must be provided if apply_mask is True.
savefile (str, optional) – Path to a CSV file where the forecast results will be saved. If not provided, a default filename is generated.
verbose (int, optional) – Verbosity level controlling printed output. Higher values result in more detailed output.

Returns:

A DataFrame containing the forecast results. In quantile mode, the output includes columns for each quantile (e.g. <tname>_q10, <tname>_q50, <tname>_q90). In point mode, a single prediction column (<tname>_pred) is provided. If y is provided, an additional column with the actual target values (<tname>_actual) is included.

Return type:

pandas.DataFrame

Examples

>>> from fusionlab.nn.transformers import XTFT
>>> from fusionlab.nn.utils import forecast_single_step
>>> import pandas as pd
>>> import numpy as np
>>>
>>> # Create a dummy training DataFrame with a date column,
>>> # two dynamic features ("feat1", "feat2"), a static feature ("stat1"),
>>> # and dummy spatial features ("longitude", "latitude"), as well as the
>>> # target variable "subsidence".
>>> date_rng = pd.date_range(start="2020-01-01", periods=50, freq="D")
>>> train_df = pd.DataFrame({
...     "date": date_rng,
...     "longitude": np.random.uniform(-180, 180, 50),
...     "latitude": np.random.uniform(-90, 90, 50),
...     "feat1": np.random.rand(50),
...     "feat2": np.random.rand(50),
...     "stat1": np.random.rand(50),
...     "subsidence": np.random.rand(50)
... })
>>>
>>> # Prepare dummy inputs for the model.
>>> # For the static input, combine the spatial feature "longitude" and the
>>> # static feature "stat1". The forecast_single_step function expects that,
>>> # if spatial_cols is provided, the first two columns of X_static correspond
>>> # to the spatial coordinates.
>>> X_static = train_df[["longitude", "stat1"]].values   # shape: (50, 2)
>>>
>>> # Create a dummy dynamic input array for "feat1" and "feat2".
>>> # Assume time_steps = 3, so the shape is (50, 3, 2).
>>> X_dynamic = np.random.rand(50, 3, 2)
>>>
>>> # Create a dummy future input array.
>>> # For this example, assume one future feature with shape (50, 3, 1).
>>> X_future = np.random.rand(50, 3, 1)
>>>
>>> # Create dummy target output from "subsidence", reshaped to (50, 1, 1)
>>> y_array = train_df["subsidence"].values.reshape(50, 1, 1)
>>>
>>> # Instantiate a dummy XTFT model.
>>> # The model expects:
>>> #   - X_static with shape (n_samples, static_input_dim)
>>> #   - X_dynamic with shape (n_samples, time_steps, dynamic_input_dim)
>>> #   - X_future with shape (n_samples, time_steps, future_input_dim)
>>> my_model = XTFT(
...     static_input_dim=2,         # "longitude" and "stat1"
...     dynamic_input_dim=2,        # "feat1" and "feat2"
...     future_input_dim=1,         # One future feature
...     forecast_horizon=1,         # Single-step forecast
...     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")
>>>
>>> # 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
... )
>>>
>>> # Package the inputs as expected by forecast_single_step.
>>> inputs = [X_static, X_dynamic, X_future]
>>>
>>> # Generate a single-step quantile forecast.
>>> forecast_df = forecast_single_step(
...     xtft_model=my_model,
...     inputs=inputs,
...     y=y_array,
...     dt_col="date",                # The time column name in the output
...     mode="quantile",              # Can be "quantile" or "point"
...     spatial_cols=["longitude", "latitude"],
...     q=[0.1, 0.5, 0.9],
...     tname="subsidence",
...     apply_mask=True,
...     mask_values=0,
...     mask_fill_value=0,
...     verbose=3
... )
>>> print(forecast_df.head())

Notes

In quantile mode, the function computes predictions for multiple quantiles and uses the median (0.5) for evaluation.
If spatial_cols is provided, it must be the first and second columns of the original training data’s X_static.
The function internally utilizes validate_keras_model for model validation, assert_ratio for quantile verification, and mask_by_reference for masking operations.
Evaluation metrics such as R² Score and Coverage Score are computed if actual target values (y) are provided.
The prediction output is expected to have the shape \((n, 1, m)\), where \(m\) is the number of outputs (e.g., the number of quantiles in quantile mode, or 1 in point mode) [1]_.