Skip to content

Commit

Permalink
Cleanup docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@aalexmmaldonado
aalexmmaldonado committed Nov 29, 2024
1 parent d9d3fa8 commit b595ce7
Show file tree
Hide file tree
Showing 3 changed files with 285 additions and 239 deletions.
291 changes: 52 additions & 239 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,267 +1,80 @@
# POVME 2.2.2
<h1 align="center">POVME</h1>

## 0. License: GNU General Public License version 3
<h4 align="center">Detect and characterize pockets from molecular simulations.</h4>

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
<p align="center">
<a href="https://github.com/durrantlab/POVME/actions/workflows/tests.yml">
<img src="https://github.com/durrantlab/POVME/actions/workflows/tests.yml/badge.svg" alt="Build Status ">
</a>
<a href="https://codecov.io/gh/durrantlab/POVME">
<img src="https://codecov.io/gh/durrantlab/POVME/branch/main/graph/badge.svg" alt="codecov">
</a>
<a href="https://github.com/durrantlab/POVME/blob/main/LICENSE.md" target="_blank">
<img src="https://img.shields.io/github/license/durrantlab/POVME" alt="License">
</a>
<a href="https://github.com/durrantlab/POVME/" target="_blank">
<img src="https://img.shields.io/github/repo-size/durrantlab/POVME" alt="GitHub repo size">
</a>
</p>

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.
POVME (POcket Volume MEasurer) is an open-source tool designed for detailed analysis of ligand-binding pocket shapes and volumes in proteins.
Initially developed to support structure-guided drug discovery, POVME has been widely adopted for its simplicity, speed, and flexibility.

