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

sknetwork/linkpred/base.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2022
+@author: Thomas Bonald <thomas.bonald@telecom-paris.fr>
+"""
+from abc import ABC
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.base import Algorithm
+
+
+class BaseLinker(Algorithm, ABC):
+    """Base class for link prediction.
+
+    Attributes
+    ----------
+    links_: sparse.csr_matrix
+        Link matrix.
+    """
+
+    def __init__(self):
+        self.links_ = None
+
+    def predict(self) -> sparse.csr_matrix:
+        """Return the predicted links.
+
+        Returns
+        -------
+        links_ : sparse.csr_matrix
+            Link matrix.
+        """
+        return self.links_
+
+    def fit_predict(self, *args, **kwargs) -> sparse.csr_matrix:
+        """Fit algorithm to data and return the links. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        links_ : sparse.csr_matrix
+            Link matrix.
+        """
+        self.fit(*args, **kwargs)
+        return self.links_

sknetwork/linkpred/nn.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2023
+@author: Thomas Bonald <thomas.bonald@telecom-paris.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.linkpred.base import BaseLinker
+from sknetwork.embedding.base import BaseEmbedding
+from sknetwork.linalg.normalizer import normalize
+from sknetwork.utils.check import check_n_neighbors
+from sknetwork.utils.format import get_adjacency
+
+
+class NNLinker(BaseLinker):
+    """Link prediction by nearest neighbors in the embedding space, using cosine similarity.
+
+    For bipartite graphs, predict links between rows and columns only.
+
+    Parameters
+    ----------
+    n_neighbors : int
+        Number of nearest neighbors. If ``None``, all nodes are considered.
+    threshold : float
+        Threshold on cosine similarity. Only links above this threshold are kept.
+    embedding_method : :class:`BaseEmbedding`
+        Embedding method used to represent nodes in vector space.
+        If ``None`` (default), use identity.
+
+    Attributes
+    ----------
+    links\_ : sparse.csr_matrix
+        Link matrix.
+
+    Example
+    -------
+    >>> from sknetwork.linkpred import NNLinker
+    >>> from sknetwork.data import karate_club
+    >>> linker = NNLinker(n_neighbors=5, threshold=0.5)
+    >>> graph = karate_club(metadata=True)
+    >>> adjacency = graph.adjacency
+    >>> links = linker.fit_predict(adjacency)
+    >>> links.shape
+    (34, 34)
+    """
+    def __init__(self, n_neighbors: Optional[int] = 10, threshold: float = 0,
+                 embedding_method: Optional[BaseEmbedding] = None):
+        super(NNLinker, self).__init__()
+        self.n_neighbors = n_neighbors
+        self.threshold = threshold
+        self.embedding_method = embedding_method
+        self.bipartite = None
+
+    def _fit_core(self, embedding, mask):
+        n = embedding.shape[0]
+        n_row = len(mask)
+        if n_row < n:
+            # bipartite graphs
+            index_col = np.arange(n_row, n)
+            n_col = n - n_row
+        else:
+            index_col = np.arange(n)
+            n_col = n
+        n_neighbors = check_n_neighbors(self.n_neighbors, n_col)
+
+        row = []
+        col = []
+        data = []
+
+        for i in np.flatnonzero(mask):
+            vector = embedding[i]
+            if sparse.issparse(vector):
+                vector = vector.toarray().ravel()
+            similarities = embedding[index_col].dot(vector)
+            nn = np.argpartition(-similarities, n_neighbors)[:n_neighbors]
+            mask_nn = np.zeros(n_col, dtype=bool)
+            mask_nn[nn] = 1
+            mask_nn[similarities < self.threshold] = 0
+            nn = np.flatnonzero(mask_nn)
+
+            row += len(nn) * [i]
+            col += list(nn)
+            data += list(similarities[nn])
+
+        links = sparse.csr_matrix((data, (row, col)), shape=(n_row, n_col))
+
+        return links
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], index: Optional[np.ndarray] = None) -> 'NNLinker':
+        """Link prediction by nearest neighbors in the embedding space, using cosine similarity
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        index : np.ndarray
+            Index of source nodes to consider. If ``None``, the links are predicted for all nodes.
+
+        Returns
+        -------
+        self: :class:`NN`
+        """
+        n_row, _ = input_matrix.shape
+
+        adjacency, self.bipartite = get_adjacency(input_matrix)
+
+        if index is None:
+            index = np.arange(n_row)
+        mask = np.zeros(n_row, dtype=bool)
+        mask[index] = 1
+
+        if self.embedding_method is None:
+            embedding = adjacency
+        else:
+            embedding = self.embedding_method.fit_transform(adjacency)
+
+        embedding = normalize(embedding, p=2)
+        links = self._fit_core(embedding, mask)
+
+        self.links_ = links
+
+        return self

sknetwork/linkpred/tests/__init__.py

@@ -0,0 +1 @@
+"""tests for link prediction"""

sknetwork/linkpred/tests/test_nn.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Tests for link prediction by nearest neighbors"""
+import unittest
+
+from sknetwork.linkpred import NNLinker
+from sknetwork.data.test_graphs import *
+from sknetwork.embedding import Spectral
+from sknetwork.utils import get_degrees
+
+
+class TestNNLinker(unittest.TestCase):
+
+    def test_link_prediction(self):
+        for input_matrix in [test_graph(), test_digraph(), test_bigraph()]:
+            n_neighbors = 2
+            threshold = 0.5
+            algo = NNLinker(n_neighbors=n_neighbors, threshold=threshold)
+            links = algo.fit_predict(input_matrix)
+            self.assertTrue(links.shape == input_matrix.shape)
+            self.assertTrue(np.all(get_degrees(links) <= n_neighbors))
+            self.assertTrue(np.all(links.data >= threshold))
+
+            algo = NNLinker(embedding_method=Spectral(2))
+            links = algo.fit_predict(input_matrix)
+            self.assertTrue(links.shape == input_matrix.shape)

