scikit-network 0.28.3__cp39-cp39-macosx_12_0_arm64.whl

sknetwork/path/search.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Jul 24, 2019
+"""
+import numpy as np
+from scipy import sparse
+
+from sknetwork.utils.check import is_symmetric
+
+
+def breadth_first_search(adjacency: sparse.csr_matrix, source: int, return_predecessors: bool = True):
+    """Breadth-first ordering starting with specified node.
+
+    Based on SciPy (scipy.sparse.csgraph.breadth_first_order)
+
+    Parameters
+    ----------
+    adjacency :
+        The adjacency matrix of the graph
+    source : int
+        The node from which to start the ordering
+    return_predecessors : bool
+        If ``True``, the size predecessor matrix is returned
+
+    Returns
+    -------
+    node_array : np.ndarray
+        The breadth-first list of nodes, starting with specified node. The length of node_array is the number of nodes
+        reachable from the specified node.
+    predecessors : np.ndarray
+        Returned only if ``return_predecessors == True``. The list of predecessors of each node in a breadth-first tree.
+        If node ``i`` is in the tree, then its parent is given by ``predecessors[i]``. If node ``i`` is not in the tree
+        (and for the parent node) then ``predecessors[i] = -9999``.
+    """
+    directed = not is_symmetric(adjacency)
+    return sparse.csgraph.breadth_first_order(adjacency, source, directed, return_predecessors)
+
+
+def depth_first_search(adjacency: sparse.csr_matrix, source: int, return_predecessors: bool = True):
+    """Depth-first ordering starting with specified node.
+
+    Based on SciPy (scipy.sparse.csgraph.depth_first_order)
+
+    Parameters
+    ----------
+    adjacency :
+        The adjacency matrix of the graph
+    source :
+        The node from which to start the ordering
+    return_predecessors:
+        If ``True``, the size predecessor matrix is returned
+
+    Returns
+    -------
+    node_array : np.ndarray
+        The depth-first list of nodes, starting with specified node. The length of node_array is the number of nodes
+        reachable from the specified node.
+    predecessors : np.ndarray
+        Returned only if ``return_predecessors == True``. The list of predecessors of each node in a depth-first tree.
+        If node ``i`` is in the tree, then its parent is given by ``predecessors[i]``. If node ``i`` is not in the tree
+        (and for the parent node) then ``predecessors[i] = -9999``.
+    """
+    directed = not is_symmetric(adjacency)
+    return sparse.csgraph.depth_first_order(adjacency, source, directed, return_predecessors)

sknetwork/path/shortest_path.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on November 12, 2019
+@author: Quentin Lutz <qlutz@enst.fr>
+"""
+from functools import partial
+from multiprocessing import Pool
+from typing import Optional, Union, Iterable
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.utils.check import check_n_jobs, is_symmetric
+
+
+def get_distances(adjacency: sparse.csr_matrix, sources: Optional[Union[int, Iterable]] = None, method: str = 'D',
+                  return_predecessors: bool = False, unweighted: bool = False, n_jobs: Optional[int] = None):
+    """Compute distances between nodes.
+
+    * Graphs
+    * Digraphs
+
+
+    Based on SciPy (scipy.sparse.csgraph.shortest_path)
+
+    Parameters
+    ----------
+    adjacency :
+        The adjacency matrix of the graph
+    sources :
+        If specified, only compute the paths for the points at the given indices. Will not work with ``method =='FW'``.
+    method :
+        The method to be used.
+
+        * ``'D'`` (Dijkstra),
+        * ``'BF'`` (Bellman-Ford),
+        * ``'J'`` (Johnson).
+    return_predecessors :
+        If ``True``, the size predecessor matrix is returned
+    unweighted :
+        If ``True``, the weights of the edges are ignored
+    n_jobs :
+        If an integer value is given, denotes the number of workers to use (-1 means the maximum number will be used).
+        If ``None``, no parallel computations are made.
+
+    Returns
+    -------
+    dist_matrix : np.ndarray
+        Matrix of distances between nodes. ``dist_matrix[i,j]`` gives the shortest
+        distance from the ``i``-th source to node ``j`` in the graph (infinite if no path exists
+        from the ``i``-th source to node ``j``).
+    predecessors : np.ndarray, optional
+        Returned only if ``return_predecessors == True``. The matrix of predecessors, which can be used to reconstruct
+        the shortest paths. Row ``i`` of the predecessor matrix contains information on the shortest paths from the
+        ``i``-th source: each entry ``predecessors[i, j]`` gives the index of the previous node in the path from
+        the ``i``-th source to node ``j`` (-1 if no path exists from the ``i``-th source to node ``j``).
+
+    Examples
+    --------
+    >>> from sknetwork.data import cyclic_digraph
+    >>> adjacency = cyclic_digraph(3)
+    >>> get_distances(adjacency, sources=0)
+    array([0., 1., 2.])
+    >>> get_distances(adjacency, sources=0, return_predecessors=True)
+    (array([0., 1., 2.]), array([-1,  0,  1]))
+
+    """
+    n_jobs = check_n_jobs(n_jobs)
+    if method == 'FW' and n_jobs != 1:
+        raise ValueError('The Floyd-Warshall algorithm cannot be used with parallel computations.')
+    if sources is None:
+        sources = np.arange(adjacency.shape[0])
+    elif np.issubdtype(type(sources), np.integer):
+        sources = np.array([sources])
+    n = len(sources)
+    directed = not is_symmetric(adjacency)
+    local_function = partial(sparse.csgraph.shortest_path,
+                             adjacency, method, directed, return_predecessors, unweighted, False)
+    if n_jobs == 1 or n == 1:
+        try:
+            res = sparse.csgraph.shortest_path(adjacency, method, directed, return_predecessors,
+                                               unweighted, False, sources)
+        except sparse.csgraph.NegativeCycleError:
+            raise ValueError("The shortest path computation could not be completed because a negative cycle is present.")
+    else:
+        try:
+            with Pool(n_jobs) as pool:
+                res = np.array(pool.map(local_function, sources))
+        except sparse.csgraph.NegativeCycleError:
+            pool.terminate()
+            raise ValueError("The shortest path computation could not be completed because a negative cycle is present.")
+    if return_predecessors:
+        res[1][res[1] < 0] = -1
+        if n == 1:
+            return res[0].ravel(), res[1].astype(int).ravel()
+        else:
+            return res[0], res[1].astype(int)
+    else:
+        if n == 1:
+            return res.ravel()
+        else:
+            return res
+
+
+def get_shortest_path(adjacency: sparse.csr_matrix, sources: Union[int, Iterable], targets: Union[int, Iterable],
+                      method: str = 'D', unweighted: bool = False, n_jobs: Optional[int] = None):
+    """Compute the shortest paths in the graph.
+
+    Parameters
+    ----------
+    adjacency :
+        The adjacency matrix of the graph
+    sources : int or iterable
+        Sources nodes.
+    targets : int or iterable
+        Target nodes.
+    method :
+        The method to be used.
+
+        * ``'D'`` (Dijkstra),
+        * ``'BF'`` (Bellman-Ford),
+        * ``'J'`` (Johnson).
+    unweighted :
+        If ``True``, the weights of the edges are ignored
+    n_jobs :
+        If an integer value is given, denotes the number of workers to use (-1 means the maximum number will be used).
+        If ``None``, no parallel computations are made.
+
+    Returns
+    -------
+    paths : list
+        If single source and single target, return a list containing the nodes on the path from source to target.
+        If multiple sources or multiple targets, return a list of paths as lists.
+        An empty list means that the path does not exist.
+
+    Examples
+    --------
+    >>> from sknetwork.data import linear_digraph
+    >>> adjacency = linear_digraph(3)
+    >>> get_shortest_path(adjacency, 0, 2)
+    [0, 1, 2]
+    >>> get_shortest_path(adjacency, 2, 0)
+    []
+    >>> get_shortest_path(adjacency, 0, [1, 2])
+    [[0, 1], [0, 1, 2]]
+    >>> get_shortest_path(adjacency, [0, 1], 2)
+    [[0, 1, 2], [1, 2]]
+    """
+    if np.issubdtype(type(sources), np.integer):
+        sources = [sources]
+    if np.issubdtype(type(targets), np.integer):
+        targets = [targets]
+
+    if len(sources) == 1:
+        source2target = True
+        source = sources[0]
+    elif len(targets) == 1:
+        source2target = False
+        source = targets[0]
+        targets = sources
+    else:
+        raise ValueError(
+            'This request is ambiguous. Either use one source and multiple targets or multiple sources and one target.')
+
+    if source2target:
+        dists, preds = get_distances(adjacency, source, method, True, unweighted, n_jobs)
+    else:
+        dists, preds = get_distances(adjacency.T, source, method, True, unweighted, n_jobs)
+
+    paths = []
+    for target in targets:
+        if dists[target] == np.inf:
+            path = []
+        else:
+            path = [target]
+            node = target
+            while node != source:
+                node = preds[node]
+                path.append(node)
+        if source2target:
+            path.reverse()
+        paths.append(path)
+    if len(paths) == 1:
+        paths = paths[0]
+    return paths

