BRIDGE: Bridging Sequence–Structure Motifs and Genetic Variants for Genome-wide Dynamic RNA–Protein Interaction Profiling

📑 Table of Contents

• 📑 Table of Contents
• 🔬Overview
• ⚙️Environment Setup
  • Tested Environment
  • 1) Prerequisites
  • 2) Recommended installation (Conda)
  • 3) Running in docker (Optional)
    • Step 1: Install Docker
    • Step 2: Build and run the Docker image
      • GPU users
      • CPU users
  • Sanity-Check for Environment Setup
• 📂Data & Resources
  • Download from
  • Verify downloaded files
• 📚 API Documentation
  • API Overview
• 🚀Usage
  • 1) Train
    • GPU version (default)
    • CPU version (force CPU)
  • 2) Validate (Evaluate a saved model)
    • GPU version (default)
    • CPU version (force CPU)
  • 3) Dynamic Transfer Prediction (Cross–cell-type)
    • GPU version (default)
    • CPU version (force CPU)
  • 4) Variant-Aware Scoring
    • GPU version
    • CPU version (force CPU)
  • 5) Motif construction
    • Step 1: Generate attention maps for motif visualization
    • Step 2: Discover motifs from attention maps
• 📘 Step-by-Step Tutorials
  • Workflow Map
    • Core modeling workflows
    • Variant-aware scoring workflows
    • Motif extraction & visualization workflow
• 🧪 Reproducibility (Figures & Supplementary Figures)
  • Notes
• 📜License
• 📚Citation
• 🤝Acknowledgements
• 💬User Support

🔬Overview

BRIDGE is an advanced multimodal deep learning framework for predicting dynamic RNA–protein binding landscapes and assessing the functional impact of genetic variants across multiple human cell types. It leverages a unified architecture that integrates:

• Sequence embeddings from pretrained Transformer models to capture rich contextual nucleotide representations.
• RNA secondary structure features to model the spatial and thermodynamic constraints on RBP binding.
• Motif priors derived from de novo motif discovery (STREME) to incorporate known binding patterns.
• Biochemical profiles capturing experimental signals such as reactivity, accessibility, and conservation.
• Graph-based attention modeling to represent long-range dependencies between nucleotides via token-wise relational graphs.

By fusing these complementary modalities, BRIDGE can accurately characterize both conserved and dynamic binding preferences, enabling:

• End-to-end model training and evaluation on large-scale eCLIP/HITS-CLIP datasets.
• Dynamic cross-cell-type transfer prediction, where the model generalizes to unseen cellular contexts without fine-tuning.
• Variant-aware inference, assessing the functional impact of genetic variants (e.g., SNVs) on RBP binding to facilitate disease and trait association studies.
• Explicit motif extraction highlighting dynamic sequence–structure patterns learned from the fused modalities.

This multimodal and interpretable design positions BRIDGE as a powerful tool for dissecting post-transcriptional regulation, guiding functional genomics studies, and prioritizing disease-associated variants with potential regulatory impact.

⚙️Environment Setup

Tested Environment

BRIDGE is platform-agnostic and can run on Linux, macOS, and Windows (via WSL). Below are the hardware and software we have tested to ensure reproducibility:

GPU	VRAM	Driver version	CUDA version
NVIDIA A40	48 GB	550.54.14	12.4
NVIDIA L40	48 GB	550.54.14	12.4
Quadro RTX 6000	24 GB	550.54.14	12.4
NVIDIA GeForce RTX 3090	24 GB	580.95.05	13.0
NVIDIA TITAN RTX	24 GB	580.95.05	13.0

1) Prerequisites

The following table summarizes the key software dependencies and the tested versions for BRIDGE:

Package	Stable version
python	3.10.10
torch	2.0.1
torchvision	0.15.2
torch-geometric	2.6.1
transformers	4.41.2
tokenizers	0.19.1
numpy	1.23.5
scipy	1.10.1
pandas	2.0.0
scikit-learn	1.6.1
biopython	1.85
viennarna	2.6.4
tqdm	4.67.1
matplotlib	3.4.1
seaborn	0.13.2
captum	0.7.0
shap	0.41.0

2) Recommended installation (Conda)

# Create and activate an environment
conda env create -f BRIDGE.yml
conda activate BRIDGE

3) Running in docker (Optional)

If you prefer a fully containerized environment, BRIDGE can also run in Docker.

Step 1: Install Docker

Download and install the latest Docker version for your platform: Docker Installers.

