Skip to content

Bulk RNA-seq Analysis in Python, From FASTQ to Differential Expression

Oak
A coiled serpentine creature with iridescent banded scales and glowing internal filaments, lit on a black plinth against darkness.

By the end of this guide you will have four outputs. The first two are a gene-level count matrix and a normalized expression matrix suitable for clustering and plots. You will also have a table of differential expression results with shrunken log fold changes and gene set scores derived from that table. The inputs are paired-end FASTQ files (roughly 30–50 million read pairs per sample for standard poly-A bulk RNA-seq), a reference transcriptome FASTA and genome FASTA from GENCODE, and a machine with at least 16 GB of RAM and 8 cores. Quantification happens in a command-line tool because no Python quantifier matches salmon or kallisto for speed or accuracy. Everything after that stays in Python. The historical argument for R in this field was package availability, and that argument has weakened considerably in the last three years 12.

1. Set up the environment

Use a single conda environment so that the command-line tools and the Python packages share one dependency graph. Micromamba resolves this faster than conda and behaves identically for our purposes.

micromamba create -n rnaseq -c conda-forge -c bioconda \
  python=3.11 salmon=1.10.3 fastp=0.23.4 multiqc=1.25 \
  pytximport pydeseq2 inmoose gseapy decoupler \
  scanpy pandas pyarrow matplotlib
micromamba activate rnaseq

Pin the salmon version in your notes. Index compatibility breaks across major versions, and a quantification run against a differently versioned index is not comparable to your earlier samples. For a longitudinal profile where you will add samples over months or years, version drift is the single most common source of artifactual batch effects.

2. Trim and quality-check the reads

Run fastp before quantification. It removes adapters, trims low-quality tails, and emits a JSON report you can aggregate later.

fastp \
  -i raw/S01_R1.fastq.gz -I raw/S01_R2.fastq.gz \
  -o trim/S01_R1.fastq.gz -O trim/S01_R2.fastq.gz \
  --detect_adapter_for_pe \
  --cut_tail --cut_tail_mean_quality 20 \
  --length_required 36 \
  --thread 8 \
  --json qc/S01.fastp.json --html qc/S01.fastp.html

Do not trim more aggressively than this. Salmon’s selective alignment tolerates soft-clipped adapter remnants well, and hard trimming to a fixed length discards information. After all samples are processed, run multiqc qc/ -o qc/multiqc. Then look at three numbers per sample: duplication rate, GC distribution, and the fraction of reads passing filter. A GC curve with a second peak near 75 percent usually means residual rRNA or a library artifact.

3. Build a decoy-aware salmon index

Selective alignment against a transcriptome alone will assign reads that truly originate from intronic or intergenic sequence. The decoy approach adds the whole genome to the index as background so those reads have somewhere else to go.

grep '^>' <(gunzip -c GRCh38.primary_assembly.genome.fa.gz) \
  | cut -d ' ' -f 1 | sed 's/>//g' > decoys.txt

cat gencode.v47.transcripts.fa.gz GRCh38.primary_assembly.genome.fa.gz > gentrome.fa.gz

salmon index -t gentrome.fa.gz -d decoys.txt -k 31 -p 16 -i salmon_index_v47 --gencode

The index build needs about 16 GB of RAM and half an hour on 16 cores. Keep -k 31 for reads of 75 bp or longer. Drop to -k 23 only if your reads are 50 bp or shorter.

4. Quantify each sample

salmon quant \
  -i salmon_index_v47 -l A \
  -1 trim/S01_R1.fastq.gz -2 trim/S01_R2.fastq.gz \
  --validateMappings --gcBias --seqBias --posBias \
  --numBootstraps 30 \
  --threads 8 \
  -o quant/S01