You should have received a copy of the GNU General Public License along with
this program. If not, see
[https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
## Why binding pocket analysis?

## 1. Download POVME 2.2.2
Binding pockets are critical for understanding protein-ligand interactions, a central theme in rational drug design.
Pocket shape and volume influence ligand binding, specificity, and the dynamics of molecular recognition.
By enabling precise volume and flexibility measurements, POVME has become an essential tool for characterizing these properties in applications such as:

Begin by downloading POVME 2.2.2. An example input file is included with the
download (in the 'povme/examples/' directory). This input file is heavily
commented and may be even more useful that the information provided on this
website.
- Identifying and analyzing transient binding pockets.
- Supporting virtual screening and druggability predictions.
- Comparing conformational ensembles from molecular dynamics simulations.

POVME is released under the GNU General Public License. If you have any
questions, comments, or suggestions, please don't hesitate to contact me,
[Jacob Durrant](http://durrantlab.com), at durrantj [at] pitt [dot] edu.
## Development

If you use POVME in your work, please cite:

1. Durrant, J. D., C. A. de Oliveira, et al. (2011). "POVME: An algorithm for
measuring binding-pocket volumes." J Mol Graph Model 29(5): 773-776.
2. Durrant, J.D., L. Votapka, J. Sørensen, and R. E. Amaro (2014). "POVME 2.0:
An Enhanced Tool for Determining Pocket Shape and Volume Characteristics."
J. Chem. Theory Comput. 10(11):5047-5056.

## 2. Align a PDB-formatted trajectory

POVME accepts a multi-frame PDB (Protein Data Bank) file as input. The
computer program [Visual Molecular Dynamics
(VMD)](http://www.ks.uiuc.edu/Research/vmd/) is useful for aligning
trajectories and converting files to the PDB format. Alignment is necessary
because the POVME algorithm assumes the pocket being measured does not
translate or rotate in space. We note also that single-frame PDB files can
likewise serve as POVME input if the user wishes only to measure the volume of
a single pocket.

## 3. Define an inclusion region

The user must define an "inclusion" region. This region is constructed from a
combination of user-specified spheres and rectangular prisms. The required
inclusion region should entirely encompass all the binding-pocket
conformations of the trajectory. Specify the spheres and rectangular prisms of
the inclusion region in a text-based POVME input file (e.g., "POVME.in"):
We use [pixi](https://pixi.sh/latest/) to manage Python environments and simplify the developer workflow.
Once you have [pixi](https://pixi.sh/latest/) installed, move into `POVME` directory (e.g., `cd POVME`) and install the environment using the command

```text
PointsInclusionSphere -7.12 2.60 -4.67 6.0
PointsInclusionSphere -2.0 -2.0 -4.0 5.0
PointsInclusionBox -5.0 -7.0 2.0 10.0 10.0 10.0
PointsInclusionBox -2.0 -9.0 -3.0 10.0 5.0 10.0
```bash
pixi install
```

Note that for the spheres, the first three parameters are coordinates, and the
fourth parameter is a radius. For the rectangular prisms (i.e. "boxes"), the
first three parameters are coordinates, and the last three are the dimensions
of the box in the X, Y, and Z directions.
Now you can activate the new virtual environment using

## 4. Define an exclusion region

An optional exclusion region defines portions of the inclusion region that
should be ignored, perhaps because they are not truly associated with the
pocket. It is similarly constructed from spheres and boxes:

```text
PointsExclusionSphere -2.0 -2.0 -4.0 5.0
PointsExclusionBox -5.0 -7.0 2.0 10.0 10.0 10.0
```sh
pixi shell
```

## 5. Create a field of equidistant points

To generate a field of equidistant points that encompasses all the
binding-pocket conformations of the trajectory, POVME first floods the
user-specified inclusion region with points and then removes any points also
contained in the optional exclusion region. You need to specify the distance
separating each of these equidistant points:

```text
GridSpacing 1.0
```

## 6. How to choose the inclusion and exclusion regions

As you can imagine, identifying just the right set of inclusion and exclusion
spheres and boxes to encompass the binding pocket is challenging. One approach
is to define an initial geometry, visualize that geometry together with the
receptor using a program like VMD, and then iteratively add new inclusion and
exclusion regions as required. You can optionally save the point field to a
file called point_field.pdb for visualization:

```text
SavePoints true
```

## 7. Specify the location of the receptor PDB file to analyze

Once you've properly generated a pocket-encompassing point field, you're ready
to use that point field to calculate pocket volumes. Here's how to specify the
location of the PDB receptor file that has the pocket you wish to analyze:

```PDBFileName my_receptor.pdb```

Note that this file can be a trajectory containing multiple frames.

## 8. Remove points that are near receptor atoms

As the purpose of POVME is to measure the volume of a binding-pocket cavity,
the program next removes any points that are close to receptor atoms, leaving
only those points that are likely to be located within the binding pocket
itself. To specify how close the points can come to the van der Waal's surface
of the receptor before being removed:
## Installation

```DistanceCutoff 1.09```
Clone the [repository](https://github.com/durrantlab/POVME):

Note that if the receptor PDB file contains multiple frames, this will be done
on a frame-by-frame basis.

## 9. Remove points outside the receptor's convex hull

POVME 2.0 introduced an optional new feature for removing points that lie
entirely outside the binding pocket. Specifically, the gift-wrapping algorithm
is used in combination with the Akl-Toussaint heuristic to define the convex
hull of receptor atoms near the user-defined inclusion region. Any points that
fall outside the convex hull are removed. This feature is particularly useful
when the user defines an inclusion region that protrudes into the surrounding
solvent-occupying space. To activate the convex-hull feature:

```ConvexHullExclusion true```

## 10. Remove points that are not contiguous with the primary pocket

Like the original POVME program, version 2.2.2 retains the optional ability to
remove isolated patches of points that are not contiguous with the primary
binding pocket. POVME perfoms this task in two steps.

First, POVME applys a low-pass filter to check the connectedness of the
remaining pocket-occupying points. It retains only those points that have at
least X neighboring points, where X is defined:

```text
ContiguousPointsCriteria 3
```bash
git clone https://github.com/durrantlab/POVME
```

(Note that points that are "kitty-corner" from each other count as neighbors.)

Second, POVME identifies which of the remaining connected points are also
connected to a user-defined contiguous pocket seed volume (e.g., located at
the center of the traditionally defined pocket), where the seed volume is
defined:
Install `povme` using `pip` after moving into the directory.

```text
ContiguousPocketSeedSphere 67.0 102.0 57.0 4.0
ContiguousPocketSeedBox 50.0 50.0 50.0 10.0 10.0 10.0
```sh
pip install .
```

All pocket-occupying points contiguous (or connected) to this region are
retained, but isolated patches of points that are not directly connected are
deleted.

## 11. Additional POVME parameters

Here are some additional POVME parameters you might find helpful:

```text
# Tell POVME how to perform the calculations.
This will install all dependencies and `povme` into your current Python environment.

NumProcessors 12 # POVME can use multiple processors on
# Unix-based systems.
## Cite

UseDiskNotMemory false # In some cases, your PDB trajectory may
# be so large that the resulting POVME
# analysis cannot be easily stored in
# your computer's memory. If
# UseDiskNotMemory is set to true, POVME
# will rely more on your disk space than
# on memory/RAM.
# Tell POVME how to save the output
OutputFilenamePrefix ./POVME_test_run/POVME_ # All the files POVME outputs will start
# with this prefix. POVME automatically
# creates any required directory
# (./POVME_test_run/ in this case).
SaveIndividualPocketVolumes true # If true, POVME saves the pocket-volume
# points of each frame to a separate PDB
# file. The file names will be like
# {PREFIX}frame_X.pdb.
SavePocketVolumesTrajectory true # If true, POVME saves all the pocket-
# volume points of each frame to a single
# PDB trajectory file. The individual
# frames are separated by END cards. The
# file name will be
# {PREFIX}volume_trajectory.pdb.
OutputEqualNumPointsPerFrame true # Some visualization programs (e.g. VMD)
# are only compatible with trajectories
# that have the same number of atoms in
# each frame. If EqualNumAtomsPerFrame is
# true, POVME adds extra points at the
# origin (0.0, 0.0, 0.0) to satisfy this
# requirement. This affects files created
# with both SaveIndividualPocketVolumes
# and SavePocketVolumesTrajectory but
# does not alter the volume calculation
# itself.
SaveTabbedVolumeFile true # If true, POVME saves the calculated
# volumes to a file in a simple tabular
# format that can be easily pasted into
# popular spreadsheet programs like
# Microsoft Excel. The file is named
# {PREFIX}volumes.tabbed.txt
SaveVolumetricDensityMap true # If true, POVME saves a volumetric
# density map in the DX format. A
# volumetric density value is associated
# with each of the pocket-occupying
# points by calculating the fraction of
# all trajectory pocket volumes that
# include the given point. The file is
# named {PREFIX}volumetric_density.dx.
CompressOutput true # If you're short on disk space, POVME
# can automatically compress all output
# files using gz compression.
```
If you use POVME in your work, please cite:

## 12. POVME output
1. Durrant, J.D., L. Votapka, J. Sørensen, and R. E. Amaro (2014). "POVME 2.0: An Enhanced Tool for Determining Pocket Shape and Volume Characteristics." J. Chem. Theory Comput. 10(11):5047-5056.
2. Durrant, J. D., C. A. de Oliveira, et al. (2011). "POVME: An algorithm for measuring binding-pocket volumes." J Mol Graph Model 29(5): 773-776.

By default, POVME writes a number of files to the disk. The calculated pocket
volumes, as well as user-defined parameters and progress messages, are saved
to a simple text-based log file. POVME can also be instructed to save the
volume measurements to a second file in a simple tabular format that can be
easily pasted into popular spreadsheet programs. Pocket-occupying points are
equidistant (1.0 Å by default), so each point is associated with an identical
cubical volume (e.g. 1.0 Å3). The volume of a whole pocket is calculated by
simply summing the individual volumes associated with each unique point.
## License

POVME also optionally saves the pocket-occupying points of each frame to PDB
file(s) on this disk. The user can instruct the program to save these points
to separate files and/or to a single PDB trajectory. Some visualization
programs (e.g. VMD) are only compatible with trajectories that have the same
number of atoms in each frame. POVME can optionally write extra points to the
origin (0.0, 0.0, 0.0) on a frame-by-frame basis to satisfy this requirement.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Finally, POVME also optionally saves a volumetric density map in the Data
Explorer (DX) format. A volumetric density value is associated with each of
the pocket-occupying points by calculating the fraction of all trajectory
pocket volumes that include the given point. If the density map is displayed
as an isosurface, the value of the isosurface expresses the fraction of time
(e.g. over the course of the simulation) that the pocket included the
displayed volume.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

(README.md adapted from [this
website](http://rocce-vm0.ucsd.edu/data/sw/hosted/POVME/).)
You should have received a copy of the GNU General Public License along with this program.
If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
1 change: 1 addition & 0 deletions docs/.pages
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
nav:
- Home: index.md
- Monolith docs: mono-docs.md
- API: api
Loading

0 comments on commit b595ce7

Please sign in to comment.