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

sknetwork/ranking/betweenness.pyx

@@ -0,0 +1,97 @@
+# distutils: language = c++
+# cython: language_level=3
+"""
+Created on September 17 2020
+@author: Tiphaine Viard <tiphaine.viard@telecom-paris.fr>
+"""
+from typing import Union
+import numpy as np
+from scipy import sparse
+
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_format, check_square, check_connected
+
+from libcpp.vector cimport vector
+from libcpp.queue cimport queue
+
+class Betweenness(BaseRanking):
+    """ Betweenness centrality, based on Brandes' algorithm.
+
+    Attributes
+    ----------
+    scores_ : np.ndarray
+        Betweenness centrality value of each node
+
+    Example
+    -------
+    >>> from sknetwork.ranking import Betweenness
+    >>> from sknetwork.data.toy_graphs import bow_tie
+    >>> betweenness = Betweenness()
+    >>> adjacency = bow_tie()
+    >>> scores = betweenness.fit_transform(adjacency)
+    >>> scores
+    array([4., 0., 0., 0., 0.])
+
+    References
+    ----------
+    Brandes, Ulrik (2001). A faster algorithm for betweenness centrality. Journal of Mathematical Sociology.
+    """
+
+    def __init__(self, normalized: bool = False):
+        super(Betweenness, self).__init__()
+        self.normalized_ = normalized
+
+    def fit(self, adjacency: Union[sparse.csr_matrix, np.ndarray]) -> 'Betweenness':
+        adjacency = check_format(adjacency)
+        check_square(adjacency)
+        check_connected(adjacency)
+
+        cdef int source
+        cdef vector[ vector[int] ] preds
+        cdef vector[int] sigma
+        cdef vector[int] dists
+        cdef int i
+        cdef int j
+        cdef vector[float] delta
+
+        cdef int n = adjacency.shape[0]
+        self.scores_ = np.zeros(n)
+        cdef vector[int] seen  # Using list as stack
+        cdef queue[int] bfs_queue
+
+        for source in range(n):
+            preds = [[] for _ in range(n)]
+            sigma = np.zeros(n)
+            sigma[source] = 1
+            dists = -np.ones(n, dtype=int)
+            dists[source] = 0
+            bfs_queue.push(source)
+
+            while bfs_queue.size() != 0:
+                i = bfs_queue.front()
+                bfs_queue.pop()
+
+                seen.push_back(i)
+                neighbors = adjacency.indices[adjacency.indptr[i]:adjacency.indptr[i + 1]]
+                for j in neighbors:
+                    if dists[j] < 0:  # j found for the first time?
+                        dists[j] = dists[i] + 1
+                        bfs_queue.push(j)
+                    if dists[j] == dists[i] + 1:  # shortest path to j via i?
+                        sigma[j] += sigma[i]
+                        preds[j].push_back(i)
+
+            # Now backtrack to compute betweenness scores
+            delta = np.zeros(n)
+            while len(seen) != 0:
+                j = seen.back()
+                seen.pop_back()
+                for i in preds[j]:
+                    delta[i] += sigma[i] / sigma[j] * (1 + delta[j])
+                if j != source:
+                    self.scores_[j] += delta[j]
+
+        # Undirected graph, divide all values by two
+        self.scores_ = 1 / 2 * self.scores_
+
+        return self

