forecaster.recursive._forecaster_recursive_multiseries

forecaster.recursive._forecaster_recursive_multiseries

Classes

Name	Description
ForecasterRecursiveMultiSeries	Recursive autoregressive forecaster for multiple time series.

ForecasterRecursiveMultiSeries

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries(
    estimator=None,
    lags=None,
    window_features=None,
    encoding='ordinal',
    transformer_series=None,
    transformer_exog=None,
    weight_func=None,
    series_weights=None,
    differentiation=None,
    dropna_from_series=False,
    fit_kwargs=None,
    binner_kwargs=None,
    forecaster_id=None,
    regressor=None,
)

Recursive autoregressive forecaster for multiple time series.

This class turns any estimator compatible with the scikit-learn API into a recursive autoregressive (multi-step) forecaster for multiple series.

Parameters

Name	Type	Description	Default
estimator	object	An instance of an estimator or pipeline compatible with the scikit-learn API.	None
lags	(int, list, np.ndarray, range, None)	Lags used as predictors. Index starts at 1, so lag 1 is equal to t-1. - int: include lags from 1 to lags (included). - list, 1d numpy ndarray or range: include only lags present in lags, all elements must be int. - None: no lags are included as predictors.	None
window_features	(object, list, None)	Instance or list of instances used to create window features from the original time series.	None
encoding	(str, None)	Encoding used to identify the different series. - 'ordinal': single column with integer values [0, n_series - 1]. - 'ordinal_category': same as ‘ordinal’ but with pandas.category dtype. - 'onehot': binary column for each series. - None: no series identification column is created. Defaults to ‘ordinal’.	'ordinal'
transformer_series	(transformer, dict, None)	Preprocessor compatible with scikit-learn (fit/transform/inverse_transform). Applied to each series before training. ColumnTransformers are not allowed. - Single transformer: cloned and applied to all series. - Dict: different transformer per series.	None
transformer_exog	(transformer, None)	Preprocessor for exogenous variables. inverse_transform is not available for ColumnTransformers.	None
weight_func	(Callable, dict, None)	Function defining weights for each sample based on index. Only used if estimator supports sample_weight. - Single function: applied to all series. - Dict: {'series_name': Callable}, others get weight 1.	None
series_weights	(dict, None)	Weights per series {'series_name': float}. Applied if estimator supports sample_weight. Others get weight 1. If None, all levels have weight 1.	None
differentiation	(int, dict, None)	Order of differencing applied to series. - int: same order for all series. - dict: different order per series (keys are series names). - None: no differencing.	None
dropna_from_series	bool	If True, drops rows with NaNs in X_train/y_train. If False, leaves NaNs and warns. Defaults to False.	False
fit_kwargs	(dict, None)	Additional arguments for the estimator’s fit method.	None
binner_kwargs	(dict, None)	Arguments for QuantileBinner used for residuals. Includes n_bins, method, subsample, random_state, dtype.	None
forecaster_id	(str, int, None)	Identifier for the forecaster.	None
regressor	object	Deprecated, alias for estimator.	None

Attributes

