prolint.core ============ .. py:module:: prolint.core .. autoapi-nested-parse:: 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 ---------- .. toctree:: :maxdepth: 1 /autoapi/prolint/core/contact_provider/index /autoapi/prolint/core/groups/index /autoapi/prolint/core/replica_detection/index /autoapi/prolint/core/universe/index Classes ------- .. autoapisummary:: prolint.core.Universe prolint.core.ExtendedAtomGroup prolint.core.ContactsProvider Package Contents ---------------- .. py:class:: Universe(*args: Any, universe: Optional[MDAnalysis.Universe] = None, query: Optional[MDAnalysis.AtomGroup] = None, database: Optional[MDAnalysis.AtomGroup] = None, normalize_by: Union[prolint.config.enums.NormalizationMethod, NormalizationLiteral] = 'counts', units: Union[prolint.config.enums.TimeUnit, TimeUnitLiteral] = 'us', **kwargs: Any) Bases: :py:obj:`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). :param \*args: Positional arguments passed to MDAnalysis Universe (topology, trajectory). :type \*args: tuple :param universe: Existing MDAnalysis Universe to wrap. If provided, topology and trajectory are extracted from this universe. :type universe: mda.Universe, optional :param query: Atoms to analyze (e.g., protein). Default: ``"protein"`` selection. :type query: mda.AtomGroup, optional :param database: Reference atoms for contact detection (e.g., lipids). Default: ``"not protein"`` selection. :type database: mda.AtomGroup, optional :param normalize_by: Normalization method for contact durations. - ``"counts"``: Duration in frame counts - ``"actual_time"``: Duration in time units :type normalize_by: {"counts", "actual_time"}, default="counts" :param units: Time units for analysis results. :type units: {"fs", "ps", "ns", "us", "ms", "s"}, default="us" :param \*\*kwargs: Additional keyword arguments passed to MDAnalysis Universe. :type \*\*kwargs: dict .. rubric:: 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") .. seealso:: :py:obj:`ComputedContacts` Result object from compute_contacts :py:obj:`ExtendedAtomGroup` Enhanced atom group with additional properties .. py:attribute:: params .. py:property:: query :type: prolint.core.groups.ExtendedAtomGroup Query atom group for analysis. :returns: The query atoms (typically protein). :rtype: ExtendedAtomGroup .. py:method:: update_query(new_query: MDAnalysis.AtomGroup) -> None Update query atom group. :param new_query: New query atom selection. :type new_query: mda.AtomGroup .. py:property:: database :type: prolint.core.groups.ExtendedAtomGroup Database atom group for contact detection. :returns: The database atoms (typically lipids or ligands). :rtype: ExtendedAtomGroup .. py:method:: update_database(new_database: MDAnalysis.AtomGroup) -> None Update database atom group. :param new_database: New database atom selection. :type new_database: mda.AtomGroup .. py:method:: compute_contacts(*args: Any, replica: Optional[str] = None, **kwargs: Any) -> Any 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. :param cutoff: Distance cutoff in Angstroms for contact detection. :type cutoff: float, default=7.0 :param start: First frame to process. Default: first frame. :type start: int, optional :param stop: Last frame to process (exclusive). Default: last frame. :type stop: int, optional :param step: Frame step size. :type step: int, default=1 :param replica: 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. :type replica: str, optional :param \*\*kwargs: Additional keyword arguments passed to ContactsProvider. :type \*\*kwargs: dict :returns: Object containing contact data and analysis methods. :rtype: ComputedContacts :raises ValueError: If multiple replicas with repeated residue IDs are detected and ``replica`` is not specified. .. rubric:: 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') .. seealso:: :py:obj:`ComputedContacts` Result object with analysis methods :py:obj:`detect_replicas` Detect replicas in query selection .. py:property:: units :type: Union[prolint.config.enums.TimeUnit, str] Current time units for analysis results. :returns: Current time unit setting. :rtype: TimeUnit or str .. py:property:: normalize_by :type: Union[prolint.config.enums.NormalizationMethod, str] Current normalization method for contact durations. :returns: Current normalization setting. :rtype: NormalizationMethod or str .. py:class:: ExtendedAtomGroup(*args: Any, **kwargs: Any) Bases: :py:obj:`MDAnalysis.AtomGroup`, :py:obj:`PLAtomGroupBase` Extended MDAnalysis AtomGroup with additional ProLint functionality. Provides enhanced methods for manipulating and querying atom selections, with cached properties for efficient repeated access. :param \*args: Arguments passed to MDAnalysis AtomGroup. :type \*args: tuple :param \*\*kwargs: Keyword arguments passed to MDAnalysis AtomGroup. :type \*\*kwargs: dict .. rubric:: Examples >>> from prolint import Universe >>> u = Universe("topology.gro", "trajectory.xtc") >>> u.database.unique_resnames array(['POPC', 'POPE', 'CHOL'], dtype='>> 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") .. seealso:: :py:obj:`Universe.query` Query atom group (typically protein) :py:obj:`Universe.database` Database atom group (typically lipids) .. py:method:: add(resname: Optional[Union[str, list[str]]] = None, atomname: Optional[Union[str, list[str]]] = None, resnum: Optional[Union[int, list[int]]] = None, atomids: Optional[Union[int, list[int]]] = None) -> ExtendedAtomGroup Add atoms to the atom group. See :meth:`PLAtomGroupBase.add` for parameter documentation. .. py:method:: remove(resname: Optional[Union[str, list[str]]] = None, atomname: Optional[Union[str, list[str]]] = None, resnum: Optional[Union[int, list[int]]] = None, atomids: Optional[Union[int, list[int]]] = None) -> ExtendedAtomGroup Remove atoms from the atom group. See :meth:`PLAtomGroupBase.remove` for parameter documentation. .. py:method:: get_resnames(resids: Iterable[int], out: Union[type[list], type[dict]] = list) -> Union[list[str], Dict[int, str]] Get residue names for given residue IDs. See :meth:`PLAtomGroupBase.get_resnames` for parameter documentation. .. py:method:: get_resids(resname: str) -> numpy.ndarray Get residue IDs for a given residue name. See :meth:`PLAtomGroupBase.get_resids` for parameter documentation. .. py:method:: get_all_resids(resnames: Iterable[str], out: Union[type[list], type[dict]] = list) -> Union[list[numpy.ndarray], Dict[str, numpy.ndarray]] Get residue IDs for multiple residue names. See :meth:`PLAtomGroupBase.get_all_resids` for parameter documentation. .. py:method:: filter_resids_by_resname(resids: Iterable[int], resname: str) -> numpy.ndarray Filter residue IDs to keep only those matching a residue name. See :meth:`PLAtomGroupBase.filter_resids_by_resname` for parameter documentation. .. py:property:: unique_resnames :type: numpy.ndarray Unique residue names in the atom group. :returns: Array of unique residue names. :rtype: ndarray .. py:property:: resname_counts :type: collections.Counter Count of residues for each residue name. :returns: Mapping of residue name to count. :rtype: Counter .. 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.