Skip to content

[DOC] Update tslib v2 tutorial to use the package (pkg) classes - #2366

Open
echo-xiao wants to merge 4 commits into
sktime:mainfrom
echo-xiao:doc/tslib-v2-tutorial
Open

[DOC] Update tslib v2 tutorial to use the package (pkg) classes#2366
echo-xiao wants to merge 4 commits into
sktime:mainfrom
echo-xiao:doc/tslib-v2-tutorial

Conversation

@echo-xiao

Copy link
Copy Markdown
Contributor

Reference Issues/PRs

Fixes #2353.

What does this implement/fix? Explain your changes.

Updates the v2 tslib tutorial notebook
(docs/source/tutorials/tslib_v2_example.ipynb) to use the high-level
package (pkg) API for v2 models, as requested in #2353. The previous
version wired up the TslibDataModule, model and Lightning Trainer by
hand; the tutorial now drives the whole pipeline through the pkg classes.

Main change:

  • Rewrite the tutorial around TimeXer_pkg_v2 / DLinear_pkg_v2: configure
    with three dicts (model_cfg / datamodule_cfg / trainer_cfg) and run
    with .fit() / .predict(), instead of manually constructing the
    datamodule, model and Trainer.
  • Import the pkg classes from their public module path
    (pytorch_forecasting.models.timexer / pytorch_forecasting.models.dlinear).
  • Add a DLinear example to show the same pipeline works with another
    tslib model.

Correctness fixes made while updating the notebook:

  • Fix the future_known_feature typo in the TimeSeries definition.
  • Fix nhead -> n_heads (the old name was silently swallowed by
    **kwargs, so the model was running with the default number of heads).
  • Make context_length divisible by patch_length to drop the
    "some time steps will not be used" warning.
  • Remove categorical_encoders, which TslibDataModule does not accept.
  • Leave logging_metrics off the QuantileLoss variant: point metrics
    (MAE/SMAPE) cannot be computed on quantile output and raise an assertion
    during fit.
  • Use accelerator="cpu" so the small demo is reproducible on any machine.

Clarifying note added to the notebook:

  • TimeXer v2 does not yet consume categorical features, and the datamodule
    does not encode them (every feature is cast to float and sliced by index).
    The cat columns are kept in the data definition to show the full API.

What should a reviewer concentrate their feedback on?

  • Whether the pkg-based flow is the right canonical example for tslib v2
    models (still an experimental / unstable API, see [ENH] Implementing D2 data module, tests and TimeXer model from tslib for v2 #1836).
  • Whether the note on categorical features accurately reflects current
    TimeXer v2 / TslibDataModule behavior.
  • Whether covering TimeXer + DLinear is sufficient — these are the only two
    models currently built on TslibBaseModelV2.

Did you add any tests for the change?

No — this is a documentation-only change (a tutorial notebook); no library
code is touched. The notebook was executed end-to-end locally and all cells
run without errors. The docs build uses nbsphinx_execute = "never", so the
committed outputs are what render.

Any other comments?

While updating the notebook I noticed a stray print(self.model_cfg) debug
statement in pytorch_forecasting/base/_base_pkg.py that fires on every pkg
construction and leaks into the output (the {'loss': ...} lines visible in
the notebook). I kept it out of this PR to keep the change documentation-only;
it could be removed in a separate [MNT] PR.

PR checklist

  • The PR title starts with [DOC].
  • Added/modified tests — N/A, documentation-only change.
  • Used pre-commit hooks when committing.

Rewrite the tslib v2 example to use the high-level pkg API
(TimeXer_pkg_v2 / DLinear_pkg_v2) instead of manually wiring up the
datamodule, model and Trainer.

- Configure via model_cfg / datamodule_cfg / trainer_cfg + .fit() / .predict()
- Add a DLinear example to show the same pipeline with another tslib model
- Fix future_known_feature typo in the TimeSeries definition
- Fix nhead -> n_heads (the old name was silently swallowed by **kwargs,
  so the model was running with the default number of heads)
- Make context_length divisible by patch_length to drop the
  'some time steps will not be used' warning
- Remove categorical_encoders, which TslibDataModule does not accept
- Note that TimeXer v2 does not yet consume categorical features and that
  the datamodule does not encode them
- Leave logging_metrics off the QuantileLoss variant: point metrics cannot
  be computed on quantile output and raise an assertion during fit
- Use accelerator='cpu' so the small demo is reproducible on any machine
@review-notebook-app

Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@codecov

codecov Bot commented Aug 2, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@8918eac). Learn more about missing BASE report.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2366   +/-   ##
=======================================
  Coverage        ?   87.46%           
=======================================
  Files           ?      175           
  Lines           ?    10165           
  Branches        ?        0           
=======================================
  Hits            ?     8891           
  Misses          ?     1274           
  Partials        ?        0           
Flag Coverage Δ
cpu 87.46% <ø> (?)
pytest 87.46% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@phoeenniixx phoeenniixx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice!
Few suggestions:

  • In v2, you can perform the training in two ways - High level API (using pkg class) or skipping the pkg class and creating the data modules, models etc yourself. So, it would be great if we dont remove the 2nd way (which was I think already present?) And instead add this new High level API with it. Although, the cells for using pkg class should be BEFORE the cells where we dont use the pkg class. See the other tutorial to see what I mean!
  • For the toydataset, you can use the inbuilt method present in data/examples file. See here.
  • For the note about API being unstable, It would be great if that can be highlighted so that, noone misses that!
  • Please in the begining of the tutorial, also add a md cell explaining tslib models are taken from thuml and they are different from the enc-dec models using EncoderDecoderDataModule.

@phoeenniixx phoeenniixx added documentation Improvements or additions to documentation ptf-v2 Related to `pytorch-forecasting` v2 labels Aug 3, 2026
…thuml/enc-dec note and highlight unstable-API warning
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation ptf-v2 Related to `pytorch-forecasting` v2

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOC] Update tslib tutorial for v2

3 participants