Frequently Asked Questions¶

Q: What file formats does VariantCentrifuge support?

VariantCentrifuge supports VCF and compressed VCF.gz files as input.

General Questions¶

What is VariantCentrifuge?¶

VariantCentrifuge is a comprehensive Python-based command-line tool designed for filtering, analyzing, and interpreting genetic variants from VCF (Variant Call Format) files. It’s specifically built for clinical geneticists, bioinformaticians, and researchers who need to identify disease-causing variants efficiently.

What file formats does VariantCentrifuge support?¶

VariantCentrifuge supports:

VCF files (Variant Call Format)
Compressed VCF files (VCF.gz)
PED files for family/pedigree information
TSV/CSV files for phenotype data
BED files for custom region annotation
JSON files for gene metadata

Can I use VariantCentrifuge for clinical variant interpretation?¶

Yes, VariantCentrifuge includes features specifically designed for clinical variant analysis:

ACMG classification integration
ClinVar annotation support
Pathogenicity prediction scores
Clinical significance filtering
Professional reporting suitable for clinical review

What are the system requirements?¶

Operating System: Linux, macOS, or Windows (via WSL)
Python: Version 3.7 or higher
External Tools: bcftools, snpEff, SnpSift, bedtools (must be in PATH)
Memory: Minimum 8GB RAM recommended (16GB+ for large cohorts)
Storage: Varies by dataset size; intermediate files can be compressed

Installation and Setup¶

How do I install VariantCentrifuge?¶

The recommended installation method uses conda/mamba:

# Create environment with dependencies
mamba create -y -n variantcentrifuge bcftools snpsift snpeff bedtools
mamba activate variantcentrifuge

# Install VariantCentrifuge
pip install variantcentrifuge

For development installation:

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

Why do I get “command not found” errors?¶

This typically means the required external tools (bcftools, snpEff, SnpSift, bedtools) are not installed or not in your PATH. Ensure all dependencies are installed and accessible:

# Check if tools are available
which bcftools snpEff SnpSift bedtools

Usage and Features¶

How do I filter variants for a specific gene?¶

Basic gene filtering example:

variantcentrifuge \
  --gene-name BRCA1 \
  --vcf-file input.vcf.gz \
  --output-file brca1_variants.tsv

For multiple genes:

variantcentrifuge \
  --gene-file genes.txt \
  --vcf-file input.vcf.gz \
  --output-file output.tsv

What filter presets are available?¶

VariantCentrifuge includes 20+ preset filter combinations:

rare: Variants with AF < 1%
super_rare: Variants with AF < 0.1%
coding: Variants in coding regions
high_impact: High impact variants only
pathogenic: ClinVar pathogenic/likely pathogenic
rare,coding,high_impact: Combined filters

Use --preset to apply:

variantcentrifuge --preset rare,coding,pathogenic ...

How does compound heterozygous detection work?¶

VariantCentrifuge automatically detects compound heterozygous variants when:

A PED file is provided with family information
Two or more heterozygous variants exist in the same gene
The variants follow expected inheritance patterns

The optimized algorithm is 10-50x faster than traditional approaches and handles large gene panels efficiently.

Can I analyze multiple samples or families?¶

Yes! VariantCentrifuge supports:

Single sample analysis
Family/trio analysis with PED files
Case-control cohort studies
Multi-sample VCFs

Example with family analysis:

variantcentrifuge \
  --gene-file panel.txt \
  --vcf-file family.vcf.gz \
  --ped family.ped \
  --inheritance-mode full \
  --output-file results.tsv

Performance and Optimization¶

How can I improve processing speed for large VCF files?¶

Several optimization strategies:

Pre-filter with bcftools:

variantcentrifuge --bcftools-filter "QUAL>=30" ...

Use chunked processing:
```
variantcentrifuge --chunks 1000 ...
```

Compress intermediate files:

variantcentrifuge --gzip-intermediates ...

Focus on specific regions:

variantcentrifuge --interval-expansion 0 ...

What’s the maximum VCF file size VariantCentrifuge can handle?¶

There’s no hard limit, but performance considerations apply:

Files <1GB: Process normally
Files 1-10GB: Use chunking (--chunks 5000)
Files >10GB: Pre-filter with bcftools and use chunking
Memory usage scales with number of samples and variants per chunk

Troubleshooting¶

Why are some variants missing from my output?¶

Common reasons:

Variants filtered by quality or coverage thresholds
Gene name mismatches (check gene symbol aliases)
Variants outside gene boundaries (adjust --interval-expansion)
Filter criteria too stringent

Debug with:

variantcentrifuge --no-filtering --keep-intermediates ...

How do I debug inheritance pattern detection?¶

Use verbose inheritance output:

variantcentrifuge --inheritance-mode full --ped family.ped ...

This provides detailed JSON output showing:

Genotypes for all family members
Segregation analysis results
Confidence scores
Reasons for pattern assignment

Can I resume an interrupted analysis?¶

Yes, with checkpoint support:

# Enable checkpointing
variantcentrifuge --enable-checkpoint ...

# Resume if interrupted
variantcentrifuge --enable-checkpoint --resume ...

Advanced Features¶

How do I create custom scoring formulas?¶

Create a scoring configuration directory:

scoring/
├── my_score/
│   ├── variable_assignment_config.json
│   └── formula_config.json

Then apply:

variantcentrifuge --scoring-config-path scoring/my_score ...

Can I integrate custom annotations?¶

Yes, multiple ways:

BED file regions:

variantcentrifuge --annotate-bed custom_regions.bed ...

Gene lists:

variantcentrifuge --annotate-gene-list important_genes.txt ...

JSON metadata:

variantcentrifuge --annotate-json-genes metadata.json \
  --json-gene-mapping '{"identifier":"symbol","dataFields":["panel","moi"]}' ...

How do I perform gene burden analysis?¶

For case-control studies:

variantcentrifuge \
  --perform-gene-burden \
  --case-samples-file cases.txt \
  --control-samples-file controls.txt \
  --output-file burden_analysis.tsv

This performs Fisher’s exact test with multiple testing correction.