# Copyright 1999-2020 Alibaba Group Holding Ltd. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. import warnings from abc import ABCMeta, abstractmethod from sklearn.base import BaseEstimator from sklearn.exceptions import ConvergenceWarning from ... import tensor as mt from ...core import ExecutableTuple from ..base import ClassifierMixin from ..metrics.pairwise import rbf_kernel from ..neighbors.unsupervised import NearestNeighbors from ..utils import check_array from ..utils.multiclass import check_classification_targets from ..utils.validation import check_is_fitted, check_X_y class BaseLabelPropagation(ClassifierMixin, BaseEstimator, metaclass=ABCMeta): """Base class for label propagation module. Parameters ---------- kernel : {'knn', 'rbf', callable} String identifier for kernel function to use or the kernel function itself. Only 'rbf' and 'knn' strings are valid inputs. The function passed should take two inputs, each of shape [n_samples, n_features], and return a [n_samples, n_samples] shaped weight matrix gamma : float Parameter for rbf kernel n_neighbors : integer > 0 Parameter for knn kernel alpha : float Clamping factor max_iter : integer Change maximum number of iterations allowed tol : float Convergence tolerance: threshold to consider the system at steady state """ def __init__(self, kernel='rbf', gamma=20, n_neighbors=7, alpha=1, max_iter=30, tol=1e-3): self.max_iter = max_iter self.tol = tol # kernel parameters self.kernel = kernel self.gamma = gamma self.n_neighbors = n_neighbors # clamping factor self.alpha = alpha self.nn_fit = None def _get_kernel(self, X, y=None): if self.kernel == "rbf": if y is None: return rbf_kernel(X, X, gamma=self.gamma) else: return rbf_kernel(X, y, gamma=self.gamma) elif self.kernel == "knn": if self.nn_fit is None: self.nn_fit = NearestNeighbors(self.n_neighbors).fit(X) if y is None: return self.nn_fit.kneighbors_graph(self.nn_fit._fit_X, self.n_neighbors, mode='connectivity') else: return self.nn_fit.kneighbors(y, return_distance=False) elif callable(self.kernel): if y is None: return self.kernel(X, X) else: return self.kernel(X, y) else: # pragma: no cover raise ValueError(f"{self.kernel} is not a valid kernel. Only rbf and knn" " or an explicit function " " are supported at this time.") @abstractmethod def _build_graph(self): # pragma: no cover raise NotImplementedError("Graph construction must be implemented" " to fit a label propagation model.") def predict(self, X, session=None, run_kwargs=None): """Performs inductive inference across the model. Parameters ---------- X : array_like, shape = [n_samples, n_features] Returns ------- y : array_like, shape = [n_samples] Predictions for input data """ probas = self.predict_proba(X, session=session, run_kwargs=run_kwargs) result = mt.tensor(self.classes_)[mt.argmax(probas, axis=1)].ravel() result.execute(session=session, **(run_kwargs or dict())) return result def predict_proba(self, X, session=None, run_kwargs=None): """Predict probability for each possible outcome. Compute the probability estimates for each single sample in X and each possible outcome seen during training (categorical distribution). Parameters ---------- X : array_like, shape = [n_samples, n_features] Returns ------- probabilities : Tensor, shape = [n_samples, n_classes] Normalized probability distributions across class labels """ check_is_fitted(self, 'X_') X_2d = check_array(X, accept_sparse=True) weight_matrices = self._get_kernel(self.X_, X_2d) if self.kernel == 'knn': probabilities = mt.array([ mt.sum(self.label_distributions_[weight_matrix], axis=0) for weight_matrix in weight_matrices]) else: weight_matrices = weight_matrices.T probabilities = mt.dot(weight_matrices, self.label_distributions_) normalizer = mt.atleast_2d(mt.sum(probabilities, axis=1)).T probabilities /= normalizer probabilities.execute(session=session, **(run_kwargs or dict())) return probabilities def fit(self, X, y, session=None, run_kwargs=None): """Fit a semi-supervised label propagation model based All the input data is provided matrix X (labeled and unlabeled) and corresponding label matrix y with a dedicated marker value for unlabeled samples. Parameters ---------- X : array-like of shape (n_samples, n_features) A {n_samples by n_samples} size matrix will be created from this y : array_like, shape = [n_samples] n_labeled_samples (unlabeled points are marked as -1) All unlabeled samples will be transductively assigned labels Returns ------- self : returns an instance of self. """ X, y = check_X_y(X, y) self.X_ = X to_run = [check_classification_targets(y)] # actual graph construction (implementations should override this) graph_matrix = self._build_graph() # label construction # construct a categorical distribution for classification only classes = mt.unique(y, aggregate_size=1).to_numpy( session=session, **(run_kwargs or dict())) classes = (classes[classes != -1]) self.classes_ = classes n_samples, n_classes = len(y), len(classes) alpha = self.alpha # add check when we support LabelSpreading # if self._variant == 'spreading' and \ # (alpha is None or alpha <= 0.0 or alpha >= 1.0): # raise ValueError('alpha=%s is invalid: it must be inside ' # 'the open interval (0, 1)' % alpha) y = mt.asarray(y) unlabeled = y == -1 # initialize distributions self.label_distributions_ = mt.zeros((n_samples, n_classes)) for label in classes: self.label_distributions_[y == label, classes == label] = 1 y_static = mt.copy(self.label_distributions_) if self._variant == 'propagation': # LabelPropagation y_static[unlabeled] = 0 else: # pragma: no cover # LabelSpreading y_static *= 1 - alpha l_previous = mt.zeros((self.X_.shape[0], n_classes)) unlabeled = unlabeled[:, mt.newaxis] for self.n_iter_ in range(self.max_iter): cond = mt.abs(self.label_distributions_ - l_previous).sum() < self.tol to_run.append(cond) ExecutableTuple(to_run).execute( session=session, **(run_kwargs or dict())) # clear to_run = [] if cond.fetch(session=session): break l_previous = self.label_distributions_ self.label_distributions_ = graph_matrix.dot(self.label_distributions_) if self._variant == 'propagation': normalizer = mt.sum( self.label_distributions_, axis=1)[:, mt.newaxis] self.label_distributions_ /= normalizer self.label_distributions_ = mt.where(unlabeled, self.label_distributions_, y_static) else: # pragma: no cover # clamp self.label_distributions_ = mt.multiply( alpha, self.label_distributions_) + y_static to_run.append(self.label_distributions_) else: warnings.warn( f'max_iter={self.max_iter} was reached without convergence.', category=ConvergenceWarning ) self.n_iter_ += 1 normalizer = mt.sum(self.label_distributions_, axis=1)[:, mt.newaxis] self.label_distributions_ /= normalizer # set the transduction item transduction = mt.tensor(self.classes_)[mt.argmax(self.label_distributions_, axis=1)] self.transduction_ = transduction.ravel() ExecutableTuple([self.label_distributions_, self.transduction_]).execute( session=session, **(run_kwargs or dict())) return self [docs]class LabelPropagation(BaseLabelPropagation): """Label Propagation classifier Read more in the :ref:`User Guide <label_propagation>`. Parameters ---------- kernel : {'knn', 'rbf', callable} String identifier for kernel function to use or the kernel function itself. Only 'rbf' and 'knn' strings are valid inputs. The function passed should take two inputs, each of shape [n_samples, n_features], and return a [n_samples, n_samples] shaped weight matrix. gamma : float Parameter for rbf kernel n_neighbors : integer > 0 Parameter for knn kernel max_iter : integer Change maximum number of iterations allowed tol : float Convergence tolerance: threshold to consider the system at steady state Attributes ---------- X_ : array, shape = [n_samples, n_features] Input array. classes_ : array, shape = [n_classes] The distinct labels used in classifying instances. label_distributions_ : array, shape = [n_samples, n_classes] Categorical distribution for each item. transduction_ : array, shape = [n_samples] Label assigned to each item via the transduction. n_iter_ : int Number of iterations run. Examples -------- >>> import numpy as np >>> from sklearn import datasets >>> from mars.learn.semi_supervised import LabelPropagation >>> label_prop_model = LabelPropagation() >>> iris = datasets.load_iris() >>> rng = np.random.RandomState(42) >>> random_unlabeled_points = rng.rand(len(iris.target)) < 0.3 >>> labels = np.copy(iris.target) >>> labels[random_unlabeled_points] = -1 >>> label_prop_model.fit(iris.data, labels) LabelPropagation(...) References ---------- Xiaojin Zhu and Zoubin Ghahramani. Learning from labeled and unlabeled data with label propagation. Technical Report CMU-CALD-02-107, Carnegie Mellon University, 2002 http://pages.cs.wisc.edu/~jerryzhu/pub/CMU-CALD-02-107.pdf See Also -------- LabelSpreading : Alternate label propagation strategy more robust to noise """ _variant = 'propagation' [docs] def __init__(self, kernel='rbf', gamma=20, n_neighbors=7, max_iter=1000, tol=1e-3): super().__init__(kernel=kernel, gamma=gamma, n_neighbors=n_neighbors, max_iter=max_iter, tol=tol, alpha=None) def _build_graph(self): """Matrix representing a fully connected graph between each sample This basic implementation creates a non-stochastic affinity matrix, so class distributions will exceed 1 (normalization may be desired). """ if self.kernel == 'knn': self.nn_fit = None affinity_matrix = self._get_kernel(self.X_) normalizer = affinity_matrix.sum(axis=0) affinity_matrix /= normalizer[:, mt.newaxis] return affinity_matrix def fit(self, X, y, session=None, run_kwargs=None): return super().fit(X, y, session=session, run_kwargs=run_kwargs)