prolint.analysis ================ .. py:module:: prolint.analysis .. autoapi-nested-parse:: Analysis module for ProLint. Provides analysis classes for extracting insights from contact data: - TimeSeriesAnalysis: Contact counts over trajectory time - DatabaseContactsAnalysis: Per-molecule contact timelines - KineticsAnalysis: Binding kinetics and residence times - DensityMapAnalysis: 2D spatial density maps - RadialDensityAnalysis: Radial density profiles - DistanceAnalysis: Distance time series between residue pairs - AtomDistancesAnalysis: Atom-atom distance matrices - SharedContactsAnalysis: Pairwise residue correlations - MetricsAnalysis: Per-residue contact metrics All analyses are registered with AnalysisRegistry and can be accessed via ComputedContacts.analyze() or directly instantiated. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/prolint/analysis/base/index /autoapi/prolint/analysis/density/index /autoapi/prolint/analysis/distances/index /autoapi/prolint/analysis/kinetics/index /autoapi/prolint/analysis/metrics/index /autoapi/prolint/analysis/shared_contacts/index /autoapi/prolint/analysis/timeseries/index Classes ------- .. autoapisummary:: prolint.analysis.BaseAnalysis prolint.analysis.AnalysisRegistry prolint.analysis.AnalysisResult prolint.analysis.DensityMapAnalysis prolint.analysis.RadialDensityAnalysis prolint.analysis.SharedContactsAnalysis prolint.analysis.TimeSeriesAnalysis prolint.analysis.DatabaseContactsAnalysis prolint.analysis.KineticsAnalysis prolint.analysis.DistanceAnalysis prolint.analysis.AtomDistancesAnalysis prolint.analysis.MetricsAnalysis Package Contents ---------------- .. py:class:: BaseAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`abc.ABC` Abstract base class for all ProLint analyses. Provides common functionality for filtering contacts, building residue mappings, and generating frame ranges. :param universe: ProLint Universe instance. :type universe: Universe :param contacts: Computed contact data to analyze. :type contacts: ComputedContacts .. seealso:: :py:obj:`AnalysisRegistry` Registry for creating analyses by name :py:obj:`ComputedContacts.analyze` High-level interface to run analyses .. py:attribute:: name :type: str :value: 'base_analysis' Analysis name for registry. .. py:attribute:: description :type: str :value: 'Base analysis class' Human-readable description. .. py:attribute:: universe .. py:attribute:: contacts .. py:method:: run(**kwargs) -> AnalysisResult :abstractmethod: Run the analysis and return results. :param \*\*kwargs: Analysis-specific parameters. :type \*\*kwargs: dict :returns: Container with analysis data and metadata. :rtype: AnalysisResult .. py:class:: AnalysisRegistry Registry for analysis types. Manages registration and creation of analysis classes. All built-in analyses are registered automatically on import. .. rubric:: Examples List available analyses: >>> from prolint.analysis import AnalysisRegistry >>> AnalysisRegistry.available() ['timeseries', 'database_contacts', 'kinetics', ...] Create an analysis: >>> analysis = AnalysisRegistry.create("timeseries", universe, contacts) >>> result = analysis.run(database_type="CHOL") .. py:method:: register(name: str, analysis_class: Type[BaseAnalysis]) :classmethod: Register an analysis class. :param name: Name to register under. :type name: str :param analysis_class: Analysis class (must inherit from BaseAnalysis). :type analysis_class: type .. py:method:: create(name: str, universe, contacts: prolint.core.contact_provider.ComputedContacts, **kwargs) -> BaseAnalysis :classmethod: Create an analysis instance. :param name: Analysis type name. :type name: str :param universe: ProLint Universe instance. :type universe: Universe :param contacts: Computed contact data. :type contacts: ComputedContacts :param \*\*kwargs: Additional arguments for the analysis. :type \*\*kwargs: dict :returns: Initialized analysis instance. :rtype: BaseAnalysis .. py:method:: available() -> List[str] :classmethod: List available analysis types. :returns: Registered analysis names. :rtype: list of str .. py:method:: get_class(name: str) -> Type[BaseAnalysis] :classmethod: Get an analysis class by name. :param name: Analysis name. :type name: str :returns: Analysis class. :rtype: type .. py:class:: AnalysisResult Container for analysis results. The ``data`` attribute holds primary analysis data (varies by analysis type). The ``metadata`` attribute holds metadata about the analysis (parameters, timestamps, etc.). .. py:attribute:: data :type: Dict[str, Any] Primary analysis data (varies by analysis type). .. py:attribute:: metadata :type: Dict[str, Any] Metadata about the analysis (parameters, timestamps, etc.). .. py:class:: DensityMapAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Compute 2D spatial density maps of database molecules around query. Computes the 2D spatial distribution of database molecule positions relative to the query center of mass over trajectory frames. .. seealso:: :py:obj:`RadialDensityAnalysis` Radially-averaged density from this output .. py:attribute:: name :value: 'density_map' Analysis name for registry. .. py:attribute:: description :value: '2D spatial density of database molecules around query' Human-readable description. .. py:method:: run(frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1, bins: int = 50, database_types: Optional[List[str]] = None) -> prolint.analysis.base.AnalysisResult Compute 2D density map of database molecules. :param frame_start: First frame to process. :type frame_start: int, default=0 :param frame_end: Last frame (exclusive). Defaults to total frames. :type frame_end: int, optional :param frame_step: Step between frames. :type frame_step: int, default=1 :param bins: Number of bins in each dimension. :type bins: int, default=50 :param database_types: Database residue names to include (e.g., ["CHOL", "POPC"]). If None, includes all database atoms. :type database_types: list of str, optional :returns: Result with data containing: - density : 2D list of float density values - x_edges, y_edges : list of float bin edges - x_centers, y_centers : list of float bin centers - query_density : 2D list of float query atom density :rtype: AnalysisResult .. py:class:: RadialDensityAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Radial density profile analysis. Computes radially-averaged density from a 2D density map, useful for analyzing the radial distribution of database molecules around the query. .. seealso:: :py:obj:`DensityMapAnalysis` Generates the 2D density map input .. py:attribute:: name :value: 'radial_density' Analysis name for registry. .. py:attribute:: description :value: 'Radial density profile from 2D density map' Human-readable description. .. py:method:: run(density: List[List[float]], x_edges: List[float], y_edges: List[float], n_bins: int = 50) -> prolint.analysis.base.AnalysisResult Compute radial density profile from 2D density map. :param density: 2D density array from DensityMapAnalysis. :type density: list of list of float :param x_edges: X bin edges from DensityMapAnalysis. :type x_edges: list of float :param y_edges: Y bin edges from DensityMapAnalysis. :type y_edges: list of float :param n_bins: Number of radial bins. :type n_bins: int, default=50 :returns: Result with data containing: - r_centers : list of float radial bin centers - radial_density : list of float density values - r_max : float maximum radius :rtype: AnalysisResult .. py:class:: SharedContactsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Analyze pairwise correlations between query residues. Identifies query residue pairs that interact with the same database molecule simultaneously, revealing potential cooperative binding sites. .. seealso:: :py:obj:`TimeSeriesAnalysis` Contact dynamics over time .. py:attribute:: name :value: 'shared_contacts' Analysis name for registry. .. py:attribute:: description :value: 'Pairwise correlations between query residues via shared database contacts' Human-readable description. .. py:method:: run(database_type: Optional[str] = None, normalize: bool = False) -> prolint.analysis.base.AnalysisResult Compute shared contacts correlation matrix. :param database_type: Filter by database residue name (e.g., "CHOL"). If None, includes all database molecules. :type database_type: str, optional :param normalize: Whether to normalize the matrix to 0-1 range. :type normalize: bool, default=False :returns: Result with data containing: - labels : list of int query residue IDs - matrix : 2D list of int/float shared contact counts - residue_to_index : dict mapping residue ID to matrix index :rtype: AnalysisResult .. py:class:: TimeSeriesAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Analyze contact dynamics over trajectory time. Computes per-frame contact counts for query residues, useful for understanding how contact behavior varies throughout the simulation. .. seealso:: :py:obj:`DatabaseContactsAnalysis` Per-molecule binary contact timeline :py:obj:`KineticsAnalysis` Binding kinetics and residence times .. py:attribute:: name :value: 'timeseries' Analysis name for registry. .. py:attribute:: description :value: 'Contact counts over trajectory time' Human-readable description. .. py:method:: run(database_type: Optional[str] = None, query_residues: Optional[List[int]] = None, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1) -> prolint.analysis.base.AnalysisResult Compute contact count time series. :param database_type: Filter by database residue name (e.g., "CHOL"). :type database_type: str, optional :param query_residues: Specific query residues to include. If None, includes all residues with contacts. :type query_residues: list of int, optional :param frame_start: First frame to process. :type frame_start: int, default=0 :param frame_end: Last frame (exclusive). Defaults to total frames. :type frame_end: int, optional :param frame_step: Step between frames. :type frame_step: int, default=1 :returns: Result with data containing: - query_residues : list of int query residue IDs - frames : list of int frame indices - contact_counts : dict mapping residue_id to list of counts :rtype: AnalysisResult .. py:class:: DatabaseContactsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Compute per-database-molecule contact timeline for a query residue. Creates a binary contact matrix showing which database molecules are in contact with a specific query residue at each frame. .. seealso:: :py:obj:`TimeSeriesAnalysis` Aggregated contact counts over time .. py:attribute:: name :value: 'database_contacts' Analysis name for registry. .. py:attribute:: description :value: 'Per-database-molecule contact timeline' Human-readable description. .. py:method:: run(query_residue: int, database_type: Optional[str] = None, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1, top_n: Optional[int] = None) -> prolint.analysis.base.AnalysisResult Compute binary contact matrix for a query residue. :param query_residue: Query residue ID to analyze. :type query_residue: int :param database_type: Filter by database residue name (e.g., "CHOL"). :type database_type: str, optional :param frame_start: First frame to process. :type frame_start: int, default=0 :param frame_end: Last frame (exclusive). Defaults to total frames. :type frame_end: int, optional :param frame_step: Step between frames. :type frame_step: int, default=1 :param top_n: If specified, return only the top N database IDs with the most contacts. Useful for reducing response size when many database molecules have minimal contacts. :type top_n: int, optional :returns: Result with data containing: - database_ids : list of int sorted database molecule IDs - frames : list of int frame indices - contact_matrix : dict mapping database_id to list of int (0 or 1) :rtype: AnalysisResult .. py:class:: KineticsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Kinetics analysis for binding/unbinding dynamics. Computes binding kinetics metrics including on/off rates, residence times, and survival curves with optional exponential fits. .. attribute:: MIN_EVENTS_MONO Minimum events required for monoexponential fit (default: 5). :type: int .. attribute:: MIN_EVENTS_BI Minimum events required for biexponential fit (default: 25). :type: int .. seealso:: :py:obj:`TimeSeriesAnalysis` Contact counts over time .. py:attribute:: name :value: 'kinetics' Analysis name for registry. .. py:attribute:: description :value: 'Binding kinetics, residence times, and survival curves' Human-readable description. .. py:attribute:: MIN_EVENTS_MONO :value: 5 .. py:attribute:: MIN_EVENTS_BI :value: 25 .. py:method:: run(query_residue: int, database_residue: Optional[int] = None, database_type: Optional[str] = None, mode: Literal['individual', 'accumulated'] = 'individual', fit_survival: bool = True, max_lag: int = 100) -> prolint.analysis.base.AnalysisResult Compute kinetics analysis for a query residue. :param query_residue: Query residue ID to analyze. :type query_residue: int :param database_residue: Specific database residue ID. Required for "individual" mode. :type database_residue: int, optional :param database_type: Database residue name (e.g., "CHOL"). Required for "accumulated" mode. :type database_type: str, optional :param mode: Analysis mode: - "individual": Single residue-residue pair kinetics - "accumulated": Aggregated kinetics across all molecules of a type :type mode: {"individual", "accumulated"}, default="individual" :param fit_survival: Whether to fit exponential models to survival curves. :type fit_survival: bool, default=True :param max_lag: Maximum lag time for survival curve computation. :type max_lag: int, default=100 :returns: Result with data containing: - mode : str analysis mode - kinetics : dict with koff, kon, kd, residence_times, occupancy, n_events, n_frames - survival_curve : dict with lag_times, survival_probability, mono_fit, bi_fit, selected_model - residence_distribution : dict with bins and counts - contact_frames : list of frame indices with contacts :rtype: AnalysisResult :raises ValueError: If database_residue not provided for "individual" mode, or database_type not provided for "accumulated" mode. .. py:class:: DistanceAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Analyze distances between query and database residues over time. Computes center-of-mass distances and optionally minimum atom-atom distances between a query-database residue pair across trajectory frames. .. seealso:: :py:obj:`AtomDistancesAnalysis` Full distance matrix at single frame .. py:attribute:: name :value: 'distances' Analysis name for registry. .. py:attribute:: description :value: 'Distance computations between residue pairs' Human-readable description. .. py:method:: run(query_residue: int, database_residue: int, frame_start: int = 0, frame_end: Optional[int] = None, frame_step: int = 1, compute_min_distances: bool = True, compute_positions: bool = True) -> prolint.analysis.base.AnalysisResult Compute distance time series between a residue pair. :param query_residue: Query residue ID. :type query_residue: int :param database_residue: Database residue ID. :type database_residue: int :param frame_start: First frame to process. :type frame_start: int, default=0 :param frame_end: Last frame (exclusive). Defaults to total frames. :type frame_end: int, optional :param frame_step: Step between frames. :type frame_step: int, default=1 :param compute_min_distances: Whether to compute minimum atom-atom distances. :type compute_min_distances: bool, default=True :param compute_positions: Whether to compute 2D positions relative to query COM. :type compute_positions: bool, default=True :returns: Result with data containing: - frames : list of int frame indices - distances : list of float center-of-mass distances - contact_frames : list of int frames where contact occurred - min_distances : list of float (if compute_min_distances) - positions : dict with query/database 2D positions (if compute_positions) :rtype: AnalysisResult :raises ValueError: If query or database residue not found in universe. .. py:class:: AtomDistancesAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Compute atom-atom distance matrix at a specific frame. Provides detailed per-atom distance information between two residues at a single trajectory frame. .. seealso:: :py:obj:`DistanceAnalysis` Distance time series over multiple frames .. py:attribute:: name :value: 'atom_distances' Analysis name for registry. .. py:attribute:: description :value: 'Atom-atom distance matrix at a specific frame' Human-readable description. .. py:method:: run(query_residue: int, database_residue: int, frame_idx: int) -> prolint.analysis.base.AnalysisResult Compute atom-atom distance matrix between two residues. :param query_residue: Query residue ID. :type query_residue: int :param database_residue: Database residue ID. :type database_residue: int :param frame_idx: Frame index to analyze. Clamped to valid range. :type frame_idx: int :returns: Result with data containing: - frame : int frame index - query_atoms : list of str atom names - database_atoms : list of str atom names - distance_matrix : 2D list of float distances - min_distance, max_distance : float extrema :rtype: AnalysisResult :raises ValueError: If query or database residue not found in universe. .. py:class:: MetricsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts) Bases: :py:obj:`prolint.analysis.base.BaseAnalysis` Per-residue contact metrics analysis. Computes per-residue contact metrics (occupancy, mean, max, sum) and returns values for all query residues in the universe. .. seealso:: :py:obj:`ExactContacts.compute_metric` Underlying metric computation .. py:attribute:: name :value: 'metrics' Analysis name for registry. .. py:attribute:: description :value: 'Per-residue contact metrics (occupancy, mean, max, sum)' Human-readable description. .. py:method:: run(**kwargs) -> prolint.analysis.base.AnalysisResult Compute per-residue contact metrics. :param metric: Metric to compute. One of "occupancy", "mean", "max", "sum". :type metric: str, default="occupancy" :param database_type: Filter by database residue name (e.g., "CHOL"). :type database_type: str, optional :param query_residues: Specific query residues to include. If None, includes all. :type query_residues: list of int, optional :returns: Result with data containing: - residues : list of dict with "resid" and "resname" - values : list of float metric values - metric : str metric name - database_type : str or None :rtype: AnalysisResult