Alignment Statistics

--output-alignment-stats FILE writes one CSV row per alignment, covering how long it took, how much memory it used, where the result came from, and what the aligner reported. It is available on both twitcher vcf and twitcher reads.

twitcher reads reads.bam --reference ref.fa.gz --output-alignment-stats stats.csv

Columns

Column	Meaning
cluster_region	The realigned cluster, in samtools region format. This is the region the cluster’s mutations edit, the same coordinates the CSV output and the log lines use
source	computed, mem_cache or db
aligner	astar or fpa
outcome	ts, no_ts, oom, timeout or error
cost	Cost of the reported alignment
ts_num	Number of template switches in the alignment
wall_ms	Wall clock time of the whole alignment, including spawning the aligner process
align_ms	Time spent aligning. wall_ms - align_ms is the process and IPC overhead
peak_rss	Peak resident set size of the aligner process, in bytes (VmHWM)
peak_vsz	Peak virtual memory size of the aligner process, in bytes (VmPeak)
memory_limit	The memory allowance the aligner process was given, in bytes
opened_nodes, closed_nodes, suboptimal_nodes, suboptimal_ratio	A* search statistics
cost_per_base	Cost normalised by the aligned length
reference_length, query_length	Length of the padded sequences handed to the aligner
error	An error message, for error outcomes

Columns that do not apply to a row are empty: the A* search statistics for --fpa runs, and everything the aligner reports for failures.

Compare peak_vsz against memory_limit, not peak_rss: the limit is an RLIMIT_AS, which bounds address space. Keep in mind that memory_limit is --memory-limit divided by the number of threads, so it shrinks as you add parallelism.

One row per request, not per alignment

A row is written whenever a cluster receives its result, so two clusters that map to the same alignment produce two rows. Only one of them was actually computed; the other reports mem_cache or db.

The execution statistics are stored alongside the result, so a mem_cache or db row replays the runtime and memory of the run that originally produced it. Those numbers are historical: they are not the cost of the lookup.

To see only the alignments that were really run, filter on source:

awk -F, 'NR == 1 || $2 == "computed"' stats.csv > computed.csv

Or filter while the run is in progress, without ever writing the full file to disk:

twitcher reads reads.bam --reference ref.fa.gz \
  --output-alignment-stats >(awk -F, 'NR == 1 || $2 == "computed"' > computed.csv)

Failures

Timeouts report their memory, which is read from the aligner process just before it is killed.

A hard out-of-memory abort does not: the process dies before it can report anything, so peak_rss and peak_vsz are empty and memory_limit is the only memory figure in the row.

chr1:42904481-42904500,computed,astar,oom,,,1089.6357329999998,,,,71428,,,,,,420,419,

Relation to --output-failed-alignments

--output-failed-alignments writes only the regions of failed alignments, one per line, in samtools region format. That file can be passed straight back to samtools, bcftools or twitcher via -R / -T; the statistics CSV cannot. The two flags are independent and can be used together.

A cluster that edits no reference base, e.g. a single insertion, has a zero-width region, written as chr1:102-101. Twitcher reads that back as the empty interval it is, but samtools and bcftools reject it. The vcf subcommand’s CSV output carries the vcf_record_region column for those cases: it is the POS-based extent of the underlying records, which is never empty.