A few of these flags matter more than the rest. -l A lets salmon infer strandedness, and you should read the inferred library type out of quant/S01/lib_format_counts.json rather than trusting it blindly. A stranded library misread as unstranded inflates antisense gene counts. --gcBias corrects fragment-level GC bias and costs little. Enable it whenever samples were prepared in different batches. --numBootstraps 30 produces inferential replicates that let you see which genes have uncertain quantification because of multimapping, which matters for paralog families and for many immunoglobulin and HLA genes.

The output you care about is quant/S01/quant.sf. It is a tab-separated file with one row per transcript. Its first columns are Name and Length, and the rest are EffectiveLength, TPM and NumReads. Also check quant/S01/logs/salmon_quant.log for the mapping rate. For a clean poly-A human library, expect 75–90 percent. Below 60 percent means contamination, the wrong reference, or heavy genomic DNA carryover.

5. Import to gene-level counts with pytximport

Transcript-level estimates need to be summed to gene level, with a correction for changes in average transcript length across samples. The pytximport package is a direct port of the R tximport logic and reproduces its output closely 3.

First build the transcript-to-gene map. The GENCODE FASTA headers carry both identifiers, so no GTF parsing is needed.

import gzip, csv

with gzip.open("gencode.v47.transcripts.fa.gz", "rt") as f, \
     open("tx2gene.tsv", "w", newline="") as out:
    w = csv.writer(out, delimiter="\t")
    w.writerow(["transcript_id", "gene_id"])
    for line in f:
        if line.startswith(">"):
            fields = line[1:].strip().split("|")
            w.writerow([fields[0], fields[1]])

Then import all samples at once.

from pathlib import Path
from pytximport import tximport

files = sorted(Path("quant").glob("*/quant.sf"))
sample_ids = [p.parent.name for p in files]

adata = tximport(
    files,
    data_type="salmon",
    transcript_gene_map="tx2gene.tsv",
    counts_from_abundance="length_scaled_tpm",
    ignore_after_bar=True,
    output_type="anndata",
)
adata.obs_names = sample_ids

Two choices here deserve explanation. ignore_after_bar=True strips the pipe-delimited suffix from GENCODE transcript identifiers so they match the map. counts_from_abundance="length_scaled_tpm" generates counts that are scaled by average transcript length, which means you can feed them straight into a count-based model without supplying a separate offset matrix. The alternative is to pass raw counts plus the length matrix as an offset, which DESeq2 in R does natively but which is awkward in the Python stack today. Length-scaled TPM is the pragmatic choice. It is not exactly equivalent, and the difference shows up mainly for genes with strong isoform switching between conditions.

Round to integers and drop the version suffix from gene identifiers before modeling.

import numpy as np

adata.X = np.rint(adata.X)
adata.var_names = [g.split(".")[0] for g in adata.var_names]
adata.var_names_make_unique()
adata.write_h5ad("counts_gene.h5ad")

6. Filter genes and attach sample metadata

Filtering is not cosmetic. Genes with near-zero counts across all samples contribute nothing but multiple-testing burden and destabilize dispersion fitting.

import pandas as pd

meta = pd.read_csv("samples.tsv", sep="\t", index_col="sample_id")
adata = adata[meta.index].copy()
adata.obs = meta

counts = pd.DataFrame(adata.X, index=adata.obs_names, columns=adata.var_names)
keep = (counts >= 10).sum(axis=0) >= 3
counts = counts.loc[:, keep]
print(counts.shape)

The rule above keeps a gene if at least three samples have ten or more counts. Set the sample threshold to the size of your smallest group. For whole-blood RNA-seq you will typically retain 14,000 to 17,000 genes out of roughly 62,000 annotated features.

If your samples came from different library prep batches or different sequencing runs, correct for that now. The InMoose package provides pycombat_seq, a Python implementation of ComBat-seq that operates on integer counts and returns integer counts 2.

from inmoose.pycombat import pycombat_seq

corrected = pycombat_seq(counts.T.values, batch=adata.obs["batch"].values)

We prefer to include batch as a covariate in the design formula rather than pre-correcting, because pre-correction understates variance and can inflate significance. Use pycombat_seq when batch is confounded with something you want to visualize, or when the downstream method cannot accept covariates 4.

7. Run differential expression with PyDESeq2

PyDESeq2 reimplements the DESeq2 model in Python and matches the R results closely on benchmark datasets, while running faster on large cohorts 1. The API takes a counts DataFrame with samples as rows and genes as columns.

from pydeseq2.dds import DeseqDataSet
from pydeseq2.ds import DeseqStats
from pydeseq2.default_inference import DefaultInference

inference = DefaultInference(n_cpus=8)

dds = DeseqDataSet(
    counts=counts,
    metadata=adata.obs,
    design="~batch + condition",
    refit_cooks=True,
    inference=inference,
)
dds.deseq2()

res = DeseqStats(
    dds,
    contrast=["condition", "treated", "baseline"],
    inference=inference,
)
res.summary()
res.lfc_shrink(coeff="condition_treated_vs_baseline")
table = res.results_df.sort_values("padj")

The contrast list is ordered as factor, numerator, denominator. A positive log2 fold change therefore means higher in treated. Run lfc_shrink before you rank genes by effect size. Without shrinkage, low-count genes produce enormous fold changes that are pure noise, and any ranked gene set analysis downstream will be dominated by them.

Inspect res.results_df["padj"].isna().sum() after the summary. Missing adjusted p-values come from independent filtering and from Cook’s distance outlier removal. Both are expected behavior. Neither is an error.

For visualization and clustering, use the variance-stabilizing transform rather than log counts per million.

dds.vst(use_design=False)
vst = pd.DataFrame(dds.layers["vst_counts"], index=counts.index, columns=counts.columns)

Then run PCA on the 2,000 most variable genes. If the first principal component separates samples by batch or by RNA integrity rather than by your variable of interest, stop and fix the design before interpreting anything.

8. Score gene sets and pathways

Ranked enrichment on the full gene list is more informative than a threshold-based overrepresentation test, because it does not discard the shape of the effect. Rank by the Wald statistic, which combines effect size and precision.

import gseapy as gp

rnk = (table.dropna(subset=["stat"])
            .reset_index()[["index", "stat"]]
            .rename(columns={"index": "gene"}))

pre = gp.prerank(
    rnk=rnk,
    gene_sets="MSigDB_Hallmark_2020",
    min_size=15, max_size=500,
    permutation_num=1000,
    threads=8, seed=42,
    outdir="gsea_hallmark",
)

Map Ensembl identifiers to HGNC symbols first, since most MSigDB collections are symbol-keyed. For transcription factor activity and pathway activity rather than enrichment, decoupler with the CollecTRI and PROGENy priors gives per-sample scores you can plot as a time series. Reviews of the field describe the broader method space and the tradeoffs between count-based and transform-based tests 56.

If your samples are whole blood, cell composition will drive a large fraction of the variance. Deconvolution estimates the proportion of each leukocyte type from the bulk expression profile, and those proportions belong in your design as covariates. Published protocols for integrative bulk analysis walk through deconvolution alongside expression and pathway modules 7.

9. Handle repeated samples from one person

A single-person longitudinal profile breaks the usual assumption of independent biological replicates. Two adjustments follow. First, when comparing conditions within one person over time, add the subject as a blocking factor only if you have more than one subject. A single-level factor is not estimable. Second, model time explicitly rather than binning it. A design like ~ cell_fraction_neut + np.sin(2*np.pi*hour/24) + np.cos(2*np.pi*hour/24) captures circadian structure that would otherwise appear as unexplained variance.

For denser time courses, pairwise contrasts are the wrong tool. Methods designed for temporal dynamics test for a trend across the whole series and have more power than repeated two-group tests 8. Collecting samples at the same clock time is the cheapest variance reduction available in blood transcriptomics.

Common problems

