Improve error messages for insufficient future_covariates in backtest() and fix residuals() #2925
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #2846
Summary
This PR improves error handling when backtest() is called with insufficient future_covariates, replacing cryptic IndexError and TypeError messages with clear, actionable ValueError exceptions. It also fixes a bug in the residuals() method where covariate parameters were not being properly forwarded.
Changes Made
1. Enhanced Error Messages in backtest()
**Added validation to detect when future_covariates are provided but do not cover the required time range. New error messages now include: **
Before:
model.backtest(series, future_covariates=short_cov, forecast_horizon=6)
IndexError: index 1 is out of bounds for axis 0 with size 1
After:
model.backtest(series, future_covariates=short_cov, forecast_horizon=6)
ValueError: TFTModel requires future_covariates to extend beyond the series end.
2. Added Validation Helper Method
Created _validate_future_covariates_for_forecast() to validate:
3. Fixed residuals() Bug
The residuals() method accepted past_covariates and future_covariates parameters but didn’t forward them to the internal backtest() call, causing potential validation failures or incorrect results. Now fixed.
4. Design Decisions
Validation added only to backtest() (not historical_forecasts()) to preserve flexibility for internal calls (e.g., ensembles). Only validates when covariates are provided; lets model handle None case. No API or behavioral breaking changes.
Testing:
• Covers 5 main scenarios: Missing covariates, IndexError → ValueError conversion, TypeError → ValueError conversion, Regression tests without future_covariates, and edge cases for exact boundary conditions.
• 5/5 new tests pass
• All existing backtest tests pass
• All residual tests pass
• No regressions detected