sknetwork/path/tests/__init__.py

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

sknetwork/path/tests/test_metrics.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for metrics.py"""
+import unittest
+
+from sknetwork.data import house
+from sknetwork.path import get_diameter, get_eccentricity, get_radius
+
+
+
+class TestMetrics(unittest.TestCase):
+
+    def test_diameter_1(self):
+        adjacency = house()
+        with self.assertRaises(ValueError):
+            get_diameter(adjacency, 2.5)
+    def test_diameter_2(self):
+        adjacency = house()
+        self.assertEqual(get_diameter(adjacency), 2)
+    def test_eccentricity_1(self):
+        adjacency = house()
+        self.assertEqual(get_eccentricity(adjacency, 1), 2)
+    def test_radius_1(self):
+        adjacency = house()
+        self.assertEqual(get_radius(adjacency), 2)
+    def test_radius_2(self):
+        adjacency = house()
+        self.assertEqual(get_radius(adjacency,[0,1]), 2)
+

sknetwork/path/tests/test_search.py

@@ -0,0 +1,25 @@
+#!/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.path import breadth_first_search, depth_first_search
+
+
+class TestSearch(unittest.TestCase):
+
+    def setUp(self) -> None:
+        """Load graph for tests."""
+        self.adjacency = cyclic_digraph(3).astype(bool)
+
+    def test_bfs(self):
+        self.assertTrue((breadth_first_search(
+            self.adjacency, 0, return_predecessors=False) == np.array([0, 1, 2])).all())
+
+    def test_dfs(self):
+        self.assertTrue((depth_first_search(
+            self.adjacency, 0, return_predecessors=False) == np.array([0, 1, 2])).all())

sknetwork/path/tests/test_shortest_path.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+""""tests for shortest_path.py"""
+import unittest
+
+from sknetwork.data import karate_club, cyclic_digraph
+from sknetwork.path.shortest_path import get_distances, get_shortest_path
+import numpy as np
+from scipy.sparse import csr_matrix
+
+
+class TestShortestPath(unittest.TestCase):
+
+    def test_parallel(self):
+        adjacency = karate_club()
+        dist1 = get_distances(adjacency)
+        dist2 = get_distances(adjacency, n_jobs=-1)
+        self.assertTrue((dist1 == dist2).all())
+
+    def test_predecessors(self):
+        adjacency = karate_club()
+        _, predecessors = get_distances(adjacency, return_predecessors=True)
+        self.assertTupleEqual(predecessors.shape, adjacency.shape)
+
+    def test_shortest_paths(self):
+        with self.assertRaises(ValueError):
+            get_shortest_path(cyclic_digraph(3), [0, 1], [0, 1])
+
+    def test_error_on_parallel_FW(self):
+        adjacency = karate_club()
+        self.assertRaises(ValueError, get_distances, adjacency, n_jobs=2, method='FW')
+
+    def test_error_neg_cycle_parallel(self):
+        adj = np.ones((5, 5), dtype=int)
+        adj[:][:] = -1
+        adj = csr_matrix(adj)
+        with self.assertRaises(ValueError):
+            get_distances(adj, method='BF', n_jobs=2)
+
+    def test_error_neg_cycle(self):
+        adj = np.ones((5, 5), dtype=int)
+        adj[:][:] = -1
+        adj = csr_matrix(adj)
+        with self.assertRaises(ValueError):
+            get_distances(adj, method='BF', n_jobs=1)