Mapping rate below 60 percent. Check the library type in lib_format_counts.json first, then confirm the reference species and annotation release. A human library quantified against a GENCODE index built from the CHR-only file will lose reads mapping to scaffolds.

Gene identifiers do not match between the counts matrix and the gene sets. Strip version suffixes from Ensembl identifiers before any join. Keep a single mapping table in the project and use it everywhere.

PyDESeq2 raises an error about non-integer counts. length_scaled_tpm output is continuous. Round it with np.rint and cast to integer.

Every gene is significant. This almost always means a confounded design. Look at the PCA of the VST matrix and check whether your groups also differ in batch, RNA integrity number, or sampling time.

Dispersion estimation fails or produces a flat trend. You likely have too few samples per group, or extreme outliers. Four samples per group is a reasonable floor for a two-group comparison. With fewer, report effect sizes and confidence intervals and avoid framing anything as a discovery.

Results differ from a collaborator’s R run. Expect small numerical differences between PyDESeq2 and DESeq2 from optimizer details and from the length-scaled TPM choice. Large differences point to a different filtering step or a different design formula 1. Published protocols are useful for pinning down where two pipelines diverge 9.

One interpretive caution applies throughout. Expression differences are measurements. They are not findings about health. A gene set score that moves between two of your samples describes those samples. Anything that looks like it bears on a clinical question belongs in a conversation with a physician who can see your full picture.

Footnotes

  1. Boris Muzellec, Maria Teleńczuk, Vincent Cabeli, et al. PyDESeq2: a python package for bulk RNA-seq differential expression analysis. Bioinformatics, 2023. https://doi.org/10.1093/bioinformatics/btad547 ↩ ↩2 ↩3

  2. Maximilien Colange, Guillaume Appé, Léa Meunier, et al. Bridging the gap between R and Python in bulk transcriptomic data analysis with InMoose. Scientific Reports, 2025. https://doi.org/10.1038/s41598-025-03376-y ↩ ↩2

  3. Malte Kuehl, Milagros N Wong, Nicola Wanner, et al. Gene count estimation with pytximport enables reproducible analysis of bulk RNA sequencing data in Python. Bioinformatics, 2024. https://doi.org/10.1093/bioinformatics/btae700 ↩

  4. Maximilien Colange, Guillaume Appé, Léa Meunier, et al. Bulk Transcriptomic Analysis with InMoose, the Integrated Multi-Omic Open-Source Environment in Python. 2024. https://doi.org/10.1101/2024.11.29.625982 ↩

  5. Maryam Kalantari-Dehaghi, Neda Ghohabi-Esfahani, Modjtaba Emadi-Baygi. From bulk RNA sequencing to spatial transcriptomics: a comparative review of differential gene expression analysis methods. Human Genomics, 2025. https://doi.org/10.1186/s40246-025-00884-w ↩

  6. Jorge A. Tzec‐Interián, Daianna González‐Padilla, Elsa B. Góngora‐Castillo. Bioinformatics perspectives on transcriptomics: A comprehensive review of bulk and single‐cell RNA sequencing analyses. Quantitative Biology, 2025. https://doi.org/10.1002/qub2.78 ↩

  7. Lin Yang, Jin Wang, Jennifer Altreuter, et al. Tutorial: integrative computational analysis of bulk RNA-sequencing data to characterize tumor immunity using RIMA. Nature Protocols, 2023. https://doi.org/10.1038/s41596-023-00841-8 ↩

  8. Vera-Khlara S. Oh, Robert W. Li. Temporal Dynamic Methods for Bulk RNA-Seq Time Series Data. Genes, 2021. https://doi.org/10.3390/genes12030352 ↩

  9. Abdullah Al Mohit, Niher Ranjan Das, Arushi Jain, et al. Streamline Protocol for Bulk‐RNA Sequencing: From Data Extraction to Expression Analysis. Current Protocols, 2026. https://doi.org/10.1002/cpz1.70304 ↩

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.