TSIGAR Format

TSIGAR (formerly CIGARETS) extends the CIGAR format with template switches. It describes how two sequences align: the reference and the query/alt, which is the alternative haplotype in twitcher vcf and the read in twitcher reads.

Syntax

A TSIGAR string is a sequence of operations. Outside a template switch they work like in CIGAR:

op meaning consumes
n= match reference and query
nX substitution reference and query
nI insertion in the query query
nD deletion from the query reference

The count n is always written. There is no M, except in the VCF output.

A template switch looks like this:

[TS<descendant><ancestor><direction>:<uncertainty range>:<first offset>:<inner alignment>:<anti-descendant gap>]
field values meaning
descendant R / Q the sequence that carries the copy
ancestor R / Q the sequence that was copied from
direction R / F R: reverse complement, F: forward
uncertainty range [-a,b]:[-c,d] or [-]:[-] see Uncertainty ranges
first offset integer jump from point 1 to point 2
inner alignment =, X, I, D ops (CIGAR string) alignment of the copy to its template
anti-descendant gap integer jump from point 1 to point 4

The first three letters name the geometry as in the cost file, e.g. QRR: the query carries the reverse complement of a piece of the reference. The default costs only allow QRR and RQR. An RQ switch explains the cluster the other way round: the reference carries a copy of the query.

Switches don’t nest. Several may follow each other, separated by ordinary operations. By default all template switches in one alignment share the same descendant (see --allow-mixed-descendants).

Geometry

A template switch has four points (see also Aligner Costs). Points are boundaries between bases.

  1. Point 1: where [TS stands. The descendant leaves the ordinary alignment here.
  2. Point 2: point 1’s position, plus first offset. The copy starts here.
  3. Point 3: where the copy ends. Not written; it follows from the inner alignment.
  4. Point 4: point 1’s position in the anti-descendant (the sequence that is not the descendant), plus the anti-descendant gap. The ordinary alignment resumes here.

The inner alignment aligns the descendant, read forward from point 1, to the ancestor, read from point 2:

  • forward (F): rightwards, base by base;
  • reverse (R): leftwards, complementing each base.

So the template is ancestor[p2, p3) (forward) or ancestor[p3, p2) (reverse). Inside the switch, = and X consume both, I only the descendant, D only the ancestor.

At ], the descendant continues right after the copy and the anti-descendant continues at point 4. The bases between points 1 and 4 of the anti-descendant are replaced by the copy. A negative gap means point 4 lies left of point 1: those bases are repeated.

Offsets and gaps are relative, so a TSIGAR string reads the same whatever its start coordinate. The template may lie outside the aligned stretch; resolve it against the reference genome.

Example

5=[TSQRR:[0,0]:[0,0]:8:5=:3]8=
         0     5     8     13
ref      GTCAG TTA   CCATG AGT
                    3<----2
              1---->4
qry      GTCAG CATGG CCATG AGT
  • 5=: GTCAG matches.
  • [TSQRR: the query copies the reverse complement of the reference. Point 1 is at reference position 5.
  • 8: point 2 is at 5 + 8 = 13.
  • 5=: the query continues with 5 bases that match the reference read leftwards from 13 and complemented: ref[8,13) = CCATG → CATGG. Point 3 is at 8.
  • 3]: point 4 is at 5 + 3 = 8. The reference bases TTA are replaced by the copy.
  • 8=: CCATGAGT matches.

Uncertainty ranges

[-<start left>,<start right>]:[-<end left>,<end right>]

How far the start (points 1 and 2) and the end (points 3 and 4) of the switch can be moved left or right. With the default --uncertainty-range-mode equal-cost, a move must not increase the alignment cost. The shifts cannot reach beyond the alignment range (aln_region), so a switch on its edge reports 0 towards that edge.

[-]:[-] means not computed: with --uncertainty-range-mode none, and always with --fpa.

Where it appears

output field reference / query
CSV ts_cigar aln_region of reference / query
CSV ts_cigar_ctx ref_ctx_region / alt_ctx_region
VCF INFO CIGARETS REF / ALT of the record, starting at POS

In the VCF, = is written as M and , as %2C, so that the value needs no further escaping. Restore it with:

bcftools query -f '%INFO/CIGARETS\n' output.vcf | sed 's/%2C/,/g; s/M/=/g'

Example vcf record, its query copying the reverse complement of the first 8 reference bases (a palindrome) and replacing all 20:

chr1  4304583  .  ACACGTGTGTGTGTGTGTGT  ACACGTGT  ...  CIGARETS=[TSQRR:[0%2C0]:[0%2C0]:8:8M:20];TSCOST=2;TSINNERLEN=8;TSJUMP=8

TSJUMP and the CSV column ts_1_2 repeat the first offset, ts_1_4 the anti-descendant gap, and TSINNERLEN / ts_2_3 the descendant length of the inner alignment.