Lesson 2 of 4
Module 4 · RNA-seq analysis
Which genes respond to dexamethasone? Three function calls answer it. This lesson runs them, explains what each does, and every column of the result.
The paired design
The design ~ cell + dex, set in RNA-seq counts and exploration, says counts depend on the donor and on the treatment. Including the donor means each donor's treated cells are compared with their own untreated cells, which removes person-to-person differences. The variable you want to test goes last.
A concrete picture helps. Suppose a gene is naturally twice as active in one donor's cells as in another's. Without cell in the design, that donor difference adds to the noise within the treated group and within the untreated group, and a real treatment effect can be lost in it. With cell in the design, the model estimates each donor's own baseline first, then asks how much treatment moves each donor away from that baseline. This is the same idea as a paired t-test, where each person is compared with themselves before and after. Placing dex last matters because, unless you name a comparison explicitly, DESeq2 reports results for the last variable in the design.
In Comparing two groups you ran a paired t-test on the sleep data, where each patient took both drugs and was their own control. The donors here play the role of those patients. The design formula is how you tell DESeq2 about that structure. It is written with a tilde, ~, followed by the variables that may affect a gene's counts, joined by +. ~ dex alone would compare all treated samples with all untreated ones and ignore who they came from, like the unpaired test. ~ cell + dex adds a separate baseline for each donor, so the treatment effect is estimated from the differences within donors.
A design can only separate effects that the experiment keeps apart. If all four treated samples had been sequenced on one day and all four untreated on another, the treatment and the day would be confounded: perfectly tangled, so that no formula could say which caused a difference. DESeq2 stops with an error that the model matrix is not full rank when a design asks for something the samples cannot answer. Airway is balanced, with every donor contributing one sample of each kind, which is what makes ~ cell + dex work.
This lesson carries on from RNA-seq counts and exploration and uses its dds object. If you start a fresh R session, run that lesson's code again first, or R will report that it cannot find DESeq or dds.
dds <- DESeq(dds)
res <- results(dds, contrast = c("dex", "trt", "untrt"), alpha = 0.05)
summary(res)
res_ordered <- res[order(res$padj), ]
head(res_ordered)DESeq() runs four steps: it estimates size factors (RNA-seq counts and exploration), estimates how much each gene varies between replicates (dispersion), fits a negative binomial model to each gene, and tests the treatment effect. summary() reports how many genes are up and down at your adjusted p-value.
Each line, and each step, explained
dds <- DESeq(dds)runs the whole analysis and stores the fitted results back indds. It prints a short message for each step as it goes.- Dispersion describes how much a gene's counts vary between replicates beyond what chance sampling of reads alone would give. With only four samples per group, one gene's own estimate is unreliable, so DESeq2 borrows strength across genes: it fits a trend of dispersion against expression level for all genes, then pulls each gene's estimate part of the way towards that trend.
- The negative binomial is a probability distribution for counts whose variance is larger than their mean, which is what RNA-seq counts between biological replicates show. Each gene gets its own model, with the donor and treatment effects as terms.
results(dds, contrast = c("dex", "trt", "untrt"), alpha = 0.05)extracts one comparison: in the variabledex, treated versus untreated, with untreated in the denominator.alpha = 0.05tells DESeq2 the adjusted p-value cut-off you plan to use, which it uses when filtering genes (see below) and in the summary.summary(res)prints the number of genes with an adjusted p-value below 0.05 and a positive log fold change (up), and with a negative one (down), together with counts of genes set aside as outliers or for low counts.res[order(res$padj), ]sorts the table so the smallest adjusted p-value comes first; genes whosepadjisNAgo to the end.head()shows the first six rows: the strongest evidence of change.
The dispersion step is worth seeing, because it is where DESeq2 makes up for having so few replicates. plotDispEsts(dds) draws one point per gene: its mean normalised count across, its dispersion up, both on log scales. Black points are each gene's own estimate, the red line is the fitted trend, and blue points are the final, moderated values. In a healthy dataset the points form a cloud that falls as the mean rises, because low-count genes vary more between replicates, and the blue points sit between the black ones and the line. A few black points far above the cloud, circled in blue, are genes whose own variability is so much higher than the trend that DESeq2 keeps their own estimate rather than pulling it in.
Why borrow strength at all? With four samples per group, a gene's own variance estimate can be badly wrong by chance: too small, and the gene looks far more certain than it is; too large, and a real change is missed. Most genes of similar expression have similar dispersion, so the trend is a sensible guess, and each gene's own data move it only as far as they can justify. The more replicates you have, the more each gene's estimate is trusted on its own.
DESeq() run in one call. The saved CSV holds the ordered, unshrunken results; the shrunken fold changes are a separate object used for ranking and plots. Schematic.Every column, explained
| Column | What it means |
|---|---|
| baseMean | Average normalised count across all samples: how highly expressed the gene is. |
| log2FoldChange | The effect size, treated versus untreated, on a log2 scale. 1 means doubled; −1 means halved. |
| lfcSE | The standard error of that fold change: how uncertain it is. |
| stat | The Wald statistic: fold change divided by its standard error. |
| pvalue | The raw p-value for this one gene. |
| padj | Adjusted for testing thousands of genes (Benjamini–Hochberg). Use this one. |
How to read this table
Each row of DESeq2's results is one gene, and the columns read left to right from "how much is there" to "how sure are we". A worked reading, with round numbers for illustration: a gene with log2FoldChange = 2 and lfcSE = 0.4 has a Wald statistic of 2 ÷ 0.4 = 5. A log2 fold change of 2 means 22 = 4 times higher in treated cells. A statistic of 5 is far from 0, so the p-value is tiny. The same fold change with lfcSE = 2 gives a statistic of 1, which is entirely consistent with no change.
- The Wald test asks how many standard errors the estimate lies from zero, and turns that distance into a p-value.
- The Benjamini–Hochberg adjustment controls the false discovery rate (FDR): among all genes you call significant at padj < 0.05, about 5% are expected to be false positives. Without adjustment, testing 20,000 genes at p < 0.05 would give about 1,000 false positives by chance alone.
In Multiple testing and power you applied p.adjust() to thousands of simulated tests and saw Benjamini–Hochberg remove almost all the false hits while keeping most real ones. DESeq2's padj column is that same adjustment applied to the genes in this table. Two misreadings are common. A padj of 0.01 does not mean the gene has a 1% chance of being a false positive; the 5% describes the whole list called significant at 0.05, not any single gene on it. And the raw pvalue puts the tested genes in almost the same order as padj, but using raw p-values as the cut-off brings back all the false positives the adjustment removes.
The log2FoldChange column also has a sign convention worth fixing in your head now. Because the contrast is "trt" against "untrt", a positive value means higher in treated cells and a negative value means lower. A log2 fold change of −1 is a halving, and of −2 a fall to a quarter. Reporting a fold change without saying which group is the denominator is one of the easiest ways to confuse a reader.
Go deeper: testing for a large change, not just any change
The usual Wald test asks whether a gene's log2 fold change differs from 0. A filter of |log2 fold change| > 1 applied afterwards then picks out the large ones, but the padj values were never about "more than a doubling". A gene with an estimate of 1.1 and a wide standard error passes, although its true change could easily be smaller.
DESeq2 can test the threshold directly: results(dds, contrast = c("dex", "trt", "untrt"), lfcThreshold = 1, alpha = 0.05). The null hypothesis becomes "the change is at most a doubling", and padj now measures the evidence that it is larger. Fewer genes pass, but each is supported as a large change, not only as a non-zero one. Love, Huber and Anders describe this option in the DESeq2 paper. Report which approach you used, because the two gene lists differ.
Why some padj values are NA
DESeq2 sets padj to NA for genes it judges unfair to test, such as those with extreme outliers or counts too low ever to reach significance. This independent filtering is expected and reduces the multiple-testing burden for the rest.
"Independent" means the filter uses only the mean count, which does not depend on the treatment labels, so it cannot favour genes that look changed. A gene with a handful of reads in total could never reach padj < 0.05 however it behaved, but counting it in the adjustment would make every other gene's padj larger. In the results you can tell the cases apart: a gene removed for low counts keeps its pvalue but has NA in padj, while a gene flagged for an extreme outlier has NA in both.
How low is "too low"? DESeq2 does not use a fixed number. It tries a range of mean-count thresholds and picks the one that gives the most genes with padj below your alpha. That is why alpha belongs in results(): the threshold is tuned for the cut-off you will use. The threshold chosen is stored with the results, and metadata(res)$filterThreshold prints it. sum(is.na(res$padj)) counts how many genes it set aside. Because the filtering in RNA-seq counts and exploration already removed the barely expressed genes, this number is usually modest here.
The outlier flag uses Cook's distance, a measure of how much a single sample pulls a gene's fitted model. One sample with ten times the reads of its replicates for one gene would have a large Cook's distance. With seven or more replicates per group, DESeq2 replaces such a count and refits; with fewer, as here with four, it sets the gene's p-values to NA instead. If a gene you care about is flagged, look at its counts sample by sample before deciding anything; the plot of a single gene in Volcano plot and interpretation is made for this.
Shrink noisy fold changes, then save
Genes with few reads can show huge fold changes by chance. Shrinkage pulls unreliable estimates towards zero and leaves well-measured genes almost untouched. Use shrunken values for ranking and plots.
An example of the problem: a gene with 1 read in each untreated sample and 6 in each treated sample has a fold change of about 6, a log2 fold change of about 2.6, larger than many genuine responders. Yet a few reads often differ that much by chance. Shrinkage looks at how uncertain each estimate is (its lfcSE): uncertain estimates are pulled strongly towards 0, while a gene measured with thousands of reads keeps nearly its original value. The p-values are not what changes; the fold changes become safer to rank and to plot.
resultsNames(dds) res_shrunk <- lfcShrink(dds, coef = "dex_trt_vs_untrt", type = "apeglm", res = res) write.csv(as.data.frame(res_ordered), "airway_deseq2_results.csv")
What this does
resultsNames(dds)lists the names of the coefficients the model estimated: the numbers that make up each gene's fitted model.lfcShrink(dds, coef = "dex_trt_vs_untrt", type = "apeglm", res = res)recomputes the treatment fold changes with apeglm shrinkage. apeglm identifies the comparison by coefficient name, which is why the name is copied from the list above rather than given as a contrast.write.csv(as.data.frame(res_ordered), ...)converts the ordered results to a data frame and saves them as a CSV file, with the gene IDs as the first column. Note that this file holds the unshrunken fold changes fromres;res_shrunkstays in R for the plots in Volcano plot and interpretation.
Reading the output
R prints long vectors over several lines, and the number in brackets at the start of each line, [1], [3], [5], is the position of the first item on that line. There are five coefficients. The intercept is the baseline: expression in the reference donor, untreated. The three cell_..._vs_N052611 terms are how much each other donor differs from donor N052611, which became the reference because it comes first in alphabetical order. Those terms absorb the donor differences.
The last coefficient, dex_trt_vs_untrt, is the treatment effect. Its name confirms that untreated is the reference, as set in RNA-seq counts and exploration.
A small detail matters for Volcano plot and interpretation, which takes its padj from res_shrunk, and it is why the code passes res = res. Given only dds and a coefficient, lfcShrink() computes its own p-values and padj with default settings, which use an alpha of 0.1 rather than your 0.05. The independent filtering threshold is then tuned differently, so more genes can be given an NA padj and the number of significant genes shifts slightly. Passing res copies your p-values and padj into the shrunken table, so the two tables agree. The shrunken fold changes are the same either way.
You can see what shrinkage did with an MA plot, introduced in Omics figures: plotMA(res, ylim = c(-5, 5)) and plotMA(res_shrunk, ylim = c(-5, 5)) draw log2 fold change against mean expression. In the unshrunken plot, the genes at the low-expression end fan out widely, with large fold changes in both directions. In the shrunken plot that fan collapses towards 0, while the well-expressed genes that changed strongly stay where they were. Shrinkage does not decide which genes are significant; it makes the size of each change more believable.
DESeq2 is described in Love, Huber & Anders 2014, "Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2" (Genome Biology). The apeglm shrinkage is from Zhu, Ibrahim & Love 2019 (Bioinformatics), and PyDESeq2 from Muzellec et al. 2023 (Bioinformatics). Cite DESeq2 with citation("DESeq2"), give its version, and name the shrinkage method, because defaults have changed since 2014: the original paper's built-in shrinkage is no longer applied by DESeq(), and lfcShrink() now offers several methods. Results can also differ slightly between versions and between the R and Python implementations.
Prefer Python? PyDESeq2
PyDESeq2 runs the same model in Python. It needs the airway counts as a CSV file with gene symbols, airway_counts.csv. Run this R code once to build it from the Bioconductor package; it also needs airway_samples.csv from the course files in the same folder. PyDESeq2 wants samples as rows, so the table is transposed.
library(airway)
library(SummarizedExperiment)
library(org.Hs.eg.db)
data("airway")
counts <- as.data.frame(assay(airway))
counts$symbol <- mapIds(org.Hs.eg.db, keys = rownames(counts),
keytype = "ENSEMBL", column = "SYMBOL")
write.csv(data.frame(gene_id = rownames(counts), counts),
"airway_counts.csv", row.names = FALSE)import pandas as pd
from pydeseq2.dds import DeseqDataSet
from pydeseq2.ds import DeseqStats
counts = pd.read_csv("airway_counts.csv", index_col="gene_id")
symbols = counts.pop("symbol")
samples = pd.read_csv("airway_samples.csv", index_col="sample")
counts = counts[(counts >= 10).sum(axis=1) >= 4] # same filter as in R
dds = DeseqDataSet(counts=counts.T, metadata=samples, design="~cell + dex")
dds.deseq2()
stats = DeseqStats(dds, contrast=["dex", "trt", "untrt"])
stats.summary()
res = stats.results_df.join(symbols).sort_values("padj")
res.to_csv("airway_pydeseq2_results.csv")What this does, matched to the R version
- The imports load pandas, for tables, and the two PyDESeq2 classes:
DeseqDataSetplays the role ofdds, andDeseqStatsthe role ofresults(). pd.read_csv(..., index_col="gene_id")reads the counts with gene IDs as row labels.counts.pop("symbol")removes the gene-symbol column from the table, so only numbers remain, and keeps it separately assymbols.- The sample sheet is read with sample names as row labels. The filter line is the R filter written in pandas: at least 10 reads in at least 4 samples.
DeseqDataSet(counts=counts.T, ...)builds the dataset;.Ttransposes the table so samples are rows. The design string is the same as in R.dds.deseq2()runs size factors, dispersions and model fitting, likeDESeq().DeseqStats(..., contrast=[...])sets up the same treated-versus-untreated comparison, andstats.summary()runs the test and prints the results table.- The last two lines attach gene symbols to the results, sort by adjusted p-value and save them.
The two implementations follow the same method but differ in some details, so expect very similar, not identical, numbers. The project at the end of this module shows one such difference with a low-count gene.
PyDESeq2 also offers fold-change shrinkage, through the lfc_shrink() method of DeseqStats, though not with apeglm. The names it gives coefficients depend on its version, so check its documentation before copying a name. Whichever language you use, record the package and its version, as the research box above recommends.
Key point
A gene is interesting when it has a large effect and strong evidence. Fold change alone overrates noisy genes; p-values alone overrate tiny, well-measured changes. The volcano plot shows both.
Two contrasting examples make the point. A gene at very high expression may rise by only 10% after treatment, a log2 fold change of about 0.14, yet with tens of thousands of reads the change can be extremely significant. It is real but may matter little biologically. A gene with 3 reads may show an eightfold rise, a log2 fold change of 3, with padj far above 0.05. It looks dramatic but is not supported. The genes worth following up are large and well supported at once.
Further reading · Module 4Love, Huber & Anders 2014: the method, and why it shrinks fold changes. · All reading for this course
Check your understanding
1. Why include cell in the design?
2. Which column decides significance?
3. A gene has log2FoldChange = 2. What does that mean here?
Up next
Lesson 3
Volcano plot and interpretation