bioalpha.singlecell.tools.louvain

bioalpha.singlecell.tools.louvain(adata: AnnData, resolution: float = 1.0, restrict_to: Tuple[str, Sequence[str]] | None = None, random_state: None | int | RandomState = 0, key_added: str = 'louvain', adjacency: spmatrix | None = None, flavor: Literal['alpha', 'vtraag', 'igraph', 'rapids'] = 'alpha', directed: bool = True, use_weights: bool = False, partition_type: Literal['rb', 'cpm', 'rber'] = 'rb', neighbors_key: str | None = None, obsp: str | None = None, copy: bool = False, **kwargs) → AnnData | None

Cluster cells into subgroups.

Cluster cells using the Louvain-alpha algorithm, an improved version of the Louvain algorithm. This requires having ran pp.neighbors or pp.bbknn first.

Parameters:

  • adata (AnnData) – The annotated data matrix of shape n_obs x n_vars. Rows correspond to cells and columns to genes.

  • resolution (float, default = 1.0) – A parameter value controlling the coarseness of the clustering. Higher values lead to more clusters. Set to None if overriding partition_type to one that doesn’t accept a resolution_parameter.

  • restrict_to (Optional[Tuple[str, Sequence[str]]], default = None) – Restrict the clustering to the categories within the key for sample annotation, tuple needs to contain (obs_key, list_of_categories).

  • random_state (Optional[Union[int, RandomState]], default = 0) – Change the initialization of the optimization.

  • key_added (str, default = "louvain") – adata.obs key under which to add the cluster labels.

  • adjacency (Optional[spmatrix], default = None) – Sparse adjacency matrix of the graph, defaults to neighbors connectivities.

  • flavor (Literal["alpha", "vtraag", "igraph", "rapids"], default = “alpha”) – Choose between to packages for computing the clustering. "alpha" is much the default.

  • directed (bool, default = True) – Interpret the adjacency matrix as directed graph?

  • use_weights (bool, default = False) – Use weights from knn graph.

  • partition_type (Optional[str], default = rb) – Type of partition to use. (rb, cpm, rber) Only a valid argument if flavor is "alpha" or "vtraag".

  • neighbors_key (Optional[str], default = None) – Use neighbors connectivities as adjacency. If not specified, louvain looks .obsp["connectivities"] for connectivities (default storage place for pp.neighbors). If specified, louvain looks .obsp[.uns[neighbors_key]["connectivities_key"]] for connectivities.

  • obsp (Optional[str], default = None) – Use .obsp[obsp] as adjacency. You can’t specify both obsp and neighbors_key at the same time.

  • copy (bool, default = False) – Whether to copy adata or modify it inplace.

  • kwargs (dict) – Any further arguments to pass to _sctools.clustering.louvain (which in turn passes arguments to the partition_type).

Returns:

adata – If copy=True it returns or else adds fields to adata:

  • .obs[key_added] Array of dim (number of samples) that stores the subgroup id ("0", "1", …) for each cell.

  • .uns[key_added]["params"] A dict with the values for the parameters resolution, random_state, and n_iterations.

  • .uns[key_added]["modularity"] The modularity score of Louvain-alpha algorithm. Only if flavor="alpha"

Return type:

AnnData