sknetwork/ranking/__init__.py

@@ -0,0 +1,9 @@
+"""ranking module"""
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.ranking.betweenness import Betweenness
+from sknetwork.ranking.closeness import Closeness
+from sknetwork.ranking.harmonic import Harmonic
+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,56 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on November 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from abc import ABC
+
+import numpy as np
+
+from sknetwork.utils.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 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 fit_transform(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the scores. Alias for ``fit_predict``.
+        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,99 @@
+# distutils: language = c++
+# cython: language_level=3
+# cython: linetrace=True
+# distutils: define_macros=CYTHON_TRACE_NOGIL=1
+"""
+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,95 @@
+#!/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):
+    """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.
+
+    For a directed graph, the closeness centrality is computed in terms of outgoing paths.
+
+    Parameters
+    ----------
+    method :
+        Denotes if the results should be exact or approximate.
+    tol: float
+        If ``method=='approximate'``, the allowed tolerance on each score entry.
+    n_jobs:
+        If an integer value is given, denotes the number of workers to use (-1 means the maximum number will be used).
+        If ``None``, no parallel computations are made.
+
+    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, n_jobs: Optional[int] = None):
+        super(Closeness, self).__init__()
+
+        self.method = method
+        self.tol = tol
+        self.n_jobs = n_jobs
+
+    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'.")
+
+        dists = get_distances(adjacency, n_jobs=self.n_jobs, sources=sources)
+
+        self.scores_ = ((n - 1) * n_sources / n) / dists.T.dot(np.ones(n_sources))
+
+        return self