Plots API Reference

Time Series

mdpp.plots.timeseries

Time-series and per-residue plotting helpers.

plot_rmsd(result, *, ax=None, label=None, linewidth=1.5, alpha=1.0, color=None, moving_average=None, ma_linewidth=2.0)

Plot RMSD as a function of time.

Parameters:

Name	Type	Description	Default
result	RMSDResult	RMSDResult from compute_rmsd.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
linewidth	float	Line width for the raw trace.	1.5
alpha	float	Opacity of the raw trace (0.0 -- 1.0).	1.0
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None
moving_average	int | None	If set, overlay a moving-average line computed with a centered window of this many frames.	None
ma_linewidth	float	Line width for the moving-average overlay.	2.0

Returns:

Type	Description
Axes	The matplotlib axis.

plot_rmsf(result, *, ax=None, label=None, linewidth=1.5, alpha=1.0, color=None)

Plot per-atom RMSF.

Parameters:

Name	Type	Description	Default
result	RMSFResult	RMSFResult from compute_rmsf.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
linewidth	float	Line width.	1.5
alpha	float	Opacity of the trace (0.0 -- 1.0).	1.0
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_rmsf_average(results, *, ax=None, label='average', linewidth=2.0, color=None, show_sem=True, sem_alpha=0.2)

Plot the average RMSF from multiple replicas with optional SEM band.

Averaging is done in MSF (mean-square fluctuation) space: the per-residue RMSF^2 values are averaged across replicas, then the square root is taken. This is the physically correct way to combine RMSF values because RMSF is the square root of a variance-like quantity.

The error band is propagated consistently through the same transformation. Given avg_rmsf = sqrt(mean(MSF)), the SEM on the MSF is propagated through the square root via sem_rmsf = sem_msf / (2 * avg_rmsf).

Parameters:

Name	Type	Description	Default
results	list[RMSFResult]	List of RMSFResult objects (one per replica). All must have the same number of atoms.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str	Legend label for the average line.	'average'
linewidth	float	Line width.	2.0
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None
show_sem	bool	If True, draw a transparent band showing +/- 1 SEM around the average. Requires at least 2 replicas.	True
sem_alpha	float	Opacity of the SEM band (0.0 -- 1.0).	0.2

Returns:

Type	Description
Axes	The matplotlib axis.

Raises:

Type	Description
ValueError	If results is empty or RMSF arrays differ in length.

plot_sasa(result, *, ax=None, label=None, aggregate='sum', linewidth=1.5, color=None)

Plot SASA over time.

Parameters:

Name	Type	Description	Default
result	SASAResult	SASAResult from compute_sasa.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
aggregate	str	Aggregation mode: "sum", "mean", or "none". When "none", each atom/residue trace uses the property cycle and the color parameter is ignored.	'sum'
linewidth	float	Line width for plotted traces.	1.5
color	str | None	Optional line color for "sum" and "mean" aggregation. Ignored when aggregate="none" (multiple traces use the property cycle). Defaults to matplotlib's next color.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_hbond_counts(result, *, ax=None, label=None, linewidth=1.5, color=None)

Plot hydrogen-bond count over time.

Parameters:

Name	Type	Description	Default
result	HBondResult	HBondResult from compute_hbonds.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
linewidth	float	Line width.	1.5
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_hbond_occupancy(result, *, ax=None, labels=None, top_n=None)

Plot per-bond occupancy as a bar plot.

Parameters:

Name	Type	Description	Default
result	HBondResult	HBondResult from compute_hbonds.	required
ax	Axes | None	Optional matplotlib axis.	None
labels	list[str] | None	Optional labels corresponding to result.triplets.	None
top_n	int | None	Optional number of highest-occupancy bonds to display.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_radius_of_gyration(result, *, ax=None, label=None, linewidth=1.5, color=None)

Plot radius of gyration over time.

Parameters:

Name	Type	Description	Default
result	RadiusOfGyrationResult	RadiusOfGyrationResult from compute_radius_of_gyration.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
linewidth	float	Line width.	1.5
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_distances(result, *, ax=None, pair_labels=None, linewidth=1.5)

Plot pairwise distances over time.

Parameters:

Name	Type	Description	Default
result	DistanceResult	DistanceResult from compute_distances or compute_minimum_distance.	required
ax	Axes | None	Optional matplotlib axis.	None
pair_labels	list[str] | None	Optional labels for each distance pair.	None
linewidth	float	Line width.	1.5

Returns:

Type	Description
Axes	The matplotlib axis.

plot_native_contacts(result, *, ax=None, label=None, linewidth=1.5, color=None)

