Overview

This tool takes an alignment file in SAM or BAM format and feature file in GFF format and calculates the number of reads mapping to each feature. It uses the htseq-count script that is part of the HTSeq python module. See https://htseq.readthedocs.io/en/latest/ for details.

A feature is an interval (i.e., a range of positions) on a chromosome or a union of such intervals. In the case of RNA-Seq, the features are typically genes, where each gene is considered here as the union of all its exons. One may also consider each exon as a feature, e.g., in order to check for alternative splicing. For comparative ChIP-Seq, the features might be binding regions from a pre-determined list.

Overlap Modes

Special care must be taken to decide how to deal with reads that align to or overlap with more than one feature. The htseq-count script allows to choose between three modes. See also the FAQ, if the following explanation seems too technical.

The three overlap resolution modes of htseq-count work as follows. For each position i in the read, a set S(i) is defined as the set of all features overlapping position i. Then, consider the set S, which is (with i running through all position within the read or a read pair)

• the union of all the sets S(i) for mode union. This mode is recommended for most use cases.
• the intersection of all the sets S(i) for mode intersection-strict.
• the intersection of all non-empty sets S(i) for mode intersection-nonempty.

If S contains precisely one feature, the read (or read pair) is counted for this feature. If S is empty, the read (or read pair) is counted as no_feature. If S contains more than one feature, htseq-count behaves differently based on the --nonunique option:

• --nonunique none (default): the read (or read pair) is counted as ambiguous and not counted for any features. Also, if the read (or read pair) aligns to more than one location in the reference, it is scored as alignment_not_unique.
• --nonunique all: the read (or read pair) is counted as ambiguous and is also counted in all features to which it was assigned. Also, if the read (or read pair) aligns to more than one location in the reference, it is scored as alignment_not_unique and also separately for each location.

Notice that when using --nonunique all the sum of all counts will not be equal to the number of reads (or read pairs), because those with multiple alignments or overlaps get scored multiple times.

The following figure illustrates the effect of these three modes and the --nonunique option:

Strandedness

Important: The default for strandedness is yes. Be sure to choose the correct value.

To check which value is correct, select forward and reverse independently. If the overall counts drop at one condition then the opposite condition is correct, otherwise your data is not stranded.

Output

The script outputs a table with counts for each feature, followed by the special counters, which count reads that were not counted for any feature for various reasons, namely

• no_feature: reads which could not be assigned to any feature (set S as described above was empty).
• ambiguous: reads which could have been assigned to more than one feature and hence were not counted for any of these (set S had mroe than one element).
• too_low_aQual: reads which were not counted due to the -a option, see below
• not_aligned: reads in the SAM file without alignment
• alignment_not_unique: reads with more than one reported alignment. These reads are recognized from the NH optional SAM field tag. (If the aligner does not set this field, multiply aligned reads will be counted multiple times.)

Options Summary

Usage: htseq-count [options] sam_file gff_file

This script takes an alignment file in SAM format and a feature file in GFF format and calculates for each feature the number of reads mapping to it. See https://htseq.readthedocs.io/en/latest/ for details.

Options:

-f <format>, --format=<format>
	Format of the input data. Possible values are sam (for text SAM files) and bam (for binary BAM files). Default is sam.
-r <order>, --order=<order>
	For paired-end data, the alignment have to be sorted either by read name or by alignment position. If your data is not sorted, use the samtools sort function of samtools to sort it. Use this option, with name or pos for <order> to indicate how the input data has been sorted. The default is name. If name is indicated, htseq-count expects all the alignments for the reads of a given read pair to appear in adjacent records in the input data. For pos, this is not expected; rather, read alignments whose mate alignment have not yet been seen are kept in a buffer in memory until the mate is found. While, strictly speaking, the latter will also work with unsorted data, sorting ensures that most alignment mates appear close to each other in the data and hence the buffer is much less likely to overflow.
--max-reads-in-buffer=<number>
	When <alignment_file> is paired end sorted by position, allow only so many reads to stay in memory until the mates are found (raising this number will use more memory). Has no effect for single end or paired end sorted by name. (default: 30000000)
-s <yes/no/reverse>, --stranded=<yes/no/reverse>
	whether the data is from a strand-specific assay (default: yes) For stranded=no, a read is considered overlapping with a feature regardless of whether it is mapped to the same or the opposite strand as the feature. For stranded=yes and single-end reads, the read has to be mapped to the same strand as the feature. For paired-end reads, the first read has to be on the same strand and the second read on the opposite strand. For stranded=reverse, these rules are reversed.
-a <minaqual>, --a=<minaqual>
	skip all reads with alignment quality lower than the given minimum value (default: 10 — Note: the default used to be 0 until version 0.5.4.)
-t <feature type>, --type=<feature type>
	feature type (3rd column in GFF file) to be used, all features of other type are ignored (default, suitable for RNA-Seq analysis using an Ensembl GTF file: exon)
-i <id attribute>, --idattr=<id attribute>
	GFF attribute to be used as feature ID. Several GFF lines with the same feature ID will be considered as parts of the same feature. The feature ID is used to identity the counts in the output table. The default, suitable for RNA-Seq analysis using an Ensembl GTF file, is gene_id.
--additional-attr=<id attributes>
	Additional feature attributes, which will be printed as an additional column after the primary attribute column but before the counts column(s). The default is none, a suitable value to get gene names using an Ensembl GTF file is gene_name.
-m <mode>, --mode=<mode>
	Mode to handle reads overlapping more than one feature. Possible values for <mode> are union, intersection-strict and intersection-nonempty (default: union)
--nonunique=<nonunique mode>
	Mode to handle reads that align to or are assigned to more than one feature in the overlap <mode> of choice (see -m option). <nonunique mode> are none and all (default: none)
--secondary-alignments=<mode>
	Mode to handle secondary alignments (SAM flag 0x100). <mode> can be score and ignore (default: score)
--supplementary-alignments=<mode>
	Mode to handle supplementary/chimeric alignments (SAM flag 0x800). <mode> can be score and ignore (default: score)
-o <samout>, --samout=<samout>
	write out all SAM alignment records into an output SAM file called <samout>, annotating each line with its assignment to a feature or a special counter (as an optional field with tag ‘XF’)
-q, --quiet	suppress progress report and warnings
-h, --help	Show a usage summary and exit