Skip to main content

RecursiveRegressionForecaster

Model
DashAI.back.models.forecasting.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​

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)

Defined on RecursiveRegressionForecaster

The scikit-learn estimator the last fit trained, or None unfitted.

resolved_defaults(self) -> Dict[str, Dict[str, Any]]

Defined on RecursiveRegressionForecaster

Lags left empty: one season, lagsFromSeason, or at least 3, lagsAtLeast when the season is shorter.

resolved_lags(self) -> int

Defined on RecursiveRegressionForecaster

The 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)

Defined on BaseModel

Calculate 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. None when 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]]

Defined on BaseModel

Score 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. None when 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'

Defined on SingleSeriesForecastingModel

Fit 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)

Defined on ConfigObject

Resolve 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]

Defined on SingleSeriesForecastingModel

The model's metadata, with what it does with exogenous variables.

get_schema(cls) -> dict

Defined on ConfigObject

Generates the component related Json Schema.

Returns

dict
Dictionary representing the Json Schema of the component.

load(filename: str) -> Any

Defined on SingleSeriesForecastingModel

Deserialise 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

Defined on SingleSeriesForecastingModel

Forecast 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

Defined on BaseModel

Predict 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

Defined on BaseModel

Return 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'

Defined on BaseModel

Hook 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'

Defined on BaseModel

Hook 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

Defined on SingleSeriesForecastingModel

Serialise 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'

Defined on SingleSeriesForecastingModel

Fit 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

Defined on ConfigObject

It 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.

Compatible with​