prolint.analysis.distances
==========================

.. py:module:: prolint.analysis.distances

.. autoapi-nested-parse::

   Distance analysis for residue pair interactions.



Classes
-------

.. autoapisummary::

   prolint.analysis.distances.AtomDistancesAnalysis
   prolint.analysis.distances.DistanceAnalysis


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

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

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


   Compute atom-atom distance matrix at a specific frame.

   Provides detailed per-atom distance information between two residues
   at a single trajectory frame.

   .. seealso::

      :py:obj:`DistanceAnalysis`
          Distance time series over multiple frames


   .. py:attribute:: name
      :value: 'atom_distances'


      Analysis name for registry.


   .. py:attribute:: description
      :value: 'Atom-atom distance matrix at a specific frame'


      Human-readable description.


   .. py:method:: run(query_residue: int, database_residue: int, frame_idx: int) -> prolint.analysis.base.AnalysisResult

      Compute atom-atom distance matrix between two residues.

      :param query_residue: Query residue ID.
      :type query_residue: int
      :param database_residue: Database residue ID.
      :type database_residue: int
      :param frame_idx: Frame index to analyze. Clamped to valid range.
      :type frame_idx: int

      :returns: Result with data containing:

                - frame : int frame index
                - query_atoms : list of str atom names
                - database_atoms : list of str atom names
                - distance_matrix : 2D list of float distances
                - min_distance, max_distance : float extrema
      :rtype: AnalysisResult

      :raises ValueError: If query or database residue not found in universe.



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

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


   Analyze distances between query and database residues over time.

   Computes center-of-mass distances and optionally minimum atom-atom
   distances between a query-database residue pair across trajectory frames.

   .. seealso::

      :py:obj:`AtomDistancesAnalysis`
          Full distance matrix at single frame


   .. py:attribute:: name
      :value: 'distances'


      Analysis name for registry.


   .. py:attribute:: description
      :value: 'Distance computations between residue pairs'


      Human-readable description.


   .. py:method:: run(query_residue: int, database_residue: int, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1, compute_min_distances: bool = True, compute_positions: bool = True) -> prolint.analysis.base.AnalysisResult

      Compute distance time series between a residue pair.

      :param query_residue: Query residue ID.
      :type query_residue: int
      :param database_residue: Database residue ID.
      :type database_residue: int
      :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 compute_min_distances: Whether to compute minimum atom-atom distances.
      :type compute_min_distances: bool, default=True
      :param compute_positions: Whether to compute 2D positions relative to query COM.
      :type compute_positions: bool, default=True

      :returns: Result with data containing:

                - frames : list of int frame indices
                - distances : list of float center-of-mass distances
                - contact_frames : list of int frames where contact occurred
                - min_distances : list of float (if compute_min_distances)
                - positions : dict with query/database 2D positions (if compute_positions)
      :rtype: AnalysisResult

      :raises ValueError: If query or database residue not found in universe.