# hhhzj-7/deeprsma architecture

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

- Interactive diagram: https://gitdiagram.com/hhhzj-7/deeprsma
- Repository: https://github.com/hhhzj-7/deeprsma

## Overview

##### Project type and purpose
- DeepRSMA is a specialized research-oriented, full-stack machine learning pipeline for predicting RNA–small molecule binding affinity.
- It ingests raw biological data, preprocesses it, builds graph/neural representations, trains deep models, and evaluates under three settings (cross‑validation, blind test, independent test).

##### Top‑level components
a. Data Layer
- Raw datasets in data/RSM_data, data/blind_test, data/independent_data.csv.
- RNA contact maps in data/RNA_contact.
- Pre‑trained RNA embeddings in data/representations_cv and data/representations_independent.
- Molecular vocabulary and tokenizer under data/smiles_vocab.pkl & data/tokenizer.
b. Preprocessing Layer
- process_data_molecule.py & process_data_rna.py: prepare cross‑validation & blind‑test features.
- process_independent_mole.py & process_independent_rna.py: prepare independent‑test features.
- feature.py: extract any additional feature vectors.
c. Representation Generation (external dependency)
- SPOT-RNA-2D and RNA-FM external tools generate RNA contact maps & embeddings.
- These tools feed into data/RNA_contact and data/representations_*.
d. Model Layer
- GNNs: gnn_model_mole.py (molecule graphs), gnn_model_rna.py (RNA graphs).
- Transformer encoder: transformer_encoder.py.
- Cross‑attention fusion: cross_attention.py.
e. Training & Inference Layer
- main_cv.py: orchestrates cross‑validation training & evaluation.
- main_blind.py: blind‑test inference pipeline.
- main_independent.py: independent‑test inference pipeline.
f. Environment & Deployment
- environment.yml: conda specification for reproducibility.

##### Relationships & data flow
- External tools feed into the data layer; environment.yml underpins all components.

