Regressor Module

The regressor module provides classes for time series regression and forecasting.

class tide.regressors.SkSTLForecast(period='24h', trend='15d', ar_model='ARIMA', seasonal=None, stl_kwargs=None, ar_kwargs=None, backcast=False)

Bases: RegressorMixin, BaseSTL

A model designed for time series forecasting or backcasting (predicting past values). It applies seasonal-trend decomposition (STL) to the training data to capture both trend and seasonal patterns. The model then uses ARIMA or a custom autoregressive model to predict these components, as well as the overall observed variable.

Parameters:

• period (int, str, or datetime.timedelta) – The period of the time series (e.g., daily, weekly, monthly, etc.). Can be an integer, string, or timedelta. This defines the seasonal periodicity for the STL decomposition.

• trend (int, str, or datetime.timedelta) – The length of the trend smoother. If an int is specified, it must be odd and larger than season. Statsplot indicate it is usually around 150% of season. Strongly depends on your time series.

• ar_model (object, optional) – A string corresponding to the name of the Autoregressive model to be used to predict STL trend an periodic component. The name must be chosen among MODEL_MAP keys() If not provided, ARIMA will be used as the default model.

• seasonal (int, str, or datetime.timedelta, optional) – The seasonal component’s smoothing parameter for STL. It defines how much the seasonal component is smoothed. If given as an integer, it must be an odd number. If None, a default value will be used.

• stl_kwargs (dict[str, float], optional) – Additional keyword arguments for the STL decomposition. These allow fine-tuning of the decomposition process. (https://www.statsmodels.org/stable/index.html)

• ar_kwargs (dict, optional) – Keyword arguments to be passed to the autoregressive model (e.g., order for ARIMA).

• backcast (bool, optional) – If True, the model will be trained to backcast (predict the past), otherwise, it will perform standard forward forecasting.

Variables:

• forecaster (dict) – Dictionary containing the fitted forecaster for each feature in the time series.

• train_dat_end (pandas.Timestamp) – Timestamp of the last data point used in training.

• training_freq (pandas.tseries.offsets.BaseOffset) – Frequency of the training data, either provided explicitly or inferred.

__init__(period='24h', trend='15d', ar_model='ARIMA', seasonal=None, stl_kwargs=None, ar_kwargs=None, backcast=False)

fit(X, y=pandas.core.series.Series | pandas.core.frame.DataFrame)

predict(X)

class tide.regressors.SkProphet(prophet_kwargs={}, changepoint_prior_scale=0.05, seasonality_prior_scale=10.0, return_upper_lower_bounds=False, backcast=False)

Bases: RegressorMixin, BaseEstimator, TideBaseMixin

A scikit-learn compatible wrapper for Meta Prophet forecasting model.

This class combines the functionality of Prophet with scikit-learn’s API, allowing it to be used in scikit-learn pipelines and model selection tools. It supports multi-feature forecasting, with a separate Prophet model fitted for each feature.

Parameters:

• prophet_kwargs (dict, optional (default={})) – Additional keyword arguments to be passed to the Prophet model.

• changepoint_prior_scale (float, optional (default=0.05)) – Determines the flexibility of the automatic changepoint selection. Large values allow many changepoints, small values allow few changepoints.

• seasonality_prior_scale (float, optional (default=10.0)) – Parameter modulating the strength of the seasonality model. Larger values allow the model to fit larger seasonal fluctuations.

• return_upper_lower_bounds (bool, optional (default=False)) – If True, return upper and lower prediction bounds along with the forecast.

• backcast (bool, optional (default=False)) – No effect, just here for tide FillGapAR compatibility.

Variables:

• forecaster (dict) – A dictionary of fitted Prophet models, one for each feature.

• feature_names_in (list) – The feature names seen during fit.

fit(X, y=None)

Fit the Prophet model to the input data.

predict(X)

Make predictions using the fitted Prophet model.

Examples

>>> import pandas as pd
>>> import numpy as np
>>> import datetime as dt
>>> from tide.regressors import SkProphet

>>> index = pd.date_range("2009-01-01", "2009-12-31 23:00:00", freq="h", tz="UTC")
>>> cumsum_second = np.arange(
...     0, (index[-1] - index[0]).total_seconds() + 1, step=3600
... )

>>> annual = 5 * -np.cos(
... 2 * np.pi / dt.timedelta(days=360).total_seconds() * cumsum_second
...)

>>> daily = 5 * np.sin(
... 2 * np.pi / dt.timedelta(days=1).total_seconds() * cumsum_second
...)

>>> toy_series = pd.Series(annual + daily + 5, index=index)

>>> exo = 12 + 3 * np.arange(index.shape[0])

>>> toy_df = pd.DataFrame(
...    {
...        "Temp_3__°C": toy_series + exo,
...        "Exo": exo,
...    }
...)

>>> forecaster = SkProphet()
>>> forecaster.fit(
...    X=toy_df.loc["2009-01-24":"2009-07-24", "Exo"],
...    y=toy_df.loc["2009-01-24":"2009-07-24", "Temp_3__°C"],
...)

>>> result = forecaster.predict(X=toy_df.loc["2009-07-25":"2009-07-30", "Exo"])
>>> print(result.head())
                             Temp_3__°C
2009-07-25 00:00:00+00:00  14781.715143
2009-07-25 01:00:00+00:00  14786.009401
2009-07-25 02:00:00+00:00  14790.215280
2009-07-25 03:00:00+00:00  14794.250621
2009-07-25 04:00:00+00:00  14798.044970

Notes

• Additional regressors are passed in X during fitting operation

• Holidays cannot be configured in this regressor. We recommend to pass it

as a feature during the fitting process. It will be treated as an additional regressor

Returns:

A DataFrame with DateTime index. Columns are the y targets

Return type:

pd.DataFrame

__init__(prophet_kwargs={}, changepoint_prior_scale=0.05, seasonality_prior_scale=10.0, return_upper_lower_bounds=False, backcast=False)

fit(X, y=pandas.core.series.Series | pandas.core.frame.DataFrame)

predict(X)