sknetwork/ranking/closeness.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on November 12 2019
+@author: Quentin Lutz <qlutz@enst.fr>
+"""
+from math import log
+from typing import Union, Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.path.shortest_path import get_distances
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_format, check_square, check_connected
+
+
+class Closeness(BaseRanking):
+    """Ranking by closeness centrality of each node in a connected graph, corresponding to the average length of the
+    shortest paths from that node to all the other ones.
+
+    Parameters
+    ----------
+    method :
+        Denotes if the results should be exact or approximate.
+    tol: float
+        If ``method=='approximate'``, the allowed tolerance on each score entry.
+
+    Attributes
+    ----------
+    scores_ : np.ndarray
+        Closeness centrality of each node.
+
+    Example
+    -------
+    >>> from sknetwork.ranking import Closeness
+    >>> from sknetwork.data import cyclic_digraph
+    >>> closeness = Closeness()
+    >>> adjacency = cyclic_digraph(3)
+    >>> scores = closeness.fit_predict(adjacency)
+    >>> np.round(scores, 2)
+    array([0.67, 0.67, 0.67])
+
+    References
+    ----------
+    Eppstein, D., & Wang, J. (2001, January).
+    `Fast approximation of centrality.
+    <http://jgaa.info/accepted/2004/EppsteinWang2004.8.1.pdf>`_
+    In Proceedings of the twelfth annual ACM-SIAM symposium on Discrete algorithms (pp. 228-229).
+    Society for Industrial and Applied Mathematics.
+    """
+
+    def __init__(self, method: str = 'exact', tol: float = 1e-1):
+        super(Closeness, self).__init__()
+
+        self.method = method
+        self.tol = tol
+
+    def fit(self, adjacency: Union[sparse.csr_matrix, np.ndarray]) -> 'Closeness':
+        """Closeness centrality for connected graphs.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`Closeness`
+        """
+        adjacency = check_format(adjacency)
+        check_square(adjacency)
+        check_connected(adjacency)
+        n = adjacency.shape[0]
+
+        if self.method == 'exact':
+            n_sources = n
+            sources = np.arange(n)
+        elif self.method == 'approximate':
+            n_sources = min(int(log(n) / self.tol ** 2), n)
+            sources = np.random.choice(np.arange(n), n_sources, replace=False)
+        else:
+            raise ValueError("Method should be either 'exact' or 'approximate'.")
+
+        distances = np.array([get_distances(adjacency, source=source) for source in sources])
+
+        distances_min = np.min(distances, axis=1)
+        scores = (n - 1) / n / np.mean(distances, axis=1)
+        scores[distances_min < 0] = 0
+        self.scores_ = scores
+
+        return self

sknetwork/ranking/hits.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Oct 07 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+
+from typing import Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.linalg import SVDSolver, LanczosSVD
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_format
+
+
+class HITS(BaseRanking):
+    """Hub and authority scores of each node.
+    For bipartite graphs, the hub score is computed on rows and the authority score on columns.
+
+    Parameters
+    ----------
+    solver : ``'lanczos'`` (default, Lanczos algorithm) or :class:`SVDSolver` (custom solver)
+        Which solver to use.
+
+    Attributes
+    ----------
+    scores_ : np.ndarray
+        Hub score of each node.
+
+    Example
+    -------
+    >>> from sknetwork.ranking import HITS
+    >>> from sknetwork.data import star_wars
+    >>> hits = HITS()
+    >>> biadjacency = star_wars()
+    >>> scores = hits.fit_predict(biadjacency)
+    >>> np.round(scores, 2)
+    array([0.5 , 0.23, 0.69, 0.46])
+
+    References
+    ----------
+    Kleinberg, J. M. (1999). Authoritative sources in a hyperlinked environment.
+    Journal of the ACM, 46(5), 604-632.
+    """
+    def __init__(self, solver: Union[str, SVDSolver] = 'lanczos'):
+        super(HITS, self).__init__()
+
+        if type(solver) == str:
+            self.solver: SVDSolver = LanczosSVD()
+        else:
+            self.solver = solver
+
+    def fit(self, adjacency: Union[sparse.csr_matrix, np.ndarray]) -> 'HITS':
+        """Compute HITS algorithm with a spectral method.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency or biadjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`HITS`
+        """
+        adjacency = check_format(adjacency)
+
+        self.solver.fit(adjacency, 1)
+        hubs: np.ndarray = self.solver.singular_vectors_left_.reshape(-1)
+        authorities: np.ndarray = self.solver.singular_vectors_right_.reshape(-1)
+
+        h_pos, h_neg = (hubs > 0).sum(), (hubs < 0).sum()
+        a_pos, a_neg = (authorities > 0).sum(), (authorities < 0).sum()
+
+        if h_pos > h_neg:
+            hubs = np.clip(hubs, a_min=0., a_max=None)
+        else:
+            hubs = np.clip(-hubs, a_min=0., a_max=None)
+
+        if a_pos > a_neg:
+            authorities = np.clip(authorities, a_min=0., a_max=None)
+        else:
+            authorities = np.clip(-authorities, a_min=0., a_max=None)
+
+        self.scores_row_ = hubs
+        self.scores_col_ = authorities
+        self.scores_ = hubs
+
+        return self

sknetwork/ranking/katz.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on May 2020
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from typing import Union
+
+import numpy as np
+from scipy import sparse
+from scipy.sparse.linalg import LinearOperator
+
+from sknetwork.linalg.polynome import Polynome
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_format
+from sknetwork.utils.format import get_adjacency
+
+
+class Katz(BaseRanking):
+    """Katz centrality, defined by:
+
+    :math:`\\sum_{k=1}^K\\alpha^k(A^k)^T\\mathbf{1}`
+
+    where :math:`A` is the adjacency matrix, :math:`\\alpha` is the damping factor and :math:`K` is the path length.
+
+    Parameters
+    ----------
+    damping_factor : float
+        Damping factor for path contributions.
+    path_length : int
+        Maximum length of the paths.
+
+    Attributes
+    ----------
+    scores_ : np.ndarray
+        Score of each node.
+
+    Examples
+    --------
+    >>> from sknetwork.data.toy_graphs import house
+    >>> adjacency = house()
+    >>> katz = Katz()
+    >>> scores = katz.fit_predict(adjacency)
+    >>> np.round(scores, 2)
+    array([6.5 , 8.25, 5.62, 5.62, 8.25])
+
+    References
+    ----------
+    Katz, L. (1953). `A new status index derived from sociometric analysis
+    <https://link.springer.com/content/pdf/10.1007/BF02289026.pdf>`_. Psychometrika, 18(1), 39-43.
+    """
+    def __init__(self, damping_factor: float = 0.5, path_length: int = 4):
+        super(Katz, self).__init__()
+        self.damping_factor = damping_factor
+        self.path_length = path_length
+        self.bipartite = None
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray, LinearOperator]) -> 'Katz':
+        """Katz centrality.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`Katz`
+        """
+        input_matrix = check_format(input_matrix)
+        adjacency, self.bipartite = get_adjacency(input_matrix)
+        n = adjacency.shape[0]
+        coefs = self.damping_factor ** np.arange(self.path_length + 1)
+        coefs[0] = 0.
+        polynome = Polynome(adjacency.T.astype(bool).tocsr(), coefs)
+        self.scores_ = polynome.dot(np.ones(n))
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self

sknetwork/ranking/pagerank.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in May 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Union, Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.linalg.ppr_solver import get_pagerank
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_damping_factor
+from sknetwork.utils.format import get_adjacency_values
+
+
+class PageRank(BaseRanking):
+    """PageRank of each node, corresponding to its frequency of visit by a random walk.
+
+    The random walk restarts with some fixed probability. The restart distribution can be personalized by the user.
+    This variant is known as Personalized PageRank.
+
+    Parameters
+    ----------
+    damping_factor : float
+        Probability to continue the random walk.
+    solver : str
+        * ``'piteration'``, use power iteration for a given number of iterations.
+        * ``'diteration'``, use asynchronous parallel diffusion for a given number of iterations.
+        * ``'lanczos'``, use eigensolver with a given tolerance.
+        * ``'bicgstab'``, use Biconjugate Gradient Stabilized method for a given tolerance.
+        * ``'RH'``, use a Ruffini-Horner polynomial evaluation.
+        * ``'push'``, use push-based algorithm for a given tolerance
+    n_iter : int
+        Number of iterations for some solvers.
+    tol : float
+        Tolerance for the convergence of some solvers.
+
+    Attributes
+    ----------
+    scores\_ : np.ndarray
+        PageRank score of each node.
+
+    Example
+    -------
+    >>> from sknetwork.ranking import PageRank
+    >>> from sknetwork.data import house
+    >>> pagerank = PageRank()
+    >>> adjacency = house()
+    >>> weights = {0: 1}
+    >>> scores = pagerank.fit_predict(adjacency, weights)
+    >>> np.round(scores, 2)
+    array([0.29, 0.24, 0.12, 0.12, 0.24])
+
+    References
+    ----------
+    Page, L., Brin, S., Motwani, R., & Winograd, T. (1999). The PageRank citation ranking: Bringing order to the web.
+    Stanford InfoLab.
+    """
+    def __init__(self, damping_factor: float = 0.85, solver: str = 'piteration', n_iter: int = 10, tol: float = 1e-6):
+        super(PageRank, self).__init__()
+        check_damping_factor(damping_factor)
+        self.damping_factor = damping_factor
+        self.solver = solver
+        self.n_iter = n_iter
+        self.tol = tol
+        self.bipartite = None
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray],
+            weights: Optional[Union[dict, np.ndarray]] = None, weights_row: Optional[Union[dict, np.ndarray]] = None,
+            weights_col: Optional[Union[dict, np.ndarray]] = None, force_bipartite: bool = False) -> 'PageRank':
+        """Compute the pagerank of each node.
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        weights : np.ndarray, dict
+            Weights of the restart distribution for Personalized PageRank.
+            If ``None``, the uniform distribution is used (no personalization, default).
+        weights_row : np.ndarray, dict
+            Weights on rows of the restart distribution for Personalized PageRank.
+            Used for bipartite graphs.
+            If both weights_row and weights_col are ``None`` (default), the uniform distribution on rows is used.
+        weights_col : np.ndarray, dict
+            Weights on columns of the restart distribution for Personalized PageRank.
+            Used for bipartite graphs.
+        force_bipartite : bool
+            If ``True``, consider the input matrix as the biadjacency matrix of a bipartite graph.
+        Returns
+        -------
+        self: :class:`PageRank`
+        """
+        adjacency, values, self.bipartite = get_adjacency_values(input_matrix, force_bipartite=force_bipartite,
+                                                                 values=weights,
+                                                                 values_row=weights_row,
+                                                                 values_col=weights_col,
+                                                                 default_value=0,
+                                                                 which='probs')
+        self.scores_ = get_pagerank(adjacency, values, damping_factor=self.damping_factor, n_iter=self.n_iter,
+                                    solver=self.solver, tol=self.tol)
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self

sknetwork/ranking/postprocess.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on May 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+import numpy as np
+
+
+def top_k(scores: np.ndarray, k: int = 1, sort: bool = True):
+    """Return the indices of the k elements of highest values.
+
+    Parameters
+    ----------
+    scores : np.ndarray
+        Array of values.
+    k : int
+        Number of elements to return.
+    sort : bool
+        If ``True``, sort the indices in decreasing order of value (element of highest value first).
+
+    Examples
+    --------
+    >>> top_k([1, 3, 2], k=2)
+    array([1, 2])
+    """
+    scores = np.array(scores)
+    if k >= len(scores):
+        if sort:
+            index = np.argsort(-scores)
+        else:
+            index = np.arange(scores)
+    else:
+        index = np.argpartition(-scores, k)[:k]
+        if sort:
+            index = index[np.argsort(-scores[index])]
+    return index

sknetwork/ranking/tests/__init__.py

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

sknetwork/ranking/tests/test_API.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for ranking API"""
+import unittest
+
+from sknetwork.data.test_graphs import *
+from sknetwork.ranking import *
+
+
+class TestPageRank(unittest.TestCase):
+
+    def test_basic(self):
+        methods = [PageRank(), Closeness(), HITS(), Katz()]
+        for adjacency in [test_graph(), test_digraph()]:
+            n = adjacency.shape[0]
+            for method in methods:
+                score = method.fit_predict(adjacency)
+                self.assertEqual(score.shape, (n, ))
+                self.assertTrue(min(score) >= 0)
+
+    def test_bipartite(self):
+        biadjacency = test_bigraph()
+        n_row, n_col = biadjacency.shape
+
+        methods = [PageRank(), HITS(), Katz()]
+        for method in methods:
+            method.fit(biadjacency)
+            scores_row = method.scores_row_
+            scores_col = method.scores_col_
+
+            self.assertEqual(scores_row.shape, (n_row,))
+            self.assertEqual(scores_col.shape, (n_col,))

