How to Align PDB Protein Structures with PyMOL and Interpret RMSD Correctly

Table of contents

• Scientific introduction
  • What structural alignment actually does
  • The PyMOL align algorithm
  • Interpreting the exact return tuple
  • Official 1D3Z and 1UBQ provenance
  • RMSD mathematics and limitations
  • Transformed coordinates are a derived artifact
  • Rendering overlays without misleading readers
  • Choosing among alignment methods
  • Semantic validation and schema repair
• Test progress
• Demo user request
• Demo data
• Validated workflow
• Results and artifacts
• What attempts 1–6 repaired
• Designing a rigorous structural comparison
• Reproducibility
• Limitations
• References
• Try this workflow

PyMOL 3.1.0 aligned the official RCSB/PDBe 1D3Z ubiquitin NMR structure as the mobile object to the official RCSB 1UBQ X-ray ubiquitin structure as the target. The exact cmd.align return was [0.39735108613967896, 449, 5, 1.2869186401367188, 602, 381.0, 76]: refined RMSD 0.397351 Å across 449 atom pairs after five refinement cycles, versus 1.286919 Å across 602 atom pairs before outlier rejection; the raw alignment score was 381.0 and 76 residues were aligned. Attempt 6 also saved transformed mobile coordinates and a validated 1200 × 900 ray-traced overlay. This is a software-validated superposition of two ubiquitin coordinate sets, not proof that the structures are biologically interchangeable or that one experimental method is more accurate. Only PyMOL align was tested; super, cealign, flexible alignment, and other modes were not.

Scientific introduction

What structural alignment actually does

Protein structural alignment places two three-dimensional coordinate sets into a common frame so corresponding features can be compared. A rigid-body transformation consists of a rotation and translation; it changes the coordinate frame but not the internal geometry of the mobile object. The optimization typically seeks to minimize distances between paired atoms after establishing a correspondence. The resulting overlay can reveal conserved folds, local deviations, alternate conformations, domain motions, or modeling differences.

“Alignment” combines two distinct problems. The first is correspondence: which residue or atom in one structure should be paired with which item in the other? The second is superposition: what rigid transformation best overlays the selected pairs? Sequence identity makes correspondence easier but does not eliminate complications caused by missing residues, alternate locations, multiple models, mutations, insertion codes, ligands, or different atom content.

An RMSD value only has meaning with its atom selection, correspondence, refinement rule, and units. A low backbone RMSD over a small conserved core can coexist with large differences elsewhere. A higher all-atom RMSD may reflect side-chain rotamers rather than a changed global fold. Reporting one number without the aligned count and selection invites overinterpretation.

The PyMOL align algorithm

PyMOL’s align command performs a sequence alignment followed by structural superposition and iterative refinement. The command is convenient for proteins with meaningful sequence similarity. It can reject outlier atom pairs over refinement cycles, reducing the RMSD of the retained core. That means the post-refinement RMSD and atom count must be read together: a lower value partly reflects removal of discordant pairs.

The official PyMOL command documentation describes a seven-element return: RMSD after refinement, number of aligned atoms after refinement, number of refinement cycles, RMSD before refinement, number of aligned atoms before refinement, raw alignment score, and number of aligned residues. The retained tuple follows that order exactly. It should not be converted into a custom schema unless every position is mapped correctly.

The input selection in this test is the complete mobile object against the complete target object. PyMOL chooses correspondences through its align behavior, refines for five cycles, transforms the mobile coordinates in memory, then saves the transformed mobile PDB. The target remains the reference frame.

Interpreting the exact return tuple

The first value, 0.39735108613967896, is the RMSD in ångströms after refinement. The second, 449, is the number of atom pairs retained for that refined RMSD. The third value records five refinement cycles. The fourth and fifth values, 1.2869186401367188 and 602, describe RMSD and atom-pair count before refinement. Thus 153 pairs were not retained in the final refined set.

The sixth value, 381.0, is PyMOL’s raw alignment score. It is not an atom count and should not be reported in ångströms. The seventh value, 76, is the number of aligned residues. These types and positions are important because plausible but incorrectly labeled JSON can survive superficial review.

