# antoniofrancaib/grnadex architecture

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

- Interactive diagram: https://gitdiagram.com/antoniofrancaib/grnadex
- Repository: https://github.com/antoniofrancaib/grnadex

## Overview

##### Project type and purpose
- gRNAde is a domain-specific ML pipeline for 3D RNA inverse design, akin to ProteinMPNN but for RNA.
- It ingests raw or preprocessed 3D RNA structures, featurizes them into geometric graphs, trains an equivariant multi-state GNN encoder with a sequence design head, and outputs novel RNA sequences for given backbone conformations.

##### High-level architecture and directory overview
- **Top-level directories**
· configs: YAML configuration files (training, evaluation, sweeps)
· data: raw, processed datasets, split metadata, scripts
· checkpoints: saved model weights (.h5)
· notebooks/tutorial: interactive examples, demos, tutorials
· src: core Python modules (data loaders, featurizer, models, trainer, evaluator)
· tools: third-party binaries and model checkpoints (ViennaRNA, RhoFold, ribonanzanet, x3dna)
· logs: stdout/err of past runs
- **Key scripts**
· main.py: orchestrates training / evaluation runs based on configs
· gRNAde.py: CLI wrapper for inference and design use cases
· data/process_data.py: pipeline to convert raw PDBs → ML-ready `.pt` files
· trainer.py / evaluator.py: training and eval loops
· layers.py / models.py: GNN architecture definitions
· sampling.py: sampling strategies for sequence generation

##### Main components
a. **Data ingestion & preprocessing**
- Raw 3D structures from RNAsolo or preprocessed `.pt` files in data/
- External tools invoked: x3dna for secondary structure determination, CD-HIT/US-align for clustering
- Script: data/process_data.py → outputs processed data stored under data/
b. **Dataset and featurization**
- src/data/dataset.py: batch sampler for single- or multi-state design splits
- src/data/featurizer.py & clustering_utils/sec_struct_utils: build geometric graph features (coordinates, edges, sec-structure)
c. **Model training & evaluation**
- src/models.py / src/layers.py: equivariant multi-state GNN encoder + sequence design head
- src/trainer.py: training loop with configurable hyperparameters (configs/*.yaml)
- src/evaluator.py: metrics computation, evaluation on held-out splits
- Logging to console, logs/ directory, optional wandb integration
d. **Inference / CLI**
- gRNAde.py: command-line interface to run single- or multi-state design predictions using trained checkpoints
e. **Notebooks & tutorial**
- Jupyter notebooks for demonstration and interactive design workflows
- tutorial/tutorial.py & tutorial.ipynb for end-to-end example

##### Component interactions and data flow
1. **External data sources** → data/raw/ (or preprocessed .pt)
2. **Preprocessing pipeline** (data/process_data.py + external tools) → data/processed.pt, data/split_ids
3. **Dataset loader & featurizer** (src/data/)
4. **Model** (src/layers.py + src/models.py)
5. **Training loop** (main.py → src/trainer.py) ↔ configs/*.yaml
6. **Checkpoint storage** → checkpoints/
7. **Evaluation loop** (main.py → src/evaluator.py) → logs/, evaluation metrics
8. **Inference CLI** (gRNAde.py) → new sequence outputs
9. **Notebooks** reference all above modules for interactive use

##### Architectural patterns & design principles
- **Modular layering**: clear separation of data, model, training, evaluation, CLI, and tutorials
- **Config-driven workflows**: Hydra-style or YAML-based parameterization
- **Plug-and-play external tools**: ViennaRNA, RhoFold, etc., wrapped under tools/
- **Equivariant GNN**: 3D roto-translation invariance captured in layers modules

##### Detail without over- compartmentalizing
- Six subsystems (Ingestion, Preprocessing, Featurization, Modeling, Training/Eval, Inference)
- Inter-relationships (e.g., Preprocessing invokes external tools; Training reads configs and writes checkpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Layer"
        direction TB
        RawData["Raw 3D Structures (data/raw/)"]:::data
        Preprocess["Preprocessing Script"]:::compute
        DataStore["Processed Data Store (data/)"]:::store
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        X3DNA["x3dna"]:::tool
        ViennaRNA["ViennaRNA"]:::tool
        RhoFold["RhoFold"]:::tool
        Ribona1["ribonanzanet"]:::tool
        Ribona2["ribonanzanet_sec_struct"]:::tool
    end

    %% Feature Engineering
    subgraph "Feature Engineering"
        direction TB
        DatasetLoader["Dataset Loader & Splits"]:::compute
        Featurizer["Graph Featurizer"]:::compute
        SecStruct["Secondary Structure Utils"]:::compute
        Clustering["Clustering Utils"]:::compute
    end

    %% Modeling
    subgraph "Modeling"
        direction TB
        ModelsDef["Model Definitions (src/models.py)"]:::compute
        LayersDef["Layer Definitions (src/layers.py)"]:::compute
        Model["Equivariant GNN + Design Head"]:::compute
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        direction TB
        Config["Config Files (configs/)"]:::config
        Orchestrator["Orchestration Script (main.py)"]:::compute
        Training["Training Loop"]:::compute
        Eval["Evaluation Loop"]:::compute
        Sampling["Sampling Strategies"]:::compute
        Checkpoints["Checkpoint Storage (checkpoints/)"]:::store
        Logs["Logs (logs/)"]:::store
    end

    %% Inference & Tutorials
    subgraph "UI / Tutorials"
        direction TB
        CLI["CLI Inference (gRNAde.py)"]:::ui
        Notebook["Jupyter Notebooks (notebooks/)"]:::ui
        Tutorial["Tutorial Scripts"]:::ui
    end

    %% Data Flow
    RawData -->|provides| Preprocess
    Preprocess -->|uses| X3DNA
    Preprocess -->|uses| ViennaRNA
    Preprocess -->|uses| RhoFold
    Preprocess -->|uses| Ribona1
    Preprocess -->|uses| Ribona2
    Preprocess -->|outputs| DataStore

    DataStore -->|loaded by| DatasetLoader
    DatasetLoader -->|feeds| Featurizer
    SecStruct -->|supports| Featurizer
    Clustering -->|supports| Featurizer
    Featurizer -->|features| Model

    ModelsDef -->|defines| Model
    LayersDef -->|defines| Model

    Model -->|trained by| Training
    Config -->|parameters| Orchestrator
    Orchestrator -->|invokes| Training
    Orchestrator -->|invokes| Eval
    Training -->|saves| Checkpoints
    Training -->|logs to| Logs
    Eval -->|logs to| Logs
    Eval -->|evaluates| Checkpoints
    Training -->|uses| Sampling

    Checkpoints -->|used by| CLI
    CLI -->|outputs| DataStore
    Notebook -->|references| Model
    Notebook -->|references| DatasetLoader
    Notebook -->|references| CLI
    Tutorial -->|demonstrates| Notebook

    %% Click Events
    click Config "https://github.com/antoniofrancaib/grnadex/tree/main/configs/"
    click Preprocess "https://github.com/antoniofrancaib/grnadex/blob/main/data/process_data.py"
    click DataStore "https://github.com/antoniofrancaib/grnadex/tree/main/data/"
    click DatasetLoader "https://github.com/antoniofrancaib/grnadex/blob/main/src/data/dataset.py"
    click Featurizer "https://github.com/antoniofrancaib/grnadex/blob/main/src/data/featurizer.py"
    click SecStruct "https://github.com/antoniofrancaib/grnadex/blob/main/src/data/sec_struct_utils.py"
    click Clustering "https://github.com/antoniofrancaib/grnadex/blob/main/src/data/clustering_utils.py"
    click ModelsDef "https://github.com/antoniofrancaib/grnadex/blob/main/src/models.py"
    click LayersDef "https://github.com/antoniofrancaib/grnadex/blob/main/src/layers.py"
    click Training "https://github.com/antoniofrancaib/grnadex/blob/main/src/trainer.py"
    click Eval "https://github.com/antoniofrancaib/grnadex/blob/main/src/evaluator.py"
    click Orchestrator "https://github.com/antoniofrancaib/grnadex/blob/main/main.py"
    click Sampling "https://github.com/antoniofrancaib/grnadex/blob/main/src/sampling.py"
    click CLI "https://github.com/antoniofrancaib/grnadex/blob/main/gRNAde.py"
    click Checkpoints "https://github.com/antoniofrancaib/grnadex/tree/main/checkpoints/"
    click Logs "https://github.com/antoniofrancaib/grnadex/tree/main/logs/"
    click Notebook "https://github.com/antoniofrancaib/grnadex/tree/main/notebooks/"
    click Tutorial "https://github.com/antoniofrancaib/grnadex/blob/main/tutorial/tutorial.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef store fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef tool fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef compute fill:#98FB98,stroke:#000,stroke-width:1px
    classDef config fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#000,stroke-width:1px
```
