prolint.plotting ================ .. py:module:: prolint.plotting .. autoapi-nested-parse:: ProLint plotting module. This module provides visualization functions and plotter classes for contact analysis results. Use the :func:`plot` function for convenient access to all plot types. .. rubric:: Examples >>> from prolint.plotting import plot >>> fig, ax = plot("heatmap", result) >>> fig, ax = plot("survival_curve", kinetics_result) Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/prolint/plotting/base/index /autoapi/prolint/plotting/density/index /autoapi/prolint/plotting/heatmap/index /autoapi/prolint/plotting/kinetics/index /autoapi/prolint/plotting/network/index /autoapi/prolint/plotting/residues/index /autoapi/prolint/plotting/structure/index /autoapi/prolint/plotting/theme/index /autoapi/prolint/plotting/timeseries/index Attributes ---------- .. autoapisummary:: prolint.plotting.COLORS prolint.plotting.COLOR_SCALES prolint.plotting.AMINO_ACID_COLORS prolint.plotting.AMINO_ACID_ONE_LETTER prolint.plotting.GRADIENTS prolint.plotting.UNIT_LABELS prolint.plotting.MAX_NETWORK_RESIDUES Classes ------- .. autoapisummary:: prolint.plotting.BasePlotter prolint.plotting.PlottingRegistry prolint.plotting.HeatmapPlotter prolint.plotting.DistanceHeatmapPlotter prolint.plotting.DatabaseContactsHeatmapPlotter prolint.plotting.NetworkPlotter prolint.plotting.TimeSeriesPlotter prolint.plotting.DistanceTimeSeriesPlotter prolint.plotting.ContactEventsPlotter prolint.plotting.SurvivalCurvePlotter prolint.plotting.ResidenceDistributionPlotter prolint.plotting.DensityMapPlotter prolint.plotting.RadialDensityPlotter prolint.plotting.ResidueMetricsPlotter prolint.plotting.LogoGridPlotter Functions --------- .. autoapisummary:: prolint.plotting.plot prolint.plotting.apply_prolint_style prolint.plotting.get_colormap prolint.plotting.get_color_for_value prolint.plotting.interpolate_color prolint.plotting.interpolate_gradient prolint.plotting.get_unit_label prolint.plotting.hex_to_rgb prolint.plotting.write_pdb Package Contents ---------------- .. py:class:: BasePlotter Bases: :py:obj:`abc.ABC` Abstract base class for all ProLint plotters. Plotters convert AnalysisResult objects into matplotlib visualizations. Subclasses must implement the ``plot()`` method. .. attribute:: name Plotter name for registry lookup. :type: str .. attribute:: required_analysis Name of the analysis type this plotter expects. :type: str .. attribute:: description Human-readable description. :type: str .. seealso:: :py:obj:`PlottingRegistry` Registry for creating plotters by name :py:obj:`plot` Convenience function for plotting .. py:attribute:: name :type: str :value: 'base_plotter' .. py:attribute:: required_analysis :type: str :value: '' .. py:attribute:: description :type: str :value: 'Base plotter class' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that the AnalysisResult contains required data keys. :param result: Result to validate. :type result: AnalysisResult :raises ValueError: If result is missing required keys for this plotter. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, **kwargs) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: :abstractmethod: Create the plot from an AnalysisResult. :param result: Analysis result containing data to plot. :type result: AnalysisResult :param \*\*kwargs: Plotter-specific options. :type \*\*kwargs: dict :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: PlottingRegistry Registry for plotter types. Manages registration and creation of plotter classes. All built-in plotters are registered automatically on import. .. rubric:: 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) .. py:method:: register(name: str, plotter_class: Type[BasePlotter]) -> None :classmethod: Register a plotter class. :param name: Name to register under. :type name: str :param plotter_class: Plotter class (must inherit from BasePlotter). :type plotter_class: type .. py:method:: plot(name: str, result: prolint.analysis.base.AnalysisResult, **kwargs) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create a plot using a registered plotter. :param name: Plotter type name. :type name: str :param result: Analysis result to plot. :type result: AnalysisResult :param \*\*kwargs: Plotter-specific options. :type \*\*kwargs: dict :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) :raises ValueError: If plotter name is not registered. .. py:method:: available() -> List[str] :classmethod: List all available plot types. :returns: Registered plotter names. :rtype: list of str .. py:method:: get_class(name: str) -> Type[BasePlotter] :classmethod: Get a plotter class by name. :param name: Plotter name. :type name: str :returns: Plotter class. :rtype: type .. py:method:: get_info(name: str) -> Dict[str, str] :classmethod: Get information about a plotter. :param name: Plotter name. :type name: str :returns: Dict with name, required_analysis, and description keys. :rtype: dict .. py:method:: list_plotters() -> List[Dict[str, str]] :classmethod: List all plotters with their info. :returns: Info dict for each registered plotter. :rtype: list of dict .. py:function:: plot(name: str, result: prolint.analysis.base.AnalysisResult, **kwargs) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] Create a plot from an AnalysisResult. Convenience function that delegates to PlottingRegistry.plot(). :param name: Plotter type name. :type name: str :param result: Analysis result to plot. :type result: AnalysisResult :param \*\*kwargs: Plotter-specific options. :type \*\*kwargs: dict :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. rubric:: Examples >>> from prolint.plotting import plot >>> fig, ax = plot("heatmap", timeseries_result) >>> fig, ax = plot("survival_curve", kinetics_result) .. py:data:: COLORS :type: Dict .. py:data:: COLOR_SCALES :type: Dict[str, List[str]] .. py:data:: AMINO_ACID_COLORS :type: Dict[str, str] .. py:data:: AMINO_ACID_ONE_LETTER :type: Dict[str, str] .. py:data:: GRADIENTS :type: Dict .. py:data:: UNIT_LABELS :type: Dict[str, str] .. py:function:: apply_prolint_style() Apply ProLint plotting style to matplotlib. Updates matplotlib rcParams with ProLint theme colors and fonts. Called automatically by plotter classes. .. py:function:: get_colormap(name: str = 'viridis') Get a matplotlib colormap by name. :param name: Color scale name from COLOR_SCALES. :type name: str, default="viridis" :returns: Matplotlib colormap object. :rtype: LinearSegmentedColormap :raises ValueError: If name is not a valid color scale. .. py:function:: get_color_for_value(value: float, scale_name: str = 'prolint', vmin: float = 0, vmax: float = 1) -> str Get a hex color for a value from a discrete color scale. :param value: Value to map to a color. :type value: float :param scale_name: Name of the color scale from COLOR_SCALES. :type scale_name: str, default="prolint" :param vmin: Minimum value of the range. :type vmin: float, default=0 :param vmax: Maximum value of the range. :type vmax: float, default=1 :returns: Hex color string. :rtype: str .. py:function:: interpolate_color(value: float, min_val: float, max_val: float, gradient_name: str = 'sharedContacts') -> Tuple[float, float, float, float] Interpolate a color from a gradient based on value. :param value: Value to interpolate. :type value: float :param min_val: Minimum value in range. :type min_val: float :param max_val: Maximum value in range. :type max_val: float :param gradient_name: Gradient name from GRADIENTS. :type gradient_name: str, default="sharedContacts" :returns: RGBA color tuple with values in 0-1 range. :rtype: tuple of (float, float, float, float) .. py:function:: interpolate_gradient(value: float, min_val: float, max_val: float, gradient_name: str = 'sharedContacts') -> Tuple[float, float, float, float] Interpolate a color from a gradient based on value. :param value: Value to map to a color. :type value: float :param min_val: Minimum value of the range. :type min_val: float :param max_val: Maximum value of the range. :type max_val: float :param gradient_name: Name of the gradient to use from GRADIENTS. :type gradient_name: str, default="sharedContacts" :returns: Interpolated RGBA color values (0-1 range). :rtype: tuple of float .. py:function:: get_unit_label(unit: str) -> str Get display label for a time unit. :param unit: Time unit code (e.g., "us", "ns", "ps"). :type unit: str :returns: Human-readable unit label (e.g., "μs", "ns", "ps"). :rtype: str .. py:function:: hex_to_rgb(hex_color: str) -> Tuple[int, int, int] Convert hex color string to RGB tuple. :param hex_color: Hex color string (e.g., "#FF5733" or "FF5733"). :type hex_color: str :returns: RGB values as (red, green, blue), each 0-255. :rtype: tuple of int .. py:class:: HeatmapPlotter Bases: :py:obj:`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). .. seealso:: :py:obj:`TimeSeriesAnalysis` Generates timeseries data :py:obj:`SharedContactsAnalysis` Generates correlation matrices .. py:attribute:: name :value: 'heatmap' .. py:attribute:: required_analysis :value: 'timeseries' .. py:attribute:: description :value: '2D heatmap for contact counts or correlation matrices' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that the AnalysisResult contains required data keys. :param result: Result to validate. :type result: AnalysisResult :raises ValueError: If result is missing required keys for this plotter. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'viridis', figsize: Optional[Tuple[float, float]] = None, show_row_labels: bool = True, show_col_labels: bool = True, show_colorbar: bool = True, xlabel: str = '', ylabel: str = '', title: str = '', vmin: Optional[float] = None, vmax: Optional[float] = None, aspect: str = 'auto', ax: Optional[matplotlib.axes.Axes] = None, cbar_label: str = '', max_display_rows: int = 40, max_display_cols: int = 200, origin: str = 'upper') -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create a 2D heatmap visualization. :param result: Result from timeseries or shared_contacts analysis. :type result: AnalysisResult :param colorscheme: Color scale name. :type colorscheme: str, default="viridis" :param figsize: Figure size (width, height). Auto-calculated if None. :type figsize: tuple of float, optional :param vmin: Color scale limits. :type vmin: float, optional :param vmax: Color scale limits. :type vmax: float, optional :param ax: Existing axes to plot on. :type ax: Axes, optional :param max_display_rows: Maximum rows/columns before sampling. :type max_display_rows: int :param max_display_cols: Maximum rows/columns before sampling. :type max_display_cols: int :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: DistanceHeatmapPlotter Bases: :py:obj:`prolint.plotting.base.BasePlotter` Heatmap plotter for atom-atom distance matrices. Visualizes pairwise distances between atoms of two residues at a specific frame. .. seealso:: :py:obj:`AtomDistancesAnalysis` Generates distance matrix data .. py:attribute:: name :value: 'distance_heatmap' .. py:attribute:: required_analysis :value: 'atom_distances' .. py:attribute:: description :value: 'Atom-atom distance matrix heatmap' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains distance matrix data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'viridis', figsize: Optional[Tuple[float, float]] = None, show_colorbar: bool = True, xlabel: str = 'Database Atoms', ylabel: str = 'Query Atoms', title: str = '', vmin: Optional[float] = None, vmax: Optional[float] = None, ax: Optional[matplotlib.axes.Axes] = None, cbar_label: str = 'Distance (Å)', annotate: bool = False, annotation_fontsize: int = 8) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create atom-atom distance matrix heatmap. :param result: Result from atom_distances analysis. :type result: AnalysisResult :param colorscheme: Color scale name. :type colorscheme: str, default="viridis" :param annotate: Whether to annotate cells with distance values. :type annotate: bool, default=False :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: DatabaseContactsHeatmapPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`DatabaseContactsAnalysis` Generates contact timeline data .. py:attribute:: name :value: 'database_contacts_heatmap' .. py:attribute:: required_analysis :value: 'database_contacts' .. py:attribute:: description :value: 'Per-residue database contact timeline heatmap' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains database contacts data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, colorscheme: str = 'blues', figsize: Optional[Tuple[float, float]] = None, show_colorbar: bool = True, xlabel: str = 'Frame', ylabel: str = 'Database Molecule ID', title: str = '', ax: Optional[matplotlib.axes.Axes] = None, cbar_label: str = 'Contact', max_display_rows: int = 50, max_display_cols: int = 500) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create binary contact timeline heatmap. :param result: Result from database_contacts analysis. :type result: AnalysisResult :param colorscheme: Color scale name. :type colorscheme: str, default="blues" :param max_display_rows: Maximum rows/columns before sampling. :type max_display_rows: int :param max_display_cols: Maximum rows/columns before sampling. :type max_display_cols: int :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: NetworkPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`SharedContactsAnalysis` Generates correlation matrix data :py:obj:`HeatmapPlotter` Alternative matrix visualization .. py:attribute:: name :value: 'network' .. py:attribute:: required_analysis :value: 'shared_contacts' .. py:attribute:: description :value: 'Network graph of query residues sharing database contacts' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required network data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, threshold: int = 0, selected_residues: Optional[List[int]] = 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: Optional[List[int]] = None) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create network graph visualization. :param result: Result from shared_contacts analysis. :type result: AnalysisResult :param threshold: Minimum shared frames to draw an edge. :type threshold: int, default=0 :param selected_residues: Subset of residues to display. :type selected_residues: list of int, optional :param max_residues: Maximum residues before raising error. :type max_residues: int, default=100 :param highlight_nodes: Residue IDs to highlight. :type highlight_nodes: list of int, optional :param show_edge_labels: Whether to show edge weights. :type show_edge_labels: bool, default=False :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) :raises ImportError: If networkx is not installed. :raises ValueError: If too many residues to display. .. py:data:: MAX_NETWORK_RESIDUES :value: 100 .. py:class:: TimeSeriesPlotter Bases: :py:obj:`prolint.plotting.base.BasePlotter` Plotter for contact time series. Displays contact counts over trajectory frames for multiple residues as overlaid line plots. .. seealso:: :py:obj:`TimeSeriesAnalysis` Generates time series data :py:obj:`DistanceTimeSeriesPlotter` Distance evolution plots .. py:attribute:: name :value: 'timeseries' .. py:attribute:: required_analysis :value: 'timeseries' .. py:attribute:: description :value: 'Contact counts over time for multiple residues' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required time series data. .. py:method:: 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: Optional[matplotlib.axes.Axes] = None, time_units: Optional[str] = None, dt: float = 1.0, legend: bool = True, max_series: int = 10) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create contact count time series plot. :param result: Result from timeseries analysis. :type result: AnalysisResult :param xlabel: X-axis label. :type xlabel: str, default="Frame" :param ylabel: Y-axis label. :type ylabel: str, default="Contact Count" :param title: Plot title. :type title: str, default="Contacts Over Time" :param figsize: Figure dimensions (width, height). :type figsize: tuple of (float, float), default=(10, 4) :param ax: Existing axes to plot on. :type ax: Axes, optional :param time_units: Time unit for x-axis (e.g., "ns", "us"). :type time_units: str, optional :param dt: Time step multiplier when using time_units. :type dt: float, default=1.0 :param legend: Whether to show legend. :type legend: bool, default=True :param max_series: Maximum number of residue series to plot. :type max_series: int, default=10 :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: DistanceTimeSeriesPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`DistanceAnalysis` Generates distance data :py:obj:`TimeSeriesPlotter` Contact count time series .. py:attribute:: name :value: 'distance_timeseries' .. py:attribute:: required_analysis :value: 'distances' .. py:attribute:: description :value: 'Distance over time between query and database residue' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required distance data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, cutoff: Optional[float] = None, xlabel: str = 'Frame', ylabel: str = 'Distance (Å)', title: str = 'Distance Over Time', figsize: Tuple[float, float] = (12, 4), ax: Optional[matplotlib.axes.Axes] = None, time_units: Optional[str] = None, dt: float = 1.0) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create distance time series plot. :param result: Result from distances analysis. :type result: AnalysisResult :param cutoff: Distance cutoff to draw as horizontal line. :type cutoff: float, optional :param xlabel: X-axis label. :type xlabel: str, default="Frame" :param ylabel: Y-axis label. :type ylabel: str, default="Distance (Å)" :param title: Plot title. :type title: str, default="Distance Over Time" :param figsize: Figure dimensions (width, height). :type figsize: tuple of (float, float), default=(12, 4) :param ax: Existing axes to plot on. :type ax: Axes, optional :param time_units: Time unit for x-axis (e.g., "ns", "us"). :type time_units: str, optional :param dt: Time step multiplier when using time_units. :type dt: float, default=1.0 :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: ContactEventsPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`KineticsAnalysis` Generates contact event data :py:obj:`SurvivalCurvePlotter` Survival probability curves .. py:attribute:: name :value: 'contact_events' .. py:attribute:: required_analysis :value: 'kinetics' .. py:attribute:: description :value: 'Contact events timeline showing when contacts occur' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains contact_frames data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, xlabel: str = 'Frame', title: str = 'Contact Events', figsize: Tuple[float, float] = (12, 2), ax: Optional[matplotlib.axes.Axes] = None, time_units: Optional[str] = None, dt: float = 1.0) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create contact events timeline plot. :param result: Result from kinetics analysis. :type result: AnalysisResult :param xlabel: X-axis label. :type xlabel: str, default="Frame" :param title: Plot title. :type title: str, default="Contact Events" :param figsize: Figure dimensions (width, height). :type figsize: tuple of (float, float), default=(12, 2) :param ax: Existing axes to plot on. :type ax: Axes, optional :param time_units: Time unit for x-axis (e.g., "ns", "us"). :type time_units: str, optional :param dt: Time step multiplier when using time_units. :type dt: float, default=1.0 :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: SurvivalCurvePlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`KineticsAnalysis` Generates survival curve data :py:obj:`ResidenceDistributionPlotter` Residence time histograms .. py:attribute:: name :value: 'survival_curve' .. py:attribute:: required_analysis :value: 'kinetics' .. py:attribute:: description :value: 'Survival curve with mono/bi-exponential fits' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required survival curve data. .. py:method:: 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: Optional[matplotlib.axes.Axes] = None, show_legend: bool = True, time_units: Optional[str] = None, dt: float = 1.0) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create survival curve plot with exponential fits. :param result: Result from kinetics analysis. :type result: AnalysisResult :param time_units: Time unit for x-axis (e.g., "ns", "us"). :type time_units: str, optional :param dt: Time step multiplier when using time_units. :type dt: float, default=1.0 :param show_legend: Whether to show fit parameters in legend. :type show_legend: bool, default=True :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: ResidenceDistributionPlotter Bases: :py:obj:`prolint.plotting.base.BasePlotter` Plotter for residence time distributions. Visualizes the distribution of contact durations as a histogram. .. seealso:: :py:obj:`KineticsAnalysis` Generates residence distribution data :py:obj:`SurvivalCurvePlotter` Survival curves .. py:attribute:: name :value: 'residence_distribution' .. py:attribute:: required_analysis :value: 'kinetics' .. py:attribute:: description :value: 'Histogram of residence time durations' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required residence distribution data. .. py:method:: 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: Optional[matplotlib.axes.Axes] = None, time_units: Optional[str] = None, dt: float = 1.0, log_scale: bool = False) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create residence time histogram. :param result: Result from kinetics analysis. :type result: AnalysisResult :param time_units: Time unit for x-axis. :type time_units: str, optional :param dt: Time step multiplier. :type dt: float, default=1.0 :param log_scale: Whether to use log scale for y-axis. :type log_scale: bool, default=False :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: DensityMapPlotter Bases: :py:obj:`prolint.plotting.base.BasePlotter` Plotter for 2D spatial density maps. Visualizes the spatial distribution of database molecules around the query center of mass. .. seealso:: :py:obj:`DensityMapAnalysis` Generates density map data :py:obj:`RadialDensityPlotter` Radial density profiles .. py:attribute:: name :value: 'density_map' .. py:attribute:: required_analysis :value: 'density_map' .. py:attribute:: description :value: '2D spatial density of database molecules around query' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required density map data. .. py:method:: 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: Optional[matplotlib.axes.Axes] = None, show_colorbar: bool = True, cbar_label: str = 'Density', log_scale: bool = False, aspect: str = 'equal', vmin: Optional[float] = None, vmax: Optional[float] = None, show_query_contours: bool = True, highlight_query_residues: Optional[List[int]] = None, highlight_database_ids: Optional[List[int]] = None, universe=None, frame: int = 0) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create 2D density map visualization. :param result: Result from density_map analysis. :type result: AnalysisResult :param colorscheme: Color scale name. :type colorscheme: str, default="viridis" :param log_scale: Whether to use logarithmic color scale. :type log_scale: bool, default=False :param show_query_contours: Whether to overlay query density as contours. :type show_query_contours: bool, default=True :param highlight_query_residues: Query residues to highlight on the map. :type highlight_query_residues: list of int, optional :param highlight_database_ids: Database molecules to highlight. :type highlight_database_ids: list of int, optional :param universe: Required for highlighting residues. :type universe: Universe, optional :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: RadialDensityPlotter Bases: :py:obj:`prolint.plotting.base.BasePlotter` Plotter for radial density profiles. Visualizes radially-averaged density as a function of distance from the query center. .. seealso:: :py:obj:`RadialDensityAnalysis` Generates radial density data :py:obj:`DensityMapPlotter` 2D density maps .. py:attribute:: name :value: 'radial_density' .. py:attribute:: required_analysis :value: 'radial_density' .. py:attribute:: description :value: 'Radial density profile from 2D density map' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains required radial density data. .. py:method:: 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: Optional[matplotlib.axes.Axes] = None) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create radial density profile plot. :param result: Result from radial_density analysis. :type result: AnalysisResult :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: ResidueMetricsPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`MetricsAnalysis` Generates per-residue metric data :py:obj:`LogoGridPlotter` Grid-based residue visualization .. py:attribute:: name :value: 'residue_metrics' .. py:attribute:: required_analysis :value: 'metrics' .. py:attribute:: description :value: 'Per-residue metrics visualization (bar/scatter)' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains residue metrics data. .. py:method:: plot(result: prolint.analysis.base.AnalysisResult, style: str = 'bar', colorscheme: str = 'prolint', xlabel: str = 'Residue', ylabel: str = 'Value', title: str = 'Per-Residue Metrics', figsize: Optional[Tuple[float, float]] = None, ax: Optional[matplotlib.axes.Axes] = None, show_aa_labels: bool = True, highlight_residues: Optional[List[int]] = None, bar_width: float = 0.8, sort_by_value: bool = False, marker_size: int = 50) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create per-residue metrics visualization. :param result: Result from metrics analysis. :type result: AnalysisResult :param style: Plot style. :type style: {"bar", "scatter"}, default="bar" :param colorscheme: Color scheme ("prolint", "amino_acid", or scale name). :type colorscheme: str, default="prolint" :param show_aa_labels: Whether to show amino acid labels on x-axis. :type show_aa_labels: bool, default=True :param highlight_residues: Residue IDs to highlight. :type highlight_residues: list of int, optional :param sort_by_value: Whether to sort residues by value. :type sort_by_value: bool, default=False :param ax: Existing axes to plot on. :type ax: Axes, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:class:: LogoGridPlotter Bases: :py:obj:`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. .. seealso:: :py:obj:`MetricsAnalysis` Generates per-residue metric data :py:obj:`ResidueMetricsPlotter` Bar/scatter visualization .. py:attribute:: name :value: 'logo_grid' .. py:attribute:: required_analysis :value: 'metrics' .. py:attribute:: description :value: 'Grid-based residue logo plot with amino acid annotations' .. py:method:: validate_result(result: prolint.analysis.base.AnalysisResult) -> None :classmethod: Validate that result contains residue metrics data. .. py:method:: 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: Optional[Tuple[float, float]] = None, highlight_residues: Optional[List[int]] = None) -> Tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] :classmethod: Create grid-based residue logo visualization. :param result: Result from metrics analysis. :type result: AnalysisResult :param colorscheme: Color scale name for value-based coloring. :type colorscheme: str, default="prolint" :param residues_per_row: Number of residue cells per row. :type residues_per_row: int, default=80 :param cell_size: Size of each cell in inches. :type cell_size: float, default=0.3 :param title: Plot title. :type title: str, default="Residue Logo Plot" :param figsize: Figure dimensions (width, height). Auto-calculated if None. :type figsize: tuple of (float, float), optional :param highlight_residues: Residue IDs to highlight with colored borders. :type highlight_residues: list of int, optional :returns: Matplotlib figure and axes objects. :rtype: tuple of (Figure, Axes) .. py:function:: write_pdb(contacts, metric: Literal['mean', 'max', 'sum', 'occupancy'] = 'occupancy', target_resname: Optional[str] = None, filename: Optional[str] = None, frame: int = 0) -> str 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. :param contacts: Computed contact data. :type contacts: ComputedContacts :param metric: Metric to write to B-factor column. :type metric: {"mean", "max", "sum", "occupancy"}, default="occupancy" :param target_resname: Filter by database residue name (e.g., "CHOL"). :type target_resname: str, optional :param filename: Output filename. If None, creates a temporary file. :type filename: str, optional :param frame: Trajectory frame to use for coordinates. :type frame: int, default=0 :returns: Path to the written PDB file. :rtype: str .. rubric:: Examples >>> from prolint.plotting import write_pdb >>> pdb_path = write_pdb(contacts, metric="occupancy") >>> # Open in PyMOL/VMD and color by B-factor