3. Convert the deduped bps.txt.gz to VCFv4.5 (SV + indel)

July 15, 2026 · View on GitHub

SvABA — Structural variation and indel analysis by assembly

SvABA (formerly Snowman) is an SV and indel caller for short-read BAMs. It performs genome-wide local assembly, realigns contigs with BWA-MEM, and scores variants by reassembled read support. Tumor/normal, trios, and single-sample modes are supported; variants are emitted as VCF plus a verbose tab-delimited companion (bps.txt.gz) carrying the full per-sample evidence.

License: GNU GPLv3. Uses the SeqLib API for BAM I/O, BWA-MEM alignment, interval trees, and the assembly front-end.

For debugging recipes, build tuning, and internals, see README.dev.md and CLAUDE.md.

Install

Package	Required?	Purpose
CMake ≥ 3.14	yes	build system
htslib	yes	BAM/CRAM/VCF I/O
zlib	yes	gzip in/out
pthread	yes	worker threads
BZip2, lzma	yes	htslib compression deps
sqlite3	optional	enables `--dump-reads` `r2c.db` output
jemalloc	optional	recommended on Linux at `-p 16+`

git clone --recursive https://github.com/walaj/svaba
cd svaba && mkdir build && cd build
cmake .. && make -j

The binary lands at build/svaba. For a non-standard htslib, pass -DHTSLIB_DIR=/path/to/htslib-1.xx. Install system-wide with make install (prefix /usr/local, override with -DCMAKE_INSTALL_PREFIX).

Build type defaults to RelWithDebInfo (-O2 -g -DNDEBUG). See README.dev.md for -O3 -mcpu=native tuning (5–15% faster), the fermi-lite/SGA assembler switch, and jemalloc (10–20% faster on Linux at high thread counts).

When sqlite3 isn't found, svaba builds fine but --dump-reads skips the ${ID}.r2c.db file (the other --dump-reads outputs are unaffected). To enable it: brew install sqlite / apt install libsqlite3-dev / dnf install sqlite-devel, then re-run cmake.

Quick start

Three steps: call, post-process, convert to VCF. The bundled combined blacklist is strongly recommended — it keeps svaba out of pileup / high-complexity regions that otherwise dominate wall-clock with no real calls.

# 1. Call: tumor/normal on chr22 with 4 threads, bundled blacklist
svaba run -t tumor.bam -n normal.bam -G ref.fa -a my_run -p 4 -k chr22 \
          --blacklist tracks/hg38.combined_blacklist.bed

# 2. Post-process (one command): merge per-thread BAMs, sort+dedup+index,
#    sort+dedup bps.txt.gz, stamp PASS reads into r2c.db.
svaba postprocess -i my_run -t 8 -m 4G

# 3. Convert the deduped bps.txt.gz to VCFv4.5 (SV + indel)
svaba tovcf -i my_run.bps.sorted.dedup.txt.gz -b tumor.bam -a my_run

A single-sample call drops -n. Any number of cases/controls can be jointly assembled; the sample-ID prefix drives routing (t* = case, n* = control).

Subcommands

SvABA is a multi-tool binary; svaba help lists everything.

svaba run — the whole assembly + variant-calling pipeline. Emits bps.txt.gz, per-sample VCFs, contigs.bam, runtime.txt, and (with --dump-reads) per-thread *.discordant.bam, *.corrected.bam, *.r2c.db.
svaba postprocess — one-command post-processing: merges per-thread BAMs and r2c.db files, coordinate-sorts + stream-dedups + @PG-stamps + indexes the BAMs, sorts/dedups bps.txt.gz (writing PASS / PASS-somatic subsets), and stamps PASS reads into r2c.db. Six idempotent phases; reruns are near-instant.
svaba tovcf — converts a deduplicated bps.txt.gz into VCFv4.5 (one SV VCF, one indel VCF; somatic marked by the SOMATIC INFO flag). Clean intrachrom events emit as symbolic <DEL>/<DUP>/<INV>; everything else stays paired BND. The SOMATIC flag is stamped when INFO/SOMLOD ≥ a cutoff (default 1.0, tune with --somlod). The raw score is always written to INFO/SOMLOD, so bcftools view -i 'INFO/SOMLOD >= 3' re-thresholds without regenerating the VCF.
svaba refilter — re-runs LOD cutoffs / PASS logic on an existing bps.txt.gz with new thresholds, regenerating VCFs without re-assembling.
svaba extract-pairs — pulls every read pair whose SEQ contains a query sequence (or, with -f bps.txt.gz, every read carrying a variant's junction kmer). See svaba extract-pairs -h.

Output files

${ID}.bps.txt.gz is the primary output — one row per breakpoint, with a v4 schema of 53 core columns plus one FORMAT-style block per sample. Full column reference below.

The VCF files (${ID}.sv.vcf.gz, ${ID}.indel.vcf.gz) declare VCFv4.5, use symbolic alleles where unambiguous, and carry the canonical scoring in INFO: MAXLOD (variant-vs-error, per-sample max), SOMLOD (somatic LLR), SOMATIC (flag), SVCLAIM (evidence class). VCF QUAL defaults to . — filter on FILTER=PASS or the two LOD fields, not QUAL.

${ID}.contigs.bam holds every assembled contig; ${ID}.runtime.txt holds per-region timing; ${ID}.log is the run log.

Opt-in outputs (behind --dump-reads, can run to tens of GB on deep samples): ${ID}.r2c.db (queryable SQLite of every contig + its r2c-aligned reads), ${ID}.corrected.bam / ${ID}.discordant.bam (per-read evidence streams).

`bps.txt.gz` column reference

Columns are 1-indexed (awk $1 == chr1). This is the v4 schema emitted by BreakPoint::toFileString; positions are 1-based (SAM/VCF convention). x marks an empty string field; . marks an empty numeric/id field.

#	Name	Description
1	`chr1`	Chromosome of breakend 1
2	`pos1`	Position of breakend 1 (1-based)
3	`strand1`	Orientation of breakend 1 (`+`/`-`)
4	`chr2`	Chromosome of breakend 2
5	`pos2`	Position of breakend 2 (1-based)
6	`strand2`	Orientation of breakend 2 (`+`/`-`)
7	`ref`	Reference allele at the breakpoint
8	`alt`	Alternate allele
9	`span`	Event span in bp (`-1` for interchromosomal)
10	`split`	Total split-read support across all samples
11	`alt_count`	Total alt-read count
12	`cov`	Read coverage at the breakpoint
13	`cigar`	Indel support from read CIGAR strings
14	`cigar_near`	CIGAR support near (but not exactly at) the breakpoint
15	`dmq1`	Discordant-cluster MAPQ, side 1
16	`dmq2`	Discordant-cluster MAPQ, side 2
17	`dcn`	Discordant read count, normal
18	`dct`	Discordant read count, tumor
19	`mapq1`	Contig-alignment MAPQ, side 1
20	`mapq2`	Contig-alignment MAPQ, side 2
21	`nm1`	Contig-alignment edit distance (NM), side 1
22	`nm2`	Contig-alignment edit distance (NM), side 2
23	`as1`	Contig-alignment score (BWA AS), side 1
24	`as2`	Contig-alignment score (BWA AS), side 2
25	`sub1`	Number of sub-optimal contig alignments, side 1
26	`sub2`	Number of sub-optimal contig alignments, side 2
27	`homol`	Microhomology at the junction (side-1 forward strand); `x` if none
28	`insert`	Inserted novel (non-template) sequence at the junction; `x` if none
29	`repeat`	Repeat-sequence context at the breakpoint; `x` if none
30	`contig_and_region`	Contig name (`cname`) — the r2c / `r2c.db` join key
31	`naln`	Number of contig-alignment fragments
32	`conf`	Confidence / FILTER (`PASS`, `LOWLOD`, `LOWSUPPORT`, …)
33	`type`	Evidence type (`ASSMB`, `ASDIS`, `DSCRD`, `INDEL`, …)
34	`qual`	Variant quality
35	`2ndary`	Secondary-alignment flag
36	`somatic`	Somatic call flag (`NA` when no normal sample present)
37	`somlod`	Somatic LOD (`LO_s`), capped at 99
38	`maxlod`	Max per-sample `LO` (variant-vs-error)
39	`dbsnp`	dbSNP overlap (rs id, or `x`)
40	`contig_conf1`	Contig-alignment confidence, side 1
41	`contig_conf2`	Contig-alignment confidence, side 2
42	`cpos1`	Contig-relative breakend position, side 1 (`-1` = unset)
43	`cpos2`	Contig-relative breakend position, side 2 (`-1` = unset)
44	`lmatch`	Left flanking match length
45	`rmatch`	Right flanking match length
46	`scov1`	Split-coverage lower bound on the contig
47	`scov2`	Split-coverage upper bound on the contig
48	`local1`	Per-end LocalAlignment enum (0–3), side 1
49	`local2`	Per-end LocalAlignment enum (0–3), side 2
50	`ctglen`	Contig length
51	`flipped`	Contig orientation flag (1 = contig flipped relative to side 1)
52	`bp_id`	Unique per-BP identifier `bpTTTNNNNNNNN` (thread `TTT`, counter `NNNNNNNN`). Joins to `bps.txt` col 52, the BAM `bi:Z` tag, `r2c.db`'s `split_bps`/`disc_bps`, and the VCF `EVENT=` field. `.` if unset
53	`jxn_kmer`	20 bp contig sequence spanning the breakend junction — a read-search query for `svaba extract-pairs -f bps.txt.gz`. `.` when no precise junction exists
54+	per-sample block	One `FORMAT`-style block per BAM (order matches the header row) — see below

Per-sample block (columns 54+, one per BAM), colon-delimited GT:AD:DP:SR:DR:GQ:PL:LO:LO_n:

Sub	Name	Description
GT	genotype	Genotype call
AD	alt depth	Alt-supporting read count (for indels, `max(alt, cigar)`)
DP	depth	Total read coverage
SR	split reads	Split-read support count
DR	discordant reads	Discordant-read support (indels: this field holds the CIGAR-indel count instead)
GQ	genotype quality	Phred genotype quality
PL	phred likelihoods	Comma-separated genotype likelihoods
LO	log-odds	Variant vs error (per-sample); `maxlod` is the max of these
LO_n	log-odds ref	Confidence the site is REF-only in this sample (the germline-vs-somatic discriminant; the normal's `LO_n` drives `somlod`)

scripts/svaba_local_function.sh::svaba_bps_cols prints this same reference from the shell.

Viewers

All-HTML, no server — drop files in from file://. Entry point: docs/index.html. Primary viewer is bps_explorer.html (sortable bps.txt.gz table, chip filters, per-sample detail, histograms, click-to-IGV). r2c_db_explorer.html loads a ${ID}.r2c.db and plots each contig with its r2c-aligned reads. runtime_explorer.html visualizes runtime.txt; comparison.html diffs two runs; learn_explorer.html plots insert-size distributions.

Blacklists

tracks/hg38.combined_blacklist.bed is the ready-made blacklist; feed it to svaba run --blacklist. It's a regeneratable union of component BEDs in tracks/ (ENCODE, high-runtime regions, manual curations, simple repeats, non-standard contigs, low-mappability). See tracks/README.md for the recipe.

Recipes

Germline-only. Raise the mate-lookup threshold so only larger discordant clusters trigger a cross-region lookup (add --single-end to disable mate lookups entirely):

svaba run -t germline.bam -p 8 --mate-min 6 -a germline_run -G ref.fa \
          --blacklist tracks/hg38.combined_blacklist.bed

Targeted assembly over a region list (BED, chr, or IGV-style string):

svaba run -t sample.bam -k targets.bed -a exome_cap -G ref.fa
svaba run -t sample.bam -k chr17:7,541,145-7,621,399 -a TP53 -G ref.fa

Non-human genome (mouse, zebrafish, …). By default svaba assumes a human reference (mate lookups skip past chrY, insert-size learning samples chr1–chrY). --non-human removes those gates:

svaba run -t mouse.bam -G mm39.fa -a mouse_run --non-human -p 16

Fine-tune individually with --max-mate-chr N and --min-mate-mapq N.

Issues and contact

File bug reports, feature requests, and questions on GitHub: https://github.com/walaj/svaba/issues.

Attributions

SvABA is developed by Jeremiah Wala in the Rameen Berkoukhim lab at Dana-Farber Cancer Institute, in collaboration with the Cancer Genome Analysis team at the Broad Institute. Particular thanks to Cheng-Zhong Zhang (HMS DBMI) and Marcin Imielinski (Weill Cornell / NYGC).

Additional thanks to Jared Simpson for SGA, Heng Li for htslib and BWA, and the SeqLib contributors.

The SvABA 2.0 release and its documentation were built with the assistance of OpenAI Codex and Anthropic Claude, with extensive human-in-the-loop review, testing, and decision-making throughout.