prolint.analysis.kinetics
=========================

.. py:module:: prolint.analysis.kinetics

.. autoapi-nested-parse::

   Kinetics analysis for binding/unbinding dynamics.



Attributes
----------

.. autoapisummary::

   prolint.analysis.kinetics.logger


Classes
-------

.. autoapisummary::

   prolint.analysis.kinetics.KineticsAnalysis


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

.. py:data:: logger

.. py:class:: KineticsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)

   Bases: :py:obj:`prolint.analysis.base.BaseAnalysis`


   Kinetics analysis for binding/unbinding dynamics.

   Computes binding kinetics metrics including on/off rates, residence times,
   and survival curves with optional exponential fits.

   .. attribute:: MIN_EVENTS_MONO

      Minimum events required for monoexponential fit (default: 5).

      :type: int

   .. attribute:: MIN_EVENTS_BI

      Minimum events required for biexponential fit (default: 25).

      :type: int

   .. seealso::

      :py:obj:`TimeSeriesAnalysis`
          Contact counts over time


   .. py:attribute:: name
      :value: 'kinetics'


      Analysis name for registry.


   .. py:attribute:: description
      :value: 'Binding kinetics, residence times, and survival curves'


      Human-readable description.


   .. py:attribute:: MIN_EVENTS_MONO
      :value: 5



   .. py:attribute:: MIN_EVENTS_BI
      :value: 25



   .. py:method:: run(query_residue: int, database_residue: Optional[int] = None, database_type: Optional[str] = None, mode: Literal['individual', 'accumulated'] = 'individual', fit_survival: bool = True, max_lag: int = 100) -> prolint.analysis.base.AnalysisResult

      Compute kinetics analysis for a query residue.

      :param query_residue: Query residue ID to analyze.
      :type query_residue: int
      :param database_residue: Specific database residue ID. Required for "individual" mode.
      :type database_residue: int, optional
      :param database_type: Database residue name (e.g., "CHOL"). Required for "accumulated" mode.
      :type database_type: str, optional
      :param mode: Analysis mode:

                   - "individual": Single residue-residue pair kinetics
                   - "accumulated": Aggregated kinetics across all molecules of a type
      :type mode: {"individual", "accumulated"}, default="individual"
      :param fit_survival: Whether to fit exponential models to survival curves.
      :type fit_survival: bool, default=True
      :param max_lag: Maximum lag time for survival curve computation.
      :type max_lag: int, default=100

      :returns: Result with data containing:

                - mode : str analysis mode
                - kinetics : dict with koff, kon, kd, residence_times,
                  occupancy, n_events, n_frames
                - survival_curve : dict with lag_times, survival_probability,
                  mono_fit, bi_fit, selected_model
                - residence_distribution : dict with bins and counts
                - contact_frames : list of frame indices with contacts
      :rtype: AnalysisResult

      :raises ValueError: If database_residue not provided for "individual" mode, or
          database_type not provided for "accumulated" mode.