gbnet.models.forecasting ======================== .. py:module:: gbnet.models.forecasting Classes ------- .. autoapisummary:: gbnet.models.forecasting.Forecast gbnet.models.forecasting.ForecastModule Functions --------- .. autoapisummary:: gbnet.models.forecasting.pd_datetime_to_seconds gbnet.models.forecasting.loadModule gbnet.models.forecasting.piecewise_linear_function gbnet.models.forecasting._get_uncertainty_params gbnet.models.forecasting._mle_G Module Contents --------------- .. py:function:: pd_datetime_to_seconds(x) .. py:function:: loadModule(module) .. py:class:: Forecast(nrounds=50, params={}, module_type='XGBModule', linear_params={}, changepoint_params={}, estimate_uncertainty=True) Bases: :py:obj:`sklearn.base.BaseEstimator`, :py:obj:`sklearn.base.RegressorMixin` A forecasting model class that implements a trend + seasonality + changepoints model using either XGBModule or LGBModule (but defaulting to XGBModule). :param nrounds: Number of training iterations (epochs) for the model. :type nrounds: int, default=50 :param params: Dictionary of additional parameters to be passed to the underlying forecast model. Defaults to {"eta": 0.17, "max_depth": 3, "lambda": 1, "alpha": 8} :type params: dict, optional :param module_type: Type of gradient boosting module to use, either "XGBModule" or "LGBModule". :type module_type: str, default="XGBModule" :param linear_params: Parameters to pass to GBLinear. Defaults to {"min_hess": 0.0, "lambd": 0.1, "lr": 0.9} :type linear_params: dict, default={} :param changepoint_params: 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 } :type changepoint_params: dict, default={} :ivar nrounds: Number of training rounds for the model. :vartype nrounds: int :ivar params: Additional parameters passed to the forecast model. :vartype params: dict :ivar model_: Trained forecast model instance. Set after fitting. :vartype model_: ForecastModule or None :ivar losses_: List of loss values recorded at each training iteration. :vartype losses_: list .. method:: fit(X, y) Trains the forecast model using the input features X and target variable y. X must contain the datetime column 'ds'. .. method:: predict(X, components=False) Predicts target values based on the input features X. If components=True, returns tuple of (trend, periodic, changepoint) components. .. rubric:: 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. .. py:attribute:: nrounds :value: 50 .. py:attribute:: model_ :value: None .. py:attribute:: losses_ :value: [] .. py:attribute:: module_type :value: 'XGBModule' .. py:attribute:: trend_type :value: 'GBLinear' .. py:attribute:: params .. py:attribute:: linear_params .. py:attribute:: changepoint_params .. py:attribute:: estimate_uncertainty :value: True .. py:method:: fit(X, y=None) .. py:method:: predict(X) .. py:class:: ForecastModule(n, params=None, module_type='XGBModule', trend_type='GBLinear', linear_params={}, changepoint_params={}) Bases: :py:obj:`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. :param n: Number of samples in training data :type n: int :param params: Parameters passed to the gradient boosting model. Defaults to None. :type params: dict, optional :param module_type: Type of gradient boosting module to use, either "XGBModule" or "LGBModule". Defaults to "XGBModule". :type module_type: str, optional :param trend_type: Type of trend model to use, either "PyTorch" or "GBLinear". Defaults to "GBLinear". :type trend_type: str, optional :param linear_params: Parameters passed to GBLinear trend model if trend_type="GBLinear". Defaults to {}. :type linear_params: dict, optional :param changepoint_params: Parameters for changepoint detection and modeling. Defaults to: { "n_changepoints": 100, "gbmodule": "XGBModule", "cp_gap": 0.9, "cp_train_gap": 10 } :type changepoint_params: dict, optional :ivar trend: Linear layer for modeling trend component, either PyTorch Linear or GBLinear :vartype trend: Union[torch.nn.Linear, GBLinear] :ivar bn: Batch normalization layer (only used with PyTorch trend) :vartype bn: torch.nn.BatchNorm1d :ivar periodic_fn: Gradient boosting module for modeling periodic patterns :vartype periodic_fn: XGBModule or LGBModule :ivar trend_fn: Gradient boosting module for modeling changepoints :vartype trend_fn: XGBModule or LGBModule :ivar initialized: Whether the model has been initialized with initial trend estimates :vartype initialized: bool :ivar trend_type: Type of trend model being used :vartype trend_type: str .. method:: initialize(df) Initializes trend parameters using least squares regression .. method:: forward(df, components=False) Forward pass combining trend, periodic, and changepoint components .. method:: gb_step() Performs one gradient boosting step for all components .. py:attribute:: initialized :value: False .. py:attribute:: trend_type :value: 'GBLinear' .. py:attribute:: periodic_fn .. py:attribute:: n_changepoints .. py:attribute:: cp_gap .. py:attribute:: cp_module .. py:attribute:: cp_train_gap .. py:attribute:: trend_fn .. py:attribute:: cp_train_count :value: 0 .. py:attribute:: use_cp :value: True .. py:method:: _changepoint_initialize(df) .. py:method:: _gblinear_initialize(df) .. py:method:: initialize(df) .. py:method:: forward(df, components=False) .. py:method:: forward_changepoints(df) .. py:method:: gb_step() .. py:function:: 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) :param 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 :param 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 .. py:function:: _get_uncertainty_params(m, train_residuals, train) .. py:function:: _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)