To enable GPU access inside Docker, install the NVIDIA Container Toolkit.

Step 2: Build and run the Docker image

GPU users

Build the image:

docker build -f Dockerfile.gpu -t bridge:gpu .

Launch a container with GPU support:

docker run --rm -it --gpus all bridge:gpu

CPU users

Build the image:

docker build -f Dockerfile.cpu -t bridge:cpu .

Launch a container with CPU support:

docker run --rm -it bridge:cpu

Sanity-Check for Environment Setup

To verify that the environment has been set up correctly and avoid dependency conflicts, especially with PyTorch and PyTorch Geometric, you can check the installed versions directly in the command line. Run the following commands to ensure that the necessary libraries are correctly installed and compatible.

Run these commands:

# Check PyTorch version and CUDA availability
python -c "import torch; print('torch:', torch.__version__, 'cuda:', torch.version.cuda, 'cuda_available:', torch.cuda.is_available())"

# Check PyTorch Geometric version
python -c "import torch_geometric; print('torch-geometric:', torch_geometric.__version__)"

This will display the installed versions of PyTorch and PyTorch Geometric, as well as the CUDA version and availability. An example output might look like this:

torch: 2.0.1+cu117 cuda: 11.7 cuda_available: True
torch-geometric: 2.6.1

If the versions match the recommended ones in the prerequisites section, the PyTorch and PyTorch Geometric are correctly set up.

📂Data & Resources

To ensure reproducibility and ease of use, we provide all necessary resources pre-packaged for BRIDGE:

Resource	Path (after extraction)	Description
🔹 Raw Data	BRIDGE/dataset/	Input RNA tracks for model training/testing
🔹 Variant FASTA	BRIDGE/dataset_variant/	Variant-aware inference inputs (FASTA format)
🔹 RBPformer	BRIDGE/RBPformer/	Pretrained Transformer model
🔹 Motif Priors	BRIDGE/utils/motif_prior/output/	Precomputed motif prior files for all RBPs
🔹 Model Files	BRIDGE/results/model/	Trained BRIDGE models
🔹 Reproducibility	BRIDGE/results/reproducibility/	Reproducible resources

Download from

Figshare

Verify downloaded files

To guarantee data integrity and exact alignment with the reported results, we provide SHA256 checksums for released files, together with a verification script.

python verify_checksums.py \
  --checksum checksums.sha256 \
  --data_dir ./

After verifying, you can extract the files to the corresponding locations under BRIDGE root directory.

📚 API Documentation

BRIDGE provides a flexible and extensible API for users to interact with the models, datasets, and results. You can use the API to automate tasks, query results, and integrate BRIDGE with other systems.

API Overview

The BRIDGE API exposes several endpoints that allow you to interact with core functionalities such as training models, evaluating performance, and accessing predictions.

For a detailed guide on using the API, please refer to the full API documentation.

🚀Usage

Below are GPU and CPU versions of each command. Use --use_cpu to force CPU even when GPUs are available.

1) Train

GPU version (default)

python main.py \
    --train \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --device_num 0 \
    --seed 42 \
    --early_stopping 20 \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model \
    --lr 0.001

CPU version (force CPU)

python main.py \
    --train \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --use_cpu \
    --seed 42 \
    --early_stopping 20 \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model \
    --lr 0.001

Flags explained

• --train Run end-to-end training.
• --data_path ./dataset Folder containing <DATA_FILE>_pos.fa and <DATA_FILE>_neg.fa.
• --data_file AUH_HepG2 Dataset stem. Loader looks for AUH_HepG2_pos.fa and AUH_HepG2_neg.fa in --data_path.
• --use_cpu Force CPU mode even if CUDA is available.
• --device_num 0 Index of the CUDA device (equivalent to torch.cuda.set_device(0)).
• --seed 42 Random seed for reproducibility. For all RBP datasets reported in the manuscript, a fixed seed of 42 was used.
• --early_stopping 20 Patience for early stopping (stop if validation metric does not improve for 20 epochs).
• --Transformer_path ./RBPformer Local directory of the pretrained Transformer/“RBPformer” checkpoint (tokenizer + model).
• --model_save_path ./results/model Directory to save best models.
• --lr 0.001 Initial learning rate.

Outputs

