scikit-network 0.33.3__cp312-cp312-macosx_10_13_x86_64.whl

sknetwork/classification/vote.pyx

@@ -0,0 +1,56 @@
+# distutils: language = c++
+# cython: language_level=3
+"""
+Created in April 2020
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from libcpp.set cimport set
+from libcpp.vector cimport vector
+
+cimport cython
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def vote_update(int[:] indptr, int[:] indices, float[:] data, int[:] labels, int[:] index):
+    """One pass of label updates over the graph by majority vote among neighbors."""
+    cdef int i
+    cdef int ii
+    cdef int j
+    cdef int jj
+    cdef int n_indices = index.shape[0]
+    cdef int label
+    cdef int label_neigh_size
+    cdef float best_score
+
+    cdef vector[int] labels_neigh
+    cdef vector[float] votes_neigh, votes
+    cdef set[int] labels_unique = ()
+
+    cdef int n = labels.shape[0]
+    for i in range(n):
+        votes.push_back(0)
+
+    for ii in range(n_indices):
+        i = index[ii]
+        labels_neigh.clear()
+        for j in range(indptr[i], indptr[i + 1]):
+            jj = indices[j]
+            labels_neigh.push_back(labels[jj])
+            votes_neigh.push_back(data[jj])
+
+        labels_unique.clear()
+        label_neigh_size = labels_neigh.size()
+        for jj in range(label_neigh_size):
+            label = labels_neigh[jj]
+            if label >= 0:
+                labels_unique.insert(label)
+                votes[label] += votes_neigh[jj]
+
+        best_score = -1
+        for label in labels_unique:
+            if votes[label] > best_score:
+                labels[i] = label
+                best_score = votes[label]
+            votes[label] = 0
+    return labels

sknetwork/clustering/__init__.py

@@ -0,0 +1,8 @@
+"""clustering module"""
+from sknetwork.clustering.base import BaseClustering
+from sknetwork.clustering.louvain import Louvain
+from sknetwork.clustering.leiden import Leiden
+from sknetwork.clustering.propagation_clustering import PropagationClustering
+from sknetwork.clustering.metrics import get_modularity
+from sknetwork.clustering.postprocess import reindex_labels, aggregate_graph
+from sknetwork.clustering.kcenters import KCenters

sknetwork/clustering/base.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Nov, 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from abc import ABC
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.linalg.normalizer import normalize
+from sknetwork.base import Algorithm
+from sknetwork.utils.membership import get_membership
+
+
+class BaseClustering(Algorithm, ABC):
+    """Base class for clustering algorithms.
+
+    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.
+    """
+    def __init__(self, sort_clusters: bool = True, return_probs: bool = False, return_aggregate: bool = False):
+        self.sort_clusters = sort_clusters
+        self.return_probs = return_probs
+        self.return_aggregate = return_aggregate
+        self._init_vars()
+
+    def predict(self, columns=False) -> np.ndarray:
+        """Return the labels predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Labels.
+        """
+        if columns:
+            return self.labels_col_
+        return self.labels_
+
+    def fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to the data and return the labels. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Labels.
+        """
+        self.fit(*args, **kwargs)
+        return self.predict()
+
+    def predict_proba(self, columns=False) -> np.ndarray:
+        """Return the probability distribution over labels as predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        probs : np.ndarray
+            Probability distribution over labels.
+        """
+        if columns:
+            return self.probs_col_.toarray()
+        return self.probs_.toarray()
+
+    def fit_predict_proba(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to the data and return the probability distribution over labels.
+        Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        probs : np.ndarray
+            Probability of each label.
+        """
+        self.fit(*args, **kwargs)
+        return self.predict_proba()
+
+    def transform(self, columns=False) -> sparse.csr_matrix:
+        """Return the probability distribution over labels in sparse format.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        probs : sparse.csr_matrix
+            Probability distribution over labels.
+        """
+        if columns:
+            return self.probs_col_
+        return self.probs_
+
+    def fit_transform(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to the data and return the membership matrix. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        membership : np.ndarray
+            Membership matrix (distribution over clusters).
+        """
+        self.fit(*args, **kwargs)
+        return self.transform()
+
+    def _init_vars(self):
+        """Init variables."""
+        self.labels_ = None
+        self.labels_row_ = None
+        self.labels_col_ = None
+        self.probs_ = None
+        self.probs_row_ = None
+        self.probs_col_ = None
+        self.aggregate_ = None
+        self.bipartite = None
+        return self
+
+    def _split_vars(self, shape):
+        """Split labels_ into labels_row_ and labels_col_"""
+        n_row = shape[0]
+        self.labels_row_ = self.labels_[:n_row]
+        self.labels_col_ = self.labels_[n_row:]
+        self.labels_ = self.labels_row_
+        return self
+
+    def _secondary_outputs(self, input_matrix: sparse.csr_matrix):
+        """Compute different variables from labels_."""
+        if self.return_probs or self.return_aggregate:
+            input_matrix = input_matrix.astype(float)
+            if not self.bipartite:
+                probs = get_membership(self.labels_)
+                if self.return_probs:
+                    self.probs_ = normalize(input_matrix.dot(probs))
+                if self.return_aggregate:
+                    self.aggregate_ = sparse.csr_matrix(probs.T.dot(input_matrix.dot(probs)))
+            else:
+                if self.labels_col_ is None:
+                    n_labels = max(self.labels_) + 1
+                    probs_row = get_membership(self.labels_, n_labels=n_labels)
+                    probs_col = normalize(input_matrix.T.dot(probs_row))
+                else:
+                    n_labels = max(max(self.labels_row_), max(self.labels_col_)) + 1
+                    probs_row = get_membership(self.labels_row_, n_labels=n_labels)
+                    probs_col = get_membership(self.labels_col_, n_labels=n_labels)
+                if self.return_probs:
+                    self.probs_row_ = normalize(input_matrix.dot(probs_col))
+                    self.probs_col_ = normalize(input_matrix.T.dot(probs_row))
+                    self.probs_ = self.probs_row_
+                if self.return_aggregate:
+                    aggregate_ = sparse.csr_matrix(probs_row.T.dot(input_matrix))
+                    aggregate_ = aggregate_.dot(probs_col)
+                    self.aggregate_ = aggregate_
+
+        return self

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