1. Project Background and Overview 🌍

RDiffusion is a diffusion-based framework for RNA sequence design and generation. It combines diffusion generation with task-specific guidance models, and supports both single-task and multi-task constraints during inference. Typical applications include functional family targeting, disease association, protein-RNA binding, secondary structure constraints, 3D structure conditions, UTR optimization, and Cas13 guide design.

2. Key Features ⭐

• 🚪 Unified Inference Entry Use inference.py as the single entry point for uncon, text, rfam, disease, prot_rna_bind, ss, ts, utr, and cas13.

• 🧠 Multi-task Guidance Support joint multi-task guidance with per-task guidance scale control.

• 🧪 Rich Conditioning Inputs Support diverse condition types, including family/label, text functional conditions, secondary structure, icshape, PDB structure, and Cas13 target context.

• 🎨 Flexible Generation Modes Support template masking generation, partial seed preservation, and position-specific design via design_pos.

• 📚 Batch Inference by JSON Load a JSON list through data_path for large-scale batch inference.

• 📤 Ready-to-Export Results Export outputs directly as JSON files under infer_results for downstream evaluation and visualization.

---

3. Environment Setup 🛠️

It is recommended to create the environment from install.sh in the project root.

3.1 Create the Environment 🧱

conda create -n RDiffusion python=3.8.11

3.2 Activate the Environment ⚡

conda activate RDiffusion

3.3 Install neccessary packages ⚡

bash install.sh

3.4 Quick Check ✅

python inference.py --help

If this command prints the argument help message correctly, the inference entry and required dependencies are ready.

3.5 Pretrained Models 📦

RDiffusion pretrained models can be downloaded from:

https://modelscope.cn/models/wj1006/RDiffusion/files

After downloading, place all model files into the checkpoints folder.

The following checkpoints are used by this repository:

• pretrained_gen.pt - Base diffusion generator checkpoint. Recommended default for uncon and text tasks.

• rfam_gen.pt - Diffusion generator checkpoint specialized for RFAM family-conditioned generation.

• rfam_guidance.pt - Guidance classifier checkpoint for RFAM label guidance during sampling.

• disease_gen.pt - Diffusion generator checkpoint for disease-related RNA generation.

• disease_guidance.pt - Guidance classifier checkpoint for disease target guidance.

• prot_rna_bind_gen.pt - Diffusion generator checkpoint for protein-RNA binding related generation.

• prot_rna_bind_guidance.pt - Multi-label guidance checkpoint for protein binding targets.

• ss_gen.pt - Diffusion generator checkpoint for secondary structure (SS) task.

• ts_gen.pt - Diffusion generator checkpoint for tertiary structure (TS) conditioned task.

• utr_gen.pt - Diffusion generator checkpoint for UTR task.

• utr_guidance.pt - Guidance checkpoint for UTR optimization/regression objective.

• cas13_gen.pt - Diffusion generator checkpoint for Cas13 guide design.

• cas13_guidance.pt - Guidance checkpoint for Cas13 activity-aware generation.

3.6 Test Data 📁

RDiffusion test data can be downloaded from:

https://modelscope.cn/models/wj1006/RDiffusion_test_data

After downloading, place the files into the corresponding project data directories as needed (for example under test_data/).

---

4. Tasks and Usage Examples 🧭

All examples below should be run from the project root. Detailed tutorials for all supported tasks are provided in the tutorials/ folder.

4.1 uncon (Unguided Generation) 🎲

Run diffusion sampling without any task guidance.

python inference.py \
  --tasks uncon \
  --lens 120 \
  --diffusion_model_path checkpoints/pretrained_gen.pt \
  --num_samples 5 \
  --output_path results/infer_results/uncon_infer.json

4.2 text (Text-Conditioned Generation) 📝

Generate RNA sequences conditioned only by a text prompt (func_cond). This task does not load any guidance model, and by default uses checkpoints/pretrained_gen.pt.