##### Architectural patterns & principles
- Pipeline pattern: clearly separated data ingestion, preprocessing, modeling, and evaluation stages.
- Modular code organization: data/, model/, main_*.py as entry points.
- Dependency injection of representations and contact maps (decouples embedding generation from model code).
- Reproducibility via environment.yml.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Data_Raw["Raw RNA–SMILES Data"]:::data
        Data_Blind["Blind-Test Datasets"]:::data
        Data_Independent["Independent Test CSV"]:::data
        RNA_Contact["RNA Contact Maps"]:::data
        Embeddings_CV["Pre-trained RNA Embeddings (CV)"]:::data
        Embeddings_Ind["Pre-trained RNA Embeddings (Independent)"]:::data
        Smiles_Vocab["SMILES Vocab"]:::data
        Tokenizer["Tokenizer"]:::data
        Vocab["Vocab"]:::data
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        Ext_Spot["SPOT-RNA-2D"]:::external
        Ext_FM["RNA-FM"]:::external
    end

    Ext_Spot -->|generates| RNA_Contact
    Ext_FM -->|generates| Embeddings_CV
    Ext_FM -->|generates| Embeddings_Ind

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        direction TB
        Proc_Mole["Molecule Prep (CV/Blind)"]:::preprocess
        Proc_RNA["RNA Prep (CV/Blind)"]:::preprocess
        Proc_Mole_Ind["Molecule Prep (Independent)"]:::preprocess
        Proc_RNA_Ind["RNA Prep (Independent)"]:::preprocess
        Feature["Additional Feature Extraction"]:::preprocess
    end

    Data_Raw --> Proc_Mole
    Data_Blind --> Proc_Mole
    Smiles_Vocab --> Proc_Mole
    Tokenizer --> Proc_Mole
    Data_Raw --> Proc_RNA
    Data_Blind --> Proc_RNA
    Data_Independent --> Proc_Mole_Ind
    Data_Independent --> Proc_RNA_Ind
    Data_Raw --> Feature
    Data_Blind --> Feature
    Data_Independent --> Feature

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        GNN_Mole["GNN Molecule Encoder"]:::model
        GNN_RNA["GNN RNA Encoder"]:::model
        Transformer["Transformer Encoder"]:::model
        Cross_Att["Cross-Attention Fusion"]:::model
    end

    Proc_Mole --> GNN_Mole
    Proc_Mole_Ind --> GNN_Mole
    Proc_RNA --> GNN_RNA
    Proc_RNA_Ind --> GNN_RNA
    Embeddings_CV --> Transformer
    Embeddings_Ind --> Transformer
    GNN_Mole --> Cross_Att
    GNN_RNA --> Cross_Att
    Transformer --> Cross_Att
    Feature --> Cross_Att

    %% Entry-Point Scripts
    subgraph "Training & Inference"
        direction TB
        Main_CV["main_cv.py"]:::entry
        Main_Blind["main_blind.py"]:::entry
        Main_Ind["main_independent.py"]:::entry
    end

    Cross_Att --> Main_CV
    Cross_Att --> Main_Blind
    Cross_Att --> Main_Ind

    %% Environment
    Env["environment.yml"]:::env

    Env -.-> Proc_Mole
    Env -.-> Proc_RNA
    Env -.-> GNN_Mole
    Env -.-> Transformer
    Env -.-> Main_CV

    %% Click Events
    click Data_Raw "https://github.com/hhhzj-7/deeprsma/tree/master/data/RSM_data"
    click Data_Blind "https://github.com/hhhzj-7/deeprsma/tree/master/data/blind_test"
    click Data_Independent "https://github.com/hhhzj-7/deeprsma/blob/master/data/independent_data.csv"
    click RNA_Contact "https://github.com/hhhzj-7/deeprsma/tree/master/data/RNA_contact"
    click Embeddings_CV "https://github.com/hhhzj-7/deeprsma/tree/master/data/representations_cv"
    click Embeddings_Ind "https://github.com/hhhzj-7/deeprsma/tree/master/data/representations_independent"
    click Smiles_Vocab "https://github.com/hhhzj-7/deeprsma/blob/master/data/smiles_vocab.pkl"
    click Tokenizer "https://github.com/hhhzj-7/deeprsma/blob/master/data/tokenizer/tokenizer.py"
    click Vocab "https://github.com/hhhzj-7/deeprsma/blob/master/data/vocab.py"
    click Proc_Mole "https://github.com/hhhzj-7/deeprsma/blob/master/data/process_data_molecule.py"
    click Proc_RNA "https://github.com/hhhzj-7/deeprsma/blob/master/data/process_data_rna.py"
    click Proc_Mole_Ind "https://github.com/hhhzj-7/deeprsma/blob/master/data/process_independent_mole.py"
    click Proc_RNA_Ind "https://github.com/hhhzj-7/deeprsma/blob/master/data/process_independent_rna.py"
    click Feature "https://github.com/hhhzj-7/deeprsma/blob/master/data/feature.py"
    click GNN_Mole "https://github.com/hhhzj-7/deeprsma/blob/master/model/gnn_model_mole.py"
    click GNN_RNA "https://github.com/hhhzj-7/deeprsma/blob/master/model/gnn_model_rna.py"
    click Transformer "https://github.com/hhhzj-7/deeprsma/blob/master/model/transformer_encoder.py"
    click Cross_Att "https://github.com/hhhzj-7/deeprsma/blob/master/model/cross_attention.py"
    click Main_CV "https://github.com/hhhzj-7/deeprsma/blob/master/main_cv.py"
    click Main_Blind "https://github.com/hhhzj-7/deeprsma/blob/master/main_blind.py"
    click Main_Ind "https://github.com/hhhzj-7/deeprsma/blob/master/main_independent.py"
    click Env "https://github.com/hhhzj-7/deeprsma/blob/master/environment.yml"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef preprocess fill:#90EE90,stroke:#333,stroke-width:1px
    classDef model fill:#FFA500,stroke:#333,stroke-width:1px
    classDef entry fill:#C183C0,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef env fill:#CCCCCC,stroke:#333,stroke-width:1px
```
