PyMOLProbity

A MolProbity-style visualization plugin for PyMOL

The PyMOLProbity plugin allows a PyMOL user to produce MolProbity-style visualization of atomic interactions within a structure (e.g. H-bonds, van der Waals interactions and clashes) directly within a PyMOL session. The plugin runs local copies of several executable programs from the Richardson Lab at Duke University, authors of the MolProbity software, parses the output, and displays the results in the PyMOL viewport. There are both a graphical user interface (GUI) for general point-and-click use, and a command-line interface (CLI) suitable for scripting.

Getting Started

Linux/MacOS only

Because the Reduce, Probe, and Prekin executables are only available for Linux and MacOS, unfortunately PyMOLProbity is not currently useful on Windows. However, if there is sufficient demand, it wouldn't be too difficult to add support to read PDB and Kinemage files generated by the MolProbity server and downloaded to the local filesystem. Please submit a feature request if this interests you.

Prerequisites

PyMOL

To use this PyMOL plugin, of course you will need to have PyMOL installed on your machine. Incentive PyMOL users can download precompiled binaries; for those who don't have an Incentive PyMOL license, there is Open Source PyMOL. Detailed instructions are available via the PyMOL Wiki.

Only PyMOL v2.0 or later is supported.

MolProbity programs

To work properly, PyMOLProbity requires 4 programs from the MolProbity software package: Reduce, Probe, Flipkin (actually a Perl script), and Prekin, which are available from the Richardson Lab Github account. There are two general ways to satisfy these requirements.

1. With PHENIX. If you have PHENIX installed and properly configured, you already have Reduce and Probe available as phenix.reduce and phenix.probe, so you only need Flipkin and Prekin.

• Direct download links (right click, Save as...):
• Flipkin: PHENIX-compatible version
• Prekin: Linux (64-bit), Linux (32-bit), MacOS

You will need to create either aliases or symlinks to the phenix.xxx executables so PyMOLProbity can find them by calling reduce and probe from the shell. For example, the following added to ~/.bashrc should be sufficient in most cases.

alias reduce=phenix.reduce
alias probe=phenix.probe

2. Without PHENIX. If you do not wish to install PHENIX, you'll need to download all 4 programs. Note that the appropriate Flipkin in this case is an older version of the script, as the latest version specifies phenix.reduce and phenix.probe explicitly.

• Direct download links (right click, Save as...):
• Reduce: Linux, MacOS
• Probe: Linux, MacOS
• Flipkin: Non-PHENIX version
• Prekin: Linux (64-bit), Linux (32-bit), MacOS

Place the downloaded files in a directory on the shell PATH such as /usr/local/bin and make sure they are executable:

cd /usr/local/bin
chmod +x flipkin prekin probe reduce

You may also wish to download the Richardson group's "slightly modified version of the connectivity table published by the PDB" from the Reduce GitHub repo, reduce_wwPDB_het_dict.txt. This file should be placed in /usr/local. If you don't, you'll probably get the following error when you run Reduce:

ERROR CTab(/usr/local/reduce_wwPDB_het_dict.txt): could not open

Installation

Installation of PyMOLProbity itself should be straightforward using PyMOL's Plugin Manager. (Mac users note: Plugins are only available for 1.x versions of MacPyMOL if you use the X11 hybrid tweak, which entails simply renaming or copying MacPyMOL.app to PyMOLX11Hybrid.app in your Applications folder. For PyMOL version 2.0 and newer, plugins are built-in and you will not need to do this.)

Launch PyMOL, open the Plugin Manager from the menu (Plugin > Plugin Manager), and navigate to the Install New Plugin tab. Paste the following URL into the URL box and click Fetch.

https://github.com/jaredsampson/pymolprobity/archive/master.zip

Confirm you wish to proceed with the download and the plugin will be installed automatically. Alternatively, or if the URL method fails, you can download the zipped plugin archive file (or a specific version, if desired) and select it using the file chooser.

Note: If you are using PyMOL version earlier than 2.3.3, the URL-based option above will fail due to the presence of thpe tests directory, so you will need to download the master.zip file from the link above, unzip it, delete the tests directory, and re-zip the file. This can all be done via the following bash commands:

curl -o pymolprobity-master.zip -O https://github.com/jaredsampson/pymolprobity/archive/master.zip \
    && unzip pymolprobity-master.zip \
    && rm -r pymolprobity-master/tests \
    && rm pymolprobity-master.zip \
    && zip -r pymolprobity-master.zip pymolprobity-master

One final step is required if you are using an incentive build and launching from an app icon rather than from the terminal. You will need to ensure that the path to the Reduce/Probe executables is included in the shell PATH within the PyMOL app environment. This can be done by editing your pymolrc file via File > Edit pymolrc and adding the following lines, changing the path to point to the actual location of your MolProbity programs if you have not used /usr/local/bin.

# for PyMOLProbity plugin, path to reduce/probe/flipkin/prekin executables
import os
os.environ['PATH'] += os.pathsep + '/usr/local/bin'

First run

Now you can open PyMOL, load or fetch a structure, and launch PyMOLProbity from the Plugin menu. Use the Add Hydrogens tab to add hydrogens with Reduce. This will also calculate which N/Q/H residue side chains should be flipped. If you would like to examine these more closely, use the Review Flips tab to examine each flippable residue and choose the ones you wish to flip or keep. Save these using the Save Selections button. Finally, use the Visualize Contacts tab to run Probe on the modified coordinates and generate contact dots and clash vectors for all the atoms in your object.

Development

Users who wish to inspect or tinker with the code or contribute to development may wish to clone the repository.

git clone https://github.com/jaredsampson/pymolprobity.git
cd pymolprobity

Running the unit tests

A unit testing suite is included in the tests subdirectory.

Running the tests requires the Python packages nose, mock, and optionally coverage. If you have these installed already, you can skip this step; if not, run the following command to install the three packages and their dependencies using conda if available, and pip otherwise.

make init

In the case of conda, the packages will be created in a new environment called mp, which you should then activate with:

conda activate mp

and deactivate when you are finished with:

conda deactivate

virtualenv users can run make init from within an activated virtualenv to keep these packages out of your global Python environment as well.

Once nose and mock are installed, run the unit tests with

make test

To run the tests and determine code coverage:

make testcov

To see a full coverage report, including line numbers missed by the tests:

make cov

Troubleshooting

If you run the tests and get errors like:

ImportError: No module named pymol
ImportError: No module named chempy

it means your PyMOL installation's Python modules are not being found by Python. The easiest way to solve this (which is accounted for in the Makefile) is to set PYMOL_HOME in your ~/.bashrc file and start a new terminal session.

export PYMOL_HOME=/path/to/pymol-installation/libexec/lib/python2.7/site-packages

where /path/to/pymol-installation/bin/pymol is the absolute path to your PyMOL executable.

Contributing

For a closer look at the plugin, to run tests yourself, or to help improve this plugin, please feel free to clone or fork this repository. Bug reports and pull requests are definitely welcome!

Versioning

PyMOLProbity uses semantic versioning. For the versions available, see the [tags on this repository](https://