Name	Type	Description
estimator	object	Estimator or pipeline compatible with scikit-learn.
lags	np.ndarray	Lags used as predictors.
lags_names	list	Names of the lags used as predictors.
max_lag	int	Maximum lag included in lags.
window_features	list	Classes used to create window features.
window_features_names	list	Names of the window features in X_train.
window_features_class_names	list	Names of classes for window features.
max_size_window_features	int	Maximum window size for window features.
window_size	int	Required window size for predictors. Max of max_lag and max_size_window_features, plus differentiation order if applicable.
encoding	str	Encoding used to identify the different series.
encoder	sklearn.preprocessing	Scikit-learn encoder for series.
encoding_mapping_	dict	Mapping of the encoding for series identities.
transformer_series	(transformer, dict)	Transformer(s) for the series.
transformer_series_	dict	Internal dictionary of series transformers.
transformer_exog	transformer	Transformer for exogenous variables.
weight_func	(Callable, dict)	Weighting function(s).
weight_func_	dict	Internal dictionary of weighting functions.
source_code_weight_func	(str, dict)	Source code of weighting functions.
series_weights	dict	Weights associated with each series.
series_weights_	dict	Internal dictionary of series weights.
differentiation	(int, dict)	Differencing order applied to series.
differentiation_max	int	Maximum order of differentiation.
differentiator	(TimeSeriesDifferentiator, dict)	Differentiation objects.
differentiator_	dict	Internal dictionary of differentiators.
dropna_from_series	bool	Whether to drop NaNs from training matrices.
last_window_	dict	Last training window per series in original scale.
index_type_	type	Type of training index.
index_freq_	str	Frequency of training index.
training_range_	dict	First/last training index values per series.
series_names_in_	list	Series names provided during training.
exog_in_	bool	True if trained with exogenous variables.
exog_names_in_	list	Names of exogenous variables used.
exog_type_in_	type	Type of exogenous data used.
exog_dtypes_in_	dict	Exogenous data types before transformation.
exog_dtypes_out_	dict	Exogenous data types after transformation.
X_train_series_names_in_	list	Series names in the internal X_train.
X_train_window_features_names_out_	list	Window feature names in X_train.
X_train_exog_names_out_	list	Exogenous variable names in X_train.
X_train_features_names_out_	list	All feature column names in X_train.
fit_kwargs	dict	Arguments passed to estimator’s fit.
in_sample_residuals_	dict	Training residuals (up to 10k per series).
in_sample_residuals_by_bin_	dict	Binned in-sample residuals.
out_sample_residuals_	dict	Non-training residuals (up to 10k per series).
out_sample_residuals_by_bin_	dict	Binned out-of-sample residuals.
binner	dict	QuantileBinner objects per series.
binner_intervals_	dict	Binning intervals per series.
binner_kwargs	dict	Arguments used for QuantileBinner.
creation_date	str	Forecaster creation date.
is_fitted	bool	True if the forecaster has been fitted.
fit_date	str	Date of last fit.
spotforecast_version	str	Version of the library used.
python_version	str	Python version used.
forecaster_id	(str, int)	Forecaster identifier.

Notes

Weights are used to control the influence of each observation. ForecasterRecursiveMultiSeries accepts two types of weights: - series_weights: Controls relative importance of each series. - weight_func: Controls relative importance based on index values. If both are provided, they are multiplied. Negative weights are not allowed.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(
    estimator=Ridge(),
    lags=3,
    forecaster_id="demo",
)
forecaster.fit(series, suppress_warnings=True)
predictions = forecaster.predict(steps=3, suppress_warnings=True)
print(predictions)
assert predictions.shape == (6, 2)
assert set(predictions["level"].unique()) == {"A", "B"}

   level      pred
60     A -0.115562
60     B  0.202789
61     A  0.037961
61     B  0.158784
62     A  0.075896
62     B  0.061138

Methods

Name	Description
create_predict_X	Create the predictors needed to predict steps ahead.
create_sample_weights	Create weights for each observation according to the forecaster’s attributes
create_train_X_y	Create training matrices from multiple time series and exogenous variables.
fit	Training Forecaster.
get_feature_importances	Return feature importances of the estimator.
predict	Predict n steps ahead.
predict_bootstrapping	Generate multiple forecasting predictions using a bootstrapping process.
predict_dist	Fit a given probability distribution for each step.
predict_interval	Predict n steps ahead and estimate prediction intervals.
predict_quantiles	Calculate the specified quantiles for each step.
set_fit_kwargs	Set new values for the additional keyword arguments passed to the fit method.
set_in_sample_residuals	Set in-sample residuals in case they were not calculated during training.
set_lags	Set new value to the attribute lags.
set_out_sample_residuals	Set new values to the attribute out_sample_residuals_.
set_params	Set new values to the parameters of the scikit-learn model.
set_window_features	Set new value to the attribute window_features.

create_predict_X

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.create_predict_X(
    steps,
    levels=None,
    last_window=None,
    exog=None,
    suppress_warnings=False,
    check_inputs=True,
)

Create the predictors needed to predict steps ahead.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values for predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False
check_inputs	bool	If True, check input for warnings/errors. Defaults to True.	True

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with the predictors.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(series, suppress_warnings=True)
X_predict = forecaster.create_predict_X(steps=2, suppress_warnings=True)
print("X_predict shape:", X_predict.shape)
print(X_predict.head(4))
assert "level" in X_predict.columns
assert "lag_1" in X_predict.columns
assert X_predict.shape[0] == 2 * len(forecaster.series_names_in_)