• Model checkpoints saved under --model_save_path.
• Experiment configuration, including seed default saved under results/logs/*_config.json
• Training logs default saved under results/logs/*.log
• Evaluation metrics default saved under results/metrics/*_best.json

2) Validate (Evaluate a saved model)

GPU version (default)

python main.py \
    --validate \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --device_num 0 \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model

CPU version (force CPU)

python main.py \
    --validate \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --use_cpu \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model

Flags explained

• --validate Run validation only. The code will load the model from --model_save_path (ensure a trained model exists).
• Other flags are identical in meaning to the Train section.

3) Dynamic Transfer Prediction (Cross–cell-type)

GPU version (default)

python main.py \
    --dynamic_predict \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --device_num 0 \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model

CPU version (force CPU)

python main.py \
    --dynamic_predict \
    --data_path ./dataset \
    --data_file AUH_HepG2 \
    --use_cpu \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model

Flags explained

• --dynamic_predict Perform zero-shot / cross–cell-type inference.
• --data_file AUH_HepG2 Target dataset stem for dynamic prediction.
• Remaining flags carry the same meaning as above.

Notes

• Ensure the correct source-trained model is available under --model_save_path.

4) Variant-Aware Scoring

GPU version

python variant_aware.py \
    --variation_mode after \
    --fasta_sequence_path ./dataset_variant/AUH_HepG2.fa \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model \
    --variant_out_file ./results/variants/AUH_HepG2_after_mut.txt \
    --device cuda:3

CPU version (force CPU)

python variant_aware.py \
    --variation_mode after \
    --fasta_sequence_path ./dataset_variant/AUH_HepG2.fa \
    --Transformer_path ./RBPformer \
    --model_save_path ./results/model \
    --variant_out_file ./results/variants/AUH_HepG2_after_mut.txt \
    --device cpu

Flags explained

• --variation_mode {before,after} before = score reference sequence; after = score mutated sequence.
• --fasta_sequence_path Path to the FASTA-like file to score.
• --Transformer_path / --model_save_path Same as above; specify the Transformer directory and the trained BRIDGE model location.
• --variant_out_file Output path for scored variants.
• --device Control whether to use CPU or GPU mode.

5) Motif construction

Step 1: Generate attention maps for motif visualization

export KMER=1
export MODEL_PATH=../RBPformer
export DATA_PATH=examples/AARS_K562
export PREDICTION_PATH=examples/AARS_K562
cd motif_construction/

python run_finetune.py \
    --model_type dna \
    --tokenizer_name $MODEL_PATH \
    --model_name_or_path $MODEL_PATH \
    --task_name dnaprom \
    --do_visualize \
    --visualize_data_dir $DATA_PATH \
    --visualize_models $KMER \
    --data_dir $DATA_PATH \
    --max_seq_length 101 \
    --per_gpu_pred_batch_size=4 \
    --output_dir $MODEL_PATH \
    --predict_dir $PREDICTION_PATH \
    --n_process 96

Flags explained

• --model_type dna Sets the model type for processing DNA/RNA sequences.
• --tokenizer_name / --model_name_or_path Paths to the pretrained RBPformer tokenizer and model.
• --task_name dnaprom Task identifier (inherited from training scripts; here for promoter-like sequence processing).
• --do_visualize Enables generation of attention maps for visualization.
• --visualize_data_dir Input data folder containing sequences.
• --visualize_models K-mer length (here set via $KMER).
• --data_dir Same as input data path.
• --max_seq_length Maximum sequence length.
• --per_gpu_pred_batch_size Prediction batch size per GPU.
• --output_dir Directory for saving outputs.
• --predict_dir Directory for prediction results.
• --n_process Number of parallel processes for data handling.

Step 2: Discover motifs from attention maps

export KMER=1
echo $(pwd)
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
export DATA_PATH=examples/AARS_K562
export ATTENTION_PATH=examples/AARS_K562
export OUTPUT_PATH=examples/AARS_K562/result

python motif/Discovery_motifs.py \
    --input_rna_dir $DATA_PATH \
    --attention_dir $ATTENTION_PATH \
    --motif_length 6 \
    --min_region_len 6 \
    --fdr_cutoff 0.01 \
    --min_motif_count 3 \
    --align_all_ties \
    --output_motif_dir $OUTPUT_PATH \
    --verbose

Flags explained

• --input_rna_dir Directory containing RNA sequences used for motif extraction.
• --attention_dir Directory with saved attention scores from Step 1.
• --motif_length Target motif length.
• --min_region_len Minimum contiguous region length for candidate motifs.
• --fdr_cutoff False discovery rate threshold for motif selection.
• --min_motif_count Minimum number of motif occurrences to be considered significant.
• --align_all_ties Align motifs even if multiple sequences have identical scores.
• --output_motif_dir Output folder for discovered motifs.
• --verbose Enables detailed logging.

📘 Step-by-Step Tutorials

We provide step-by-step tutorials in the Tutorial folder to help users get started. Each tutorial is designed as a self-contained Jupyter notebook.

Workflow Map

We provide the canonical entry point for running BRIDGE end-to-end. Each workflow below maps a user-facing task to the recommended tutorial notebook(s), the script entry point, and the expected inputs/outputs—so you do not need to infer behavior by reading multiple scripts.

Core modeling workflows

Task	Recommended notebook	Script entry point	Inputs	Outputs
Train BRIDGE models for the RBPs in different cell lines	docs/tutorials/notebooks/train.ipynb	python main.py --train ...	{DATA_FILE}_{pos,neg}.fa, Transformer backbone	checkpoints under results/model/ + metrics/logs
Evaluate trained models on held-out data	docs/tutorials/notebooks/validate.ipynb	python main.py --validate ...	same inputs + checkpoint	evaluation metrics/predictions
Dynamic cross-cell-type prediction	docs/tutorials/notebooks/dynamic_predict.ipynb	python main.py --dynamic_predict ...	target dataset + resolved checkpoint name	dynamic prediction outputs/metrics

Variant-aware scoring workflows

Variant task	Recommended notebook	How it maps to variant_aware.py	What it clarifies explicitly
GWAS variant scoring	docs/tutorials/notebooks/GWAS_tutorial.ipynb	python variant_aware.py --gwas ... (or default when no other pipeline flag is provided)	Header schema → 0-based variant localization (strand-aware) → before/after allele substitution, with checkpoint resolved from the FASTA stem and scores appended per record.
Ribosnitch scoring	docs/tutorials/notebooks/Ribosnitch_tutorial.ipynb	python variant_aware.py --ribosnitch ...	Requires headers ending with two cell lines, scores all matching cell-line checkpoints, and optionally forces the “after-variation” ALT substitution before writing per-(record, model, score) output.
ClinVar / TCGA / 1000G (catalog variants)	docs/tutorials/notebooks/ClinVar_TCGA_1000G_tutorial.ipynb	python variant_aware.py --catalog_variants/--genomic_variants ...	Specifies the required chr:start-end(strand) and POS:REF>ALT header tokens and makes strict REF checking plus optional ±1 off-by-one handling explicit in the before/after scoring output.

Motif extraction & visualization workflow

Task	Recommended notebook	What it covers
Motif extraction and visualization	docs/tutorials/notebooks/motif_discovery.ipynb	end-to-end motif workflow: discovering motifs from attention maps, converting motif instances to MEME, Tomtom comparison to motif databases, extracting motif-related sequences, generating sequence–structure PWMs, plotting motif logos, and generating circos-style visualizations

You can also visit the online documentation for detailed instructions.

🧪 Reproducibility (Figures & Supplementary Figures)

This folder contains figure-specific notebooks for reproducing the main and supplementary figures in the BRIDGE paper.

Entry point: BRIDGE/reproducibility/

Notes

This assumes the packaged data/resources and trained checkpoints are already placed in the appropriate location (see the Data & Resources section above).

📜License

This project is licensed under the MIT License.

📚Citation

If you use BRIDGE in your research, please cite the accompanying manuscript.

@article{Wang2026BRIDGE,
  title   = {Bridging sequence-structure motifs and genetic variants for genome-wide dynamic RNA-protein interaction profiling},
  author  = {Wang, Yubo and Zhu, Haoran and Hao, Gaoyang and Su, Yanchi and Yu, Zhuohan and Yang, Yuning and Wang, Fuzhou and Chen, Xingjian and Wong, Ka-chun and Li, Xiangtao},
  journal = {Nature Communications},
  year    = {2026},
  doi     = {10.1038/s41467-026-73086-0},
  url     = {https://doi.org/10.1038/s41467-026-73086-0}
}

🤝Acknowledgements

• Hugging Face Transformers for tokenizer/model loading.
• PyTorch & PyTorch Geometric for deep learning and GNN components.

💬User Support

We provide two primary channels for user support and feedback:

• GitHub IssuesFor bug reports, feature requests, and usage questions. This is the preferred channel for public discussion and community-driven support.
• Contact Email yubo23@mails.jlu.edu.cn; lixt314@jlu.edu.cn For questions related to the paper or experimental details.