1. Installation

Installation

This guide explains how to set up RiSPICE for either running the workflow or contributing to the project.

Download the Required Resources

RiSPICE requires three external resources: the trained models used for prediction, the Nipponbare reference genome for sequence generation, and the empirical background distribution for statistical significance testing.

1. RiSPICE Models

RiSPICE builds upon DNABERT-2-117M. We provide the RiSPICE Base model together with LoRA adapters for different input sequence lengths, all hosted on Hugging Face.

• RiSPICE Base: paolomanlapaz/rispice-base
• 1000 bp Adapter: paolomanlapaz/rispice-1000bp
• 750 bp Adapter: paolomanlapaz/rispice-750bp
• 500 bp Adapter: paolomanlapaz/rispice-500bp

Download the RiSPICE Base model together with the desired LoRA adapter. The model repositories can be downloaded directly from the Hugging Face website, cloned with Git, or retrieved using the Hugging Face CLI.

2. Nipponbare Reference Genome

RiSPICE generates reference and alternate allele sequences from the IRGSP-1.0 Nipponbare reference genome. Download the GenBank assembly and note its location for use in subsequent workflows.

3. Empirical Background Distribution

The empirical background distribution is used to determine the statistical significance of Overall and Per-Feature Scores. Download the archive matching the adapter you selected.

DOI: https://doi.org/10.5281/zenodo.21639098

Adapter	Background Distribution
1000 bp	background-dist-1000bp.zip
750 bp	background-dist-750bp.zip
500 bp	background-dist-500bp.zip

For Users

If you only plan to run the RiSPICE workflow, Docker provides the simplest setup. The prebuilt images include all required dependencies, so no manual Python environment is needed.

1. Install Docker

Install Docker on your system.

2. Pull the Latest Docker Image

Pull the image that matches your hardware configuration.

CUDA (GPU)

docker pull ghcr.io/bioinfodlsu/rispice-cuda:latest

CPU

docker pull ghcr.io/bioinfodlsu/rispice-cpu:latest

Modify the tag if you want a specific version (i.e. rispice-cuda:v0.1.0).

3. Launch the Environment

Launch an interactive shell inside the container while mounting your local data, models, analysis, and figures directories.

docker run --rm -it \
    --gpus all \
    -v <DATA_DIR>:/workspace/.data \
    -v <MODELS_DIR>:/workspace/.models \
    -v <ANALYSIS_DIR>:/workspace/.analysis \
    -v <FIGURES_DIR>:/workspace/.figures \
    ghcr.io/bioinfodlsu/rispice-cuda:latest \
    bash

The mounted directories allow the container to read your input data and models while writing analysis results and figures directly to your local machine.

Notes
Omit the --gpus all argument when using the CPU image.
Replace the placeholder directories with paths on your local machine.

For Contributors

Contributors can either create a local Python environment for development or use Docker to obtain a reproducible development environment.

Clone the Repository

Clone the RiSPICE repository to your local machine.

Virtual Environment

Create a Virtual Environment

A virtual environment allows you to modify and run the source code directly on your system.

python -m venv .venv 
source .venv/bin/activate

Install PyTorch

Install the PyTorch build appropriate for your hardware before installing the remaining project dependencies.

CUDA (GPU):

python -m pip install --upgrade pip
pip install torch==2.10.0+cu128 --index-url https://download.pytorch.org/whl/cu128

For CPU-only systems, install: pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cpu

Install Dependencies

Install the Python packages required to develop and run RiSPICE.

pip install -r requirements.txt

To reproduce the original development environment, install requirements/frozen-cuda.txt or requirements/frozen-cpu.txt instead.

Docker

Build the Docker Images

Docker Compose builds local development images and mounts the repository into the container, allowing you to edit the source code from your host machine.

docker compose -f docker/compose.yml build

Notes

• This builds the local rispice-cuda and rispice-cpu images.
• Append rispice-cuda or rispice-cpu to build only a single image.
• The Docker Compose configuration mounts the entire repository into the container for development.

Access the Development Environment

Start an interactive shell inside the development container.

docker compose -f docker/compose.yml run \
    --rm \
    rispice-cuda \
    bash

Replace rispice-cuda with rispice-cpu when using the CPU image.