AnnotSV is a robust open-source software package and web-based platform designed for the annotation and prioritization of structural variants (SVs) in the human genome. Because the native installation process can be somewhat involved, I provide a Singularity container that bundles AnnotSV for straightforward, ready-to-use deployment. For details on installing Singularity, please refer to the guide “Singularity Installation and Usage Tutorial: A Containerization Guide for High-Performance Computing Environments”.
Download Container
AnnotSV 3.5.3 （2025.10.31）：
Singularity Repository
Huggingface Repository
Container Overview
This Singularity container bundles AnnotSV to enable convenient deployment in Linux-based environments.
Original AnnotSV project: AnnotSV GitHub
Original project license: GPL-3.0
This container inherits the GPL-3.0 license from the upstream project.
Modification
- Exomiser Port Allocation:
- In the original AnnotSV implementation, the port availability check and the actual port assignment for the Exomiser server are executed separately. Under concurrent workloads, this can lead to port conflicts. Specifically, when multiple tasks simultaneously invoke the “port availability check,” the function returns the same default port (10000) because no Exomiser server is running at that moment. However, once the tasks subsequently attempt to start their respective Exomiser servers, they all try to bind to the same port, resulting in conflicts and runtime errors.
- In this container, the Exomiser server port assignment has been modified to rely on system-allocated ports. The dynamically assigned port number is returned and used independently by each task to retrieve its Exomiser analysis results, preventing collisions.
- PhenoGenius Execution Option:
- Because PhenoGenius analysis is time-consuming, a new command-line option, -PhenoGeniusCli, has been introduced to control whether PhenoGenius should be executed.
Default: False — PhenoGenius analysis is skipped.
Optional: Set to True to enable PhenoGenius processing.
- Because PhenoGenius analysis is time-consuming, a new command-line option, -PhenoGeniusCli, has been introduced to control whether PhenoGenius should be executed.
- Prioritiser Database:
- A new option, -prioritiserParams, allows users to specify which databases Exomiser should use. In the original code, Exomiser used the following databases by default: human, mouse, fish, PPI. In this container, the default has been changed to human only.
- Users may provide a comma-separated list to select any combination of the four databases, for example: -prioritiserParams “human,mouse”.
Installation Location
The AnnotSV source code and installation within the container are located at:
/opt/software/AnnotSV_3.5.3/AnnotSV/
Disclaimer
During the container build process, various warnings, errors, or temporary log files may have been generated and left behind. The author does not take responsibility for these residual files, as it is not feasible to track every intermediate change or artifact created during installation. If users wish to study the AnnotSV installation process based on these logs, they are encouraged to review and test them carefully.
This image is actively used in long-term workflows. Any issues discovered will be addressed promptly, and updated container versions will be uploaded to the repository.
License
The distribution of this codebase and the packaged software complies with the terms of the GPL-3.0 license.
Usage
Downloading the Annotation Files
#!/usr/bin/env bash
set -e
# 创建安装目录
echo "===== download annotation files ====="
# Human
curl -C - -LO "https://www.lbgi.fr/~geoffroy/Annotations/Annotations_Human_3.5.tar.gz"
# Mouse
curl -C - -LO "https://www.lbgi.fr/~geoffroy/Annotations/Annotations_Mouse_3.4.2.tar.gz"
# Exomiser phenotype
curl -C - -LO "https://data.monarchinitiative.org/exomiser/data/2406_phenotype.zip"
# Exomiser JAR
curl -C - -LO "https://github.com/exomiser/Exomiser/releases/download/14.1.0/exomiser-rest-prioritiser-14.1.0.jar"
echo ""
echo "===== Download complete, starting extraction ====="
mkdir -p ./AnnotSV_3.5.3_anno
# 解压 Human
tar -xf Annotations_Human_3.5.tar.gz -C ./AnnotSV_3.5.3_anno
# 解压 Mouse
tar -xf Annotations_Mouse_3.4.2.tar.gz -C ./AnnotSV_3.5.3_anno
# 解压 Exomiser phenotype
mkdir -p ./AnnotSV_3.5.3_anno/Annotations_Exomiser/2406
unzip -o 2406_phenotype.zip -d ./AnnotSV_3.5.3_anno/Annotations_Exomiser/2406
# 放置 Exomiser JAR
mkdir -p ./AnnotSV_3.5.3_anno/jar
mv exomiser-rest-prioritiser-14.1.0.jar ./AnnotSV_3.5.3_anno/jar
# 清理压缩包
# rm -f Annotations_Human_3.5.tar.gz
# rm -f Annotations_Mouse_3.4.2.tar.gz
# rm -f 2406_phenotype.zip
echo ""
echo "===== All data installation complete ====="
# echo "安装目录: $(pwd)"
Running AnnotSV
This image is built with Singularity (version 3.5.3) and therefore requires a Singularity environment to run.
singularity exec AnnotSV_3.5.3.sif \
AnnotSV \
-SVinputFile 'Path of your VCF or BED input file with SV coordinates' \
-outputFile 'Output path and file name' \
-genomeBuild 'GRCh38 or GRCh37 or CHM13 or or mm9 or mm10' \
-annotationsDir 'Path of the annotations directory' \
-svtBEDcol 4 -vcf 0 \
-PhenoGeniusCli True \
-hpo "HP:0011003,HP:0030329" \
-prioritiserParams human,ppi \
-txFile 'Path of a file containing a list of preferred genes transcripts to be used in priority during the annotation (Preferred genes transcripts names should be tab or space separated)'- -annotationsDir: This specifies the directory containing the AnnotSV annotation data downloaded earlier. Each AnnotSV release requires its own corresponding annotation set, so make sure to download the version that matches your AnnotSV installation.
- -PhenoGeniusCli: This parameter was added in the container. In the original AnnotSV design, if the -hpo parameter is provided, PhenoGenius analysis is automatically enabled. Because PhenoGenius is computationally intensive — and often unnecessary in production workflows — a toggle was added here. By default, PhenoGenius analysis is disabled, and PhenoGenius analysis can be enabled by setting this option to True.
- -prioritiserParams: This is another container-specific addition. By default, AnnotSV invokes Exomiser using all available databases (human, mouse, fish, PPI), which increases the rate of false positives. This may be acceptable in a research environment but is undesirable in production settings. This parameter allows users to specify which of the four databases should be included in Exomiser prioritization.
- -txFile: A file specifying preferred transcripts for gene selection. The file may contain one transcript ID per line, making it easy to provide custom transcript sets.
Leave a Reply