scanpy.tl.louvain#

scanpy.tl.louvain(adata, resolution=None, *, random_state=0, restrict_to=None, flavor='vtraag', directed=True, use_weights=False, partition_type=None, partition_kwargs=mappingproxy({}), use=None, out=False, adjacency=None, neighbors_key=None, obsp=None, key_added=None, copy=False)[source]#

Cluster cells into subgroups [Blondel et al., 2008, Levine et al., 2015, Traag, 2015].

Deprecated: The function louvain is deprecated and will be removed in the future. Use :func:`scanpy.tl.leiden` instead.

Deprecated since version 1.12.0: Use scanpy.tl.leiden() instead.

Cluster cells using the Louvain algorithm [Blondel et al., 2008] in the implementation of Traag [2015]. The Louvain algorithm was proposed for single-cell analysis by Levine et al. [2015].

This requires having run neighbors() or bbknn() first (see use).

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

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

✅

❌
Parameters:
adata AnnData

The annotated data matrix.

resolution float | None (default: None)

For the default flavor ('vtraag') or for `RAPIDS`, you can provide a resolution (higher resolution means finding more and smaller clusters), which defaults to 1.0. See “Time as a resolution parameter” in Lambiotte et al. [2014].

random_state int | RandomState | None (default: 0)

Change the initialization of the optimization.

restrict_to tuple[str, Sequence[str]] | None (default: None)

Restrict the clustering to the categories within the key for sample annotation, tuple needs to contain (obs_key, list_of_categories).

flavor Literal['vtraag', 'igraph'] (default: 'vtraag')

Choose between to packages for computing the clustering.

'vtraag'

Much more powerful than 'igraph', and the default.

'igraph'

Built in igraph method.

directed bool (default: True)

Interpret the graph as directed?

use_weights bool (default: False)

Use weights from knn graph.

partition_type type[MutableVertexPartition] | None (default: None)

Type of partition to use. Only a valid argument if flavor is 'vtraag'.

partition_kwargs Mapping[str, Any] (default: mappingproxy({}))

Key word arguments to pass to partitioning, if vtraag method is being used.

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.

out AdRef[Idx2D | int, AnnData] | str | bool (default: False)

Where to write the cluster labels. Given by an accessor, e.g. A.obs['clusters']. strs are anndata.acc.AdAcc.resolve()d. Accompanying uns entries are stored under the same key. If True, the cluster labels is returned instead of written. If False, it is written to .obs['louvain'] and .uns['louvain'] ('louvain_R' if restrict_to is passed).

key_added str | None (default: None)

Deprecated since version 1.13.0: Use out instead.

key_added='k' is out=A.obs['k'].

adjacency csr_array | csc_array | csr_matrix | csc_matrix | None (default: None)

Deprecated since version 1.13.0: Store the graph in .obsp and pass use=A.obsp[...] instead.

Sparse adjacency matrix of the graph, defaults to neighbors connectivities.

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'.

Use neighbors connectivities as adjacency. If not specified, louvain looks at .obsp[‘connectivities’] for connectivities (default storage place for pp.neighbors). If specified, louvain looks at .obsp[.uns[neighbors_key][‘connectivities_key’]] for connectivities.

obsp str | None (default: None)

Deprecated since version 1.13.0: Use use=A.obsp[...] instead.

Use .obsp[obsp] as adjacency. You can’t specify both obsp and neighbors_key at the same time.

copy bool (default: False)

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

Copy adata or modify it inplace.

Return type:

AnnData | Categorical | None

Returns:

Returns the cluster labels if out=True, else None. By default sets the following fields (see out for others):

adata.obs['louvain']pandas.Series (dtype category)

Array of dim (number of samples) that stores the subgroup id ('0', '1', …) for each cell.

adata.uns['louvain']['params']dict

A dict with the values for the parameters resolution, random_state, and n_iterations.