How wall-ee/py-p2rank works
Project Type and Purpose
• P2Rank is a standalone, command-line full-stack tool (Java/Groovy core plus Python utilities) for predicting ligand-binding sites in protein structures.
• The Java/Groovy code implements the core algorithm: data loading, surface‐point sampling, feature extraction, ML scoring, clustering (pocket prediction), output & visualization.
• A parallel Python/“py” subproject (src_py) provides config management, model conversion & distribution, and a pure-Python implementation of the prediction pipeline and demos.
High-Level Components
A. CLI Frontends
• Java CLI (prank.sh / distro/prank)
• Python CLI (p2rank_py.sh / src_py/p2rank/program/main.py)
B. Core Engine (Java/Groovy, src/main/groovy/cz/siret/prank)
1. Program & Arg Parsing (program/)
2. Domain Model (domain/)
3. Loaders for structures, conservation, pockets (domain/loaders/)
4. Point Sampling & Geometry (geom/)
5. Feature Extraction (features/)
6. Prediction & Rescoring (prediction/)
7. Export & Visualization (export/, program/visualization/)
8. Utilities (utils/)
C. Configuration & Models
• Groovy configs under config/ and distro/config/
• Pretrained ML models in distro/models/ (.zst, JSON transformers)
• Python config & converted model repository in src_py/config_py & src_py/converted_models_final/
D. External Dependencies
• Native libraries (BioJava, CDK, Weka) under lib/
• External pocket tools invoked by routines (fpocket, ConCavity, DeepSite, etc.)
E. Tests & Examples
• Unit/integration tests (src/test/groovy, src_py/tests/)
• Example data under distro/test_data/ and src_py/examples/visualization/
Relationships & Data Flow
• User invokes CLI → Arg parser selects routine (predict, rescore, eval, etc.)
• Core engine:
• Structure Loader reads PDB/CIF → Sampler generates SAS points
• FeatureSetup registers calculators → Extractor builds feature vectors
• ModelLoader loads the selected ML model → ScoreTransformer calibrates scores
• PocketPredictor clusters scored points → generates Pocket objects
• Exporters write CSVs (predictions.csv, residues.csv)
• Visualization module produces .pml/.cxc scripts + point clouds
• Python CLI follows a similar pipeline in pure-Python, or orchestrates Java subprocess calls, and manages model conversions.
Architectural Patterns & Principles
• Modular Layers:
• CLI layer → Program/Routines → Domain/Loaders → Feature → Prediction → Export/Visualization
• Factory & Registry patterns in FeatureRegistry, CollectorFactory, ClassifierFactory
• Strategy pattern for interchangeable Labelers, FeatureCalculators, Rescorers, Renderers
• External-tool adapters (e.g., FpocketRunner) shield core from CLI commands
• Config-driven behavior: all parameters overridable via Groovy/YAML/command line