gbnet.models.forecasting

Classes

Forecast	A forecasting model class that implements a trend + seasonality + changepoints
ForecastModule	PyTorch module for time series forecasting.

Functions

pd_datetime_to_seconds(x)
loadModule(module)
piecewise_linear_function(changepoints, timepoints)	Calculate a piecewise linear function based on changepoints evaluated at timepoints.
_get_uncertainty_params(m, train_residuals, train)
_mle_G(r, h, S2[, bracket_pad])	MLE for G in Var(r_i)=S2 + G*h_i with known S2.

Module Contents

gbnet.models.forecasting.pd_datetime_to_seconds(x)

Parameters:

x (pandas.Series)

gbnet.models.forecasting.loadModule(module)

class gbnet.models.forecasting.Forecast(nrounds=50, params={}, module_type='XGBModule', linear_params={}, changepoint_params={}, estimate_uncertainty=True)

Bases: sklearn.base.BaseEstimator, sklearn.base.RegressorMixin

A forecasting model class that implements a trend + seasonality + changepoints model using either XGBModule or LGBModule (but defaulting to XGBModule).

Parameters:

• nrounds (int, default=50) – Number of training iterations (epochs) for the model.

• params (dict, optional) – Dictionary of additional parameters to be passed to the underlying forecast model. Defaults to {“eta”: 0.17, “max_depth”: 3, “lambda”: 1, “alpha”: 8}

• module_type (str, default="XGBModule") – Type of gradient boosting module to use, either “XGBModule” or “LGBModule”.

• linear_params (dict, default={}) – Parameters to pass to GBLinear. Defaults to {“min_hess”: 0.0, “lambd”: 0.1, “lr”: 0.9}

• changepoint_params (dict, default={}) –

  Parameters for changepoint detection and modeling. Defaults to: {

  ”n_changepoints”: 32, # how many changepoints to consider “eta”: 0.9, “max_depth”: 9, “lambda”: 6.5, “alpha”: 3.8, “cp_gap”: 0.5, # portion of time series allowing changepoints “cp_train_gap”: 4 # how many training rounds to NOT update the periodic component

  }

Variables:

• nrounds (int) – Number of training rounds for the model.

• params (dict) – Additional parameters passed to the forecast model.

• model (ForecastModule or None) – Trained forecast model instance. Set after fitting.

• losses (list) – List of loss values recorded at each training iteration.

fit(X, y)

Trains the forecast model using the input features X and target variable y. X must contain the datetime column ‘ds’.

predict(X, components=False)

Predicts target values based on the input features X. If components=True, returns tuple of (trend, periodic, changepoint) components.

Notes

The model uses a linear trend + periodic function + changepoints via XGBModule or LGBModule. The loss function used is Mean Squared Error (MSE). The trend component uses GBLinear. Changepoints allow the model to capture changes in the time series trend.

nrounds = 50

model_ = None

losses_ = []

module_type = 'XGBModule'

trend_type = 'GBLinear'

params

linear_params

changepoint_params

estimate_uncertainty = True

fit(X, y=None)

predict(X)

class gbnet.models.forecasting.ForecastModule(n, params=None, module_type='XGBModule', trend_type='GBLinear', linear_params={}, changepoint_params={})

Bases: torch.nn.Module

PyTorch module for time series forecasting.

This module combines a linear trend component with a periodic function and changepoints learned through gradient boosting to model time series data. The trend is modeled using GBLinear layer, while the periodic patterns and changepoints are captured by either XGBoost or LightGBM.

Parameters:

• n (int) – Number of samples in training data

• params (dict, optional) – Parameters passed to the gradient boosting model. Defaults to None.

• module_type (str, optional) – Type of gradient boosting module to use, either “XGBModule” or “LGBModule”. Defaults to “XGBModule”.

• trend_type (str, optional) – Type of trend model to use, either “PyTorch” or “GBLinear”. Defaults to “GBLinear”.

• linear_params (dict, optional) – Parameters passed to GBLinear trend model if trend_type=”GBLinear”. Defaults to {}.

• changepoint_params (dict, optional) –

  Parameters for changepoint detection and modeling. Defaults to: {

  ”n_changepoints”: 100, “gbmodule”: “XGBModule”, “cp_gap”: 0.9, “cp_train_gap”: 10

  }

Variables:

• trend (Union[torch.nn.Linear, GBLinear]) – Linear layer for modeling trend component, either PyTorch Linear or GBLinear

• bn (torch.nn.BatchNorm1d) – Batch normalization layer (only used with PyTorch trend)

• periodic_fn (XGBModule or LGBModule) – Gradient boosting module for modeling periodic patterns

• trend_fn (XGBModule or LGBModule) – Gradient boosting module for modeling changepoints

• initialized (bool) – Whether the model has been initialized with initial trend estimates

• trend_type (str) – Type of trend model being used

initialize(df)

Initializes trend parameters using least squares regression

forward(df, components=False)

Forward pass combining trend, periodic, and changepoint components

gb_step()

Performs one gradient boosting step for all components

initialized = False

trend_type = 'GBLinear'

periodic_fn

n_changepoints

cp_gap

cp_module

cp_train_gap

trend_fn

cp_train_count = 0

use_cp = True

_changepoint_initialize(df)

_gblinear_initialize(df)

initialize(df)

forward(df, components=False)

forward_changepoints(df)

gb_step()

gbnet.models.forecasting.piecewise_linear_function(changepoints, timepoints)

Calculate a piecewise linear function based on changepoints evaluated at timepoints.

For every tp in timepoints, compute: Sum_{(cp1, cp2) such that cp1 < tp} cp2 * (tp - cp1)

Parameters:

• changepoints – torch.Tensor of shape [N, 2] where: - First column (cp1) contains the positions of changepoints - Second column (cp2) contains the slopes at those changepoints

• timepoints – torch.Tensor of shape [M] containing points to evaluate the function

Returns:

torch.Tensor of shape [M] containing the evaluated function at each timepoint

gbnet.models.forecasting._get_uncertainty_params(m, train_residuals, train)

gbnet.models.forecasting._mle_G(r, h, S2, bracket_pad=1.0)

MLE for G in Var(r_i)=S2 + G*h_i with known S2. Returns (G_hat, diagnostics)