Ubuntu Manpage: samtools-flagstat - counts the number of alignments for each FLAG type

NAME

       samtools-flagstat - counts the number of alignments for each FLAG type

SYNOPSIS

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

DESCRIPTION

       Does a full pass through the input file to calculate and print statistics to stdout.

       Provides  counts for each of 13 categories based primarily on bit flags in the FLAG field.
       Information on the meaning of the  flags  is  given  in  the  SAM  specification  document
       <https://samtools.github.io/hts-specs/SAMv1.pdf>.

       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.

       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"

       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:

           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.

Using -O tsv selects a tab-separated values format that can easily be imported into
spreadsheet software. 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.

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.

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.

OPTIONS

       -@ INT    Set number of additional threads to use when reading the file.

       -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.

AUTHOR