prolint.core

Core module for ProLint.

Provides the main classes for biomolecular interaction analysis: - Universe: Entry point extending MDAnalysis Universe - ExtendedAtomGroup: Enhanced atom group with additional properties - ContactsProvider: Orchestrates contact computation

Submodules

Classes

Universe

ProLint Universe for biomolecular interaction analysis.

ExtendedAtomGroup

Extended MDAnalysis AtomGroup with additional ProLint functionality.

ContactsProvider

Orchestrates contact computation between atom groups.

Package Contents

class prolint.core.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
property query: prolint.core.groups.ExtendedAtomGroup

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

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')

See also

ComputedContacts

Result object with analysis methods

detect_replicas

Detect replicas in query selection

property units: prolint.config.enums.TimeUnit | str

Current time units for analysis results.

Returns:

Current time unit setting.

Return type:

TimeUnit or str

property normalize_by: prolint.config.enums.NormalizationMethod | str

Current normalization method for contact durations.

Returns:

Current normalization setting.

Return type:

NormalizationMethod or str

class prolint.core.ExtendedAtomGroup(*args: Any, **kwargs: Any)[source]

Bases: MDAnalysis.AtomGroup, PLAtomGroupBase

Extended MDAnalysis AtomGroup with additional ProLint functionality.

Provides enhanced methods for manipulating and querying atom selections, with cached properties for efficient repeated access.

Parameters:

  • *args (tuple) – Arguments passed to MDAnalysis AtomGroup.

  • **kwargs (dict) – Keyword arguments passed to MDAnalysis AtomGroup.

Examples

>>> from prolint import Universe
>>> u = Universe("topology.gro", "trajectory.xtc")
>>> u.database.unique_resnames
array(['POPC', 'POPE', 'CHOL'], dtype='<U4')
>>> u.database.resname_counts
Counter({'POPC': 128, 'POPE': 64, 'CHOL': 32})

Add atoms:

>>> extended = u.database.add(resname="DPPC")

Remove atoms:

>>> filtered = u.database.remove(resname="CHOL")

See also

Universe.query

Query atom group (typically protein)

Universe.database

Database atom group (typically lipids)

add(resname: str | list[str] | None = None, atomname: str | list[str] | None = None, resnum: int | list[int] | None = None, atomids: int | list[int] | None = None) → ExtendedAtomGroup[source]

Add atoms to the atom group.

See PLAtomGroupBase.add() for parameter documentation.

remove(resname: str | list[str] | None = None, atomname: str | list[str] | None = None, resnum: int | list[int] | None = None, atomids: int | list[int] | None = None) → ExtendedAtomGroup[source]

Remove atoms from the atom group.

See PLAtomGroupBase.remove() for parameter documentation.

get_resnames(resids: Iterable[int], out: type[list] | type[dict] = list) → list[str] | Dict[int, str][source]

Get residue names for given residue IDs.

See PLAtomGroupBase.get_resnames() for parameter documentation.

get_resids(resname: str) → numpy.ndarray[source]

Get residue IDs for a given residue name.

See PLAtomGroupBase.get_resids() for parameter documentation.

get_all_resids(resnames: Iterable[str], out: type[list] | type[dict] = list) → list[numpy.ndarray] | Dict[str, numpy.ndarray][source]

Get residue IDs for multiple residue names.

See PLAtomGroupBase.get_all_resids() for parameter documentation.

filter_resids_by_resname(resids: Iterable[int], resname: str) → numpy.ndarray[source]

Filter residue IDs to keep only those matching a residue name.

See PLAtomGroupBase.filter_resids_by_resname() for parameter documentation.

property unique_resnames: numpy.ndarray

Unique residue names in the atom group.

Returns:

Array of unique residue names.

Return type:

ndarray

property resname_counts: collections.Counter

Count of residues for each residue name.

Returns:

Mapping of residue name to count.

Return type:

Counter

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

Orchestrates contact computation between atom groups.

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

Parameters:

  • query (ExtendedAtomGroup) – Query atoms (e.g., protein).

  • database (ExtendedAtomGroup) – Database atoms (e.g., lipids).

  • params (dict, optional) – Computation parameters including units and normalization.

  • compute_strategy ({"default"}, default="default") – Contact computation strategy to use.

See also

Universe.compute_contacts

High-level interface using this provider

ComputedContacts

Result container returned by compute()

query
database
params
compute(strategy_or_computer=None, start=None, stop=None, step=1, **kwargs)[source]

Compute contacts between query and database.

Parameters:

  • strategy_or_computer (str, optional) – Computation strategy name. Default: “default”.

  • start (int, optional) – First frame to process.

  • stop (int, optional) – Last frame to process (exclusive).

  • step (int, default=1) – Frame step size.

  • **kwargs (dict) – Additional arguments passed to contact computer (e.g., cutoff).

Returns:

Container with contact data and analysis methods.

Return type:

ComputedContacts

Raises:

ValueError – If strategy_or_computer is not recognized.