prolint.plotting¶

ProLint plotting module.

This module provides visualization functions and plotter classes for contact analysis results. Use the plot() function for convenient access to all plot types.

Examples

>>> from prolint.plotting import plot
>>> fig, ax = plot("heatmap", result)
>>> fig, ax = plot("survival_curve", kinetics_result)

Submodules¶

Attributes¶

`COLORS`
`COLOR_SCALES`
`AMINO_ACID_COLORS`
`AMINO_ACID_ONE_LETTER`
`GRADIENTS`
`UNIT_LABELS`
`MAX_NETWORK_RESIDUES`

Classes¶

`BasePlotter`	Abstract base class for all ProLint plotters.
`PlottingRegistry`	Registry for plotter types.
`HeatmapPlotter`	Heatmap plotter for contact counts or correlation matrices.
`DistanceHeatmapPlotter`	Heatmap plotter for atom-atom distance matrices.
`DatabaseContactsHeatmapPlotter`	Heatmap plotter for per-molecule contact timelines.
`NetworkPlotter`	Plotter for residue contact correlation networks.
`TimeSeriesPlotter`	Plotter for contact time series.
`DistanceTimeSeriesPlotter`	Plotter for distance time series.
`ContactEventsPlotter`	Plotter for contact event timelines.
`SurvivalCurvePlotter`	Plotter for survival curves with exponential fits.
`ResidenceDistributionPlotter`	Plotter for residence time distributions.
`DensityMapPlotter`	Plotter for 2D spatial density maps.
`RadialDensityPlotter`	Plotter for radial density profiles.
`ResidueMetricsPlotter`	Plotter for per-residue contact metrics.
`LogoGridPlotter`	Plotter for grid-based residue logo visualization.

Functions¶

