prolint.contacts ================ .. py:module:: prolint.contacts .. autoapi-nested-parse:: Contact storage and aggregation strategies. This module provides classes for storing contact data and computing duration-based metrics from contact frame indices. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/prolint/contacts/base/index /autoapi/prolint/contacts/exact_contacts/index Classes ------- .. autoapisummary:: prolint.contacts.BaseContactStore prolint.contacts.ExactContacts Package Contents ---------------- .. py:class:: BaseContactStore(ts, contact_frames, norm_factor: float = 1.0) Abstract base class for contact storage strategies. Defines the interface for storing and computing metrics on contact data. Subclasses implement specific storage and aggregation strategies. :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 .. seealso:: :py:obj:`ExactContacts` Concrete implementation for exact contact aggregation .. py:attribute:: norm_factor .. py:attribute:: contact_frames .. py:method:: run(database_resnames: Union[str, List] = None) :abstractmethod: Process contact frames into aggregated contact data. :param database_resnames: Residue names to process. If None, processes all. :type database_resnames: str or list of str, optional :raises NotImplementedError: Subclasses must implement this method. .. py:method:: compute(metric: str, target_resname=None) Compute a standard metric on contacts. :param metric: Metric to compute. :type metric: {"max", "sum", "mean", "occupancy"} :param target_resname: Filter by residue name. :type target_resname: str, optional :returns: Computed metric values. :rtype: dict :raises ValueError: If metric is not recognized. .. py:method:: compute_metric(metric: str, target_resname=None) :abstractmethod: Compute a specific metric. Implemented by subclasses. :param metric: Metric to compute. :type metric: str :param target_resname: Filter by residue name. :type target_resname: str, optional :raises NotImplementedError: Subclasses must implement this method. .. py:method:: apply_function(func: Callable, target_resname=None) :abstractmethod: 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 :raises NotImplementedError: Subclasses must implement this method. .. py:property:: contacts Processed contact data. :returns: Contact data organized by residue and database molecule. :rtype: dict :raises ValueError: If run() has not been called yet. .. 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