Metadata-Version: 2.4
Name: pocketnet
Version: 0.2.2
Summary: Ligand-binding pocket prediction from protein structures with a message-passing / attention-pooling network (five-model ensemble, weights included).
Author: Stalin Arulsamy, Kiruthiga Natarajan
License: MIT
Project-URL: Homepage, https://github.com/precisionmatics/pocketnet
Project-URL: Issues, https://github.com/precisionmatics/pocketnet/issues
Project-URL: Changelog, https://github.com/precisionmatics/pocketnet/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/precisionmatics/pocketnet/blob/main/docs/usage.md
Keywords: binding site prediction,drug discovery,protein structure,graph neural network,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: torch>=2.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: df
Requires-Dist: pandas; extra == "df"
Provides-Extra: all
Requires-Dist: pytest; extra == "all"
Requires-Dist: pandas; extra == "all"
Dynamic: license-file

# PocketNet

[![PyPI](https://img.shields.io/pypi/v/pocketnet)](https://pypi.org/project/pocketnet/) [![tests](https://github.com/precisionmatics/pocketnet/actions/workflows/ci.yml/badge.svg)](https://github.com/precisionmatics/pocketnet/actions) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Ligand-binding pocket prediction from a protein structure. A gated message-passing network over the atom graph feeds an attention-pooling
read-out over the 32 nearest atoms of every solvent-accessible surface point; the scored points are clustered into ranked pockets.
The package bundles a five-model ensemble (about 20 MB of weights): no download is needed at run time, and it runs on CPU or GPU.

```bash
pip install pocketnet
pocketnet predict 3POZ -o results/          # PDB identifier, file, folder or UniProt accession
```

```python
from pocketnet import PocketPredictor

pred = PocketPredictor()                     # CUDA if available, otherwise CPU
result = pred.predict("protein.pdb")         # also mmCIF, "3POZ", "P00533" (AlphaFold DB) or a Structure
print(result)                                # ranked pockets with scores and calibrated probabilities

best = result.best
best.center, best.residues[:5], best.probability
result.residue_scores                        # score of every residue
result.save("out/")                          # CSV, JSON, B-factor PDB, PyMOL (.pml), ChimeraX (.cxc) and SDF
```

## Features
* PDB and mmCIF input (gzip supported), chain selection, PDB identifiers and AlphaFold models fetched on demand
* Ranked pockets with centre, score, calibrated probability, druggability flag, convex-hull volume, lining residues and member surface points
* Per-residue scores and a PDB file whose B-factor column holds them, ready to colour in any viewer
* Exporters for CSV, JSON, pandas DataFrame, SDF (RDKit/OpenBabel-compatible), PyMOL script and ChimeraX command file
* `filter()` for slicing by probability, score or rank; `_repr_html_()` for Jupyter display with probability bars
* Context-manager interface, `residue_scores_df()` for pandas DataFrame of per-residue scores
* Batch prediction that survives bad inputs; typed API (`py.typed`), command line, 20 tests, continuous integration

## Quick examples

### Filtering and volume
```python
result = PocketPredictor().predict("3POZ")

# keep only druggable pockets (probability ≥ 0.5)
druggable = result.filter(druggable_only=True)
for p in druggable:
    print(f"rank {p.rank}  p={p.probability:.2f}  vol={p.volume(result.points):.0f} Å³")

# all volumes in one call
print(result.volumes)
```

### SDF export (RDKit-compatible)
```python
result.write_sdf("pockets.sdf")

# read back with RDKit
from rdkit.Chem import SDMolSupplier
for mol in SDMolSupplier("pockets.sdf", removeHs=False):
    print(mol.GetProp("RANK"), mol.GetProp("PROBABILITY"), mol.GetProp("VOLUME_A3"))
```

### Context manager and residue DataFrame
```python
with PocketPredictor() as pred:
    result = pred.predict("2HHB")
    df = pred.residue_scores_df(result)   # pandas DataFrame, sorted by score
    print(df.head(10))
```

### Jupyter display
```python
result   # calls _repr_html_() automatically — probability bars, druggability ticks, volumes
```

### Batch prediction
```python
import pocketnet
pred = PocketPredictor()
for name, result, err in pred.predict_many(["3POZ", "2HHB", "bad_id"]):
    if err: print(f"{name}: FAILED ({err})")
    else:   print(f"{name}: {len(result)} pockets, best p={result.best.probability:.2f}")
```

## Performance

Evaluated using a 4 Å distance-to-any-ligand-atom criterion, at most 10 pockets per method,
on sequence-identity-filtered subsets of HOLO4K and COACH420 (primary unseen: < 30 % identity,
80 % coverage to every training chain).  Numbers are top-*n* / top-*n*+2 / top-10 success rates
(% of ligands found).

| Method | COACH420 top-*n* | top-*n*+2 | top-10 | HOLO4K top-*n* | top-*n*+2 | top-10 |
|---|---|---|---|---|---|---|
| **PocketNet** | **70.0** | **80.0** | **85.0** | — | — | — |
| P2Rank | 64.6 | 73.8 | 83.1 | — | — | — |
| DeepPocket | 57.5 | 67.5 | 75.6 | — | — | — |
| fpocket | 54.2 | 63.3 | 68.3 | — | — | — |
| PUResNet | 54.2 | 55.8 | 55.8 | — | — | — |

Bootstrap 95 % confidence intervals and McNemar tests for paired differences are in the manuscript.
HOLO4K numbers will be added upon completion of the full benchmark run.

Limitations: VN-EGNN, EquiPocket, DeepSurf and Kalasanty are not in the table above.
The model was trained on PLAS-20k (simulation-derived complexes), so performance on
membrane proteins, large assemblies and cryptic sites is not yet characterised.
Ligands, ions and nucleic acids in the input are ignored.

## Repository layout
`pocketnet/` package and weights, `tests/`, `examples/`, `docs/`, `training/` (data preparation and training), `benchmarks/` (scoring on the P2Rank datasets).

## Citation
Arulsamy S, Natarajan K. PocketNet: message passing and attention pooling on the protein surface for ligand-binding pocket prediction (manuscript in preparation). See `CITATION.cff`.

## License
MIT. See `LICENSE`.