`plot`(→ Tuple[matplotlib.figure.Figure, ...)	Create a plot from an AnalysisResult.
`apply_prolint_style`()	Apply ProLint plotting style to matplotlib.
`get_colormap`([name])	Get a matplotlib colormap by name.
`get_color_for_value`(→ str)	Get a hex color for a value from a discrete color scale.
`interpolate_color`(→ Tuple[float, float, float, float])	Interpolate a color from a gradient based on value.
`interpolate_gradient`(→ Tuple[float, float, float, float])	Interpolate a color from a gradient based on value.
`get_unit_label`(→ str)	Get display label for a time unit.
`hex_to_rgb`(→ Tuple[int, int, int])	Convert hex color string to RGB tuple.
`write_pdb`(→ str)	Write contact metrics to a PDB file for visualization.

Package Contents¶

class prolint.plotting.BasePlotter[source]¶

Bases: abc.ABC

Abstract base class for all ProLint plotters.

Plotters convert AnalysisResult objects into matplotlib visualizations. Subclasses must implement the plot() method.

name¶

Plotter name for registry lookup.

Type:: str

required_analysis¶

Name of the analysis type this plotter expects.

Type:: str

description¶

Human-readable description.

Type:: str

See also

PlottingRegistry: Registry for creating plotters by name
plot: Convenience function for plotting

name: str = 'base_plotter'¶

required_analysis: str = ''¶

description: str = 'Base plotter class'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶

Validate that the AnalysisResult contains required data keys.

Parameters:: result (AnalysisResult) – Result to validate.
Raises:: ValueError – If result is missing required keys for this plotter.

classmethod plot(result: prolint.analysis.base.AnalysisResult, **kwargs) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Abstractmethod:

Create the plot from an AnalysisResult.

Parameters:

result (AnalysisResult) – Analysis result containing data to plot.
**kwargs (dict) – Plotter-specific options.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.PlottingRegistry[source]¶

Registry for plotter types.

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

Examples

List available plotters:

>>> from prolint.plotting import PlottingRegistry
>>> PlottingRegistry.available()
['heatmap', 'density_map', 'survival_curve', ...]

Create a plot:

>>> fig, ax = PlottingRegistry.plot("heatmap", result)

classmethod register(name: str, plotter_class: Type[BasePlotter]) → None[source]¶

Parameters:

name (str) – Name to register under.
plotter_class (type) – Plotter class (must inherit from BasePlotter).

classmethod plot(name: str, result: prolint.analysis.base.AnalysisResult, **kwargs) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create a plot using a registered plotter.

Parameters:

name (str) – Plotter type name.
result (AnalysisResult) – Analysis result to plot.
**kwargs (dict) – Plotter-specific options.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

Raises:

ValueError – If plotter name is not registered.

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

List all available plot types.

Returns:: Registered plotter names.
Return type:: list of str

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

Get a plotter class by name.

Parameters:: name (str) – Plotter name.
Returns:: Plotter class.
Return type:: type

classmethod get_info(name: str) → Dict[str, str][source]¶

Get information about a plotter.

Parameters:: name (str) – Plotter name.
Returns:: Dict with name, required_analysis, and description keys.
Return type:: dict

classmethod list_plotters() → List[Dict[str, str]][source]¶

List all plotters with their info.

Returns:: Info dict for each registered plotter.
Return type:: list of dict

prolint.plotting.plot(name: str, result: prolint.analysis.base.AnalysisResult, **kwargs) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create a plot from an AnalysisResult.

Convenience function that delegates to PlottingRegistry.plot().

Parameters:

name (str) – Plotter type name.
result (AnalysisResult) – Analysis result to plot.
**kwargs (dict) – Plotter-specific options.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

Examples

>>> from prolint.plotting import plot
>>> fig, ax = plot("heatmap", timeseries_result)
>>> fig, ax = plot("survival_curve", kinetics_result)

prolint.plotting.COLORS: Dict[source]¶

prolint.plotting.COLOR_SCALES: Dict[str, List[str]][source]¶

prolint.plotting.AMINO_ACID_COLORS: Dict[str, str][source]¶

prolint.plotting.AMINO_ACID_ONE_LETTER: Dict[str, str][source]¶

prolint.plotting.GRADIENTS: Dict[source]¶

prolint.plotting.UNIT_LABELS: Dict[str, str][source]¶

prolint.plotting.apply_prolint_style()[source]¶

Apply ProLint plotting style to matplotlib.

Updates matplotlib rcParams with ProLint theme colors and fonts. Called automatically by plotter classes.

prolint.plotting.get_colormap(name: str = 'viridis')[source]¶

Get a matplotlib colormap by name.

Parameters:: name (str, default="viridis") – Color scale name from COLOR_SCALES.
Returns:: Matplotlib colormap object.
Return type:: LinearSegmentedColormap
Raises:: ValueError – If name is not a valid color scale.

prolint.plotting.get_color_for_value(value: float, scale_name: str = 'prolint', vmin: float = 0, vmax: float = 1) → str[source]¶

Get a hex color for a value from a discrete color scale.

Parameters:

value (float) – Value to map to a color.
scale_name (str, default="prolint") – Name of the color scale from COLOR_SCALES.
vmin (float, default=0) – Minimum value of the range.
vmax (float, default=1) – Maximum value of the range.

Returns:

Hex color string.

Return type:

str

prolint.plotting.interpolate_color(value: float, min_val: float, max_val: float, gradient_name: str = 'sharedContacts') → Tuple[float, float, float, float][source]¶

Interpolate a color from a gradient based on value.

Parameters:

value (float) – Value to interpolate.
min_val (float) – Minimum value in range.
max_val (float) – Maximum value in range.
gradient_name (str, default="sharedContacts") – Gradient name from GRADIENTS.

Returns:

RGBA color tuple with values in 0-1 range.

Return type:

tuple of (float, float, float, float)

prolint.plotting.interpolate_gradient(value: float, min_val: float, max_val: float, gradient_name: str = 'sharedContacts') → Tuple[float, float, float, float][source]¶

Interpolate a color from a gradient based on value.

Parameters:

value (float) – Value to map to a color.
min_val (float) – Minimum value of the range.
max_val (float) – Maximum value of the range.
gradient_name (str, default="sharedContacts") – Name of the gradient to use from GRADIENTS.

Returns:

Interpolated RGBA color values (0-1 range).

Return type:

tuple of float

prolint.plotting.get_unit_label(unit: str) → str[source]¶

Get display label for a time unit.

Parameters:: unit (str) – Time unit code (e.g., “us”, “ns”, “ps”).
Returns:: Human-readable unit label (e.g., “μs”, “ns”, “ps”).
Return type:: str

prolint.plotting.hex_to_rgb(hex_color: str) → Tuple[int, int, int][source]¶

Convert hex color string to RGB tuple.

Parameters:: hex_color (str) – Hex color string (e.g., “#FF5733” or “FF5733”).
Returns:: RGB values as (red, green, blue), each 0-255.
Return type:: tuple of int

class prolint.plotting.HeatmapPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Heatmap plotter for contact counts or correlation matrices.

Works with timeseries results (residue × frame heatmaps) or shared_contacts results (residue × residue correlation matrices).

See also

TimeSeriesAnalysis: Generates timeseries data
SharedContactsAnalysis: Generates correlation matrices

name = 'heatmap'¶

required_analysis = 'timeseries'¶

description = '2D heatmap for contact counts or correlation matrices'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶

Validate that the AnalysisResult contains required data keys.

Parameters:: result (AnalysisResult) – Result to validate.
Raises:: ValueError – If result is missing required keys for this plotter.

classmethod plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'viridis', figsize: Tuple[float, float] | None = None, show_row_labels: bool = True, show_col_labels: bool = True, show_colorbar: bool = True, xlabel: str = '', ylabel: str = '', title: str = '', vmin: float | None = None, vmax: float | None = None, aspect: str = 'auto', ax: matplotlib.axes.Axes | None = None, cbar_label: str = '', max_display_rows: int = 40, max_display_cols: int = 200, origin: str = 'upper') → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create a 2D heatmap visualization.

Parameters:

result (AnalysisResult) – Result from timeseries or shared_contacts analysis.
colorscheme (str, default="viridis") – Color scale name.
figsize (tuple of float, optional) – Figure size (width, height). Auto-calculated if None.
vmin (float, optional) – Color scale limits.
vmax (float, optional) – Color scale limits.
ax (Axes, optional) – Existing axes to plot on.
max_display_rows (int) – Maximum rows/columns before sampling.
max_display_cols (int) – Maximum rows/columns before sampling.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.DistanceHeatmapPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Heatmap plotter for atom-atom distance matrices.

Visualizes pairwise distances between atoms of two residues at a specific frame.

See also

AtomDistancesAnalysis: Generates distance matrix data

name = 'distance_heatmap'¶

required_analysis = 'atom_distances'¶

description = 'Atom-atom distance matrix heatmap'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains distance matrix data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'viridis', figsize: Tuple[float, float] | None = None, show_colorbar: bool = True, xlabel: str = 'Database Atoms', ylabel: str = 'Query Atoms', title: str = '', vmin: float | None = None, vmax: float | None = None, ax: matplotlib.axes.Axes | None = None, cbar_label: str = 'Distance (Å)', annotate: bool = False, annotation_fontsize: int = 8) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create atom-atom distance matrix heatmap.

