prolint.core.universe¶

ProLint Universe module.

This module provides the main entry point for ProLint, extending MDAnalysis Universe with biomolecular interaction analysis capabilities.

Attributes¶

`logger`
`TimeUnitLiteral`
`NormalizationLiteral`
`VALID_UNITS`

Classes¶

Universe

ProLint Universe for biomolecular interaction analysis.

Module Contents¶

prolint.core.universe.logger[source]¶

prolint.core.universe.TimeUnitLiteral[source]¶

prolint.core.universe.NormalizationLiteral[source]¶

prolint.core.universe.VALID_UNITS[source]¶

class prolint.core.universe.Universe(*args: Any, universe: MDAnalysis.Universe | None = None, query: MDAnalysis.AtomGroup | None = None, database: MDAnalysis.AtomGroup | None = None, normalize_by: prolint.config.enums.NormalizationMethod | NormalizationLiteral = 'counts', units: prolint.config.enums.TimeUnit | TimeUnitLiteral = 'us', **kwargs: Any)[source]¶

Bases: MDAnalysis.Universe

ProLint Universe for biomolecular interaction analysis.

Extends MDAnalysis Universe with specialized methods for computing and analyzing contacts between molecular groups (e.g., protein-lipid, protein-ligand interactions).

Parameters:

*args (tuple) – Positional arguments passed to MDAnalysis Universe (topology, trajectory).
universe (mda.Universe, optional) – Existing MDAnalysis Universe to wrap. If provided, topology and trajectory are extracted from this universe.
query (mda.AtomGroup, optional) – Atoms to analyze (e.g., protein). Default: "protein" selection.
database (mda.AtomGroup, optional) – Reference atoms for contact detection (e.g., lipids). Default: "not protein" selection.
normalize_by ({"counts", "actual_time"}, default="counts") – Normalization method for contact durations. - "counts": Duration in frame counts - "actual_time": Duration in time units
units ({"fs", "ps", "ns", "us", "ms", "s"}, default="us") – Time units for analysis results.
**kwargs (dict) – Additional keyword arguments passed to MDAnalysis Universe.

Examples

Basic usage with topology and trajectory files:

>>> from prolint import Universe
>>> u = Universe("topology.gro", "trajectory.xtc")
>>> print(f"Loaded {u.trajectory.n_frames} frames")

From an existing MDAnalysis Universe:

>>> import MDAnalysis as mda
>>> mda_u = mda.Universe("topology.gro", "trajectory.xtc")
>>> u = Universe(universe=mda_u)

With custom selections:

>>> u = Universe("topology.gro", "trajectory.xtc")
>>> u.query = u.select_atoms("protein and name CA")
>>> u.database = u.select_atoms("resname POPC POPE CHOL")

Compute contacts:

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

See also

ComputedContacts: Result object from compute_contacts
ExtendedAtomGroup: Enhanced atom group with additional properties

params[source]¶

property query: prolint.core.groups.ExtendedAtomGroup[source]¶

Query atom group for analysis.

Returns:: The query atoms (typically protein).
Return type:: ExtendedAtomGroup

update_query(new_query: MDAnalysis.AtomGroup) → None[source]¶

Update query atom group.

Parameters:: new_query (mda.AtomGroup) – New query atom selection.

property database: prolint.core.groups.ExtendedAtomGroup[source]¶

Database atom group for contact detection.

Returns:: The database atoms (typically lipids or ligands).
Return type:: ExtendedAtomGroup

update_database(new_database: MDAnalysis.AtomGroup) → None[source]¶

Update database atom group.

Parameters:: new_database (mda.AtomGroup) – New database atom selection.

compute_contacts(*args: Any, replica: str | None = None, **kwargs: Any) → Any[source]¶

Compute contacts between query and database atom groups.

Detects distance-based contacts between query (e.g., protein) and database (e.g., lipids) atoms across the trajectory.

Parameters:

cutoff (float, default=7.0) – Distance cutoff in Angstroms for contact detection.
start (int, optional) – First frame to process. Default: first frame.
stop (int, optional) – Last frame to process (exclusive). Default: last frame.
step (int, default=1) – Frame step size.
replica (str, optional) – Replica ID to analyze (e.g., ‘A’, ‘B’). Required when multiple replicas with repeated residue IDs are detected. Use detect_replicas() to see available replicas.
**kwargs (dict) – Additional keyword arguments passed to ContactsProvider.

Returns:

Object containing contact data and analysis methods.

Return type:

ComputedContacts

Raises:

ValueError – If multiple replicas with repeated residue IDs are detected and replica is not specified.

Examples

Compute contacts for a single-replica system:

>>> contacts = universe.compute_contacts(cutoff=7.0)

For multi-replica systems, first detect replicas:

>>> from prolint.core.replica_detection import detect_replicas
>>> result = detect_replicas(universe.query)
>>> print(f"Found {result.n_replicas} replicas")
>>> for info in result.replica_info:
...     print(f"  Replica {info.replica_id}: {info.n_residues} residues")

Then select a specific replica for analysis:

>>> contacts = universe.compute_contacts(cutoff=7.0, replica='A')