README.md

---
license: apache-2.0
tasks:
  - genomic-sequence-modeling
frameworks:
  - jax
language:
  - en
  - zh
tags:
  - OneScience
  - Life Sciences
  - Genomics
  - DNA Sequence Model
  - Variant Effect Prediction
  - AlphaGenome
datasets:
  - OneScience-Sugon/alphagenome_dataset
---

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

# Model Introduction

AlphaGenome is a DNA sequence model developed by Google DeepMind. It accepts DNA intervals of up to 1 Mbp as input and predicts a range of functional genomic signals for genomic track prediction and regulatory variant-effect scoring.

Paper: Advancing regulatory variant effect prediction with AlphaGenome  
https://www.nature.com/articles/s41586-025-10014-0

# Model Description

AlphaGenome is implemented in JAX / Flax and supports genomic interval inference, variant effect scoring, track evaluation, and example fine-tuning workflows. This model package is accompanied by the Hugging Face dataset `OneScience-Sugon/alphagenome_dataset`, which enables rapid local validation.

# Use Cases

| Scenario | Description |
| :---: | :--- |
| Genomic interval prediction | Takes a reference-genome FASTA file, a chromosome, and genomic interval coordinates as input and outputs predicted tracks such as ATAC, DNase, CAGE, RNA-seq, and ChIP |
| Variant effect scoring | Takes either a VCF file or built-in example variants as input, compares predictions for the reference and variant sequences, and produces a variant scoring table |
| Track prediction evaluation | Uses validation data from the AlphaGenome dataset to compute regression evaluation metrics across different assay bundles |
| Fine-tuning experiments | Validates a fine-tuning workflow using custom reference genomes, interval CSVs, and BigWig signal files |
| Hugging Face / OneCode execution | After downloading the model project and accompanying dataset, quickly verifies that the scripts run correctly in a life-sciences runtime environment |



# Usage Guide

## 1. OneCode Usage

Try one-click AI4S development in the OneCode online environment:

[Try one-click AI4S development](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- GPU or DCU is recommended.
- A CPU can be used for import checks and lightweight configuration tests; full training and inference will be slow.
- DCU users must install DTK in advance. DTK 25.04.2 or later is recommended, or a OneScience-recommended version matching the current cluster.





**Environment Check**

- NVIDIA GPU:

```bash
nvidia-smi
```

- Hygon DCU:

```bash
hy-smi
```

### Download the Model Package

```bash
hf download --model OneScience-Sugon/alphagenome --local-dir ./alphagenome
cd alphagenome
```

### Install the Runtime Environment

**DCU Environment**

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
# uv installation supported
pip install onescience[bio-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/  --trusted-host mirrors.onescience.ai
```

After installation, return to the model package directory:

```bash
cd ./alphagenome
```

### Data for Inference, Evaluation, and Fine-Tuning

The OneScience community has uploaded the data required for AlphaGenome inference, evaluation, and fine-tuning to Hugging Face: [OneScience-Sugon/alphagenome_dataset](https://huggingface.co/datasets/OneScience-Sugon/alphagenome_dataset). After downloading, place the data in the `data/` directory under the model package.

```bash
hf download --dataset OneScience-Sugon/alphagenome_dataset --local-dir ./data
```

### Model Weights

The repository already includes `weight/alphagenome-all-folds`, and all scripts allow the model weights directory to be specified via `--model_dir`.

### Preparing Weights

If using local weights, place the AlphaGenome Orbax checkpoint in the following directory:

```text
weight/
  alphagenome-all-folds/
    _CHECKPOINT_METADATA
    _METADATA
    ...
```

When running in a shared environment, you can also reuse centrally managed model and dataset directories via environment variables:

```bash
export ONESCIENCE_MODELS_DIR=/path/to/onescience/models
export ONESCIENCE_DATASETS_DIR=/path/to/onescience/datasets
```

Scripts look in the following locations first:

- `${ONESCIENCE_MODELS_DIR}/AlphaGenome/alphagenome-all-folds`
- `${ONESCIENCE_DATASETS_DIR}/AlphaGenome`

If the above environment variables are not set, the scripts fall back to the following paths under the current model package:

- `weight/alphagenome-all-folds`
- `data/`

### Interval Inference

```bash
bash scripts/inference.sh
```

Equivalent Python command example:

```bash
python scripts/run_inference.py \
  --fasta_path ./data/reference/HOMO_SAPIENS/GRCh38.p13.genome.fa \
  --model_dir ./weight/alphagenome-all-folds \
  --chromosome chr19 \
  --start 10587331 \
  --end 11635907 \
  --output_dir ./outputs
```

Inference results are saved to `outputs/`.

### Variant Effect Scoring

```bash
bash scripts/run_variant.sh
```

To specify a VCF input:

```bash
python scripts/run_variant_scoring.py \
  --vcf_path ./data/example.vcf \
  --fasta_path ./data/reference/HOMO_SAPIENS/GRCh38.p13.genome.fa \
  --model_dir ./weight/alphagenome-all-folds \
  --output_dir ./outputs_variant
```

Scoring results are saved as a CSV file.

### Track Prediction Evaluation

```bash
bash scripts/run_track.sh
```

You can also explicitly specify data and output paths:

```bash
python scripts/run_track_prediction_eval.py \
  --model_dir ./weight/alphagenome-all-folds \
  --model_version ALL_FOLDS \
  --data_dir ./data/v1/train \
  --output_path ./outputs_track/eval_results.csv
```

### Fine-Tuning Example

```bash
python scripts/run_finetuning.py \
  --fasta_path ./data/reference/HOMO_SAPIENS/GRCh38.p13.genome.fa \
  --regions_csv ./data/finetune_regions.csv \
  --bigwig_paths ./data/sample_atac.bw \
  --output_dir ./finetuned_model \
  --num_steps 1000 \
  --batch_size 2
```

# Data Format

It is recommended to download the Hugging Face dataset `OneScience-Sugon/alphagenome_dataset` to `data/` under the model package. The default directory structure is as follows:

```text
data/
  reference/
    HOMO_SAPIENS/
      GRCh38.p13.genome.fa
      GRCh38.p13.genome.fa.fai
  v1/
    train/
      ...
```

In this structure:

- `reference/HOMO_SAPIENS/GRCh38.p13.genome.fa` is the human reference genome FASTA.
- `.fai` is the FASTA index file.
- `v1/train/` is the data directory used for track prediction evaluation.
- Custom fine-tuning also requires an interval CSV file with column names `chromosome,start,end`, as well as one or more BigWig signal files.

# OneScience Official Information

| 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 & License

- This repository is adapted from the open-source AlphaGenome model to support DCUs. The source code is licensed under Apache License 2.0.
- For scientific use, please cite the original paper: [Advancing regulatory variant effect prediction with AlphaGenome](https://www.nature.com/articles/s41586-025-10014-0).