# arontier/akscore2_paper architecture

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

- Interactive diagram: https://gitdiagram.com/arontier/akscore2_paper
- Repository: https://github.com/arontier/akscore2_paper

## Overview

##### Project type and purpose
- This is a command-line Python tool (monolithic application) for predicting protein–ligand binding affinities.
- It ingests ligand files (.mol2/.pdb) and protein structures (.pdb), builds graph representations, runs PyTorch-based graph-neural-network models, and outputs scores.

##### File structure
- Top-level scripts:
- convert_mol2pdb.py – converts ligand .mol2 → .pdb using OpenBabel/RDKit.
- construct_pyg_graph.py – reads .pdbs and builds PyG graphs.
- akscore2_run.py – orchestrates the full pipeline (graph construction + model inference).
- akscore2_models.py – defines the neural network architectures.
- Supporting directories:
- examples/ – sample inputs for testing.
- model_weights/ – pretrained .pth files for 3 models (NonDock, DockC, DockS).
- Config/dependencies: requirements.txt lists PyTorch, PyG, RDKit, OpenBabel, Meeko, NumPy, pandas.

##### README
- Confirms a three-stage workflow: (1) convert ligand, (2) construct graph & infer, (3) aggregate ensemble score (+ optional AutoDock).
- Describes CLI usage patterns, model selection flags, output format.

##### Main components & interactions
a. Components
- Input Module
– CLI parser (argparse in akscore2_run.py)
– File readers (mol2, pdb)
- Preprocessing Module
– convert_mol2pdb.py (OpenBabel/RDKit)
- Graph Construction Module
– construct_pyg_graph.py (PyTorch Geometric)
- Model Inference Module
– akscore2_models.py
– Model loader (loads .pth weights)
– Inference engine (runs forward pass on GPU/CPU)
- Output Module
– result.csv writer (pandas I/O)
- External Services/Libraries
– OpenBabel, RDKit, Meeko
– PyTorch & PyG
– Optional AutoDock executable for ensemble scoring

b. Relationships & data flow
1. User invokes akscore2_run.py → CLI parser reads arguments.
2. If ligand in .mol2, call convert_mol2pdb module → produce .pdb.
3. Feed protein .pdb + ligand .pdb into graph constructor → build graph objects.
4. Load pretrained weights into neural network architectures → run inference.
5. Collect scores (NonDock, DockC/S) and compute final score.
6. Write tabular results to result.csv.
7. (Optional) Call external AutoDock → add scores → update CSV.

c. Architectural patterns & design principles
- Pipeline pattern: clear sequential stages (Convert → Graphify → Infer → Write).
- Modularization: distinct scripts for each stage, shared model definitions.
- Configuration via CLI arguments, enabling model selection and hardware targeting.

d. Key technologies & libraries
- Python 3.x, argparse
- OpenBabel/RDKit (file conversion and chemistry)
- Meeko (ligand preparation)
- PyTorch 1.11 + CUDA/cuDNN
- PyTorch Geometric 2.0.4
- pandas, NumPy

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLIParser["CLI Parser\n(argparse)"]:::internal
    Preprocess["Preprocessing Module\n(convert_mol2pdb.py)\nOpenBabel/RDKit"]:::internal
    GraphConstruct["Graph Construction Module\n(construct_pyg_graph.py)\nPyTorch Geometric"]:::internal
    subgraph "Model Inference"
        Loader["Model Loader\n(load .pth weights)"]:::internal
        NNArch["Inference Engine\n(akscore2_models.py)\nPyTorch"]:::internal
    end
    OutputWriter["Output Module\n(write result.csv)"]:::internal

    extAutoDock["AutoDock"]:::external
    Examples["examples/"]:::data
    Requirements["requirements.txt"]:::data

    W1["akscore2_nondock_weights.pth"]:::data
    W2["akscore2_dockc_weights.pth"]:::data
    W3["akscore2_docks_weights.pth"]:::data

    CLIParser -->|"arguments"| Preprocess
    Preprocess -->|".mol2 → .pdb"| GraphConstruct
    GraphConstruct -->|".pdb → PyG Graph"| Loader
    W1 --> Loader
    W2 --> Loader
    W3 --> Loader
    Loader -->|"graph → tensor"| NNArch
    NNArch -->|"scores"| OutputWriter
    extAutoDock -.->|"optional scores"| OutputWriter

    CLIParser --> Examples
    CLIParser --> Requirements

    click CLIParser "https://github.com/arontier/akscore2_paper/blob/main/akscore2_run.py"
    click Preprocess "https://github.com/arontier/akscore2_paper/blob/main/convert_mol2pdb.py"
    click GraphConstruct "https://github.com/arontier/akscore2_paper/blob/main/construct_pyg_graph.py"
    click NNArch "https://github.com/arontier/akscore2_paper/blob/main/akscore2_models.py"
    click W1 "https://github.com/arontier/akscore2_paper/blob/main/model_weights/akscore2_nondock_weights.pth"
    click W2 "https://github.com/arontier/akscore2_paper/blob/main/model_weights/akscore2_dockc_weights.pth"
    click W3 "https://github.com/arontier/akscore2_paper/blob/main/model_weights/akscore2_docks_weights.pth"
    click OutputWriter "https://github.com/arontier/akscore2_paper/blob/main/akscore2_run.py"
    click Examples "https://github.com/arontier/akscore2_paper/tree/main/examples/"
    click Requirements "https://github.com/arontier/akscore2_paper/blob/main/requirements.txt"

    classDef internal fill:#e0ffe0,stroke:#2d8f2d,color:#000
    classDef data fill:#e0e0ff,stroke:#2d2d8f,color:#000
    classDef external fill:#ffe0e0,stroke:#8f2d2d,color:#000
```
