scanpy.tl.paga#

scanpy.tl.paga(adata, groups=None, *, use_rna_velocity=False, model='v1.2', use=None, out=False, neighbors_key=None, copy=False)[source]#

Map out the coarse-grained connectivity structures of complex manifolds [Wolf et al., 2019].

By quantifying the connectivity of partitions (groups, clusters) of the single-cell graph, partition-based graph abstraction (PAGA) generates a much simpler abstracted graph (PAGA graph) of partitions, in which edge weights represent confidence in the presence of connections. By thresholding this confidence in paga(), a much simpler representation of the manifold data is obtained, which is nonetheless faithful to the topology of the manifold.

The confidence should be interpreted as the ratio of the actual versus the expected value of connections under the null model of randomly connecting partitions. We do not provide a p-value as this null model does not precisely capture what one would consider “connected” in real data, hence it strongly overestimates the expected value. See an extensive discussion of this in Wolf et al. [2019].

Note

Note that you can use the result of paga() in umap() and draw_graph() via init_pos='paga' to get single-cell embeddings that are typically more faithful to the global topology.

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

scipy.sparse.{csr,csc}_{array,matrix}

✅

❌
Parameters:
adata AnnData

An annotated data matrix.

groups AdRef | str | None (default: None)

Key for categorical in adata.obs. You can pass your predefined groups by choosing any categorical annotation of observations. Default: The first present key of 'leiden' or 'louvain'. Given by a reference like A.obs['leiden'], or by column name (strs are resolve()d with ScanpyV2Preview).

use_rna_velocity bool (default: False)

Use RNA velocity to orient edges in the abstracted graph and estimate transitions. Requires that adata.uns contains a directed single-cell graph with key ['velocity_graph']. This feature might be subject to change in the future.

model Literal['v1.2', 'v1.0'] (default: 'v1.2')

The PAGA connectivity model.

use GraphAcc | str | None (default: None)

The neighborhood graph (connectivities) to use, e.g. A.obsp['k'] after sc.pp.neighbors(adata, out=A.obsp['k']), or any other graph. strs are resolve()d, e.g. 'obsp.k'. If None, the one neighbors() wrote by default. Distances and parameters are used from where neighbors() stored them alongside it, if they exist.

out bool (default: False)

Where to write the abstracted graph. If True, the abstracted graph is returned instead of written. If False, it is written to .uns['paga'] (and the group sizes to .uns[f'{groups}_sizes']).

neighbors_key str | None (default: None)

Deprecated since version 1.13.0: Use use instead, e.g. use=A.obsp['k_connectivities'] for neighbors_key='k'.

If not specified, paga looks .uns['neighbors'] for neighbors settings and .obsp['connectivities'], .obsp['distances'] for connectivities and distances respectively (default storage places for pp.neighbors). If specified, paga looks .uns[neighbors_key] for neighbors settings and .obsp[.uns[neighbors_key]['connectivities_key']], .obsp[.uns[neighbors_key]['distances_key']] for connectivities and distances respectively.

copy bool (default: False)

Deprecated since version 1.13.0: Copy adata before calling this function instead.

Copy adata before computation and return a copy. Otherwise, perform computation inplace and return None.

Return type:

AnnData | dict[str, Any] | None

Returns:

Returns the following as a dict if out=True (plus 'sizes', the group sizes, unless use_rna_velocity), else None. By default sets the following fields (see out for others):

adata.uns['paga']['connectivities']numpy.ndarray (dtype float)

The full adjacency matrix of the abstracted graph, weights correspond to confidence in the connectivities of partitions. Unless use_rna_velocity.

adata.uns['paga']['connectivities_tree']scipy.sparse.csr_matrix (dtype float)

The adjacency matrix of the tree-like subgraph that best explains the topology. Unless use_rna_velocity.

adata.uns['paga']['transitions_confidence']scipy.sparse.csr_matrix (dtype float)

Confidence of transitions between groups, if use_rna_velocity.

adata.uns['paga']['groups']str

The .obs column groups refers to.

adata.uns[f'{groups}_sizes']numpy.ndarray (dtype int)

The group sizes, unless use_rna_velocity.

Notes

Together with a random walk-based distance measure (e.g. scanpy.tl.dpt()) this generates a partial coordinatization of data useful for exploring and explaining its variation.

See also

pl.paga, pl.paga_path, pl.paga_compare