Parameters:

result (AnalysisResult) – Result from atom_distances analysis.
colorscheme (str, default="viridis") – Color scale name.
annotate (bool, default=False) – Whether to annotate cells with distance values.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.DatabaseContactsHeatmapPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Heatmap plotter for per-molecule contact timelines.

Shows binary contact states (on/off) for each database molecule across trajectory frames for a single query residue.

See also

DatabaseContactsAnalysis: Generates contact timeline data

name = 'database_contacts_heatmap'¶

required_analysis = 'database_contacts'¶

description = 'Per-residue database contact timeline heatmap'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains database contacts data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'blues', figsize: Tuple[float, float] | None = None, show_colorbar: bool = True, xlabel: str = 'Frame', ylabel: str = 'Database Molecule ID', title: str = '', ax: matplotlib.axes.Axes | None = None, cbar_label: str = 'Contact', max_display_rows: int = 50, max_display_cols: int = 500) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create binary contact timeline heatmap.

Parameters:

result (AnalysisResult) – Result from database_contacts analysis.
colorscheme (str, default="blues") – Color scale name.
max_display_rows (int) – Maximum rows/columns before sampling.
max_display_cols (int) – Maximum rows/columns before sampling.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.NetworkPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for residue contact correlation networks.

Visualizes query residues as nodes connected by edges when they share contacts with the same database molecule.

See also

