prolint.contacts.exact_contacts
===============================

.. py:module:: prolint.contacts.exact_contacts

.. autoapi-nested-parse::

   Exact contact storage and aggregation.

   This module provides the ExactContacts class for storing contacts
   with exact frame-level information and computing duration-based metrics.



Attributes
----------

.. autoapisummary::

   prolint.contacts.exact_contacts.logger


Classes
-------

.. autoapisummary::

   prolint.contacts.exact_contacts.ExactContacts


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

.. py:data:: logger

.. py:class:: ExactContacts(ts, contact_frames, norm_factor: float = 1.0)

   Bases: :py:obj:`prolint.contacts.base.BaseContactStore`


   Exact contact storage with duration-based metric computation.

   Stores contacts at frame-level precision and computes metrics
   based on contiguous contact durations (binding events).

   :param ts: MDAnalysis Universe instance.
   :type ts: Universe
   :param contact_frames: Nested dict mapping residue_id -> database_id -> list of frame indices.
   :type contact_frames: dict
   :param norm_factor: Normalization factor for duration calculations.
   :type norm_factor: float, default=1.0

   .. attribute:: contacts

      Contact durations organized by residue, database type, and molecule ID.

      :type: dict

   .. attribute:: contact_frames

      Raw frame indices where contacts occur.

      :type: dict

   .. rubric:: Examples

   >>> contacts = universe.compute_contacts(cutoff=7.0)
   >>> occupancy = contacts.compute_metric("occupancy", target_resname="CHOL")
   >>> mean_duration = contacts.compute_metric("mean")

   .. seealso::

      :py:obj:`BaseContactStore`
          Abstract base class
      
      :py:obj:`ComputedContacts`
          High-level wrapper for contact results


   .. py:method:: run(database_resnames: Union[str, List] = None) -> None

      Aggregate contact frames into contact durations.

      Processes raw contact frame indices into contiguous binding events
      (durations) for each residue-molecule pair. Results are stored in
      the ``contacts`` attribute.

      :param database_resnames: Residue names to process. If None, processes all unique
                                residue names in the database.
      :type database_resnames: str or list of str, optional



   .. py:method:: compute_metric(metric: str, target_resname=None)

      Compute a metric across all contacts.

      :param metric: Metric to compute:
                     - "occupancy": Fraction of frames with contact
                     - "mean": Mean contact duration
                     - "max": Maximum contact duration
                     - "sum": Total contact duration
      :type metric: {"max", "sum", "mean", "occupancy"}
      :param target_resname: Filter by database residue name (e.g., "CHOL").
      :type target_resname: str, optional

      :returns: Nested dict with structure:
                {residue_id: {database_name: {"global": value, "per_id": {id: value}}}}
      :rtype: dict



   .. py:method:: apply_function(func: Callable, target_resname=None)

      Apply a custom function to contact duration arrays.

      :param func: Function that takes an array of durations and returns a value.
      :type func: callable
      :param target_resname: Filter by database residue name.
      :type target_resname: str, optional

      :returns: Function results organized by residue and database ID.
      :rtype: dict

      .. rubric:: Examples

      >>> # Custom metric: number of binding events
      >>> n_events = contacts.apply_function(len, target_resname="CHOL")



   .. py:method:: compute_database_durations(contact_frame: Dict[int, List[int]], database_resname: str) -> Dict[int, numpy.ndarray]

      Compute contact durations for a specific database residue type.

      :param contact_frame: Mapping of database_id -> list of frame indices.
      :type contact_frame: dict
      :param database_resname: Residue name to filter by.
      :type database_resname: str

      :returns: Mapping of database_id -> array of contact durations.
      :rtype: dict