X_predict shape: (4, 5)
   level     lag_1     lag_2     lag_3  _level_skforecast
60     A -0.661703 -1.184118  0.696043                0.0
60     B  1.164864  0.843733  0.726094                1.0
61     A -0.115562 -0.661703 -1.184118                0.0
61     B  0.202789  1.164864  0.843733                1.0

create_sample_weights

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.create_sample_weights(
    series_names_in_,
    X_train,
)

Create weights for each observation according to the forecaster’s attributes series_weights and weight_func. The resulting weights are product of both types of weights.

Parameters

Name	Type	Description	Default
series_names_in_	list	Names of the series (levels) used during training.	required
X_train	pd.DataFrame	Dataframe created with the create_train_X_y method.	required

Returns

Name	Type	Description
	np.ndarray	np.ndarray: Weights to use in fit method.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
# Series A gets twice the weight of series B during training.
forecaster = ForecasterRecursiveMultiSeries(
    estimator=Ridge(),
    lags=3,
    series_weights={"A": 2.0, "B": 1.0},
)
X_train, y_train = forecaster.create_train_X_y(series, suppress_warnings=True)
weights = forecaster.create_sample_weights(
    series_names_in_=["A", "B"], X_train=X_train
)
print("weights shape:", weights.shape)
print("unique weight values:", np.unique(weights))
assert weights is not None
assert set(np.unique(weights)).issubset({1.0, 2.0})

weights shape: (114,)
unique weight values: [1. 2.]

create_train_X_y

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.create_train_X_y(
    series,
    exog=None,
    suppress_warnings=False,
)

Create training matrices from multiple time series and exogenous variables.

Parameters

Name	Type	Description	Default
series	(pd.DataFrame, dict)	Training time series.	required
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
suppress_warnings	bool	If True, skforecast warnings will be suppressed during creation. Defaults to False.	False

Returns

Name	Type	Description
tuple	tuple[pd.DataFrame, pd.Series]	A tuple containing: - X_train (pd.DataFrame): Training values (predictors). - y_train (pd.Series): Values (target) of the time series related to each row of X_train.

Notes

See _create_train_X_y for detailed information on input types.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
X_train, y_train = forecaster.create_train_X_y(
    series, suppress_warnings=True
)
print("X_train shape:", X_train.shape)
print("y_train shape:", y_train.shape)
print(X_train.head(3))
assert X_train.shape[0] == y_train.shape[0]
assert "lag_1" in X_train.columns

X_train shape: (114, 4)
y_train shape: (114,)
      lag_1     lag_2     lag_3  _level_skforecast
3  0.640423 -0.132105  0.125730                  0
4  0.104900  0.640423 -0.132105                  0
5 -0.535669  0.104900  0.640423                  0

fit

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.fit(
    series,
    exog=None,
    store_last_window=True,
    store_in_sample_residuals=False,
    random_state=123,
    suppress_warnings=False,
)

Training Forecaster.

Parameters

Name	Type	Description	Default
series	(pd.DataFrame, dict)	Training time series.	required
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
store_last_window	(bool, list)	Whether or not to store the last window (last_window_) of training data. Defaults to True.	True
store_in_sample_residuals	bool	If True, in-sample residuals will be stored in the forecaster object after fitting. Defaults to False.	False
random_state	int	Set a seed for the random generator so that the stored sample residuals are always deterministic. Defaults to 123.	123
suppress_warnings	bool	If True, skforecast warnings will be suppressed during training. Defaults to False.	False

Returns

Name	Type	Description
	None	None

Notes

• If series is a wide-format pandas DataFrame, each column represents a different time series.
• If series is a long-format pandas DataFrame with a MultiIndex, the first level of the index must contain the series IDs.
• If series is a dictionary, each key must be a series ID.
• If exog is a wide-format pandas DataFrame, it must share the same index type as series.
• If exog is a long-format pandas Series or DataFrame with a MultiIndex, the first level contains the series IDs.
• If exog is a dictionary, each key must correspond to a series ID.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(
    series,
    store_in_sample_residuals=True,
    suppress_warnings=True,
)
print("Fitted:", forecaster.is_fitted)
print("Series seen:", forecaster.series_names_in_)
assert forecaster.is_fitted
assert set(forecaster.series_names_in_) == {"A", "B"}