The post-refinement RMSD being lower than the pre-refinement value is consistent with iterative outlier rejection. It does not show that discarded regions are unimportant. For studies of flexible loops, binding sites, or conformational switching, the rejected pairs may contain the biology of interest. The transformed PDB and overlay should be inspected alongside residue-level or domain-specific comparisons.

Official 1D3Z and 1UBQ provenance

Both input files come from official structural archives. Entry 1D3Z is a human ubiquitin solution-NMR structure with ten models. Its header describes validation using anisotropic carbonyl chemical shifts in a dilute liquid-crystalline phase. Entry 1UBQ is a human ubiquitin X-ray diffraction structure refined at 1.8 Å resolution. Source URLs and PDBe fallbacks are retained in sources.json.

The test treats 1D3Z as mobile and 1UBQ as target. A multi-model PDB requires an explicit policy. PyMOL’s loading and alignment behavior determines which states participate in the command, and the saved mobile file can retain transformed coordinate content. A production analysis should state the model or state selection instead of assuming all readers infer it from the filename.

Ubiquitin is highly conserved and both entries represent the same protein, making the pair suitable for a functional superposition test. This does not turn the resulting RMSD into a comparison of NMR versus crystallography quality. Experimental structures are supported by different observations, models, restraints, refinement procedures, and environmental conditions. Differences may arise from genuine conformational variation, coordinate uncertainty, crystal packing, ensemble representation, or file handling.

RMSD mathematics and limitations

For N paired coordinates after optimal superposition, RMSD is the square root of the mean squared Euclidean distance. A least-squares rigid fit can be obtained using methods such as the Kabsch algorithm, which finds the rotation minimizing the sum of squared deviations after centering. RMSD has the same length unit as the coordinates, usually ångströms for PDB files.

RMSD is sensitive to selection and outliers. It scales with the distribution of deviations and can be dominated by a mobile domain or flexible terminus. It does not identify where differences occur. Two alignments with identical RMSD can have very different spatial patterns. It also does not provide a p-value or uncertainty by itself.

Complementary measures include per-residue displacement, distance-matrix differences, contact overlap, TM-score, local distance difference tests, torsion comparisons, and domain-specific fits. The appropriate measure depends on whether the question concerns global fold, active-site geometry, interface conservation, model quality, or conformational change.

Transformed coordinates are a derived artifact

The saved mobile-aligned.pdb contains 1D3Z coordinates after PyMOL applied the fitted transformation. It is useful for downstream visualization, distance calculation, figure creation, and reproducibility. It is not a new experimentally determined structure. Its provenance should point back to the original file, target, command, software version, and exact tuple.

Rigid transformation preserves internal pairwise distances within each state apart from serialization precision. If a saved coordinate file unexpectedly changes bond geometry, atom identity, occupancy, or B-factors, the workflow needs review. Downstream tools should not confuse transformed coordinates with the original archive deposition.

The validator reopens the transformed text and requires at least as many ATOM records as the 449 refined pairs. That check demonstrates a substantive output, but it does not independently reproduce every transformation matrix element. High-consequence workflows should save the matrix or session and verify selected distances after reload.

Rendering overlays without misleading readers

The native image uses marine for the mobile structure and orange for the target, displays cartoons, orients both objects, and ray traces a white-background PNG at 1200 × 900 pixels and 200 DPI. Distinct colors make overlap and deviations visible. The renderer output is checked through the PNG signature and dimensions.

A visually convincing overlay does not prove alignment quality. Thick cartoons can hide local differences, perspective can emphasize one region, and opaque objects can cover each other. Figures should include a legend or caption naming mobile and target, state the method, report both RMSDs and counts, and show close-ups when a local claim is made.

For publication, preserve vector or high-resolution raster output when possible and ensure colors remain distinguishable. The molecular overlay should be linked to machine-readable coordinates and statistics. A screenshot of a file explorer or raw JSON is not a substitute for presenting the structural result.

Choosing among alignment methods

