[ENH] Implement N-BEATS (Neural Basis Expansion Analysis for Time Series) forecaster

[satwiksps]

[ENH] Implement N-BEATS (Neural Basis Expansion Analysis for Time Series) forecaster

Reference Issues/PRs

• [ENH] Implement N-BEATS (Neural Basis Expansion Analysis for Time Series) forecaster #2850

What does this implement/fix? Explain your changes.

This PR implements the N-BEATS deep learning architecture https://arxiv.org/abs/1905.10437 as a new forecaster in aeon.forecasting.deep_learning.

Key Features Implemented:

• Architecture: Implements the "Doubly Residual Stacking" topology where blocks are organized into stacks using residual principles for both backcast (reconstruction) and forecast.
• Configurations: Supports both architecture types described in the paper:
  • Generic: Uses learnable linear projections for basis functions.
  • Interpretable: Implements specific inductive biases for Trend (polynomial basis) and Seasonality (Fourier basis).
• Training Strategy: Includes a custom _NBeatsDataGenerator to implement the paper's specific training methodology: sampling random anchor points from history to maximize diversity, rather than sequential windowing.
• Custom Loss: Implemented SMAPE (Symmetric Mean Absolute Percentage Error) .
• Decomposition API: Added a predict_decomposition(y) method. This allows users to retrieve the specific outputs of the Trend and Seasonality stacks, fulfilling the interpretability claims of the paper.

Files Added:

• aeon/forecasting/deep_learning/_nbeats.py: The core implementation.
• aeon/forecasting/deep_learning/tests/test_nbeats.py: Unit tests covering generic/interpretable modes, weight sharing, and decomposition shapes.

Does your contribution introduce a new dependency? If yes, which one?

No new dependencies. It utilizes TensorFlow, which is already an optional soft dependency in aeon.

Any other comments?

The implementation defaults to the "Interpretable" configuration (Trend + Seasonality stacks) as it provides the most value over standard black-box DL models. The predict_decomposition method returns a dictionary separating the "Trend" and "Seasonality" components from the total forecast.

PR checklist

For all contributions

• I've added myself to the list of contributors. Alternatively, you can use the @all-contributors bot to do this for you after the PR has been merged.
• The PR title starts with either [ENH], [MNT], [DOC], [BUG], [REF], [DEP] or [GOV] indicating whether the PR topic is related to enhancement, maintenance, documentation, bugs, refactoring, deprecation or governance.

For new estimators and functions

• I've added the estimator/function to the online API documentation.
• (OPTIONAL) I've added myself as a __maintainer__ at the top of relevant files and want to be contacted regarding its maintenance. Unmaintained files may be removed. This is for the full file, and you should not add yourself if you are just making minor changes or do not want to help maintain its contents.

For developers with write access

• (OPTIONAL) I've updated aeon's CODEOWNERS to receive notifications about future changes to these files.

[aeon-actions-bot]

Thank you for contributing to aeon

I have added the following labels to this PR based on the title: [ enhancement ].
I have added the following labels to this PR based on the changes made: [ forecasting ]. Feel free to change these if they do not properly represent the PR.

The Checks tab will show the status of our automated tests. You can click on individual test runs in the tab or "Details" in the panel below to see more information if there is a failure.

If our pre-commit code quality check fails, any trivial fixes will automatically be pushed to your PR unless it is a draft.

Don't hesitate to ask questions on the aeon Slack channel if you have any.

PR CI actions

These checkboxes will add labels to enable/disable CI functionality for this PR. This may not take effect immediately, and a new commit may be required to run the new configuration.

• Run pre-commit checks for all files
• Run mypy typecheck tests
• Run all pytest tests and configurations
• Run all notebook example tests
• Run numba-disabled codecov tests
• Stop automatic pre-commit fixes (always disabled for drafts)
• Disable numba cache loading
• Regenerate expected results for testing
• Push an empty commit to re-run CI checks

[hadifawaz1999]

Hello, thanks for this but we have a PR in development here to get the network in before getting the forecaster in. Happy to keep this one on hold but for now we can't move forward with it because it will have to depend on the other PR

[satwiksps]

Thanks @hadifawaz1999
I wasn't aware of PR #3057.

That makes perfect sense. I'm happy to put this on hold until the network implementation is merged. Once #3057 is in, I will refactor this PR to import the NBeatsNetwork from aeon.networks and focus this contribution strictly on the NBeatsForecaster wrapper, the data generator/sampling logic, and the decomposition API. I'll keep an eye on the other PR.

[hadifawaz1999]

Thanks @hadifawaz1999 I wasn't aware of PR #3057.

That makes perfect sense. I'm happy to put this on hold until the network implementation is merged. Once #3057 is in, I will refactor this PR to import the NBeatsNetwork from aeon.networks and focus this contribution strictly on the NBeatsForecaster wrapper, the data generator/sampling logic, and the decomposition API. I'll keep an eye on the other PR.

Great ! we will ping you once the network pr is finished, thanks for contributing !