How antoniofrancaib/grnadex works
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)