samtools-stats(1)

📦
version 1.24 · 10 versions
, in epel 10, nixpkgs unstable

💅 samtools-stats(1): the stats glow-up manual 💅

🌸 NAME 🌸

samtools stats — produces comprehensive statistics from an alignment file, like a full vibe check for your reads 💖

✨ SYNOPSIS ✨

samtools stats [options] in.sam|in.bam|in.cram [region...]

🦋 DESCRIPTION 🦋

Okay so samtools stats collects statistics from BAM files and outputs them in a text format. Bestie, the output can be visualized graphically using plot-bamstats, which is giving “data but make it cute” ✨

Here’s the output section lineup first, then the detailed lore:

  • CHK — Checksum
  • SN — Summary numbers
  • FFQ — First fragment qualities
  • LFQ — Last fragment qualities
  • GCF — GC content of first fragments
  • GCL — GC content of last fragments
  • GCC — ACGT content per cycle
  • GCT — ACGT content per cycle, read oriented
  • FBC — ACGT content per cycle for first fragments only
  • FTC — ACGT raw counters for first fragments
  • LBC — ACGT content per cycle for last fragments only
  • LTC — ACGT raw counters for last fragments
  • BCC — ACGT content per cycle for BC barcode
  • CRC — ACGT content per cycle for CR barcode
  • OXC — ACGT content per cycle for OX barcode
  • RXC — ACGT content per cycle for RX barcode
  • MPC — Mismatch distribution per cycle
  • QTQ — Quality distribution for BC barcode
  • CYQ — Quality distribution for CR barcode
  • BZQ — Quality distribution for OX barcode
  • QXQ — Quality distribution for RX barcode
  • IS — Insert sizes
  • RL — Read lengths
  • FRL — Read lengths for first fragments only
  • LRL — Read lengths for last fragments only
  • MAPQ — Mapping qualities
  • ID — Indel size distribution
  • IC — Indels per cycle
  • COV — Coverage (depth) distribution
  • GCD — GC-depth
  • RFS — Reference Statistics

The “cycle” terminology used here originates from the Illumina instruments, but it is interpreted more generally as the Nth base reported in the original read orientation (starting from 1). 🧬

Not all sections will be reported, because some depend on the data being coordinate sorted while others are only present when specific barcode tags are in use. It’s giving “it depends,” lowkey.

Some of the statistics are collected for “first” or “last” fragments. Records are put into these categories using the PAIRED (0x1), READ1 (0x40) and READ2 (0x80) flag bits, as follows:

  • Unpaired reads (i.e. PAIRED is not set) are all “first” fragments. For these records, the READ1 and READ2 flags are ignored.
  • Reads where PAIRED and READ1 are set, and READ2 is not set are “first” fragments.
  • Reads where PAIRED and READ2 are set, and READ1 is not set are “last” fragments.
  • Reads where PAIRED is set and either both READ1 and READ2 are set or neither is set are not counted in either category.

Information on the meaning of the flags is given in the SAM specification document at https://samtools.github.io/hts-specs/SAMv1.pdf. 📄

The CHK row contains distinct CRC32 checksums of read names, sequences and quality values. The checksums are computed per alignment record and summed, meaning the checksum does not change if the input file has the sort-order changed. Slay, stable checksums.

NOTE: Checksum calculation for quality values was modified and quality checksum value will be different from that generated using versions up to 1.21. ⚠️

