# byungukp/masif_pmp architecture

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

- Interactive diagram: https://gitdiagram.com/byungukp/masif_pmp
- Repository: https://github.com/byungukp/masif_pmp

## Overview

##### Project Type & Purpose
- A research-grade, command-line bioinformatics toolkit written in Python plus shell/Slurm scripts.
- Implements several MaSIF variants (site prediction, PPI, ensemble learning, ligand binding, PMP/IBS).
- Designed for HPC execution (Slurm scripts) on large protein surface datasets.

##### High-Level Component Identification
a. Data Storage
– “data/…” directories: raw inputs (PDB lists), TFRecords, precomputed models.
– Disk volumes or shared filesystem on HPC.
b. Orchestration Layer (Shell & Slurm Scripts)
– `*.sh` and `*.slurm` scripts under each pipeline: data preparation, training, inference.
– Acts as the glue invoking Python modules on the cluster scheduler.
c. Core Python Library
– `source/data_preparation`: PDB download, triangulation, TFRecord creation.
– `source/geometry`, `source/gif_descriptors`: feature‐computation routines.
– `source/input_output`: PDB I/O, mesh handling.
– `source/default_config`: global settings and hyperparameters.
– `source/masif_modules`: neural network layers, data readers, training wrappers.
– `source/masif_site`, `source/masif_ensemble`, `source/masif_ligand`, `source/masif_ppi_search`, `source/conf_ensemble`, `source/triangulation`, `source/pmp_ibs`: pipeline‐specific entry points.
d. Machine-Learning Models
– TensorFlow/PyTorch serialized model files under `data/.../nn_models` and `transformation_training_data/models`.
e. Visualization & Plugin
– `data/*/color_site.sh` and `source/masif_pymol_plugin`: post-hoc coloring of sites in PyMOL.

##### Relationships & Data Flow
1) Raw PDBs & lists → Data preparation scripts (`source/data_preparation`) → triangulated meshes + TFRecords.
2) TFRecords → Feature computation (`source/geometry`, `source/gif_descriptors`) → descriptor files.
3) Descriptor files + default_config → Model training (`source/masif_modules`, pipeline-specific trainers) → serialized NN models.
4) Trained models + new structures → Prediction scripts (`source/…_predict.py`, `*.sh`) → score files.

##### Architectural Patterns & Design Principles
- Layered, modular design:
– Bottom layer: data I/O and mesh handling
– Middle: feature computation
– Top: model training/inference
- Separation of concerns: distinct modules for each MaSIF variant
- HPC integration via Slurm scripts external to the library
- Config-driven behavior via `default_config`

