Written and maintained by CASRAI Editorial Board
Published
On this page
featureCounts assigns aligned sequencing reads or read pairs to annotated genomic regions, producing a count matrix and assignment statistics. For RNA-seq, its central choices are what constitutes one count and which exons belong to one gene. This guide connects those choices to an illustrative assignment example and a downloadable comparison of command-line and R settings.
Short answer
featureCounts is the counting component of the Subread software family, also available through the Rsubread package. It takes alignment files and genomic annotation, then reports how many qualifying alignments or fragments support each target. The Subread project describes targets ranging from genes and exons to promoters and genomic bins.
For a laboratory receiving a count matrix, the useful question is what its entries represent. A gene count can depend on exon grouping, paired-end handling, strandedness and ambiguity rules. Keep that definition with the matrix: two files with identical gene labels can still encode different counting decisions. The comparison dataset below separates the command-line switches from their R counterparts, including a default that differs between interfaces.
Definition and scope
Read summarization links an alignment to a biological target. An aligner establishes where a sequence maps; featureCounts evaluates those mapped positions against annotated intervals. The input is therefore SAM or BAM alignment data together with annotation, rather than an unaligned sequence file. Our STAR aligner guide covers the preceding alignment task.
The project’s terminology distinguishes a feature from a meta-feature. A feature is an annotated interval, such as an exon. A meta-feature combines intervals sharing an identifier, such as the exons belonging to a gene. Selecting exon records and grouping them by gene identifier therefore produces gene-level counts; it does not automatically produce a separate result for each transcript.
This distinction defines the scope of the output. A matrix of gene assignments answers how much qualifying sequence evidence was allocated to each annotated gene under the selected rules. It does not itself test whether expression differs between experimental conditions. Statistical testing, effect estimates and the experimental design belong to the subsequent analysis.
How featureCounts works in practice
Annotation defines the counting target
The Rsubread reference describes two separate annotation selections: a feature type, normally exon, and an attribute used to group those features, normally gene_id. One identifies which annotation records participate; the other determines which records belong in the same output group. Confusing them changes the question the matrix answers.
Annotation format also needs an explicit interpretation in R: the reference lists isGTFAnnotationFile as FALSE by default, so providing an external GTF involves identifying it as such. The Subread guide recommends unique gene identifiers for grouping because different genes can share names. A readable display label and the identifier establishing a counting group serve different purposes; preserving both avoids making a label change look like a different biological target.
The Subread guide requires the alignment and counting reference genome to agree. It also describes SAF, a simplified tab-delimited annotation carrying an identifier, chromosome, start, end and strand. Its endpoints are inclusive, and reference sequence names must match the alignments. A file containing plausible-looking coordinates is insufficient evidence that its intervals refer to the same assembly. The GTF versus GFF3 comparison explains the related annotation-format distinction.
Read pairs and fragments are separate settings
The Subread changelog records a specific compatibility boundary: release 2.0.2 introduced --countReadPairs, while -p became the declaration that input contains paired-end reads. Thus an old example containing only -p can communicate a different counting intention from an example using both switches. The version and complete arguments are needed to interpret it.
Rsubread expresses the same distinction with isPairedEnd and countReadPairs. Its reference makes countReadPairs applicable only to paired-end input. A request to count fragments should therefore identify both the input layout and the desired unit. Neither a BAM filename nor the presence of two original sequencing files documents that choice.
Strand and ambiguity rules determine eligibility
The R reference defines strandSpecific codes as 0 for unstranded, 1 for stranded and 2 for reversely stranded counting. These encode an analysis assumption about the library. They are not a ranking in which a larger number produces a more accurate result. Preserve the relevant library information alongside the selected code.
Another distinction concerns mapping ambiguity versus target overlap. A multimapping read has alignments at multiple reference locations. A multi-overlapping alignment intersects multiple counting targets. The options controlling these situations are separate; allowing one does not explain how the other is treated. The dataset below identifies the corresponding controls without treating every permissive option as desirable.
Types and related concepts
Gene counts, exon counts and transcript estimates
At gene level, an exon-spanning read that overlaps several component exons contributes once to that gene, provided another gene does not create ambiguity. Counting each participating exon as a separate feature answers a different question. Adding those independently produced exon counts is consequently not a safe substitute for a count made directly at gene level.
Transcript-level estimation introduces another problem: transcripts from the same gene often share sequence. The Subread authors recommend specialized transcript quantification methods for resolving that overlap. Changing an annotation grouping field does not, by itself, supply a model for separating shared transcript evidence.
Illustrative composite: why an exon hit is not a gene count
Consider a fictional annotation in which gene A contains exons A1 and A2, while gene B contains exon B1. An alignment spans A1 and A2 but touches no exon from B. Under the documented gene-level rule, this contributes one to A. Two exon overlaps do not mean two independent observations of the gene.
Now consider a different alignment overlapping both A1 and B1. Under the default multi-overlap exclusion, it contributes to neither gene. If multi-overlap counting is enabled, both targets can receive a contribution. With fractional overlap assignment enabled for these two targets, each receives 1/2. These are illustrative rule outcomes, not measured results or evidence that either gene was the true source.
The arithmetic makes the interpretation visible: under full overlap allocation, one alignment creates two target contributions, 1 + 1 = 2; under fractional allocation it creates 0.5 + 0.5 = 1. Neither calculation resolves biological origin. This is why a column sum must be interpreted in light of its allocation policy, rather than assumed to equal a number of uniquely observed fragments.
Counts and normalized expression units
A counting result is distinct from a normalized expression measure. The DESeq2 vignette requires unnormalized counts or suitable estimated counts and handles library-size differences internally. It specifically documents accepting the counts component returned by Rsubread. Normalizing a matrix in advance simply because sample totals differ changes the intended input. The raw counts, TPM and FPKM comparison covers those units separately.
Where featureCounts matters for laboratory analysis
The consequential handoff is between library information, annotation, counting and statistical analysis. The following editorial checklist organizes the documented parameters into a record a laboratory and analyst can interpret together. It is a synthesis of the project documentation, rather than an official Subread reporting standard.
- Reference identity: retain the assembly and annotation identity used for the count. A descriptive filename alone does not establish compatibility with the alignment reference.
- Target definition: state whether output rows are features or meta-features, which annotation records were selected, and which identifier grouped them. Preserve identifiers separately from optional display names.
- Observation unit: record whether paired-end input was counted as reads or fragments, together with the software interface and version.
- Allocation policy: preserve strand handling, multimapping and multi-overlap treatment, fractional counting and any enabled filters. A bare software name does not specify these choices.
- Sample identity: retain an explicit mapping between each count column and its sample metadata. The DESeq2 vignette requires matrix columns and metadata rows to be in corresponding order.
- Assignment evidence: retain the counting summary together with the matrix, so rejected alignments remain visible when interpreting a sample’s totals.
For example, imagine two analysts receive identical BAM files but one reports individual read counts and the other reports fragment counts. A difference between their matrices is not, on its own, a new biological finding. The comparison first needs a common definition of an observation. The same reasoning applies when one analyst retains multimappers and the other excludes them.
A second illustrative handoff failure is less visible: two sample columns are exchanged while all gene rows remain intact. Every individual count can still be numerically correct, yet the condition labels describe the wrong samples. This follows directly from the DESeq2 requirement to align count columns with metadata rows; successful counting does not verify experimental labels.
Once that handoff is explicit, the count matrix can support the next analytical question without confusing allocation rules with statistical evidence. Our differential gene expression analysis guide covers the modeling stage, including design and interpretation.
Common misunderstandings
The two interfaces have identical defaults
They do not. The Rsubread reference lists countMultiMappingReads as TRUE, whereas the Subread guide describes excluding multimapping reads as the command-line default unless -M is supplied. A switch-by-switch comparison is more informative than assuming that using the same function name reproduces an analysis. The downloadable dataset highlights this difference alongside related controls.
A low assignment total identifies a single cause
The summary records several rejection categories. The guide distinguishes unmapped alignments, insufficient mapping quality, multimapping, absence of overlapping features and ambiguous target overlap, among others. Those categories answer different questions; an unassigned total alone cannot distinguish them. A diagnostic interpretation needs the category breakdown and the active counting settings.
There is a further limit: filters are applied in an order, and an excluded alignment is allocated to its first applicable rejection category. A category count therefore does not enumerate every problem that alignment might have. Removing an earlier exclusion could expose a later one, rather than convert every previously rejected alignment into an assignment.
The Length column is a sample count or one transcript length
The command-line output combines annotation fields with sample count columns. Its Length field reports the number of non-overlapping bases in a feature or meta-feature; for a gene assembled from exons, that is the union of its included exonic bases. It is not another sample’s expression measurement, and it need not represent one particular transcript.
That separation matters when importing the output: annotation describes what was counted, while sample columns contain the observations. Keeping both is useful, but treating every numeric column as a sample changes the matrix. Rsubread makes the distinction explicit by returning counts, annotation and assignment statistics as separate components.
More permissive counting proves more expression
Allowing additional alignments or distributing ambiguous evidence changes the allocation rule. In the fictional example above, both genes receive larger totals when an ambiguous alignment is fully assigned to both. That increase is produced by a parameter choice. Interpreting it as stronger evidence of independent expression would require information the assignment arithmetic does not provide.
Sources
- Subread project: featureCounts overview and examples. Checked 2026-11-14.
- Shi and Liao: Rsubread/Subread Users Guide, chapter 6. Checked 2026-11-14.
- Rsubread reference manual: featureCounts arguments and returned values. Checked 2026-11-14.
- Subread project changelog, release 2.0.2. Checked 2026-11-14.
- Love, Anders and Huber: Analyzing RNA-seq data with DESeq2, input data and count matrix sections. Checked 2026-11-14.
Data: featureCounts command-line and R setting crosswalk
Original crosswalk of counting decisions compiled from the Subread project overview, Users Guide and changelog, and the Rsubread reference manual. Each row connects command-line controls to R parameters and states the interpretation or documented default difference; it is not a recommended universal configuration.
| Counting decision | Command-line control | Rsubread control | Interpretation or default | Source attribution |
|---|---|---|---|---|
| Select exon records | -t exon | GTF.featureType = "exon" | GTF feature-type selection; R setting applies when isGTFAnnotationFile = TRUE. | Subread overview; Rsubread reference |
| Group exons into genes | -g gene_id; omit -f for meta-features | GTF.attrType = "gene_id"; useMetaFeatures = TRUE | Gene-level targets combine exon records sharing the identifier. | Subread Users Guide; Rsubread reference |
| Identify paired-end input | -p | isPairedEnd = TRUE | Declares library layout; the fragment-counting setting is separate. | Subread changelog; Rsubread reference |
| Count paired-end fragments | -p --countReadPairs | isPairedEnd = TRUE; countReadPairs = TRUE | R countReadPairs defaults to TRUE but applies only to paired-end input. | Subread overview and changelog; Rsubread reference |
| Strand handling | -s 0, -s 1 or -s 2 | strandSpecific = 0, 1 or 2 | 0 unstranded; 1 stranded; 2 reverse stranded. Default is 0. | Subread Users Guide; Rsubread reference |
| Multimapping evidence | Excluded by default; -M includes it | countMultiMappingReads = TRUE by default | The two interfaces differ in the default treatment of multimapping evidence. | Subread Users Guide section 6.2.6; Rsubread reference |
| Multiple overlapping targets | Excluded by default; -O includes them | allowMultiOverlap = FALSE by default | The control concerns target overlap, separately from multiple mapping locations. | Subread overview; Rsubread reference |
Sources
- Subread featureCounts overview (accessed 2026-11-14)
- Rsubread/Subread Users Guide, chapter 6 (accessed 2026-11-14)
- Rsubread reference manual, featureCounts (accessed 2026-11-14)
- Subread changelog, release 2.0.2 (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