The SN section contains a series of counts, percentages, and averages, in a similar style to samtools flagstat, but more comprehensive. It’s the main character of summary sections, honestly 👑

  • raw total sequences — total number of reads in a file, excluding supplementary and secondary reads. Same number reported by samtools view -c -F 0x900.
  • filtered sequences — number of discarded reads when using -f or -F option.
  • sequences — number of processed reads.
  • is sorted — flag indicating whether the file is coordinate sorted (1) or not (0).
  • 1st fragments — number of first fragment reads (flags 0x01 not set; or flags 0x01 and 0x40 set, 0x80 not set).
  • last fragments — number of last fragment reads (flags 0x01 and 0x80 set, 0x40 not set).
  • reads mapped — number of reads, paired or single, that are mapped (flag 0x4 or 0x8 not set).
  • reads mapped and paired — number of mapped paired reads (flag 0x1 is set and flags 0x4 and 0x8 are not set).
  • reads unmapped — number of unmapped reads (flag 0x4 is set).
  • reads properly paired — number of mapped paired reads with flag 0x2 set.
  • paired — number of paired reads, mapped or unmapped, that are neither secondary nor supplementary (flag 0x1 is set and flags 0x100 (256) and 0x800 (2048) are not set).
  • reads duplicated — number of duplicate reads (flag 0x400 (1024) is set).
  • reads MQ0 — number of mapped reads with mapping quality 0.
  • reads QC failed — number of reads that failed the quality checks (flag 0x200 (512) is set).
  • non-primary alignments — number of secondary reads (flag 0x100 (256) set).
  • supplementary alignments — number of supplementary reads (flag 0x800 (2048) set).
  • total length — number of processed bases from reads that are neither secondary nor supplementary (flags 0x100 (256) and 0x800 (2048) are not set).
  • total first fragment length — number of processed bases that belong to first fragments.
  • total last fragment length — number of processed bases that belong to last fragments.
  • bases mapped — number of processed bases that belong to reads mapped.
  • bases mapped (cigar) — number of mapped bases filtered by the CIGAR string corresponding to the read they belong to. Only alignment matches(M), inserts(I), sequence matches(=) and sequence mismatches(X) are counted.
  • bases trimmed — number of bases trimmed by bwa, that belong to non secondary and non supplementary reads. Enabled by -q option.
  • bases duplicated — number of bases that belong to reads duplicated.
  • mismatches — number of mismatched bases, as reported by the NM tag associated with a read, if present.
  • error rate — ratio between mismatches and bases mapped (cigar).
  • average length — ratio between total length and sequences.
  • average first fragment length — ratio between total first fragment length and 1st fragments.
  • average last fragment length — ratio between total last fragment length and last fragments.
  • maximum length — length of the longest read (includes hard-clipped bases).
  • maximum first fragment length — length of the longest first fragment read (includes hard-clipped bases).
  • maximum last fragment length — length of the longest last fragment read (includes hard-clipped bases).
  • average quality — ratio between the sum of base qualities and total length.
  • insert size average — the average absolute template length for paired and mapped reads.
  • insert size standard deviation — standard deviation for the average template length distribution.
  • inward oriented pairs — number of paired reads with flag 0x40 (64) set and flag 0x10 (16) not set or with flag 0x80 (128) set and flag 0x10 (16) set.
  • outward oriented pairs — number of paired reads with flag 0x40 (64) set and flag 0x10 (16) set or with flag 0x80 (128) set and flag 0x10 (16) not set.
  • pairs with other orientation — number of paired reads that don't fall in any of the above two categories.
  • pairs on different chromosomes — number of pairs where one read is on one chromosome and the pair read is on a different chromosome.
  • percentage of properly paired reads — percentage of reads properly paired out of sequences.
  • bases inside the target — number of bases inside the target region(s) (when a target file is specified with -t option).
  • percentage of target genome with coverage > VAL — percentage of target bases with a coverage larger than VAL. By default, VAL is 0, but a custom value can be supplied by the user with -g option.

The FFQ and LFQ sections report the quality distribution per first/last fragment and per cycle number. They have one row per cycle (reported as the first column after the FFQ/LFQ key) with remaining columns being the observed integer counts per quality value, starting at quality 0 in the left-most row and ending at the largest observed quality. Thus each row forms its own quality distribution and any cycle specific quality artefacts can be observed. It’s giving quality drama per cycle 😭

GCF and GCL report the total GC content of each fragment, separated into first and last fragments. The columns show the GC percentile (between 0 and 100) and an integer count of fragments at that percentile. GC but split, periodt 💅