Fitted: True
Series seen: ['A', 'B']

get_feature_importances

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.get_feature_importances(
    sort_importance=True,
)

Return feature importances of the estimator.

Parameters

Name	Type	Description	Default
sort_importance	bool	If True, sorts the feature importances in descending order. Defaults to True.	True

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Feature importances associated with each predictor.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.ensemble import RandomForestRegressor

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(
    estimator=RandomForestRegressor(n_estimators=10, random_state=0),
    lags=3,
)
forecaster.fit(series, suppress_warnings=True)
importances = forecaster.get_feature_importances()
print(importances)
assert "feature" in importances.columns
assert "importance" in importances.columns
assert abs(importances["importance"].sum() - 1.0) < 1e-10
assert len(importances) == len(forecaster.X_train_features_names_out_)

             feature  importance
2              lag_3    0.396469
1              lag_2    0.381419
0              lag_1    0.177540
3  _level_skforecast    0.044573

predict

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.predict(
    steps,
    levels=None,
    last_window=None,
    exog=None,
    suppress_warnings=False,
    check_inputs=True,
)

Predict n steps ahead.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values for predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False
check_inputs	bool	If True, check input for warnings/errors. Defaults to True.	True

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with the predictions.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(series, suppress_warnings=True)
predictions = forecaster.predict(steps=4, suppress_warnings=True)
print(predictions)
assert predictions.shape == (8, 2)
assert "level" in predictions.columns
assert "pred" in predictions.columns

   level      pred
60     A -0.115562
60     B  0.202789
61     A  0.037961
61     B  0.158784
62     A  0.075896
62     B  0.061138
63     A  0.071201
63     B  0.086680

predict_bootstrapping

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.predict_bootstrapping(
    steps,
    levels=None,
    last_window=None,
    exog=None,
    n_boot=250,
    use_in_sample_residuals=True,
    use_binned_residuals=True,
    random_state=123,
    suppress_warnings=False,
)

Generate multiple forecasting predictions using a bootstrapping process.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values used to create predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
n_boot	int	Number of bootstrapping iterations. Defaults to 250.	250
use_in_sample_residuals	bool	If True, use residuals from training data. Defaults to True.	True
use_binned_residuals	bool	If True, residuals are selected based on predicted values. Defaults to True.	True
random_state	int	Seed for reproducibility. Defaults to 123.	123
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with the bootstrapping predictions.

References

[1] Forecasting: Principles and Practice (3rd ed) Rob J Hyndman and George Athanasopoulos. https://otexts.com/fpp3/prediction-intervals.html

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(
    series, store_in_sample_residuals=True, suppress_warnings=True
)
boot_preds = forecaster.predict_bootstrapping(
    steps=2, n_boot=5, random_state=0, suppress_warnings=True
)
print(boot_preds)
assert boot_preds.shape == (4, 6)  # 2 steps × 2 levels, 1 level col + 5 boot cols
assert "level" in boot_preds.columns
assert "pred_boot_0" in boot_preds.columns

   level  pred_boot_0  pred_boot_1  pred_boot_2  pred_boot_3  pred_boot_4
60     A    -0.499982    -1.203549    -1.203549    -0.006950    -0.006950
60     B    -0.618267    -0.724733    -0.724733    -0.724733     0.166372
61     A     0.815271     0.002330     0.891047     0.519212    -2.334749
61     B    -0.713870     1.822347     1.822347    -0.274258     1.973761

predict_dist

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.predict_dist(
    steps,
    distribution,
    levels=None,
    last_window=None,
    exog=None,
    n_boot=250,
    use_in_sample_residuals=True,
    use_binned_residuals=True,
    random_state=123,
    suppress_warnings=False,
)

