volumizer 0.1.1

Search the RCSB for occluded volumes like cavities, pockets, and pores.

volumizer discovers and annotates occluded volumes in proteins including:

• cavities: Volumes within a protein that do not make any contacts with bulk solvent. Useful for e.g. carrying cargo.
• pockets: Volumes on the protein surface that make a single contact with bulk solvent. Useful for e.g. ligand binding or catalysis.
• pores: Volumes connecting two bulk solvent surfaces. Useful for e.g. filtering solutes.
• hubs: Volumes connecting more than two bulk solvent surfaces. Useful for e.g. containing a small reaction volume.

Example Identified Volume

Here is shown an example pore identified and annotated (red) in PDB 4JPN (green).

The same pore volume annotated (red) shown as a slice through the protein (grey).

The dataframe output shows volume/dimensinos of each occluded volume in the structure

	id	type	volume	x	y	z
0	0	pore	38286.0	108.221	38.574	36.310
1	0	pocket	189.0	8.214	5.628	0.000
2	1	pocket	162.0	6.635	3.843	2.840
3	2	pocket	162.0	7.298	4.002	2.557
4	3	pocket	162.0	10.757	2.701	0.000
5	4	pocket	135.0	6.000	6.000	0.000

Installation

The package is published on PyPi, pip install volumizer.

Developing the Volumizer Package

If you want to develop the package, poetry install within the repository. Test with pytest within the repository base directory

Usage

Using the test file tests/pdbs/4jpn.pdb try out the following:

Volumize a PDB and Save the Volumized PDB and DataFrame

Performing end-to-end loading, cleaning, volumizing, and saving is done with a single convenience function:

from volumizer import volumizer

volumizer.volumize_pdb_and_save("my_input.pdb", "volumized_pdb.pdb", "volumized_df.json")

Load a PDB as a Biotite Structure, Clean, Volumize, and Save Output

If you want access to the individual end-products: volume dataframe, the input structure after cleaning, and the structure of the volumes:

from volumizer import volumizer, pdb

pdb_structure = pdb.load_structure("my_input.pdb")
volumes_df, cleaned_structure, volumes_structure = volumizer.volumize_structure(pdb_structure)

# take the cleaned input and annotated volumes and convert them to a PDB format string and then save
#  modify the `deliminator` to suit your visualization preference
#  e.g. the default "END" allows Pymol to load the resulting PDB file as two separate objects, one for the cleaned input, and one for the volumes
pdb_lines = pdb.make_volumized_pdb_lines([cleaned_structure, volumes_structure], deliminator="END")
pdb.save_pdb_lines(pdb_lines, "volumized_pdb.pdb")

volumes_df.to_json("volumized_df.json")

Changing Resolution, Modifying PDB Cleaning, and Beyond

If you are interested in additional control over the volumizing method, the resolution of the voxels can be changed, you can skip cleaning, or modify which residues are kept/removed by the cleaning process

Note: the default voxel resolution is 3.0 Angstroms, which gives sensible results in the majority of cases. Higher resolutions especially < 2.0 Angstroms will often find small paths through a protein structure, making e.g. cavities look like pores, etc. Lower resolutions are faster to compute, but may begin to under-estimate the true volume of solvent occluded elements.

Note: by default all residues that make L- or D- peptide bonds are retained through cleaning (e.g. Non-canonicals are kept, even if they are heteroatoms in PDB structure). By constrast all non-covalently attached residues are removed. Currently glycan residues are also removed as they make non-peptide bonds, below is shown an example of how would would retain glycans.

from volumizer import volumizer, pdb, utils

# specify whichever residues you are interested in keeping during cleaning, or having additionally removed
KEEP_RESIDUE_NAMES = {"GAL", "NAG", "MAN", "GLC"}  # some example sugar residues to keep when cleaning
REMOVE_RESIDUE_NAMES = {"SME"}  # some example NCAAs to remove when cleaning

utils.set_resolution(2.0)
utils.add_protein_components(KEEP_RESIDUE_NAMES)
utils.remove_protein_components(REMOVE_RESIDUE_NAMES)

pdb_structure = pdb.load_structure("my_input.pdb")
cleaned_structure = volumizer.prepare_pdb_structure(pdb_structure)  # skip this if you want to keep the exact input structure
volumes_df, volumes_structure = volumizer.annotate_structure_volumes(cleaned_structure)

# take the cleaned input and annotated volumes and convert them to a PDB format string and then save
#  modify the `deliminator` to suit your visualization preference
#  e.g. the default "END" allows Pymol to load the resulting PDB file as two separate objects, one for the cleaned input, and one for the volumes
pdb_lines = pdb.make_volumized_pdb_lines([cleaned_structure, volumes_structure], deliminator="END")
pdb.save_pdb_lines(pdb_lines, "volumized_pdb.pdb")

volumes_df.to_json("volumized_df.json")

How It Works

volumizer identifies hydrated volumes in a protein structure that are not fully solvent exposed, e.g. a binding pocket. It then computes the volume and dimensions of these and outputs that information along with an annotated version of the input PDB showing where these volumes are (which can be visualized in e.g. Pymol, Chimerax, etc.).

Identifying hydrated volumes

1. A large voxel-grid is built around the atoms of the protein or other structure supplied.
2. All voxels within a van der Waals radius of a protein or other atom is flagged as being non-solvent
3. Remaining solvent atoms are then broken into two groups: bulk solvent and occluded volumes This is done by tracing a vector along each ordinal axis from a given voxel and if 2 or more of these vectors would cross a non-solvent voxel, then the query voxel is identified as an occluded volume to be further analyzed otherwise it is considered bulk solvent The intention is to identify points on the grid that are outside the protein as bulk solvent
4. All occluded volume voxels are then grouped into a number of continuous volumes
5. For each continous volume the number of distinct surfaces that contact bulk solvent voxels is computed and used to indicate the volume type: 0 surfaces interacting with solvent: cavity 1 surface interacting with solvent: pocket 2 surfaces interacting with solvent: pore 3+ surfaces interacting with solvent: hub

Annotations

Pandas DataFrame

Annotations are given as a pandas data frame saved as a .json file. The annotation lists all hydrated volumes ordered by total volume, giving the type of volume, and dimensions.

PDB File

The input PDB file will be annotated by adding atoms to represent the hydrated volumes. The ATOM entries contain several points of information about the volume from which they come:

Type of volume: the residue name encodes the type of volume in 3-letter code

• OCC for occluded
• CAV for cavity
• POK for pocket
• POR for pore
• HUB for hub

Surface of the hydrated volume that interacts with bulk solvent: this is indicated by a B-factor of 50.0, whereas the remainder of the volume (that does not interact with the bulk solvent) has a value of 0.0.

All atoms of a particular volume are grouped under the same residue number.