Pymol academic figures

PyMOL Academic Figures

Use PyMOL to make clean, reproducible molecular figures for papers, posters, talks, and reports. Prefer scripted .pml generation over manual GUI steps so figures can be regenerated after structure or style changes.

This skill is adapted for Codex from the PyMOL figure workflow in claudemol, with local command-line rendering added for this machine.

Local Environment

Use these commands directly:

pymol -cq figure.pml
claudemol --help

Known local paths:

C:\Users\dell\Downloads\PyMOL-3.1.6.1_appveyor2641-Win64-portable-py310\PyMOL\Scripts\pymol.exe
C:\Users\dell\Downloads\PyMOL-3.1.6.1_appveyor2641-Win64-portable-py310\PyMOL\pymol.cmd
C:\Users\dell\Downloads\PyMOL-3.1.6.1_appveyor2641-Win64-portable-py310\PyMOL\claudemol.cmd

For headless batch rendering, prefer:

python C:\Users\dell\.codex\skills\pymol-academic-figures\scripts\run_pymol_render.py --pml figure.pml --output figure.png

Workflow

1. Clarify the scientific message: binding site, conformational change, alignment, interaction network, surface property, mutation, epitope, or MD snapshot.
2. Identify the input: PDB ID, local .pdb/.cif, trajectory-derived snapshot, aligned structures, ligand/cofactor, or user-provided session.
3. Generate a .pml script with deterministic object names, selections, colors, camera, labels, image dimensions, and output path.
4. Render headlessly with run_pymol_render.py or pymol -cq.
5. Inspect the resulting PNG. Fix clipping, crowded labels, hidden ligand, low contrast, bad orientation, or excessive visual complexity.

Figure Standards

Default publication settings:

bg_color white
set ray_opaque_background, off
set antialias, 2
set ray_trace_mode, 1
set ray_shadows, off
set ambient, 0.35
set direct, 0.65
set spec_reflect, 0.15
set cartoon_fancy_helices, on
set cartoon_smooth_loops, on
set depth_cue, off
set orthoscopic, on

Use 2400 x 1800 for most single-panel figures. Use 3000 x 2400 or higher when labels or surfaces need extra room. Export transparent backgrounds only when the downstream layout needs it.

Visual Grammar

Use restrained color and representation:

• Protein overview: cartoon, one chain or domain per color.
• Binding site: protein cartoon muted, ligand sticks bright, nearby residues sticks, pocket surface semi-transparent if useful.
• Interaction network: show distances or hydrogen bonds only when they support the claim.
• Structure alignment: reference in gray, comparison in one accent color; avoid rainbow unless sequence position matters.
• MD snapshots: show representative conformers or clustered states, not a cluttered pile of frames.
• Labels: label only key residues, mutations, ligand, domains, or panels. Keep labels readable and sparse.

Avoid saturated rainbow defaults, unnecessary black outlines, overlapping labels, huge spheres unless atom identity matters, and screenshots from the PyMOL viewport when a script can render the same view.

Common Recipes

Read references/figure-recipes.md for copyable PyMOL snippets:

• publication setup block
• protein-ligand binding site
• hydrogen bonds and contacts
• surface plus ligand pocket
• structure alignment
• MD snapshot figure
• transparent PNG export

Execution Notes

When a user asks for a figure, create files in the current workspace unless they specify an output directory. Name files clearly, for example binding_site_1abc.pml and binding_site_1abc.png.

If PyMOL rendering fails, report the exact error and check:

• input path exists and has no problematic spaces without quotes
• object/selection names are valid
• output directory exists
• the script ends with png ... and quit
• PyMOL can run pymol -cq

If the user asks for an interactive PyMOL control flow, use claudemol launch, claudemol status, and claudemol exec only after verifying PyMOL is running. For reproducible figures, prefer .pml scripts.