sknetwork/ranking/tests/test_betweenness.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for betweenness.py"""
+
+import unittest
+import numpy as np
+
+from sknetwork.ranking.betweenness import Betweenness
+from sknetwork.data.test_graphs import test_graph, test_disconnected_graph
+from sknetwork.data.toy_graphs import bow_tie, star_wars
+
+
+class TestBetweenness(unittest.TestCase):
+
+    def test_basic(self):
+        adjacency = test_graph()
+        betweenness = Betweenness()
+        scores = betweenness.fit_predict(adjacency)
+        self.assertEqual(len(scores), adjacency.shape[0])
+
+    def test_bowtie(self):
+        adjacency = bow_tie()
+        betweenness = Betweenness()
+        scores = betweenness.fit_predict(adjacency)
+        self.assertEqual(np.sum(scores > 0), 1)
+
+    def test_disconnected(self):
+        adjacency = test_disconnected_graph()
+        betweenness = Betweenness()
+        with self.assertRaises(ValueError):
+            betweenness.fit(adjacency)
+
+    def test_bipartite(self):
+        adjacency = star_wars()
+        betweenness = Betweenness()
+
+        with self.assertRaises(ValueError):
+            betweenness.fit_predict(adjacency)

sknetwork/ranking/tests/test_closeness.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for closeness.py"""
+
+import unittest
+
+from sknetwork.data.test_graphs import *
+from sknetwork.ranking.closeness import Closeness
+
+
+class TestDiffusion(unittest.TestCase):
+
+    def test_params(self):
+        with self.assertRaises(ValueError):
+            adjacency = test_graph()
+            Closeness(method='toto').fit(adjacency)
+
+    def test_parallel(self):
+        adjacency = test_graph()
+        n = adjacency.shape[0]
+
+        closeness = Closeness(method='approximate')
+        scores = closeness.fit_predict(adjacency)
+        self.assertEqual(scores.shape, (n,))
+
+    def test_disconnected(self):
+        adjacency = test_disconnected_graph()
+        closeness = Closeness()
+        with self.assertRaises(ValueError):
+            closeness.fit(adjacency)