Fit a given probability distribution for each step.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
distribution	object	A distribution object from scipy.stats.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values used to create predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
n_boot	int	Number of bootstrapping iterations. Defaults to 250.	250
use_in_sample_residuals	bool	If True, use residuals from training data. Defaults to True.	True
use_binned_residuals	bool	If True, residuals are selected based on predicted values. Defaults to True.	True
random_state	int	Seed for reproducibility. Defaults to 123.	123
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with parameters of the fitted distribution.

Examples

import warnings
import numpy as np
import pandas as pd
from scipy.stats import norm
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(
    series, store_in_sample_residuals=True, suppress_warnings=True
)
dist_preds = forecaster.predict_dist(
    steps=2,
    distribution=norm,
    n_boot=5,
    random_state=0,
    suppress_warnings=True,
)
print(dist_preds)
assert "loc" in dist_preds.columns
assert "scale" in dist_preds.columns
assert dist_preds.shape[0] == 4  # 2 steps × 2 levels

   level       loc     scale
60     A -0.584196  0.536789
60     B -0.525219  0.348245
61     A -0.021378  1.198080
61     B  0.926065  1.169143

predict_interval

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.predict_interval(
    steps,
    levels=None,
    last_window=None,
    exog=None,
    method='conformal',
    interval=[5, 95],
    n_boot=250,
    use_in_sample_residuals=True,
    use_binned_residuals=True,
    random_state=123,
    suppress_warnings=False,
)

Predict n steps ahead and estimate prediction intervals.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values used to create predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
method	str	Technique used to estimate prediction intervals. Options: ‘bootstrapping’, ‘conformal’. Defaults to 'conformal'.	'conformal'
interval	(float, list, tuple)	Confidence level of the prediction interval. Defaults to [5, 95].	[5, 95]
n_boot	int	Number of bootstrapping iterations. Defaults to 250.	250
use_in_sample_residuals	bool	If True, use residuals from training data. Defaults to True.	True
use_binned_residuals	bool	If True, residuals are selected based on predicted values. Defaults to True.	True
random_state	int	Seed for reproducibility. Defaults to 123.	123
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with predictions and intervals.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(
    series, store_in_sample_residuals=True, suppress_warnings=True
)
interval_preds = forecaster.predict_interval(
    steps=2, method="conformal", suppress_warnings=True
)
print(interval_preds)
assert "pred" in interval_preds.columns
assert "lower_bound" in interval_preds.columns
assert "upper_bound" in interval_preds.columns
assert interval_preds.shape[0] == 4  # 2 steps × 2 levels

   level      pred  lower_bound  upper_bound
60     A -0.115562    -0.908236     0.677112
60     B  0.202789    -0.808742     1.214321
61     A  0.037961    -1.912966     1.988888
61     B  0.158784    -1.994959     2.312527

predict_quantiles

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.predict_quantiles(
    steps,
    levels=None,
    last_window=None,
    exog=None,
    quantiles=[0.05, 0.5, 0.95],
    n_boot=250,
    use_in_sample_residuals=True,
    use_binned_residuals=True,
    random_state=123,
    suppress_warnings=False,
)

Calculate the specified quantiles for each step.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
levels	(str, list, None)	Time series to be predicted. Defaults to None.	None
last_window	(pd.DataFrame, None)	Series values used to create predictors. Defaults to None.	None
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
quantiles	(list, tuple)	Sequence of quantiles to compute (0 to 1). Defaults to [0.05, 0.5, 0.95].	[0.05, 0.5, 0.95]
n_boot	int	Number of bootstrapping iterations. Defaults to 250.	250
use_in_sample_residuals	bool	If True, use residuals from training data. Defaults to True.	True
use_binned_residuals	bool	If True, residuals are selected based on predicted values. Defaults to True.	True
random_state	int	Seed for reproducibility. Defaults to 123.	123
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Long-format DataFrame with the predicted quantiles.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(
    series, store_in_sample_residuals=True, suppress_warnings=True
)
quantile_preds = forecaster.predict_quantiles(
    steps=2,
    quantiles=[0.1, 0.5, 0.9],
    n_boot=5,
    random_state=0,
    suppress_warnings=True,
)
print(quantile_preds)
assert "q_0.1" in quantile_preds.columns
assert "q_0.9" in quantile_preds.columns
assert quantile_preds.shape[0] == 4  # 2 steps × 2 levels

   level     q_0.1     q_0.5     q_0.9
