Package: volumizer
volumizerdiscovers 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 VolumeHere 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 structureidtypevolumexyz00pore38286.0108.22138.57436.31010pocket189.08.2145.6280.00021pocket162.06.6353.8432.84032pocket162.07.2984.0022.55743pocket162.010.7572.7010.00054pocket135.06.0006.0000.000InstallationThe package is published on PyPi,pip install volumizer.Developing the Volumizer PackageIf you want to develop the package,poetry installwithin the repository.
Test withpytestwithin the repository base directoryUsageUsing the test filetests/pdbs/4jpn.pdbtry out the following:Volumize a PDB and Save the Volumized PDB and DataFramePerforming 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 OutputIf 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, and BeyondIf you are interested in additional control over the volumizing method:the resolution of the voxels can be changedcleaning can be skippedNote: 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

utils.set_resolution(2.0)

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 Worksvolumizeridentifies 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 volumesA large voxel-grid is built around the atoms of the protein or other structure supplied.All voxels within a van der Waals radius of a protein or other atom is flagged as beingnon-solventRemainingsolventatoms are then broken into two groups:bulk solventandoccluded volumesThis is done by tracing a vector along each ordinal axis from a given voxel and if 2 or more of these vectors would
cross anon-solventvoxel, then the query voxel is identified as anoccluded volumeto be further analyzed
otherwise it is consideredbulk solventThe intention is to identify points on the grid that are outside the protein asbulk solventAlloccluded volumevoxels are then grouped into a number of continuous volumesFor each continous volume the number of distinct surfaces that contactbulk solventvoxels is computed and used
to indicate the volume type:
0 surfaces interacting with solvent:cavity1 surface interacting with solvent:pocket2 surfaces interacting with solvent:pore3+ surfaces interacting with solvent:hubAnnotationsPandas DataFrameAnnotations 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 FileThe input PDB file will be annotated by addingatomsto 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 codeOCCforoccludedCAVforcavityPOKforpocketPORforporeHUBforhubSurface 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.Allatomsof a particular volume are grouped under the same residue number.