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.
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.
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.
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.
- With PHENIX. If you have PHENIX
installed and properly configured, you already have Reduce and Probe
available as
phenix.reduceandphenix.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
- 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.reduceandphenix.probeexplicitly.
- 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 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'
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.
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
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
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.
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!
PyMOLProbity uses semantic versioning. For the versions available, see the tags on this repository.
- Jared Sampson wrote this plugin as part of his 2014-2015 Warren L. DeLano PyMOL Open Source Fellowship, while working as a technician at NYU Langone Medical Center and then as a Ph.D. student at Columbia University.
- Thomas Holder - "quad" dots visualization style and a number of other improvements and bugfixes.
Please cite the PyMOLProbity plugin with the following information:
Sampson, Jared M. PyMOLProbity: a MolProbity-style visualization plugin for PyMOL, <version>. (<year>). <url>
where:
<version>is the version number for the release you used (e.g. v0.1.4);<year>is the date that release version was made available; and<url>is either:- the address of this repository on GitHub (https://github.com/jaredsampson/pymolprobity); or
- the DOI associated with the release, available on the releases page, or via this Zenodo record, which will always resolve to the latest release and display a list of available releases and DOIs.
For example, a BibTeX-formatted citation might look like this:
@software{pymolprobity,
author = {Sampson, Jared M.},
title = {PyMOLProbity: a MolProbity-style visualization plugin for PyMOL},
url = {https://github.com/jaredsampson/pymolprobity},
version = {0.1.4},
date = {2019-08-12},
}
Remember also that PyMOLProbity uses the Reduce, Probe, Flipkin and Prekin programs from the Richardson group's MolProbity package, so please cite those as well. Some relevant information may be found here.
This project is licensed under the MIT License - see LICENSE.md for details
The PyMOLProbity plugin was initially developed as part of my 2014-15 Warren L. DeLano Memorial PyMOL Open Source Fellowship. I would like to thank Schrodinger for sponsoring my POSF fellowship and opportunity to work on this software. Specifically, I am grateful to the PyMOL developers for their help and patience.
Additional thanks go to David and Jane Richardson and members of the Richardson Lab for providing the MolProbity software and server and the programs on which this plugin depends, and to Bradley Hintze and Christopher Williams in particular for their help in answering questions I had about the programs.