Changes

The <code>stats</code> option on the [[BamUtil]] executable generates the specified statistics on a SAM/BAM file. == Troubleshooting ==See [[BamUtil:_FAQ#BamUtil:_stats|BamUtil: FAQ -> BamUtil: stats]] for troubleshooting help.

./bam stats --in <inputFile> [--basic] [--qual] [--phred] [--baseQC pBaseQC <outputFileName>] [--cBaseQC <outputFileName>] [--maxNumReads <maxNum>][--unmapped] [--bamIndex <bamIndexFile>] [--regionList <regFileName>] [--minMapQual requiredFlags <minMapQintegerRequiredFlags>] [--dbsnp excludeFlags <dbsnpFileintegerExcludeFlags>] [--sumStatsnoeof] [--params] [--withinRegion] [--baseSum] [--noeofbufferSize <buffSize>] [--minMapQual <minMapQ>] [--paramsdbsnp <dbsnpFile>]</pre>  

Required Parameters: --in : the SAM/BAM file to calculate stats for Types of Statistics that can be generated: --basic : Turn on basic statistic generation --qual : Generate a count for each quality (displayed as non-phred quality) --phred : Generate a count for each quality (displayed as phred quality) --baseQC pBaseQC : Write per base statistics as Percentages to the specified file. (use - for stdout) pBaseQC & cBaseQC cannot both be specified. --cBaseQC : Write per base statistics as Counts to the specified file. (use - for stdout) pBaseQC & cBaseQC cannot both be specified. Optional Parameters: --maxNumReads : Maximum number of reads to process Defaults to -1 to indicate all reads. --unmapped : Only process unmapped reads (requires a bamIndex file) --bamIndex : The path/name of the bam index file (if required and not specified, uses the --in value + ".bai") --regionList : File containing the regions to be processed chr<tab>start_pos<tab>end<pos>end_pos. Positions are 0 based and the end_pos is not included in the region. Uses bamIndex. --minMapQual excludeFlags : The minimum mapping quality for filtering reads in Skip any records with any of the specified flags set (specify an integer representation of the baseQC stats.flags) --dbsnp requiredFlags : The dbSnp file Only process records with all of the specified flags set (specify an integer representation of positions to exclude from baseQC analysis.the flags) --noeof : Do not expect an EOF block on a bam file. --params : Print the parameter settings. Optional phred/qual Only Parameters: --withinRegion : Only count qualities if they fall within regions specified. Only applicable if regionList is also specified. Optional Base QC BaseQC Only Parameters: --baseSum : Print an overall summary of the baseQC for the file to stderr. --bufferSize : Size of the pileup buffer for calculating the BaseQC parameters. Default: 1024 --sumStats minMapQual : Alternate summary outputThe minimum mapping quality for filtering reads in the baseQC stats. --dbsnp : The dbSnp file of positions to exclude from baseQC analysis.

For all types {{PhoneHomeParamDesc}} == Required Parameters == {{inBAMInputFile}} == Optional Parameters ===== Maximum number of reads to process(<code>--maxNumReads</code>) ===Use <code>--maxNumReads</code> followed by a number to indicate the maximum number of statisticsreads to process before exiting. By default, it is set to -1 to indicate all reads should be processed. === Only Process Unmapped Reads (<code>--unmapped</code>) ===Use <code>--unmapped</code> to process only unmapped reads. This parameter requires [[#Bam Index File (--bamIndex)|<code>--bamIndex</code>]]. {{BamIndex}} === Only Process Certain Regions (<code>--regionList</code>) ===Use <code>--regionList</code> followed by the filename to process only the regions specified in the file. The positions in the bam file used are specified one per line with the following format: <nowiki>chr<tab>start_pos<tab>end_pos.</nowiki> Positions are 0 based and the end_pos is specified by not included in the region. This parameter requires [[#Bam Index File (--bamIndex)|<code>--inbamIndex</code>]].

The optional parameters are also used for all types === Exclude Flags (<code>--excludeFlags</code>) ===Use <code>--excludeFlags</code> followed by an integer representation of statisticsthe flags to only process reads with any of the specified flags set.

== Types of Statistics ==

=== Basic (<code>--basic</code>) ===

=== Qual/Phred (<code>--phred</code> and <code>--qual</code>) ===

Prints a count of the number of times each quality value appears in the fileto stderr.

<br> By default, these counts include all qualities in the BAM file. To exclude unmapped reads and soft clips, use --excludeFlags 4.

== BaseQC To only include records that overlap a set of regions, use --regionList and specify a bed file with the regions. ==If a read overlaps the region, all qualities will be counted even if those bases do not fall in the region. If you only want to count qualities that fall within the region, also specify --withinRegion. Without excluding unmapped reads, it will include soft clips that overlap the region.

The ==== Optional Phred/Qual Only Parameters ========= Within Region (<code>--withinRegion</code>) =====Use <code>baseQC--withinRegion</code> option generates with [[#Qual/Phred (--phred and --qual)|<code>--phred</code> or <code>--qual</code>]] options to only count qualities if they fall within the following statistics: regions specified using [[#Only Process Certain Regions (--regionList)|<code>--regionList</code>]] (only applicable if [[#Only Process Certain Regions (--regionList)|<code>--regionList</code>]] is also specified).

A read spans a position if the read starts at or before the position, ends at or after the position === BaseQC (<code>--pBaseQC</code> and the position is not a clip. CIGAR operations allowed for the position are M<code>--cBaseQC</Xcode> and <code>--baseSum</code>) ===/D/N. If the CIGAR is '*', only numbers for the specified reference position are incremented.

Currently there is no special The <code>pBaseQC</code> and <code>cBaseQC</code> options generate per base statistics. Only one of these two options can be specified. They write statistics generated for each position to the file specified after the option (use <code>-</code> to write to STDOUT). They use the same logic to exclude positionsfor calculating statistics, but <code>pBaseQC</reads where code> writes the reference base is 'N' or statistics as percentages, and <code>cBaseQC</code> writes them as counts. The order of the read base is 'N'statistics are also different.

The <brcode> baseSum</code> option can be used with either <code>pBaseQC</code> or <code>cBaseQC</code> or on its own. <code>baseSum</code> generates a summary of the per position statistics and writes it to stderr. It calculates the per position base statistics even if they will not be written anywhere (neither <code>pBaseQC</code> nor <code>cBaseQC</code> are specified).

There All three options use the same logic for calculating the statistics:* A read spans a position if the read starts at or before the position, ends at or after the position and the position is not a clip. CIGAR operations allowed for the position are two output options M/X/=/D/N. If the CIGAR is '*', only numbers for BaseQCthe specified reference position are incremented.*Currently there is no special logic to exclude positions/reads where the reference base is 'N' or the read base is 'N'.

==== Percentage-Based Output Format (<code>--pBaseQC</code>) ====

  ==== Count-Based Output Format (<code>--cBaseQC</code>) ====