README.md

---
frameworks:
- TensorFlow
language:
- en
license: apache-2.0
tags:
- OneScience
- bioscience
- RNA
- mRNA-half-life-prediction
- Saluki
- DCU
tasks:
- regression

---

<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](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-022-02811-x)

# 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:

```text
conf/params.json
```

The model input shape is:

```text
(batch, 12288, 6)
```

The output shape of a single regression head is:

```text
(batch, 1)
```

# Use Cases

| Use Case | Description |
| :---: | :--- |
| mRNA half-life prediction | Predict relative mRNA stability from full-length mRNA sequences, coding-frame information, and splice-site features. |
| Official test-set evaluation | Evaluate the model on the official Saluki TFRecord test datasets using MSE, Pearson correlation, and R². |
| Dual-task training | Jointly train two output heads using `data0` and `data1`. |
| Model compatibility validation | Verify that TensorFlow can construct and execute the Saluki model in the OneScience DTK/DCU environment. |
| Sequence feature analysis | Provide a base model for downstream gradient analysis, in silico mutagenesis, and motif analysis. |

# Usage

## 1. OneCode

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

[Try OneCode for AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 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:

```bash
python -m pip install -U huggingface_hub

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

### Install the OneScience Base Environment

```bash
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:

```bash
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](https://zenodo.org/records/6326409)
- Archive: `datasets.zip`
- Official MD5: `45f0d6bd3857eb19e04eb5be2bb47451`

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

```text
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.

```bash
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.

```bash
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:

```text
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.

```bash
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:

```text
conf/params.json
```

to a new relative configuration file and set:

```text
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:

```text
statistics.json
tfrecords/
```

New datasets can follow the relative directory organization used by:

```text
conf/data/f0_c0/
```

# OneScience Official Resources

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |

# Citation and License

- Saluki paper: [Agarwal and Kelley, Genome Biology, 2022](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-022-02811-x)
- Saluki paper reproduction code: https://github.com/vagarwal87/saluki_paper
- Basenji official implementation: https://github.com/calico/basenji
- Official dataset: [Zenodo 6326409](https://zenodo.org/records/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.