Skip to content

Pocketeer

Pocketeer Logo

A lightweight, fast pocket finder in Python

Pocketeer detects binding pockets and cavities in protein structures using the alpha-sphere method based on Delaunay tessellation, similar to the popular fpocket, but more modern. It's lightweight, fast, and designed to be easy to use both as a Python library and command-line tool.

🚧 Warning: This software is in alpha. Some features (e.g., similarity calculation) are not yet implemented and there may be bugs. If you encounter any issues, please open an issue on the repository. 🚧

Key Features

  • Modern Python implementation - installable with pip or uv, works on Apple Silicon
  • Flexible Python API - built on biotite atom arrays
  • Command-line interface - simple CLI for batch processing
  • JIT-compiled performance - numba acceleration for volume calculations

Quick Start

Installation

pip install pocketeer

or 

uv add pocketeer

Python API

import pocketeer as pt

# Load structure from PDB file
atomarray = pt.load_structure("protein.pdb")

# Detect pockets with default parameters
pockets = pt.find_pockets(atomarray)

# Print results
for pocket in pockets:
    print(f"Pocket {pocket.pocket_id}:")
    print(f"  Score: {pocket.score:.2f}")
    print(f"  Volume: {pocket.volume:.1f} ų")
    print(f"  Spheres: {pocket.n_spheres}")

Command-Line Interface

# Basic usage
pocketeer protein.pdb # also works with .cif files 

# Custom output directory
pocketeer protein.pdb --o results/

# Adjust parameters
pocketeer protein.pdb --r-min 2.5 --r-max 7.0 --min-spheres 25

Output Files

The CLI generates these output files:

  • pockets.json - All pocket descriptors in JSON format
  • json/ - Subdirectory with individual JSON files for each pocket (pocket_0.json, pocket_1.json, etc.)
  • summary.txt - Human-readable summary (unless --no-summary is used)

Algorithm

Pocketeer implements a simplified version of the fpocket algorithm:

  1. Delaunay Tessellation - Compute Delaunay triangulation of protein atoms
  2. Alpha-Sphere Detection - Extract circumspheres of tetrahedra within radius bounds
  3. Polarity Labeling - Classify spheres as buried (interior) or surface
  4. Clustering - Group buried spheres into pockets using graph connectivity
  5. Scoring - Rank pockets by volume and geometric features

Limitations

  • Simplified scoring compared to fpocket (no hydrophobicity, flexibility, etc.)
  • Volume estimation is approximate (voxel-based)

Visualization in Notebooks

Pocketeer integrates smoothly with Jupyter and scientific Python notebooks. You can directly visualize detected pockets for rapid exploration:

import pocketeer as pt

# Load structure
atomarray = pt.load_structure("protein.pdb")
pockets = pt.find_pockets(atomarray)

# Visualize the pockets in your notebook
pt.view_pockets(atomarray, pockets)

What's Next?

Citation

If you use Pocketeer in your research, please cite the original fpocket paper:

Le Guilloux, V., Schmidtke, P., & Tuffery, P. (2009). Fpocket: An open source platform for ligand pocket detection. BMC Bioinformatics, 10(1), 168.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Run ruff check --fix && ruff format before committing
  5. Submit a pull request

Development installation

git clone https://github.com/cch1999/pocketeer.git
cd pocketeer
pip install -e ".[dev]"

Support

For bugs and feature requests, please open an issue on GitHub.