Metadata-Version: 2.4
Name: pocketmapper
Version: 0.0.3rc0
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
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 fetch protein structures, compute PISA-derived pockets,
    extract atomic coordinates from mmCIF files, perform local or Foldseek alignments, compare
    pockets across structures and write results to disk. It is intended for comparative analysis
    of binding pockets between query and target protein chains.

    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

    Requirements
    - Python 3.8+
    - pandas
    - gemmi
    - pisa (project-specific downloader wrapper used by this package)
    - foldseek (optional, required only when using Foldseek alignment)
    - Additional dependencies: lib (project helper module), LocalAligner class (local_aligner.py)
    - Command-line wrapper: fire

    Installation
    1. Clone the repository (or copy the project into your workspace).
    2. Create a virtualenv and install dependencies:
        python -m venv .venv
        source .venv/bin/activate
        pip install -r requirements.txt

    3. Ensure external tools are available:
        - foldseek (if using Foldseek): install and available on PATH

    Quick start / Usage
    - Basic local alignment run for a single pair:
      pocketmapper search --query 1ABC_A_B --target 2XYZ_C_D --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

    - Use bundled Foldseek DB:
      pocketmapper search --query 1ABC_A_B --target ted --foldseek True --results_dir ./out_fs

    Options
    - --query: Query identifier or path. Accepts a single PDB_CHAIN_CHAIN (e.g. 1ABC_A_B) or a file with one per line.
    - --target: Target identifier or path. Accepts single PDB_CHAIN_CHAIN, file, or 'ted' for bundled Foldseek DB.
    - --settings: Path to JSON settings file. CLI args override settings file.
    - --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 and appropriate DB).
    - --pisa_pockets: Whether to retrieve PISA pockets (default: true).

    Configuration (settings JSON)
    The settings JSON may include keys such as:
    - cache_dir, structure_dir, pocket_dir, pisa_dir, divided_struct_dir
    - results_dir, query_dir, target_dir, alignment_path, pocket_comparison_path
    - foldseek (bool), pisa_pockets (bool), structure (bool)

    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)
    - Divided mmCIF files and temporary directories under results_dir

    Design / Workflow
    1. Parse CLI args and settings
    2. Determine types of query/target (single PDB_CHAIN_CHAIN, file, or foldseek DB)
    3. Fetch mmCIF structures to cache (structure_dir)
    4. Preprocess and divide structures (gemmi) into per-domain files (divided_struct_dir)
    5. Retrieve PISA interface data and compute pockets (pisa)
    6. Extract CA coordinates from divided mmCIFs
    7. Perform alignment (local or foldseek)
    8. Compare pockets using alignments and BLOSUM scoring
    9. Save results and clean up temporary directories

    Extending or Debugging
    - Increase verbosity with --verbose or --debug to get more details in logs.
    - The library 'lib' contains helper functions for fetching mmCIFs, preprocessing and comparing pockets.
    - Local alignment logic is in local_aligner.py (LocalAligner).
    - The default logging writes to test.log in the current working directory.

    License
    - Add your preferred license information here.

    Contributing
    - Report issues or open pull requests against the repository.
    - Add tests for new functionality and keep changes small and focused.

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