scikit-network 0.28.3__cp39-cp39-macosx_12_0_arm64.whl

sknetwork/ranking/harmonic.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on November 19 2019
+@author: Quentin Lutz <qlutz@enst.fr>
+"""
+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
+
+
+class Harmonic(BaseRanking):
+    """Harmonic centrality of each node in a connected graph, corresponding to the average inverse length of
+    the shortest paths from that node to all the other ones.
+
+    For a directed graph, the harmonic centrality is computed in terms of outgoing paths.
+
+    Parameters
+    ----------
+    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
+        Score of each node.
+
+    Example
+    -------
+    >>> from sknetwork.ranking import Harmonic
+    >>> from sknetwork.data import house
+    >>> harmonic = Harmonic()
+    >>> adjacency = house()
+    >>> scores = harmonic.fit_predict(adjacency)
+    >>> np.round(scores, 2)
+    array([3. , 3.5, 3. , 3. , 3.5])
+
+    References
+    ----------
+    Marchiori, M., & Latora, V. (2000).
+    `Harmony in the small-world.
+    <https://arxiv.org/pdf/cond-mat/0008357.pdf>`_
+    Physica A: Statistical Mechanics and its Applications, 285(3-4), 539-546.
+    """
+
+    def __init__(self, n_jobs: Optional[int] = None):
+        super(Harmonic, self).__init__()
+
+        self.n_jobs = n_jobs
+
+    def fit(self, adjacency: Union[sparse.csr_matrix, np.ndarray]) -> 'Harmonic':
+        """Harmonic centrality for connected graphs.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`Harmonic`
+        """
+        adjacency = check_format(adjacency)
+        check_square(adjacency)
+        n = adjacency.shape[0]
+        indices = np.arange(n)
+
+        dists = get_distances(adjacency, n_jobs=self.n_jobs, sources=indices)
+
+        np.fill_diagonal(dists, 1)
+        inv = (1 / dists)
+        np.fill_diagonal(inv, 0)
+
+        self.scores_ = inv.dot(np.ones(n))
+
+        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,81 @@
+#!/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}`.
+
+    Parameters
+    ----------
+    damping_factor : float
+        Decay parameter for path contributions.
+    path_length : int
+        Maximum length of the paths to take into account.
+
+    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

sknetwork/ranking/pagerank.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on 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 scipy.sparse.linalg import LinearOperator
+
+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_seeds
+from sknetwork.utils.verbose import VerboseMixin
+
+
+class PageRank(BaseRanking, VerboseMixin):
+    """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()
+    >>> seeds = {0: 1}
+    >>> scores = pagerank.fit_predict(adjacency, seeds)
+    >>> 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, LinearOperator],
+            seeds: Optional[Union[dict, np.ndarray]] = None, seeds_row: Optional[Union[dict, np.ndarray]] = None,
+            seeds_col: Optional[Union[dict, np.ndarray]] = None, force_bipartite: bool = False) -> 'PageRank':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        seeds :
+            Parameter to be used for Personalized PageRank.
+            Restart distribution as a vector or a dict (node: weight).
+            If ``None``, the uniform distribution is used (no personalization, default).
+        seeds_row, seeds_col :
+            Parameter to be used for Personalized PageRank on bipartite graphs.
+            Restart distribution as vectors or dicts on rows, columns (node: weight).
+            If both seeds_row and seeds_col are ``None`` (default), the uniform distribution on rows is used.
+        force_bipartite :
+            If ``True``, consider the input matrix as the biadjacency matrix of a bipartite graph.
+        Returns
+        -------
+        self: :class:`PageRank`
+        """
+        adjacency, seeds, self.bipartite = get_adjacency_seeds(input_matrix, force_bipartite=force_bipartite,
+                                                               seeds=seeds, seeds_row=seeds_row,
+                                                               seeds_col=seeds_col, default_value=0, which='probs')
+        self.scores_ = get_pagerank(adjacency, seeds, 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,25 @@
+#!/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):
+    """Return the indices of the k elements of highest values.
+
+    Parameters
+    ----------
+    scores : np.ndarray
+        Array of values.
+    k : int
+        Number of elements to return.
+
+    Examples
+    --------
+    >>> top_k([1, 3, 2], k=2)
+    array([1, 2])
+    """
+    return np.argpartition(-np.array(scores), k)[:k]

sknetwork/ranking/tests/__init__.py

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

sknetwork/ranking/tests/test_API.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""tests for ranking API"""
+import unittest
+
+from sknetwork.data.test_graphs import test_bigraph, test_graph, test_digraph
+from sknetwork.ranking import *
+
+
+class TestPageRank(unittest.TestCase):
+
+    def test_basic(self):
+        methods = [PageRank(), Closeness(), HITS(), Harmonic(), 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)
+                score = method.fit_transform(adjacency)
+                self.assertEqual(score.shape, (n,))
+
+    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_graph_disconnect
+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_graph_disconnect()
+        betweenness = Betweenness()
+        with self.assertRaises(ValueError):
+            betweenness.fit(adjacency)
+
+    def test_bipartite(self):
+        adjacency = star_wars()
+        betweenness = Betweenness()
+
+        with self.assertRaises(ValueError):
+            betweenness.fit_transform(adjacency)

sknetwork/ranking/tests/test_closeness.py

@@ -0,0 +1,34 @@
+#!/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')
+        scores1 = closeness.fit_predict(adjacency)
+        closeness = Closeness(method='approximate', n_jobs=-1)
+        scores2 = closeness.fit_predict(adjacency)
+
+        self.assertEqual(scores1.shape, (n,))
+        self.assertAlmostEqual(np.linalg.norm(scores1 - scores2), 0)
+
+    def test_disconnected(self):
+        adjacency = test_graph_disconnect()
+        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,69 @@
+#!/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_bigraph
+from sknetwork.ranking.pagerank import PageRank
+from sknetwork.utils import co_neighbor_graph
+
+
+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_transform(self.adjacency, seeds_array)
+        scores2 = pagerank.fit_transform(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_transform(self.adjacency)
+        self.assertAlmostEqual(np.linalg.norm(scores - self.truth), 0.)
+
+        pagerank = PageRank(damping_factor=0.01)
+        scores = pagerank.fit_transform(self.adjacency)
+        self.assertAlmostEqual(np.linalg.norm(scores - self.truth), 0.)
+
+    def test_copagerank(self):
+        seeds = {0: 1}
+        biadjacency = test_bigraph()
+
+        adjacency = co_neighbor_graph(biadjacency, method='exact', normalized=True)
+        pagerank = PageRank(damping_factor=0.85, solver='lanczos')
+        pagerank.fit(biadjacency, seeds_row=seeds)
+        scores1 = pagerank.scores_row_
+        scores1 /= scores1.sum()
+        scores2 = PageRank(damping_factor=0.85**2, solver='lanczos').fit_transform(adjacency, seeds)
+        self.assertAlmostEqual(np.linalg.norm(scores1 - scores2), 0., places=6)

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,56 @@
+#!/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.utils.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 fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the scores. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        values : np.ndarray
+            Values.
+        """
+        self.fit(*args, **kwargs)
+        return self.values_
+
+    def fit_transform(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the scores. Alias for ``fit_transform``.
+        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_