scikit-network 0.33.3__cp313-cp313-win_amd64.whl

sknetwork/classification/base.py

@@ -0,0 +1,142 @@
+#!/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 scipy import sparse
+
+from sknetwork.base import Algorithm
+
+
+class BaseClassifier(Algorithm, ABC):
+    """Base class for classifiers.
+
+    Attributes
+    ----------
+    bipartite : bool
+        If ``True``, the fitted graph is bipartite.
+    labels_ : np.ndarray, shape (n_labels,)
+        Labels of nodes.
+    probs_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distribution over labels (soft classification).
+    labels_row_ , labels_col_ : np.ndarray
+        Labels of rows and columns (for bipartite graphs).
+    probs_row_, probs_col_ : sparse.csr_matrix, shapes (n_row, n_labels) and (n_col, n_labels)
+        Probability distributions over labels for rows and columns (for bipartite graphs).
+    """
+
+    def __init__(self):
+        self.bipartite = None
+        self.labels_ = None
+        self.probs_ = None
+        self.labels_row_ = None
+        self.labels_col_ = None
+        self.probs_row_ = None
+        self.probs_col_ = None
+
+    def predict(self, columns: bool = False) -> np.ndarray:
+        """Return the labels predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Labels.
+        """
+        if columns:
+            return self.labels_col_
+        return self.labels_
+
+    def fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to the data and return the labels. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Labels.
+        """
+        self.fit(*args, **kwargs)
+        return self.predict()
+
+    def predict_proba(self, columns=False) -> np.ndarray:
+        """Return the probability distribution over labels as predicted by the algorithm.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        probs : np.ndarray
+            Probability distribution over labels.
+        """
+        if columns:
+            return self.probs_col_.toarray()
+        return self.probs_.toarray()
+
+    def fit_predict_proba(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to the data and return the probability distribution over labels.
+        Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        probs : np.ndarray
+            Probability of each label.
+        """
+        self.fit(*args, **kwargs)
+        return self.predict_proba()
+
+    def transform(self, columns=False) -> sparse.csr_matrix:
+        """Return the probability distribution over labels in sparse format.
+
+        Parameters
+        ----------
+        columns : bool
+            If ``True``, return the prediction for columns.
+
+        Returns
+        -------
+        probs : sparse.csr_matrix
+            Probability distribution over labels.
+        """
+        if columns:
+            return self.probs_col_
+        return self.probs_
+
+    def fit_transform(self, *args, **kwargs) -> sparse.csr_matrix:
+        """Fit algorithm to the data and return the probability distribution over labels in sparse format.
+        Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        probs : sparse.csr_matrix
+            Probability distribution over labels.
+        """
+        self.fit(*args, **kwargs)
+        return self.transform()
+
+    def _split_vars(self, shape: tuple):
+        """Split variables for bipartite graphs."""
+        if self.bipartite:
+            n_row = shape[0]
+            self.labels_row_ = self.labels_[:n_row]
+            self.labels_col_ = self.labels_[n_row:]
+            self.labels_ = self.labels_row_
+            self.probs_row_ = self.probs_[:n_row]
+            self.probs_col_ = self.probs_[n_row:]
+            self.probs_ = self.probs_row_
+        else:
+            self.labels_row_ = self.labels_
+            self.labels_col_ = self.labels_
+            self.probs_row_ = self.probs_
+            self.probs_col_ = self.probs_
+        return self

