scikit-network 0.33.0__cp312-cp312-macosx_11_0_arm64.whl

sknetwork/clustering/louvain.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in November 2018
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Quentin Lutz <qlutz@enst.fr>
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Union, Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.clustering.base import BaseClustering
+from sknetwork.clustering.louvain_core import optimize_core
+from sknetwork.clustering.postprocess import reindex_labels
+from sknetwork.utils.check import check_random_state, get_probs
+from sknetwork.utils.format import check_format, get_adjacency, directed2undirected
+from sknetwork.utils.membership import get_membership
+from sknetwork.log import Log
+
+
+class Louvain(BaseClustering, Log):
+    """Louvain algorithm for clustering graphs by maximization of modularity.
+
+    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 Louvain
+    >>> from sknetwork.data import karate_club
+    >>> louvain = Louvain()
+    >>> adjacency = karate_club()
+    >>> labels = louvain.fit_predict(adjacency)
+    >>> len(set(labels))
+    4
+
+    References
+    ----------
+    * Blondel, V. D., Guillaume, J. L., Lambiotte, R., & Lefebvre, E. (2008).
+      `Fast unfolding of communities in large networks.
+      <https://arxiv.org/abs/0803.0476>`_
+      Journal of statistical mechanics: theory and experiment, 2008.
+
+    * Dugué, N., & Perez, A. (2015).
+      `Directed Louvain: maximizing modularity in directed networks
+      <https://hal.archives-ouvertes.fr/hal-01231784/document>`_
+      (Doctoral dissertation, Université d'Orléans).
+
+    * Barber, M. J. (2007).
+      `Modularity and community detection in bipartite networks
+      <https://arxiv.org/pdf/0707.1616>`_
+      Physical Review E, 76(6).
+    """
+
+    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(Louvain, 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 Louvain 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.
+        """
+        labels = labels.astype(np.int64)
+        indices = adjacency.indices.astype(np.int64)
+        indptr = adjacency.indptr.astype(np.int64)
+        data = adjacency.data.astype(np.float32)
+        out_weights = out_weights.astype(np.float32)
+        in_weights = in_weights.astype(np.float32)
+        out_cluster_weights = out_weights.copy()
+        in_cluster_weights = in_weights.copy()
+        cluster_weights = np.zeros_like(out_cluster_weights).astype(np.float32)
+        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)
+
+    @staticmethod
+    def _aggregate(labels, adjacency, out_weights, in_weights):
+        """Aggregate nodes belonging to the same cluster.
+
+        Parameters
+        ----------
+        labels :
+            Labels of nodes.
+        adjacency :
+            Adjacency matrix.
+        out_weights :
+            Out-weights of nodes.
+        in_weights :
+            In-weights of nodes.
+
+        Returns
+        -------
+        Aggregate graph (adjacency matrix, out-weights, in-weights).
+        """
+        membership = get_membership(labels)
+        adjacency_ = membership.T.tocsr().dot(adjacency.dot(membership))
+        out_weights_ = membership.T.dot(out_weights)
+        in_weights_ = membership.T.dot(in_weights)
+        return adjacency_, out_weights_, in_weights_
+
+    def _pre_processing(self, input_matrix, force_bipartite):
+        """Pre-processing for Louvain.
+
+         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
+        -------
+        adjacency :
+            Adjacency matrix.
+        out_weights, in_weights :
+            Node weights.
+        membership :
+            Membership matrix (labels).
+        index :
+            Index of nodes.
+        """
+        self._init_vars()
+
+        # adjacency matrix
+        input_matrix = check_format(input_matrix)
+        force_directed = self.modularity == 'dugue'
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_directed=force_directed,
+                                                  force_bipartite=force_bipartite)
+
+        # shuffling
+        n = adjacency.shape[0]
+        index = np.arange(n)
+        if self.shuffle_nodes:
+            index = self.random_state.permutation(index)
+            adjacency = adjacency[index][:, index]
+
+        # node weights
+        if self.modularity == 'potts':
+            out_weights = get_probs('uniform', adjacency)
+            in_weights = out_weights.copy()
+        elif self.modularity == 'newman':
+            out_weights = get_probs('degree', adjacency)
+            in_weights = out_weights.copy()
+        elif self.modularity == 'dugue':
+            out_weights = get_probs('degree', adjacency)
+            in_weights = get_probs('degree', adjacency.T)
+        else:
+            raise ValueError('Unknown modularity function.')
+
+        # normalized, symmetric adjacency matrix (sums to 1)
+        adjacency = directed2undirected(adjacency)
+        adjacency = adjacency / adjacency.data.sum()
+
+        # cluster membership
+        membership = sparse.identity(n, format='csr')
+
+        return adjacency, out_weights, in_weights, membership, index
+
+    def _post_processing(self, input_matrix, membership, index):
+        """Post-processing for Louvain.
+
+         Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        membership :
+            Membership matrix (labels).
+        index :
+            Index of nodes.
+        """
+        if self.sort_clusters:
+            labels = reindex_labels(membership.indices)
+        else:
+            labels = membership.indices
+        if self.shuffle_nodes:
+            reverse = np.empty(index.size, index.dtype)
+            reverse[index] = np.arange(index.size)
+            labels = labels[reverse]
+        self.labels_ = labels
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        self._secondary_outputs(input_matrix)
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) -> 'Louvain':
+        """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:`Louvain`
+        """
+        adjacency, out_weights, in_weights, membership, index = self._pre_processing(input_matrix, force_bipartite)
+        n = adjacency.shape[0]
+        count = 0
+        stop = False
+        while not stop:
+            count += 1
+            labels = np.arange(n)
+            labels, increase = self._optimize(labels, adjacency, out_weights, in_weights)
+            _, labels = np.unique(labels, return_inverse=True)
+            adjacency, out_weights, in_weights = self._aggregate(labels, adjacency, out_weights, in_weights)
+            membership = membership.dot(get_membership(labels))
+            n = adjacency.shape[0]
+            stop = n == 1
+            stop |= increase <= self.tol_aggregation
+            stop |= count == self.n_aggregations
+            self.print_log("Aggregation:", count, " Clusters:", n, " Increase:", increase)
+        self._post_processing(input_matrix, membership, index)
+        return self

sknetwork/clustering/louvain_core.pyx

@@ -0,0 +1,124 @@
+# distutils: language=c++
+# cython: language_level=3
+from libcpp.set cimport set
+cimport cython
+
+ctypedef fused int_or_long:
+    int
+    long
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def optimize_core(int_or_long[:] labels, 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, float tol_optimization):  # pragma: no cover
+    """Find clusters maximizing modularity.
+
+    Parameters
+    ----------
+    labels :
+        Initial 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).
+    tol_optimization :
+        Minimum increase in modularity to enter a new optimization pass.
+
+    Returns
+    -------
+    labels :
+        Labels of nodes.
+    increase :
+        Increase in modularity.
+    """
+    cdef int_or_long n
+    cdef int_or_long stop = 0
+    cdef int_or_long label
+    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 = 0
+    cdef float increase_pass
+    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 = ()
+
+    n = labels.shape[0]
+    while not stop:
+        increase_pass = 0
+
+        for i in range(n):
+            label_set.clear()
+            label = labels[i]
+            start = indptr[i]
+            end = indptr[i+1]
+
+            # neighboring clusters
+            for j in range(start, end):
+                label_target = labels[indices[j]]
+                label_set.insert(label_target)
+                cluster_weights[label_target] += data[j]
+            label_set.erase(label)
+
+            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] - self_loops[i])
+                delta -= resolution * out_weight * (in_cluster_weights[label] - in_weight)
+                delta -= resolution * in_weight * (out_cluster_weights[label] - out_weight)
+
+                delta_best = 0
+                label_best = label
+
+                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 > delta_best:
+                        delta_best = delta_local
+                        label_best = label_target
+                    cluster_weights[label_target] = 0
+
+                if label_best != label:
+                    increase_pass += delta_best
+                    labels[i] = label_best
+                    # update weights
+                    out_cluster_weights[label] -= out_weight
+                    in_cluster_weights[label] -= in_weight
+                    out_cluster_weights[label_best] += out_weight
+                    in_cluster_weights[label_best] += in_weight
+
+            cluster_weights[label] = 0
+
+        increase += increase_pass
+        stop = increase_pass <= tol_optimization
+
+    return labels, increase

sknetwork/clustering/metrics.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in July 2018
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Optional, Union, Tuple
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.utils.check import get_probs
+from sknetwork.utils.format import get_adjacency
+from sknetwork.utils.membership import get_membership
+
+
+def get_modularity(input_matrix: Union[sparse.csr_matrix, np.ndarray], labels: np.ndarray,
+                   labels_col: Optional[np.ndarray] = None, weights: str = 'degree',
+                   resolution: float = 1, return_all: bool = False) -> Union[float, Tuple[float, float, float]]:
+    """Modularity of a clustering.
+
+    The modularity of a clustering is
+
+    :math:`Q = \\dfrac{1}{w} \\sum_{i,j}\\left(A_{ij} - \\gamma \\dfrac{w_iw_j}{w}\\right)\\delta_{c_i,c_j}`
+    for graphs,
+
+    :math:`Q = \\dfrac{1}{w} \\sum_{i,j}\\left(A_{ij} - \\gamma \\dfrac{d^+_id^-_j}{w}\\right)\\delta_{c_i,c_j}`
+    for directed graphs,
+
+    where
+
+    * :math:`c_i` is the cluster of node :math:`i`,\n
+    * :math:`w_i` is the weight of node :math:`i`,\n
+    * :math:`w^+_i, w^-_i` are the out-weight, in-weight of node :math:`i` (for directed graphs),\n
+    * :math:`w = 1^TA1` is the total weight,\n
+    * :math:`\\delta` is the Kronecker symbol,\n
+    * :math:`\\gamma \\ge 0` is the resolution parameter.
+
+    Parameters
+    ----------
+    input_matrix :
+        Adjacency matrix or biadjacency matrix of the graph.
+    labels :
+        Labels of nodes.
+    labels_col :
+        Labels of column nodes (for bipartite graphs).
+    weights :
+        Weighting of nodes (``'degree'`` (default) or ``'uniform'``).
+    resolution:
+        Resolution parameter (default = 1).
+    return_all:
+        If ``True``, return modularity, fit, diversity.
+
+    Returns
+    -------
+    modularity : float
+    fit: float, optional
+    diversity: float, optional
+
+    Example
+    -------
+    >>> from sknetwork.clustering import get_modularity
+    >>> from sknetwork.data import house
+    >>> adjacency = house()
+    >>> labels = np.array([0, 0, 1, 1, 0])
+    >>> np.round(get_modularity(adjacency, labels), 2)
+    0.11
+    """
+    adjacency, bipartite = get_adjacency(input_matrix.astype(float))
+
+    if bipartite:
+        if labels_col is None:
+            raise ValueError('For bipartite graphs, you must specify the labels of both rows and columns.')
+        else:
+            labels = np.hstack((labels, labels_col))
+
+    if len(labels) != adjacency.shape[0]:
+        raise ValueError('Dimension mismatch between labels and input matrix.')
+
+    probs_row = get_probs(weights, adjacency)
+    probs_col = get_probs(weights, adjacency.T)
+    membership = get_membership(labels).astype(float)
+
+    fit = membership.T.dot(adjacency.dot(membership)).diagonal().sum() / adjacency.data.sum()
+    div = membership.T.dot(probs_col).dot(membership.T.dot(probs_row))
+    mod = fit - resolution * div
+    if return_all:
+        return mod, fit, div
+    else:
+        return mod

sknetwork/clustering/postprocess.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on July 10, 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.utils.membership import get_membership
+
+
+def reindex_labels(labels: np.ndarray) -> np.ndarray:
+    """Reindex clusters in decreasing order of size.
+
+    Parameters
+    ----------
+    labels :
+        Label of each node.
+    Returns
+    -------
+    new_labels : np.ndarray
+        New label of each node.
+
+    Example
+    -------
+    >>> from sknetwork.clustering import reindex_labels
+    >>> labels = np.array([0, 1, 1])
+    >>> reindex_labels(labels)
+    array([1, 0, 0])
+    """
+    _, index, counts = np.unique(labels, return_inverse=True, return_counts=True)
+    _, new_index = np.unique(np.argsort(-counts), return_index=True)
+    return new_index[index]
+
+
+def aggregate_graph(input_matrix: sparse.csr_matrix, labels: Optional[np.ndarray] = None,
+                    labels_row: Optional[np.ndarray] = None, labels_col: Optional[np.ndarray] = None) \
+        -> sparse.csr_matrix:
+    """Aggregate graph per label. All nodes with the same label become a single node.
+    Negative labels are ignored (corresponding nodes are discarded).
+
+    Parameters
+    ----------
+    input_matrix: sparse matrix
+        Adjacency or biadjacency matrix of the graph.
+    labels: np.ndarray
+        Labels of nodes.
+    labels_row: np.ndarray
+        Labels of rows (for bipartite graphs). Alias for labels.
+    labels_col: np.ndarray
+        Labels of columns (for bipartite graphs).
+    """
+    if labels_row is not None:
+        membership_row = get_membership(labels_row)
+    else:
+        membership_row = get_membership(labels)
+    if labels_col is not None:
+        membership_col = get_membership(labels_col)
+    else:
+        membership_col = membership_row
+    aggregate_matrix = membership_row.T.dot(input_matrix).dot(membership_col)
+    return aggregate_matrix.tocsr()

sknetwork/clustering/propagation_clustering.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# coding: utf-8
+"""
+Created on May, 2020
+@author: Thomas Bonald <tbonald@enst.fr>
+"""
+from typing import Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.classification.propagation import Propagation
+from sknetwork.clustering.base import BaseClustering
+from sknetwork.utils.format import check_format, get_adjacency
+
+
+class PropagationClustering(BaseClustering, Propagation):
+    """Clustering by label propagation.
+
+    Parameters
+    ----------
+    n_iter : int
+        Maximum number of iterations (-1 for infinity).
+    node_order : str
+        * `'random'`: node labels are updated in random order.
+        * `'increasing'`: node labels are updated by increasing order of weight.
+        * `'decreasing'`: node labels are updated by decreasing order of weight.
+        * Otherwise, node labels are updated by index order.
+    weighted : bool
+        If ``True``, the vote of each neighbor is proportional to the edge weight.
+        Otherwise, all votes have weight 1.
+    sort_clusters : bool
+        If ``True``, sort labels in decreasing order of cluster size.
+    return_probs : bool
+        If ``True``, return the probability distribution over clusters (soft clustering).
+    return_aggregate : bool
+        If ``True``, return the aggregate adjacency matrix or biadjacency matrix between clusters.
+
+    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 PropagationClustering
+    >>> from sknetwork.data import karate_club
+    >>> propagation = PropagationClustering()
+    >>> graph = karate_club(metadata=True)
+    >>> adjacency = graph.adjacency
+    >>> labels = propagation.fit_predict(adjacency)
+    >>> len(set(labels))
+    2
+
+    References
+    ----------
+    Raghavan, U. N., Albert, R., & Kumara, S. (2007).
+    `Near linear time algorithm to detect community structures in large-scale networks.
+    <https://arxiv.org/pdf/0709.2938.pdf>`_
+    Physical review E, 76(3), 036106.
+    """
+    def __init__(self, n_iter: int = 5, node_order: str = 'decreasing', weighted: bool = True,
+                 sort_clusters: bool = True, return_probs: bool = True, return_aggregate: bool = True):
+        Propagation.__init__(self, n_iter, node_order, weighted)
+        BaseClustering.__init__(self, sort_clusters, return_probs, return_aggregate)
+        self.bipartite = None
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray]) -> 'PropagationClustering':
+        """Clustering by label propagation.
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`PropagationClustering`
+        """
+        self._init_vars()
+
+        # input
+        input_matrix = check_format(input_matrix)
+        adjacency, bipartite = get_adjacency(input_matrix)
+
+        # propagation
+        Propagation.fit(self, adjacency)
+
+        # output
+        _, self.labels_ = np.unique(self.labels_, return_inverse=True)
+        if bipartite:
+            self._split_vars(input_matrix.shape)
+            self.bipartite = True
+        self._secondary_outputs(input_matrix)
+
+        return self

sknetwork/clustering/tests/__init__.py

@@ -0,0 +1 @@
+"""tests for clustering"""