Introduction

tradeSeq (TRAjectory Differential Expression analysis for SEQuencing data) provides a flexible statistical framework for identifying genes that are differentially expressed along cell trajectories in single-cell RNA sequencing data.

This quick start guide will walk you through a basic analysis workflow in just a few minutes.

Installation

# From R-universe (recommended for latest version)
install.packages("tradeSeq", repos = "https://zaoqu-liu.r-universe.dev")

# From Bioconductor (stable release)
BiocManager::install("tradeSeq")

# From GitHub (development version)
remotes::install_github("Zaoqu-Liu/tradeSeq")

Quick Workflow

Step 1: Load Required Packages

library(tradeSeq)
library(RColorBrewer)
library(SingleCellExperiment)
library(slingshot)
library(ggplot2)

# Set seed for reproducibility
set.seed(42)

Step 2: Load Example Data

tradeSeq comes with example datasets from a study of bone marrow hematopoiesis.

# Load count matrix and trajectory
data(countMatrix, package = "tradeSeq")
data(crv, package = "tradeSeq")

# Convert to matrix
counts <- as.matrix(countMatrix)

# Check dimensions
cat("Genes:", nrow(counts), "\n")

## Genes: 240

cat("Cells:", ncol(counts), "\n")

## Cells: 2660

Step 3: Fit GAM Models

The core of tradeSeq is fitting generalized additive models (GAMs) for each gene.

# Fit GAM with 6 knots (default)
sce <- fitGAM(counts = counts, sds = crv, nknots = 6, verbose = FALSE)

# Check the fitted object
sce

## class: SingleCellExperiment 
## dim: 240 2660 
## metadata(1): tradeSeq
## assays(1): counts
## rownames(240): Acin1 Actb ... Zfpm1 rp9
## rowData names(1): tradeSeq
## colnames(2660): W31105 W31106 ... W39167 W39168
## colData names(2): crv tradeSeq
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):

Step 4: Run Differential Expression Tests

Association Test

Test whether gene expression is associated with pseudotime.

# Test for association with pseudotime
assocRes <- associationTest(sce)

# View top results
head(assocRes[order(assocRes$pvalue), ])

##        waldStat df pvalue meanLogFC
## Alad   157.7881 10      0 0.5649757
## Aldoa  213.8379 10      0 0.4460548
## Anp32b 202.3285 10      0 0.8790910
## Atp5d  189.7143 10      0 0.5107889
## Atp5f1 106.3698 10      0 0.6954332
## Atp5g3 371.4604 10      0 0.9153786

Differential End Points Test

Compare expression at the endpoints of different lineages.

# Test for differential expression at lineage endpoints
endRes <- diffEndTest(sce)

# View top results
head(endRes[order(endRes$pvalue), ])

##          waldStat df pvalue   logFC1_2
## Actb     173.0271  1      0  0.4000577
## Alad     388.7256  1      0 -2.3307909
## Alas1   1524.0997  1      0  3.3854298
## Aldoa    182.0214  1      0  0.8103589
## Aqp1     285.9741  1      0 -3.0298347
## Arhgdib  773.3596  1      0  3.2942820

Pattern Test

Test whether genes have different expression patterns between lineages.

# Test for differential patterns
patternRes <- patternTest(sce)

# View top results
head(patternRes[order(patternRes$pvalue), ])

##           waldStat df pvalue  fcMedian
## Actb      773.5380  7      0 0.2292909
## Alad     1187.4058  6      0 1.1962029
## Alas1    2114.1364  2      0 1.5190536
## Aldoa     549.4235  6      0 0.1366923
## Ankrd13a  149.8242  6      0 0.3132776
## Apoe      246.0942  7      0 0.6908463

Step 5: Visualize Results

Plot Gene Expression Smoothers

# Get a significant gene
topGene <- rownames(assocRes[order(assocRes$pvalue), ])[1]

# Plot smoother
plotSmoothers(sce, counts, gene = topGene) +
  ggtitle(paste("Expression of", topGene, "along trajectory"))

Plot Gene Count

# Plot gene counts on trajectory
plotGeneCount(crv, counts, gene = topGene) +
  ggtitle(paste(topGene, "expression"))

Summary

In this quick start guide, you learned how to:

Load data: Import count matrix and trajectory information
Fit models: Use fitGAM() to fit GAMs for each gene
Test DE: Apply various statistical tests
Visualize: Create publication-ready plots

For more detailed tutorials, please see the other vignettes:

Session Info

sessionInfo()

## R version 4.6.0 (2026-04-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.4 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
## 
## Random number generation:
##  RNG:     Mersenne-Twister 
##  Normal:  Inversion 
##  Sample:  Rounding 
##  
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: Etc/UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] ggplot2_4.0.3               mgcv_1.9-4                 
##  [3] nlme_3.1-169                slingshot_2.21.0           
##  [5] TrajectoryUtils_1.21.0      princurve_2.1.6            
##  [7] SingleCellExperiment_1.35.1 SummarizedExperiment_1.43.0
##  [9] Biobase_2.73.1              GenomicRanges_1.65.0       
## [11] Seqinfo_1.3.0               IRanges_2.47.1             
## [13] S4Vectors_0.51.2            BiocGenerics_0.59.3        
## [15] generics_0.1.4              MatrixGenerics_1.25.0      
## [17] matrixStats_1.5.0           RColorBrewer_1.1-3         
## [19] tradeSeq_1.13.13            knitr_1.51                 
## [21] rmarkdown_2.31             
## 
## loaded via a namespace (and not attached):
##  [1] gtable_0.3.6        xfun_0.57           bslib_0.11.0       
##  [4] lattice_0.22-9      vctrs_0.7.3         tools_4.6.0        
##  [7] parallel_4.6.0      tibble_3.3.1        pkgconfig_2.0.3    
## [10] Matrix_1.7-5        S7_0.2.2            lifecycle_1.0.5    
## [13] compiler_4.6.0      farver_2.1.2        statmod_1.5.2      
## [16] codetools_0.2-20    htmltools_0.5.9     sys_3.4.3          
## [19] buildtools_1.0.0    sass_0.4.10         yaml_2.3.12        
## [22] pillar_1.11.1       jquerylib_0.1.4     BiocParallel_1.47.0
## [25] limma_3.69.1        DelayedArray_0.39.2 cachem_1.1.0       
## [28] viridis_0.6.5       abind_1.4-8         locfit_1.5-9.12    
## [31] tidyselect_1.2.1    digest_0.6.39       dplyr_1.2.1        
## [34] labeling_0.4.3      maketools_1.3.2     splines_4.6.0      
## [37] fastmap_1.2.0       grid_4.6.0          cli_3.6.6          
## [40] SparseArray_1.13.2  magrittr_2.0.5      S4Arrays_1.13.0    
## [43] withr_3.0.2         edgeR_4.11.1        scales_1.4.0       
## [46] XVector_0.53.0      igraph_2.3.1        gridExtra_2.3      
## [49] pbapply_1.7-4       evaluate_1.0.5      viridisLite_0.4.3  
## [52] rlang_1.2.0         Rcpp_1.1.1-1.1      glue_1.8.1         
## [55] jsonlite_2.0.0      R6_2.6.1

Quick Start Guide