SharedContactsAnalysis: Generates correlation matrix data
HeatmapPlotter: Alternative matrix visualization

name = 'network'¶

required_analysis = 'shared_contacts'¶

description = 'Network graph of query residues sharing database contacts'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required network data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, threshold: int = 0, selected_residues: List[int] | None = None, max_residues: int = MAX_NETWORK_RESIDUES, figsize: Tuple[float, float] = (10, 10), node_size: int = 500, font_size: int = 8, show_edge_labels: bool = False, title: str = 'Shared Contacts Network', highlight_nodes: List[int] | None = None) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create network graph visualization.

Parameters:

result (AnalysisResult) – Result from shared_contacts analysis.
threshold (int, default=0) – Minimum shared frames to draw an edge.
selected_residues (list of int, optional) – Subset of residues to display.
max_residues (int, default=100) – Maximum residues before raising error.
highlight_nodes (list of int, optional) – Residue IDs to highlight.
show_edge_labels (bool, default=False) – Whether to show edge weights.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

Raises:

ImportError – If networkx is not installed.
ValueError – If too many residues to display.

prolint.plotting.MAX_NETWORK_RESIDUES = 100[source]¶

class prolint.plotting.TimeSeriesPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for contact time series.

Displays contact counts over trajectory frames for multiple residues as overlaid line plots.

See also

TimeSeriesAnalysis: Generates time series data
DistanceTimeSeriesPlotter: Distance evolution plots

name = 'timeseries'¶

required_analysis = 'timeseries'¶

description = 'Contact counts over time for multiple residues'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required time series data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Frame', ylabel: str = 'Contact Count', title: str = 'Contacts Over Time', figsize: Tuple[float, float] = (10, 4), ax: matplotlib.axes.Axes | None = None, time_units: str | None = None, dt: float = 1.0, legend: bool = True, max_series: int = 10) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create contact count time series plot.

Parameters:

result (AnalysisResult) – Result from timeseries analysis.
xlabel (str, default="Frame") – X-axis label.
ylabel (str, default="Contact Count") – Y-axis label.
title (str, default="Contacts Over Time") – Plot title.
figsize (tuple of (float, float), default=(10, 4)) – Figure dimensions (width, height).
ax (Axes, optional) – Existing axes to plot on.
time_units (str, optional) – Time unit for x-axis (e.g., “ns”, “us”).
dt (float, default=1.0) – Time step multiplier when using time_units.
legend (bool, default=True) – Whether to show legend.
max_series (int, default=10) – Maximum number of residue series to plot.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.DistanceTimeSeriesPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for distance time series.

Displays distance evolution between query and database residues over trajectory frames with optional cutoff line and contact highlighting.

See also

DistanceAnalysis: Generates distance data
TimeSeriesPlotter: Contact count time series

name = 'distance_timeseries'¶

required_analysis = 'distances'¶

description = 'Distance over time between query and database residue'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required distance data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, cutoff: float | None = None, xlabel: str = 'Frame', ylabel: str = 'Distance (Å)', title: str = 'Distance Over Time', figsize: Tuple[float, float] = (12, 4), ax: matplotlib.axes.Axes | None = None, time_units: str | None = None, dt: float = 1.0) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create distance time series plot.

Parameters:

result (AnalysisResult) – Result from distances analysis.
cutoff (float, optional) – Distance cutoff to draw as horizontal line.
xlabel (str, default="Frame") – X-axis label.
ylabel (str, default="Distance (Å)") – Y-axis label.
title (str, default="Distance Over Time") – Plot title.
figsize (tuple of (float, float), default=(12, 4)) – Figure dimensions (width, height).
ax (Axes, optional) – Existing axes to plot on.
time_units (str, optional) – Time unit for x-axis (e.g., “ns”, “us”).
dt (float, default=1.0) – Time step multiplier when using time_units.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.ContactEventsPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for contact event timelines.

Displays contact events as horizontal bars on a timeline, showing when contacts occur during the trajectory.

See also

KineticsAnalysis: Generates contact event data
SurvivalCurvePlotter: Survival probability curves

name = 'contact_events'¶

required_analysis = 'kinetics'¶