PyMOL offers multiple structural-comparison commands. align is sequence-guided and appropriate for related proteins. super uses a different, more structure-oriented scoring and can be more robust for some divergent pairs. cealign implements combinatorial extension concepts for structural alignment. External methods such as TM-align, DALI, FATCAT, and others make different correspondence and flexibility assumptions.

No method is universally superior. Method choice should reflect sequence similarity, topology, domain architecture, expected flexibility, and the scientific question. Agreement between methods can increase confidence, while disagreement deserves inspection. This dossier validates only align; it must not imply that super, cealign, or external algorithms produced the same transformation.

Semantic validation and schema repair

The semantic validator opens the JSON, accepts only explicit aliases for the raw seven-value array, and checks tuple length. It verifies finite refined RMSD, requires it to be nonnegative and lower than the raw RMSD, requires a positive aligned atom count, opens the transformed PDB, checks PNG signature, and requires an image at least 800 × 600.

Attempts 1–5 all generated the correct scientific artifacts and the same raw tuple. They failed because the JSON stored that array under different keys while the then-current validator recognized fewer aliases. Some attempts also added derived labels; a raw array remained the stable authoritative evidence. Attempt 6 used align_return, which the repaired validator recognizes, and passed.

Supporting multiple named aliases is appropriate when they are unambiguous: raw_return_values, raw_align_return, alignment_return_values, alignment_return, align_return, return_values, and pymol_align_return. The validator does not scan arbitrary arrays or trust prose. This preserves fail-closed semantics while accommodating harmless naming variation.

Test progress

Demo user request

Use headless PyMOL 3.1.0 to align official data/1d3z.pdb as the mobile structure onto official data/1ubq.pdb as the target with align. Preserve the exact seven-value return, save transformed mobile coordinates as mobile-aligned.pdb, and render a 1200 × 900 ray-traced alignment-overlay.png with distinct colors. Report pre- and post-refinement RMSD and atom counts without claiming other alignment modes or biological equivalence.

This request states scientific roles, method, output, rendering, and interpretation boundaries. Canonical filenames allow deterministic semantic review.

Demo data

1d3z.pdb and 1ubq.pdb are official archive files. The first is a solution-NMR ubiquitin entry with ten models; the second is a 1.8 Å X-ray ubiquitin structure. sources.json records RCSB primary downloads and PDBe fallbacks.

Validated workflow

The installer solved a 156-package Linux AMD64 micromamba transaction for Python 3.11 and pymol-open-source. The measured 288,571,940 bytes stayed below the 500,000,000-byte ceiling. The environment and packages were retained after testing.

The script launched PyMOL headlessly, loaded 1D3Z as mobile and 1UBQ as target, called cmd.align("mobile", "target"), saved the transformed mobile object, configured the cartoon overlay, and ray traced the PNG. It wrote the exact tuple to JSON. Chat execution repeated the request, and the validator reopened all outputs.

official 1D3Z mobile + official 1UBQ target
  → PyMOL 3.1.0 sequence-guided align
  → iterative refinement and rigid mobile transformation
  → exact seven-value tuple
  → transformed mobile PDB
  → 1200 × 900 ray-traced overlay
  → semantic artifact validation

Transparent developer reproduction:

python test/scientific-skills/run_skill_cycle.py align-pdbs
python test/scientific-skills/skills/align-pdbs/chat_e2e.py
python test/scientific-skills/validate_how_to.py \
  test/scientific-skills/skills/align-pdbs

These commands expose the validation path; a structural biologist does not need to write them to request the analysis.

Results and artifacts

The refined result is 0.3973510861 Å over 449 atom pairs after five cycles, compared with 1.2869186401 Å over 602 pairs before refinement. PyMOL reports raw score 381.0 and 76 aligned residues. No confidence interval, biological effect, flexibility model, or cross-method consensus was calculated.

The focused application result reports the tuple and limitations rather than showing a prompt, file list, or raw editor.

The native 1200 × 900 overlay presents the transformed mobile and fixed target in distinct colors. The derived mobile-aligned.pdb and exact alignment-stats.json are retained.

