ASOCompass

ASOCompass is a context- and chemistry-aware framework for ASO activity prediction and candidate ranking. It integrates contextualized ASO and target-RNA sequence representations with position-specific molecular representations of chemical modifications. The framework further incorporates dose and delivery information together with prototype-adapted transcriptomic representations of target genes and cell lines. Auxiliary molecular-property and sequence-derived thermodynamic prediction tasks encourage chemically and biophysically informative representations.

Key Insights & Contributions

• Context-aware activity modeling: jointly models ASO sequence and chemistry, target-RNA context, experimental conditions, and cellular environment.
• Fine-grained chemical representation: replaces discrete modification labels with position-aligned molecular representations of modified monomers.
• Chemical- and thermodynamic-guided multitask learning: introduces auxiliary objectives that capture molecular, folding, accessibility, and hybridization priors.

Model Overview

ASOCompass integrates ASO sequence, position-specific chemical modifications, target-RNA context, and experimental-biological context for activity prediction.

Getting Started

Requirements

The reference environment uses:

• Python 3.10
• PyTorch 2.1 or newer
• Lighting 2.2 or newer

Install PyTorch for your CUDA version first, then install the remaining dependencies:

python -m pip install -r requirements.txt

flash-attn and Uni-Mol2 require a compatible CUDA toolchain.

Required Assets

Large datasets and checkpoints are intentionally not tracked by Git. Prepare the following files before training:

Asset	Purpose
Inhibition dataset	ASO examples, experimental metadata, labels, and predefined splits
Gene map CSV	Normalizes source gene symbols to canonical symbols
RiNALMo checkpoint	Initializes the RNA language model
Uni-Mol2 checkpoint	Initializes the molecular encoder

Chemical-property targets, Vienna features, cell-line embeddings, and a gene index are optional. They enable the corresponding auxiliary or biological-context branches.

Minimal Training Run

From the repository root:

python train.py /path/to/inhibition.csv.gz \
    --gene_map_path /path/to/gene_map.csv \
    --pretrained_rinalmo_weights /path/to/rinalmo_giga.pt \
    --unimol_checkpoint /path/to/unimol2_1.1b.pt \
    --output_dir outputs/baseline \
    --batch_size 32 \
    --max_epochs 20

This runs the primary inhibition task without the optional auxiliary datasets or precomputed biological embeddings. The gradual-unfreezing schedule defaults to configs/finetune.yaml.

Data Format

A compact schema example is available at data/aso_inhibitions.csv. It contains representative ASO records for inspecting the expected fields.

The following columns are required:

Column	Description
aso_sequence_5_to_3	ASO sequence in 5' to 3' orientation
rna_context	Target RNA context with 50nt flanks
smiles_list	Python-style list of monomer SMILES strings
inhibition_percent	Regression target in the range [0, 100]
dosage	Numeric treatment dosage
transfection_method	Categorical transfection method
split	One of train, val, or test

Optional columns:

Column	Description
splitlevel	Generalization level used for split-level reporting
target_gene	Target gene used by the biological-context branch
CVCL_ID, cvcl, or cell_line	Cell-line identifier

The gene map supplied through --gene_map_path is required and must contain source_gene and canonical_gene columns.

The optional chemical-property table must contain a SMILES column and numeric property targets. The optional Vienna table is joined by ASO sequence and RNA context. Column names can be selected with --chem_property_cols and --vienna_feature_cols; otherwise supported columns are detected automatically.

Full Experiment

scripts/train.sh captures the main multimodal configuration. Supply all artifact paths through environment variables:

export DATA_PATH=/path/to/inhibition.csv.gz
export RINALMO_CHECKPOINT=/path/to/rinalmo_giga.pt
export UNIMOL_CHECKPOINT=/path/to/unimol2_1.1b.pt
export VIENNA_FEATURES=/path/to/vienna_features.csv
export CHEM_PROPERTIES=/path/to/chemical_properties.csv
export CVCL_EMBEDDINGS=/path/to/cellline_embeddings.pt
export GENE_INDEX=/path/to/gene_index.pt
export GENE_MAP_PATH=/path/to/gene_map.csv

bash scripts/train.sh

Common overrides include CUDA_VISIBLE_DEVICES, OUTPUT_DIR, and UNIMOL_CACHE.

Evaluation

Training evaluates the final model on the held-out test split and reports global Spearman correlation. To evaluate an existing Lightning checkpoint:

python train.py /path/to/inhibition.csv.gz \
    --gene_map_path /path/to/gene_map.csv \
    --resume_from_checkpoint /path/to/model.ckpt \
    --test_only

Fine-Tuning Schedule

configs/finetune.yaml controls which parameter groups are trainable at each epoch. The default policy trains newly initialized heads first, then progressively unfreezes the final Uni-Mol2 and RiNALMo blocks.

Edit the YAML file or pass another schedule with:

python train.py ... --ft_schedule /path/to/schedule.yaml

Repository Layout

ASOCompass/
|-- configs/
|   `-- finetune.yaml        # staged backbone-unfreezing policy
|-- data/
|   `-- aso_inhibitions.csv  # compact input-schema example
|-- rinalmo/                 # RNA and molecular encoder components
|-- scripts/
|   `-- train.sh             # full experiment launcher
|-- train.py                 # model training and evaluation

Reference:

@article{liu2026asocompass,
  title={ASOCompass: Context-and Chemistry-Aware Activity Prediction for Transferable Antisense Oligonucleotide Screening},
  author={Liu, Shuyu and Zhuo, Jin and Lei, Shuchang and Wu, Tianhao and Han, Jiaxuan and Wu, Chaoyi and Wang, Yanfeng and Xie, Weidi},
  journal={bioRxiv},
  pages={2026--08},
  year={2026},
  publisher={Cold Spring Harbor Laboratory}
}