(feat): igraph leiden implementation now included as an option in sc.tl.leiden

scanpy/tests/notebooks/test_pbmc3k.py

@@ -29,6 +29,9 @@
 @needs.leidenalg
 def test_pbmc3k(image_comparer):
     save_and_compare_images = partial(image_comparer, ROOT, tol=20)
+    save_and_compare_images_rank_genes = partial(
+        image_comparer, ROOT, tol=10
+    )  # 20 is too high for such sparse plots
 
     adata = sc.read(
         "./data/pbmc3k_raw.h5ad", backup_url="https://falexwolf.de/data/pbmc3k_raw.h5ad"
@@ -115,32 +118,32 @@ def test_pbmc3k(image_comparer):
 
     sc.tl.rank_genes_groups(adata, "leiden")
     sc.pl.rank_genes_groups(adata, n_genes=20, sharey=False, show=False)
-    save_and_compare_images("rank_genes_groups_1")
+    save_and_compare_images_rank_genes("rank_genes_groups_1")
 
     sc.tl.rank_genes_groups(adata, "leiden", method="logreg")
     sc.pl.rank_genes_groups(adata, n_genes=20, sharey=False, show=False)
-    save_and_compare_images("rank_genes_groups_2")
+    save_and_compare_images_rank_genes("rank_genes_groups_2")
 
     sc.tl.rank_genes_groups(adata, "leiden", groups=["0"], reference="1")
     sc.pl.rank_genes_groups(adata, groups="0", n_genes=20, show=False)
-    save_and_compare_images("rank_genes_groups_3")
+    save_and_compare_images_rank_genes("rank_genes_groups_3")
 
     # gives a strange error, probably due to jitter or something
     # sc.pl.rank_genes_groups_violin(adata, groups='0', n_genes=8)
     # save_and_compare_images('rank_genes_groups_4')
 
-    if adata[adata.obs["leiden"] == "4", "CST3"].X.mean() < 1:
+    if adata[adata.obs["leiden"] == "3", "CST3"].X.mean() < 1:
         (  # switch clusters
+            adata.obs["leiden"][adata.obs["leiden"] == "3"],
             adata.obs["leiden"][adata.obs["leiden"] == "4"],
-            adata.obs["leiden"][adata.obs["leiden"] == "5"],
-        ) = ("5", "4")
+        ) = ("4", "3")
     new_cluster_names = [
         "CD4 T cells",
-        "CD14+ Monocytes",
-        "B cells",
         "CD8 T cells",
+        "B cells",
         "NK cells",
         "FCGR3A+ Monocytes",
+        "CD14+ Monocytes",
         "Dendritic cells",
         "Megakaryocytes",
     ]

scanpy/tests/test_clustering.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import pytest
+from sklearn.metrics.cluster import normalized_mutual_info_score
 
 import scanpy as sc
 from scanpy.testing._helpers.data import pbmc68k_reduced
@@ -13,8 +14,51 @@ def adata_neighbors():
 
 
 @needs.leidenalg
