dynamo.tl.louvain(adata, resolution=1.0, use_weight=False, weights=None, initial_membership=None, adj_matrix=None, adj_matrix_key=None, seed=None, result_key=None, layer=None, obsm_key=None, selected_cluster_subset=None, selected_cell_subset=None, directed=True, copy=False, **kwargs)[source]

Apply louvain clustering to adata.

For other general community detection related parameters, please refer to dynamo's cluster_community() function.

Based on the cdlib package, the Louvain algorithm optimises the modularity in two elementary phases: (1) local moving of nodes; (2) aggregation of the network. In the local moving phase, individual nodes are moved to the community that yields the largest increase in the quality function. In the aggregation phase, an aggregate network is created based on the partition obtained in the local moving phase. Each community in this partition becomes a node in the aggregate network. The two phases are repeated until the quality function cannot be increased further.

Please note that since 2/23/23, we have replaced the integrated louvain method from cdlib package with that from the original louvain package.

  • adata (AnnData) – An adata object

  • resolution (float) – The resolution of the clustering that determines the level of detail in the clustering process. An increase in this value will result in the generation of a greater number of clusters.

  • use_weight (bool) – Whether to use the weight of the edges in the clustering process. Default False

  • weights (Union[str, Iterable, None]) – Weights of edges. Can be either an iterable (list of double) or an edge attribute.

  • initial_membership (Optional[List[int]]) – List of int. Initial membership for the partition. If None then defaults to a singleton partition.

  • adj_matrix (Optional[csr_matrix]) – The adjacency matrix to use for the cluster_community function. Default None.

  • adj_matrix_key (Optional[str]) – The adjacency matrix key in adata.obsp used for the cluster_community function. Default None.

  • seed (Optional[int]) – Seed for the random number generator. By default, uses a random seed if nothing is specified.

  • result_key (Optional[str]) – the key to use for saving clustering results which will be included in both adata.obs and adata.uns.

  • layer (Optional[str]) – The adata layer where cluster algorithms will work on.

  • obsm_key (Optional[str]) – The key of the obsm that points to the expression embedding to be used for dyn.tl.neighbors to calculate the nearest neighbor graph.

  • selected_cluster_subset (Optional[Tuple[str, List[int]]]) – A tuple of 2 elements (cluster_key, allowed_clusters) filtering cells in adata based on cluster_key in adata.obs and only reserves cells in the allowed clusters.

  • selected_cell_subset (Optional[List[int]]) – A list of cell indices to cluster.

  • directed (bool) – Whether the graph is directed.

  • copy (bool) – Return a copy instead of writing to adata.

  • **kwargs – Additional arguments to pass to the clustering function.


An updated AnnData object with the leiden clustering results added. The adata is updated up with the result_key key to use for saving clustering results which will be included in both adata.obs and adata.uns. adata.obs[result_key] saves the clustering identify of each cell where the adata.uns[result_key] saves the relevant parameters for the leiden clustering .

Return type: