Package Design

The main PyVOL algorithm is run from identify.pocket. Input option sanitization and logger configuration have been split into identify.pocket_wrapper. The pocket identification logic occurs within identify.pocket with almost all direct data manipulation handled by the class methods of Spheres. If enabled, subpocket clustering occurs in identify.subpockets with data manipulation occurring in cluster. Frequently used functions have been split into utilities. Configuration file reading and writing as well as input parameter checking is done in configuration.

The PyMOL interface is contained in pymol_interface though integration into the PyMOL environment is actually handled in pyvol_gui.__init__. Display and other PyMOL-specific functions are defined in pymol_utilities.

The two primary interfaces are via configuration file (invoked through the command line using the entry point in __main__ that is created on installation) and via PyMOL. PyMOL is extended with all commands, and the GUI provides a limited interface to these functions. Programmatic invocation is also supported. If standard output options are reasonable, using the identify.pocket_wrapper entry point is better. For more customization, directly call identify.pocket after calling configuration.clean_opts on a dictionary containing all required options.

Algorithm Design

The primary algorithmic logic is supplied in which acts as the only interface between the user-facing modules and the computational back-end.

The Spheres class holds all of the geometric information about proteins and pockets. It represents any object as a collection of spheres by holding their coordinates, radii, and cluster identifications in a 5D numpy array. Surface triangulation using MSMS and many other convenience functions are included in the class itself. The methods contained in the separate would largely work as methods in the Spheres class but have been separated due to that class becoming too large and the specificity of those methods to subpocket partitioning.

GUI Design

The GUI was developed using Qt Designer and run using PyQT5. PyQT does not run in PyMOL 1.x distributions, so the GUI is only available in PyMOL 2.0+.

Version Incrementation

PyVOL uses a standard incrementation scheme. The version of the back-end must be updated in, pyvol/, and docs/source/ The GUI version is set in pyvolgui/, and the the version of the GUI that the back-end expects is set again in pyvol/ Experimental code is pushed with an alpha or beta designation (a or b before the final digit). GUI versions should only change when the GUI files are changed, but the version is intended to catch up to the backend version rather than the next available incrementation.


The code is hosted on github by the Schlessinger Lab. The PyVOL backend is distributed through PyPI. This process of uploading to PyPI is automated in the dev/ script. Installers are packaged using the dev/ script. Documentation is generated and pushed to the github-hosted documentation website with the dev/ script. All three are combined in the dev/ script. The plugin will be available both from the github page and (eventually) through the official PyMOL wiki.


Documentation is in the Sphinx/RTD style. Module documentation is collated using sphinx-apidoc. The documentation website is built using the sphinx-rtd-theme and maintained on the gh-pages branch of PyVOL. The pyvol_manual.pdf is generated using sphinx’s evocation of pdfTeX. PyPI can apparently not parse rst files, so the README.rst is converted to a md file using pandoc just prior to deployment.


Integration testing of the non-PyMOL components is performed using pytest out of tests/ These are invoked by running python -m pytest in the root pyvol directory. These tests have been run using pytest version 5.3.5. Installing pytest-xdist is recommended for efficiency’s sake.