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

sknetwork/path/shortest_path.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in May 2023
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Iterable, Optional, Union, Tuple
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.path.dag import get_dag
+from sknetwork.utils.format import bipartite2undirected
+from sknetwork.path.distances import get_distances
+
+
+def get_shortest_path(input_matrix: sparse.csr_matrix, source: Optional[Union[int, Iterable]] = None,
+                      source_row: Optional[Union[int, Iterable]] = None,
+                      source_col: Optional[Union[int, Iterable]] = None, force_bipartite: bool = False) \
+        -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray]]:
+    """Get the shortest paths from a source (or a set of sources) in number of hops.
+
+    Parameters
+    ----------
+    input_matrix :
+        Adjacency matrix or biadjacency matrix of the graph.
+    source :
+        If an integer, index of the source node.
+        If a list, indices of source nodes (the shortest distances to one of these nodes in returned).
+    source_row, source_col :
+        For bipartite graphs, index of source nodes on rows and columns.
+        The parameter source_row is an alias for source (at least one of them must be ``None``).
+    force_bipartite :
+        If ``True``, consider the input matrix as the biadjacency matrix of a bipartite graph.
+        Set to ``True`` is the parameters source_row or source_col are specified.
+
+    Returns
+    -------
+    path : sparse.csr_matrix
+        Adjacency matrix of the graph of the shortest paths from the source node (or the set of source nodes).
+        If the input graph is a bipartite graph, the shape of the matrix is (n_row + n_col, n_row + n_col) with the new
+        index corresponding to the rows then the columns of the original graph.
+
+    Examples
+    --------
+    >>> from sknetwork.data import cyclic_digraph
+    >>> adjacency = cyclic_digraph(3)
+    >>> path = get_shortest_path(adjacency, source=0)
+    >>> path.toarray().astype(int)
+    array([[0, 1, 0],
+           [0, 0, 1],
+           [0, 0, 0]])
+    """
+    distances = get_distances(input_matrix, source, source_row, source_col, force_bipartite)
+    if type(distances) == tuple:
+        adjacency = bipartite2undirected(input_matrix)
+        distances = np.hstack(distances)
+    else:
+        adjacency = input_matrix
+    return get_dag(adjacency, order=distances)
+

sknetwork/path/tests/__init__.py

@@ -0,0 +1 @@
+"""tests for path module"""

sknetwork/path/tests/test_dag.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for search.py"""
+
+import unittest
+
+import numpy as np
+
+from sknetwork.data import cyclic_digraph
+from sknetwork.data.test_graphs import *
+from sknetwork.path import get_dag
+
+
+class TestSearch(unittest.TestCase):
+
+    def test(self):
+        adjacency = cyclic_digraph(3)
+        dag = get_dag(adjacency)
+        self.assertEqual(dag.nnz, 2)
+
+        adjacency = test_graph_empty()
+        dag = get_dag(adjacency)
+        self.assertEqual(dag.nnz, 0)
+
+        adjacency = test_graph()
+        dag = get_dag(adjacency)
+        self.assertEqual(dag.nnz, 12)
+        dag = get_dag(adjacency, order=np.arange(10) % 3)
+        self.assertEqual(dag.nnz, 10)
+
+        adjacency = test_disconnected_graph()
+        dag = get_dag(adjacency, 3)
+        self.assertEqual(dag.nnz, 1)
+
+        adjacency = test_digraph()
+        dag = get_dag(adjacency, 1)
+        self.assertEqual(dag.nnz, 4)

sknetwork/path/tests/test_distances.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for distances.py"""
+import unittest
+
+from sknetwork.data.test_graphs import *
+from sknetwork.path.distances import get_distances
+
+
+class TestDistances(unittest.TestCase):
+
+    def test_input(self):
+        adjacency = test_graph()
+        with self.assertRaises(ValueError):
+            get_distances(adjacency)
+        with self.assertRaises(ValueError):
+            get_distances(adjacency, source=0, source_row=5)
+
+    def test_algo(self):
+        adjacency = test_graph()
+        distances = get_distances(adjacency, 0)
+        distances_ = np.array([0, 1, 3, 2, 2, 3, 2, 3, 4, 4])
+        self.assertTrue(all(distances == distances_))
+        distances = get_distances(adjacency, 0, transpose=True)
+        self.assertTrue(all(distances == distances_))
+        distances = get_distances(adjacency, [0, 5])
+        distances_ = np.array([0, 1, 3, 2, 1, 0, 1, 2, 4, 3])
+        self.assertTrue(all(distances == distances_))
+
+        adjacency = test_graph_empty()
+        source = [0, 3]
+        distances = get_distances(adjacency, source)
+        distances_ = -np.ones(len(distances), dtype=int)
+        distances_[source] = 0
+        self.assertTrue(all(distances == distances_))
+
+        adjacency = test_digraph()
+        distances = get_distances(adjacency, [0])
+        distances_ = np.array([0, 1, 3, 2, 2, 3, -1, -1, -1, -1])
+        self.assertTrue(all(distances == distances_))
+        distances = get_distances(adjacency, [0], transpose=True)
+        self.assertTrue(sum(distances < 0) == 9)
+        distances = get_distances(adjacency, [0, 5], transpose=True)
+        distances_ = np.array([0, 2, -1, -1, 1, 0, 1, -1, -1, -1])
+        self.assertTrue(all(distances == distances_))
+
+        biadjacency = test_bigraph()
+        distances_row, distances_col = get_distances(biadjacency, [0])
+        distances_row_, distances_col_ = np.array([0, -1, 2, -1, -1, -1]), np.array([3,  1, -1, -1, -1, -1, -1, -1])
+        self.assertTrue(all(distances_row == distances_row_))
+        self.assertTrue(all(distances_col == distances_col_))
+
+        adjacency = test_graph()
+        distances_row, distances_col = get_distances(adjacency, source_col=[0])
+        self.assertTrue(all(distances_row % 2))
+        self.assertTrue(all((distances_col + 1) % 2))
+
+        biadjacency = test_bigraph()
+        distances_row, distances_col = get_distances(biadjacency, source=0, source_col=[1, 2])
+        distances_row_, distances_col_ = np.array([0,  1,  1, -1, -1, -1]), np.array([2,  0,  0,  2, -1, -1, -1, -1])
+        self.assertTrue(all(distances_row == distances_row_))
+        self.assertTrue(all(distances_col == distances_col_))

