Import transcript-level quantifications from Salmon/kallisto/RSEM into R for gene-level analysis with DESeq2/edgeR using tximport or tximeta. Use when summarizing transcript abundances to gene counts with the correct length offset, choosing a countsFromAbundance mode (full-length vs 3'-tag vs DTU), resolving transcript-ID version mismatches, or handing off to DESeq2/edgeR without double-applying the offset.
Import transcript-level quantifications from Salmon/kallisto/RSEM into R for gene-level analysis with DESeq2/edgeR using tximport or tximeta. Use when summarizing transcript abundances to gene counts with the correct length offset, choosing a countsFromAbundance mode (full-length vs 3'-tag vs DTU), resolving transcript-ID version mismatches, or handing off to DESeq2/edgeR without double-applying the offset.
Before using code patterns, verify installed versions match. If versions differ:
R: packageVersion('<pkg>') then ?function_name to verify parameters
If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.
tximport Workflow
"Import Salmon/kallisto results into DESeq2" -> Summarize transcript-level abundance estimates to gene-level counts AND compute a per-gene, per-sample length offset that the DE model consumes.
tximport does not merely add transcript counts to a gene total. The fragment count a gene produces depends on the average length of the isoforms expressed in that sample, because longer molecules yield more fragments (more start positions). When isoform usage shifts between conditions (differential transcript usage), the gene's average effective length changes, so a naive summed count is length-biased in a condition-correlated way and masquerades as differential expression. tximport corrects this by returning a per-gene, per-sample average-length matrix () and passing it as a normalization offset to DESeq2/edgeR. A single per-gene length cannot capture this because the bias is sample-specific (Soneson, Love, Robinson 2015).
txi$length
Basic tximport
Goal: Import transcript-level quantifications into R as gene-level counts plus the length offset for DESeq2 or edgeR.
Approach: Build a transcript-to-gene map, then run tximport over the quant files; the returned txi$counts/txi$length carry both the gene counts and the offset.
txi is a list: $abundance (TPM), $counts (estimated counts), $length (the average-length offset source), $countsFromAbundance.
Decision: countsFromAbundance mode
This argument silently determines correctness; nothing errors when it is wrong.
Mode
What it returns
Use when
'no' (default)
Estimated counts + separate length offset
Full-length library -> DESeq2/edgeR (they consume the offset). The cleanest path.
'lengthScaledTPM'
Counts with the length correction baked in, no separate offset
A tool that cannot take an offset (e.g. limma-voom)
'scaledTPM'
TPM scaled to library size, no length scaling
Transcript-level DTU with txOut=TRUE (DRIMSeq/DEXSeq); the established Love et al. workflow input
'dtuScaledTPM'
Scaled by median isoform length
DTU alternative (tximport >= 1.10), needs tx2gene; helps when isoform lengths within a gene differ widely
For DTU, scaledTPM is the established default; dtuScaledTPM is the newer purpose-built mode, preferable when a gene's isoforms span very different lengths.
The 3'-tag exception: for 3'-end protocols (10x, QuantSeq, Lexogen) a read count does not scale with transcript length, so there is no length bias to correct, and length-correcting injects one. Do not use the length-scaled modes (lengthScaledTPM/dtuScaledTPM) for tag-seq. Import with the default, but build the DESeqDataSet from the plain counts so the length offset is NOT auto-applied:
# 3'-tag: bypass the length offset that DESeqDataSetFromTximport would otherwise apply
dds <- DESeqDataSetFromMatrix(round(txi$counts), colData = coldata, design =~ condition)
# Full-length, DESeq2/edgeR (default): keep the offset path
txi <- tximport(files, type ='salmon', tx2gene = tx2gene)# Transcript-level for DTU (hand off to alternative-splicing/isoform-switching)
txi_tx <- tximport(files, type ='salmon', txOut =TRUE,
countsFromAbundance ='scaledTPM')
Creating tx2gene
The map is a two-column data frame; column ORDER is load-bearing (TXNAME first, GENEID second), names do not matter.
Goal: Map every quantified transcript ID to its gene, with IDs that exactly match the quant files.
Approach: Derive from the annotation that built the index (GTF, ensembldb, biomaRt, or the index t2g); strip version suffixes to match.
# From a GTF: makeTxDbFromGFF moved to txdbmaker in Bioconductor >= 3.19# (defunct in GenomicFeatures >= 1.61.1; on older Bioconductor use GenomicFeatures::makeTxDbFromGFF)
library(txdbmaker)
txdb <- makeTxDbFromGFF('annotation.gtf')
k <- keys(txdb, keytype ='TXNAME')
tx2gene <- AnnotationDbi::select(txdb, keys = k, keytype ='TXNAME',
columns =c('TXNAME','GENEID'))# From biomaRt (useEnsembl; useMart is deprecated)
library(biomaRt)
mart <- useEnsembl(biomart ='genes', dataset ='hsapiens_gene_ensembl')
tx2gene <- getBM(attributes=c('ensembl_transcript_id','ensembl_gene_id'), mart = mart)
The #1 silent failure: transcript-ID version mismatch
If quant.sf IDs carry version suffixes (ENST00000456328.4) but tx2gene does not (or vice versa), the IDs do not match. Total non-overlap raises an error; partial mismatch silently drops the non-matching transcripts and prints a summary, deflating affected genes toward zero. Fix by stripping versions consistently or with ignoreTxVersion:
Passing a countsFromAbundance='no' txi prints "using counts and average transcript lengths from tximport"; a length-scaled txi prints "using just counts" and applies no offset. Both are handled correctly by the function.
Handoff to edgeR (manual offset)
Goal: Carry the length offset into an edgeR DGEList.
Approach: Geometric-mean-center the length matrix, fold in composition-corrected library sizes, log it, attach via scaleOffset.
library(edgeR)
cts <- txi$counts
normMat <- txi$length/exp(rowMeans(log(txi$length)))# center each gene on its geometric mean
normCts <- cts / normMat
eff.lib <- calcNormFactors(normCts)* colSums(normCts)
normMat <- sweep(normMat,2, eff.lib,'*')
y <- scaleOffset(DGEList(cts),log(normMat))
y <- y[filterByExpr(y, group = coldata$condition),, keep.lib.sizes =FALSE]# group-aware filter
Do not double-apply the offset: if countsFromAbundance='lengthScaledTPM' already baked the correction into the counts, do not also attach a length offset. Use 'no' for the offset path, the scaled modes for the no-offset path, never both.
Transcript-level uncertainty (DTE/DTU)
Gene-level estimates are robust because per-isoform assignment uncertainty cancels on summation. Transcript-level testing must propagate it: edgeR catchSalmon deflates counts by per-transcript overdispersion (differential-expression/edger-basics), swish/fishpond tests across Salmon Gibbs samples (alternative-splicing/isoform-switching), and sleuth uses kallisto bootstraps (expression-matrix/counts-ingest). Generate the replicates at quantification time (rna-quantification/alignment-free-quant).
tximeta: provenance by checksum
tximeta hashes the index's reference sequences and looks the digest up against known GENCODE/Ensembl/RefSeq releases, attaching transcript ranges and release metadata automatically, so the exact reference becomes a verified property of the object rather than lab lore.
