RecursiveRegressionForecaster
Forecast a series with a regression model that reads its own past.
The reduction to regression: each value of the series is a target, and the
lags values before it are its features. Any regressor can learn that
table. To forecast several steps, the model predicts one step, appends
the prediction to the history and predicts the next from it: the
recursive strategy. Errors compound along the horizon, which is what the
intervals show.
The table and the recursion are skforecast's ForecasterRecursive. The
regressor is one of DashAI's scikit-learn regressors, chosen and
configured in a nested form; skforecast is handed the plain scikit-learn
estimator inside it (sklearn_estimator).
Exogenous variables, when a run reads them, are features of each row next to the lags, and their future values are needed to forecast.
Intervals come from bootstrapping the residuals of the training fit:
N_BOOT paths are simulated by adding resampled residuals at every
step of the recursion, and the bounds at each level are quantiles of those
paths, so the 80% interval always lies within the 95% one. The residuals
are signed, so a biased regressor can leave the point forecast outside
its own interval.
The bootstrap's seed is fixed, so a fitted model gives the same intervals
every time. Fitting again is as deterministic as the regressor, as in the
x/y tasks: for a reproducible forest, set its random_state in the
nested form.
Known limits, stated in the description too:
- a regressor that fits its training data closely, as trees do, leaves residuals near zero and intervals too narrow; the coverage of the backtest shows it;
- with exogenous variables, the backtest measures the forecast with the future values that actually happened, so its error and coverage are optimistic when the future has to be estimated.
References
- [1] https://skforecast.org/0.26.0/user_guides/autoregresive-forecaster
- [2] https://otexts.com/fpp3/prediction-intervals.html
Parameters
- regressor : object
- The regression model that predicts the next value from the previous ones, along with its own configuration. A linear regression extends a trend; trees and forests cannot forecast past the values they were trained on.
- lags, default=
None - How many past values the regressor reads to predict the next one. Left empty: it uses one season of lags (the value of Season length, or the season of the frequency when that field is empty too), with a minimum of 3. A number sets another count.
- season_length
- How many steps make up one season. Only used for the default lags: it sets how many lags are read when Lags is left empty; it does not model the seasonality. Left empty, it uses the season of the series' frequency (monthly: 12, daily: 7, hourly: 24; 1 if the frequency has no known cycle). A number sets another cycle.
- differentiation : integer, default=
0 - How many times to difference the series before regressing on it. Use 1 on a series with a trend: the regressor then predicts the changes, which a tree can do where it cannot predict values it has never seen. 0 leaves the series as it is.
- use_exogenous : boolean, default=
True - Read the session's exogenous variables. Turn it off to compare the same model without them.
Methods
fitted_estimator(self)
RecursiveRegressionForecasterThe scikit-learn estimator the last fit trained, or None unfitted.
resolved_defaults(self) -> Dict[str, Dict[str, Any]]
RecursiveRegressionForecasterLags left empty: one season, lagsFromSeason, or at least 3, lagsAtLeast when the season is shorter.
resolved_lags(self) -> int
RecursiveRegressionForecasterThe lags each prediction reads: lags, or one season, at least 3.
calculate_metrics(self, split: DashAI.back.core.enums.metrics.SplitEnum = <SplitEnum.VALIDATION: 'validation'>, level: DashAI.back.core.enums.metrics.LevelEnum = <LevelEnum.LAST: 'last'>, log_index: int = None, x_data: 'DashAIDataset' = None, y_data: 'DashAIDataset' = None, fold_index: int = None, inner_fold_index: int = None)
BaseModelCalculate metrics for a data split and save them to the database.
Parameters
- split : SplitEnum
- The data split to evaluate (TRAIN, VALIDATION, or TEST). Defaults to SplitEnum.VALIDATION.
- level : LevelEnum
- The metric granularity level (LAST, TRIAL, STEP, or BATCH). Defaults to LevelEnum.LAST.
- log_index : int, optional
- Explicit step index for the metric entry. If None, the next step index is computed automatically. Defaults to None.
- x_data : DashAIDataset, optional
- Input features. If None, the dataset stored in the model for the given split is used. Defaults to None.
- y_data : DashAIDataset, optional
- Target labels. If None, the labels stored in the model for the given split are used. Defaults to None.
Returns
- Dict[str, float] or None
- What was written, so a caller that also wants the numbers does not have to score the same split twice.
Nonewhen nothing was written: no run to write against, or nothing to score.
compute_metrics(self, split: DashAI.back.core.enums.metrics.SplitEnum = <SplitEnum.VALIDATION: 'validation'>, x_data: 'DashAIDataset' = None, y_data: 'DashAIDataset' = None) -> Optional[Dict[str, float]]
BaseModelScore a data split with this model's metrics, without persisting.
Parameters
- split : SplitEnum
- The data split to evaluate. Defaults to
SplitEnum.VALIDATION. - x_data : DashAIDataset, optional
- Input features. Defaults to the split stored on the model.
- y_data : DashAIDataset, optional
- Target labels. Defaults to the split stored on the model.
Returns
- Dict[str, float] or None
- Metric name to score. A metric that scored a non-finite value is absent from the mapping rather than present with a NaN, so the mapping is empty when every metric returned one.
Nonewhen there is nothing to score at all: no metrics configured, or no data for this split. Callers that need a particular metric must therefore check that it is there. A metric with no value on the data (UndefinedMetricError) is absent the same way.
fit(self, y: Sequence[float], x: Optional[Any] = None) -> 'SingleSeriesForecastingModel'
SingleSeriesForecastingModelFit the model on the series, in time order.
Parameters
- y : sequence of float
- The series, one value per step of its grid.
- x : array-like, optional
- Exogenous variables, one row per step. Refused by a model that declares
EXOGENOUS = "none", and required by one that declares"required".
Returns
- SingleSeriesForecastingModel
- The fitted model.
get_credential(self, name: str)
ConfigObjectResolve a registered credential component by name.
Parameters
- name : str
- Credential component class name (e.g. "HuggingFaceCredential").
Returns
- BaseCredential
- An instance of the requested credential component.
get_metadata(cls) -> Dict[str, Any]
SingleSeriesForecastingModelThe model's metadata, with what it does with exogenous variables.
get_schema(cls) -> dict
ConfigObjectGenerates the component related Json Schema.
Returns
- dict
- Dictionary representing the Json Schema of the component.
load(filename: str) -> Any
SingleSeriesForecastingModelDeserialise a model from disk using joblib.
Parameters
- filename : str
- Path to the file previously written by :meth:
save.
Returns
- SingleSeriesForecastingModel
- The loaded model instance.
predict(self, h: int, x_future: Optional[Any] = None, levels: Optional[Sequence[int]] = None) -> DashAI.back.models.forecasting.single_series_forecasting_model.Forecast
SingleSeriesForecastingModelForecast the h steps that follow the fitted series.
Parameters
- h : int
- How many steps to forecast, at least 1.
- x_future : array-like, optional
- Exogenous variables for the forecast steps, one row per step.
- levels : sequence of int, optional
- Prediction interval levels, in percent, each between 0 and 100.
Returns
- Forecast
- The point forecast and, if levels were asked for, the intervals.
predict_prepared(self, features: Any) -> Any
BaseModelPredict from data that is already in this model's feature space.
Parameters
- features : pandas.DataFrame or numpy.ndarray
- Feature matrix as returned by
prepare_dataset(..., is_fit=False). No further preparation is applied to it.
Returns
- Any
- The same kind of output as
predict: predicted values for regressors, class probabilities for DashAI classifiers.
predict_proba_prepared(self, features: Any) -> Any
BaseModelReturn class probabilities for data already in the feature space.
Parameters
- features : pandas.DataFrame or numpy.ndarray
- Feature matrix as returned by
prepare_dataset(..., is_fit=False).
Returns
- numpy.ndarray
- Array of shape
(n_samples, n_classes)with class probabilities.
prepare_dataset(self, dataset: 'DashAIDataset', is_fit: bool = False) -> 'DashAIDataset'
BaseModelHook for model specific preprocessing of input features.
Parameters
- dataset : DashAIDataset
- The input dataset to preprocess.
- is_fit : bool
- Whether the call is part of a fitting phase. Defaults to False.
Returns
- DashAIDataset
- The preprocessed dataset ready to be fed into the model.
prepare_output(self, dataset: 'DashAIDataset', is_fit: bool = False) -> 'DashAIDataset'
BaseModelHook for model-specific preprocessing of output targets.
Parameters
- dataset : DashAIDataset
- The output dataset (target labels) to preprocess.
- is_fit : bool
- Whether the call is part of a fitting phase. Defaults to False.
Returns
- DashAIDataset
- The preprocessed output dataset.
save(self, filename: str) -> None
SingleSeriesForecastingModelSerialise the model to disk using joblib.
Parameters
- filename : str
- Destination file path where the model will be written.
train(self, x_train: 'DashAIDataset', y_train: 'DashAIDataset', x_validation: 'DashAIDataset' = None, y_validation: 'DashAIDataset' = None) -> 'SingleSeriesForecastingModel'
SingleSeriesForecastingModelFit on the series held by y_train, ignoring every other input.
Parameters
- x_train : DashAIDataset
- Ignored: the model never sees dates.
- y_train : DashAIDataset
- One column holding the series, in time order.
- x_validation, y_validation : DashAIDataset, optional
- Ignored.
Returns
- SingleSeriesForecastingModel
- The fitted model.
validate_and_transform(self, raw_data: dict) -> dict
ConfigObjectIt takes the data given by the user to initialize the model and returns it with all the objects that the model needs to work.
Parameters
- raw_data : dict
- A dictionary with the data provided by the user to initialize the model.
Returns
- dict
- A validated dictionary with the necessary objects.