gbnet.lgbmodule
===============

.. py:module:: gbnet.lgbmodule


Classes
-------

.. autoapisummary::

   gbnet.lgbmodule.LGBModule
   gbnet.lgbmodule.LightGBObj


Module Contents
---------------

.. py:class:: LGBModule(batch_size, input_dim, output_dim, params={}, min_hess=0)

   Bases: :py:obj:`gbnet.base.BaseGBModule`


   LightGBM Module that wraps LightGBM boosting into a PyTorch Module.

   This module allows integration of LightGBM gradient boosting with PyTorch neural networks.
   It maintains the boosting model state and handles both training and inference.

   :param batch_size: Size of training data
   :type batch_size: int
   :param input_dim: Dimension of input features
   :type input_dim: int
   :param output_dim: Dimension of output predictions
   :type output_dim: int
   :param params: Parameters passed to LightGBM. Defaults to {}.
   :type params: dict, optional
   :param min_hess: Minimum hessian value submitted to LightGBM. Defaults to 0.
   :type min_hess: float, optional

   :ivar batch_size: Size of mini-batches
   :vartype batch_size: int
   :ivar input_dim: Input feature dimension
   :vartype input_dim: int
   :ivar output_dim: Output prediction dimension
   :vartype output_dim: int
   :ivar params: LightGBM parameters
   :vartype params: dict
   :ivar bst: The underlying LightGBM booster
   :vartype bst: lightgbm.Booster
   :ivar FX: Current predictions tensor
   :vartype FX: torch.nn.Parameter
   :ivar train_dat: Training dataset used for caching
   :vartype train_dat: lightgbm.Dataset
   :ivar min_hess: Minimum hessian threshold

   :vartype min_hess: float


   .. py:attribute:: batch_size


   .. py:attribute:: input_dim


   .. py:attribute:: output_dim


   .. py:attribute:: params


   .. py:attribute:: bst
      :value: None



   .. py:attribute:: FX


   .. py:attribute:: train_dat
      :value: None



   .. py:attribute:: min_hess
      :value: 0



   .. py:attribute:: grad
      :value: None



   .. py:attribute:: hess
      :value: None



   .. py:method:: _set_train_dat(input_dataset)


   .. py:method:: _input_checking_setting(input_dataset)


   .. py:method:: forward(input_dataset, return_tensor=True)

      Forward pass through the LightGBM module.

      :param input_dataset: Input data for prediction.
                            Can be a LightGBM Dataset, numpy array, or pandas DataFrame.
      :type input_dataset: Union[lgb.Dataset, np.ndarray, pd.DataFrame]
      :param return_tensor: Whether to return predictions as a PyTorch tensor.
                            Defaults to True.
      :type return_tensor: bool, optional

      :returns: Model predictions. Returns a PyTorch tensor if
                return_tensor=True, otherwise returns a numpy array.
      :rtype: Union[torch.Tensor, np.ndarray]

      The forward pass handles both train and eval
      - In train mode, maintains state between iterations and updates internal FX tensor
      - In eval mode, generates predictions on new data using the trained model



   .. py:method:: gb_calc()


   .. py:method:: gb_step()

      Performs a gradient boosting step to update the model.

      This method:
      1. Computes gradients and hessians from the current predictions
      2. Creates a LightGBM objective using the computed gradients/hessians
      3. Updates the internal boosting model by either:
         - Updating the existing model if one exists
         - Training a new model for 1 boosting round if no model exists

      The gradients are scaled by batch size and hessians are clipped to a minimum value
      to ensure numerical stability.

      :returns: None



   .. py:method:: get_extra_state()


   .. py:method:: set_extra_state(state)


.. py:class:: LightGBObj(grad, hess)

   Helper class for use with LightGBM as a backend for LGBModule


   .. py:attribute:: grad


   .. py:attribute:: hess


   .. py:method:: __call__(y_true, y_pred)