Paga graph abstraction

paga-graph-abstraction

Summary

PAGA (Partition-based Graph Abstraction) constructs a coarse-grained connectivity matrix from clustered single-cell data by abstracting the neighborhood graph into a graph where nodes represent cell clusters and edges encode partition-based connectivity. Use this skill to infer high-level trajectory structure and developmental relationships from clustered scRNA-seq data.

When to use

You have clustered single-cell RNA-seq data (via Leiden, Louvain, or equivalent) and a k-nearest neighbor graph computed in PCA space, and you want to abstract cell-level connectivity into cluster-level connectivity to infer developmental trajectories, lineage relationships, or coarse-grained manifold structure without trajectory inference on individual cells.

When NOT to use

• Your clusters are biologically meaningless or only partially overlapping with true cell states; PAGA assumes clusters represent coherent biological entities.
• You are analyzing time-series or perturbation data where directionality matters; PAGA produces undirected graphs unless you apply directional post-hoc methods.
• Your data has very few clusters (< 3) or extreme imbalance in cluster sizes; the abstraction may not capture meaningful inter-cluster structure.

Inputs

• anndata.AnnData object with preprocessed log-transformed gene expression (adata.X)
• PCA representation (adata.obsm['X_pca'])
• k-nearest neighbors graph (adata.obsp['distances'] and adata.obsp['connectivities'])
• cluster labels (adata.obs['leiden'] or equivalent categorical column)

Outputs

• adata.uns['paga']['connectivities']: sparse n_clusters × n_clusters connectivity matrix
• adata.uns['paga']['transitions_confidence']: edge weights quantifying cluster connectivity strength
• adata.obsm['X_paga']: cluster-level coordinates for visualization

How to apply

After computing a k-nearest neighbors graph (sc.pp.neighbors with n_neighbors=15 and use_rep='X_pca' by default) and partitioning cells into clusters using Leiden clustering (sc.tl.leiden), execute sc.tl.paga on the annotated data object. The algorithm computes a connectivity matrix where each entry [i,j] quantifies the strength of connection between clusters i and j based on the proportion of edges in the k-NN graph that cross between those clusters. The resulting partition-based graph abstraction is stored in adata.uns['paga']['connectivities'], a sparse n_clusters × n_clusters matrix. Verify the output by confirming that connectivities dimensions match the number of clusters and that values reflect inter-cluster edge density.

Related tools

• Scanpy (Scalable toolkit housing sc.tl.paga trajectory inference method and neighborhood graph computation (sc.pp.neighbors, sc.tl.leiden)) — https://github.com/scverse/scanpy
• anndata (Data structure (AnnData) that stores clustered single-cell data, k-NN graphs, and PAGA outputs) — https://github.com/scverse/anndata
• PAGA (Original partition-based graph abstraction algorithm; integrated into Scanpy as sc.tl.paga) — https://github.com/theislab/paga

Examples

import scanpy as sc
adata = sc.datasets.paul15()
sc.pp.neighbors(adata, n_neighbors=15, use_rep='X_pca')
sc.tl.leiden(adata)
sc.tl.paga(adata)
print(adata.uns['paga']['connectivities'].shape)

Evaluation signals

• adata.uns['paga'] dictionary exists and contains 'connectivities' and 'transitions_confidence' keys
• connectivities matrix has shape (n_clusters, n_clusters) matching the unique values in the cluster column
• connectivities matrix is sparse and non-negative; values typically in [0, 1] range reflecting edge density fractions
• Visualization of the PAGA graph (via sc.pl.paga) shows meaningful cluster-level topology consistent with known biology (e.g., branching lineages for hematopoiesis)
• Connectivity strength between biologically related clusters is substantially higher than between unrelated clusters; no spurious long-range edges

Limitations

• PAGA abstraction quality depends critically on the input clustering; poor or over/under-clustered data produces uninformative partitions.
• The method is fundamentally undirected; it does not infer direction of differentiation without additional directional cues or time-series labels.
• PAGA loses cell-level resolution; subtle within-cluster heterogeneity or intermediate cells may be compressed in the cluster-level graph.
• Results are sensitive to k-nearest neighbor parameter (n_neighbors); the default k=15 may require tuning for datasets with different cell density or dimensionality.

Evidence

• [other] How does PAGA compute connectivity: "PAGA (Partition-based Graph Abstraction) algorithm construct a connectivity matrix from clustered single-cell data, and what is the expected dimensionality of the resulting abstraction"
• [intro] Scanpy trajectory inference: "Scanpy is a scalable toolkit for analyzing single-cell gene expression data that includes trajectory inference capabilities, which encompasses methods like PAGA"
• [other] Workflow for PAGA execution: "Compute k-nearest neighbors graph using sc.pp.neighbors with default parameters (n_neighbors=15, use_rep='X_pca'). 3. Run Leiden clustering via sc.tl.leiden to partition cells into clusters. 4."
• [other] PAGA output structure: "nodes represent clusters. 5. Verify that adata.uns['paga'] exists and contains a 'connectivities' matrix with dimensions matching n_clusters × n_clusters"
• [readme] PAGA availability in Scanpy: "PAGA is available within Scanpy through: [tl.paga] | [pl.paga] | [pl.paga_path] | [pl.paga_compare]"