prolint.analysis

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

Classes

BaseAnalysis

Abstract base class for all ProLint analyses.

AnalysisRegistry

Registry for analysis types.

AnalysisResult

Container for analysis results.

DensityMapAnalysis

Compute 2D spatial density maps of database molecules around query.

RadialDensityAnalysis

Radial density profile analysis.

SharedContactsAnalysis

Analyze pairwise correlations between query residues.

TimeSeriesAnalysis

Analyze contact dynamics over trajectory time.

DatabaseContactsAnalysis

Compute per-database-molecule contact timeline for a query residue.

KineticsAnalysis

Kinetics analysis for binding/unbinding dynamics.

DistanceAnalysis

Analyze distances between query and database residues over time.

AtomDistancesAnalysis

Compute atom-atom distance matrix at a specific frame.

MetricsAnalysis

Per-residue contact metrics analysis.

Package Contents

class prolint.analysis.BaseAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: abc.ABC

Abstract base class for all ProLint analyses.

Provides common functionality for filtering contacts, building residue mappings, and generating frame ranges.

Parameters:

See also

AnalysisRegistry

Registry for creating analyses by name

ComputedContacts.analyze

High-level interface to run analyses

name: str = 'base_analysis'

Analysis name for registry.

description: str = 'Base analysis class'

Human-readable description.

universe
contacts
abstractmethod run(**kwargs) → AnalysisResult[source]

Run the analysis and return results.

Parameters:

**kwargs (dict) – Analysis-specific parameters.

Returns:

Container with analysis data and metadata.

Return type:

AnalysisResult

class prolint.analysis.AnalysisRegistry[source]

Registry for analysis types.

Manages registration and creation of analysis classes. All built-in analyses are registered automatically on import.

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")
classmethod register(name: str, analysis_class: Type[BaseAnalysis])[source]

Register an analysis class.

Parameters:

  • name (str) – Name to register under.

  • analysis_class (type) – Analysis class (must inherit from BaseAnalysis).

classmethod create(name: str, universe, contacts: prolint.core.contact_provider.ComputedContacts, **kwargs) → BaseAnalysis[source]

Create an analysis instance.

Parameters:

  • name (str) – Analysis type name.

  • universe (Universe) – ProLint Universe instance.

  • contacts (ComputedContacts) – Computed contact data.

  • **kwargs (dict) – Additional arguments for the analysis.

Returns:

Initialized analysis instance.

Return type:

BaseAnalysis

classmethod available() → List[str][source]

List available analysis types.

Returns:

Registered analysis names.

Return type:

list of str

classmethod get_class(name: str) → Type[BaseAnalysis][source]

Get an analysis class by name.

Parameters:

name (str) – Analysis name.

Returns:

Analysis class.

Return type:

type

class prolint.analysis.AnalysisResult[source]

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

data: Dict[str, Any]

Primary analysis data (varies by analysis type).

metadata: Dict[str, Any]

Metadata about the analysis (parameters, timestamps, etc.).

class prolint.analysis.DensityMapAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

RadialDensityAnalysis

Radially-averaged density from this output

name = 'density_map'

Analysis name for registry.

description = '2D spatial density of database molecules around query'

Human-readable description.

run(frame_start: int = 0, frame_end: int | None = None, frame_step: int = 1, bins: int = 50, database_types: List[str] | None = None) → prolint.analysis.base.AnalysisResult[source]

Compute 2D density map of database molecules.

Parameters:

  • frame_start (int, default=0) – First frame to process.

  • frame_end (int, optional) – Last frame (exclusive). Defaults to total frames.

  • frame_step (int, default=1) – Step between frames.

  • bins (int, default=50) – Number of bins in each dimension.

  • database_types (list of str, optional) – Database residue names to include (e.g., [“CHOL”, “POPC”]). If None, includes all database atoms.

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

Return type:

AnalysisResult

class prolint.analysis.RadialDensityAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

DensityMapAnalysis

Generates the 2D density map input

name = 'radial_density'

Analysis name for registry.

description = 'Radial density profile from 2D density map'

Human-readable description.

run(density: List[List[float]], x_edges: List[float], y_edges: List[float], n_bins: int = 50) → prolint.analysis.base.AnalysisResult[source]

Compute radial density profile from 2D density map.

Parameters:

  • density (list of list of float) – 2D density array from DensityMapAnalysis.

  • x_edges (list of float) – X bin edges from DensityMapAnalysis.

  • y_edges (list of float) – Y bin edges from DensityMapAnalysis.

  • n_bins (int, default=50) – Number of radial bins.

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

Return type:

AnalysisResult

class prolint.analysis.SharedContactsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

TimeSeriesAnalysis

Contact dynamics over time

name = 'shared_contacts'

Analysis name for registry.

description = 'Pairwise correlations between query residues via shared database contacts'

Human-readable description.

run(database_type: str | None = None, normalize: bool = False) → prolint.analysis.base.AnalysisResult[source]

Compute shared contacts correlation matrix.

Parameters:

  • database_type (str, optional) – Filter by database residue name (e.g., “CHOL”). If None, includes all database molecules.

  • normalize (bool, default=False) – Whether to normalize the matrix to 0-1 range.

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

Return type:

AnalysisResult

class prolint.analysis.TimeSeriesAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

DatabaseContactsAnalysis

Per-molecule binary contact timeline

KineticsAnalysis

Binding kinetics and residence times

name = 'timeseries'

Analysis name for registry.

description = 'Contact counts over trajectory time'

Human-readable description.

