CSV Output

The CSV is the main output of twitcher reads (-o) and an optional one (although increasingly also the primary one) of twitcher vcf (--csv). Both modes write the same format: one row per realigned cluster that contains a template switch (with --all-clusters, reads writes the others too).

Each row has enough data to rebuild the alignment from a reference to the reference genome alone. That makes the CSV the bridge to everything after twitcher:

• twitcher viz reads it and draws one SVG per row.
• Twitcher Workbench takes it as input for post-processing.

Regions

Three regions are reported for every cluster:

column	meaning
cluster_region	the reference bases the mutations edit (see Clustering)
aln_region	cluster_region plus --range-extension bases on either side: the region the alignment covers, and what fw_cigar, ts_cigar, fw_cost and ts_cost are relative to. A template switch must start and end inside it.
ref_ctx_region / alt_ctx_region	the padded window (--padding), which a template switch may jump into, and what the _ctx columns are relative to

Naming

• fw_ columns describe the forward alignment: the plain alignment without template switches, as given by the VCF records or the read’s CIGAR.
• ts_ columns describe the template switch alignment Twitcher found.
• A _ctx suffix means the column covers the whole context region instead of only aln_region. For example ts_cigar spans aln_region, ts_cigar_ctx spans ref_ctx_region / alt_ctx_region.

Comparing fw_cost with ts_cost shows how much better the template switch explains the cluster.

CIGAR columns are in the TSIGAR format. If an alignment has several template switches (ts_num > 1), the per-switch columns (ts_1_2, ts_2_3, ts_1_4, …) hold one value per switch, separated by |.

Important columns

column	why
cluster_region	where the event is; the coordinate logs and other outputs use
read_id / sample_name	which read (reads) or sample (vcf) it came from
ts_cigar	the template switch alignment, see TSIGAR
fw_cost, ts_cost	cost without and with template switches
ts_num	number of template switches
ts_1_4_region	the reference stretch a switch replaces; useful to deduplicate events seen on many reads
cluster_id / cluster_grp	link rows to each other and to the VCF output; cluster_grp is shared by the haplotype sub-clusters of one proximity cluster
ref_ctx_region, fw_cigar_ctx, fw_mi_ctx	together with the reference, rebuild the alt sequence; fw_mi_ctx lists the inserted and substituted bases