sknetwork/path/tests/test_search.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for search.py"""
+
+import unittest
+
+import numpy as np
+
+from sknetwork.data import cyclic_digraph
+from sknetwork.data.test_graphs import *
+from sknetwork.path import breadth_first_search
+
+
+class TestSearch(unittest.TestCase):
+
+    def test_bfs(self):
+        adjacency = cyclic_digraph(3)
+        search = breadth_first_search(adjacency, 0)
+        search_ = np.arange(3)
+        self.assertTrue(all(search == search_))
+
+        adjacency = test_graph_empty()
+        search = breadth_first_search(adjacency, 0)
+        search_ = np.array([0])
+        self.assertTrue(all(search == search_))
+
+        adjacency = test_graph()
+        search = breadth_first_search(adjacency, 3)
+        search_ = np.array([3, 1, 2, 0, 4, 6, 8, 5, 7, 9])
+        self.assertTrue(all(search == search_))
+
+        adjacency = test_disconnected_graph()
+        search = breadth_first_search(adjacency, 2)
+        search_ = np.array([2, 3])
+        self.assertTrue(all(search == search_))
+
+        adjacency = test_digraph()
+        search = breadth_first_search(adjacency, 1)
+        search_ = {1, 3, 4, 2, 5}
+        self.assertTrue(set(list(search)) == search_)

sknetwork/path/tests/test_shortest_path.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for shortest_path.py"""
+import unittest
+
+from sknetwork.data.test_graphs import *
+from sknetwork.path.shortest_path import get_shortest_path
+
+
+class TestShortestPath(unittest.TestCase):
+
+    def test_path(self):
+        adjacency = test_graph_empty()
+        path = get_shortest_path(adjacency, 0)
+        self.assertEqual(path.nnz, 0)
+
+        adjacency = test_graph()
+        path = get_shortest_path(adjacency, 0)
+        self.assertEqual(path.nnz, 10)
+        path = get_shortest_path(adjacency, [0, 4, 6])
+        self.assertEqual(path.nnz, 10)
+        path = get_shortest_path(adjacency, np.arange(10))
+        self.assertEqual(path.nnz, 0)
+        path = get_shortest_path(adjacency, [0, 5])
+        self.assertEqual(path.nnz, 9)
+
+        adjacency = test_disconnected_graph()
+        path = get_shortest_path(adjacency, 4)
+        self.assertEqual(path.nnz, 5)
+
+        adjacency = test_digraph()
+        path = get_shortest_path(adjacency, 0)
+        self.assertEqual(path.nnz, 5)
+
+        biadjacency = test_bigraph()
+        path = get_shortest_path(biadjacency, 0)
+        self.assertEqual(path.nnz, 3)
+        self.assertTrue(path.shape[0] == np.sum(biadjacency.shape))
+        path = get_shortest_path(biadjacency, source_col=np.arange(biadjacency.shape[1]))
+        self.assertEqual(path.nnz, biadjacency.nnz)

sknetwork/ranking/__init__.py

@@ -0,0 +1,8 @@
+"""ranking module"""
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.ranking.betweenness import Betweenness
+from sknetwork.ranking.closeness import Closeness
+from sknetwork.ranking.hits import HITS
+from sknetwork.ranking.katz import Katz
+from sknetwork.ranking.pagerank import PageRank
+from sknetwork.ranking.postprocess import top_k

sknetwork/ranking/base.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in November 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from abc import ABC
+
+import numpy as np
+
+from sknetwork.base import Algorithm
+
+
+class BaseRanking(Algorithm, ABC):
+    """Base class for ranking algorithms.
+
+    Attributes
+    ----------
+    scores_ : np.ndarray
+        Score of each node.
+    scores_row_: np.ndarray
+        Scores of rows, for bipartite graphs.
+    scores_col_: np.ndarray
+        Scores of columns, for bipartite graphs.
+    """
+    def __init__(self):
+        self.scores_ = None
+
+    def predict(self, columns: bool = False) -> np.ndarray:
+        """Return the scores predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        scores : np.ndarray
+            Scores.
+        """
+        if columns:
+            return self.scores_col_
+        return self.scores_
+
+    def fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the scores. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        scores : np.ndarray
+            Scores.
+        """
+        self.fit(*args, **kwargs)
+        return self.scores_
+
+    def _split_vars(self, shape):
+        n_row = shape[0]
+        self.scores_row_ = self.scores_[:n_row]
+        self.scores_col_ = self.scores_[n_row:]
+        self.scores_ = self.scores_row_

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,94 @@
+#!/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.
+    scores_row_ : np.ndarray
+        Hub score of each row, for bipartite graphs.
+    scores_col_ : np.ndarray
+        Authority score of each column, for bipartite graphs.
+
+    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,83 @@
+#!/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.
+    scores_row_: np.ndarray
+        Scores of rows, for bipartite graphs.
+    scores_col_: np.ndarray
+        Scores of columns, for bipartite graphs.
+
+    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