prolint ======= .. py:module:: prolint Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/prolint/analysis/index /autoapi/prolint/computers/index /autoapi/prolint/config/index /autoapi/prolint/contacts/index /autoapi/prolint/core/index /autoapi/prolint/plotting/index /autoapi/prolint/utils/index Classes ------- .. autoapisummary:: prolint.Universe Functions --------- .. autoapisummary:: prolint.setup_logging prolint.get_logger 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:function:: setup_logging(level: int = logging.INFO, format_string: Optional[str] = None, simple: bool = False) -> logging.Logger Configure logging for ProLint. :param level: Logging level (e.g., logging.DEBUG, logging.INFO). :type level: int, default=logging.INFO :param format_string: Custom format string for log messages. :type format_string: str, optional :param simple: If True, use simplified format without timestamps. :type simple: bool, default=False :returns: Configured ProLint logger instance. :rtype: logging.Logger .. py:function:: get_logger(name: str) -> logging.Logger Get a child logger for a ProLint module. :param name: Module name (will be prefixed with "prolint."). :type name: str :returns: Logger instance for the specified module. :rtype: logging.Logger