prolint.core.universe ===================== .. py:module:: prolint.core.universe .. autoapi-nested-parse:: ProLint Universe module. This module provides the main entry point for ProLint, extending MDAnalysis Universe with biomolecular interaction analysis capabilities. Attributes ---------- .. autoapisummary:: prolint.core.universe.logger prolint.core.universe.TimeUnitLiteral prolint.core.universe.NormalizationLiteral prolint.core.universe.VALID_UNITS Classes ------- .. autoapisummary:: prolint.core.universe.Universe Module Contents --------------- .. py:data:: logger .. py:data:: TimeUnitLiteral .. py:data:: NormalizationLiteral .. py:data:: VALID_UNITS .. 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