Installation

Bioconda

mamba install -c conda-forge -c bioconda wasp2

PyPI

pip install wasp2

The PyPI package does not install external tools such as samtools, bcftools, or bedtools; install those separately.

Docker

docker pull ghcr.io/mcvickerlab/wasp2:1.5.0
docker run --rm ghcr.io/mcvickerlab/wasp2:1.5.0 wasp2-count --help

Singularity/Apptainer

singularity pull wasp2.sif docker://ghcr.io/mcvickerlab/wasp2:1.5.0
singularity exec wasp2.sif wasp2-count --help

CLI Tools

WASP2 installs three command-line entry points:

• wasp2-map
• wasp2-count
• wasp2-analyze

Quick Start

Prerequisite — normalize your VCF first. WASP2's allelic-imbalance model is biallelic. Split multi-allelic records and left-align before running:

bcftools norm -m- -f reference.fa input.vcf.gz -Oz -o input.norm.vcf.gz
bcftools index -t input.norm.vcf.gz

By default WASP2 keeps biallelic SNVs only (multi-allelic sites are dropped, equivalent to bcftools view -m2 -M2). Pass --include-multiallelic to count-variants, count-variants-sc, or make-reads to instead emit one row per ALT at any remaining multi-allelic sites.

1. Correct mapping bias

wasp2-map make-reads input.bam variants.vcf.gz -s sample1 -o remap_dir

# Realign remap_dir/*_swapped_alleles_r1.fq and r2.fq with the same aligner
# and settings used for the original BAM, then:

wasp2-map filter-remapped remapped.bam \
  -j remap_dir/input_wasp_data_files.json \
  -o filtered.bam

2. Count alleles

wasp2-count count-variants filtered.bam variants.vcf.gz -s sample1 -o counts.tsv

For a bulk cohort, use one final indexed BAM per donor and map donor identifiers to VCF sample names explicitly:

donor_id	vcf_sample	bam
donor1	VCF_sample_1	/path/to/donor1.bam
donor2	VCF_sample_2	/path/to/donor2.bam

wasp2-count count-cohort donors.tsv variants.vcf.gz cohort_counts \
  --unit snv --regions atac_peaks.bed

This creates a new locked directory containing counts.tsv.gz, normalized donors.tsv, and count_manifest.json. In SNV mode, regions restrict included sites but do not combine their tests. Use --unit feature --regions peaks.bed to retain peak identifiers for feature-level analysis.

3. Test for imbalance

wasp2-analyze find-imbalance counts.tsv -o ai_results.tsv

Single-Cell Example

wasp2-count count-variants-sc \
  cellranger.bam \
  variants.vcf.gz \
  barcodes.tsv \
  --samples sample1 \
  --feature genes.gtf \
  --out_file allele_counts.h5ad

wasp2-analyze find-imbalance-sc \
  allele_counts.h5ad \
  barcode_groups.tsv \
  --sample sample1 \
  -o ai_results.tsv

See the documentation for complete usage, tutorials, and API details.