Skip to content

pkg_v2.rst

Latest commit

 

History

History
103 lines (74 loc) · 4.11 KB

pkg_v2.rst

File metadata and controls

103 lines (74 loc) · 4.11 KB
Raw

Package (P) Layer v2

Warning

Please note that the v2 modules are currently in active-development and is in beta right now, so please use this API with caution. See complete documentation for v2 API :doc:`here <api_v2>` and stable v1 documentation :doc:`here <api>`.

.. currentmodule:: pytorch_forecasting

The Package Layer is the defining feature of the V2 user experience. While the underlying D1, D2, and Model layers are strictly decoupled to maintain separation of concerns, the Package layer acts as the Orchestrator.

It wraps the PyTorch Lightning boilerplate and provides a streamlined, scikit-learn-like interface. By passing standard Python dictionaries for configuration, the Package layer automatically handles the instantiation of the DataModule, extracts the necessary metadata, initializes the underlying forecasting model, and manages the training loop.

The Configuration Driven Workflow

To use a V2 Package, you do not need to manually instantiate the DataModule or the Model. Instead, you provide three configuration dictionaries to the Package wrapper:

  1. datamodule_cfg: Parameters for the D2 layer (e.g., batch size, scalers, encoders, and maximum sequence lengths).
  2. model_cfg: Parameters for the core neural network (e.g., hidden sizes, dropout, loss metrics, and optimizers).
  3. trainer_cfg: Parameters for the PyTorch Lightning Trainer (e.g., max epochs, accelerator type, and logging configurations).

sklearn like Methods

The Package layer exposes two primary methods for interacting with the model lifecycle:

  • fit(): Initiates the training process. You can pass a raw D1 TimeSeries dataset (which the package will internally wrap in a D2 DataModule) or a pre-configured D2 LightningDataModule.
  • predict(): Generates forecasts. Similar to fit(), this accepts a D1 dataset, a D2 DataModule, or even a standard PyTorch DataLoader. It also accepts a return_info parameter to easily append identifying columns (like time indices and series IDs) alongside the predictions.

All package classes inherit from :py:class:`~pytorch_forecasting.base._base_pkg.Base_pkg`

.. autoclass:: pytorch_forecasting.base._base_pkg.Base_pkg
   :noindex:
   :members: __init__

Code Example

Here is how the configuration dictionaries and lifecycle methods come together using the Temporal Fusion Transformer package (TFT_pkg_v2):

from pytorch_forecasting.models.temporal_fusion_transformer._tft_pkg_v2 import TFT_pkg_v2
from pytorch_forecasting.metrics import MAE, SMAPE
from pytorch_forecasting.data.encoders import NaNLabelEncoder, TorchNormalizer
from sklearn.preprocessing import StandardScaler

# Define Configurations
datamodule_cfg = dict(
    max_encoder_length=30,
    max_prediction_length=1,
    batch_size=32,
)

model_cfg = dict(
    loss=MAE(),
    logging_metrics=[MAE(), SMAPE()],
    optimizer="adam",
    optimizer_params={"lr": 1e-3},
    hidden_size=64,
    num_layers=2,
)

trainer_cfg = dict(
    max_epochs=5,
    accelerator="auto",
    devices=1,
)

# Initialize the Package
model_pkg = TFT_pkg_v2(
    model_cfg=model_cfg,
    trainer_cfg=trainer_cfg,
    datamodule_cfg=datamodule_cfg,
)

# Train the model
# (Assuming `dataset` is a previously defined D1 TimeSeries object)
model_pkg.fit(dataset)

# Generate predictions
preds = model_pkg.predict(dataset, return_info=["index", "x", "y"])

API Reference

See the detailed API documentation for the available V2 Package classes below:

.. currentmodule:: pytorch_forecasting


.. autosummary::
   :toctree: api

   models.temporal_fusion_transformer._tft_pkg_v2.TFT_pkg_v2
   models.dlinear._dlinear_pkg_v2.DLinear_pkg_v2
   models.samformer._samformer_v2_pkg.Samformer_pkg_v2
   models.tide._tide_dsipts._tide_v2_pkg.TIDE_pkg_v2
   models.timexer._timexer_pkg_v2.TimeXer_pkg_v2
   models.mlp._decodermlp_pkg_v2.DecoderMLP_pkg_v2
   models.softs._softs_pkg_v2.SOFTS_pkg_v2