Metadata-Version: 2.4
Name: pocketmapper
Version: 0.0.6rc0
Summary: A tool for mapping surface pockets in PDB structures
Author-email: Lachlan Ellingboe <Lachlan.Ellingboe@icr.ac.uk>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bio
Requires-Dist: fire
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: gemmi
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# PocketMapper

PocketMapper is a command-line tool to compare the binding surfaces of protein-protein interactions.
PocketMapper fetches protein structures from the PDB, fetches contact residues from PDBe (PISA), aligns structures based on sequence (pairwise BLOSUM62) or structure (Foldseek) alignment, and returns information about overlapping surfaces including the conservation of surface residues and their RMSD.
It is intended for comparative analysis of binding pockets between query and target protein chains.

## Installation
PocketMapper has been tested with Python 3.12 and is available on [PyPI](https://pypi.org/project/pocketmapper/). Optionally, [Foldseek](https://github.com/steineggerlab/foldseek) can be installed to enable effecient structural alignment.
```
# Setup conda environment for pocketmapper
conda create --name=pocketmapper python=3.12

# Pip installation of PocketMapepr
pip install pocketmapper

# Optional - Conda installation of Foldseek
conda install -c conda-forge -c bioconda foldseek
```
Foldseek also has precompiled binaries available at https://dev.mmseqs.com/foldseek/

## Usage
### Example commands
Basic sequence alignment run for a single pair:
```
pocketmapper search --query 4Q5J_B_F --target 4Q5J_A_E --results_dir ./out
```
Batch mode using files with one PDB_CHAIN_CHAIN per line:
```
pocketmapper search --query queries.txt --target targets.txt --settings config.json
```
Using the bundled Foldseek DB:
```
pocketmapper search --query 4Q5J_B_F --target human_domains --foldseek True --results_dir ./out_fs
```

### Options
--query: Query identifier or path. Accepts a single PDB_CHAIN_CHAIN (e.g. 4Q5J_B_F) or a file with one per line.\
--target: Target identifier or path. Accepts single PDB_CHAIN_CHAIN, file, or 'human_domains' for bundled Foldseek DB.\
--settings: Path to JSON settings file. CLI args override settings file. Same available arguments as command line.\
--cache_dir: Directory for caching downloaded or intermediate files.\
--results_dir: Directory to write results and temporary divided structures.\
--verbose / --debug: Increase log verbosity.\
--foldseek: If true, run Foldseek alignments (requires foldseek binary).\
--help: Display the help message

### Features
- Download and cache mmCIF files
- Preprocess/mmCIF splitting using gemmi
- Retrieve PISA interface/pocket information and store pocket data
- Extract CA coordinates from divided structures
- Perform local alignments or Foldseek-based alignments
- Compare pockets using alignment and substitution scoring (BLOSUM62)
- Save tabular results and auxiliary JSON files to a results directory

### Outputs
- alignment.tsv: Alignment report (Foldseek or local aligner)
- pocket_comparison.tsv: Final pocket comparison table
- pisa_pockets and intermediate JSON snapshots under pisa_dir
- unknown_ids.json (if unknown Foldseek aliases are encountered e.g., MSE -> M)
- Divided mmCIF files and temporary directories under results_dir

## Contact / Authors
See project repository for maintainer and contributor information.
