fusionlab.nn.forecast_tuner.tft_tuner¶

fusionlab.nn.forecast_tuner.tft_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='tft', verbose=1)[source]¶

Fine-tunes TemporalFusionTransformer (flexible via model_name=’tft_flex’) or TFT (stricter via model_name=’tft’) models.

This function is a wrapper around xtft_tuner() that explicitly sets the model type to "tft" and configures hyperparameter tuning for Temporal Fusion Transformer (TFT) models. It leverages Bayesian Optimization (or another tuner type if specified) to search over a defined hyperparameter space. The tuning process 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 loss (e.g., validation loss) computed over the training data.

Parameters:

inputs (List[Union[np.ndarray, Tensor]]) –
A list containing three input arrays:
- X_static with shape (B, N_s),
- X_dynamic with shape (B, F, N_d), and
- X_future with shape (B, F, N_f).
Here, \(B\) denotes 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 (Optional[np.ndarray], default None) – The target output with shape (B, F, O) (if provided), where \(O\) is the output dimension.
param_space (Optional[Dict[str, Any]], default None) – A dictionary defining the hyperparameter search space. If omitted, a default parameter space is used.
forecast_horizon (int, default 1) – The expected number of future steps to forecast.
quantiles (Optional[List[float]], default None) – A list of quantile values for quantile regression (e.g., [0.1, 0.5, 0.9]). Ignored in point forecasting mode.
case_info (Optional[Dict[str, Any]], default None) – A dictionary containing additional configuration details (e.g., forecast horizon, quantiles) used to configure the model.
max_trials (int, default 10) – Maximum number of hyperparameter tuning trials to perform.
objective (str, default 'val_loss') – The performance metric (objective) to minimize during tuning.
epochs (int, default 50) – Number of training epochs per 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 the training data to use for validation.
tuner_dir (Optional[str], default None) – Directory where tuner results and logs are stored. If not provided, a default directory is used.
project_name (Optional[str], default None) – The name of the tuning project. If omitted, a project name is generated based on the case information.
tuner_type (str, default 'bayesian') – The tuner type to use (e.g., "bayesian" or "random").
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 function that builds and compiles the TFT model. If omitted, a default builder is used.
verbose (int, default 1) – Verbosity level for logging output. Higher values (from 1 up to 7) yield more detailed debug messages.
model_name (str)

Returns:

A tuple containing:

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

Return type:

tuple

Examples

>>> from fusionlab.nn.forecast_tuner import tft_tuner
>>> best_hps, best_model, tuner = tft_tuner(
...     inputs=[X_static, X_dynamic, X_future],
...     y=y,
...     forecast_horizon=4,
...     quantiles=[0.1, 0.5, 0.9],
...     case_info={"description": "TFT Point Forecast",
...                "forecast_horizon": 4,
...                "quantiles": None},
...     max_trials=5,
...     epochs=50,
...     batch_sizes=[16, 32],
...     validation_split=0.2,
...     tuner_dir="tuning_results",
...     project_name="TFT_Tuning",
...     tuner_type="bayesian",
...     verbose=5
... )
>>> print("Best Hyperparameters:", best_hps)
>>> best_model.summary()

Notes

This function is a thin wrapper around xtft_tuner() that sets the model_name parameter to "tft". It validates input tensors using validate_minimal_inputs() and constructs a default model builder if none is provided. Hyperparameter tuning is performed over multiple batch sizes to identify the configuration that minimizes the validation loss.