prolint.analysis.timeseries
===========================

.. py:module:: prolint.analysis.timeseries

.. autoapi-nested-parse::

   Time series analysis for contact dynamics over trajectory.



Attributes
----------

.. autoapisummary::

   prolint.analysis.timeseries.logger


Classes
-------

.. autoapisummary::

   prolint.analysis.timeseries.DatabaseContactsAnalysis
   prolint.analysis.timeseries.TimeSeriesAnalysis


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

.. py:data:: logger

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

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


   Compute per-database-molecule contact timeline for a query residue.

   Creates a binary contact matrix showing which database molecules are
   in contact with a specific query residue at each frame.

   .. seealso::

      :py:obj:`TimeSeriesAnalysis`
          Aggregated contact counts over time


   .. py:attribute:: name
      :value: 'database_contacts'


      Analysis name for registry.


   .. py:attribute:: description
      :value: 'Per-database-molecule contact timeline'


      Human-readable description.


   .. py:method:: run(query_residue: int, database_type: Optional[str] = None, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1, top_n: Optional[int] = None) -> prolint.analysis.base.AnalysisResult

      Compute binary contact matrix for a query residue.

      :param query_residue: Query residue ID to analyze.
      :type query_residue: int
      :param database_type: Filter by database residue name (e.g., "CHOL").
      :type database_type: str, optional
      :param frame_start: First frame to process.
      :type frame_start: int, default=0
      :param frame_end: Last frame (exclusive). Defaults to total frames.
      :type frame_end: int, optional
      :param frame_step: Step between frames.
      :type frame_step: int, default=1
      :param top_n: If specified, return only the top N database IDs with the most
                    contacts. Useful for reducing response size when many database
                    molecules have minimal contacts.
      :type top_n: int, optional

      :returns: Result with data containing:

                - database_ids : list of int sorted database molecule IDs
                - frames : list of int frame indices
                - contact_matrix : dict mapping database_id to list of int (0 or 1)
      :rtype: AnalysisResult



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

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


   Analyze contact dynamics over trajectory time.

   Computes per-frame contact counts for query residues, useful for
   understanding how contact behavior varies throughout the simulation.

   .. seealso::

      :py:obj:`DatabaseContactsAnalysis`
          Per-molecule binary contact timeline
      
      :py:obj:`KineticsAnalysis`
          Binding kinetics and residence times


   .. py:attribute:: name
      :value: 'timeseries'


      Analysis name for registry.


   .. py:attribute:: description
      :value: 'Contact counts over trajectory time'


      Human-readable description.


   .. py:method:: run(database_type: Optional[str] = None, query_residues: Optional[List[int]] = None, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1) -> prolint.analysis.base.AnalysisResult

      Compute contact count time series.

      :param database_type: Filter by database residue name (e.g., "CHOL").
      :type database_type: str, optional
      :param query_residues: Specific query residues to include. If None, includes all
                             residues with contacts.
      :type query_residues: list of int, optional
      :param frame_start: First frame to process.
      :type frame_start: int, default=0
      :param frame_end: Last frame (exclusive). Defaults to total frames.
      :type frame_end: int, optional
      :param frame_step: Step between frames.
      :type frame_step: int, default=1

      :returns: Result with data containing:

                - query_residues : list of int query residue IDs
                - frames : list of int frame indices
                - contact_counts : dict mapping residue_id to list of counts
      :rtype: AnalysisResult