The data-derived visual supports review; the JSON tuple is authoritative.

What attempts 1–6 repaired

Attempts 1 through 5 executed real headless PyMOL and produced the correct transformed PDB, image, and exact seven values. Their JSON keys varied: align_return, alignment_return, raw_align_return, return_values, and pymol_align_return appeared across runs. At each stage, the active validator did not yet recognize the emitted alias, so feature credit correctly remained false.

Attempt 6 again emitted align_return. The final validator had been repaired to recognize the bounded set of explicit semantic aliases. It then checked actual tuple semantics and reopened the outputs, producing the first complete pass. Correct artifacts from failed attempts remain diagnostic evidence, but this article sources attempt 6 only.

The history also warns against derived-field drift. The seven tuple positions must be interpreted using PyMOL documentation. A generated label that assigns 602 to raw score or 381 to aligned residues is wrong even if the underlying tuple is correct. Publication therefore quotes the exact array and maps its positions explicitly.

Designing a rigorous structural comparison

Before alignment, define the biological unit, model, chain, residue range, atom selection, and treatment of ligands or waters. Check sequence correspondence and missing residues. For NMR ensembles, decide whether to align every model, a representative model, or an ensemble average and explain why.

After global fitting, calculate per-residue deviations and inspect outliers rather than discarding them conceptually. Fit domains separately when hinge motion is plausible. Examine active sites, interfaces, secondary structures, and flexible termini under selections appropriate to the question.

Repeat with an independent method if the conclusion matters. Report method-specific scores and correspondence counts without forcing them into one metric. Save transformation matrices, selections, software versions, and exact source revisions. Structural similarity supports a hypothesis; function, dynamics, and mechanism require additional evidence.

Reproducibility

The evidence identifier is align-pdbs/attempt-6, validated on 2026-07-27. Execution used PyMOL 3.1.0, Python 3.11, Linux AMD64 CPU, and a solved 156-package transaction of 288,571,940 bytes. CUDA was not required or tested. The natural-language execution gate completed with the configured application runtime.

Reproduction requires the official 1D3Z and 1UBQ files, mobile/target direction, complete-object selections, default align settings, and exact tuple mapping. A changed structure revision, model selection, PyMOL version, method, or selection creates a new validation condition. Screenshot and visual manifests bind images to retained evidence with SHA-256.

Limitations

This demonstration compares two ubiquitin entries with PyMOL align. It does not benchmark alignment algorithms, quantify experimental uncertainty, assess function, or establish NMR/X-ray equivalence. The treatment of the multi-model 1D3Z file follows the tested PyMOL load behavior rather than an ensemble analysis.

Iterative refinement rejects atom pairs, so the 0.397 Å RMSD describes the retained 449-pair core, not all 602 initial pairs. Rejected regions may be scientifically important. The raw alignment score is method-specific.

PyMOL super, cealign, external structural alignment programs, flexible fitting, trajectories, ligands, multimers, Windows, macOS, ARM, and GPU modes were not validated.

References

• PyMOLWiki. Official-style align command reference and return-value ordering
• Schrodinger. PyMOL open-source repository
• RCSB Protein Data Bank. Official 1D3Z structure entry
• RCSB Protein Data Bank. Official 1UBQ structure entry
• Kabsch, W. “A solution for the best rotation to relate two sets of vectors.” Acta Crystallographica A 32, 922–923 (1976). DOI: 10.1107/S0567739476001873
• Zhang, Y. and Skolnick, J. “TM-align: a protein structure alignment algorithm based on the TM-score.” Nucleic Acids Research 33, 2302–2309 (2005). DOI: 10.1093/nar/gki524

Try this workflow

MindPlot has built-in support for the demonstrated Align-PDBs skill. A user can name mobile and target structures and request an evidence-qualified alignment in ordinary language; the MindPlot agent runs PyMOL, saves transformed coordinates and visual deliverables, and presents the validated result. Users do not need to write the reproduction commands above. Try it at https://mindplot.ai, or download the desktop version for a more integrated experience and stronger local-data privacy.