description = 'Contact events timeline showing when contacts occur'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains contact_frames data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Frame', title: str = 'Contact Events', figsize: Tuple[float, float] = (12, 2), ax: matplotlib.axes.Axes | None = None, time_units: str | None = None, dt: float = 1.0) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create contact events timeline plot.

Parameters:

result (AnalysisResult) – Result from kinetics analysis.
xlabel (str, default="Frame") – X-axis label.
title (str, default="Contact Events") – Plot title.
figsize (tuple of (float, float), default=(12, 2)) – Figure dimensions (width, height).
ax (Axes, optional) – Existing axes to plot on.
time_units (str, optional) – Time unit for x-axis (e.g., “ns”, “us”).
dt (float, default=1.0) – Time step multiplier when using time_units.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.SurvivalCurvePlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for survival curves with exponential fits.

Visualizes contact survival probability over lag time with optional mono- and bi-exponential model fits.

See also

KineticsAnalysis: Generates survival curve data
ResidenceDistributionPlotter: Residence time histograms

name = 'survival_curve'¶

required_analysis = 'kinetics'¶

description = 'Survival curve with mono/bi-exponential fits'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required survival curve data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Lag Time (frames)', ylabel: str = 'Survival Probability', title: str = 'Survival Curve', figsize: Tuple[float, float] = (8, 5), ax: matplotlib.axes.Axes | None = None, show_legend: bool = True, time_units: str | None = None, dt: float = 1.0) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create survival curve plot with exponential fits.

Parameters:

result (AnalysisResult) – Result from kinetics analysis.
time_units (str, optional) – Time unit for x-axis (e.g., “ns”, “us”).
dt (float, default=1.0) – Time step multiplier when using time_units.
show_legend (bool, default=True) – Whether to show fit parameters in legend.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.ResidenceDistributionPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for residence time distributions.

Visualizes the distribution of contact durations as a histogram.

See also

KineticsAnalysis: Generates residence distribution data
SurvivalCurvePlotter: Survival curves

name = 'residence_distribution'¶

required_analysis = 'kinetics'¶

description = 'Histogram of residence time durations'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required residence distribution data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Residence Time (frames)', ylabel: str = 'Count', title: str = 'Residence Time Distribution', figsize: Tuple[float, float] = (8, 4), ax: matplotlib.axes.Axes | None = None, time_units: str | None = None, dt: float = 1.0, log_scale: bool = False) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create residence time histogram.

Parameters:

result (AnalysisResult) – Result from kinetics analysis.
time_units (str, optional) – Time unit for x-axis.
dt (float, default=1.0) – Time step multiplier.
log_scale (bool, default=False) – Whether to use log scale for y-axis.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.DensityMapPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for 2D spatial density maps.

Visualizes the spatial distribution of database molecules around the query center of mass.

See also

DensityMapAnalysis: Generates density map data
RadialDensityPlotter: Radial density profiles

name = 'density_map'¶

required_analysis = 'density_map'¶

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

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required density map data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'viridis', xlabel: str = 'X (Å)', ylabel: str = 'Y (Å)', title: str = 'Density Map', figsize: Tuple[float, float] = (8, 8), ax: matplotlib.axes.Axes | None = None, show_colorbar: bool = True, cbar_label: str = 'Density', log_scale: bool = False, aspect: str = 'equal', vmin: float | None = None, vmax: float | None = None, show_query_contours: bool = True, highlight_query_residues: List[int] | None = None, highlight_database_ids: List[int] | None = None, universe=None, frame: int = 0) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create 2D density map visualization.

Parameters:

result (AnalysisResult) – Result from density_map analysis.
colorscheme (str, default="viridis") – Color scale name.
log_scale (bool, default=False) – Whether to use logarithmic color scale.
show_query_contours (bool, default=True) – Whether to overlay query density as contours.
highlight_query_residues (list of int, optional) – Query residues to highlight on the map.
highlight_database_ids (list of int, optional) – Database molecules to highlight.
universe (Universe, optional) – Required for highlighting residues.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.RadialDensityPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for radial density profiles.

Visualizes radially-averaged density as a function of distance from the query center.

See also

RadialDensityAnalysis: Generates radial density data
DensityMapPlotter: 2D density maps

name = 'radial_density'¶