sknetwork/log.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in December 2019
+@author: Quentin Lutz <qlutz@enst.fr>
+"""
+
+
+class Log:
+    """Log class for verbosity features"""
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+        self.log = ''
+
+    def print_log(self, *args):
+        """Fill log with text."""
+        if self.verbose:
+            print(*args)
+        self.log += ' '.join(map(str, args)) + '\n'

sknetwork/path/__init__.py

@@ -0,0 +1,5 @@
+"""Path module"""
+from sknetwork.path.dag import get_dag
+from sknetwork.path.distances import get_distances
+from sknetwork.path.search import breadth_first_search
+from sknetwork.path.shortest_path import get_shortest_path

sknetwork/path/dag.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in May 2023
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from typing import Iterable, Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.path.distances import get_distances
+from sknetwork.utils.check import check_format, check_square
+
+
+def get_dag(adjacency: sparse.csr_matrix, source: Optional[Union[int, Iterable]] = None,
+            order: Optional[np.ndarray] = None) -> sparse.csr_matrix:
+    """Get a Directed Acyclic Graph (DAG) from a graph.
+    If the order is specified, keep only edges i -> j such that 0 <= order[i] < order[j].
+    If the source is specified, use the distances from this source node (or set of source nodes) as order.
+    If neither the order nor the source is specified, use the node indices as order.
+
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    source :
+        Source node (or set of source nodes).
+    order :
+        Order of nodes. Negative values ignored.
+
+    Returns
+    -------
+    dag :
+        Adjacency matrix of the directed acyclic graph.
+    """
+    adjacency = check_format(adjacency, allow_empty=True)
+    check_square(adjacency)
+
+    if order is None:
+        if source is None:
+            order = np.arange(adjacency.shape[0])
+        else:
+            order = get_distances(adjacency, source)
+
+    dag = adjacency.astype(bool).tocoo()
+    for value in np.unique(order):
+        if value < 0:
+            dag.data[order[dag.row] == value] = 0
+        else:
+            dag.data[(order[dag.row] == value) & (order[dag.col] <= value)] = 0
+    dag.eliminate_zeros()
+
+    return dag.tocsr()

sknetwork/path/distances.py

@@ -0,0 +1,98 @@
+#!/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.utils.format import get_adjacency
+
+
+def get_distances(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, transpose: bool = False,
+                  force_bipartite: bool = False) \
+        -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray]]:
+    """Get the distances 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 or array, indices of source nodes (the shortest distances to one of these nodes is 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``).
+    transpose :
+        If ``True``, transpose the input matrix.
+    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 re specified.
+
+    Returns
+    -------
+    distances : np.ndarray of shape (n_nodes,)
+        Vector of distances from source (distance = -1 if no path exists from the source).
+        For a bipartite graph, two vectors are returned, one for the rows and one for the columns.
+
+    Examples
+    --------
+    >>> from sknetwork.data import cyclic_digraph
+    >>> adjacency = cyclic_digraph(3)
+    >>> get_distances(adjacency, source=0)
+    array([0, 1, 2])
+    >>> get_distances(adjacency, source=[0, 2])
+    array([0, 1, 0])
+    """
+    if transpose:
+        matrix = sparse.csr_matrix(input_matrix.T)
+    else:
+        matrix = input_matrix
+    if source_row is not None or source_col is not None:
+        force_bipartite = True
+    adjacency, bipartite = get_adjacency(matrix, force_bipartite=force_bipartite, allow_empty=True)
+    adjacency_transpose = adjacency.astype(bool).T.tocsr()
+    n_row, n_col = matrix.shape
+    n_nodes = adjacency.shape[0]
+
+    mask = np.zeros(n_nodes, dtype=bool)
+    if bipartite:
+        if source is not None:
+            if source_row is not None:
+                raise ValueError('Only one of the parameters source and source_row can be specified.')
+            source_row = source
+        if source_row is None and source_col is None:
+            raise ValueError('At least one of the parameters source_row or source_col must be specified.')
+        if source_row is not None:
+            mask[source_row] = 1
+        if source_col is not None:
+            mask[n_row + np.array(source_col)] = 1
+    else:
+        if source is None:
+            raise ValueError('The parameter source must be specified.')
+        mask[source] = 1
+
+    distances = -np.ones(n_nodes, dtype=int)
+    distances[mask] = 0
+
+    distance = 0
+    reach = mask
+
+    while 1:
+        distance += 1
+        mask = adjacency_transpose.dot(reach).astype(bool) & ~reach
+        if np.sum(mask) == 0:
+            break
+        distances[mask] = distance
+        reach |= mask
+
+    if bipartite:
+        return distances[:n_row], distances[n_row:]
+    else:
+        return distances

sknetwork/path/search.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in May 2023
+"""
+import numpy as np
+from scipy import sparse
+
+from sknetwork.path.distances import get_distances
+
+
+def breadth_first_search(adjacency: sparse.csr_matrix, source: int):
+    """Breadth-first ordering starting from some node.
+
+    Parameters
+    ----------
+    adjacency :
+        Adjacency matrix of the graph.
+    source : int
+        Source node.
+
+    Returns
+    -------
+    index : np.ndarray
+        Node index corresponding to the breadth-first-search from the source.
+        The length of the vector is the number of nodes reachable from the source.
+    """
+    distances = get_distances(adjacency, source)
+    indices = np.argsort(distances)
+    n = np.sum(distances < 0)
+    return indices[n:]

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