scikit-network 0.33.0__cp312-cp312-macosx_11_0_arm64.whl

sknetwork/clustering/kcenters.py

@@ -0,0 +1,253 @@
+"""
+Created in March 2024
+@author: Laurène David <laurene.david@ip-paris.fr>
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+
+from typing import Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.clustering import BaseClustering
+from sknetwork.ranking import PageRank
+from sknetwork.clustering import get_modularity
+from sknetwork.classification.pagerank import PageRankClassifier
+from sknetwork.utils.format import get_adjacency, directed2undirected
+
+
+class KCenters(BaseClustering):
+    """K-center clustering algorithm. The center of each cluster is obtained by the PageRank algorithm.
+
+    Parameters
+    ----------
+    n_clusters : int
+        Number of clusters.
+    directed : bool, default False
+        If ``True``, the graph is considered directed.
+    center_position : str, default "row"
+        Force centers to correspond to the nodes on the rows or columns of the biadjacency matrix.
+        Can be ``row``, ``col`` or ``both``. Only considered for bipartite graphs.
+    n_init : int, default 5
+        Number of reruns of the k-centers algorithm with different centers.
+        The run that produce the best modularity is chosen as the final result.
+    max_iter : int, default 20
+        Maximum number of iterations of the k-centers algorithm for a single run.
+
+    Attributes
+    ----------
+    labels_ : np.ndarray, shape (n_nodes,)
+        Label of each node.
+    labels_row_, labels_col_ : np.ndarray
+        Labels of rows and columns, for bipartite graphs.
+    centers_ : np.ndarray, shape (n_nodes,)
+        Cluster centers.
+    centers_row_, centers_col_ : np.ndarray
+        Cluster centers of rows and columns, for bipartite graphs.
+
+    Example
+    -------
+    >>> from sknetwork.clustering import KCenters
+    >>> from sknetwork.data import karate_club
+    >>> kcenters = KCenters(n_clusters=2)
+    >>> adjacency = karate_club()
+    >>> labels = kcenters.fit_predict(adjacency)
+    >>> len(set(labels))
+    2
+
+    """
+    def __init__(self, n_clusters: int, directed: bool = False, center_position: str = "row", n_init: int = 5,
+                 max_iter: int = 20):
+        super(BaseClustering, self).__init__()
+        self.n_clusters = n_clusters
+        self.directed = directed
+        self.bipartite = None
+        self.center_position = center_position
+        self.n_init = n_init
+        self.max_iter = max_iter
+        self.labels_ = None
+        self.centers_ = None
+        self.centers_row_ = None
+        self.centers_col_ = None
+
+    def _compute_mask_centers(self, input_matrix: Union[sparse.csr_matrix, np.ndarray]):
+        """Generate mask to filter nodes that can be cluster centers.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+
+        Return
+        ------
+        mask : np.array, shape (n_nodes,)
+            Mask for possible cluster centers.
+
+        """
+        n_row, n_col = input_matrix.shape
+        if self.bipartite:
+            n_nodes = n_row + n_col
+            mask = np.zeros(n_nodes, dtype=bool)
+            if self.center_position == "row":
+                mask[:n_row] = True
+            elif self.center_position == "col":
+                mask[n_row:] = True
+            elif self.center_position == "both":
+                mask[:] = True
+            else:
+                raise ValueError('Unknown center position')
+        else:
+            mask = np.ones(n_row, dtype=bool)
+
+        return mask
+
+    @staticmethod
+    def _init_centers(adjacency: Union[sparse.csr_matrix, np.ndarray], mask: np.ndarray, n_clusters: int):
+        """
+        Kcenters++ initialization to select cluster centers.
+        This algorithm is an adaptation of the Kmeans++ algorithm to graphs.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency matrix of the graph.
+        mask :
+            Initial mask for allowed positions of centers.
+        n_clusters : int
+            Number of centers to initialize.
+
+        Returns
+        ---------
+        centers : np.array, shape (n_clusters,)
+            Initial cluster centers.
+        """
+        mask = mask.copy()
+        n_nodes = adjacency.shape[0]
+        nodes = np.arange(n_nodes)
+        centers = []
+
+        # Choose the first center uniformly at random
+        center = np.random.choice(nodes[mask])
+        mask[center] = 0
+        centers.append(center)
+
+        pagerank = PageRank()
+        weights = {center: 1}
+
+        for k in range(n_clusters - 1):
+            # select nodes that are far from existing centers
+            ppr_scores = pagerank.fit_predict(adjacency, weights)
+            ppr_scores = ppr_scores[mask]
+
+            if min(ppr_scores) == 0:
+                center = np.random.choice(nodes[mask][ppr_scores == 0])
+            else:
+                probs = 1 / ppr_scores
+                probs = probs / np.sum(probs)
+                center = np.random.choice(nodes[mask], p=probs)
+
+            mask[center] = 0
+            centers.append(center)
+            weights.update({center: 1})
+
+        centers = np.array(centers)
+        return centers
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) -> "KCenters":
+        """Compute the clustering of the graph by k-centers.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix even if square.
+
+        Returns
+        -------
+        self : :class:`KCenters`
+        """
+
+        if self.n_clusters < 2:
+            raise ValueError("The number of clusters must be at least 2.")
+
+        if self.n_init < 1:
+            raise ValueError("The n_init parameter must be at least 1.")
+
+        if self.directed:
+            input_matrix = directed2undirected(input_matrix)
+
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_bipartite=force_bipartite)
+        n_row = input_matrix.shape[0]
+        n_nodes = adjacency.shape[0]
+        nodes = np.arange(n_nodes)
+
+        mask = self._compute_mask_centers(input_matrix)
+        if self.n_clusters > np.sum(mask):
+            raise ValueError("The number of clusters is to high. This might be due to the center_position parameter.")
+
+        pagerank_clf = PageRankClassifier()
+        pagerank = PageRank()
+
+        labels_ = []
+        centers_ = []
+        modularity_ = []
+
+        # Restarts
+        for i in range(self.n_init):
+
+            # Initialization
+            centers = self._init_centers(adjacency, mask, self.n_clusters)
+            prev_centers = None
+            labels = None
+            n_iter = 0
+
+            while not np.equal(prev_centers, centers).all() and (n_iter < self.max_iter):
+
+                # Assign nodes to centers
+                labels_center = {center: label for label, center in enumerate(centers)}
+                labels = pagerank_clf.fit_predict(adjacency, labels_center)
+
+                # Find new centers
+                prev_centers = centers.copy()
+                new_centers = []
+
+                for label in np.unique(labels):
+                    mask_cluster = labels == label
+                    mask_cluster &= mask
+                    scores = pagerank.fit_predict(adjacency, weights=mask_cluster)
+                    scores[~mask_cluster] = 0
+                    new_centers.append(nodes[np.argmax(scores)])
+
+                n_iter += 1
+
+            # Store results
+            if self.bipartite:
+                labels_row = labels[:n_row]
+                labels_col = labels[n_row:]
+                modularity = get_modularity(input_matrix, labels_row, labels_col)
+            else:
+                modularity = get_modularity(adjacency, labels)
+
+            labels_.append(labels)
+            centers_.append(centers)
+            modularity_.append(modularity)
+
+        # Select restart with the highest modularity
+        idx_max = np.argmax(modularity_)
+        self.labels_ = np.array(labels_[idx_max])
+        self.centers_ = np.array(centers_[idx_max])
+
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+
+            # Define centers based on center position
+            if self.center_position == "row":
+                self.centers_row_ = self.centers_
+            elif self.center_position == "col":
+                self.centers_col_ = self.centers_ - n_row
+            else:
+                self.centers_row_ = self.centers_[self.centers_ < n_row]
+                self.centers_col_ = self.centers_[~np.isin(self.centers_, self.centers_row_)] - n_row
+
+        return self

sknetwork/clustering/leiden.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2024
+@author: Thomas Bonald <bonald@enst.fr>
+@author: Ahmed Zaiou <ahmed.zaiou@capgemini.com>
+"""
+from typing import Union, Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.clustering import Louvain
+from sknetwork.clustering.louvain_core import optimize_core
+from sknetwork.clustering.leiden_core import optimize_refine_core
+from sknetwork.utils.membership import get_membership
+from sknetwork.utils.check import check_random_state
+from sknetwork.log import Log
+
+
+class Leiden(Louvain):
+    """Leiden algorithm for clustering graphs by maximization of modularity.
+    Compared to the Louvain algorithm, the partition is refined before each aggregation.
+
+    For bipartite graphs, the algorithm maximizes Barber's modularity by default.
+
+    Parameters
+    ----------
+    resolution :
+        Resolution parameter.
+    modularity : str
+        Type of modularity to maximize. Can be ``'Dugue'``, ``'Newman'`` or ``'Potts'`` (default = ``'dugue'``).
+    tol_optimization :
+        Minimum increase in modularity to enter a new optimization pass in the local search.
+    tol_aggregation :
+        Minimum increase in modularity to enter a new aggregation pass.
+    n_aggregations :
+        Maximum number of aggregations.
+        A negative value is interpreted as no limit.
+    shuffle_nodes :
+        Enables node shuffling before optimization.
+    sort_clusters :
+        If ``True``, sort labels in decreasing order of cluster size.
+    return_probs :
+        If ``True``, return the probability distribution over clusters (soft clustering).
+    return_aggregate :
+        If ``True``, return the adjacency matrix of the graph between clusters.
+    random_state :
+        Random number generator or random seed. If None, numpy.random is used.
+    verbose :
+        Verbose mode.
+
+    Attributes
+    ----------
+    labels_ : np.ndarray, shape (n_labels,)
+        Label of each node.
+    probs_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distribution over labels.
+    labels_row_, labels_col_ : np.ndarray
+        Labels of rows and columns, for bipartite graphs.
+    probs_row_, probs_col_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distributions over labels for rows and columns (for bipartite graphs).
+    aggregate_ : sparse.csr_matrix
+        Aggregate adjacency matrix or biadjacency matrix between clusters.
+
+    Example
+    -------
+    >>> from sknetwork.clustering import Leiden
+    >>> from sknetwork.data import karate_club
+    >>> leiden = Leiden()
+    >>> adjacency = karate_club()
+    >>> labels = leiden.fit_predict(adjacency)
+    >>> len(set(labels))
+    4
+
+    References
+    ----------
+    * Traag, V. A., Waltman, L., & Van Eck, N. J. (2019).
+      `From Louvain to Leiden: guaranteeing well-connected communities`, Scientific reports.
+
+    """
+
+    def __init__(self, resolution: float = 1, modularity: str = 'dugue', tol_optimization: float = 1e-3,
+                 tol_aggregation: float = 1e-3, n_aggregations: int = -1, shuffle_nodes: bool = False,
+                 sort_clusters: bool = True, return_probs: bool = True, return_aggregate: bool = True,
+                 random_state: Optional[Union[np.random.RandomState, int]] = None, verbose: bool = False):
+        super(Leiden, self).__init__(sort_clusters=sort_clusters, return_probs=return_probs,
+                                     return_aggregate=return_aggregate)
+        Log.__init__(self, verbose)
+
+        self.labels_ = None
+        self.resolution = resolution
+        self.modularity = modularity.lower()
+        self.tol_optimization = tol_optimization
+        self.tol_aggregation = tol_aggregation
+        self.n_aggregations = n_aggregations
+        self.shuffle_nodes = shuffle_nodes
+        self.random_state = check_random_state(random_state)
+        self.bipartite = None
+
+    def _optimize(self, labels, adjacency, out_weights, in_weights):
+        """One optimization pass of the Leiden algorithm.
+
+        Parameters
+        ----------
+        labels :
+            Labels of nodes.
+        adjacency :
+            Adjacency matrix.
+        out_weights :
+            Out-weights of nodes.
+        in_weights :
+            In-weights of nodes
+
+        Returns
+        -------
+        labels :
+            Labels of nodes after optimization.
+        increase :
+            Gain in modularity after optimization.
+        """
+        indices = adjacency.indices
+        indptr = adjacency.indptr
+        data = adjacency.data.astype(np.float32)
+        out_weights = out_weights.astype(np.float32)
+        in_weights = in_weights.astype(np.float32)
+        membership = get_membership(labels)
+        out_cluster_weights = membership.T.dot(out_weights)
+        in_cluster_weights = membership.T.dot(in_weights)
+        cluster_weights = np.zeros_like(out_cluster_weights).astype(np.float32)
+        labels = labels.astype(np.int32)
+        self_loops = adjacency.diagonal().astype(np.float32)
+        return optimize_core(labels, indices, indptr, data, out_weights, in_weights, out_cluster_weights,
+                             in_cluster_weights, cluster_weights, self_loops, self.resolution, self.tol_optimization)
+
+    def _optimize_refine(self, labels, labels_refined, adjacency, out_weights, in_weights):
+        """Get the refined partition optimizing modularity.
+
+        Parameters
+        ----------
+        labels :
+            Labels of nodes.
+        labels_refined :
+            Refined labels of nodes.
+        adjacency :
+            Adjacency matrix.
+        out_weights :
+            Out-weights of nodes.
+        in_weights :
+            In-weights of nodes
+
+        Returns
+        -------
+        labels_refined :
+            Refined labels of nodes.
+        """
+        indices = adjacency.indices
+        indptr = adjacency.indptr
+        data = adjacency.data.astype(np.float32)
+        out_weights = out_weights.astype(np.float32)
+        in_weights = in_weights.astype(np.float32)
+        membership = get_membership(labels_refined)
+        out_cluster_weights = membership.T.dot(out_weights)
+        in_cluster_weights = membership.T.dot(in_weights)
+        cluster_weights = np.zeros_like(out_cluster_weights).astype(np.float32)
+        self_loops = adjacency.diagonal().astype(np.float32)
+        labels = labels.astype(np.int32)
+        labels_refined = labels_refined.astype(np.int32)
+        return optimize_refine_core(labels, labels_refined, indices, indptr, data, out_weights, in_weights,
+                                    out_cluster_weights, in_cluster_weights, cluster_weights, self_loops,
+                                    self.resolution)
+
+    @staticmethod
+    def _aggregate_refine(labels, labels_refined, adjacency, out_weights, in_weights):
+        """Aggregate nodes according to refined labels.
+
+        Parameters
+        ----------
+        labels :
+            Labels of nodes.
+        labels_refined :
+            Refined labels of nodes.
+        adjacency :
+            Adjacency matrix.
+        out_weights :
+            Out-weights of nodes.
+        in_weights :
+            In-weights of nodes.
+
+        Returns
+        -------
+        Aggregate graph (labels, adjacency matrix, out-weights, in-weights).
+        """
+        membership = get_membership(labels)
+        membership_refined = get_membership(labels_refined)
+        adjacency_ = membership_refined.T.tocsr().dot(adjacency.dot(membership_refined))
+        out_weights_ = membership_refined.T.dot(out_weights)
+        in_weights_ = membership_refined.T.dot(in_weights)
+        labels_ = membership_refined.T.tocsr().dot(membership).indices
+        return labels_, adjacency_, out_weights_, in_weights_
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) -> 'Leiden':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix even if square.
+
+        Returns
+        -------
+        self : :class:`Leiden`
+        """
+        adjacency, out_weights, in_weights, membership, index = self._pre_processing(input_matrix, force_bipartite)
+        n = adjacency.shape[0]
+        labels = np.arange(n)
+        count = 0
+        stop = False
+        while not stop:
+            count += 1
+            labels, increase = self._optimize(labels, adjacency, out_weights, in_weights)
+            _, labels = np.unique(labels, return_inverse=True)
+            labels_original = labels.copy()
+            labels_refined = np.arange(len(labels))
+            labels_refined = self._optimize_refine(labels, labels_refined, adjacency, out_weights, in_weights)
+            _, labels_refined = np.unique(labels_refined, return_inverse=True)
+            labels, adjacency, out_weights, in_weights = self._aggregate_refine(labels, labels_refined, adjacency,
+                                                                                out_weights, in_weights)
+            n = adjacency.shape[0]
+            stop = n == 1
+            stop |= increase <= self.tol_aggregation
+            stop |= count == self.n_aggregations
+            if stop:
+                membership = membership.dot(get_membership(labels_original))
+            else:
+                membership = membership.dot(get_membership(labels_refined))
+            self.print_log("Aggregation:", count, " Clusters:", n, " Increase:", increase)
+
+        self._post_processing(input_matrix, membership, index)
+        return self

sknetwork/clustering/leiden_core.pyx

@@ -0,0 +1,124 @@
+# distutils: language=c++
+# cython: language_level=3
+from libcpp.set cimport set
+from libc.stdlib cimport rand
+
+cimport cython
+
+ctypedef fused int_or_long:
+    int
+    long
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def optimize_refine_core(int_or_long[:] labels, int_or_long[:] labels_refined, int_or_long[:] indices,
+    int_or_long[:] indptr, float[:] data, float[:] out_weights, float[:] in_weights, float[:] out_cluster_weights,
+    float[:] in_cluster_weights, float[:] cluster_weights, float[:] self_loops, float resolution):  # pragma: no cover
+    """Refine clusters while maximizing modularity.
+
+    Parameters
+    ----------
+    labels :
+        Labels (initial partition).
+    labels_refined :
+        Refined labels.
+    indices :
+        CSR format index array of the normalized adjacency matrix.
+    indptr :
+        CSR format index pointer array of the normalized adjacency matrix.
+    data :
+        CSR format data array of the normalized adjacency matrix.
+    out_weights :
+        Out-weights of nodes (sum to 1).
+    in_weights :
+        In-weights of nodes (sum to 1).
+    out_cluster_weights :
+        Out-weights of clusters (sum to 1).
+    in_cluster_weights :
+        In-weights of clusters (sum to 1).
+    cluster_weights :
+        Weights of clusters (initialized to 0).
+    self_loops :
+        Weights of self loops.
+    resolution :
+        Resolution parameter (positive).
+
+    Returns
+    -------
+    labels_refined :
+        Refined labels.
+    """
+    cdef int_or_long n
+    cdef int_or_long label
+    cdef int_or_long label_refined
+    cdef int_or_long label_target
+    cdef int_or_long label_best
+    cdef int_or_long i
+    cdef int_or_long j
+    cdef int_or_long start
+    cdef int_or_long end
+
+    cdef float increase = 1
+    cdef float delta
+    cdef float delta_local
+    cdef float delta_best
+    cdef float in_weight
+    cdef float out_weight
+
+    cdef set[int_or_long] label_set
+    cdef set[int_or_long] label_target_set
+
+    n = labels.shape[0]
+    while increase:
+        increase = 0
+
+        for i in range(n):
+            label_set = ()
+            label = labels[i]
+            label_refined = labels_refined[i]
+            start = indptr[i]
+            end = indptr[i+1]
+
+            # neighboring clusters
+            for j in range(start, end):
+                if labels[indices[j]] == label:
+                    label_target = labels_refined[indices[j]]
+                    label_set.insert(label_target)
+                    cluster_weights[label_target] += data[j]
+            label_set.erase(label_refined)
+
+            if not label_set.empty():
+                out_weight = out_weights[i]
+                in_weight = in_weights[i]
+
+                # node leaving the current cluster
+                delta = 2 * (cluster_weights[label_refined] - self_loops[i])
+                delta -= resolution * out_weight * (in_cluster_weights[label_refined] - in_weight)
+                delta -= resolution * in_weight * (out_cluster_weights[label_refined] - out_weight)
+
+                label_target_set = ()
+                for label_target in label_set:
+                    delta_local = 2 * cluster_weights[label_target]
+                    delta_local -= resolution * out_weight * in_cluster_weights[label_target]
+                    delta_local -= resolution * in_weight * out_cluster_weights[label_target]
+                    delta_local -= delta
+                    if delta_local > 0:
+                        label_target_set.insert(label_target)
+                    cluster_weights[label_target] = 0
+
+                if not label_target_set.empty():
+                    increase = 1
+                    k = rand() % label_target_set.size()
+                    for label_target in label_target_set:
+                        k -= 1
+                        if k == 0:
+                            break
+                    labels_refined[i] = label_target
+                    # update weights
+                    out_cluster_weights[label_refined] -= out_weight
+                    in_cluster_weights[label_refined] -= in_weight
+                    out_cluster_weights[label_target] += out_weight
+                    in_cluster_weights[label_target] += in_weight
+            cluster_weights[label_refined] = 0
+
+    return labels_refined