OneScience-Group/Saluki

<p align="center"> <strong> <span style="font-size: 30px;">Saluki</span> </strong> </p>

Model Introduction

Saluki is a deep learning model for predicting mammalian mRNA half-life. The model takes full-length mRNA sequences as input and jointly encodes the first codon frame and splice-site information. It uses convolutional neural networks and gated recurrent units to learn sequence features associated with mRNA stability.

Paper: The genetic and biochemical determinants of mRNA degradation rates in mammals

Model Description

The main computational architecture of Saluki is as follows:

• —The input sequence length is 12,288, with 6 channels at each position;
• —The first 4 channels represent the RNA nucleotide sequence;
• —The 5th channel marks the first reading frame of codons within the coding region;
• —The 6th channel marks splice sites;
• —Multiple one-dimensional convolution and max-pooling layers are used to extract local sequence features;
• —A GRU aggregates long-range contextual information;
• —A fully connected layer outputs the predicted mRNA half-life score;
• —data0/model0 and data1/model1 use a shared model architecture with independent output heads;
• —Training uses MSE loss, L2 regularization, and the Adam optimizer.

The default configuration is located at:

conf/params.json

The model input shape is:

(batch, 12288, 6)

The output shape of a single regression head is:

(batch, 1)

Use Cases

Usage

1. OneCode

You can use the OneCode online environment for an intelligent one-click AI4S programming experience:

Try OneCode for AI4S Programming

2. Manual Installation

Hardware Requirements

• —Running on DCU in the OneScience DTK environment is recommended;
• —The current adaptation has been validated on BW DCU;
• —Both single-device inference and training are supported;
• —At least 8 GB of device memory is recommended.

Download the Model Package

Install the Hugging Face command-line tool and download the model repository:

python -m pip install -U huggingface_hub

hf download OneScience-Group/Saluki --local-dir ./Saluki
cd Saluki

Install the OneScience Base Environment

conda create -n onescience311 python=3.11 -y
conda activate onescience311

python -m pip install "onescience[bio-dcu]" \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai

Upgrade DTK and TensorFlow

The current Saluki adaptation requires a newer DTK and TensorFlow combination than the legacy OneScience default environment.

Before running Saluki, upgrade the platform DTK toolchain to DTK 26.04, and then install the corresponding DTK TensorFlow 2.18.0 package.

DTK is provided as part of the platform compiler and runtime environment. Switch to DTK 26.04 according to the SCNet platform configuration, and then install the required TensorFlow package and additional Saluki dependencies with:

python -m pip install --no-deps -r requirements.txt

Weights and Data Preparation

The official dataset and pretrained weights originate from:

• —Dataset record: Zenodo 6326409
• —Archive: datasets.zip
• —Official MD5: 45f0d6bd3857eb19e04eb5be2bb47451

The corresponding dataset and weight directory structure in the Hugging Face model package is:

conf/data/f0_c0/
├── data0/
│   ├── statistics.json
│   └── tfrecords/
│       ├── train-*.tfr
│       ├── valid-*.tfr
│       └── test-*.tfr
└── data1/
    ├── statistics.json
    └── tfrecords/
        ├── train-*.tfr
        ├── valid-*.tfr
        └── test-*.tfr

weight/f0_c0/
├── model0_best.h5
└── model1_best.h5

Quick Inference

model0 / data0

Purpose: Use output head 0 and the official model0 weights to generate one mRNA half-life prediction score for each sample in the data0 test set.

The score represents the relative mRNA stability predicted from nucleotide sequence, coding-frame information, and splice-site features. In general, a higher score corresponds to a longer predicted half-life.

The value is a regression target learned according to the official data0 target preprocessing procedure and should not be interpreted directly as hours.

The output also includes the true target values, predicted values, MSE, Pearson correlation coefficient, and R². Lower MSE and higher Pearson correlation and R² indicate better agreement between predictions and experimental targets.

python scripts/predict.py \
  conf/data/f0_c0/data0 \
  weight/f0_c0/model0_best.h5 \
  --head 0 \
  --out-dir output/f0_c0/model0

model1 / data1

Purpose: Use output head 1 and the official model1 weights to generate one mRNA half-life prediction score for each sample in the data1 test set.

The score represents relative mRNA stability under the data1 target definition. In general, a higher score corresponds to a longer predicted half-life.

Because data0 and data1 use independent output heads and target systems, their raw prediction scores should not be directly compared without considering the corresponding dataset definitions.

The output includes true targets, predictions, MSE, Pearson correlation coefficient, and R², which measure prediction error, ranking consistency, and the proportion of target variance explained by the model.

python scripts/predict.py \
  conf/data/f0_c0/data1 \
  weight/f0_c0/model1_best.h5 \
  --head 1 \
  --out-dir output/f0_c0/model1

Each output directory contains:

predictions.h5
metrics.json

predictions.h5 stores the prediction values and target values.

metrics.json stores:

• —Number of samples;
• —Output shape;
• —Data type;
• —NaN/Inf validation results;
• —MSE;
• —Pearson correlation coefficient;
• —R².

Full-Dataset Training

The default configuration contains two output heads. Therefore, both data0 and data1 should be provided during training.

Purpose: Jointly read the training and validation TFRecord datasets from data0 and data1, optimize the shared one-dimensional convolution and GRU feature-extraction backbone together with the two independent regression heads, and learn mappings from the 6-channel mRNA representation to the half-life target scores of the two datasets.

During training, the validation loss is used to select and save the best model0 and model1 weights as well as recovery checkpoints.

These checkpoints can be used for subsequent inference, continued training, and comparison across training epochs.

python scripts/train.py \
  conf/data/f0_c0/data0 \
  conf/data/f0_c0/data1 \
  --params conf/params.json \
  --out-dir output/f0_c0/train

The training entry point performs:

• —Real TFRecord dataset loading;
• —Forward propagation;
• —MSE and L2 loss computation;
• —Backward propagation;
• —Adam parameter updates;
• —Validation;
• —Checkpoint saving.

A single epoch should only be used to validate the training pipeline and should not be expected to reproduce the final accuracy reported in the paper.

To validate one complete training epoch, copy:

conf/params.json

to a new relative configuration file and set:

train_epochs_min = 1
train_epochs_max = 1
patience = 0

Do not overwrite the default parameter file so that the standard training configuration remains available.

Custom Data

Custom datasets must be converted into the compressed TFRecord format used by Saluki.

Each sample must provide:

• —RNA nucleotide sequence;
• —Actual sequence length;
• —Codon first-reading-frame track;
• —Splice-site track;
• —Regression target.

Each dataset directory must contain:

statistics.json
tfrecords/

New datasets can follow the relative directory organization used by:

conf/data/f0_c0/

OneScience Official Resources

Citation and License

• —Saluki paper: Agarwal and Kelley, Genome Biology, 2022
• —Saluki paper reproduction code: https://github.com/vagarwal87/saluki_paper
• —Basenji official implementation: https://github.com/calico/basenji
• —Official dataset: Zenodo 6326409
• —The Basenji/Saluki code included in this model package is provided under the Apache License 2.0.
• —Model weights, datasets, source code, and third-party resources remain subject to their respective original licenses, copyright notices, and terms of use.