Skip to content

docs: add custom forecaster tutorial (#1128) - #1145

Open
charanteja25 wants to merge 2 commits into
OpenSTEF:mainfrom
charanteja25:docs/1128-custom-forecaster-tutorial
Open

charanteja25 wants to merge 2 commits into
OpenSTEF:mainfrom
charanteja25:docs/1128-custom-forecaster-tutorial

Conversation

@charanteja25

@charanteja25 charanteja25 commented Oct 15, 2026 •

Copy link
Copy Markdown

Closes #1128

Is your feature request related to a problem?

Yes, issue #1128. There is no tutorial that shows how to write a custom Forecaster. The only custom example, examples/benchmarks/custom/custom_forecaster.py, is a template for the BEAM benchmark interface (BacktestForecasterMixin). A user who wants to add their own model to a ForecastingModel has to read the source code of the built-in forecasters.

Describe the solution you'd like

A new tutorial, examples/tutorials/custom_forecaster.py (with the paired .ipynb), that shows:

  • The contract of a Forecaster: hparams, is_fitted, fit, predict, and the quantiles and horizons fields.
  • A small working example: a weekly profile forecaster. For each time slot of the week, it stores the quantiles of the past values.
  • How to use it in a ForecastingModel and a CustomForecastingWorkflow.
  • A comparison with the built-in ConstantQuantileForecaster.

The tutorial is linked in docs/source/examples.rst (table and toctree), after "Custom Pipeline".

Describe alternatives you've considered

  • Extend the BEAM template in examples/benchmarks/custom: it is about benchmarking, not about the model interface. The tutorial links to it.
  • Write a how-to guide in docs/source/user_guide/guides/: a tutorial with runnable code fits the other tutorials better. A short link from a guide can follow.
  • Use a gradient boosting model as the example: it needs feature engineering, which hides the contract. The weekly profile uses only the target column.

Affected package(s)

  • docs
  • examples / deployment
  • openstef-core
  • openstef-models
  • openstef-beam
  • openstef-foundation-models
  • openstef-meta

Would this require breaking changes to the public API?

No. Only a new tutorial and one docs index entry.

Additional context

I read the issue as a request for a tutorial on the Forecaster interface (a custom model). If you meant something else, please tell me and I change it.

Result on the Liander data used in the other tutorials (45 days of training, 36 h forecast):

Model MAE of the median forecast
ConstantQuantileForecaster 229,816
WeeklyProfileForecaster 183,425

This is one 36 h forecast window. It is an illustration for the tutorial, not a benchmark.

Notes for the review:

  • ForecastingModel holds back validation and test data by default. The weekly profile needs every week, so the tutorial sets DataSplitter(val_fraction=0.0, test_fraction=0.0) and explains why in a note.
  • I removed the unit from the plot axis ("Load"). The values reach ±1,000,000 and can be negative, so "MW" looked wrong. Please correct me if the unit is known.

Checks:

  • poe all --check passes (ruff, ty, tests, doctests, REUSE, notebooks).
  • On my machine (timezone UTC+05:30), 5 existing tests fail in test_datetime.py and test_evaluation_pipeline.py. They pass with TZ=UTC. They are not related to this change.
  • Commit is signed off (DCO).

Add a tutorial that shows how to write a custom Forecaster: the contract (hparams, is_fitted, fit, predict), a weekly profile example, use in ForecastingModel and CustomForecastingWorkflow, and a comparison with ConstantQuantileForecaster. Link it from the examples index.

Signed-off-by: charanteja25 <charanteja.teja25@gmail.com>
@charanteja25
charanteja25 requested a review from a team October 15, 2026 11:26
@github-actions github-actions Bot added the chore Improvements or additions to documentation label Oct 15, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

chore Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create a documentation page/example showing how to implement a custom forecaster

1 participant