sknetwork/classification/base_rank.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2020
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from functools import partial
+from multiprocessing import Pool
+from typing import Union, Optional
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.classification.base import BaseClassifier
+from sknetwork.linalg.normalizer import normalize
+from sknetwork.ranking.base import BaseRanking
+from sknetwork.utils.check import check_labels, check_n_jobs
+from sknetwork.utils.format import get_adjacency_values
+
+
+class RankClassifier(BaseClassifier):
+    """Generic class for ranking based classifiers.
+
+    Parameters
+    ----------
+    algorithm :
+        Which ranking algorithm to use.
+    n_jobs :
+        If positive, number of parallel jobs allowed (-1 means maximum number).
+        If ``None``, no parallel computations are made.
+
+    Attributes
+    ----------
+    labels_ : np.ndarray, shape (n_labels,)
+        Label of each node.
+    probs_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distribution over labels.
+    labels_row_, labels_col_ : np.ndarray
+        Labels of rows and columns, for bipartite graphs.
+    probs_row_, probs_col_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distributions over labels for rows and columns (for bipartite graphs).
+    """
+    def __init__(self, algorithm: BaseRanking, n_jobs: Optional[int] = None, verbose: bool = False):
+        super(RankClassifier, self).__init__()
+
+        self.algorithm = algorithm
+        self.n_jobs = check_n_jobs(n_jobs)
+        self.verbose = verbose
+
+    @staticmethod
+    def _process_labels(labels: np.ndarray) -> list:
+        """Make one-vs-all binary labels from labels.
+
+        Parameters
+        ----------
+        labels
+
+        Returns
+        -------
+        List of binary labels.
+        """
+        labels_all = []
+        labels_unique, _ = check_labels(labels)
+
+        for label in labels_unique:
+            labels_binary = np.array(labels == label).astype(int)
+            labels_all.append(labels_binary)
+
+        return labels_all
+
+    @staticmethod
+    def _process_scores(scores: np.ndarray) -> np.ndarray:
+        """Post-processing of the scores.
+
+        Parameters
+        ----------
+        scores
+            Matrix of scores, shape number of nodes x number of labels.
+
+        Returns
+        -------
+        scores : np.ndarray
+        """
+        return scores
+
+    def _split_vars(self, shape):
+        """Split the vector of labels and build membership matrix."""
+        n_row = shape[0]
+        self.labels_row_ = self.labels_[:n_row]
+        self.labels_col_ = self.labels_[n_row:]
+        self.labels_ = self.labels_row_
+        self.probs_row_ = self.probs_[:n_row]
+        self.probs_col_ = self.probs_[n_row:]
+        self.probs_ = self.probs_row_
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], labels: Union[np.ndarray, dict] = None,
+            labels_row: Union[np.ndarray, dict] = None, labels_col: Union[np.ndarray, dict] = None) -> 'RankClassifier':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+        labels :
+            Known labels (dictionary or array; negative values ignored).
+        labels_row, labels_col :
+            Known labels on rows and columns (for bipartite graphs).
+        Returns
+        -------
+        self: :class:`RankClassifier`
+        """
+        adjacency, seeds_labels, bipartite = get_adjacency_values(input_matrix, values=labels, values_row=labels_row,
+                                                                  values_col=labels_col)
+        seeds_labels = seeds_labels.astype(int)
+        labels_unique, n_classes = check_labels(seeds_labels)
+        seeds_all = self._process_labels(seeds_labels)
+        local_function = partial(self.algorithm.fit_predict, adjacency)
+        with Pool(self.n_jobs) as pool:
+            scores = np.array(pool.map(local_function, seeds_all))
+        scores = scores.T
+
+        scores = self._process_scores(scores)
+        scores = normalize(scores)
+
+        probs = sparse.coo_matrix(scores)
+        probs.col = labels_unique[probs.col]
+
+        labels = np.argmax(scores, axis=1)
+        self.labels_ = labels_unique[labels]
+        self.probs_ = sparse.csr_matrix(probs, shape=(adjacency.shape[0], np.max(seeds_labels) + 1))
+        self._split_vars(input_matrix.shape)
+
+        return self

sknetwork/classification/diffusion.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in July 2022
+@author: Thomas Bonald <thomas.bonald@telecom-paris.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.classification.base import BaseClassifier
+from sknetwork.path.distances import get_distances
+from sknetwork.linalg.normalizer import normalize
+from sknetwork.utils.format import get_adjacency_values
+from sknetwork.utils.membership import get_membership
+from sknetwork.utils.neighbors import get_degrees
+
+
+class DiffusionClassifier(BaseClassifier):
+    """Node classification by heat diffusion.
+
+    For each label, the temperature of a node corresponds to its probability to have this label.
+
+    Parameters
+    ----------
+    n_iter : int
+        Number of iterations of the diffusion (discrete time).
+    centering : bool
+        If ``True``, center the temperature of each label to its mean before classification (default).
+    scale : float
+        Multiplicative factor applied to tempreatures before softmax (default = 5).
+        Used only when centering is ``True``.
+
+    Attributes
+    ----------
+    labels_ : np.ndarray, shape (n_labels,)
+        Labels of nodes.
+    probs_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distribution over labels.
+    labels_row_ : np.ndarray
+        Labels of rows, for bipartite graphs.
+    labels_col_ : np.ndarray
+        Labels of columns, for bipartite graphs.
+    probs_row_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distributions over labels of rows, for bipartite graphs.
+    probs_col_ : sparse.csr_matrix, shape (n_col, n_labels)
+        Probability distributions over labels of columns, for bipartite graphs.
+    Example
+    -------
+    >>> from sknetwork.data import karate_club
+    >>> diffusion = DiffusionClassifier()
+    >>> graph = karate_club(metadata=True)
+    >>> adjacency = graph.adjacency
+    >>> labels_true = graph.labels
+    >>> labels = {0: labels_true[0], 33: labels_true[33]}
+    >>> labels_pred = diffusion.fit_predict(adjacency, labels)
+    >>> float(round(np.mean(labels_pred == labels_true), 2))
+    0.97
+
+    References
+    ----------
+    Zhu, X., Lafferty, J., & Rosenfeld, R. (2005). `Semi-supervised learning with graphs`
+    (Doctoral dissertation, Carnegie Mellon University, language technologies institute, school of computer science).
+    """
+    def __init__(self, n_iter: int = 10, centering: bool = True, scale: float = 5):
+        super(DiffusionClassifier, self).__init__()
+
+        if n_iter <= 0:
+            raise ValueError('The number of iterations must be positive.')
+        else:
+            self.n_iter = n_iter
+        self.centering = centering
+        self.scale = scale
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray],
+            labels: Optional[Union[dict, list, np.ndarray]] = None,
+            labels_row: Optional[Union[dict, list, np.ndarray]] = None,
+            labels_col: Optional[Union[dict, list, np.ndarray]] = None, force_bipartite: bool = False) \
+            -> 'DiffusionClassifier':
+        """Compute the solution to the Dirichlet problem (temperatures at equilibrium).
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        labels : dict, np.ndarray
+            Known labels (dictionary or vector of int). Negative values ignored.
+        labels_row : dict, np.ndarray
+            Labels of rows for bipartite graphs. Negative values ignored.
+        labels_col : dict, np.ndarray
+            Labels of columns for bipartite graphs. Negative values ignored.
+        force_bipartite : bool
+            If ``True``, consider the input matrix as a biadjacency matrix (default = ``False``).
+
+        Returns
+        -------
+        self: :class:`DiffusionClassifier`
+        """
+        adjacency, values, self.bipartite = get_adjacency_values(input_matrix, force_bipartite=force_bipartite,
+                                                                 values=labels,
+                                                                 values_row=labels_row,
+                                                                 values_col=labels_col)
+        labels = values.astype(int)
+        if (labels < 0).all():
+            raise ValueError('At least one node must be given a non-negative label.')
+        labels_reindex = labels.copy()
+        labels_unique, inverse = np.unique(labels[labels >= 0], return_inverse=True)
+        labels_reindex[labels >= 0] = inverse
+        temperatures = get_membership(labels_reindex).toarray()
+        temperatures_seeds = temperatures[labels >= 0]
+        temperatures[labels < 0] = 0.5
+        diffusion = normalize(adjacency)
+        for i in range(self.n_iter):
+            temperatures = diffusion.dot(temperatures)
+            temperatures[labels >= 0] = temperatures_seeds
+        if self.centering:
+            temperatures -= temperatures.mean(axis=0)
+        labels_ = labels_unique[temperatures.argmax(axis=1)]
+
+        # softmax
+        if self.centering:
+            temperatures = np.exp(self.scale * temperatures)
+
+        # set label -1 to nodes not reached by diffusion
+        distances = get_distances(adjacency, source=np.flatnonzero(labels >= 0))
+        labels_[distances < 0] = -1
+        temperatures[distances < 0] = 0
+
+        self.labels_ = labels_
+        self.probs_ = sparse.csr_matrix(normalize(temperatures))
+        self._split_vars(input_matrix.shape)
+
+        return self

sknetwork/classification/knn.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in November 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+@author: Thomas Bonald <tbonald@enst.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.classification.base import BaseClassifier
+from sknetwork.embedding.base import BaseEmbedding
+from sknetwork.linalg.normalizer import get_norms, normalize
+from sknetwork.utils.check import check_n_neighbors
+from sknetwork.utils.format import get_adjacency_values
+
+
+class NNClassifier(BaseClassifier):
+    """Node classification by K-nearest neighbors in the embedding space.
+
+    Parameters
+    ----------
+    n_neighbors : int
+        Number of nearest neighbors .
+    embedding_method : :class:`BaseEmbedding`
+        Embedding method used to represent nodes in vector space.
+        If ``None`` (default), use identity.
+    normalize : bool
+        If ``True``, apply normalization so that all vectors have norm 1 in the embedding space.
+
+    Attributes
+    ----------
+    labels_ : np.ndarray, shape (n_labels,)
+        Labels of nodes.
+    probs_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distribution over labels.
+    labels_row_ : np.ndarray
+        Labels of rows, for bipartite graphs.
+    labels_col_ : np.ndarray
+        Labels of columns, for bipartite graphs.
+    probs_row_ : sparse.csr_matrix, shape (n_row, n_labels)
+        Probability distributions over labels of rows, for bipartite graphs.
+    probs_col_ : sparse.csr_matrix, shape (n_col, n_labels)
+        Probability distributions over labels of columns, for bipartite graphs.
+
+    Example
+    -------
+    >>> from sknetwork.classification import NNClassifier
+    >>> from sknetwork.data import karate_club
+    >>> classifier = NNClassifier(n_neighbors=1)
+    >>> graph = karate_club(metadata=True)
+    >>> adjacency = graph.adjacency
+    >>> labels_true = graph.labels
+    >>> labels = {0: labels_true[0], 33: labels_true[33]}
+    >>> labels_pred = classifier.fit_predict(adjacency, labels)
+    >>> float(round(np.mean(labels_pred == labels_true), 2))
+    0.82
+    """
+    def __init__(self, n_neighbors: int = 3, embedding_method: Optional[BaseEmbedding] = None, normalize: bool = True):
+        super(NNClassifier, self).__init__()
+        self.n_neighbors = n_neighbors
+        self.embedding_method = embedding_method
+        self.normalize = normalize
+
+    @staticmethod
+    def _instantiate_vars(labels: np.ndarray):
+        index_train = np.flatnonzero(labels >= 0)
+        index_test = np.flatnonzero(labels < 0)
+        return index_train, index_test
+
+    def _fit_core(self, embedding, labels, index_train, index_test):
+        n_neighbors = check_n_neighbors(self.n_neighbors, len(index_train))
+
+        norms_train = get_norms(embedding[index_train], p=2)
+        neighbors = []
+        for i in index_test:
+            vector = embedding[i]
+            if sparse.issparse(vector):
+                vector = vector.toarray().ravel()
+            distances = norms_train**2 - 2 * embedding[index_train].dot(vector) + np.sum(vector**2)
+            neighbors += list(index_train[np.argpartition(distances, n_neighbors)[:n_neighbors]])
+        labels_neighbor = labels[neighbors]
+
+        # membership matrix
+        row = list(np.repeat(index_test, n_neighbors))
+        col = list(labels_neighbor)
+        data = list(np.ones_like(labels_neighbor))
+
+        row += list(index_train)
+        col += list(labels[index_train])
+        data += list(np.ones_like(index_train))
+
+        probs = normalize(sparse.csr_matrix((data, (row, col)), shape=(len(labels), np.max(labels) + 1)))
+        labels = np.argmax(probs.toarray(), axis=1)
+
+        return probs, labels
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], labels: Union[np.ndarray, list, dict] = None,
+            labels_row: Union[np.ndarray, list, dict] = None,
+            labels_col: Union[np.ndarray, list, dict] = None) -> 'NNClassifier':
+        """Node classification by k-nearest neighbors in the embedding space.
+
+        Parameters
+        ----------
+        input_matrix : sparse.csr_matrix, np.ndarray
+            Adjacency matrix or biadjacency matrix of the graph.
+        labels : np.ndarray, dict
+            Known labels. Negative values ignored.
+        labels_row : np.ndarray, dict
+            Known labels of rows, for bipartite graphs.
+        labels_col : np.ndarray, dict
+            Known labels of columns, for bipartite graphs.
+
+        Returns
+        -------
+        self: :class:`KNN`
+        """
+        adjacency, labels, self.bipartite = get_adjacency_values(input_matrix, values=labels, values_row=labels_row,
+                                                                 values_col=labels_col)
+        labels = labels.astype(int)
+        index_seed, index_remain = self._instantiate_vars(labels)
+
+        if self.embedding_method is None:
+            embedding = adjacency
+        else:
+            embedding = self.embedding_method.fit_transform(adjacency)
+
+        if self.normalize:
+            embedding = normalize(embedding, p=2)
+
+        probs, labels = self._fit_core(embedding, labels, index_seed, index_remain)
+
+        self.labels_ = labels
+        self.probs_ = probs
+        self._split_vars(input_matrix.shape)
+
+        return self