scikit-network 0.33.4__cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

sknetwork/hierarchy/louvain_hierarchy.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2020
+@author: Quentin Lutz <qlutz@enst.fr>
+@author: Thomas Bonald <tbonald@enst.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.clustering.louvain import Louvain
+from sknetwork.hierarchy.base import BaseHierarchy
+from sknetwork.hierarchy.postprocess import get_dendrogram, reorder_dendrogram
+from sknetwork.utils.check import check_format
+from sknetwork.utils.format import get_adjacency
+
+
+class LouvainIteration(BaseHierarchy):
+    """Hierarchical clustering by successive instances of Louvain (top-down).
+
+    Parameters
+    ----------
+    depth : int
+        Depth of the tree.
+        A negative value is interpreted as no limit (return a tree of maximum depth).
+    resolution : float
+        Resolution parameter.
+    tol_optimization : float
+        Minimum increase in the objective function to enter a new optimization pass.
+    tol_aggregation : float
+        Minimum increase in the objective function to enter a new aggregation pass.
+    n_aggregations : int
+        Maximum number of aggregations.
+        A negative value is interpreted as no limit.
+    shuffle_nodes : bool
+        If ``True``,  shuffle nodes before optimization.
+    random_state : int
+        Random number generator or random seed. If ``None``, numpy.random is used.
+    verbose : bool
+        Verbose mode.
+
+    Attributes
+    ----------
+    dendrogram\_ : np.ndarray
+        Dendrogram of the graph.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import LouvainIteration
+    >>> from sknetwork.data import house
+    >>> louvain = LouvainIteration()
+    >>> adjacency = house()
+    >>> louvain.fit_predict(adjacency)
+    array([[3., 2., 1., 2.],
+           [4., 1., 1., 2.],
+           [6., 0., 1., 3.],
+           [5., 7., 2., 5.]])
+
+    Notes
+    -----
+    Each row of the dendrogram = merge nodes, distance, size of cluster.
+
+    See Also
+    --------
+    scipy.cluster.hierarchy.dendrogram
+    sknetwork.clustering.Louvain
+    """
+
+    def __init__(self, depth: int = 3, resolution: float = 1, tol_optimization: float = 1e-3,
+                 tol_aggregation: float = 1e-3, n_aggregations: int = -1, shuffle_nodes: bool = False,
+                 random_state: Optional[Union[np.random.RandomState, int]] = None, verbose: bool = False):
+        super(LouvainIteration, self).__init__()
+
+        self.dendrogram_ = None
+        self.depth = depth
+        self._clustering_method = Louvain(resolution=resolution, tol_optimization=tol_optimization,
+                                          tol_aggregation=tol_aggregation, n_aggregations=n_aggregations,
+                                          shuffle_nodes=shuffle_nodes, random_state=random_state, verbose=verbose)
+        self.bipartite = None
+
+    def _recursive_louvain(self, adjacency: Union[sparse.csr_matrix, np.ndarray], depth: int,
+                           nodes: Optional[np.ndarray] = None):
+        """Recursive function for fit.
+
+        Parameters
+        ----------
+        adjacency : sparse.csr_matrix, np.ndarray
+            Adjacency matrix of the graph.
+        depth : int
+            Depth of the recursion.
+        nodes : np.ndarray
+            The indices of the current nodes in the original graph.
+
+        Returns
+        -------
+        tree: recursive list of list of nodes.
+        """
+        n = adjacency.shape[0]
+        if nodes is None:
+            nodes = np.arange(n)
+
+        if adjacency.nnz and depth:
+            labels = self._clustering_method.fit_predict(adjacency)
+        else:
+            labels = np.zeros(n)
+
+        clusters = np.unique(labels)
+
+        tree = []
+        if len(clusters) == 1:
+            if len(nodes) > 1:
+                return [[node] for node in nodes]
+            else:
+                return [nodes[0]]
+        else:
+            for cluster in clusters:
+                mask = (labels == cluster)
+                nodes_cluster = nodes[mask]
+                adjacency_cluster = adjacency[mask, :][:, mask]
+                tree.append(self._recursive_louvain(adjacency_cluster, depth - 1, nodes_cluster))
+            return tree
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) \
+            -> 'LouvainIteration':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix.
+
+        Returns
+        -------
+        self: :class:`LouvainIteration`
+        """
+        self._init_vars()
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_bipartite=force_bipartite)
+        tree = self._recursive_louvain(adjacency, self.depth)
+        dendrogram, _ = get_dendrogram(tree)
+        dendrogram = np.array(dendrogram)
+        dendrogram[:, 2] += 1 - min(dendrogram[:, 2])
+        self.dendrogram_ = reorder_dendrogram(dendrogram)
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self
+
+
+class LouvainHierarchy(BaseHierarchy):
+    """Hierarchical clustering by Louvain (bottom-up).
+
+    Each level corresponds to an aggregation step of the Louvain algorithm.
+
+    Parameters
+    ----------
+    resolution : float
+        Resolution parameter.
+    tol_optimization : float
+        Minimum increase in the objective function to enter a new optimization pass.
+    tol_aggregation : float
+        Minimum increase in the objective function to enter a new aggregation pass.
+    shuffle_nodes : bool
+        If ``True``, shuffle nodes before optimization.
+    random_state : int
+        Random number generator or random seed. If ``None``, numpy.random is used.
+    verbose : bool
+        Verbose mode.
+
+    Attributes
+    ----------
+    dendrogram\_ : np.ndarray
+        Dendrogram of the graph.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import LouvainHierarchy
+    >>> from sknetwork.data import house
+    >>> louvain = LouvainHierarchy()
+    >>> adjacency = house()
+    >>> louvain.fit_predict(adjacency)
+    array([[3., 2., 1., 2.],
+           [4., 1., 1., 2.],
+           [6., 0., 1., 3.],
+           [5., 7., 2., 5.]])
+
+    Notes
+    -----
+    Each row of the dendrogram = merge nodes, distance, size of cluster.
+
+    See Also
+    --------
+    scipy.cluster.hierarchy.dendrogram
+    sknetwork.clustering.Louvain
+    """
+
+    def __init__(self, resolution: float = 1, tol_optimization: float = 1e-3,
+                 tol_aggregation: float = 1e-3, shuffle_nodes: bool = False,
+                 random_state: Optional[Union[np.random.RandomState, int]] = None, verbose: bool = False):
+        super(LouvainHierarchy, self).__init__()
+
+        self.dendrogram_ = None
+        self._clustering_method = Louvain(resolution=resolution, tol_optimization=tol_optimization,
+                                          tol_aggregation=tol_aggregation, n_aggregations=1,
+                                          shuffle_nodes=shuffle_nodes, random_state=random_state, verbose=verbose)
+        self.bipartite = None
+
+    def _get_hierarchy(self, adjacency: Union[sparse.csr_matrix, np.ndarray]):
+        """Get the hierarchy from Louvain.
+
+        Parameters
+        ----------
+        adjacency : sparse.csr_matrix, np.ndarray
+            Adjacency matrix of the graph.
+
+        Returns
+        -------
+        tree: recursive list of list of nodes
+        """
+        tree = [[node] for node in range(adjacency.shape[0])]
+        labels = self._clustering_method.fit_predict(adjacency)
+        labels_unique = np.unique(labels)
+        while 1:
+            tree = [[tree[node] for node in np.flatnonzero(labels == label)] for label in labels_unique]
+            tree = [cluster[0] if len(cluster) == 1 else cluster for cluster in tree]
+            aggregate = self._clustering_method.aggregate_
+            labels = self._clustering_method.fit_predict(aggregate)
+            if len(labels_unique) == len(np.unique(labels)):
+                break
+            else:
+                labels_unique = np.unique(labels)
+        return tree
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) \
+            -> 'LouvainHierarchy':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix.
+
+        Returns
+        -------
+        self: :class:`LouvainHierarchy`
+        """
+        self._init_vars()
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_bipartite=force_bipartite)
+        tree = self._get_hierarchy(adjacency)
+        dendrogram, _ = get_dendrogram(tree)
+        dendrogram = np.array(dendrogram)
+        dendrogram[:, 2] += 1 - min(dendrogram[:, 2])
+        self.dendrogram_ = reorder_dendrogram(dendrogram)
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self

