Monocle 3: Single-Cell Trajectory Guide

Single-cell transcriptomics resolves cellular heterogeneity across tissues, but static clustering models biological states as discrete categories. Monocle 3 provides an established computational toolkit in R to reconstruct continuous biological processes—such as cellular differentiation, lineage branching, immune cell activation, and disease progression—through single-cell trajectory inference and pseudotime analysis.

What it is used for in research

In single-cell biology, cells rarely transition between states in synchronized jumps. Standard single-cell clustering methods group cells into discrete subpopulations, but they cannot inherently recover the temporal continuum of differentiation or identify the exact transcriptional branch points where cell fates diverge. Monocle 3 addresses this by modeling single-cell transitions as a continuous progression called pseudotime.

Developed by the Cole Trapnell Lab at the University of Washington and the Brotman Baty Institute, Monocle 3 is engineered for large-scale single-cell RNA sequencing (scRNA-seq) workflows encompassing hundreds of thousands of cells. Researchers use Monocle 3 across four primary applications:

Principal Graph Learning: Constructing a branched trajectory tree through low-dimensional single-cell embeddings using Reversed Graph Embedding (SimplePPT).
Pseudotime Ordering: Measuring the biological distance (geodesic distance) each individual cell has traveled along the trajectory from an ancestral or stem-like starting state.
Trajectory-Dependent Differential Expression: Applying spatial autocorrelation statistics (Moran's I) to identify genes that fluctuate dynamically along developmental paths without requiring manual binning.
Co-Regulated Gene Modules: Grouping co-varying genes along trajectories into functional modules using graph clustering algorithms. Epigenetic datasets can also be compared alongside trajectory models using toolkits like ArchR single-cell ATAC-seq analysis to connect gene expression with chromatin accessibility dynamics.

Install or access (official source only)

Monocle 3 is an open-source R package distributed directly through the Cole Trapnell Lab GitHub repository and built on Bioconductor infrastructure. It is compatible with Linux, macOS, and Windows environments running R.

1. System Library Prerequisites (Linux / Ubuntu)

Monocle 3 relies on spatial, projection, and hierarchical data packages (such as sf and HDF5Array). On Debian/Ubuntu Linux systems, install the required development headers through your system terminal before installing the R packages:

sudo apt-get update
sudo apt-get install -y libgdal-dev libgeos-dev libproj-dev libhdf5-dev

2. R and Bioconductor Requirements

Monocle 3 requires R (version ≥ 4.4.1) and Bioconductor (version ≥ 3.21). Open your R console or RStudio session and run the following commands to install BiocManager and the required Bioconductor core packages:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install(version = "3.21")

BiocManager::install(c(
    "BiocGenerics", "DelayedArray", "DelayedMatrixStats",
    "limma", "lme4", "S4Vectors", "SingleCellExperiment",
    "SummarizedExperiment", "batchelor", "HDF5Array", "ggrastr"
))

3. Matrix Backend and Monocle 3 Installation

Install the BPCells matrix backend (for memory-efficient out-of-core calculations) and Monocle 3 using remotes or devtools:

if (!requireNamespace("remotes", quietly = TRUE))
    install.packages("remotes")

remotes::install_github("bnprks/BPCells/r")
remotes::install_github("cole-trapnell-lab/monocle3")

4. Verifying Package Installation

Load the library in a clean R session to verify successful installation:

library(monocle3)

Step-by-step task (numbered, with menu names or commands exactly as in the current docs)

The following step-by-step procedure carries an scRNA-seq count matrix through the complete Monocle 3 trajectory pipeline: object initialization, dimensionality reduction, cell partitioning, graph learning, pseudotime calculation, and trajectory differential expression.

1. Initialize the Cell Data Set Object

Monocle 3 holds single-cell data in an S4 container named cell_data_set (CDS), which extends Bioconductor's SingleCellExperiment. It requires a raw count matrix, cell metadata (with cell barcodes as row names), and feature metadata (with gene IDs as row names and a mandatory column named gene_short_name):

library(monocle3)

# expression_matrix: sparse matrix (dgCMatrix) of counts (genes x cells)
# cell_metadata: data frame containing cell-level annotations
# gene_metadata: data frame containing gene IDs and a 'gene_short_name' column

cds <- new_cell_data_set(
    expression_data = expression_matrix,
    cell_metadata   = cell_metadata,
    gene_metadata   = gene_metadata
)

2. Preprocess and Normalize Counts

Normalize the raw library sizes and compute initial Principal Component Analysis (PCA) dimensions to compress technical noise:

# Normalize and compute 50 principal components
cds <- preprocess_cds(cds, num_dim = 50, method = "PCA")

3. Optional Batch Alignment

If cells were sequenced across multiple experimental runs or donors, align batches using mutual nearest neighbors (via the batchelor package) to remove technical batch effects:

# Align across experimental batches
cds <- align_cds(cds, alignment_group = "batch")

4. Low-Dimensional Projection via UMAP

Project high-dimensional PCA components into a two-dimensional visualization space using Uniform Manifold Approximation and Projection (UMAP):

cds <- reduce_dimension(cds, reduction_method = "UMAP", preprocess_method = "PCA")

5. Cluster Cells and Identify Lineage Partitions

Group cells into clusters and broader partitions (disconnected trajectory subgraphs) using the Leiden community detection algorithm:

cds <- cluster_cells(cds, reduction_method = "UMAP", k = 20, cluster_method = "leiden")

6. Fit the Principal Trajectory Graph

Learn the trajectory graph spanning the cell coordinates in UMAP space using Reversed Graph Embedding (SimplePPT):

# Learn the trajectory graph; use_partition = TRUE restricts graphs to individual partitions
cds <- learn_graph(cds, use_partition = TRUE)

7. Assign Root States and Calculate Pseudotime

Calculate pseudotime values for each cell by defining the root principal node corresponding to the developmental origin. In non-interactive or batch scripts, pass the root node identifier programmatically:

# Identify root node programmatically or inspect interactively
# cds <- order_cells(cds) launches an interactive GUI if run without arguments
cds <- order_cells(cds, root_pr_nodes = "Y_1")

# Visualize trajectory colored by pseudotime
plot_cells(
    cds,
    color_cells_by          = "pseudotime",
    label_cell_groups       = FALSE,
    label_leaves            = FALSE,
    label_branch_points     = TRUE,
    graph_label_size        = 2
)

8. Test for Differential Expression Along the Trajectory

Identify genes whose expression fluctuates significantly along trajectory branches using Moran's I spatial autocorrelation on the principal graph:

# Test dynamic expression across the principal graph
pr_graph_test_res <- graph_test(cds, neighbor_graph = "principal_graph", cores = 4)

# Filter for significantly dynamic genes (FDR q-value < 0.05 and Moran's I > 0.1)
pr_deg_ids <- row.names(subset(pr_graph_test_res, q_value < 0.05 & morans_I > 0.1))

# Group co-varying genes into functional co-expression modules
gene_module_df <- find_gene_modules(cds[pr_deg_ids, ], resolution = 1e-3)

Output and how to read it

Monocle 3 produces three primary forms of output: visual trajectory embeddings, per-cell pseudotime coordinates, and statistical differential expression tables.

1. Trajectory Graph Visualization

When plotted using plot_cells(), Monocle 3 renders:

Principal Graph Backbone: Solid grey tree structures that connect the centers of cell density across the UMAP embedding.
Branch Points: Solid black circular nodes indicating bifurcation points where a multipotent progenitor cell lineage splits into two or more distinct developmental fates.
Leaves: Light or white circular nodes representing terminal endpoints of the differentiation process.

2. Pseudotime Numerical Values

Extracted via pseudotime(cds), pseudotime measures the continuous geodesic distance traversed from the user-selected root node along the principal graph. Cells located at the root node have a pseudotime value of 0. Cells further down a differentiation lineage receive progressively higher positive values. If a cell belongs to a partition completely disconnected from the partition containing the designated root node, its pseudotime is assigned as Inf (infinity).

3. Graph Autocorrelation Results (Moran's I)

The table returned by graph_test() contains statistical metrics for each tested gene:

status: Quality verification flag for the numerical test (e.g. OK).
p_value: Asymptotic or permutation p-value testing the null hypothesis of random spatial expression.
q_value: False discovery rate (FDR) adjusted p-value accounting for genome-wide multiple hypothesis testing.
morans_test_statistic: Standardized z-score representing deviation from expected spatial neutrality.
morans_I: Moran's I spatial autocorrelation coefficient ranging from -1 to +1:
- morans_I > 0 (positive autocorrelation): Cells near each other on the trajectory display similar gene expression levels, highlighting trajectory-dependent marker genes.
- morans_I ≈ 0: Gene expression is randomly distributed across the trajectory graph without spatial patterning.
- morans_I < 0 (negative autocorrelation): Neighboring cells display alternating high and low expression, indicating localized spatial repulsion.

Dynamic expression trends can be inspected with kinetic trajectory plots (plot_genes_in_pseudotime()), contrasting with static pairwise comparisons such as DESeq2 vs edgeR differential expression models and traditional volcano plot visualization.

Troubleshooting

Here are operational solutions for common issues encountered when running Monocle 3 pipelines:

1. Disconnected Trajectories and Disjoint Partitions

Symptom: The learned principal graph does not connect separate cell clusters, and downstream order_cells() returns Inf pseudotime values for major cell groups.
Resolution: By default, learn_graph(cds, use_partition = TRUE) learns separate disjoint graphs for each partition detected during cluster_cells(). If intermediate transitional cells exist but were split into separate partitions due to stringent clustering, run learn_graph(cds, use_partition = FALSE) to force a single unified graph spanning all partitions. Alternatively, decrease the clustering resolution parameter in cluster_cells() to merge continuous lineages into a single partition.

2. Interactive GUI Fails on Headless Clusters or Batch Scripts

Symptom: Calling order_cells(cds) without arguments in an automated R script or headless High-Performance Computing (HPC) environment triggers an error or hangs waiting for user input.
Resolution: In automated pipelines, specify root states programmatically using either root_pr_nodes or root_cells. To programmatically extract the root node corresponding to early experimental timepoints (e.g., Day 0 stem cells), query the principal graph projection auxiliary matrix directly:

# Helper function to programmatically determine root node from early cells
get_earliest_principal_node <- function(cds, time_label = "Day0") {
    early_barcodes <- which(colData(cds)$timepoint == time_label)
    closest_vertex <- cds@principal_graph_aux[["UMAP"]]$pr_graph_cell_proj_closest_vertex
    closest_vertex <- as.matrix(closest_vertex[colnames(cds), ])
    root_node_name <- igraph::V(principal_graph(cds)[["UMAP"]])$name[
        as.numeric(names(which.max(table(closest_vertex[early_barcodes, ]))))
    ]
    return(root_node_name)
}
root_node <- get_earliest_principal_node(cds, "Day0")
cds <- order_cells(cds, root_pr_nodes = root_node)

3. GDAL or GEOS System Library Compilation Errors

Symptom: Installation of Monocle 3 fails during compilation of the sf package with configure: error: gdal-config not found.
Resolution: The sf package requires external geospatial libraries installed on the host system. Install libgdal-dev, libgeos-dev, and libproj-dev via apt-get on Ubuntu/Debian or brew install gdal geos proj on macOS before running the R package installation.

4. Out-of-Memory Errors on Massive Single-Cell Datasets

Symptom: R terminates with an out-of-memory error when initializing new_cell_data_set() or running preprocess_cds() on datasets with >100,000 cells.
Resolution: Ensure expression count matrices are passed as sparse matrices (dgCMatrix from the Matrix package) rather than base R dense matrices. For datasets containing hundreds of thousands of cells, use the BPCells matrix backend, which streams matrix tiles directly from disk without allocating large in-memory buffers.

Free alternatives (table)

Several open-source software packages provide trajectory inference and pseudotime calculation across the R and Python bioinformatics ecosystems:

Tool	Ecosystem	Trajectory Algorithm	Branching Support	Primary Research Strengths	Key Trade-Off
Monocle 3	R / Bioconductor	Reversed Graph Embedding (SimplePPT) on UMAP coordinates	Yes (bifurcations, loops, and multi-lineage partitions)	Integrated pipeline from count matrix through graph autocorrelation (Moran's I) differential expression; native support for massive scRNA-seq datasets.	Heavily dependent on UMAP topology; partitions can fragment continuous lineages unless tuned.
Slingshot	R / Bioconductor	Minimum Spanning Tree (MST) on cluster centers + simultaneous principal curves	Yes (multi-branching lineages)	Stable, non-parametric curve fitting; operates directly on arbitrary dimensional reductions (PCA, UMAP, Diffusion Maps).	Requires pre-computed clusters; less scalable to datasets exceeding 200,000 cells without downsampling.
Scanpy (PAGA / DPT)	Python / AnnData	Partition-based Graph Abstraction (PAGA) and Diffusion Pseudotime (DPT)	Yes (topological graph abstraction)	High computational speed, native integration with AnnData, robust diffusion-based pseudotime ordering across complex topologies.	Python-only ecosystem; requires separate modules for trajectory differential expression modeling.
CellRank	Python / AnnData	Markov chains combining RNA velocity (scVelo) with transcriptomic similarity	Yes (probabilistic cell fates and macrostates)	Directional cell-fate probabilities without requiring manual root node definition; integrates spliced/unspliced kinetics.	Requires RNA velocity data (spliced/unspliced read counts) or high-quality lineage tracing priors.

FAQ

What is the difference between Monocle 2 and Monocle 3?

Monocle 2 used the DDRTree algorithm to learn tree-structured trajectories directly in high-dimensional gene expression space, which limited scalability to tens of thousands of cells and could not handle circular or disconnected trajectories. Monocle 3 uses Reversed Graph Embedding (SimplePPT) directly on UMAP embeddings, supports automatic partitioning into disjoint subgraphs, scales to millions of cells, and replaces parametric differential expression with Moran's I spatial autocorrelation in graph_test().

Does Monocle 3 require raw counts or normalized expression values?

Monocle 3 requires raw integer count data when constructing the cell_data_set object. Its internal preprocessing function (preprocess_cds()) automatically computes size factors, standardizes sequencing depth across cells, applies a log-transformation, and computes principal components. Providing pre-normalized or log-transformed counts as raw input distorts the statistical assumptions of downstream models.

How does Monocle 3 select root cells for pseudotime calculation?

Monocle 3 identifies the root state through user-directed biological supervision. In an interactive R session, order_cells() displays the learned trajectory graph, allowing researchers to select root nodes visually. In scripted or automated workflows, researchers specify root nodes programmatically via the root_pr_nodes argument by identifying the principal graph node closest to known progenitor cells or early experimental timepoints.

Can Monocle 3 analyze multi-branching cell lineages?

Yes. Monocle 3's SimplePPT graph-learning algorithm identifies bifurcation and multifurcation branch points where progenitor lineages diverge into multiple distinct mature cell types. Each branch is indexed on the principal graph, allowing researchers to isolate branch-specific pseudotime segments and compare gene activation kinetics across diverging cell fates.

How does graph_test() differ from traditional differential expression testing?

Traditional single-cell differential expression tools perform pairwise tests comparing discrete categorical cell clusters. In contrast, graph_test() treats single-cell expression as a continuous spatial process across the principal trajectory graph. By evaluating Moran's I spatial autocorrelation coefficient, it identifies genes whose expression levels vary smoothly along developmental trajectories without requiring artificial clustering or pseudotime discretization.

Sources (official docs)

Cole Trapnell Lab / University of Washington. Monocle 3 Documentation: Installation Guide. Verified 2026-11-10. https://cole-trapnell-lab.github.io/monocle3/docs/installation/
Cole Trapnell Lab / University of Washington. Monocle 3 Documentation: Constructing Single-Cell Trajectories. Verified 2026-11-10. https://cole-trapnell-lab.github.io/monocle3/docs/trajectories/
Cole Trapnell Lab / University of Washington. Monocle 3 Documentation: Differential Expression Analysis. Verified 2026-11-10. https://cole-trapnell-lab.github.io/monocle3/docs/differential/
Cao, J., Spielmann, M., Qiu, X., Huang, X., Ibrahim, D. M., Hill, A. J., Zhang, F., Mundlos, S., Christiansen, L., Steemers, F. J., Trapnell, C., & Shendure, J. (2019). The single-cell transcriptional landscape of mammalian organogenesis. Nature, 566(7745), 496–502. DOI: 10.1038/s41586-019-0969-x. Verified 2026-11-10. https://pubmed.ncbi.nlm.nih.gov/30787437/
Cole Trapnell Lab. monocle3: Single-cell analysis toolkit for R. GitHub repository. Verified 2026-11-10. https://github.com/cole-trapnell-lab/monocle3

Monocle 3: Single-Cell Trajectory and Pseudotime Analysis in R