Installation¶

Dependencies¶

External Tools¶

VariantCentrifuge requires several bioinformatics tools to be installed and available in your PATH:

bcftools - For variant extraction and manipulation
snpEff - For generating gene BED files and functional annotations
SnpSift - For filtering and field extraction
bedtools (specifically sortBed) - For sorting BED files

Installing via mamba/conda¶

mamba create -y -n annotation bcftools snpsift snpeff bedtools
mamba activate annotation

Ensure these tools are in your PATH before running VariantCentrifuge.

Python Requirements¶

VariantCentrifuge requires Python 3.12+ and the following Python packages:

pandas - For XLSX conversion and data handling
jinja2 - For HTML template rendering
openpyxl - For XLSX creation
scipy - For Fisher exact test in variant analysis
statsmodels - For multiple testing correction in gene burden analysis

Installation Methods¶

Method 1: Install from PyPI (Recommended)¶

pip install variantcentrifuge

Method 2: Install from Source¶

Clone the repository:

git clone https://github.com/scholl-lab/variantcentrifuge.git
cd variantcentrifuge

Set up a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the package:
```
pip install .
```
For development (editable install):
```
pip install -e .
```

Method 3: Using conda environment¶

# Clone the repository
git clone https://github.com/scholl-lab/variantcentrifuge.git
cd variantcentrifuge

# Create and activate conda environment
mamba env create -f conda/environment.yml
mamba activate annotation

# Install the package
pip install -e .

Method 4: Docker (Recommended for Quick Setup)¶

The Docker image bundles all external tools (bcftools, snpEff, SnpSift, bedtools) and Python dependencies into a single container. No local installation of bioinformatics tools is required.

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/scholl-lab/variantcentrifuge:latest

# Verify the installation
docker run --rm ghcr.io/scholl-lab/variantcentrifuge:latest --version

Place your VCF files in a local directory and mount it into the container. Mount a local directory at /data/snpeff so downloaded SnpEff genome databases persist between runs:

mkdir -p ./data ./snpeff_data
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v ./data:/data \
  -v ./snpeff_data:/data/snpeff \
  ghcr.io/scholl-lab/variantcentrifuge:latest \
  --gene-name BRCA1 \
  --vcf-file /data/input.vcf.gz \
  --output-file /data/output.tsv

You can also mount dedicated input and output directories as child mounts under /data:

mkdir -p ./input ./output ./snpeff_data
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v ./input:/data/input:ro \
  -v ./output:/data/output \
  -v ./snpeff_data:/data/snpeff \
  ghcr.io/scholl-lab/variantcentrifuge:latest \
  --gene-name BRCA1 \
  --vcf-file /data/input/input.vcf.gz \
  --output-file /data/output/output.tsv

Keep the SnpEff database mount writable for the first download of each required genome. After the directory is fully populated with every genome the workflow will use, it may optionally be mounted read-only as ./snpeff_data:/data/snpeff:ro. A read-only cache cannot download a missing genome.

A docker-compose.yml is included in the repository for convenience:

services:
  variantcentrifuge:
    image: ghcr.io/scholl-lab/variantcentrifuge:latest
    user: "${HOST_UID:-1000}:${HOST_GID:-1000}"
    volumes:
      - ./data:/data
      # Writable for the first download; persist and reuse SnpEff databases
      - ./snpeff_data:/data/snpeff
      # Optional only after every required genome is fully populated:
      # - ./snpeff_data:/data/snpeff:ro
      # Override built-in scoring configs
      # - ./my_scoring:/app/scoring:ro

mkdir -p ./data ./snpeff_data
HOST_UID="$(id -u)" HOST_GID="$(id -g)" docker compose run --rm variantcentrifuge \
  --gene-name BRCA1 --vcf-file /data/input.vcf.gz --output-file /data/output.tsv

The image runs as a non-root user, includes built-in scoring models at /app/scoring/, and is signed with cosign for supply chain security.

Container Security and Vulnerability Reporting¶