Plot fraction of native contacts Q(t) over time.

Parameters:

Name	Type	Description	Default
result	NativeContactResult	NativeContactResult from compute_native_contacts.	required
ax	Axes | None	Optional matplotlib axis.	None
label	str | None	Optional legend label.	None
linewidth	float	Line width.	1.5
color	str | None	Optional line color. Defaults to matplotlib's next color in the property cycle.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_energy(data, *, columns=None, time_column=None, ax=None, linewidth=1.5)

Plot energy terms from a parsed XVG or EDR DataFrame.

Parameters:

Name	Type	Description	Default
data	DataFrame	DataFrame as returned by read_xvg or read_edr.	required
columns	list[str] | None	Column names to plot. If None, plots all non-time columns.	None
time_column	str | None	Name of the time column. Auto-detected if None (looks for "Time" or the first column).	None
ax	Axes | None	Optional matplotlib axis.	None
linewidth	float	Line width.	1.5

Returns:

Type	Description
Axes	The matplotlib axis.

plot_delta_rmsf(result, *, ax=None, labels=('system A', 'system B'), positive_color='crimson', negative_color='steelblue', linewidth=1.5, sem_alpha=0.3)

Plot per-residue RMSF difference as a colored line with SEM band.

The line and SEM band are colored per-residue: positive_color where delta > 0 (system B more flexible) and negative_color where delta < 0 (system A more flexible).

Parameters:

Name	Type	Description	Default
result	DeltaRMSFResult	DeltaRMSFResult from compute_delta_rmsf.	required
ax	Axes | None	Optional matplotlib axis.	None
labels	tuple[str, str]	Tuple of (system_a_name, system_b_name) used in the legend (e.g. ("BirA", "TurboID")).	('system A', 'system B')
positive_color	str	Color for residues where system B is more flexible (delta > 0).	'crimson'
negative_color	str	Color for residues where system A is more flexible (delta < 0).	'steelblue'
linewidth	float	Line width for the delta-RMSF trace.	1.5
sem_alpha	float	Opacity of the SEM band (0.0 -- 1.0).	0.3

Returns:

Type	Description
Axes	The matplotlib axis.

Matrix

mdpp.plots.matrix

Matrix-like plotting helpers.

plot_dccm(result, *, ax=None, vmin=-1.0, vmax=1.0, cmap='RdBu_r', add_colorbar=True)

Plot a dynamic cross-correlation matrix as a heatmap.

Parameters:

Name	Type	Description	Default
result	DCCMResult	DCCMResult from compute_dccm.	required
ax	Axes | None	Optional matplotlib axis.	None
vmin	float	Minimum value for the color scale.	-1.0
vmax	float	Maximum value for the color scale.	1.0
cmap	str	Colormap name.	'RdBu_r'
add_colorbar	bool	Whether to add a colorbar.	True

Returns:

Type	Description
Axes	The matplotlib axis with the DCCM heatmap.

Free Energy Surface

mdpp.plots.fes

Free-energy surface plotting helpers.

plot_fes(result, *, ax=None, cmap='coolwarm', add_colorbar=True, add_contours=True, contour_levels=12)

Plot a 2D free-energy surface.

Parameters:

Name	Type	Description	Default
result	FES2DResult	FES2DResult from compute_fes_2d.	required
ax	Axes | None	Optional matplotlib axis.	None
cmap	str	Colormap name.	'coolwarm'
add_colorbar	bool	Whether to add a colorbar.	True
add_contours	bool	Whether to overlay contour lines.	True
contour_levels	int	Number of contour levels.	12

Returns:

Type	Description
Axes	The matplotlib axis with the FES plot.

Scatter

mdpp.plots.scatter

Scatter plot helpers for projections and torsion analysis.

plot_projection(result, *, x_index=0, y_index=1, color_by=None, cmap='viridis', ax=None, s=5.0, alpha=0.6, add_colorbar=True)

Plot a 2D scatter of projected coordinates (PCA or TICA).

Parameters:

Name	Type	Description	Default
result	PCAResult | TICAResult	PCAResult or TICAResult containing projections.	required
x_index	int	Component index for the x-axis.	0
y_index	int	Component index for the y-axis.	1
color_by	ArrayLike | None	Optional array to color points by (e.g. time or cluster labels). Must have length equal to the number of samples.	None
cmap	str	Colormap name when color_by is provided.	'viridis'
ax	Axes | None	Optional matplotlib axis.	None
s	float	Marker size.	5.0
alpha	float	Marker transparency.	0.6
add_colorbar	bool	Whether to add a colorbar when color_by is used.	True

