Trajectory Analysis with PAGA & DPT
Reconstruct cell differentiation trajectories using PAGA graph abstraction and Diffusion Pseudotime on the PBMC 3k dataset.
What you'll learn
- Reduce a clustered scRNA-seq dataset into a coarse PAGA graph that captures cluster connectivity, then a per-cell pseudotime ordering using Diffusion Pseudotime.
- Pick an appropriate root cluster and recognize when pseudotime is reversed.
- Lay out the trajectory with a force-directed graph initialized from PAGA positions for a clean publication-quality figure.
Prerequisites
- • Oreumics installed (install guide).
- • PBMC tutorial completed — trajectory inference runs on top of standard preprocessing & clustering.
- • PAGA, DPT, and diffusion map are defined in the glossary at the bottom of this page.
- • Sample data:
sampledata/scrna/pbmc3k_raw.h5ad— pre-bundled. For a clearer developmental trajectory, swap insampledata/velocity/dentategyrus_velocity.h5adfrom the velocity tutorial.
Dataset
Sample file (pre-packaged)
sampledata/scrna/pbmc3k_raw.h5ad— 2,700 cells × 32,738 genes · integer counts · already included in OreumicsWhat it is
Peripheral blood mononuclear cells (PBMCs) from a healthy human donor, sequenced on a 10x Chromium v2 chip. The trajectory analysis captures monocyte-to-DC maturation and T-cell activation axes — a useful learning example even though the biology is more complex than a pure stem-cell dataset.
Prerequisite
Trajectory analysis is most meaningful on datasets with a clear biological continuum (stem cells, immune activation, development). On PBMC data the trajectory captures monocyte-to-DC maturation and T-cell activation axes rather than a single linear lineage — this makes it a useful learning example even if the biology is more complex than a pure stem-cell dataset.
Trajectory with PAGA+DPT
A 14-node pipeline from raw counts to a trajectory figure. PAGA builds a coarse-grained graph of cluster connectivity, and DPT assigns each cell a pseudotime value reflecting its progress along the inferred trajectory. Together they reveal the branching topology of cell state transitions.
Pipeline — Part 1 (preprocessing + embedding)
Pipeline — Part 2 (trajectory)
Load the PBMC 3k counts. The h5ad format stores the full AnnData object with counts matrix, cell barcodes, and gene names in a single file — faster to load than MTX directories.
file_pathsampledata/scrna/pbmc3k_raw.h5adWhat you'll see
AnnData with 2,700 cells × 32,738 genes loaded. The raw count matrix is stored in adata.X.
Scale each cell so its total counts equal 10,000 (counts-per-ten-thousand, CP10K), making cells directly comparable regardless of sequencing depth.
target_sum10000Apply log(x+1) transformation. The +1 prevents log(0) for zero-count genes. Log transformation compresses the dynamic range so that highly expressed genes do not dominate downstream variance calculations.
basenullnatural log (default)save_normalizedtrueSelect the top 2,000 highly variable genes. HVG selection retains genes with the most cell-to-cell variation, which carry the biological signal for clustering and trajectory. The seurat flavor uses a mean/dispersion approach that works well for most datasets.
n_top_genes2000flavorseuratWhat you'll see
2,000 genes flagged as highly_variable: True in adata.var.
Scale each gene to zero mean and unit variance, clamped at max_value: 10. Scaling ensures each gene contributes equally to PCA — without it, high-expression genes like ribosomal proteins would dominate the first principal components. With hvg_only (default true) only the HVGs stay in X; the full gene set is preserved in adata.raw.
max_value10Compute 50 principal components. PCA is the backbone of the entire downstream analysis. For trajectory analysis, retaining more PCs (30+) in Neighbors is often better than for simple clustering, because subtle continuous variation in later PCs can capture gradual cell state transitions.
n_comps50Tip
Add a PCA Visualization node (plot_type: variance_ratio) after PCA to find the "elbow" — use that number of PCs for n_pcs in Neighbors (node default 15; 0 = all PCs).
Build the k-nearest-neighbor graph. This graph is shared by UMAP, clustering, PAGA, and the diffusion map — getting this right is critical. n_neighbors: 15 balances local precision with global connectivity. Larger values (30+) produce smoother trajectories at the cost of detail.
n_neighbors15n_pcs30default 15Compute a 2D UMAP embedding for visualization. min_dist: 0.3 spreads clusters a little more than the node default of 0.1, making trajectory paths between clusters visually clearer. UMAP here is primarily for visualization — the trajectory itself is computed from the diffusion map, not UMAP coordinates. (init_pos: paga is available once PAGA has run, for a trajectory-aware layout.)
min_dist0.3spread1.0What you'll see
After this step you can preview the UMAP in the node output panel. You should see 7–9 loosely separated clusters, with monocyte and T-cell populations on opposite ends of the layout.
Run Leiden clustering. Resolution 0.8 yields roughly 8–11 clusters on PBMC 3k data, fine enough to capture distinct cell types while keeping the PAGA graph interpretable. Store results under the key "leiden" — this key is referenced by both PAGA and DPT nodes downstream.
methodleidenresolution0.8key_addedleidenWhat you'll see
Cluster labels added to adata.obs["leiden"]. Each cell has an integer cluster ID. The UMAP should show distinct colored islands.
PAGA computes a weighted graph where nodes are clusters and edge weights represent the statistical likelihood of connectivity between clusters — high weight means many cells in one cluster are nearest neighbors of cells in the other. Model v1.2 is the current recommended version and produces more robust connectivity estimates than v1.0. This step does NOT produce pseudotime; it only maps the topology of the cell state space.
groupsleidenmodelv1.2What you'll see
The PAGA graph is stored in adata.uns["paga"]. Edge weights above ~0.1 represent meaningful connectivity. For PBMC data, expect a central monocyte cluster connected to dendritic cells, and a peripheral T-cell/NK-cell subgraph.
Compute diffusion components. The diffusion map re-embeds cells in a space where Euclidean distance approximates biological transition probability. The node default of 15 components is enough to capture branching trajectories faithfully. The first 2–3 diffusion components often reveal the major developmental axes of the data.
n_comps15defaultWhat you'll see
Diffusion components stored in adata.obsm["X_diffmap"]. The first component (DC1) typically separates the most divergent cell populations (e.g., monocytes from lymphocytes in PBMC).
Compute Diffusion Pseudotime. DPT needs a root: name a root_group (a cluster label from groups) and the node picks the root cell inside it; or set root_cell to an explicit cell index, which overrides root_group. If both are empty the node falls back to an automatic choice from the first diffusion component. n_dcs: 10 uses the first 10 diffusion components for the pseudotime calculation, filtering out noise from later components.
groupsleidenroot_groupn_dcs10use top 10 diffusion componentsWhat you'll see
Pseudotime values between 0.0 and 1.0 added to adata.obs["dpt_pseudotime"]. Cells close to the root get values near 0; terminally differentiated cells approach 1.
Tip
If pseudotime is reversed (your expected root cluster has high values), set root_group to that cluster and re-run DPT — nothing upstream needs to change. Ask the AI Copilot which cluster carries the progenitor markers if you are unsure.
Compute a force-directed graph layout initialized from the PAGA positions. init_pos: paga respects the cluster topology inferred by PAGA, producing a much cleaner result than a random start. The default layout is "fa" (ForceAtlas2), but shipped Oreumics builds do not include the optional fa2 backend, so scanpy falls back to "fr" (Fruchterman–Reingold); the node reports the layout actually used and writes the coordinates to obsm["X_draw_graph_fr"]. The layout is seeded (random_state) so re-runs reproduce the same picture.
layoutfaruns as "fr" in shipped builds — reported in the resultinit_pospagainitialize from PAGA positionsrandom_state0What you'll see
The graph layout shows clusters as dense islands with thin bridge regions connecting related populations. This layout is often more interpretable than UMAP for trajectory visualization because inter-cluster distances directly reflect PAGA connectivity weights. The Methods text names the effective layout.
Tip
Force-directed layouts are slow on large datasets. If Draw Graph takes too long, run it on a Subset Data selection first, or skip it — UMAP with init_pos: paga is a cheaper trajectory-aware embedding.
One plot per node. plot_type: paga draws the abstracted graph with edge widths proportional to connectivity; threshold: 0.01 filters out very weak PAGA edges, keeping the graph clean. Add further Trajectory Visualization nodes with plot_type: dpt_pseudotime (embedding colored by pseudotime) and plot_type: draw_graph (the force-directed layout) to complete the figure set — they fan out from DPT / Draw Graph and need no re-computation.
plot_typepagaalso: paga_embedding, dpt_pseudotime, dpt_groups, diffmap, draw_graphgroupsleidenembeddingumapthreshold0.01filter weak PAGA edgesWhat you'll see
The PAGA graph shows clusters as nodes joined by weighted edges; the dpt_pseudotime plot shows a gradient from pseudotime 0 to 1 over the embedding. Clear linear paths through the PAGA graph indicate confident trajectory directions. Branching points appear as cluster nodes with 3 or more strong edges.
Expected Results
- • PAGA graph: roughly 8–11 cluster nodes; monocyte clusters are centrally connected with edges > 0.3
- • DC1 (first diffusion component): explains the main monocyte–lymphocyte axis of variation
- • DPT pseudotime: ranges 0.0–1.0 from the chosen root_group outward
- • Force-directed layout with PAGA initialization shows cleaner separation than a random start; the node reports the effective layout (fr in shipped builds)
- • Trajectory Visualization: PAGA graph, pseudotime gradient and draw_graph layout as separate images, each with its own Visualization Workspace
Tips & Troubleshooting
PAGA graph is fully connected (all edges dark)
Increase the threshold in Trajectory Visualization from 0.01 to 0.05 or 0.1 to suppress weak edges. If the problem persists, your clustering resolution may be too high — try reducing to 0.5.
Pseudotime is reversed (expected root has high values)
Set root_group on the DPT node to the cluster you consider the origin (or root_cell to an explicit cell index) and re-run. Only DPT and its downstream plots re-execute.
Draw Graph is very slow
Force-directed layouts scale poorly with cell count. Try layout: drl, run on a Subset Data selection, or use UMAP with init_pos: paga instead. Note that layout: fa resolves to fr in shipped builds — the effective layout is reported on the node.
Going Further
- For a more biologically-grounded direction, use RNA Velocity instead of DPT — see the velocity tutorial. Velocity uses spliced/unspliced ratios to determine direction, no root cell needed.
- To turn pseudotime into fate probabilities and gene trends, continue with the CellRank nodes (CellRank Kernel with kernel_type: pseudotime → Cell Fate Analysis → Lineage Drivers → Gene Trends). The CellRank — Pseudotime Fate Analysis template wires exactly this chain; see the CellRank node reference.
- Give the PAGA nodes biological names: run Auto Annotation or CellTypist Annotation after Clustering (or rename with Edit Clusters) and point PAGA / DPT
groupsat the annotated column.
Glossary
- PAGA
- Partition-based Graph Abstraction. A method that summarizes a kNN graph as cluster nodes connected by weighted edges, where edge weight reflects connectivity strength.
- DPT (Diffusion Pseudotime)
- A continuous per-cell ordering derived from random-walk distances in diffusion-map space. Requires a root (root_group or root_cell on the DPT node).
- Diffusion map
- A non-linear embedding where Euclidean distance approximates random-walk transition probability — well-suited to continuous biological gradients (development, differentiation).
- Root
- The cell DPT calls "time 0". Choose it by cluster (
root_group) or by explicit index (root_cell); with neither set the node picks one automatically. - Force-directed layout (fa / fr)
- Draw Graph places cells by simulating attractive and repulsive forces on the kNN graph. "fa" is ForceAtlas2, which needs the optional fa2 package not shipped with Oreumics, so the node runs Fruchterman–Reingold ("fr") and says so. Initializing from PAGA positions (init_pos="paga") produces a much cleaner layout than random initialization.