[ENH] New API design for `pytorch-forecasting` v2

[phoeenniixx]

Background

After some user feedback on the current API of pytorch-forecasting, we came to know there are some issues with it.

API

• They hit many errors, and the messages did not say what went wrong or how to fix it
• Errors surfaced late, deep in the pipeline, rather than at the call that took the bad input
• Configs are plain dicts; users coming from sklearn and torch found this unintuitive
• Constructors accept invalid configs without complaint
• fit / predict do not check their inputs
• Users found the 3-stage pipeline (not using pkg class) easier to follow than the current entry point
• predict output and other returned objects are hard to inspect and do not behave as expected

Docs

• Users could not find a copy-pasteable example of the v2 pipeline
• Docs do not describe the shape of the config dicts
• Users could not tell which parameters model_cfg accepts and got stuck there
• Online docs were hard to navigate and examples hard to find

New v2 API

So, based on this input, we are revamping and making some (a LOT of) changes to the v2 API.
To keep the changes separate from the current version and to not break the current code, we will be doing it on a separate branch (v2-dev) instead of main.

Changes

See #2398 for prototype.

• Make TimeSeries a datatype and not D1 layer - this will be the standardised datatype of ptf-v2. This means the input and final preds will be a TimeSeries obj.
• The metadata objects will now be dataclasses
• The pkg class will be renamed to forecaster (like in place of TFT_pkg_v2, it will be TFTForecaster)
  • The model_cfg will be replaced by the flattened params - meaning, the forecaster class will NOT accept the model_cfg, instead we will flatten the the cfg and the params will be passed directly to the class
  • It will now accept the datamodule and trainer class directly (not cfgs)
    • datamodule will be passed as __init__ argument
    • trainer can be passed as an __init__ arg as well as as fit arg.
      • Here, the trainer passed to fit will override the trainer passed to __init__.

Vignettes

Minimal Vignette

data = TimeSeries(
    df, 
    num=['x'], 
    ...,
) 
forecaster = TFTForecaster()
forecaster.fit(data)

Maximal Vignette

trainer_init = Trainer(
    max_epochs = 5, 
    accelerator = "auto", 
    ...
)
trainer_fit = Trainer(
    max_epochs = 10, 
    accelerator = "cpu", 
    ...
)
data = TimeSeries(
    df, 
    num=['x'], 
    ...,
) 
forecaster = TFTForecaster(
    # model parameters
    n_layers=42,
    ...
    # data module parameters
    # this is a class that the user has written
    # (following a base pattern)
    datamodule = DecoderEncoderDataModuleCustomizedByUser(
        stuff=2,
        more_stuff=42,
    )
    trainer=trainer_init
)
forecaster.fit(data, trainer=trainer_fit) # trainer_fit overrides trainer_init

Milestones

• Implement TimeSeries as datatype
• Update datamodule to accept data as TimeSeries object in place of a dataset obj
• Implement forecaster pipeline
• Update tests

[phoeenniixx]

FYI @CloseChoice @fkiraly