forecaster.base

forecaster.base

ForecasterBase class.

This module contains the base class for all forecasters in spotforecast2_safe and spotforecast. All forecasters should specify all the parameters that can be set at the class level in their init.

Examples

Create a custom forecaster inheriting from ForecasterBase:

>>> from spotforecast2_safe.forecaster.base import ForecasterBase
>>> import pandas as pd
>>> import numpy as np
>>> class MyForecaster(ForecasterBase):
...     def __init__(self, estimator):
...         self.estimator = estimator
...         self.__spotforecast_tags__ = {'hide_lags': True}
...     def create_train_X_y(self, y, exog=None):
...         return pd.DataFrame(), pd.Series(dtype=float)
...     def fit(self, y, exog=None):
...         pass
...     def predict(self, steps, last_window=None, exog=None):
...         return pd.Series(np.zeros(steps))
...     def set_params(self, params):
...         pass
>>> from sklearn.linear_model import Ridge
>>> forecaster = MyForecaster(estimator=Ridge())
>>> forecaster
MyForecaster(estimator=Ridge())

Classes

Name	Description
ForecasterBase	Base class for all forecasters in spotforecast2.

ForecasterBase

forecaster.base.ForecasterBase()

Base class for all forecasters in spotforecast2.

All forecasters should specify all the parameters that can be set at the class level in their init.

Attributes

Name	Type	Description
spotforecast_tags		Dictionary with forecaster tags that characterize the behavior of the forecaster.

Examples

To see all abstract methods that need to be implemented:

>>> import inspect
>>> from spotforecast2_safe.forecaster.base import ForecasterBase
>>> [m[0] for m in inspect.getmembers(ForecasterBase, predicate=inspect.isabstract)]
['create_train_X_y', 'fit', 'predict', 'set_params']

Methods

Name	Description
create_train_X_y	Create training matrices from univariate time series and exogenous variables.
fit	Training Forecaster.
get_tags	Return the tags that characterize the behavior of the forecaster.
predict	Predict n steps ahead.
set_lags	Set new value to the attribute lags.
set_params	Set new values to the parameters of the scikit-learn model stored in the forecaster.
set_window_features	Set new value to the attribute window_features.
summary	Show forecaster information.

create_train_X_y

forecaster.base.ForecasterBase.create_train_X_y(y, exog=None)

Create training matrices from univariate time series and exogenous variables.

Parameters

Name	Type	Description	Default
y	pd.Series	Training time series.	required
exog	pd.Series \| pd.DataFrame \| None	Exogenous variable(s) included as predictor(s). Must have the same number of observations as y and their indexes must be aligned. Default is None.	`None`

Returns

Name	Type	Description
	pd.DataFrame	Tuple containing X_train (training values/predictors with shape
	pd.Series	(len(y) - max_lag, len(lags))) and y_train (target values of the
	tuple[pd.DataFrame, pd.Series]	time series related to each row of X_train with shape (len(y) - max_lag,)).

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> import pandas as pd
>>> import numpy as np
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> y = pd.Series(np.arange(10), name='y')
>>> X_train, y_train = forecaster.create_train_X_y(y)
>>> X_train.head(2)
   lag_1  lag_2  lag_3
3    2.0    1.0    0.0
4    3.0    2.0    1.0
>>> y_train.head(2)
3    3
4    4
Name: y, dtype: int64

fit

forecaster.base.ForecasterBase.fit(y, exog=None)

Training Forecaster.

Parameters

Name	Type	Description	Default
y	pd.Series	Training time series.	required
exog	pd.Series \| pd.DataFrame \| None	Exogenous variable(s) included as predictor(s). Must have the same number of observations as y and their indexes must be aligned so that y[i] is regressed on exog[i]. Default is None.	`None`

Returns

Name	Type	Description
	None	None

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> import pandas as pd
>>> import numpy as np
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> y = pd.Series(np.arange(10), name='y')
>>> forecaster.fit(y)
>>> forecaster.is_fitted
True

get_tags

forecaster.base.ForecasterBase.get_tags()

Return the tags that characterize the behavior of the forecaster.

Returns

Name	Type	Description
	dict[str, Any]	Dictionary with forecaster tags describing behavior and capabilities.

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> tags = forecaster.get_tags()
>>> tags['forecaster_task']
'regression'

predict

forecaster.base.ForecasterBase.predict(steps, last_window=None, exog=None)

Predict n steps ahead.

Parameters

Name	Type	Description	Default
steps	int	Number of steps to predict.	required
last_window	pd.Series \| pd.DataFrame \| None	Series values used to create the predictors (lags) needed in the first iteration of the prediction (t + 1). If None, the values stored in last_window are used to calculate the initial predictors, and the predictions start right after training data. Default is None.	`None`
exog	pd.Series \| pd.DataFrame \| None	Exogenous variable(s) included as predictor(s). Default is None.	`None`

Returns

Name	Type	Description
	pd.Series	Predicted values as a pandas Series.

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> import pandas as pd
>>> import numpy as np
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> y = pd.Series(np.arange(10), name='y')
>>> forecaster.fit(y)
>>> forecaster.predict(steps=3)
10    9.5
11    9.0
12    8.5
Name: pred, dtype: float64

set_lags

forecaster.base.ForecasterBase.set_lags(lags=None)

Set new value to the attribute lags.

Attributes max_lag and window_size are also updated.

Parameters

Name	Type	Description	Default
lags	int \| list[int] \| np.ndarray[int] \| range[int] \| None	Lags used as predictors. Index starts at 1, so lag 1 is equal to t-1. If int: include lags from 1 to lags (included). If list, 1d numpy ndarray, or range: include only lags present in lags, all elements must be int. If None: no lags are included as predictors. Default is None.	`None`

Returns

Name	Type	Description
	None	None

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> forecaster.set_lags(lags=5)
>>> forecaster.lags
array([1, 2, 3, 4, 5])

set_params

forecaster.base.ForecasterBase.set_params(params)

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

Parameters

Name	Type	Description	Default
params	dict[str, object]	Parameters values dictionary.	required

Returns

Name	Type	Description
	None	None

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> forecaster = ForecasterRecursive(estimator=Ridge(alpha=1.0), lags=3)
>>> forecaster.set_params({'estimator__alpha': 0.5})
>>> forecaster.estimator.alpha
0.5

set_window_features

forecaster.base.ForecasterBase.set_window_features(window_features=None)

Set new value to the attribute window_features.

Attributes max_size_window_features, window_features_names, window_features_class_names and window_size are also updated.

Parameters

Name	Type	Description	Default
window_features	object \| list[object] \| None	Instance or list of instances used to create window features. Window features are created from the original time series and are included as predictors. Default is None.	`None`

Returns

Name	Type	Description
	None	None

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from spotforecast2_safe.forecaster.preprocessing import RollingFeatures
>>> from sklearn.linear_model import Ridge
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> window_feat = RollingFeatures(stats='mean', window_sizes=3)
>>> forecaster.set_window_features(window_features=window_feat)
>>> forecaster.window_features
[RollingFeatures(stats=['mean'], window_sizes=[3])]

summary

forecaster.base.ForecasterBase.summary()

Show forecaster information.

Returns

Name	Type	Description
	None	None

Examples

>>> from spotforecast2_safe.forecaster.recursive import ForecasterRecursive
>>> from sklearn.linear_model import Ridge
>>> forecaster = ForecasterRecursive(estimator=Ridge(), lags=3)
>>> forecaster.summary()
ForecasterRecursive
===================
Estimator: Ridge()
Lags: [1 2 3]
...