required_analysis = 'radial_density'¶

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

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains required radial density data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Distance from Center (Å)', ylabel: str = 'Radial Density', title: str = 'Radial Density Profile', figsize: Tuple[float, float] = (8, 4), ax: matplotlib.axes.Axes | None = None) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create radial density profile plot.

Parameters:

result (AnalysisResult) – Result from radial_density analysis.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.ResidueMetricsPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for per-residue contact metrics.

Visualizes metrics as bar charts or scatter plots with amino acid coloring and highlighting options.

See also

MetricsAnalysis: Generates per-residue metric data
LogoGridPlotter: Grid-based residue visualization

name = 'residue_metrics'¶

required_analysis = 'metrics'¶

description = 'Per-residue metrics visualization (bar/scatter)'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains residue metrics data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, style: str = 'bar', colorscheme: str = 'prolint', xlabel: str = 'Residue', ylabel: str = 'Value', title: str = 'Per-Residue Metrics', figsize: Tuple[float, float] | None = None, ax: matplotlib.axes.Axes | None = None, show_aa_labels: bool = True, highlight_residues: List[int] | None = None, bar_width: float = 0.8, sort_by_value: bool = False, marker_size: int = 50) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create per-residue metrics visualization.

Parameters:

result (AnalysisResult) – Result from metrics analysis.
style ({"bar", "scatter"}, default="bar") – Plot style.
colorscheme (str, default="prolint") – Color scheme (“prolint”, “amino_acid”, or scale name).
show_aa_labels (bool, default=True) – Whether to show amino acid labels on x-axis.
highlight_residues (list of int, optional) – Residue IDs to highlight.
sort_by_value (bool, default=False) – Whether to sort residues by value.
ax (Axes, optional) – Existing axes to plot on.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

class prolint.plotting.LogoGridPlotter[source]¶

Bases: prolint.plotting.base.BasePlotter

Plotter for grid-based residue logo visualization.

Displays residues as colored cells arranged in rows with one-letter amino acid codes and residue numbers.

See also

MetricsAnalysis: Generates per-residue metric data
ResidueMetricsPlotter: Bar/scatter visualization

name = 'logo_grid'¶

required_analysis = 'metrics'¶

description = 'Grid-based residue logo plot with amino acid annotations'¶

classmethod validate_result(result: prolint.analysis.base.AnalysisResult) → None[source]¶: Validate that result contains residue metrics data.

classmethod plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'prolint', residues_per_row: int = 80, cell_size: float = 0.3, title: str = 'Residue Logo Plot', figsize: Tuple[float, float] | None = None, highlight_residues: List[int] | None = None) → Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes][source]¶

Create grid-based residue logo visualization.

Parameters:

result (AnalysisResult) – Result from metrics analysis.
colorscheme (str, default="prolint") – Color scale name for value-based coloring.
residues_per_row (int, default=80) – Number of residue cells per row.
cell_size (float, default=0.3) – Size of each cell in inches.
title (str, default="Residue Logo Plot") – Plot title.
figsize (tuple of (float, float), optional) – Figure dimensions (width, height). Auto-calculated if None.
highlight_residues (list of int, optional) – Residue IDs to highlight with colored borders.

Returns:

Matplotlib figure and axes objects.

Return type:

tuple of (Figure, Axes)

prolint.plotting.write_pdb(contacts, metric: Literal['mean', 'max', 'sum', 'occupancy'] = 'occupancy', target_resname: str | None = None, filename: str | None = None, frame: int = 0) → str[source]¶

Write contact metrics to a PDB file for visualization.

Exports query atoms to a PDB file with metric values stored in the B-factor column for coloring in molecular viewers.

Parameters:

contacts (ComputedContacts) – Computed contact data.
metric ({"mean", "max", "sum", "occupancy"}, default="occupancy") – Metric to write to B-factor column.
target_resname (str, optional) – Filter by database residue name (e.g., “CHOL”).
filename (str, optional) – Output filename. If None, creates a temporary file.
frame (int, default=0) – Trajectory frame to use for coordinates.

Returns:

Path to the written PDB file.

Return type:

str

Examples

>>> from prolint.plotting import write_pdb
>>> pdb_path = write_pdb(contacts, metric="occupancy")
>>> # Open in PyMOL/VMD and color by B-factor