Skip to content

Latest commit

 

History

History
299 lines (213 loc) · 10.3 KB

README.md

File metadata and controls

299 lines (213 loc) · 10.3 KB
Raw

PyMOLProbity

A MOLProbity 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, but briefly, the easiest way to get Open Source PyMOL installed is probably to use a Package Manager.

On Debian/Ubuntu, for example:

apt-get install pymol

On a Mac, Homebrew is a good option. Install XQuartz if you don't have it already (this can be done without Homebrew, but Homebrew Cask simply automates the downloading and running of the installer:

brew install Caskroom/cask/xquartz

and then PyMOL:

brew install homebrew/science/pymol

Homebrew's PyMOL formula requires Python to be installed --with-tcl-tk and Tcl/Tk to be installed --with-threads --with-x11, so if you've already installed either of those with Homebrew, you'll have to unlink and reinstall them.

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.

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
  1. 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.

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 software page. 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 MacPyMOL if you use the X11 hybrid tweak, which entails simply renaming or copying MacPyMOL.app to PyMOLX11Hybrid.app in your Applications folder.)

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://raw.githubusercontent.com/jaredsampson/pymolprobity/master/pymolprobity.tar.gz

Confirm you wish to proceed with the download and the plugin will be installed automatically. Alternatively, you can download the zipped plugin archive file and select it using the file chooser.

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:

source activate mp

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.

Authors

Primary Author

Contributors

  • Thomas Holder - code for the "quad" dots visualization style.

License

This project is licensed under the MIT License - see LICENSE.md for details

Acknowledgments

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, Thomas Holder, Blaine Bell, and Gabriel Marques, for their help, guidance, 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.