sknetwork/hierarchy/metrics.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on March 2019
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+import numpy as np
+from scipy import sparse
+from sknetwork.hierarchy.paris import AggregateGraph
+
+from sknetwork.utils.check import check_format, get_probs, check_square
+from sknetwork.utils.check import check_min_size, check_min_nnz
+from sknetwork.utils.format import directed2undirected
+
+
+def _instantiate_vars(adjacency: sparse.csr_matrix, weights: str = 'uniform'):
+    """Initialize standard variables for metrics."""
+    weights_row = get_probs(weights, adjacency)
+    weights_col = get_probs(weights, adjacency.T)
+    sym_adjacency = directed2undirected(adjacency)
+    aggregate_graph = AggregateGraph(weights_row, weights_col, sym_adjacency.data.astype(float),
+                                     sym_adjacency.indices, sym_adjacency.indptr)
+    return aggregate_graph, weights_row, weights_col
+
+
+def get_sampling_distributions(adjacency: sparse.csr_matrix, dendrogram: np.ndarray, weights: str = 'uniform'):
+    """Get sampling distributions over each internal node of the tree.
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    dendrogram :
+        Dendrogram.
+    weights :
+        Weights of nodes.
+        ``'degree'`` or ``'uniform'`` (default).
+    Returns
+    -------
+    edge_sampling: np.ndarray
+        Edge sampling distribution.
+    node_sampling: np.ndarray
+        Node sampling distribution.
+    cluster_weights: np.ndarray
+        Cluster weights.
+    """
+    n = adjacency.shape[0]
+    aggregate_graph, weights_row, weights_col = _instantiate_vars(adjacency, weights)
+    cluster_weight = np.zeros(n-1)
+    edge_sampling = np.zeros(n-1)
+    node_sampling = np.zeros(n-1)
+
+    for t in range(n - 1):
+        i = int(dendrogram[t][0])
+        j = int(dendrogram[t][1])
+        if j in aggregate_graph.neighbors[i]:
+            edge_sampling[t] += 2 * aggregate_graph.neighbors[i][j]
+        node_sampling[t] += aggregate_graph.cluster_out_weights[i] * aggregate_graph.cluster_in_weights[j] + \
+            aggregate_graph.cluster_out_weights[j] * aggregate_graph.cluster_in_weights[i]
+        cluster_weight[t] = aggregate_graph.cluster_out_weights[i] + aggregate_graph.cluster_out_weights[j] + \
+            aggregate_graph.cluster_in_weights[i] + aggregate_graph.cluster_in_weights[j]
+        for node in {i, j}:
+            if node < n:
+                # self-loop
+                node_sampling[t] += aggregate_graph.cluster_out_weights[node] * aggregate_graph.cluster_in_weights[node]
+                if node in aggregate_graph.neighbors[node]:
+                    edge_sampling[t] += aggregate_graph.neighbors[node][node]
+        aggregate_graph.merge(i, j)
+    return edge_sampling, node_sampling, cluster_weight / 2
+
+
+def dasgupta_cost(adjacency: sparse.csr_matrix, dendrogram: np.ndarray, weights: str = 'uniform',
+                  normalized: bool = False) -> float:
+    """Dasgupta's cost of a hierarchy.
+
+    Expected size (weights = ``'uniform'``) or expected volume (weights = ``'degree'``) of the cluster induced by
+    random edge sampling (closest ancestor of the two nodes in the hierarchy).
+
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    dendrogram :
+        Dendrogram.
+    weights :
+        Weights of nodes.
+        ``'degree'`` or ``'uniform'`` (default).
+    normalized :
+        If ``True``, normalized cost (between 0 and 1).
+
+    Returns
+    -------
+    cost : float
+        Cost.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import dasgupta_score, Paris
+    >>> from sknetwork.data import house
+    >>> paris = Paris()
+    >>> adjacency = house()
+    >>> dendrogram = paris.fit_transform(adjacency)
+    >>> cost = dasgupta_cost(adjacency, dendrogram)
+    >>> float(np.round(cost, 2))
+    3.33
+
+    References
+    ----------
+    Dasgupta, S. (2016). A cost function for similarity-based hierarchical clustering.
+    Proceedings of ACM symposium on Theory of Computing.
+    """
+    adjacency = check_format(adjacency)
+    check_square(adjacency)
+
+    n = adjacency.shape[0]
+    check_min_size(n, 2)
+
+    edge_sampling, _, cluster_weight = get_sampling_distributions(adjacency, dendrogram, weights)
+    cost = edge_sampling.dot(cluster_weight)
+
+    if not normalized:
+        if weights == 'degree':
+            cost *= adjacency.data.sum()
+        else:
+            cost *= n
+
+    return cost
+
+
+def dasgupta_score(adjacency: sparse.csr_matrix, dendrogram: np.ndarray, weights: str = 'uniform') -> float:
+    """Dasgupta's score of a hierarchy (quality metric, between 0 and 1).
+
+    Defined as 1 - normalized Dasgupta's cost.
+
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    dendrogram :
+        Dendrogram.
+    weights :
+        Weights of nodes.
+        ``'degree'`` or ``'uniform'`` (default).
+
+    Returns
+    -------
+    score : float
+        Score.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import dasgupta_score, Paris
+    >>> from sknetwork.data import house
+    >>> paris = Paris()
+    >>> adjacency = house()
+    >>> dendrogram = paris.fit_transform(adjacency)
+    >>> score = dasgupta_score(adjacency, dendrogram)
+    >>> float(np.round(score, 2))
+    0.33
+
+    References
+    ----------
+    Dasgupta, S. (2016). A cost function for similarity-based hierarchical clustering.
+    Proceedings of ACM symposium on Theory of Computing.
+    """
+    return 1 - dasgupta_cost(adjacency, dendrogram, weights, normalized=True)
+
+
+def tree_sampling_divergence(adjacency: sparse.csr_matrix, dendrogram: np.ndarray, weights: str = 'degree',
+                             normalized: bool = True) -> float:
+    """Tree sampling divergence of a hierarchy (quality metric).
+
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    dendrogram :
+        Dendrogram.
+    weights :
+        Weights of nodes.
+        ``'degree'`` (default) or ``'uniform'``.
+    normalized :
+        If ``True``, normalized score (between 0 and 1).
+
+    Returns
+    -------
+    score : float
+        Score.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import tree_sampling_divergence, Paris
+    >>> from sknetwork.data import house
+    >>> paris = Paris()
+    >>> adjacency = house()
+    >>> dendrogram = paris.fit_transform(adjacency)
+    >>> score = tree_sampling_divergence(adjacency, dendrogram)
+    >>> float(np.round(score, 2))
+    0.05
+
+    References
+    ----------
+    Charpentier, B. & Bonald, T. (2019).
+    `Tree Sampling Divergence: An Information-Theoretic Metric for
+    Hierarchical Graph Clustering.
+    <https://hal.telecom-paristech.fr/hal-02144394/document>`_
+    Proceedings of IJCAI.
+    """
+    adjacency = check_format(adjacency)
+    check_square(adjacency)
+    check_min_nnz(adjacency.nnz, 1)
+    adjacency = adjacency.astype(float)
+    n = adjacency.shape[0]
+    check_min_size(n, 2)
+
+    adjacency.data /= adjacency.data.sum()
+    edge_sampling, node_sampling, _ = get_sampling_distributions(adjacency, dendrogram, weights)
+
+    index = np.where(edge_sampling)[0]
+    score = edge_sampling[index].dot(np.log(edge_sampling[index] / node_sampling[index]))
+    if normalized:
+        weights_row = get_probs(weights, adjacency)
+        weights_col = get_probs(weights, adjacency.T)
+        inv_out_weights = sparse.diags(weights_row, shape=(n, n), format='csr')
+        inv_out_weights.data = 1 / inv_out_weights.data
+        inv_in_weights = sparse.diags(weights_col, shape=(n, n), format='csr')
+        inv_in_weights.data = 1 / inv_in_weights.data
+        sampling_ratio = inv_out_weights.dot(adjacency.dot(inv_in_weights))
+        inv_out_weights.data = np.ones(len(inv_out_weights.data))
+        inv_in_weights.data = np.ones(len(inv_in_weights.data))
+        edge_sampling = inv_out_weights.dot(adjacency.dot(inv_in_weights))
+        mutual_information = edge_sampling.data.dot(np.log(sampling_ratio.data))
+        if mutual_information > 0:
+            score /= mutual_information
+    return score