GCC, FBC and LBC report the nucleotide content per cycle either combined (GCC) or split into first (FBC) and last (LBC) fragments. The columns are cycle number (integer), and percentage counts for A, C, G, T, N and other (typically containing ambiguity codes) normalised against the total counts of A, C, G and T only (excluding N and other). A/C/G/T girlies stay winning 🌈

GCT offers a similar report to GCC, but whereas GCC counts nucleotides as they appear in the SAM output (in reference orientation), GCT takes into account whether a nucleotide belongs to a reverse complemented read and counts it in the original read orientation. If there are no reverse complemented reads in a file, the GCC and GCT reports will be identical. No reverse complements, no difference, iconic 🦋

FTC and LTC report the total numbers of nucleotides for first and last fragments, respectively. The columns are the raw counters for A, C, G, T and N bases. Raw counters, no filter, we love to see it 🫶

MPC reports the number of mismatches per cycle and per quality value. The MPC statistics are only included when a reference is specified via the -r option. There is one row per cycle number. Each row includes the cycle number, the number of N bases (not counted in the per-qual columns), followed by one column per quality value (starting at zero and incrementing by one each time) listing the number of non-N mismatches with that quality. A mismatch is defined as an ACGT sequence base mismatching an ACGT reference base. Ambiguity codes are ignored (except for sequence N as mentioned above, which is counted even when the reference is also N). Mismatch lore, but make it per quality 🔥

okay so we're still in DESCRIPTION bestie — here's the rest of the section list, no cap 💅

BCC, CRC, OXC and RXC</p> are literally the barcode equivalent of GCC — they show you the nucleotide content for the barcode tags BC, CR, OX and RX respectively 🧬. Their quality value distributions live in the QTQ, CYQ, BZQ and QXQ sections, and those correspond to the BC/QT, CR/CY, OX/BZ and RX/QX SAM format sequence/quality tags. These quality value distributions follow the exact same format used in the FFQ and LFQ sections, iykyk ✨.

All these section names get a number slapped on the end (1 or 2), and that number tells you whether the stats underneath are for the first or the second barcode — which only happens in the dual indexing case. So you'll see them as BCC1, CRC1, OXC1 and RXC1, hanging out with their quality besties QTQ1, CYQ1, BZQ1 and QXQ1 🫶. And if there's a separator in the barcode sequence (usually a hyphen) — which is the signal that dual indexing is happening — then the sections ending in "2" get reported too, showing the second tag statistics (so like, both BCC1 and BCC2 show up, iconic).

IS</p> reports insert size distributions, one row per size, with the size in the first column 🌸. The columns after that are: frequency of total pairs, inward oriented pairs, outward orient pairs, and other orientation pairs. The -i option sets the maximum insert size that gets reported.

RL</p> reports the distribution for all read lengths, one row per observed length (up to the maximum you set with the -l option). Columns are read length and frequency. FRL and LRL carry the exact same info, just split into first and last fragments 🎀.

MAPQ</p> reports the mapping qualities for the mapped reads — and it ignores duplicates, supplementary, secondary and failing quality reads. Not them, blocked 💀.

ID</p> reports the distribution of indel sizes, one row per observed size. Columns are: size, frequency of insertions at that size, and frequency of deletions at that size.

IC</p> reports the frequency of indels occurring per cycle, broken down by both insertion / deletion and by first / last read 🔥. Quick note bestie: for multi-base indels this only counts the first base location. Columns are cycle, number of insertions in first fragments, number of insertions in last fragments, number of deletions in first fragments, and number of deletions in last fragments.

COV</p> reports a distribution of the alignment depth per covered reference site 👑. For example, an average depth of 50 would ideally give you a normal distribution centred on 50 — but repeats or copy-number variation can pop extra peaks at approximate multiples of 50, which is very much a look 🙈. The first column is an inclusive coverage range in the form of [min-max]. The next columns are a repeat of the maximum portion of the depth range (now as a single integer) and the frequency that depth range was observed. Minimum, maximum and range step size are all controlled by the -c option. Depths above and below the minimum and maximum get reported with ranges [<min] and [max<].

