scikit-network 0.33.0__cp312-cp312-macosx_11_0_arm64.whl

sknetwork/ranking/pagerank.py

@@ -0,0 +1,110 @@
+#!/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.
+    scores_row_: np.ndarray
+        Scores of rows, for bipartite graphs.
+    scores_col_: np.ndarray
+        Scores of columns, for bipartite graphs.
+
+    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.)

sknetwork/ranking/tests/test_postprocess.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for postprocessing"""
+
+import unittest
+
+import numpy as np
+
+from sknetwork.ranking.postprocess import top_k
+
+
+class TestPostprocessing(unittest.TestCase):
+
+    def test_top_k(self):
+        scores = np.arange(10)
+        index = top_k(scores, 3)
+        self.assertTrue(set(index) == {7, 8, 9})
+        index = top_k(scores, 10)
+        self.assertTrue(len(index) == 10)
+        index = top_k(scores, 20)
+        self.assertTrue(len(index) == 10)
+        scores = [3, 1, 6, 2]
+        index = top_k(scores, 2)
+        self.assertTrue(set(index) == {0, 2})
+        index = top_k(scores, 2, sort=True)
+        self.assertTrue(list(index) == [2, 0])

sknetwork/regression/__init__.py

@@ -0,0 +1,4 @@
+"""regression module"""
+from sknetwork.regression.base import BaseRegressor
+from sknetwork.regression.diffusion import Diffusion, Dirichlet
+

sknetwork/regression/base.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on April 2022
+@author: Thomas Bonald <bonald@enst.fr>
+"""
+from abc import ABC
+
+import numpy as np
+
+from sknetwork.base import Algorithm
+
+
+class BaseRegressor(Algorithm, ABC):
+    """Base class for regression algorithms.
+
+    Attributes
+    ----------
+    values_ : np.ndarray
+        Value of each node.
+    values_row_: np.ndarray
+        Values of rows, for bipartite graphs.
+    values_col_: np.ndarray
+        Values of columns, for bipartite graphs.
+    """
+    def __init__(self):
+        self.values_ = None
+
+    def predict(self, columns: bool = False) -> np.ndarray:
+        """Return the values predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        values : np.ndarray
+            Values.
+        """
+        if columns:
+            return self.values_col_
+        return self.values_
+
+    def fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the values. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        values : np.ndarray
+            Values.
+        """
+        self.fit(*args, **kwargs)
+        return self.values_
+
+    def _split_vars(self, shape):
+        n_row = shape[0]
+        self.values_row_ = self.values_[:n_row]
+        self.values_col_ = self.values_[n_row:]
+        self.values_ = self.values_row_

sknetwork/regression/diffusion.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in July 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Thomas Bonald <thomas.bonald@telecom-paris.fr>
+"""
+from typing import Union, Optional, Tuple
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.linalg.normalizer import normalize
+from sknetwork.regression.base import BaseRegressor
+from sknetwork.utils import get_adjacency_values, get_degrees
+
+
+def init_temperatures(seeds: np.ndarray, init: Optional[float]) -> Tuple[np.ndarray, np.ndarray]:
+    """Init temperatures."""
+    n = len(seeds)
+    border = (seeds >= 0)
+    if init is None:
+        temperatures = seeds[border].mean() * np.ones(n)
+    else:
+        temperatures = init * np.ones(n)
+    temperatures[border] = seeds[border]
+    return temperatures, border
+
+
+class Diffusion(BaseRegressor):
+    """Regression by diffusion along the edges, given the temperatures of some seed nodes (heat equation).
+
+    The row vector of tempreatures :math:`T` evolves like:
+
+    :math:`T \\gets (1-\\alpha) T + \\alpha  PT`
+
+    where :math:`\\alpha` is the damping factor and :math:`P` is the transition matrix of the random walk in the graph.
+
+    All values are updated, including those of seed nodes (free diffusion).
+    See ``Dirichlet`` for diffusion with boundary constraints.
+
+    Parameters
+    ----------
+    n_iter : int
+        Number of iterations of the diffusion (must be positive).
+    damping_factor : float
+        Damping factor.
+
+    Attributes
+    ----------
+    values_ : np.ndarray
+        Value of each node (= temperature).
+    values_row_: np.ndarray
+        Values of rows, for bipartite graphs.
+    values_col_: np.ndarray
+        Values of columns, for bipartite graphs.
+    Example
+    -------
+    >>> from sknetwork.data import house
+    >>> diffusion = Diffusion(n_iter=1)
+    >>> adjacency = house()
+    >>> values = {0: 1, 2: 0}
+    >>> values_pred = diffusion.fit_predict(adjacency, values)
+    >>> np.round(values_pred, 1)
+    array([0.8, 0.5, 0.2, 0.4, 0.6])
+
+    References
+    ----------
+    Chung, F. (2007). The heat kernel as the pagerank of a graph. Proceedings of the National Academy of Sciences.
+    """
+    def __init__(self, n_iter: int = 3, damping_factor: float = 0.5):
+        super(Diffusion, self).__init__()
+
+        if n_iter <= 0:
+            raise ValueError('The number of iterations must be positive.')
+        else:
+            self.n_iter = n_iter
+        self.damping_factor = damping_factor
+        self.bipartite = None
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray],
+            values: Optional[Union[dict, list, np.ndarray]] = None,
+            values_row: Optional[Union[dict, list, np.ndarray]] = None,
+            values_col: Optional[Union[dict, list, np.ndarray]] = None, init: Optional[float] = None,
+            force_bipartite: bool = False) -> 'Diffusion':
+        """Compute the diffusion (temperatures at equilibrium).
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        values :
+            Temperatures of nodes in initial state (dictionary or vector). Negative temperatures ignored.
+        values_row, values_col :
+            Temperatures of rows and columns for bipartite graphs. Negative temperatures ignored.
+        init :
+            Temperature of nodes in initial state.
+            If ``None``, use the average temperature of seed nodes (default).
+        force_bipartite :
+            If ``True``, consider the input matrix as a biadjacency matrix (default = ``False``).
+
+        Returns
+        -------
+        self: :class:`Diffusion`
+        """
+        adjacency, values, self.bipartite = get_adjacency_values(input_matrix, force_bipartite=force_bipartite,
+                                                                 values=values,
+                                                                 values_row=values_row,
+                                                                 values_col=values_col)
+        values, _ = init_temperatures(values, init)
+        diffusion = normalize(adjacency.T.tocsr())
+        degrees = get_degrees(diffusion)
+        diag = sparse.diags((degrees == 0).astype(int)).tocsr()
+        diffusion += diag
+
+        diffusion = (1 - self.damping_factor) * sparse.identity(len(degrees)).tocsr() + self.damping_factor * diffusion
+
+        for i in range(self.n_iter):
+            values = diffusion.dot(values)
+
+        self.values_ = values
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+
+        return self
+
+
+class Dirichlet(BaseRegressor):
+    """Regression by the Dirichlet problem (heat diffusion with boundary constraints).
+
+    The temperatures of some seed nodes are fixed. The temperatures of other nodes are computed.
+
+    Parameters
+    ----------
+    n_iter : int
+        Number of iterations of the diffusion (must be positive).
+
+    Attributes
+    ----------
+    values_ : np.ndarray
+        Value of each node (= temperature).
+    values_row_: np.ndarray
+        Values of rows, for bipartite graphs.
+    values_col_: np.ndarray
+        Values of columns, for bipartite graphs.
+    Example
+    -------
+    >>> from sknetwork.regression import Dirichlet
+    >>> from sknetwork.data import house
+    >>> dirichlet = Dirichlet()
+    >>> adjacency = house()
+    >>> values = {0: 1, 2: 0}
+    >>> values_pred = dirichlet.fit_predict(adjacency, values)
+    >>> np.round(values_pred, 2)
+    array([1.  , 0.54, 0.  , 0.31, 0.62])
+
+    References
+    ----------
+    Chung, F. (2007). The heat kernel as the pagerank of a graph. Proceedings of the National Academy of Sciences.
+    """
+    def __init__(self, n_iter: int = 10):
+        super(Dirichlet, self).__init__()
+
+        if n_iter <= 0:
+            raise ValueError('The number of iterations must be positive.')
+        else:
+            self.n_iter = n_iter
+        self.bipartite = None
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray],
+            values: Optional[Union[dict, list, np.ndarray]] = None,
+            values_row: Optional[Union[dict, list, np.ndarray]] = None,
+            values_col: Optional[Union[dict, list, np.ndarray]] = None, init: Optional[float] = None,
+            force_bipartite: bool = False) -> 'Dirichlet':
+        """Compute the solution to the Dirichlet problem (temperatures at equilibrium).
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        values :
+            Temperatures of nodes (dictionary or vector). Negative temperatures ignored.
+        values_row, values_col :
+            Temperatures of rows and columns for bipartite graphs. Negative temperatures ignored.
+        init :
+            Temperature of nodes in initial state.
+            If ``None``, use the average temperature of seed nodes (default).
+        force_bipartite :
+            If ``True``, consider the input matrix as a biadjacency matrix (default = ``False``).
+
+        Returns
+        -------
+        self: :class:`Dirichlet`
+        """
+        adjacency, values, self.bipartite = get_adjacency_values(input_matrix, force_bipartite=force_bipartite,
+                                                                 values=values,
+                                                                 values_row=values_row,
+                                                                 values_col=values_col)
+        temperatures, border = init_temperatures(values, init)
+        values = temperatures.copy()
+        diffusion = normalize(adjacency)
+        for i in range(self.n_iter):
+            values = diffusion.dot(values)
+            values[border] = temperatures[border]
+
+        self.values_ = values
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+
+        return self

sknetwork/regression/tests/__init__.py

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

sknetwork/regression/tests/test_API.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for regression API"""
+import unittest
+
+from sknetwork.data.test_graphs import test_bigraph, test_graph, test_digraph
+from sknetwork.regression import *
+
+
+class TestAPI(unittest.TestCase):
+
+    def test_basic(self):
+        methods = [Diffusion(), Dirichlet()]
+        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 = [Diffusion(), Dirichlet()]
+        for method in methods:
+            method.fit(biadjacency)
+            values_row = method.values_row_
+            values_col = method.values_col_
+
+            self.assertEqual(values_row.shape, (n_row,))
+            self.assertEqual(values_col.shape, (n_col,))