Reading and Working With an RNA-seq Count Matrix
By the end of this guide you will have a gene-by-sample count matrix loaded in R or Python. It will be normalized to a scale you can compare across samples, checked for the failure modes that make count matrices misleading, and reduced to a handful of plots that tell you whether the data is usable. You need a set of FASTQ files from a bulk RNA-seq run, paired-end and ideally 30 million or more read pairs per sample. You also need a reference transcriptome and genome annotation for your species, roughly 32 GB of RAM, and a working install of either salmon or STAR plus featureCounts. If you already have a counts file from a sequencing vendor, skip to step 3 and read step 1 anyway, because the choices made upstream determine what the numbers in your file mean.
1. Understand what a single count is
A count matrix has genes on the rows and samples on the columns. Cell (i, j) holds the number of sequenced fragments from sample j that were assigned to gene i. That single sentence hides three decisions that change the number.
The first is what counts as a fragment. In a paired-end library the two mates come from one cDNA molecule. A correctly configured counter therefore increments by one per pair rather than per read. If your matrix totals are suspiciously close to twice your read-pair count, someone counted reads instead of fragments.
The second is how multi-mapping and ambiguous fragments are handled. featureCounts by default discards any fragment that maps to more than one location and any fragment overlapping two genes. Salmon and other expectation-maximization quantifiers instead distribute those fragments probabilistically across compatible transcripts, which is why salmon output contains fractional values like 413.87. Both are defensible. The EM approach recovers signal from paralogs and overlapping isoforms, at the cost of estimates that depend on the model.
The third is what a gene is. The same library quantified against GENCODE v44 and against RefSeq will give different counts for the same locus, because the annotations disagree about transcript boundaries and about which readthrough transcripts exist. Record the annotation version alongside the matrix. A count matrix without its annotation version is close to uninterpretable.
2. Generate counts from FASTQ
We use salmon for bulk RNA-seq quantification. It is fast, it corrects for sequence-specific and GC fragment bias, and it gives you transcript-level estimates you can aggregate to genes when you want them. Build the index once against a decoy-aware transcriptome so that fragments from unannotated genomic regions are not forced onto transcripts.
# Build a decoy-aware index (GENCODE human, release 44)
grep "^>" GRCh38.primary_assembly.genome.fa | cut -d " " -f 1 \
| sed 's/>//g' > decoys.txt
cat gencode.v44.transcripts.fa GRCh38.primary_assembly.genome.fa > gentrome.fa
salmon index \
-t gentrome.fa \
-d decoys.txt \
-p 16 \
-i salmon_index_gencode44 \
--gencode \
-k 31
Then quantify each sample. The -l A flag lets salmon infer library type, which is worth doing once and then hard-coding, because a silently misdetected strandedness will halve your counts.
salmon quant \
-i salmon_index_gencode44 \
-l A \
-1 sample01_R1.fastq.gz \
-2 sample01_R2.fastq.gz \
-p 16 \
--validateMappings \
--seqBias --gcBias \
--numBootstraps 30 \
-o quants/sample01
--gcBias matters more than people expect in samples prepared in different batches. --numBootstraps 30 gives you inferential replicates, which let downstream tools know how uncertain each transcript estimate is. Check quants/sample01/logs/salmon_quant.log for the mapping rate. Below about 70% for a well-prepared human polyA library, something is wrong. The usual causes are the wrong species, adapter contamination, or heavy rRNA carryover.
If you need a genome-aligned BAM anyway (for variant calling, coverage tracks, or splice inspection), align with STAR and count with featureCounts instead. Note the strandedness flag. The value -s 2 is correct for standard dUTP protocols such as Illumina Stranded mRNA.
featureCounts \
-a gencode.v44.primary_assembly.annotation.gtf \
-o counts_raw.tsv \
-T 16 -p --countReadPairs \
-s 2 -t exon -g gene_id \
aligned/*.sortedByCoord.out.bam
3. Load counts into a matrix
For salmon output, import with tximport, which aggregates transcripts to genes and carries an average transcript length offset per gene per sample. That offset is the point. Aggregating transcript counts by naive summation throws away the fact that isoform switching changes the effective length of a gene between samples.
library(tximport)
library(DESeq2)
samples <- read.csv("samples.csv") # columns: sample_id, condition, batch
files <- file.path("quants", samples$sample_id, "quant.sf")
names(files) <- samples$sample_id
tx2gene <- read.delim("tx2gene_gencode44.tsv") # TXNAME, GENEID
txi <- tximport(files, type = "salmon", tx2gene = tx2gene,
countsFromAbundance = "no")
dds <- DESeqDataSetFromTximport(txi, colData = samples,
design = ~ batch + condition)
dim(dds)
head(counts(dds)[, 1:4])
The raw matrix for a human polyA library will have roughly 60,000 rows if you use the full GENCODE annotation. Most of those rows are zero or near-zero in every sample: pseudogenes, lowly expressed lncRNAs, and genes not transcribed in your tissue. Filtering is a modelling choice. It is not data cleaning. We keep genes with at least 10 counts in at least as many samples as the smallest group.
smallest_group <- min(table(samples$condition))
keep <- rowSums(counts(dds) >= 10) >= smallest_group
dds <- dds[keep, ]
nrow(dds) # typically 14,000-20,000 for whole blood or a solid tissue
In Python, read the same salmon output with pyroe or load a featureCounts TSV directly with pandas, then hand it to pydeseq2. The R path has more mature tooling for the diagnostics in step 5, so we default to R and move to Python only for downstream machine learning.
4. Normalize, and know which normalization answers which question
Raw counts are not comparable across samples or across genes. Three separate factors confound them: sequencing depth, gene length, and library composition. Different normalizations remove different subsets.
Counts per million (CPM) divides by depth only. It is fine for comparing one gene across samples and wrong for comparing two genes within a sample, because a 10 kb transcript yields more fragments than a 1 kb transcript at equal molar concentration. TPM (transcripts per million) divides by effective length first and then by depth, so it is the right unit for within-sample comparisons and ranking genes by abundance. Neither is appropriate as input to differential expression testing.
For differential expression, use raw integer counts and let the model handle normalization internally. DESeq2’s median-of-ratios estimator computes one size factor per sample from the median ratio of each gene’s count to its geometric mean across samples. This is resistant to a handful of very high-expression genes dominating the library, which simple depth scaling is not. Open-source pipelines built on this negative binomial framework are the standard path from a count matrix to a ranked gene list.1
dds <- DESeq(dds)
sizeFactors(dds) # expect ~0.6 to 1.6; anything outside is worth checking
res <- results(dds, contrast = c("condition", "treated", "control"),
alpha = 0.05)
res <- lfcShrink(dds, coef = "condition_treated_vs_control", type = "apeglm")
summary(res)
For visualization, clustering, and any distance-based method, use the variance-stabilizing transform. Log-transformed CPM leaves low-count genes with inflated variance, which then dominates principal components.
vsd <- vst(dds, blind = FALSE)
plotPCA(vsd, intgroup = c("condition", "batch"))
Principal component analysis on count data is worth doing carefully. Standard PCA assumes additive Gaussian noise, which count data violates, and the mismatch can put sampling noise into leading components. Methods that model the count noise directly separate signal from noise more cleanly in omics matrices.2
5. Run the diagnostics that decide whether the matrix is usable
This is the step most tutorials skip, and it is where you catch the problems that would otherwise turn into a false result. Work through four checks in order.
Start with library size and detected genes per sample. Plot colSums(counts(dds)) and the count of genes above zero. A sample with half the depth of its neighbors is usually still usable. A sample with normal depth but 30% fewer detected genes usually has a degraded or low-complexity library, and it will behave as an outlier in every downstream analysis.
Next, look at what fraction of each library one gene family consumes. In whole blood, the hemoglobin genes HBB, HBA1, and HBA2 can take 30% to 70% of reads unless globin depletion was used. Mitochondrial genes rising above roughly 15% of a bulk tissue library suggests degradation. Report these fractions as a per-sample QC column rather than deleting the genes silently.
raw <- counts(dds, normalized = FALSE)
frac <- function(ids) colSums(raw[rownames(raw) %in% ids, , drop = FALSE]) / colSums(raw)
globin <- frac(c("HBB", "HBA1", "HBA2", "HBD"))
round(globin, 3)
Third, check sample clustering against your metadata. Compute a sample-to-sample distance matrix on the VST values and look at whether samples group by biological condition or by sequencing batch. If the first principal component tracks batch, include batch in the design as shown above and never interpret the uncorrected PCA.
Fourth, and most consequential for tissue samples, consider cell composition. A bulk count matrix is a weighted average of the transcriptomes of the cells in the sample. A twofold change in a gene expressed by one cell type can reflect a shift in how many of those cells were present, with no change in per-cell expression. Deconvolution methods estimate those proportions from the bulk matrix using reference expression profiles.3 Treat the estimates as hypotheses rather than measurements. Systematic evaluation in brain tissue found that different estimation approaches disagree substantially and are sensitive to the reference and the marker set used.4
6. Get from a gene list to an interpretation
A ranked list of differentially expressed genes is not yet an interpretation. Gene set enrichment analysis tests whether genes in a pathway are systematically shifted toward one end of your ranked list, which is more stable than intersecting an arbitrary significance cutoff with a pathway database. It has an established workflow for blood-derived samples like peripheral blood mononuclear cells.5
library(fgsea)
library(msigdbr)
stats <- res$stat
names(stats) <- res$symbol
stats <- stats[!is.na(stats)]
hallmark <- msigdbr(species = "Homo sapiens", collection = "H")
pathways <- split(hallmark$gene_symbol, hallmark$gs_name)
fg <- fgsea(pathways, stats, minSize = 15, maxSize = 500, nPermSimple = 10000)
head(fg[order(padj), .(pathway, padj, NES, size)], 10)
Rank by the Wald statistic rather than by fold change alone, because fold change without its standard error promotes low-expression genes with wide confidence intervals. Read the normalized enrichment score together with the set size. A pathway of 18 genes with an NES of 2.1 is a weaker claim than a pathway of 200 genes with an NES of 1.6.
Interpretation improves when the count matrix is not the only measurement. Transcript abundance and protein abundance correlate imperfectly, and combined transcriptomic and proteomic profiling frequently identifies responses that either layer alone would miss.6 If you also have proteomics or epigenetic data on the same samples, align them on shared gene identifiers and look at where the layers agree. That is one of the main uses of integrated multi-omics tooling.7 For single-cell or spatial work, integrating measurements across modalities in the same cells lets you connect regulatory state to expression directly.8
Finally, be clear about what the matrix cannot tell you. RNA-seq measures abundance at one moment in one tissue. A differentially expressed gene in your data is a measurement. It is not a finding about your health. Anything you want to act on medically belongs in a conversation with a clinician who can order validated clinical assays.
Common problems
Counts are unexpectedly low for every gene while the mapping rate is high. This is almost always a strandedness mismatch. Run featureCounts with -s 0, -s 1, and -s 2 on one BAM and compare assignment rates. The correct setting typically assigns 60% to 85% of fragments, while the wrong one drops toward 5% to 30%.
Salmon mapping rate is under 50%. Check for adapter read-through with fastqc first, then confirm your index species and release match the library. A common cause is a total-RNA library quantified against a polyA-only transcriptome, which leaves most intronic and rRNA-derived fragments unmapped.
Gene IDs will not join to your annotation. GENCODE gene IDs carry version suffixes such as ENSG00000141510.16. Strip the suffix with sub("\\..*$", "", ids) before joining to anything Ensembl-derived. Expect a small number of genuinely retired IDs that will not map at all.
The same gene appears twice after mapping to symbols. Several Ensembl IDs share one HGNC symbol. Aggregate by summing counts within symbol, or better, keep Ensembl IDs as the primary key and carry symbols as a display label only.
One sample dominates the first principal component. Before removing it, check its library size and detected gene count. Then check its globin and mitochondrial fractions and its duplicate rate. If three or more of those are outliers, exclude the sample and say so in your writeup. If none are, the variation may be biological and removing it would be a mistake.
Fold changes look enormous for genes with low counts. Use lfcShrink with apeglm as shown above. A gene going from 2 counts to 20 counts is an eightfold apparent change built on almost no information, and shrinkage estimators pull those toward zero in proportion to their uncertainty.
Results change when you rerun the pipeline. Pin the annotation release, the tool versions, and the filtering thresholds in a single config file. Record the salmon index checksum there too. The largest single source of irreproducibility in count matrices is an unrecorded annotation change.
Footnotes
-
Moritz Kebschull, Melanie Julia Fittler, Ryan T. Demmer, et al. Differential Expression and Functional Analysis of High-Throughput -Omics Data Using Open Source Tools. Methods in Molecular Biology, 2016. https://doi.org/10.1007/978-1-4939-6685-1_19 ↩
-
Jay S. Stanley, Junchen Yang, Ruiqi Li, et al. Principled PCA separates signal from noise in omics count data. 2025. https://doi.org/10.1101/2025.02.03.636129 ↩
-
Ziyi Chen, Lijun Quan, Anfei Huang, et al. seq-ImmuCC: Cell-Centric View of Tissue Transcriptome Measuring Cellular Compositions of Immune Microenvironment From Mouse RNA-Seq Data. Frontiers in Immunology, 2018. https://doi.org/10.3389/fimmu.2018.01286 ↩
-
Lilah Toker, Gonzalo S. Nido, Charalampos Tzoulis. Not every estimate counts – evaluation of cell composition estimation approaches in brain bulk tissue data. Genome Medicine, 2023. https://doi.org/10.1186/s13073-023-01195-2 ↩
-
Fayuan Wen, Namita Kumari, James G. Taylor Vi. RNA-Seq and Gene Set Enrichment Analysis (GSEA) in Peripheral Blood Mononuclear Cells (PBMCs). Methods in Molecular Biology, 2025. https://doi.org/10.1007/978-1-0716-4276-4_8 ↩
-
Huan Zhong, Yuming Shi, Aleksandra Kozlova, et al. Omics Insights Into the Effects of Highbush Blueberry and Cranberry Crop Agroecosystems on Honey Bee Health and Physiology. PROTEOMICS, 2025. https://doi.org/10.1002/pmic.70033 ↩
-
Zeyu Zhang, Zuoling Ma, Tian Hua, et al. OmicsCanvas: A multi‐omics platform for integration and visualization of epigenetic regulation. Journal of Integrative Plant Biology, 2026. https://doi.org/10.1111/jipb.70258 ↩
-
Ricard Argelaguet, Tim Lohoff, Jingyu Gavin Li, et al. Decoding gene regulation in the mouse embryo using single-cell multi-omics. 2022. https://doi.org/10.1101/2022.06.15.496239 ↩
Pothos builds longitudinal molecular profiles of individuals: whole-genome sequencing, single-cell RNA sequencing, and plasma proteomics, delivered as a detailed report, every data file, and stored cells. Build your profile.