The container retains the Bioconda SnpEff and SnpSift 5.2 wrappers and configuration files for behavioral compatibility. Their JAR payloads are rebuilt from pinned 5.2 source commits with fixed runtime dependencies, and container smoke tests compare their behavior with the stock 5.2 tools.

Each container workflow run produces two complementary vulnerability reports:

A complete Trivy JSON audit includes vendor-fixed and vendor-unfixed OS and library findings at UNKNOWN, LOW, MEDIUM, HIGH, and CRITICAL severity. The workflow retains this artifact for 90 days.
The actionable SARIF uploaded to GitHub code scanning and the blocking merge gate cover vendor-fixed findings at all of those severities. The actionable scan uses --ignore-unfixed to partition findings that have a vendor-provided fix; it does not mean that vendor-unfixed findings are absent or remediated.

This remediation does not use a .trivyignore file or dismiss code-scanning alerts. Vendor-unfixed findings remain visible in the complete JSON audit and become actionable automatically when vendor data identifies a fixed version.

Method 5: Apptainer / Singularity (HPC Execution)¶

In high-performance computing (HPC) environments where root access and Docker daemons are unavailable, Apptainer (formerly Singularity) executes the container image directly without elevated privileges.

Running Directly from GitHub Container Registry¶

Prefer apptainer run over apptainer exec. apptainer run executes the container’s entrypoint script (/usr/local/bin/_entrypoint.sh), activating the Conda/Micromamba environment containing bcftools, snpEff, SnpSift, and bedtools:

# Verify version using apptainer run
apptainer run docker://ghcr.io/scholl-lab/variantcentrifuge:latest --version

For production workflows and strict reproducibility, pin the image by its immutable SHA-256 digest:

# Look up the immutable digest for a release tag
docker buildx imagetools inspect ghcr.io/scholl-lab/variantcentrifuge:v0.16.0

# Execute with immutable digest pinning
apptainer run \
  docker://ghcr.io/scholl-lab/variantcentrifuge@sha256:<digest> \
  --version

Alternatively, build a reusable Singularity Image File (.sif):

apptainer build variantcentrifuge.sif docker://ghcr.io/scholl-lab/variantcentrifuge:latest

If using apptainer exec instead of apptainer run, invoke the activation entrypoint explicitly so environmental bioinformatics tools are in PATH:

apptainer exec variantcentrifuge.sif /usr/local/bin/_entrypoint.sh variantcentrifuge --version

Filesystem Binds and SnpEff Storage¶

Map local data into the container with -B /path/to/data:/data. Provide a persistent, writable host directory mounted to /data/snpeff so downloaded SnpEff genome databases persist between job runs:

mkdir -p /path/to/snpeff_cache

apptainer run \
  -B /path/to/data:/data \
  -B /path/to/snpeff_cache:/data/snpeff \
  docker://ghcr.io/scholl-lab/variantcentrifuge:latest \
    --gene-name BRCA1 \
    --vcf-file /data/input.vcf.gz \
    --output-file /data/output.tsv

[!NOTE] The host directory bound to /data/snpeff must be writable during the first run for each required genome database so SnpEff can download and unpack reference annotations. Once populated, it may optionally be mounted read-only as -B /path/to/snpeff_cache:/data/snpeff:ro.

Verification¶

Verify your installation by running:

variantcentrifuge --version

And check that external tools are available:

bcftools --version
snpEff -version
java -jar $SNPSIFT_JAR
bedtools --version

Troubleshooting¶

Common Issues¶

External tools not found:
- Ensure all external tools are installed and in your PATH
- For conda installations, activate the correct environment
Permission errors:
- Use --user flag with pip: pip install --user variantcentrifuge
- Or use a virtual environment
Version conflicts:
- Use a fresh virtual environment or conda environment
- Update pip: pip install --upgrade pip

Environment Variables¶

You may need to set environment variables for some tools:

export SNPEFF_JAR=/path/to/snpEff.jar
export SNPSIFT_JAR=/path/to/SnpSift.jar

Next Steps¶

Once installed, proceed to the Usage Guide to learn how to configure and run VariantCentrifuge.