pocketeer 0.3.0

A minimal, fpocket-style pocket finder in pure Python/Numpy.

Pocketeer

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 with a modern, Pythonic interface. It's lightweight, fast, and easy to use as both a Python library and a command-line tool. Pocketeer natively supports atomarrays from biotite, making it fully compatible with atomworks.

Read the full documentation here.

🚧 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. 🚧

Installation

pip install pocketeer

Other options

Install with notebook viewer:

pip install pocketeer[vis]

Install with acceleration (Numba JIT compilation for faster volume calculations):

pip install pocketeer[accelerate]

Install using uv:

uv add pocketeer

Install with extra dependencies, e.g. for acceleration and visualization:

uv add 'pocketeer[accelerate]'
uv add 'pocketeer[vis]'
uv add 'pocketeer[dev, vis, accelerate]'

Quick Start

Example output image from Pocketeer

A couple quick tips before you start:

• Pocketeer automatically removes hydrogens from your structure, and is designed to work with them absent, so you don't need to worry about them.
• By default, Pocketeer removes all waters and hetero atoms from your input structure. Set ignore_hetero to False if you don't want this behavior (e.g. to take into account a metal ion in the pocket).

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}")

Custom Parameters

import pocketeer as pt

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

# Find pockets with custom parameters
pockets = pt.find_pockets(
    atomarray,
    r_min=3.0,           # Minimum sphere radius (Å)
    r_max=6.0,           # Maximum sphere radius (Å)
    min_spheres=30,      # Minimum spheres per pocket cluster
    merge_distance=2.5,  # Distance threshold for clustering
    sasa_threshold=25.0,  # SASA threshold for buried spheres (Ų)
    engine="numba",      # Use Numba for faster volume calculation (requires pocketeer[accelerate])
)

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

# Fine-tune buried sphere detection
pocketeer protein.pdb --sasa-threshold 25.0 --polar-probe 1.6

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 - Calculate SASA (solvent accessible surface area) for atoms defining each sphere
4. Surface Filtering - Filter to buried spheres using SASA threshold (spheres with mean SASA < threshold)
5. Clustering - Group buried spheres into pockets using graph connectivity
6. 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:

Note: The view_pockets() function requires the optional atomworks dependency. Install it with:

pip install pocketeer[vis]

or

uv add 'pocketeer[vis]'

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)

Example notebook visualization of predicted binding pockets colored by cluster.

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 (or run just all)
5. Submit a pull request

Development installation

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

Support

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