GCD</p> reports the GC content of the reference data aligned against, per alignment record 🌈. One row per observed GC percentage, that percentage in the first column, and the whole thing is sorted on that column. The second column is a total sequence percentile, as a running total (ending at 100%). You can use the first and second columns together to produce a simple distribution of GC content ✨. The subsequent columns list the coverage depth at the 10th, 25th, 50th, 75th and 90th GC percentiles for this specific GC percentage — that's how you spot any GC bias in mapping. Heads up: these columns are averaged depths, so they're floating point with no maximum value.

RFS</p> reports statistics of the reference data 🦋. The first line gives the overall statistics for the reference: total number of targets in the input file and the number covered, then the average GC content, and the minimum, maximum, average and total lengths of the targets in the report. The second and subsequent lines contain the statistics for each individual target. Targets are regions either specified on the command line or given in the target file (the -t option). If you don't choose any regions, all the reference data is used. Each line gives the name of the target, its length, GC content and number of unknown bases. For the GC content and the number of unknown bases you need a reference file (the -t option) — otherwise that value is set to -1. The lengths come from the region specification and from the file header.

✨ OPTIONS ✨

  • -c, --coverage MIN,MAX,STEP — sets the coverage distribution to the range you give (MIN, MAX, STEP, all integers) [1,1000,1]
  • -d, --remove-dups — yeets reads marked as duplicates out of the statistics entirely
  • -f, --required-flag STR|INT — the required flag, 0 means unset. Also peep samtools flags [0]
  • -F, --filtering-flag STR|INT — the filtering flag, 0 means unset. Also peep samtools flags [0]
  • --GC-depth FLOAT — the size of the GC-depth bins (smaller bin size = more memory needed, no cap) [2e4]
  • -h, --help — this help message, your bestie 🫶
  • -i, --insert-size INT — maximum insert size [8000]
  • -I, --id STR — include only the listed read group or sample name [[]]
  • -l, --read-length INT — only reads with the given read length make it into the statistics [-1]
  • -m, --most-inserts FLOAT — report only the main part of inserts [0.99]
  • -P, --split-prefix STR — a path or string prefix to prepend to filenames when you're making categorised statistics files with -S/--split [input filename]
  • -q, --trim-quality INT — the BWA trimming parameter [0]
  • -r, --ref-seq FILE — reference sequence, which is required for GC-depth and mismatches-per-cycle calculation [[]]
  • -S, --split TAG — on top of the complete statistics, also output categorised statistics based on the tagged field TAG (like, use --split RG to split into read groups) 💅
    • Categorised statistics get written to files named <prefix>_<value>.bamstat, where prefix is whatever you gave --split-prefix (or the input filename by default) and value is a value that's been encountered as the specified tagged field's value in one or more alignment records.
  • -t, --target-regions FILE — only do stats in these regions. Tab-delimited file chr,from,to, 1-based, inclusive [[]]
  • -x, --sparse — suppress outputting IS rows where there are no insertions
  • -p, --remove-overlaps — remove overlaps of paired-end reads from coverage and base count computations
  • -g, --cov-threshold INT — only bases with coverage above this value get included in the target percentage computation [0]
  • -X — if this option is set, it lets you specify customised index file location(s) when the data folder has no index file in it. Example usage: samtools stats [options] -X /data_folder/data.bam /index_folder/data.bai chrM:1-10
  • -@, --threads INT — number of input/output compression threads to use in addition to the main thread [0].
  • --ref-stats — create statistics on reference data
  • --ref-stats-chunk INT — number of reference bases to read at a time, in Mbs, for reference statistics [1]

👑 AUTHOR 👑

Written by Petr Danacek, with major modifications by Nicholas Clarke, Martin Pollard, Josh Randall, and Valeriu Ohan — all from the Sanger Institute, absolute icons the lot of them 🎓💖.

🔗 SEE ALSO 🔗

Samtools website: http://www.htslib.org/ ⭐

aaaand that's the whole page bestie, you ate that 🍓✨ this one's from samtools-1.24, dated 9 July 2026, and it's the samtools-stats(1) manual — go forth and stat responsibly, mwah 💜🧚

📦 where this page comes from