splisosm.logger
===============

.. py:module:: splisosm.logger

.. autoapi-nested-parse::

   Training logger utilities for GLM/GLMM optimization.



Classes
-------

.. autoapisummary::

   splisosm.logger.PatienceLogger


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

.. py:class:: PatienceLogger(batch_size, patience, min_delta = 1e-05, tol_relative = False, diagnose = False, store_param_history = False)

   Logger for tracking training patience and convergence.

   For training MultinomGLM and MultinomGLMM.

   Loss history is always recorded (one scalar per gene per epoch).
   Per-epoch *parameter* snapshots are only stored when
   ``store_param_history=True``.

   :param batch_size: Number of samples in the batch.
   :param patience: Number of epochs to wait after the last significant improvement.
   :param min_delta: Minimum change in the loss to qualify as an improvement.
                     Interpreted as an absolute change when ``tol_relative=False``
                     (default) or as a fraction of the current best loss when
                     ``tol_relative=True``.
   :param tol_relative: If ``True``, ``min_delta`` is treated as a *relative* threshold:
                        an epoch counts as a "big improvement" only when
                        ``(best - current) / max(|best|, 1) >= min_delta``.
                        Relative mode is more robust when the loss scale varies widely
                        across genes or datasets.  Default ``False`` preserves the
                        original absolute behaviour.
   :param diagnose: Deprecated alias for ``store_param_history``.  Will be removed in
                    a future version.
   :param store_param_history: Whether to store per-epoch parameter snapshots during training.
                               This can consume significant memory (O(epochs × n_genes × params)).
                               Loss history is always stored regardless of this flag.


   .. py:method:: get_params_iter()

      Return stored parameter history if ``store_param_history=True``.

      :returns: Dictionary ``{"loss": list[Tensor], "params": list[dict]}`` where
                each entry corresponds to one epoch, if ``store_param_history=True``;
                otherwise ``None``.
      :rtype: dict or None



   .. py:method:: log(loss, params)

      Log loss for a given epoch and update best parameters if improved.

      :param loss: Loss for the current epoch, shape ``(batch_size,)``.
      :param params: Current model parameters, keyed by parameter name.



   .. py:attribute:: batch_size


   .. py:attribute:: best_epoch


   .. py:attribute:: best_loss


   .. py:attribute:: best_params
      :value: None



   .. py:attribute:: convergence


   .. py:attribute:: epoch
      :value: 0



   .. py:attribute:: epochs_without_improvement


   .. py:property:: loss_history
      :type: torch.Tensor


      Loss history as a 2-D tensor of shape ``(n_epochs, batch_size)``.

      Each row is the per-gene negative log-likelihood at that epoch.
      Always available after at least one call to :meth:`log`.


   .. py:attribute:: min_delta
      :value: 1e-05



   .. py:attribute:: patience


   .. py:attribute:: store_param_history
      :value: False



   .. py:attribute:: tol_relative
      :value: False