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 nor 0x800 bit set

                         secondary
                                0x100 bit set

                         supplementary
                                0x800 bit set

                         duplicates
                                0x400 bit set

                         primary duplicates
                                0x400 bit set and neither 0x100 nor 0x800 bit set

                         mapped 0x4 bit not set

                         primary mapped
                                0x4, 0x100 and 0x800 bits not set

                         paired in sequencing
                                0x1 bit set

                         read1  both 0x1 and 0x40 bits set

                         read2  both 0x1 and 0x80 bits set

                         properly paired
                                both 0x1 and 0x2 bits set and 0x4 bit not set

                         with itself and mate mapped
                                0x1 bit set and neither 0x4 nor 0x8 bits set

                         singletons
                                both 0x1 and 0x8 bits set and bit 0x4 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 bit set and neither 0x4 nor 0x8 bits set and MRNM not equal to RNAME

                         with mate mapped to a different chr (mapQ>=5)
                                0x1 bit set and neither 0x4 nor 0x8 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