-def test_leiden_basic(adata_neighbors):
-    sc.tl.leiden(adata_neighbors)
+@pytest.mark.parametrize("use_igraph", [True, False, False])
+@pytest.mark.parametrize("resolution", [1, 2])
+@pytest.mark.parametrize("n_iterations", [-1, 3])
+def test_leiden_basic(adata_neighbors, use_igraph, resolution, n_iterations):
+    sc.tl.leiden(
+        adata_neighbors,
+        use_igraph=use_igraph,
+        resolution=resolution,
+        n_iterations=n_iterations,
+    )
+    assert adata_neighbors.uns["leiden"]["params"]["resolution"] == resolution
+    assert adata_neighbors.uns["leiden"]["params"]["n_iterations"] == n_iterations
+
+
+def test_leiden_igraph_directed(adata_neighbors):
+    with pytest.raises(ValueError):
+        sc.tl.leiden(adata_neighbors, directed=True)
+
+
+@needs.leidenalg
+def test_leiden_equal_defaults(adata_neighbors):
+    """Ensure the two implementations are the same for the same args."""
+    leiden_alg_clustered = sc.tl.leiden(adata_neighbors, use_igraph=False, copy=True)
+    igraph_clustered = sc.tl.leiden(adata_neighbors, copy=True)
+    assert (
+        normalized_mutual_info_score(
+            leiden_alg_clustered.obs["leiden"], igraph_clustered.obs["leiden"]
+        )
+        > 0.9
+    )
+
+
+@needs.leidenalg
+def test_leiden_equal_old_defaults(adata_neighbors):
+    """Ensure that the old leidenalg defaults are close enough to the current default outputs."""
+    leiden_alg_clustered = sc.tl.leiden(
+        adata_neighbors, use_igraph=False, directed=True, n_iterations=-1, copy=True
+    )
+    igraph_clustered = sc.tl.leiden(adata_neighbors, copy=True)
+    assert (
+        normalized_mutual_info_score(
+            leiden_alg_clustered.obs["leiden"], igraph_clustered.obs["leiden"]
+        )
+        > 0.9
+    )
 
 
 @pytest.mark.parametrize(

scanpy/tools/_leiden.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import random
 from typing import TYPE_CHECKING
 
 import numpy as np
@@ -34,14 +35,15 @@ def leiden(
     random_state: _utils.AnyRandom = 0,
     key_added: str = "leiden",
     adjacency: sparse.spmatrix | None = None,
-    directed: bool = True,
+    directed: bool = False,
     use_weights: bool = True,
-    n_iterations: int = -1,
+    n_iterations: int = 2,
     partition_type: type[MutableVertexPartition] | None = None,
     neighbors_key: str | None = None,
     obsp: str | None = None,
     copy: bool = False,
-    **partition_kwargs,
+    use_igraph: bool = True,
+    **clustering_args,
 ) -> AnnData | None:
     """\
     Cluster cells into subgroups [Traag18]_.
@@ -96,9 +98,9 @@ def leiden(
         `obsp` and `neighbors_key` at the same time.
     copy
         Whether to copy `adata` or modify it inplace.
-    **partition_kwargs
-        Any further arguments to pass to `~leidenalg.find_partition`
-        (which in turn passes arguments to the `partition_type`).
+    **clustering_args
+        Any further arguments to pass to `~leidenalg.find_partition` (which in turn passes arguments to the `partition_type`)
+        or `community_detection` from `igraph`.
 
     Returns
     -------
@@ -112,13 +114,14 @@ def leiden(
         A dict with the values for the parameters `resolution`, `random_state`,
         and `n_iterations`.
     """
-    try:
-        import leidenalg
-    except ImportError:
-        raise ImportError(
-            "Please install the leiden algorithm: `conda install -c conda-forge leidenalg` or `pip3 install leidenalg`."
-        )
-    partition_kwargs = dict(partition_kwargs)
+    if not use_igraph:
+        try:
+            import leidenalg
+        except ImportError:
+            raise ImportError(
+                "Please install the leiden algorithm: `conda install -c conda-forge leidenalg` or `pip3 install leidenalg`."
+            )
+    clustering_args = dict(clustering_args)
 
     start = logg.info("running Leiden clustering")
     adata = adata.copy() if copy else adata
@@ -134,22 +137,38 @@ def leiden(
             adjacency=adjacency,
         )
     # convert it to igraph
+    if use_igraph and directed:
+        raise ValueError(
+            "Cannot use igraph's leiden implementaiton with a directed graph."
+        )
     g = _utils.get_igraph_from_adjacency(adjacency, directed=directed)
     # flip to the default partition type if not overriden by the user
-    if partition_type is None:
+    if partition_type is None and not use_igraph:
         partition_type = leidenalg.RBConfigurationVertexPartition
+    elif use_igraph and partition_type is not None:
+        raise ValueError("Do not pass in partition_type argument when using igraph.")
     # Prepare find_partition arguments as a dictionary,
     # appending to whatever the user provided. It needs to be this way
     # as this allows for the accounting of a None resolution
     # (in the case of a partition variant that doesn't take it on input)
     if use_weights:
-        partition_kwargs["weights"] = np.array(g.es["weight"]).astype(np.float64)
-    partition_kwargs["n_iterations"] = n_iterations
-    partition_kwargs["seed"] = random_state
+        clustering_args["weights"] = (
+            "weight" if use_igraph else np.array(g.es["weight"]).astype(np.float64)
+        )
+    clustering_args["n_iterations"] = n_iterations
+    if not use_igraph:
+        clustering_args["seed"] = random_state
+    else:
+        random.seed(random_state)
     if resolution is not None:
-        partition_kwargs["resolution_parameter"] = resolution
+        clustering_args[
+            f"resolution{'_parameter' if not use_igraph else ''}"
+        ] = resolution
     # clustering proper
-    part = leidenalg.find_partition(g, partition_type, **partition_kwargs)
+    if use_igraph:
+        part = g.community_leiden(objective_function="modularity", **clustering_args)
+    else:
+        part = leidenalg.find_partition(g, partition_type, **clustering_args)
     # store output into adata.obs
     groups = np.array(part.membership)
     if restrict_to is not None: