# wall-ee/py-p2rank architecture

> Architecture diagram of the GitHub repository wall-ee/py-p2rank, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wall-ee/py-p2rank
- Repository: https://github.com/wall-ee/py-p2rank

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontends
    subgraph "CLI Frontends" 
        direction TB
        JavaCLI_sh["prank.sh"]:::cli
        JavaCLI_dist["distro/prank"]:::cli
        PythonCLI_sh["p2rank_py.sh"]:::cli
        PythonCLI_main["main.py"]:::cli
    end

    %% Core Engine Modules
    subgraph "Core Engine" 
        direction TB
        Program["Program & Arg Parsing"]:::core
        Domain["Domain Model"]:::core
        Loaders["Structure & Conservation Loaders"]:::core
        PocketLoaders["Pocket Loaders (Adapters)"]:::core
        Geom["Geometry & Sampling"]:::core
        FeaturesAPI["Feature Extraction API"]:::core
        FeaturesImpl["Feature Implementations"]:::core
        Prediction["Prediction & Rescoring"]:::core
        Exporters["Exporters"]:::core
        Visualization["Visualization Module"]:::core
        Utils["Utilities"]:::core
    end

    %% Config & Models
    subgraph "Config & Models Store"
        direction TB
        GroovyConfig["Groovy Configs"]:::storage
        MLModels["Pretrained ML Models"]:::storage
        PyConfig["Python Config"]:::storage
        PyModels["Converted Python Models"]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ExternalLibs["Native Libraries"]:::external
        ExternalTools["Pocket Tools (e.g., fpocket)"]:::external
    end

    %% Tests & Examples
    subgraph "Tests & Examples"
        direction TB
        JavaTests["Java Unit/Integration Tests"]:::tests
        PyTests["Python Tests"]:::tests
        JavaExamples["Java Example Data"]:::tests
        PyExamples["Python Example Data"]:::tests
    end

    %% Data Flow
    JavaCLI_sh -->|"invoke"| Program
    JavaCLI_dist --> Program
    PythonCLI_sh --> Program
    PythonCLI_main --> Program

    Program -->|"loads domain"| Domain
    Domain --> Loaders
    Loaders --> Geom
    PocketLoaders --> Geom
    Geom --> FeaturesAPI
    FeaturesAPI --> FeaturesImpl
    FeaturesImpl --> Prediction
    Prediction --> Exporters
    Exporters --> Visualization
    Visualization --> Utils

    %% Config & Models Links
    Program --> GroovyConfig
    Prediction --> MLModels
    Program --> PyConfig
    Prediction --> PyModels

    %% External Dependencies Links
    Loaders --> ExternalLibs
    PocketLoaders --> ExternalTools

    %% Tests & Examples Links
    JavaTests --> Program
    PyTests --> PythonCLI_main
    JavaExamples --> JavaCLI_dist
    PyExamples --> PythonCLI_main

    %% Click Events
    click JavaCLI_sh "https://github.com/wall-ee/py-p2rank/blob/develop/prank.sh"
    click JavaCLI_dist "https://github.com/wall-ee/py-p2rank/tree/develop/distro/prank"
    click PythonCLI_sh "https://github.com/wall-ee/py-p2rank/blob/develop/src_py/p2rank_py.sh"
    click PythonCLI_main "https://github.com/wall-ee/py-p2rank/blob/develop/src_py/p2rank/program/main.py"
    click Program "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/program"
    click Domain "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/domain"
    click Loaders "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/domain/loaders"
    click PocketLoaders "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/domain/loaders/pockets"
    click Geom "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/geom"
    click FeaturesAPI "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/features/api"
    click FeaturesImpl "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/features/implementation"
    click Prediction "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/prediction"
    click Exporters "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/export"
    click Visualization "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/program/visualization"
    click Utils "https://github.com/wall-ee/py-p2rank/tree/develop/src/main/groovy/cz/siret/prank/utils"
    click GroovyConfig "https://github.com/wall-ee/py-p2rank/tree/develop/config/"
    click MLModels "https://github.com/wall-ee/py-p2rank/tree/develop/distro/models/"
    click PyConfig "https://github.com/wall-ee/py-p2rank/tree/develop/src_py/config_py"
    click PyModels "https://github.com/wall-ee/py-p2rank/tree/develop/src_py/converted_models_final"
    click JavaTests "https://github.com/wall-ee/py-p2rank/tree/develop/src/test/groovy"
    click PyTests "https://github.com/wall-ee/py-p2rank/tree/develop/src_py/tests"
    click JavaExamples "https://github.com/wall-ee/py-p2rank/tree/develop/distro/test_data/"
    click PyExamples "https://github.com/wall-ee/py-p2rank/tree/develop/src_py/examples/visualization"

    %% Styles
    classDef cli fill:#CCEEFF,stroke:#0077CC,stroke-width:2px
    classDef core fill:#CCFFCC,stroke:#009900,stroke-width:2px
    classDef external fill:#FFE5CC,stroke:#FF6600,stroke-width:2px
    classDef storage fill:#EEEEEE,stroke:#666666,stroke-width:2px
    classDef tests fill:#F2E5FF,stroke:#9933CC,stroke-width:2px
```
