prolint.core.contact_provider
=============================

.. py:module:: prolint.core.contact_provider

.. autoapi-nested-parse::

   Contact provider module.

   This module provides classes for computing and managing contact data
   between molecular groups.



Attributes
----------

.. autoapisummary::

   prolint.core.contact_provider.logger


Classes
-------

.. autoapisummary::

   prolint.core.contact_provider.ComputedContacts
   prolint.core.contact_provider.ContactsProvider


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

.. py:data:: logger

.. py:class:: ComputedContacts(contact_strategy_instance: prolint.contacts.base.BaseContactStore, provider: ContactsProvider)

   Container for computed contact data with analysis methods.

   This class wraps contact computation results and provides methods
   for analyzing contacts, computing metrics, and performing set operations.

   :param contact_strategy_instance: Contact storage instance containing computed contacts.
   :type contact_strategy_instance: BaseContactStore
   :param provider: The provider that created this instance.
   :type provider: ContactsProvider

   .. rubric:: Examples

   >>> contacts = universe.compute_contacts(cutoff=7.0)
   >>> result = contacts.analyze("timeseries", database_type="CHOL")

   Compute metrics:

   >>> occupancy = contacts.compute_metric("occupancy", target_resname="CHOL")

   Set operations:

   >>> common = contacts1 + contacts2  # Intersection
   >>> unique = contacts1 - contacts2  # Difference

   .. seealso::

      :py:obj:`Universe.compute_contacts`
          Method that creates ComputedContacts
      
      :py:obj:`AnalysisRegistry`
          Registry of available analysis types


   .. py:attribute:: provider


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

      Compute a metric for contacts.

      :param metric: Metric to compute. Options: "occupancy", "mean", "max", "sum".
      :type metric: str
      :param target_resname: Filter by residue name (e.g., "CHOL", "POPC").
      :type target_resname: str, optional

      :returns: Metric values organized by residue ID.
      :rtype: dict

      .. rubric:: Examples

      >>> occupancy = contacts.compute_metric("occupancy", target_resname="CHOL")
      >>> mean_duration = contacts.compute_metric("mean")



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

      Apply a custom function to contact data.

      :param func: Function to apply to contact durations.
      :type func: callable
      :param target_resname: Filter by residue name.
      :type target_resname: str, optional

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



   .. py:property:: contacts

      Raw contact data.

      :returns: Contact data organized by residue and database molecule.
      :rtype: dict


   .. py:property:: contact_frames

      Frame indices where contacts occur.

      :returns: Nested dict mapping residue_id -> database_id -> list of frame indices.
      :rtype: dict


   .. py:property:: norm_factor
      :type: float


      Normalization factor for duration calculations.

      :returns: Factor used to normalize contact durations.
      :rtype: float


   .. py:method:: intersection(other: ComputedContacts) -> ComputedContacts

      Find contacts common to both ComputedContacts objects.

      :param other: Another computed contacts object.
      :type other: ComputedContacts

      :returns: New object containing only contacts present in both.
      :rtype: ComputedContacts

      .. rubric:: Examples

      >>> common = contacts1.intersection(contacts2)
      >>> # Or using operator
      >>> common = contacts1 + contacts2



   .. py:method:: difference(other: ComputedContacts) -> ComputedContacts

      Find contacts in self but not in other.

      :param other: Another computed contacts object.
      :type other: ComputedContacts

      :returns: New object containing contacts unique to self.
      :rtype: ComputedContacts

      .. rubric:: Examples

      >>> unique = contacts1.difference(contacts2)
      >>> # Or using operator
      >>> unique = contacts1 - contacts2



   .. py:method:: analyze(analysis_type: str, **kwargs) -> prolint.analysis.base.AnalysisResult

      Run an analysis on computed contacts.

      :param analysis_type: Type of analysis to run. Options:
                            - "timeseries": Contact counts over time
                            - "database_contacts": Per-molecule contact timeline
                            - "kinetics": Binding kinetics and residence times
                            - "density_map": 2D spatial density
                            - "radial_density": Radial density profile
                            - "shared_contacts": Residue contact correlations
                            - "distances": Distance distributions
                            - "atom_distances": Atom-level distances
                            - "metrics": Per-residue metrics
      :type analysis_type: str
      :param \*\*kwargs: Analysis-specific parameters.
      :type \*\*kwargs: dict

      :returns: Result object containing analysis data.
      :rtype: AnalysisResult

      .. rubric:: Examples

      >>> result = contacts.analyze("timeseries", database_type="CHOL")
      >>> result = contacts.analyze("kinetics", query_residue=42, mode="accumulated")
      >>> result = contacts.analyze("metrics", metric="occupancy")

      .. seealso::

         :py:obj:`AnalysisRegistry`
             Registry of available analysis types



.. py:class:: ContactsProvider(query, database, params=None, compute_strategy: Literal['default'] = 'default')

   Orchestrates contact computation between atom groups.

   This class manages the contact detection process, coordinating
   between different computation strategies and contact storage methods.

   :param query: Query atoms (e.g., protein).
   :type query: ExtendedAtomGroup
   :param database: Database atoms (e.g., lipids).
   :type database: ExtendedAtomGroup
   :param params: Computation parameters including units and normalization.
   :type params: dict, optional
   :param compute_strategy: Contact computation strategy to use.
   :type compute_strategy: {"default"}, default="default"

   .. seealso::

      :py:obj:`Universe.compute_contacts`
          High-level interface using this provider
      
      :py:obj:`ComputedContacts`
          Result container returned by compute()


   .. py:attribute:: query


   .. py:attribute:: database


   .. py:attribute:: params


   .. py:method:: compute(strategy_or_computer=None, start=None, stop=None, step=1, **kwargs)

      Compute contacts between query and database.

      :param strategy_or_computer: Computation strategy name. Default: "default".
      :type strategy_or_computer: str, optional
      :param start: First frame to process.
      :type start: int, optional
      :param stop: Last frame to process (exclusive).
      :type stop: int, optional
      :param step: Frame step size.
      :type step: int, default=1
      :param \*\*kwargs: Additional arguments passed to contact computer (e.g., cutoff).
      :type \*\*kwargs: dict

      :returns: Container with contact data and analysis methods.
      :rtype: ComputedContacts

      :raises ValueError: If strategy_or_computer is not recognized.