fusionlab.nn.forecast_tuner.xtft_tuner¶

fusionlab.nn.forecast_tuner.xtft_tuner(inputs, y, param_space=None, forecast_horizon=1, quantiles=None, case_info=None, max_trials=10, objective='val_loss', epochs=10, batch_sizes=[32], validation_split=0.2, tuner_dir=None, project_name=None, tuner_type='random', callbacks=None, model_builder=None, model_name='xtft', verbose=1, **kws)[source]¶

Fine-tunes XTFT, SuperXTFT, or TFT (stricter) models.

The function sets up a hyperparameter tuning workflow for the XTFT model, leveraging Keras Tuner’s Bayesian Optimization to search over a defined hyperparameter space. The function accepts input tensors for static, dynamic, and future features along with the target output, and returns the best hyperparameter configuration, the corresponding trained model, and the tuner instance.

The hyperparameter search is formulated as:

\[\min_{\theta \in \Theta} \; L\bigl(\theta; \mathbf{X}, y\bigr)\]

where \(\Theta\) is the hyperparameter space and \(L(\theta; \mathbf{X}, y)\) is the validation loss computed over the training data.

Parameters:

inputs (List[Union[np.ndarray, Tensor]]) –
A list containing three input tensors:
- X_static: static features with shape (B, N_s)
- X_dynamic: dynamic features with shape (B, F, N_d)
- X_future: future features with shape (B, F, N_f)
Here, \(B\) is the batch size, \(N_s\) is the number of static features, \(F\) is the forecast horizon, \(N_d\) is the number of dynamic features, and \(N_f\) is the number of future features.
y (np.ndarray) – The target output tensor with shape (B, F, O), where \(O\) is the output dimension.
param_space (Dict[str, Any], optional) – A dictionary specifying custom hyperparameter ranges. If not provided, a default parameter space is used.
forecast_horizon (int, default 1) – The number of future steps to forecast. This should be consistent with the forecast horizon in the dynamic and future inputs.
quantiles (List[float], optional) – A list of quantile values for quantile forecasting (e.g., [0.1, 0.5, 0.9]). If not provided, default quantiles are used based on the case configuration.
case_info (Dict[str, Any], optional) – A dictionary containing case-specific configuration parameters (such as forecast horizon and quantiles) to configure the XTFT model.
max_trials (int, default 10) – Maximum number of hyperparameter tuning trials to perform.
objective (str, default 'val_loss') – The performance metric to optimize (e.g., "val_loss").
epochs (int, default 50) – The number of training epochs for each tuning trial.
batch_sizes (List[int], default [16, 32, 64]) – A list of batch sizes to explore during tuning.
validation_split (float, default 0.2) – Fraction of training data used as the validation set.
tuner_dir (Optional[str], default None) – Directory in which tuner results and logs will be saved. A default directory is used if not provided.
project_name (Optional[str], default None) – Name for the tuning project. If not provided, a name is generated based on the case description.
tuner_type (str, default 'bayesian') – The type of tuner to use. Currently, only Bayesian Optimization is supported.
callbacks (Optional[list], default None) – A list of Keras callbacks to use during tuning. If not provided, a default EarlyStopping callback is applied.
model_builder (Optional[Callable], default None) – A callable that builds and compiles the XTFT model. If omitted, a default model builder is used which defines a hyperparameter search space over key model parameters.
verbose (int, default 1) – Verbosity level controlling logging output. Values range from 1 (minimal) to 7 (very detailed).
model_name (str)

Returns:

A tuple containing:

dict: The best hyperparameters found.
tf.keras.Model: The best trained XTFT model.
kt.Tuner: The tuner instance used for hyperparameter search.

Return type:

tuple

Examples

>>> from fusionlab.nn.forecast_tuner import xtft_tuner
>>> # Assume preprocessed inputs: X_static, X_dynamic, X_future, and y
>>> best_hps, best_model, tuner = xtft_tuner(
...     inputs=[X_static, X_dynamic, X_future],
...     y=y,
...     forecast_horizon=4,
...     quantiles=[0.1, 0.5, 0.9],
...     case_info={"description": "Quantile Forecast",
...                "forecast_horizon": 4,
...                "quantiles": [0.1, 0.5, 0.9]},
...     max_trials=5,
...     epochs=50,
...     batch_sizes=[16, 32],
...     validation_split=0.2,
...     tuner_dir="tuning_results",
...     project_name="XTFT_Tuning_Case",
...     verbose=5
... )
>>> print("Best hyperparameters:", best_hps)
>>> best_model.summary()

Notes

The function first validates and converts input tensors to float32 for numerical stability via validate_minimal_inputs(). It then defines a hyperparameter search space (defaulting to a predefined space if param_space is not provided) and iterates over the specified batch sizes. For each batch size, the tuner trains the model for a set number of epochs and selects the best model based on the validation loss. The final best hyperparameters, trained model, and tuner instance are returned.