# lpdi-epfl/masif architecture

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

- Interactive diagram: https://gitdiagram.com/lpdi-epfl/masif
- Repository: https://github.com/lpdi-epfl/masif

## Overview

##### Core System Layers and Components
- Data Ingestion & Preprocessing: At the base lie the raw protein structural data and PDB inputs. This module involves external tools (e.g., MSMS, Reduce, PDB2PQR, APBS, BioPython, PyMesh, open3D) used to download protein structures, add protons, compute surfaces and chemical features, and ultimately decompose protein surfaces into patches.
- Deep Learning & Descriptor Computation: Central to the workflow is the neural network module (built with TensorFlow). Here, “geodesic convolution” layers process patches and output surface fingerprint descriptors. This component also branches into sub-applications:
– MaSIF-ligand: For ligand binding pocket prediction.
– MaSIF-site: For identifying protein–protein interaction sites.
– MaSIF-search: For fast scanning and matching protein surfaces.
- Model Training and Evaluation: Includes components for training (with job slurm scripts, GPU support), evaluation (storing outputs such as logits and labels) and caching data (e.g., tfrecords, cached training pairs).
- Visualization & Reporting: The final outputs are visualized via a PyMOL plugin (source/pymol_plugin) and even web assets for rendering images (e.g., molecular surface renderings) and possibly further analysis notebooks.
- Infrastructure & Deployment: Finally, encapsulate the containerized deployment (Docker tutorial) and integration with HPC clusters (SLURM job scripts) for large-scale processing.

##### Relationships and Data Flow
- Connectors should show how external tools (MSMS, APBS, etc.) are invoked during the data preparation steps.
- Transformation of data into different intermediate representations (PDB files to surface meshes, then to patch files, then to TensorFlow-compatible TFRecords, and finally to neural network predictions).

##### Architectural Patterns and Technologies
- Pipeline Orchestration & Distributed Execution: Emphasize the use of shell scripts and SLURM files to asynchronously process large datasets on clusters.
- Modular Design: The repository is split into “source”, “data”, “comparison”, “docker_tutorial.md”, and others, showing a modular division between production code (in source/masif_modules, source/masif_site, etc.) and data preparation pipelines.
- Configuration & Reusability: Note the “default_config” directory that provides global variables and options which configure different modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        A1["Raw Protein Data"]:::data
        A2["Data Preparation Scripts"]:::data
        A3["Default Configurations"]:::data
        A4["PDB/Ligand Slurm Jobs"]:::data
    end

    %% Feature Extraction & Patch Generation
    subgraph "Feature Extraction & Patch Generation"
        B1["Surface Computation"]:::feature
        B2["Triangulation Module"]:::feature
        B3["Geometry Computation"]:::feature
        B4["Mesh I/O Operations"]:::feature
    end

    %% Deep Learning & Descriptor Computation
    subgraph "Deep Learning & Descriptor Computation"
        C1["Neural Network Module"]:::deep
        C2["MaSIF-ligand"]:::deep
        C3["MaSIF-ligand Core"]:::deep
        C4["MaSIF-site"]:::deep
        C5["MaSIF-site Core"]:::deep
        C6["MaSIF-search"]:::deep
        C7["MaSIF-search Core"]:::deep
    end

    %% Model Training & Evaluation
    subgraph "Model Training & Evaluation"
        D1["Training & Evaluation"]:::train
        D2["Ligand Training"]:::train
        D3["Site Training"]:::train
        D4["Search Training"]:::train
        D5["SLURM Job Scripts"]:::train
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        E1["PyMOL Plugin"]:::viz
        E2["Plugin Documentation"]:::viz
        E3["Rendered Images"]:::viz
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        F1["Container Deployment"]:::deploy
        F2["Cluster SLURM Jobs"]:::deploy
    end

    %% Data Flow Connections
    A1 --> A2
    A2 --> B1
    A3 --> B1
    A4 --> B1

    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> C1

    C1 --> C2
    C2 --> C3
    C1 --> C4
    C4 --> C5
    C1 --> C6
    C6 --> C7
    C1 --> D1

    D1 --> D2
    D1 --> D3
    D1 --> D4
    D2 --> D5
    D3 --> D5
    D4 --> D5

    D5 --> E1
    E1 --> E2
    E1 --> E3

    D1 --> F2
    F2 --> F1

    %% Click Events
    click A2 "https://github.com/lpdi-epfl/masif/tree/master/source/data_preparation"
    click A3 "https://github.com/lpdi-epfl/masif/tree/master/source/default_config"
    click A4 "https://github.com/lpdi-epfl/masif/tree/master/data/masif_ligand"
    click B2 "https://github.com/lpdi-epfl/masif/tree/master/source/triangulation"
    click B3 "https://github.com/lpdi-epfl/masif/tree/master/source/geometry"
    click B4 "https://github.com/lpdi-epfl/masif/tree/master/source/input_output"
    click C2 "https://github.com/lpdi-epfl/masif/tree/master/source/masif_ligand"
    click C3 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_modules/MaSIF_ligand.py"
    click C4 "https://github.com/lpdi-epfl/masif/tree/master/source/masif_site"
    click C5 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_modules/MaSIF_site.py"
    click C6 "https://github.com/lpdi-epfl/masif/tree/master/source/masif_ppi_search"
    click C7 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_modules/MaSIF_ppi_search.py"
    click D2 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_ligand/masif_ligand_train.py"
    click D3 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_site/masif_site_train.py"
    click D4 "https://github.com/lpdi-epfl/masif/blob/master/source/masif_ppi_search/masif_ppi_search_train.py"
    click D5 "https://github.com/lpdi-epfl/masif/blob/master/data/masif_ppi_search/masif_ppi_search_comp_desc.slurm"
    click E1 "https://github.com/lpdi-epfl/masif/tree/master/source/masif_pymol_plugin"
    click E2 "https://github.com/lpdi-epfl/masif/blob/master/pymol_plugin_installation.md"
    click E3 "https://github.com/lpdi-epfl/masif/tree/master/img"
    click F1 "https://github.com/lpdi-epfl/masif/blob/master/docker_tutorial.md"
    click F2 "https://github.com/lpdi-epfl/masif/blob/master/data/masif_ligand/data_prepare.slurm"

    %% Styles
    classDef data fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef feature fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef deep fill:#a9dfbf,stroke:#28b463,stroke-width:2px;
    classDef train fill:#f5cba7,stroke:#e67e22,stroke-width:2px;
    classDef viz fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef deploy fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
