Creating Publication-Quality Images with PyMOL

PyMOL Scripting: Automate Your Molecular Graphics WorkflowPyMOL is a powerful molecular visualization tool widely used in structural biology, chemistry, and related fields. While the graphical interface is convenient for ad hoc visualization, scripting unlocks PyMOL’s full potential: reproducible workflows, batch processing of large datasets, automated figure generation, and integration with other analysis pipelines. This article covers why scripting matters, core scripting concepts, practical examples, best practices, and tips for building automated workflows.

Why script PyMOL?

• Reproducibility: Scripts record every command so figures and analyses can be exactly reproduced months or years later.
• Scalability: Process many structures or frames (e.g., MD trajectories) without manual repetition.
• Automation: Generate publication-ready images, rotate animations, and produce multiple views with consistent styling.
• Integration: Combine PyMOL with Python libraries (NumPy, Biopython, MDAnalysis) for richer analyses.

How PyMOL scripting works: two modes

1. Command-line scripting (PyMOL language): commands you type in the PyMOL console or put in a .pml file. These are rapid for common visualization tasks.
2. Python API scripting: import pymol or use pymol.cmd inside Python scripts. This is more flexible, allowing loops, conditionals, file I/O, and integration with other Python packages.

Example of a simple .pml command sequence:

fetch 1tup, async=0 hide everything show cartoon color blue, chain A ray 1200,900 png 1tup_cartoon.png 

Example of using the Python API inside a script:

from pymol import cmd cmd.fetch("1tup", async_=0) cmd.hide("everything") cmd.show("cartoon") cmd.color("blue", "chain A") cmd.ray(1200, 900) cmd.png("1tup_cartoon.png") 

Core scripting concepts and common commands

• Objects vs. selections: load structures as objects (e.g., myprot), then use named selections (e.g., ligand, helix) to target subsets.
• Representations: cartoon, surface, sticks, spheres, mesh, ribbon — combine them for clarity.
• Coloring: by chain, by secondary structure, by element, or custom palettes.
• Views: save_view / load_view or get_view / set_view to reproduce camera positions.
• Scenes: create scenes to store different views and states for animations or presentation.
• Ray tracing and rendering: ray for high-quality images; set ray_trace_mode, ambient, direct to tune lighting.
• Labels: label atoms, residues, or use pseudoatoms for annotations.
• Movie and animation: mset, util.mroll, mpng to export frames; combine into GIF/MP4 externally or via ffmpeg.

Practical examples

1. Batch render multiple PDBs with consistent style “`python from pymol import cmd import glob, os

pdb_files = glob.glob(“pdbs/*.pdb”) for pdb in pdb_files:

name = os.path.splitext(os.path.basename(pdb))[0] cmd.reinitialize() cmd.load(pdb, name) cmd.remove("resn HOH") cmd.hide("everything") cmd.show("cartoon", name) cmd.color("cyan", f"{name} and chain A") cmd.png(f"rendered/{name}.png", width=1600, height=1200, dpi=300, ray=1) 

2) Highlight ligand interactions and annotate distances ```python from pymol import cmd cmd.load("complex.pdb", "complex") cmd.select("lig", "resn LIG") cmd.show("sticks", "lig") cmd.show("surface", "complex and not resn HOH") cmd.select("nearby", "br. lig around 4") cmd.distance("d1", "lig", "nearby and name NZ") cmd.set("label_color", "yellow") cmd.label("nearby and name NZ", ""%s%d" % (resn, resi)") cmd.png("complex_ligand.png", 1200, 800, ray=1) 

1. Generate a rotating movie of the structure

   from pymol import cmd cmd.load("protein.pdb", "prot") cmd.show("cartoon") cmd.set("ray_shadows", 0) cmd.mset("1 x360") for i in range(360): cmd.turn("y", 1) cmd.png(f"frames/frame_{i:03d}.png", 800, 800, ray=1) # combine frames with ffmpeg: ffmpeg -framerate 30 -i frames/frame_%03d.png -c:v libx264 out.mp4 

Integrating PyMOL scripts into pipelines

• Run headless on servers: use pymol -cq script.py (on systems with an X server or using OSMesa for offscreen rendering).
• Use Conda to manage environments: install pymol-open-source or pymol-bundle depending on features needed.
• Combine with MDAnalysis or MDtraj to load trajectories and produce time-series visualizations or per-frame analyses.
• Use Jupyter notebooks for exploratory scripting and inline images (via png export or pymol2 bindings).

Best practices

• Reinitialize between files when batch-processing to avoid state carryover (cmd.reinitialize()).
• Save session files (.pse) or scripts that re-create scenes; avoid saving one-off manual tweaks only in the GUI.
• Parameterize scripts with argparse to pass filenames, output dirs, and styles without editing code.
• Version-control your scripts and include example PDBs and README for reproducibility.
• Keep rendering settings consistent (lighting, DPI, camera) across a figure set.

Troubleshooting common issues

• Ray rendering fails headless: try using OSMesa builds or run on a machine with an X server; reduce ray_trace_mode or use smaller image sizes to lower memory.
• Fonts/labels not appearing: ensure label_font is supported or use default fonts; confirm labels are enabled.
• Colors differ between versions: pin PyMOL version in your environment and document color maps used.

Advanced tips

• Create custom functions and plugins using the Python API to encapsulate complex tasks (e.g., map contouring + ligand placement).
• Use pseudoatoms for annotations like centroids or to attach labels to non-atom coordinates.
• Generate publication panels programmatically: render separate views for different representations and compose them with Pillow or matplotlib.
• For very high-quality images, render with POV-Ray via PyMOL’s POV export for advanced lighting and shading.

Short example: parameterized script with argparse

#!/usr/bin/env python3 import argparse from pymol import cmd parser = argparse.ArgumentParser() parser.add_argument("pdb", help="input PDB file") parser.add_argument("-o","--out", default="out.png") args = parser.parse_args() cmd.reinitialize() cmd.load(args.pdb, "m") cmd.hide("everything") cmd.show("cartoon", "m") cmd.color("slate", "m and chain A") cmd.png(args.out, 1600, 1200, ray=1) 

Conclusion

Scripting in PyMOL transforms it from an interactive viewer into a reproducible, automatable visualization engine. With a handful of scripting patterns—batch loading, consistent styling, scene management, and integration with Python tools—you can create scalable, publication-quality figures and movies while keeping your workflow reproducible and efficient. Start small: convert repetitive GUI steps into scripts, then gradually introduce parameterization and integration with analysis libraries.