Getting started
===============
.. _getting-started:
Installation
--------------
.. _install:
If you are working windows, you need to first install PyTorch with
``pip install torch -f https://download.pytorch.org/whl/torch_stable.html``.
Otherwise, you can proceed with
``pip install pytorch-forecasting``
Alternatively, to installl the package via conda:
``conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge``
PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel.
To use the MQF2 loss (multivariate quantile loss), also install
`pip install pytorch-forecasting[mqf2]`
Usage
-------------
.. currentmodule:: pytorch_forecasting
The library builds strongly upon `PyTorch Lightning `_ which allows to train models with ease,
spot bugs quickly and train on multiple GPUs out-of-the-box.
Further, we rely on `Tensorboard `_ for logging training progress.
The general setup for training and testing a model is
#. Create training dataset using :py:class:`~data.timeseries.TimeSeriesDataSet`.
#. Using the training dataset, create a validation dataset with :py:meth:`~data.timeseries.TimeSeriesDataSet.from_dataset`.
Similarly, a test dataset or later a dataset for inference can be created. You can store the dataset parameters
directly if you do not wish to load the entire training dataset at inference time.
#. Instantiate a model using the its ``.from_dataset()`` method.
#. Create a ``lightning.Trainer()`` object.
#. Find the optimal learning rate with its ``.tuner.lr_find()`` method.
#. Train the model with early stopping on the training dataset and use the tensorboard logs
to understand if it has converged with acceptable accuracy.
#. Tune the hyperparameters of the model with your
`favourite package `_.
#. Train the model with the same learning rate schedule on the entire dataset.
#. Load the model from the model checkpoint and apply it to new data.
The :ref:`Tutorials ` section provides detailled guidance and examples on how to use models and implement new ones.
Example
--------
.. code-block:: python
import lightning.pytorch as pl
from lightning.pytorch.callbacks import EarlyStopping, LearningRateMonitor
from lightning.pytorch.tuner import Tuner
from pytorch_forecasting import TimeSeriesDataSet, TemporalFusionTransformer
# load data
data = ...
# define dataset
max_encoder_length = 36
max_prediction_length = 6
training_cutoff = "YYYY-MM-DD" # day for cutoff
training = TimeSeriesDataSet(
data[lambda x: x.date < training_cutoff],
time_idx= ...,
target= ...,
# weight="weight",
group_ids=[ ... ],
max_encoder_length=max_encoder_length,
max_prediction_length=max_prediction_length,
static_categoricals=[ ... ],
static_reals=[ ... ],
time_varying_known_categoricals=[ ... ],
time_varying_known_reals=[ ... ],
time_varying_unknown_categoricals=[ ... ],
time_varying_unknown_reals=[ ... ],
)
# create validation and training dataset
validation = TimeSeriesDataSet.from_dataset(training, data, min_prediction_idx=training.index.time.max() + 1, stop_randomization=True)
batch_size = 128
train_dataloader = training.to_dataloader(train=True, batch_size=batch_size, num_workers=2)
val_dataloader = validation.to_dataloader(train=False, batch_size=batch_size, num_workers=2)
# define trainer with early stopping
early_stop_callback = EarlyStopping(monitor="val_loss", min_delta=1e-4, patience=1, verbose=False, mode="min")
lr_logger = LearningRateMonitor()
trainer = pl.Trainer(
max_epochs=100,
accelerator="auto",
gradient_clip_val=0.1,
limit_train_batches=30,
callbacks=[lr_logger, early_stop_callback],
)
# create the model
tft = TemporalFusionTransformer.from_dataset(
training,
learning_rate=0.03,
hidden_size=32,
attention_head_size=1,
dropout=0.1,
hidden_continuous_size=16,
output_size=7,
loss=QuantileLoss(),
log_interval=2,
reduce_on_plateau_patience=4
)
print(f"Number of parameters in network: {tft.size()/1e3:.1f}k")
# find optimal learning rate (set limit_train_batches to 1.0 and log_interval = -1)
res = Tuner(trainer).lr_find(
tft, train_dataloaders=train_dataloader, val_dataloaders=val_dataloader, early_stop_threshold=1000.0, max_lr=0.3,
)
print(f"suggested learning rate: {res.suggestion()}")
fig = res.plot(show=True, suggest=True)
fig.show()
# fit the model
trainer.fit(
tft, train_dataloaders=train_dataloader, val_dataloaders=val_dataloader,
)
Main API
---------
.. currentmodule:: pytorch_forecasting
.. moduleautosummary::
:toctree: api
:template: custom-module-template.rst
:recursive:
pytorch_forecasting