60     A -1.203549 -0.499982 -0.006950
60     B -0.724733 -0.724733 -0.147483
61     A -1.399917  0.519212  0.860737
61     B -0.538025  1.822347  1.913195

set_fit_kwargs

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_fit_kwargs(
    fit_kwargs,
)

Set new values for the additional keyword arguments passed to the fit method.

Parameters

Name	Type	Description	Default
fit_kwargs	dict	Dict of the form {“argument”: new_value}.	required

Returns

Name	Type	Description
	None	None

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.ensemble import RandomForestRegressor

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
forecaster = ForecasterRecursiveMultiSeries(
    estimator=RandomForestRegressor(n_estimators=10, random_state=0),
    lags=3,
)
forecaster.set_fit_kwargs({})
print("fit_kwargs:", forecaster.fit_kwargs)
assert isinstance(forecaster.fit_kwargs, dict)

fit_kwargs: {}

set_in_sample_residuals

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_in_sample_residuals(
    series,
    exog=None,
    random_state=123,
    suppress_warnings=False,
)

Set in-sample residuals in case they were not calculated during training.

Parameters

Name	Type	Description	Default
series	(pd.DataFrame, dict)	Training time series.	required
exog	(pd.Series, pd.DataFrame, dict, None)	Exogenous variable/s included as predictor/s. Defaults to None.	None
random_state	int	Seed for reproducibility. Defaults to 123.	123
suppress_warnings	bool	If True, suppress warnings. Defaults to False.	False

Returns

Name	Type	Description
	None	None

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
# Fit without storing in-sample residuals, then compute them afterwards.
forecaster.fit(series, store_in_sample_residuals=False, suppress_warnings=True)
forecaster.set_in_sample_residuals(
    series, random_state=0, suppress_warnings=True
)
print("in_sample_residuals_ keys:", list(forecaster.in_sample_residuals_.keys()))
assert "A" in forecaster.in_sample_residuals_
assert "B" in forecaster.in_sample_residuals_
assert "_unknown_level" in forecaster.in_sample_residuals_

in_sample_residuals_ keys: ['A', 'B', '_unknown_level']

set_lags

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_lags(
    lags=None,
)

Set new value to the attribute lags.

Parameters

Name	Type	Description	Default
lags	(int, list, np.ndarray, range, None)	Lags used as predictors. Defaults to None.	None

Returns

Name	Type	Description
	None	None

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
print("lags before:", forecaster.lags)
forecaster.set_lags([1, 2, 5])
print("lags after:", forecaster.lags)
assert list(forecaster.lags) == [1, 2, 5]
assert forecaster.max_lag == 5
assert forecaster.window_size == 5

lags before: [1 2 3]
lags after: [1 2 5]

set_out_sample_residuals

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_out_sample_residuals(
    y_true,
    y_pred,
    append=False,
    random_state=123,
)

Set new values to the attribute out_sample_residuals_.

Parameters

Name	Type	Description	Default
y_true	dict	Dictionary with the true values of the time series.	required
y_pred	dict	Dictionary with the predicted values of the time series.	required
append	bool	If True, new residuals are added to the existing ones. Defaults to False.	False
random_state	int	Seed for reproducibility. Defaults to 123.	123

Returns

Name	Type	Description
	None	None

Notes

Out-of-sample residuals can only be stored for series seen during fit.

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
rng = np.random.default_rng(0)
series = pd.DataFrame(
    {"A": rng.standard_normal(60), "B": rng.standard_normal(60)},
    index=pd.RangeIndex(60),
)
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
forecaster.fit(series, store_in_sample_residuals=True, suppress_warnings=True)

# Provide held-out true vs. predicted values for both series.
y_true = {"A": rng.standard_normal(15), "B": rng.standard_normal(15)}
y_pred = {"A": rng.standard_normal(15), "B": rng.standard_normal(15)}
forecaster.set_out_sample_residuals(
    y_true=y_true, y_pred=y_pred, random_state=0
)
print("out_sample_residuals_ keys:", list(forecaster.out_sample_residuals_.keys()))
assert "A" in forecaster.out_sample_residuals_
assert "_unknown_level" in forecaster.out_sample_residuals_

