[ENH] Allow direct initialization of NBeats model without from_dataset

[MeherBhaskar]

Description

This PR fixes issue #1548 where the NBeats model fails when initialized without using the from_dataset method. The changes enable direct initialization while maintaining backward compatibility and adding proper validation.

Changes

• Enhanced __init__ method with comprehensive parameter validation
• Added clear documentation for both initialization methods (direct and from_dataset)
• Added validation for parameter list lengths to match stack types
• Updated from_dataset method documentation to clarify its role
• Added unit tests for direct initialization

Now users can:

1. Use from_dataset (recommended) for standard time series forecasting
2. Initialize directly for custom use cases
3. Get clear error messages when parameters are invalid

Example of direct initialization:

model = NBeats(
    stack_types=["trend", "seasonality"],
    num_blocks=[3, 3],
    num_block_layers=[3, 3],
    widths=[32, 512],
    sharing=[True, True],
    expansion_coefficient_lengths=[3, 7],
    prediction_length=24,
    context_length=72,
)

Checklist

• Linked issues (if existing)
• Amended changelog for large changes (and added myself there as contributor)
• Added/modified tests
• Used pre-commit hooks when committing to ensure that code is compliant with hooks. Install hooks with pre-commit install.
  To run hooks independent of commit, execute pre-commit run --all-files

Make sure to have fun coding!

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@81b5303). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
pytorch_forecasting/models/nbeats/_nbeats.py	90.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1837   +/-   ##
=======================================
  Coverage        ?   86.85%           
=======================================
  Files           ?      101           
  Lines           ?     8085           
  Branches        ?        0           
=======================================
  Hits            ?     7022           
  Misses          ?     1063           
  Partials        ?        0           

Flag	Coverage Δ
cpu	86.85% <90.00%> (?)
pytest	86.85% <90.00%> (?)

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

☔ View full report in Codecov by Sentry.
📢 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.

[fkiraly]

Thanks!

Quick question, why are we changing the old test? Does this mean existing code breaks?

We should avoid to break working code of users.

[MeherBhaskar]

Hi @fkiraly,
The change to update the widths from [4, 4, 4] to [4, 4] was made to match the number of stacks used by the N-BEATS model (["trend", "seasonality"])

Passing a list of length 3 was causing the following error:

ValueError: Length of widths (3) must match length of stack_types (2)

Let me know if you'd like to handle this differently!

[fkiraly]

Can you explain why the [4, 4, 4] was previously passing them in the tests? If it worked previously - and seems to have been standard expectation, an dnow we change it, we might break someone's code.

[jobs-git]

@MeherBhaskar can I request that we also allow training the model this way:

output = model(x)

[jobs-git]

Hi @fkiraly, The change to update the widths from [4, 4, 4] to [4, 4] was made to match the number of stacks used by the N-BEATS model (["trend", "seasonality"])

Passing a list of length 3 was causing the following error:

ValueError: Length of widths (3) must match length of stack_types (2)

Let me know if you'd like to handle this differently!

I encountered a similar issue in nhits too! Apparently, even if you just have two hidden layers, its asking hidden_size as 3 elements! What happens was that, there is a weird implementation in the NHiTS block for MLP, it adds the input_feature which are features of the input layer to the hidden size! This was forcibly needed to be able to fix the input_feature of the first hidden layer as supplied by the input layer. That is why I have this pull request to avoid this confusion: #1864

Note that, i also saw this same style from the reference code of the paper authors, so it was nobody's fault. NBeaTS might also have this same confusion?

Ref: Check out the n_theta_hidden here: https://github.com/cchallu/n-hits/blob/main/src/models/nhits/nhits.py