Computing volume

The povme volume command in POVME is designed to compute and analyze the volume of molecular pockets based on user-specified inclusion and exclusion regions. This command can process both static protein structures and molecular dynamics (MD) trajectories to identify binding pocket volumes and characteristics.

YAML configuration

The command is configured through a YAML input file that will be used to update PocketVolumeConfig that defines the parameters for pocket volume calculations.

grid_spacing: 1.0
load_points_path: null

points_inclusion_sphere:
  - center: [65.0, 98.0, 50.0]
    radius: 16.0
  - center: [-100.0, -100.0, -100.0]
    radius: 10.0

save_points: true
distance_cutoff: 1.09
convex_hull_exclusion: true

contiguous_pocket_seed_sphere:
  - center: [67.0, 102.0, 57.0]
    radius: 4.0
contiguous_points_criteria: 3

use_ray: true
n_cores: 8

save_individual_pocket_volumes: true
save_pocket_volumes_trajectory: true
output_equal_num_points_per_frame: true
save_volumetric_density_map: true
compress_output: false

compress_output: bool = False

Whether to compress all output files using gz compression to save disk space.

contiguous_pocket_seed_box: list[dict[str, list[float]]] = []

Seed boxes for contiguous pocket detection.

A list of dictionaries, each specifying a rectangular region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
box's center.
- `"lengths"` (`list[float]`): The lengths of the box along the
x, y, and z axes.

contiguous_pocket_seed_sphere: list[dict[str, list[float] | float]] = []

Seed regions for contiguous pocket detection.

A list of dictionaries, each specifying a spherical region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
sphere's center.
- `"radius"` (`float`): The radius of the sphere.

contiguous_points_criteria: int = 4

The minimum number of neighboring points required to consider two pocket volumes contiguous.

convex_hull_exclusion: bool = True

Whether to calculate the convex hull of receptor atoms near the pocket and exclude points outside it.

distance_cutoff: float = 1.09

The distance from a receptor atom's van der Waals surface below which points are excluded.

Default is 1.09 Angstroms, the van der Waals radius of a hydrogen atom.

grid_spacing: float = 1.0

The distance, in Angstroms, between adjacent points.

Smaller values improve accuracy but increase computational cost.

load_points_filename: str | None = None

Optional filename to load a previously saved point field.

Should use the .pdb.npy format.

load_points_path: str | None = None

Load points from npy file.

n_cores: int = 4

Number of processors to use for the calculation on Unix-based systems.

output_equal_num_points_per_frame: bool = False

Whether to add extra points at the origin (0.0, 0.0, 0.0) to ensure the same number of points in each frame.

points_exclusion_box: list[dict[str, list[float]]] = []

A list of rectangular prisms ('boxes') to exclude from the pocket-encompassing region.

A list of dictionaries, each specifying a rectangular region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
box's center.
- `"lengths"` (`list[float]`): The lengths of the box along the
x, y, and z axes.

points_exclusion_sphere: list[dict[str, list[float] | float]] = []

A list of spheres to exclude from the pocket-encompassing region.

A list of dictionaries, each specifying a spherical region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
sphere's center.
- `"radius"` (`float`): The radius of the sphere.

points_inclusion_box: list[dict[str, list[float]]] = []

A list of rectangular prisms ('boxes') to include in the pocket-encompassing region.

A list of dictionaries, each specifying a rectangular region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
box's center.
- `"lengths"` (`list[float]`): The lengths of the box along the
x, y, and z axes.

points_inclusion_sphere: list[dict[str, list[float] | float]] = []

A list of spheres to include in the pocket-encompassing region.

A list of dictionaries, each specifying a spherical region. Each dictionary must have:

- `"center"` (`list[float]`): The x, y, and z coordinates of the
sphere's center.
- `"radius"` (`float`): The radius of the sphere.

save_individual_pocket_volumes: bool = False

Whether to save the pocket-volume points for each frame to separate PDB files.

save_pocket_volumes_trajectory: bool = False

Whether to save all pocket-volume points for each frame to a single PDB trajectory file.

save_points: bool = False

Whether to save the point field to a PDB file for visualization or reuse.

save_volumetric_density_map: bool = False

Whether to save a volumetric density map in DX format.

use_ray: bool = False

Parallelize computations with ray.

Running the command

Once the configuration file is ready, you can use the povme detect command to identify pockets. The command syntax is:

povme volume -c config.yaml -i input.pdb -o output/

• -c: Path to the YAML configuration file.
• -i: Input file, typically a PDB structure or trajectory.
• -o: Output directory.

Outputs

By default, POVME writes several files to the disk. POVME will save the volume measurements to a CSV file that can be easily pasted into popular spreadsheet programs.

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 with the same number of atoms in each frame. To satisfy this requirement, POVME can optionally write extra points to the origin (0.0, 0.0, 0.0) on a frame-by-frame basis.

Finally, POVME also optionally saves a volumetric density map in the Data Explorer (DX) format. A volumetric density value is associated with each pocket-occupying point 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., throughout the simulation) that the pocket included the displayed volume.