run(database_type: str | None = None, query_residues: List[int] | None = None, frame_start: int = 0, frame_end: int | None = None, frame_step: int = 1) → prolint.analysis.base.AnalysisResult[source]

Compute contact count time series.

Parameters:

  • database_type (str, optional) – Filter by database residue name (e.g., “CHOL”).

  • query_residues (list of int, optional) – Specific query residues to include. If None, includes all residues with contacts.

  • frame_start (int, default=0) – First frame to process.

  • frame_end (int, optional) – Last frame (exclusive). Defaults to total frames.

  • frame_step (int, default=1) – Step between frames.

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

Return type:

AnalysisResult

class prolint.analysis.DatabaseContactsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

TimeSeriesAnalysis

Aggregated contact counts over time

name = 'database_contacts'

Analysis name for registry.

description = 'Per-database-molecule contact timeline'

Human-readable description.

run(query_residue: int, database_type: str | None = None, frame_start: int = 0, frame_end: int | None = None, frame_step: int = 1, top_n: int | None = None) → prolint.analysis.base.AnalysisResult[source]

Compute binary contact matrix for a query residue.

Parameters:

  • query_residue (int) – Query residue ID to analyze.

  • database_type (str, optional) – Filter by database residue name (e.g., “CHOL”).

  • frame_start (int, default=0) – First frame to process.

  • frame_end (int, optional) – Last frame (exclusive). Defaults to total frames.

  • frame_step (int, default=1) – Step between frames.

  • top_n (int, optional) – 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.

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)

Return type:

AnalysisResult

class prolint.analysis.KineticsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

MIN_EVENTS_MONO

Minimum events required for monoexponential fit (default: 5).

Type:

int

MIN_EVENTS_BI

Minimum events required for biexponential fit (default: 25).

Type:

int

See also

TimeSeriesAnalysis

Contact counts over time

name = 'kinetics'

Analysis name for registry.

description = 'Binding kinetics, residence times, and survival curves'

Human-readable description.

MIN_EVENTS_MONO = 5
MIN_EVENTS_BI = 25
run(query_residue: int, database_residue: int | None = None, database_type: str | None = None, mode: Literal['individual', 'accumulated'] = 'individual', fit_survival: bool = True, max_lag: int = 100) → prolint.analysis.base.AnalysisResult[source]

Compute kinetics analysis for a query residue.

Parameters:

  • query_residue (int) – Query residue ID to analyze.

  • database_residue (int, optional) – Specific database residue ID. Required for “individual” mode.

  • database_type (str, optional) – Database residue name (e.g., “CHOL”). Required for “accumulated” mode.

  • mode ({"individual", "accumulated"}, default="individual") –

    Analysis mode:

    • ”individual”: Single residue-residue pair kinetics

    • ”accumulated”: Aggregated kinetics across all molecules of a type

  • fit_survival (bool, default=True) – Whether to fit exponential models to survival curves.

  • max_lag (int, default=100) – Maximum lag time for survival curve computation.

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

Return type:

AnalysisResult

Raises:

ValueError – If database_residue not provided for “individual” mode, or database_type not provided for “accumulated” mode.

class prolint.analysis.DistanceAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

AtomDistancesAnalysis

Full distance matrix at single frame

name = 'distances'

Analysis name for registry.

description = 'Distance computations between residue pairs'

Human-readable description.

run(query_residue: int, database_residue: int, frame_start: int = 0, frame_end: int | None = None, frame_step: int = 1, compute_min_distances: bool = True, compute_positions: bool = True) → prolint.analysis.base.AnalysisResult[source]

Compute distance time series between a residue pair.

Parameters:

  • query_residue (int) – Query residue ID.

  • database_residue (int) – Database residue ID.

  • frame_start (int, default=0) – First frame to process.

  • frame_end (int, optional) – Last frame (exclusive). Defaults to total frames.

  • frame_step (int, default=1) – Step between frames.

  • compute_min_distances (bool, default=True) – Whether to compute minimum atom-atom distances.

  • compute_positions (bool, default=True) – Whether to compute 2D positions relative to query COM.

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)

Return type:

AnalysisResult

Raises:

ValueError – If query or database residue not found in universe.

class prolint.analysis.AtomDistancesAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

DistanceAnalysis

Distance time series over multiple frames

name = 'atom_distances'

Analysis name for registry.

description = 'Atom-atom distance matrix at a specific frame'

Human-readable description.

run(query_residue: int, database_residue: int, frame_idx: int) → prolint.analysis.base.AnalysisResult[source]

Compute atom-atom distance matrix between two residues.

Parameters:

  • query_residue (int) – Query residue ID.

  • database_residue (int) – Database residue ID.

  • frame_idx (int) – Frame index to analyze. Clamped to valid range.

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

Return type:

AnalysisResult

Raises:

ValueError – If query or database residue not found in universe.

class prolint.analysis.MetricsAnalysis(universe, contacts: prolint.core.contact_provider.ComputedContacts)[source]

Bases: 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.

See also

ExactContacts.compute_metric

Underlying metric computation

name = 'metrics'

Analysis name for registry.

description = 'Per-residue contact metrics (occupancy, mean, max, sum)'

Human-readable description.

run(**kwargs) → prolint.analysis.base.AnalysisResult[source]

Compute per-residue contact metrics.

Parameters:

  • metric (str, default="occupancy") – Metric to compute. One of “occupancy”, “mean”, “max”, “sum”.

  • database_type (str, optional) – Filter by database residue name (e.g., “CHOL”).

  • query_residues (list of int, optional) – Specific query residues to include. If None, includes all.

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

Return type:

AnalysisResult