feat: support for directed graphs with igraph Leiden clustering (#4490)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: maltekuehl

docs/release-notes/4490.feat.md

@@ -0,0 +1 @@
+Allow `directed=True` with `flavor="igraph"` in {func}`~scanpy.tl.leiden`, and default to it with {attr}`~scanpy.Preset.ScanpyV2Preview`; the `leiden` extra now requires `igraph>=1` and `leidenalg>=0.11` {smaller}`M Kuehl`

pyproject.toml

@@ -87,7 +87,7 @@ bbknn = [ "bbknn" ]
 dask = [ "anndata[dask]", "dask[array]>=2024.10" ]
 # PCA acceleration
 dask-ml = [ "dask-ml", "scanpy[dask]" ]
-leiden = [ "igraph>=0.10.8", "leidenalg>=0.10.1" ]
+leiden = [ "igraph>=1", "leidenalg>=0.11" ]
 louvain = [ "igraph", "louvain>=0.8.2", "setuptools" ]
 magic = [ "magic-impute>=2.0.4" ]
 paga = [ "igraph" ]
@@ -101,7 +101,7 @@ scanpy2 = [
     "anndata>=0.13.3",
     "holoviews>=1.23.2",
     "hv-anndata>=0.0.3a5",
-    "igraph>=0.10.8",
+    "igraph>=1",
     "matplotlib>=3.11",
     "scanpy[illico]",
     "scikit-misc>=0.5.1",

src/scanpy/_settings/presets.py

@@ -113,6 +113,7 @@ class ScoreGenesPreset(NamedTuple):
 
 class LeidenPreset(NamedTuple):
     flavor: LeidenFlavor
+    directed: bool | None
 
 
 preset_postprocessors: list[Callable[[], None]] = []
@@ -289,10 +290,10 @@ def score_genes() -> Mapping[Preset, ScoreGenesPreset]:
 
     @preset_property
     def leiden() -> Mapping[Preset, LeidenPreset]:
-        """Flavor for :func:`~scanpy.tl.leiden`."""
+        """Settings for :func:`~scanpy.tl.leiden`."""  # noqa: D401
         return {
-            Preset.ScanpyV1: LeidenPreset(flavor="leidenalg"),
-            Preset.ScanpyV2Preview: LeidenPreset(flavor="igraph"),
+            Preset.ScanpyV1: LeidenPreset(flavor="leidenalg", directed=None),
+            Preset.ScanpyV2Preview: LeidenPreset(flavor="igraph", directed=True),
         }
 
     @contextmanager

src/scanpy/tools/_leiden.py

@@ -19,6 +19,7 @@
     doc_rng,
 )
 from .._settings import Default
+from .._settings.presets import LeidenPreset
 from .._utils import _doc_params
 from .._utils.random import _accepts_legacy_random_state, _LegacyRng, _set_igraph_rng
 from ..get._out import _out_key, deprecated_copy
@@ -35,9 +36,9 @@
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from typing import Literal
 
     from anndata import AnnData
+    from igraph import Graph
 
     from .._compat import CSBase
     from .._settings.presets import LeidenFlavor
@@ -85,7 +86,7 @@ def leiden(  # noqa: PLR0913
     *,
     restrict_to: tuple[str, Sequence[str]] | None = None,
     rng: SeedLike | RNGLike | None = None,
-    directed: bool | None = None,
+    directed: bool | Default | None = Default(preset=("leiden", "directed")),
     use_weights: bool = True,
     n_iterations: int = -1,
     partition_type: type[MutableVertexPartition] | None = None,
@@ -123,6 +124,7 @@ def leiden(  # noqa: PLR0913
     {restrict_to}
     directed
         Whether to treat the graph as directed or undirected.
+        `None` means directed for `flavor='leidenalg'` and undirected for `flavor='igraph'`.
     use_weights
         If `True`, edge weights from the graph are used in the computation
         (placing more emphasis on stronger edges).
@@ -169,7 +171,9 @@ def leiden(  # noqa: PLR0913
         to calculate a score independent of `flavor`.
 
     """
-    flavor = _validate_flavor(flavor, partition_type=partition_type, directed=directed)
+    flavor, directed = _validate_flavor(
+        flavor, partition_type=partition_type, directed=directed
+    )
     _utils.ensure_igraph()
     clustering_args = dict(clustering_args)
     rng = np.random.default_rng(rng)
@@ -205,7 +209,6 @@ def leiden(  # noqa: PLR0913
 
         if resolution is not None:
             clustering_args["resolution_parameter"] = resolution
-        directed = True if directed is None else directed
         g = _utils.get_igraph_from_adjacency(adjacency, directed=directed)
         if partition_type is None:
             partition_type = leidenalg.RBConfigurationVertexPartition
@@ -222,12 +225,20 @@ def leiden(  # noqa: PLR0913
             leidenalg.find_partition(g, partition_type, seed=seed, **clustering_args),
         )
     else:
-        g = _utils.get_igraph_from_adjacency(adjacency, directed=False)
+        g = _utils.get_igraph_from_adjacency(adjacency, directed=directed)
         if use_weights:
             clustering_args["weights"] = "weight"
         if resolution is not None:
             clustering_args["resolution"] = resolution
         clustering_args.setdefault("objective_function", "modularity")
+        if (
+            directed
+            and clustering_args["objective_function"] == "modularity"
+            and clustering_args.keys().isdisjoint({"node_weights", "node_in_weights"})
+        ):
+            clustering_args |= _directed_node_weights(
+                g, weights=clustering_args.get("weights")
+            )
         with _set_igraph_rng(rng):
             part = g.community_leiden(**clustering_args)
     # store output into adata.obs
@@ -265,18 +276,30 @@ def leiden(  # noqa: PLR0913
     return None
 
 
+def _directed_node_weights(
+    g: Graph, *, weights: str | Sequence[float] | None
+) -> dict[str, list[float]]:
+    """Get in- and out-degrees as node weights; python-igraph otherwise only counts out-degrees."""
+    return dict(
+        node_weights=g.strength(mode="out", weights=weights),
+        node_in_weights=g.strength(mode="in", weights=weights),
+    )
+
+
 def _validate_flavor(
-    flavor: str | None, *, partition_type: object | None, directed: bool | None
-) -> Literal["igraph", "leidenalg"]:
-    if was_default := (flavor is None or isinstance(flavor, Default)):
-        from scanpy import settings
+    flavor: str | None,
+    *,
+    partition_type: object | None,
+    directed: bool | Default | None,
+) -> LeidenPreset:
+    from scanpy import settings
 
+    if was_default := (flavor is None or isinstance(flavor, Default)):
         flavor = settings.preset.leiden.flavor
+    if isinstance(directed, Default):
+        directed = settings.preset.leiden.directed
     match flavor:
         case "igraph":
-            if directed:
-                msg = "Cannot use igraph’s leiden implementation with a directed graph."
-                raise ValueError(msg)
             if partition_type is not None:
                 msg = "Do not pass in partition_type argument when using igraph."
                 raise ValueError(msg)
@@ -288,8 +311,7 @@ def _validate_flavor(
             if was_default:
                 msg += (
                     "\nIn the future, the default backend for leiden will be igraph instead of leidenalg. "
-                    "To achieve the future defaults please pass: `flavor='igraph'` and `n_iterations=2`. "
-                    "`directed` must also be `False` to work with igraph’s implementation."
+                    "To achieve the future defaults please pass: `flavor='igraph'` and `n_iterations=2`."
                 )
             warn(msg, FutureWarning if was_default else UserWarning)
             try:
@@ -302,4 +324,6 @@ def _validate_flavor(
         case _:
             msg = f"flavor must be either 'igraph' or 'leidenalg', but {flavor!r} was passed."
             raise ValueError(msg)
-    return flavor
+    if directed is None:
+        directed = flavor == "leidenalg"
+    return LeidenPreset(flavor, directed)

tests/test_clustering.py

@@ -4,8 +4,10 @@
 from functools import partial
 from typing import TYPE_CHECKING
 
+import numpy as np
 import pandas as pd
 import pytest
+from anndata import AnnData
 from sklearn.metrics.cluster import normalized_mutual_info_score
 
 import scanpy as sc
@@ -15,8 +17,6 @@
 if TYPE_CHECKING:
     from typing import Literal
 
-    from anndata import AnnData
-
 
 @pytest.fixture
 def adata_neighbors() -> AnnData:
@@ -105,10 +105,27 @@ def test_leiden_random_state(
         )
 
 
+@needs.anndata_acc
 @needs.igraph
-def test_leiden_igraph_directed(adata_neighbors):
-    with pytest.raises(ValueError, match=r"Cannot use igraph’s leiden.*directed"):
-        sc.tl.leiden(adata_neighbors, flavor="igraph", directed=True)
+@needs.leidenalg
+def test_leiden_igraph_directed():
+    from anndata.acc import A
+
+    graph = np.array([
+        [0, 0, 0, 3, 0, 0, 0, 2],
+        [0, 0, 1, 0, 0, 0, 3, 0],
+        [2, 0, 0, 1, 2, 0, 1, 2],
+        [0, 0, 0, 0, 0, 0, 0, 0],
+        [0, 0, 0, 1, 0, 0, 0, 0],
+        [0, 0, 0, 1, 0, 0, 0, 0],
+        [0, 0, 1, 1, 0, 1, 0, 0],
+        [1, 0, 0, 0, 0, 0, 1, 0],
+    ])
+    adata = AnnData(np.zeros((8, 1)), obsp=dict(graph=graph))
+    kw = dict(use=A.obsp["graph"], directed=True, out=True)
+    igraph = sc.tl.leiden(adata, flavor="igraph", **kw)
+    leidenalg = sc.tl.leiden(adata, flavor="leidenalg", **kw)
+    assert normalized_mutual_info_score(igraph, leidenalg) == 1
 
 
 @needs.igraph