python inference.py \
  --tasks text \
  --diffusion_model_path checkpoints/pretrained_gen.pt \
  --func_cond "RNA aptamer with high stability" \
  --lens 120 \
  --num_samples 5 \
  --output_path results/infer_results/text_infer.json

4.3 rfam (Family Guidance) 👪

Apply class-level constraints using RFAM family targets.

python inference.py \
  --tasks rfam \
  --rfam_target RF00001 \
  --diffusion_model_path checkpoints/rfam_gen.pt \
  --guidance_scale 1.0 \
  --num_samples 5 \
  --lens 120 \
  --update_by_guide \
  --update_all \
  --output_path results/infer_results/rfam_infer.json

4.4 disease (Disease Association Guidance For miRNA) 🏥

Guide generation using disease labels.

python inference.py \
  --tasks disease \
  --disease_target Osteoarthritis \
  --diffusion_model_path checkpoints/disease_gen.pt \
  --guidance_scale 1.0 \
  --lens 20 \
  --num_samples 10 \
  --update_by_guide \
  --update_all \
  --output_path results/infer_results/disease_infer.json

4.5 prot_rna_bind (Protein Binding Guidance) 🔗

Guide generation using a list of protein names (multi-label). Use -ProteinName to indicate a negative target (reduce binding probability to that protein).

python inference.py \
  --tasks prot_rna_bind \
  --protein_targets EIF4G2,TRA2A \
  --diffusion_model_path checkpoints/prot_rna_bind_gen.pt \
  --guidance_scale 1.0 \
  --lens 101 \
  --num_samples 5 \
  --update_by_guide \
  --update_all \
  --output_path results/infer_results/prot_rna_bind_infer.json

# Mixed positive/negative targets: increase CAPRIN1 binding and suppress AARS binding.
python inference.py \
  --tasks prot_rna_bind \
  --protein_targets CAPRIN1,-AARS \
  --diffusion_model_path checkpoints/prot_rna_bind_gen.pt \
  --guidance_scale 1.0 \
  --lens 101 \
  --num_samples 5 \
  --update_by_guide \
  --update_all \
  --output_path results/infer_results/prot_rna_bind_infer_mixed.json

4.6 ss (Secondary Structure Conditioning) 🧵

Use dot-bracket secondary structure conditions for guided design.

python inference.py \
  --tasks ss \
  --diffusion_model_path checkpoints/ss_gen.pt \
  --secondary_structure "(((...)))..." \
  --lens 12 \
  --num_samples 3 \
  --update_by_guide \
  --update_all \
  --output_path results/infer_results/ss_infer.json

💡 Note: The ss task depends on ERNIE-RNA related model checkpoints/arguments (defaults are already provided in the script).

4.7 ts (Tertiary Structure Conditioning) 🧊

Use encoded PDB structure features as condition input.

python inference.py \
  --tasks ts \
  --diffusion_model_path checkpoints/ts_gen.pt \
  --pdb_path /path/to/example.pdb \
  --num_samples 3 \
  --argmax \
  --output_path results/infer_results/ts_infer.json

4.8 utr (UTR Regression Guidance) 📈

Run generation with UTR guidance.

python inference.py \
  --tasks utr \
  --diffusion_model_path checkpoints/utr_gen.pt \
  --num_samples 5 \
  --output_path results/infer_results/utr_infer.json

4.9 cas13 (Cas13 Guide Sequence Design) ✂️

Build full context from target_before, target_at_guide, and target_after, then output guide_seq.

python inference.py \
  --tasks cas13 \
  --diffusion_model_path checkpoints/cas13_gen.pt \
  --target_before GAAGGAGCTTGAGCTCAAAA \
  --target_at_guide GCTCTGAAAACAAGCGCATCTCTAGAGA \
  --target_after CAAATAATCTCCATGACTAG \
  --num_samples 5 \
  --output_path results/infer_results/cas13_infer.json

4.10 Multi-task Joint Example 🤝

For example, RFAM + protein binding joint guidance:

python inference.py \
  --tasks rfam,prot_rna_bind \
  --rfam_target RF00001 \
  --diffusion_model_path checkpoints/prot_rna_bind_gen.pt(pretrained_gen.pt/rfam_gen.pt) \
  --protein_targets CAPRIN1 \
  --guidance_scales '{"rfam":1.4,"prot_rna_bind":1.1}' \
  --num_samples 5 \
  --output_path results/infer_results/multi_task_infer.json

4.11 Batch JSON Inference Example 📦

data_path should point to a JSON list, where each item defines one sample input (for example template, targets, and other fields).

python inference.py \
  --tasks rfam \
  --diffusion_model_path checkpoints/prot_rna_bind_gen.pt \
  --data_path results/infer_results/test_rfam.json \
  --output_path results/infer_results/rfam_batch_infer.json

---

5. Key Parameters (Selected) 🔑

The following are the most commonly used and important parameters.

• 🎯 tasks Task type. Supports a single task or comma-separated multi-task input. Available values: uncon, text, rfam, disease, prot_rna_bind, ss, ts, utr, cas13.

• 🧬 template Initial template sequence. If provided, generation/design is performed on top of this template according to mask_ratio or design_pos.

• 📏 lens Target generation length. Especially important when template is not provided.

• 🔁 num_samples Number of samples to generate per input.

• 🧭 guidance_scale Global guidance strength.

• 🔄 update_by_guide Whether to enable gradient-based guidance updates from guidance models during sampling. For tasks without guidance model (uncon, text, ts), this flag has no effect.

• 🔁 update_all Whether each guidance update modifies logits at all masked positions (True) or only the current sampled position (False). In practice, True usually gives stronger guidance but can be less diverse.

• 📝 func_cond Plain text condition string. This is required for task text, and should be natural language text (not a label ID).

• 🎭 mask_ratio Ratio of positions to mask in template-based generation. Larger values increase novelty, smaller values preserve more from template.

• 🧠 guidance_scales Task-level guidance strengths in JSON format, for example {"rfam":1.5,"ss":2.0}.

• ✏️ design_pos Specify design position ranges, for example 88-115 or (5-9,10-17,19-25).

• 🗂️ data_path Path to batch input JSON. When set, each record is sampled once, which is suitable for batch processing.

• 🔗 protein_targets Comma-separated protein names for prot_rna_bind. Prefix with - to suppress binding to that protein (for example CAPRIN1,-AARS).

• 📤 output_path Path to output JSON results.

• 🧩 secondary_structure / icshape / pdb_path Inputs for ss conditioning, icshape conditioning, and ts 3D structure conditioning, respectively.

---

6. Directory Structure 🗺️

The following is the core inference-related structure (non-essential details omitted).

RDiffusion/
├── inference.py
├── install.sh
├── checkpoints/
├── figures/
│   └── RDiffusion_workflow.pdf
├── results/
│   └── infer_results/
├── docs/
└── src/
    ├── design/
    ├── guidance_models/
    ├── models/
    ├── data/
    ├── utils/
    ├── ERNIE-RNA/
    ├── structure_encoder/
    ├── evaluation/
    └── visualization/

---

7. Practical Running Tips 🧠

• 🧪 For first-time validation, start with a single task (for example ss or rfam) to confirm checkpoints and environment are working correctly.
• 📉 For multi-task runs, start with smaller guidance_scales and increase them gradually.
• 🔍 If using data_path for batch processing, begin with a small smoke test of 2-3 samples.

To extend with new tasks, start from inference.py and the inference_* modules under src/utils.

8. License

This source code is released under the MIT License. See the LICENSE file in the root directory for details.

Our framework and model training were inspired by the following outstanding open-source projects:

• RNA-FM
• ERNIE-RNA
• geometric-rna-design

We sincerely thank the authors of these works for providing excellent foundations for RDiffusion.