Twitcher

Template switch aligner.

A tool to re-annotate VCF files. We want to explain clusters of SNVs/Indels with one or more short-range template switches (Löytynoja and Goldman (2017)).

The tool operates in two stages:

1. While reading the input vcf file (either from stdin or a file), find suspicious™ clusters of SNVs and Indels, e.g. more than 3 indels within 10 basepairs.
2. Realign those clusters under consideration of a few hundred surrounding base pairs. If the mutation cluster can be better explained with one or more template switches, output the new, reannotated vcf records instead of the original ones.

The tool is designed to enrich the vcf file with more information. Unaffected records are output as-is.

Installation

You can install the tool from source using cargo (needs at least version 1.87.0):

cargo install twitcher

Get cargo e.g. via rustup. You'll also need the clang C compiler to compile the underlying htslib bindings.

Usage

Twitcher has two main commands:

• twitcher vcf — Re-annotate VCF files with template switch mutations
• twitcher reads — Find template switch mutations in sequencing reads

Quick Start

twitcher vcf input.vcf reference.fa -o output.vcf

This realigns suspicious mutation clusters and outputs reannotated variants.

Full Documentation

Complete documentation is available in docs/:

Examples

# Realign with larger context window
twitcher vcf input.vcf reference.fa --padding 500 -o output.vcf

# Only output realigned variants
twitcher vcf input.vcf reference.fa --only-realigned -o output.vcf

# Use reads to (try to) phase ambiguous clusters
twitcher vcf input.vcf reference.fa --bam-file reads.bam -o output.vcf

# Export template switch regions
twitcher vcf input.vcf reference.fa -o output.vcf --output-regions ts_regions.bed

# Use a database to store known cases
twitcher vcf input.vcf reference.fa --db known.db -o output.vcf

Background

The underlying pairwise aligner is developed on GitHub by Sebastian Schmidt.