prolint.contacts¶

Contact storage and aggregation strategies.

This module provides classes for storing contact data and computing duration-based metrics from contact frame indices.

Submodules¶

Classes¶

`BaseContactStore`	Abstract base class for contact storage strategies.
`ExactContacts`	Exact contact storage with duration-based metric computation.

Package Contents¶

class prolint.contacts.BaseContactStore(ts, contact_frames, norm_factor: float = 1.0)[source]¶

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.

Parameters:

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

See also

ExactContacts: Concrete implementation for exact contact aggregation

norm_factor¶

contact_frames¶

abstractmethod run(database_resnames: str | List = None)[source]¶

Process contact frames into aggregated contact data.

Parameters:: database_resnames (str or list of str, optional) – Residue names to process. If None, processes all.
Raises:: NotImplementedError – Subclasses must implement this method.

compute(metric: str, target_resname=None)[source]¶

Compute a standard metric on contacts.

Parameters:

metric ({"max", "sum", "mean", "occupancy"}) – Metric to compute.
target_resname (str, optional) – Filter by residue name.

Returns:

Computed metric values.

Return type:

dict

Raises:

ValueError – If metric is not recognized.

abstractmethod compute_metric(metric: str, target_resname=None)[source]¶

Compute a specific metric. Implemented by subclasses.

Parameters:

metric (str) – Metric to compute.
target_resname (str, optional) – Filter by residue name.

Raises:

NotImplementedError – Subclasses must implement this method.

abstractmethod apply_function(func: Callable, target_resname=None)[source]¶

Apply a custom function to contact data.

Parameters:

func (callable) – Function to apply to contact durations.
target_resname (str, optional) – Filter by residue name.

Raises:

NotImplementedError – Subclasses must implement this method.

property contacts¶

Processed contact data.

Returns:: Contact data organized by residue and database molecule.
Return type:: dict
Raises:: ValueError – If run() has not been called yet.

class prolint.contacts.ExactContacts(ts, contact_frames, norm_factor: float = 1.0)[source]¶

Bases: 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).

Parameters:

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

contacts¶

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

Type:: dict

contact_frames¶

Raw frame indices where contacts occur.

Type:: dict

Examples

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

See also

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

run(database_resnames: str | List = None) → None[source]¶

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.

Parameters:: database_resnames (str or list of str, optional) – Residue names to process. If None, processes all unique residue names in the database.

compute_metric(metric: str, target_resname=None)[source]¶

Compute a metric across all contacts.

Parameters:

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

Returns:

Nested dict with structure: {residue_id: {database_name: {“global”: value, “per_id”: {id: value}}}}

Return type:

dict

apply_function(func: Callable, target_resname=None)[source]¶

Apply a custom function to contact duration arrays.

Parameters:

func (callable) – Function that takes an array of durations and returns a value.
target_resname (str, optional) – Filter by database residue name.

Returns:

Function results organized by residue and database ID.

Return type:

dict

Examples

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

compute_database_durations(contact_frame: Dict[int, List[int]], database_resname: str) → Dict[int, numpy.ndarray][source]¶

Compute contact durations for a specific database residue type.

Parameters:

contact_frame (dict) – Mapping of database_id -> list of frame indices.
database_resname (str) – Residue name to filter by.

Returns:

Mapping of database_id -> array of contact durations.

Return type:

dict