Returns:

Type	Description
Axes	The matplotlib axis with the scatter plot.

plot_ramachandran(torsions, *, ax=None, s=3.0, alpha=0.3, color='tab:blue')

Plot a Ramachandran diagram from backbone torsion features.

Expects torsions to have been computed with sincos_embedding=False so that raw phi/psi angles (in radians) are available.

Parameters:

Name	Type	Description	Default
torsions	TorsionFeatures	TorsionFeatures from featurize_backbone_torsions with sincos_embedding=False.	required
ax	Axes | None	Optional matplotlib axis.	None
s	float	Marker size.	3.0
alpha	float	Marker transparency.	0.3
color	str	Marker color.	'tab:blue'

Returns:

Type	Description
Axes	The matplotlib axis with the Ramachandran plot.

Raises:

Type	Description
ValueError	If phi and psi angles cannot be identified from labels.

plot_pca_scree(*results, labels=None, colors=None, ax=None)

Plot a scree plot (variance explained per principal component).

Multiple PCA results can be overlaid as grouped bars for comparison.

Parameters:

Name	Type	Description	Default
*results	PCAResult	One or more PCAResult objects.	()
labels	list[str] | None	Optional legend labels, one per result.	None
colors	list[str] | None	Optional bar colors, one per result.	None
ax	Axes | None	Optional matplotlib axis.	None

Returns:

Type	Description
Axes	The matplotlib axis.

plot_pca_cumulative_variance(*results, labels=None, colors=None, thresholds=None, ax=None)

Plot cumulative explained variance as a function of the number of PCs.

Parameters:

Name	Type	Description	Default
*results	PCAResult	One or more PCAResult objects.	()
labels	list[str] | None	Optional legend labels, one per result.	None
colors	list[str] | None	Optional line colors, one per result.	None
thresholds	list[float] | None	Optional horizontal reference lines (e.g. [80, 90] for 80% and 90% thresholds). Drawn as dashed gray lines.	None
ax	Axes | None	Optional matplotlib axis.	None

Returns:

Type	Description
Axes	The matplotlib axis.

Contacts

mdpp.plots.contacts

Contact map visualization helpers.

plot_contact_map(frequency, *, residue_ids=None, ax=None, cmap='hot_r', vmin=0.0, vmax=1.0, add_colorbar=True)

Plot a residue-residue contact frequency heatmap.

Parameters:

Name	Type	Description	Default
frequency	NDArray[floating]	Symmetric contact frequency matrix of shape (n_res, n_res) with values in [0, 1].	required
residue_ids	NDArray[int_] | None	Optional residue IDs for axis labels.	None
ax	Axes | None	Optional matplotlib axis.	None
cmap	str	Colormap name.	'hot_r'
vmin	float	Minimum value for the color scale.	0.0
vmax	float	Maximum value for the color scale.	1.0
add_colorbar	bool	Whether to add a colorbar.	True

Returns:

Type	Description
Axes	The matplotlib axis with the contact map.

contact_frequency_to_matrix(frequency, residue_pairs, n_residues)

Convert per-pair contact frequencies to a symmetric matrix.

Parameters:

Name	Type	Description	Default
frequency	NDArray[floating]	Per-pair frequencies of shape (n_pairs,).	required
residue_pairs	NDArray[int_]	Residue index pairs of shape (n_pairs, 2).	required
n_residues	int	Total number of residues for the output matrix.	required

Returns:

Type	Description
NDArray[floating]	Symmetric matrix of shape (n_residues, n_residues) in the
NDArray[floating]	same floating dtype as frequency (float32 by default).

Molecules (2D)

mdpp.plots.molecules

Molecule structure drawing utilities using RDKit.

build_draw_options()

Create ACS 1996-style drawing options for crisp medicinal chemistry figures.

get_highlight_bonds(mol, atoms, pattern)

Return molecule bond indices corresponding to a matched pattern.

Parameters:

Name	Type	Description	Default
mol	Mol	Molecule containing the matched substructure.	required
atoms	Sequence[int]	Molecule atom indices matching the pattern atom order.	required
pattern	Mol	Pattern whose bonds should be mapped onto mol.	required

Returns:

Type	Description
list[int]	Bond indices in mol corresponding to bonds in pattern.

draw_mol(mol, *, pattern=None, img_size=(300, 300), highlight=True, highlight_color=_DEFAULT_HIGHLIGHT_COLOR)

Draw a single molecule as a PIL image.

Parameters:

Name	Type	Description	Default
mol	Mol	An RDKit molecule.	required
pattern	Mol | None	SMARTS pattern to align and highlight as a substructure.	None
img_size	tuple[int, int]	Image dimensions in pixels (width, height).	(300, 300)
highlight	bool	Highlight matched substructure atoms.	True
highlight_color	tuple[float, float, float, float]	RGBA highlight colour used for matched atoms and bonds.	_DEFAULT_HIGHLIGHT_COLOR

Returns:

Type	Description
Image	A PIL image.

draw_mols(mols, *, output_file=None, legends=None, pattern=None, mols_per_row=8, sub_img_size=(300, 300), highlight=True, highlight_color=_DEFAULT_HIGHLIGHT_COLOR)

Draw a grid of molecules as a PIL image.

Parameters:

Name	Type	Description	Default
mols	Sequence[Mol]	RDKit molecules to draw.	required
output_file	str | None	If given, save the image to this path.	None
legends	Sequence[str] | None	Per-molecule labels shown beneath each cell.	None
pattern	Mol | None	SMARTS pattern to align and highlight as a substructure.	None
mols_per_row	int	Number of molecules per grid row.	8
sub_img_size	tuple[int, int]	Size of each cell in pixels (width, height).	(300, 300)
highlight	bool	Highlight matched substructure atoms.	True
highlight_color	tuple[float, float, float, float]	RGBA highlight colour used for matched atoms and bonds.	_DEFAULT_HIGHLIGHT_COLOR

Returns:

Type	Description
Image | None	A PIL image, or None if drawing fails due to layout constraints.

3D Visualization

mdpp.plots.three_d

Interactive 3D visualization helpers for molecules and trajectories.

Heavy dependencies (rdkit, py3Dmol, nglview) are imported lazily inside the functions that need them so that importing this module does not require all three packages to be installed.

make_atom_labels_3d(mol, *, conformer_id=-1, atom_indices=None, text_fn=None, color_fn=None, base_style=None)

Build generic per-atom label specifications for view_mol_3d.

Parameters:

Name	Type	Description	Default
mol	Mol	Molecule to label.	required
conformer_id	int	RDKit conformer ID to use. -1 selects the default conformer.	-1
atom_indices	Sequence[int] | None	Optional subset of atom indices to label.	None
text_fn	Callable[[Atom], str] | None	Function that returns the label text for an atom.	None
color_fn	Callable[[Atom], str | None] | None	Optional function that returns a font color for an atom.	None
base_style	Mapping[str, object] | None	Optional py3Dmol label-style keys to apply to every label.	None

Returns:

Type	Description
list[dict[str, object]]	Label dictionaries consumable by view_mol_3d.

Raises:

Type	Description
ValueError	If the molecule has no conformer or text_fn is not provided.

view_mol_3d(mol, *, conformer_id=-1, width=800, height=400, style=None, labels=None, background_color='white', zoom_to=True, show=False)

Create an interactive py3Dmol viewer for an RDKit molecule.

Parameters:

Name	Type	Description	Default
mol	Mol	Molecule to visualize.	required
conformer_id	int	RDKit conformer ID to use. -1 selects the default conformer.	-1
width	int	Viewer width in pixels.	800
height	int	Viewer height in pixels.	400
style	Mapping[str, object] | None	py3Dmol style dictionary passed to setStyle.	None
labels	Sequence[Mapping[str, object]] | None	Sequence of label dictionaries. Each must contain text and exactly one of atom_index or position.	None
background_color	str	Viewer background color.	'white'
zoom_to	bool	Whether to call zoomTo() after loading content.	True
show	bool	Whether to call show() before returning the viewer.	False

Returns:

Type	Description
view	A configured py3Dmol viewer.

Raises:

Type	Description
ValueError	If the molecule has no conformer or any label spec is invalid.

view_traj_3d(traj, *, representations=None)

Create an interactive nglview widget for a trajectory or structure.

Parameters:

Name	Type	Description	Default
traj	Trajectory	MDTraj trajectory to visualize.	required
representations	Sequence[Mapping[str, object]] | None	Optional custom representations. If omitted, nglview's default display settings are used. If provided, they fully replace the default display.	None

Returns:

Type	Description
NGLWidget	A configured nglview widget.

Raises:

Type	Description
ValueError	If any representation dictionary is missing type.

Utilities

mdpp.plots.utils

Shared plotting utilities.

get_axis(ax)

Return the passed axis or create a new one.

Parameters:

Name	Type	Description	Default
ax	Axes | None	An existing matplotlib axis, or None to create a new figure.	required

Returns:

Type	Description
Axes	The provided axis or a freshly created one.