samtools-flagstat(1)

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

✨ samtools-flagstat — like, the whole manual page, bestie ✨

okay so this is part of samtools, the bioinformatics toolbox thingy, and honestly? it ate. let's get into it 🫶

💅 NAME

samtools flagstat — counts the number of alignments for each FLAG type. that's it. that's the whole vibe check. it counts stuff by flag. slay. 🔥

🎀 SYNOPSIS

samtools flagstat in.sam|in.bam|in.cram

🌸 DESCRIPTION

so what it does is: it does a full pass through the input file to calculate and print statistics to stdout. like, it reads the whole thing. every single read. no skipping. main character energy fr. ✨

it gives you counts for each of 13 categories, based primarily on bit flags in the FLAG field. if you're sitting there like "what do the flags even mean", the info on the meaning of the flags is given in the SAM specification document <https://samtools.github.io/hts-specs/SAMv1.pdf>. go read it, it's giving homework but it's good for you 📚

each category in the output is broken down into QC pass and QC fail. in the default output format, these are presented as #PASS + #FAIL followed by a description of the category. iconic formatting tbh.

the first row of output gives the total number of reads that are QC pass and fail (according to flag bit 0x200). for example:

122 + 28 in total (QC-passed reads + QC-failed reads)

which would indicate that there are a total of 150 reads in the input file, 122 of which are marked as QC pass and 28 of which are marked as "not passing quality controls". the math is mathing 💅

following this, additional categories are given for reads which are:

  • primary — neither 0x100 (SECONDARY) nor 0x800 (SUPPLEMENTARY) bit set
  • secondary — 0x100 (SECONDARY) bit set
  • supplementary — 0x800 (SUPPLEMENTARY) bit set
  • duplicates — 0x400 (DUP) bit set
  • primary duplicates — 0x400 (DUP) bit set and neither 0x100 (SECONDARY) nor 0x800 (SUPPLEMENTARY) bit set
  • mapped — 0x4 (UNMAP) bit not set
  • primary mapped — 0x4 (UNMAP), 0x100 (SECONDARY) and 0x800 (SUPPLEMENTARY) bits not set
  • paired in sequencing — 0x1 (PAIRED) bit set
  • read1 — both 0x1 (PAIRED) and 0x40 (READ1) bits set
  • read2 — both 0x1 (PAIRED) and 0x80 (READ2) bits set
  • properly paired — both 0x1 (PAIRED) and 0x2 (PROPER_PAIR) bits set and 0x4 (UNMAP) bit not set
  • with itself and mate mapped — 0x1 (PAIRED) bit set and neither 0x4 (UNMAP) nor 0x8 (MUNMAP) bits set
  • singletons — both 0x1 (PAIRED) and 0x8 (MUNMAP) bits set and bit 0x4 (UNMAP) not set

and finally, two rows are given that additionally filter on the reference name (RNAME), mate reference name (MRNM), and mapping quality (MAPQ) fields. extra credit rows, lowkey:

  • with mate mapped to a different chr — 0x1 (PAIRED) bit set and neither 0x4 (UNMAP) nor 0x8 (MUNMAP) bits set and MRNM not equal to RNAME
  • with mate mapped to a different chr (mapQ>=5) — 0x1 (PAIRED) bit set and neither 0x4 (UNMAP) nor 0x8 (MUNMAP) bits set and MRNM not equal to RNAME and MAPQ >= 5

🌈 ALTERNATIVE OUTPUT FORMATS

the -O option can be used to select two alternative formats for the output. two whole other aesthetics. choose your fighter 🦋

using -O tsv selects a tab-separated values format that can easily be imported into spreadsheet software. yes, spreadsheet girlies, this one's for you 🍓 in this format the first column contains the values for QC-passed reads, the second column has the values for QC-failed reads and the third contains the category names.

using -O json generates an ECMA-404 JSON data interchange format object <https://www.json.org/>. the top-level object contains two named objects QC-passed reads and QC-failed reads. these contain the various categories listed above as names and the corresponding count as value. it's giving API-ready. ngl kinda obsessed 🔥

for the default format, mapped shows the count as a percentage of the total number of QC-passed or QC-failed reads after the category name. for example:

32 + 0 mapped (94.12% : N/A)

the properly paired and singletons counts work in a similar way but the percentage is against the total number of QC-passed and QC-failed pairs. the primary mapped count is a percentage of the total number of QC-passed and QC-failed primary reads. okay so different denominators, don't get it twisted 💀

in the tsv and json formats, these percentages are listed in separate categories mapped %, primary mapped %, properly paired %, and singletons %. if the percentage cannot be calculated (because the total is zero) then in the default and tsv formats it will be reported as N/A. in the json format, it will be reported as a JSON null value. no dividing by zero here bestie, we're not doing that 🙈

⭐ OPTIONS ⭐

  • -@ INT — set number of additional threads to use when reading the file. more threads = more go brrr 🧚
  • -O FORMAT — set the output format. FORMAT can be set to default, json or tsv to select the default, JSON or tab-separated values output format. if this option is not used, the default format will be selected. defaults gonna default 💜

👑 AUTHOR

written by Heng Li from the Sanger Institute. king behavior, honestly. 👑

💖 SEE ALSO

samtools website: <http://www.htslib.org/>

and that's the whole page, bestie 🌟 this one's samtools-1.24, dated 9 July 2026 — go forth and flagstat your little heart out, iykyk 💅✨🌸

📦 where this page comes from