DistanceMatrix

DistanceMatrix is an educational PyMOL plugin for calculating and exploring two residue-level structure-comparison matrices:

• Aligned error (AE): after aligning the mobile structure on one residue, how far apart are the corresponding residues elsewhere?
• Distance error (DE): how much does each pairwise residue distance differ between the two structures?

These observed errors illustrate the quantities estimated by predicted aligned error (PAE) and predicted distance error (PDE) in structure-prediction systems.

Development has included coding assistance from OpenAI's Codex.

Installation

Download the source ZIP file and use the PyMOL "Plugin Manager" to install the plugin. Alternatively, clone this repository into a folder on PyMOL's plugin search path. Runtime dependencies are NumPy (typically included in PyMOL) and Matplotlib.

Open the plugin from Plugin → DistanceMatrix….

For development, create or update the included environment with:

uv sync

Workflow

1. Load two structures as separate PyMOL objects.
2. Choose a Reference and a distinct Mobile object.
3. DistanceMatrix reads the active PyMOL state and calculates the matrices.
4. Check the reported number of valid residue pairs.
5. Open Plot AE or Plot DE.

The Palette control offers a curated set of Matplotlib colormaps, and rev reverses the selected map. Min and Max set the heatmap color range in Å. Leave either limit blank to use its automatic value. Open plots update immediately when these settings change.

The plots support:

• Hovering to display the matrix value and complete row/column residue identities.
• Left-clicking or dragging to replace the managed reference selection, dm_plot_selection. A rectangle selects the union of its row and column residues.
• In the AE plot, Cmd-click (macOS) or Ctrl-click (other platforms) aligns the complete mobile object on the row residue and displays the column Cα distance as dm_ae_distance. Cyan reference and orange mobile overlays show the row N/Cα/C alignment frame as sticks and the measured column Cα atoms as spheres. Reference overlays are labeled with their row or column token and residue identity. PyMOL zooms to the completed highlight group after each AE action.
• Matplotlib pan and zoom modes temporarily disable these custom interactions.

Every AE action starts from the coordinates captured by the current calculation, so repeated actions do not accumulate transformations. Use Recalculate after changing atoms, alternate locations, object state, or topology outside the plugin. Selecting another object automatically resets the session and recalculates. Changing object selections does not restore a previously moved mobile object.

AE overlays and the distance persist when the matrix plot is closed. The next AE action deletes and recreates the complete highlight group, while recalculation, an object change, or closing the main plugin dialog removes it. These overlays are copies, so DistanceMatrix does not change the source objects' colors, representations, labels, or normal selections.

DistanceMatrix reserves the following PyMOL names for its visualization state:

• dm_plot_selection;
• dm_ae_highlights, which contains dm_ae_distance and the four overlays;
• dm_ae_row_reference and dm_ae_row_mobile;
• dm_ae_column_reference and dm_ae_column_mobile.

Pairing rules

Only non-HETATM atoms returned by PyMOL's polymer.protein selection are considered. Reference and mobile residues pair only when all of these fields match exactly:

• chain ID;
• residue number;
• insertion code;
• residue name.

No sequence alignment or residue renumbering is performed. Both residues must have usable N, CA, and C atoms. Blank alternate locations are preferred over A; other alternates are ignored, and an unresolved duplicate backbone atom makes that residue invalid. Nucleic acids, hetero components, unmatched residues, and incomplete residues are excluded.

Definitions

For every valid row residue (i), a proper-rotation Kabsch fit maps its mobile N, CA, and C coordinates onto the reference backbone:

$$ x' = R_i x + t_i $$

Using Cα as the representative coordinate:

$$ AE_{ij} = \left|R_i m_j + t_i - r_j\right| $$

$$ DE_{ij} = \left|\left|m_i-m_j\right|-\left|r_i-r_j\right|\right| $$

AE is directional because each row defines a different alignment frame. DE is symmetric and has a zero diagonal. Both matrices are reported in Å.

This version compares only the current PyMOL state.

Development

uv run pytest
uv run ruff format --check .
uv run ruff check .
uv run mypy .