gbnet.models.survival.hazard_survival
=====================================

.. py:module:: gbnet.models.survival.hazard_survival


Classes
-------

.. autoapisummary::

   gbnet.models.survival.hazard_survival.HazardSurvivalModel


Functions
---------

.. autoapisummary::

   gbnet.models.survival.hazard_survival.expand_overlapping_units_locf


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

.. py:class:: HazardSurvivalModel(nrounds=None, params=None, module_type='LGBModule', min_hess=0.0, input_is_expanded=False, integration_method='trapezoid')

   Bases: :py:obj:`sklearn.base.BaseEstimator`, :py:obj:`sklearn.base.RegressorMixin`


   Gradient Boosting Hazard Integration Survival Model.

   This model combines gradient boosting with hazard integration for continuous
   survival analysis. It uses either XGBoost or LightGBM as the underlying
   boosting engine wrapped in a PyTorch module.

   The model supports both static and time-varying datasets:
   - Static datasets: Each unit has one observation with static features
   - Time-varying datasets: Each unit has multiple observations over time

   :param nrounds: Number of boosting rounds. Defaults to 100.
   :type nrounds: int, optional
   :param params: Additional parameters passed to the gradient boosting model.
   :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 min_hess: Minimum hessian value for numerical stability. Defaults to 0.0.
   :type min_hess: float, optional
   :param input_is_expanded: If True, trust X already contains the intended unit-time rows and skip
                             internal expansion. Defaults to False.
   :type input_is_expanded: bool, optional
   :param integration_method: Method for integrating hazards and survival estimates. One of
                              "trapezoid", "stepwise_left", or "stepwise_right".
   :type integration_method: str, optional

   :ivar integrator_: Trained hazard integrator module. Set after fitting.
   :vartype integrator_: HazardIntegrator
   :ivar losses_: List of loss values recorded at each training iteration.
   :vartype losses_: list
   :ivar data_format_: Detected data format: 'static' or 'time_varying'.

   :vartype data_format_: str

   .. method:: fit(X, y)

      Trains the model using input features X and survival data y.

   .. method:: predict_survival(X, times)

      Predicts survival probabilities for given times.

   .. method:: predict_hazard(X, times)

      Predicts hazard values for given times.

   .. method:: predict(X)

      Predicts the expected survival time.

   .. method:: score(X, y)

      Returns the negative log likelihood score.


   .. rubric:: Notes

   The model uses hazard integration to model continuous survival times.
   The gradient boosting model learns hazard rates for each time point,
   which are then integrated to compute survival probabilities.

   Supported data formats:
   - Static: X is DataFrame with static features, y is DataFrame with 'time', 'event', 'unit_id'
   - Time-varying: X is DataFrame with time-varying features, y has 'time', 'event', 'unit_id'

   For survival data, y must be a DataFrame containing:
   - 'time': observed time (continuous)
   - 'event': event indicator (0=censored, 1=event)
   - 'unit_id': unique identifier for each unit/subject


   .. py:attribute:: params
      :value: None



   .. py:attribute:: module_type
      :value: 'LGBModule'



   .. py:attribute:: nrounds
      :value: None



   .. py:attribute:: min_hess
      :value: 0.0



   .. py:attribute:: input_is_expanded
      :value: False



   .. py:attribute:: integration_method
      :value: 'trapezoid'



   .. py:attribute:: losses_
      :value: []



   .. py:attribute:: data_format_
      :value: None



   .. py:method:: _static_to_minimal_time_varying_dataset(X)


   .. py:method:: _warn_if_expanded_input_missing_times(X, y)


   .. py:method:: _validate_and_convert_input_data(X, y)

      Validate input data according to the new requirements.

      :param X: Input features
      :type X: pd.DataFrame
      :param y: Survival data with 'time', 'event', 'unit_id' columns
      :type y: pd.DataFrame

      :returns: (data_format, modified_X) where data_format is 'static' or 'time_varying'
                and modified_X is the potentially modified X DataFrame
      :rtype: tuple



   .. py:method:: fit(X, y)

      Fit the hazard integration survival model.

      :param X: Training features. Can be static or time-varying.
      :type X: pd.DataFrame
      :param y: Survival data with 'time', 'event', 'unit_id' columns.
      :type y: pd.DataFrame

      :returns: **self** -- Returns self.
      :rtype: object



   .. py:method:: predict_base(X, y)


   .. py:method:: predict_times(X, times=None)


   .. py:method:: predict_survival(X, times=None)


   .. py:method:: predict(X, times=None)


   .. py:method:: score(X, y)

      Return the negative log likelihood score.



.. py:function:: expand_overlapping_units_locf(df, y = None, unit_col = 'unit_id', time_col = 'time')