Draft PR: Add modularity and modularity_adata functions to scanpy.metrics

src/scanpy/metrics/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from ._gearys_c import gearys_c
-from ._metrics import confusion_matrix
+from ._metrics import confusion_matrix, modularity, modularity_adata
 from ._morans_i import morans_i
 
-__all__ = ["confusion_matrix", "gearys_c", "morans_i"]
+__all__ = ["confusion_matrix", "gearys_c", "modularity", "modularity_adata", "morans_i"]

src/scanpy/metrics/_metrics.py

@@ -4,11 +4,15 @@
 
 from typing import TYPE_CHECKING
 
+import igraph as ig
 import numpy as np
 import pandas as pd
+from anndata import AnnData
 from natsort import natsorted
 from pandas.api.types import CategoricalDtype
 
+from scanpy._compat import CSRBase
+
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
@@ -60,7 +64,9 @@ def confusion_matrix(
     orig, new = pd.Series(orig), pd.Series(new)
     assert len(orig) == len(new)
 
-    unique_labels = pd.unique(np.concatenate((orig.values, new.values)))
+    unique_labels = pd.unique(
+        np.concatenate((np.asarray(orig.values), np.asarray(new.values)))
+    )
 
     # Compute
     mtx = _confusion_matrix(orig, new, labels=unique_labels)
@@ -89,3 +95,61 @@ def confusion_matrix(
     df = df.loc[np.array(orig_idx), np.array(new_idx)]
 
     return df
+
+
+def modularity(connectivities, labels, mode="UNDIRECTED") -> float:
+    # default mode is undirected?? can be specified as directed or undirected
+    """Compute the modularity of a graph given its connectivities and labels.
+
+    Parameters
+    ----------
+    connectivities: array-like or sparse matrix
+        Weighted adjacency matrix representing the graph. Can be a dense NumPy array or a sparse CSR matrix.
+    labels: array-like or pandas.Series
+        Cluster labels for each node in the graph.
+    mode: str
+        The mode of the graph. Can be "UNDIRECTED" or "DIRECTED". Default is "UNDIRECTED".
+
+    Returns
+    -------
+    float
+        The modularity of the graph based on the provided clustering.
+    """
+    if isinstance(connectivities, CSRBase):
+        # Convert sparse matrix to dense format so that igraph can handle it
+        # Weighted_Adjacency expects with nested lists or numpy arrays and not sparse matrices
+        dense_connectivities = connectivities.toarray()
+    else:
+        dense_connectivities = connectivities
+    # creating igraph graph from the dense connectivity matrix
+    graph = ig.Graph.Weighted_Adjacency(dense_connectivities.tolist(), mode=mode)
+    if isinstance(labels, pd.Series):
+        labels = labels.values
+    # making sure labels are in the right format, i.e., a list of integers
+    labels = pd.Categorical(np.asarray(labels)).codes
+    return graph.modularity(labels)
+
+
+def modularity_adata(adata: AnnData, labels="leiden", obsp="connectivities") -> float:
+    """Compute modularity from an AnnData object using stored graph and clustering labels.
+
+    Parameters
+    ----------
+    adata: AnnData
+        The AnnData object containing the data.
+    labels: str or array-like
+        The key in adata.obs that contains the cluster labels.
+    obsp: str
+        The key in adata.obsp that contains the connectivities.
+
+    Returns
+    -------
+    float
+        The modularity of the graph based on the provided clustering.
+    """
+    # if user passes leiden or louvain as a string, this will get the actual labels
+    # from adata.obs
+    label_array = adata.obs[labels] if isinstance(labels, str) else labels
+    # extracting the connectivities from adata.obsp["connectivities"]
+    connectivities = adata.obsp[obsp]
+    return modularity(connectivities, label_array)