twitcher 0.1.8

Find template switch mutations in genomic data
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# Twitcher

**T**emplate s**witch** align**er**.

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)](https://doi.org/10.1101/gr.214973.116)).

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):

```bash
cargo install twitcher
```

Get cargo e.g. via [rustup](https://rustup.rs/). 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

```bash
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/`](docs/index.md):

### Examples

```bash
# 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](https://github.com/sebschmi/template-switch-aligner).