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.10+ 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. Use a named volume at /data/snpeff so downloaded SnpEff genome databases persist between runs:

docker volume create snpeff_data
docker run --rm \
  -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

Keep the SnpEff database mount writable for the first download of each required genome. After the volume 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
    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

volumes:
  snpeff_data:

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.

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.