Skip to main content
v2026.11,986 entries · CC-BY 4.0

featureCounts: RNA-seq read counting explained

Understand what featureCounts counts, how annotation and paired-end settings define a gene matrix, and which defaults differ in Rsubread.

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.

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

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.

featureCounts command-line and R setting crosswalk
Counting decisionCommand-line controlRsubread controlInterpretation or defaultSource attribution
Select exon records-t exonGTF.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-featuresGTF.attrType = "gene_id"; useMetaFeatures = TRUEGene-level targets combine exon records sharing the identifier.Subread Users Guide; Rsubread reference
Identify paired-end input-pisPairedEnd = TRUEDeclares library layout; the fragment-counting setting is separate.Subread changelog; Rsubread reference
Count paired-end fragments-p --countReadPairsisPairedEnd = TRUE; countReadPairs = TRUER 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 2strandSpecific = 0, 1 or 20 unstranded; 1 stranded; 2 reverse stranded. Default is 0.Subread Users Guide; Rsubread reference
Multimapping evidenceExcluded by default; -M includes itcountMultiMappingReads = TRUE by defaultThe two interfaces differ in the default treatment of multimapping evidence.Subread Users Guide section 6.2.6; Rsubread reference
Multiple overlapping targetsExcluded by default; -O includes themallowMultiOverlap = FALSE by defaultThe control concerns target overlap, separately from multiple mapping locations.Subread overview; Rsubread reference

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about featureCounts: RNA-seq read counting explained

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →