pymolprobity

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #typescript #android #rust #linux #nodejs #java #cli #awesome-list #security #ios

(★ 16)

A MolProbity-style visualization plugin for PyMOL

pymolprobity Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

[PyMOL]: http://www.pymol.org/
  [Richardson Lab]: http://kinemage.biochem.duke.edu/
  [MolProbity]: http://molprobity.biochem.duke.edu/

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

[feature request]: https://github.com/jaredsampson/pymolprobity/issues

### 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][].

[PyMOL Wiki]: http://www.pymolwiki.org/index.php/Category:Installation

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

[Github account]: https://github.com/rlabduke

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][fkp]
  * Prekin: [Linux (64-bit)][pkl64], [Linux (32-bit)][pkl32], [MacOS][pkm]

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
  ```

[PHENIX]: http://www.phenix-online.org/

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][rl], [MacOS][rm]
  * Probe: [Linux][pl], [MacOS][pmac]
  * Flipkin: [Non-PHENIX version][fkold]
  * Prekin: [Linux (64-bit)][pkl64], [Linux (32-bit)][pkl32], [MacOS][pkm]

[rl]: https://github.com/rlabduke/MolProbity/raw/master/bin/linux/reduce
  [rm]: https://github.com/rlabduke/MolProbity/raw/master/bin/macosx/reduce
  [pl]: https://github.com/rlabduke/MolProbity/raw/master/bin/linux/probe
  [pmac]: https://github.com/rlabduke/MolProbity/raw/master/bin/macosx/probe
  [fkp]: https://raw.githubusercontent.com/rlabduke/MolProbity/master/bin/flipkin
  [fkold]: https://github.com/rlabduke/MolProbity/raw/4f09d8a7e888d865fecec99a9b7338303b0cbc51/bin/flipkin
  [pkl64]: https://github.com/rlabduke/MolProbity/raw/master/bin/linux/prekin_64
  [pkl32]: https://github.com/rlabduke/MolProbity/raw/master/bin/linux/prekin_32
  [pkm]: https://github.com/rlabduke/MolProbity/raw/master/bin/macosx/prekin

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][rp], `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:

[rp]: https://github.com/rlabduke/reduce/raw/master/reduce_wwPDB_het_dict.txt

```
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][pm].  (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.)

[pm]: http://www.pymolwiki.org/index.php/Plugin_Manager
  [tweak]: http://www.pymolwiki.org/index.php/Plugins#Plugins_on_OS_X

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.

[download]: https://github.com/jaredsampson/pymolprobity/archive/master.zip
  [version]: https://github.com/jaredsampson/pymolprobity/releases

*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](http://semver.org/). For the versions
available, see the [tags on this
repository](https://github.com/jaredsampson/pymolprobity/tags).

## Authors

### Primary Author

* **Jared Sampson** wrote this plugin as part of his 2014-2015 [Warren L.
  DeLano PyMOL Open Source Fellowship][posf], while working as a technician at
  [NYU Langone Medical Center][nyu] and then as a Ph.D. student at [Columbia
  University][cu].

[posf]: http://www.pymol.org/fellowship/
  [nyu]: http://www.med.nyu.edu/
  [cu]: http://www.columbia.edu/

### Contributors

* **Thomas Holder** - "quad" dots visualization style and a number of other
  improvements and bugfixes.

## Citing PyMOLProbity

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][releases] 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.

[releases]: https://github.com/jaredsampson/pymolprobity/releases
  [record]: https://zenodo.org/record/3366407

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][mpabout].

[mpabout]: http://molprobity.biochem.duke.edu/help/about.html

## License

This project is licensed under the MIT License - see [LICENSE.md](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][posf].  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.

[Schrodinger]: http://www.schrodinger.com/

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.

pymolprobity

pymolprobity Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pymolprobity

pymolprobity Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README