sknetwork/ranking/tests/test_hits.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Tests for his.py"""
+
+import unittest
+
+from sknetwork.data.test_graphs import test_bigraph
+from sknetwork.ranking import HITS
+
+
+class TestHITS(unittest.TestCase):
+
+    def test_keywords(self):
+        biadjacency = test_bigraph()
+        n_row, n_col = biadjacency.shape
+
+        hits = HITS()
+        hits.fit(biadjacency)
+        self.assertEqual(hits.scores_row_.shape, (n_row,))
+        self.assertEqual(hits.scores_col_.shape, (n_col,))

sknetwork/ranking/tests/test_pagerank.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for pagerank.py"""
+
+import unittest
+
+import numpy as np
+
+from sknetwork.data.models import cyclic_digraph
+from sknetwork.data.test_graphs import test_graph, test_digraph, test_bigraph
+from sknetwork.ranking.pagerank import PageRank
+
+
+class TestPageRank(unittest.TestCase):
+
+    def setUp(self) -> None:
+        """Cycle graph for tests."""
+        self.n = 5
+        self.adjacency = cyclic_digraph(self.n)
+        self.truth = np.ones(self.n) / self.n
+
+    def test_params(self):
+        with self.assertRaises(ValueError):
+            PageRank(damping_factor=1789)
+
+    def test_solvers(self):
+        for solver in ['piteration', 'lanczos', 'bicgstab', 'RH']:
+            pagerank = PageRank(solver=solver)
+            scores = pagerank.fit_predict(self.adjacency)
+            self.assertAlmostEqual(0, np.linalg.norm(scores - self.truth))
+        with self.assertRaises(ValueError):
+            PageRank(solver='toto').fit_predict(self.adjacency)
+
+    def test_seeding(self):
+        pagerank = PageRank()
+        seeds_array = np.zeros(self.n)
+        seeds_array[0] = 1.
+        seeds_dict = {0: 1}
+
+        scores1 = pagerank.fit_predict(self.adjacency, seeds_array)
+        scores2 = pagerank.fit_predict(self.adjacency, seeds_dict)
+        self.assertAlmostEqual(np.linalg.norm(scores1 - scores2), 0.)
+
+    def test_input(self):
+        pagerank = PageRank()
+        scores = pagerank.fit_predict(self.adjacency, force_bipartite=True)
+        self.assertEqual(len(scores), len(pagerank.scores_col_))
+
+    def test_damping(self):
+        pagerank = PageRank(damping_factor=0.99)
+        scores = pagerank.fit_predict(self.adjacency)
+        self.assertAlmostEqual(np.linalg.norm(scores - self.truth), 0.)
+
+        pagerank = PageRank(damping_factor=0.01)
+        scores = pagerank.fit_predict(self.adjacency)
+        self.assertAlmostEqual(np.linalg.norm(scores - self.truth), 0.)
+
+    def test_bigraph(self):
+        pagerank = PageRank()
+        for adjacency in [test_graph(), test_digraph(), test_bigraph()]:
+            pagerank.fit(adjacency, weights_col={0: 1})
+            self.assertAlmostEqual(np.linalg.norm(pagerank.scores_col_ - pagerank.predict(columns=True)), 0.)