╭─────────────────────────────── ResidualsUsageWarning ────────────────────────────────╮
│ The following bins of level 'A' have no out of sample residuals: [1, 3, 4, 6, 7, 8]. │
│ No predicted values fall in the interval [(-0.06234948501196549,                     │
│ -0.023842117782350836), (0.014822197019194017, 0.03423651182704578),                 │
│ (0.03423651182704578, 0.06902995015200565), (0.09203715525675166,                    │
│ 0.12581362419200626), (0.12581362419200626, 0.14607325565711668),                    │
│ (0.14607325565711668, 0.20931967159738377)]. Empty bins will be filled with a random │
│ sample of residuals.                                                                 │
│                                                                                      │
│ Category : spotforecast2.exceptions.ResidualsUsageWarning                            │
│ Location :                                                                           │
│ /home/runner/work/spotforecast2-safe/spotforecast2-safe/src/spotforecast2_safe/forec │
│ aster/recursive/_forecaster_recursive_multiseries.py:3833                            │
│ Suppress : warnings.simplefilter('ignore', category=ResidualsUsageWarning)           │
╰──────────────────────────────────────────────────────────────────────────────────────╯

╭─────────────────────────────── ResidualsUsageWarning ────────────────────────────────╮
│ The following bins of level 'B' have no out of sample residuals: [2, 5, 6, 7, 8]. No │
│ predicted values fall in the interval [(-0.010755494695769053,                       │
│ 0.037246907723060094), (0.10234442477429201, 0.12410775318879069),                   │
│ (0.12410775318879069, 0.15552325616339985), (0.15552325616339985,                    │
│ 0.19067649479196455), (0.19067649479196455, 0.2232361691047662)]. Empty bins will be │
│ filled with a random sample of residuals.                                            │
│                                                                                      │
│ Category : spotforecast2.exceptions.ResidualsUsageWarning                            │
│ Location :                                                                           │
│ /home/runner/work/spotforecast2-safe/spotforecast2-safe/src/spotforecast2_safe/forec │
│ aster/recursive/_forecaster_recursive_multiseries.py:3833                            │
│ Suppress : warnings.simplefilter('ignore', category=ResidualsUsageWarning)           │
╰──────────────────────────────────────────────────────────────────────────────────────╯

out_sample_residuals_ keys: ['A', 'B', '_unknown_level']

set_params

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_params(
    params,
)

Set new values to the parameters of the scikit-learn model.

Parameters

Name	Type	Description	Default
params	dict	Parameter values.	required

Returns

Name	Type	Description
	None	None

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)

warnings.simplefilter("ignore")
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(alpha=1.0), lags=3)
print("alpha before:", forecaster.estimator.get_params()["alpha"])
forecaster.set_params({"alpha": 0.5})
print("alpha after:", forecaster.estimator.get_params()["alpha"])
assert forecaster.estimator.get_params()["alpha"] == 0.5
assert not forecaster.is_fitted

alpha before: 1.0
alpha after: 0.5

set_window_features

forecaster.recursive._forecaster_recursive_multiseries.ForecasterRecursiveMultiSeries.set_window_features(
    window_features=None,
)

Set new value to the attribute window_features.

Parameters

Name	Type	Description	Default
window_features	(object, list, None)	Instance or list of instances used to create window features. Defaults to None.	None

Returns

Name	Type	Description
	None	None

Examples

import warnings
import numpy as np
import pandas as pd
from sklearn.linear_model import Ridge

from spotforecast2_safe.forecaster.recursive._forecaster_recursive_multiseries import (
    ForecasterRecursiveMultiSeries,
)
from spotforecast2_safe.preprocessing import RollingFeatures

warnings.simplefilter("ignore")
forecaster = ForecasterRecursiveMultiSeries(estimator=Ridge(), lags=3)
print("window_features before:", forecaster.window_features)
forecaster.set_window_features(RollingFeatures(stats="mean", window_sizes=4))
print("window_features after:", forecaster.window_features_names)
assert forecaster.window_features is not None
assert "roll_mean_4" in forecaster.window_features_names

window_features before: None
window_features after: ['roll_mean_4']