k. Label external dependencies outside boundary: Python runtime, TensorFlow, Slurm scheduler, PyMOL.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage Layer
    RawData["Raw Data / PDB Lists"]:::data
    click RawData "https://github.com/byungukp/masif_pmp/tree/main/data/masif_site"
    click RawData "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ppi_search"
    click RawData "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ensemble"
    click RawData "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ens_ppi"

    MeshTF["Mesh & TFRecord Storage"]:::data
    click MeshTF "https://github.com/byungukp/masif_pmp/tree/main/data/masif_site"
    click MeshTF "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ppi_search"
    click MeshTF "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ensemble"
    click MeshTF "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ens_ppi"

    FeatureDS["Feature Dataset"]:::data

    TrainedModels["Trained Models"]:::data
    click TrainedModels "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ppi_search/nn_models"
    click TrainedModels "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ppi_search/transformation_training_data/models"
    click TrainedModels "https://github.com/byungukp/masif_pmp/tree/main/data/masif_site"
    click TrainedModels "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ensemble"
    click TrainedModels "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ens_ppi"

    Scores["Scores / Results"]:::data

    %% Preprocessing & Feature Computation
    DataPrep["Data Preparation\n(source/data_preparation)"]:::preprocess
    click DataPrep "https://github.com/byungukp/masif_pmp/tree/main/source/data_preparation"

    Geometry["Geometry Computation\n(source/geometry)"]:::preprocess
    click Geometry "https://github.com/byungukp/masif_pmp/tree/main/source/geometry"

    GIF["GIF Descriptor Computation\n(source/gif_descriptors)"]:::preprocess
    click GIF "https://github.com/byungukp/masif_pmp/tree/main/source/gif_descriptors"

    Config["Configuration Loader\n(source/default_config)"]:::preprocess
    click Config "https://github.com/byungukp/masif_pmp/tree/main/source/default_config"

    %% Orchestration Layer
    subgraph "HPC Cluster / Slurm Scheduler"
        direction TB
        SiteScripts["Site Pipeline Scripts"]:::orches
        click SiteScripts "https://github.com/byungukp/masif_pmp/tree/main/data/masif_site"
        PPIScripts["PPI Search Scripts"]:::orches
        click PPIScripts "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ppi_search"
        EnsScripts["Ensemble Pipeline Scripts"]:::orches
        click EnsScripts "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ensemble"
        ENSPPIScripts["ENS_PPI Pipeline Scripts"]:::orches
        click ENSPPIScripts "https://github.com/byungukp/masif_pmp/tree/main/data/masif_ens_ppi"
    end

    %% Machine Learning Modules
    subgraph "Model Training & Inference" 
        direction TB
        MasifModules["ML Modules & Trainers\n(source/masif_modules)"]:::ml
        click MasifModules "https://github.com/byungukp/masif_pmp/tree/main/source/masif_modules"
        SiteEntry["Site Entry Points\n(source/masif_site)"]:::ml
        click SiteEntry "https://github.com/byungukp/masif_pmp/tree/main/source/masif_site"
        PPIEntry["PPI Entry Points\n(source/masif_ppi_search)"]:::ml
        click PPIEntry "https://github.com/byungukp/masif_pmp/tree/main/source/masif_ppi_search"
        EnsembleEntry["Ensemble Entry Points\n(source/masif_ensemble)"]:::ml
        click EnsembleEntry "https://github.com/byungukp/masif_pmp/tree/main/source/masif_ensemble"
        LigandEntry["Ligand Entry Points\n(source/masif_ligand)"]:::ml
        click LigandEntry "https://github.com/byungukp/masif_pmp/tree/main/source/masif_ligand"
        PMPEntry["PMP/IBS Entry Points\n(source/pmp_ibs)"]:::ml
        click PMPEntry "https://github.com/byungukp/masif_pmp/tree/main/source/pmp_ibs"
        ConfEns["Conformational Ensemble\n(source/conf_ensemble)"]:::ml
        click ConfEns "https://github.com/byungukp/masif_pmp/tree/main/source/conf_ensemble"
        Triang["Triangulation & Mesh\n(source/triangulation)"]:::ml
        click Triang "https://github.com/byungukp/masif_pmp/tree/main/source/triangulation"
    end

    %% Visualization
    VizScripts["Visualization Scripts\n(color_site.sh)"]:::orches
    click VizScripts "https://github.com/byungukp/masif_pmp/blob/main/data/masif_site/color_site.sh"
    click VizScripts "https://github.com/byungukp/masif_pmp/blob/main/data/masif_ensemble/color_site.sh"
    click VizScripts "https://github.com/byungukp/masif_pmp/blob/main/data/masif_ens_ppi/color_site.sh"

    PyMOL["PyMOL Plugin\n(source/masif_pymol_plugin)"]:::preprocess
    click PyMOL "https://github.com/byungukp/masif_pmp/tree/main/source/masif_pymol_plugin"

    %% Data Flow
    RawData -->|"PDB lists"| DataPrep
    DataPrep -->|"Meshes + TFRecords"| MeshTF
    MeshTF -->|"TFRecords"| Geometry
    MeshTF -->|"TFRecords"| GIF
    Geometry -->|"Descriptor .npy"| FeatureDS
    GIF -->|"Descriptor .npy"| FeatureDS
    Config -->|"Configs"| FeatureDS

    FeatureDS -->|"Training Data"| MasifModules
    SiteScripts --> MasifModules
    PPIScripts --> MasifModules
    EnsScripts --> MasifModules
    ENSPPIScripts --> MasifModules

    MasifModules -->|"Serialized Models"| TrainedModels
    TrainedModels -->|"Models + TFRecords"| PMPEntry
    TrainedModels -->|"Models + TFRecords"| SiteEntry
    TrainedModels -->|"Models + TFRecords"| PPIEntry
    TrainedModels -->|"Models + TFRecords"| EnsembleEntry
    TrainedModels -->|"Models + TFRecords"| LigandEntry

    SiteEntry -->|"Scores"| Scores
    PPIEntry -->|"Scores"| Scores
    EnsembleEntry -->|"Scores"| Scores
    LigandEntry -->|"Scores"| Scores
    PMPEntry -->|"Scores"| Scores

    Scores --> VisualizationFlow[[ ]]
    VisualizationFlow --> VizScripts
    VizScripts --> PyMOL

    classDef data fill:#a2cffe,stroke:#000;
    classDef preprocess fill:#c2f0c2,stroke:#000;
    classDef ml fill:#ffd27f,stroke:#000;
    classDef orches fill:#e4c2f0,stroke:#000;
```
