scikit-network 0.28.3__cp39-cp39-macosx_12_0_arm64.whl

sknetwork/gnn/base_activation.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on April 2022
+@author: Simon Delarue <sdelarue@enst.fr>
+"""
+import numpy as np
+
+
+class BaseActivation:
+    """Base class for activation functions.
+    Parameters
+    ----------
+    name : str
+        Name of the activation function.
+    """
+    def __init__(self, name: str = 'custom'):
+        self.name = name
+
+    @staticmethod
+    def output(signal: np.ndarray) -> np.ndarray:
+        """Output of the activation function.
+
+        Parameters
+        ----------
+        signal : np.ndarray, shape (n_samples, n_channels)
+            Input signal.
+
+        Returns
+        -------
+        output : np.ndarray, shape (n_samples, n_channels)
+            Output signal.
+        """
+        output = signal
+        return output
+
+    @staticmethod
+    def gradient(signal: np.ndarray, direction: np.ndarray) -> np.ndarray:
+        """Gradient of the activation function.
+
+        Parameters
+        ----------
+        signal : np.ndarray, shape (n_samples, n_channels)
+            Input signal.
+        direction : np.ndarray, shape (n_samples, n_channels)
+            Direction where the gradient is taken.
+
+        Returns
+        -------
+        gradient : np.ndarray, shape (n_samples, n_channels)
+            Gradient.
+        """
+        gradient = direction
+        return gradient
+
+
+class BaseLoss(BaseActivation):
+    """Base class for loss functions."""
+    @staticmethod
+    def loss(signal: np.ndarray, labels: np.ndarray) -> float:
+        """Get the loss value.
+
+        Parameters
+        ----------
+        signal : np.ndarray, shape (n_samples, n_channels)
+            Input signal (before activation).
+        labels : np.ndarray, shape (n_samples)
+            True labels.
+        """
+        return 0
+
+    @staticmethod
+    def loss_gradient(signal: np.ndarray, labels: np.ndarray) -> np.ndarray:
+        """Gradient of the loss function.
+
+        Parameters
+        ----------
+        signal : np.ndarray, shape (n_samples, n_channels)
+            Input signal.
+        labels : np.ndarray, shape (n_samples,)
+            True labels.
+
+        Returns
+        -------
+        gradient : np.ndarray, shape (n_samples, n_channels)
+            Gradient.
+        """
+        gradient = np.ones_like(signal)
+        return gradient

sknetwork/gnn/base_layer.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on July 2022
+@author: Simon Delarue <sdelarue@enst.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+
+from sknetwork.gnn.activation import BaseActivation, get_activation
+from sknetwork.gnn.loss import BaseLoss, get_loss
+
+
+class BaseLayer:
+    """Base class for GNN layers.
+
+    Parameters
+    ----------
+    layer_type : str
+        Layer type. Can be either ``'Conv'`` (Convolution) or ``'Sage'`` (GraphSAGE).
+    out_channels: int
+        Dimension of the output.
+    activation: str (default = ``'Relu'``) or custom activation.
+        Activation function.
+        If a string, can be either ``'Identity'``, ``'Relu'``, ``'Sigmoid'`` or ``'Softmax'``.
+    use_bias: bool (default = `True`)
+        If ``True``, add a bias vector.
+    normalization: str (default = ``'both'``)
+        Normalization of the adjacency matrix for message passing.
+        Can be either `'left'`` (left normalization by the degrees), ``'right'`` (right normalization by the degrees),
+        ``'both'`` (symmetric normalization by the square root of degrees, default) or ``None`` (no normalization).
+    self_embeddings: bool (default = `True`)
+        If ``True``, consider self-embedding in addition to neighbors embedding for each node of the graph.
+    sample_size: int (default = 25)
+        Size of neighborhood sampled for each node. Used only for ``'SAGEConv'`` layer.
+
+    Attributes
+    ----------
+    weight : np.ndarray,
+        Trainable weight matrix.
+    bias : np.ndarray
+        Bias vector.
+    embedding : np.ndarray
+        Embedding of the nodes (before activation).
+    output : np.ndarray
+        Output of the layer (after activation).
+    """
+    def __init__(self, layer_type: str, out_channels: int, activation: Optional[Union[BaseActivation, str]] = 'Relu',
+                 use_bias: bool = True, normalization: str = 'both', self_embeddings: bool = True,
+                 sample_size: int = 25, loss: Optional[Union[BaseLoss, str]] = None):
+        self.layer_type = layer_type
+        self.out_channels = out_channels
+        if loss is None:
+            self.activation = get_activation(activation)
+        else:
+            self.activation = get_loss(loss)
+        self.use_bias = use_bias
+        self.normalization = normalization.lower()
+        self.self_embeddings = self_embeddings
+        self.sample_size = sample_size
+        self.weight = None
+        self.bias = None
+        self.embedding = None
+        self.output = None
+        self.weights_initialized = False
+
+    def _initialize_weights(self, in_channels: int):
+        """Initialize weights and bias.
+
+        Parameters
+        ----------
+        in_channels: int
+            Number of input channels.
+        """
+        # Trainable parameters with He initialization
+        self.weight = np.random.randn(in_channels, self.out_channels) * np.sqrt(2 / self.out_channels)
+        if self.use_bias:
+            self.bias = np.zeros((self.out_channels, 1)).T
+        self.weights_initialized = True
+
+    def forward(self, *args, **kwargs):
+        """Compute forward pass."""
+        raise NotImplementedError
+
+    def __call__(self, *args, **kwargs):
+        return self.forward(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        """ String representation of object
+
+        Returns
+        -------
+        str
+            String representation of object
+        """
+        print_attr = ['out_channels', 'layer_type', 'activation', 'use_bias', 'normalization', 'self_embeddings']
+        if 'sage' in self.layer_type:
+            print_attr.append('sample_size')
+        attributes_dict = {k: v for k, v in self.__dict__.items() if k in print_attr}
+        string = ''
+
+        for k, v in attributes_dict.items():
+            if k == 'activation':
+                string += f'{k}: {v.name}, '
+            else:
+                string += f'{k}: {v}, '
+
+        return f'  {self.__class__.__name__}({string[:-2]})'

sknetwork/gnn/gnn_classifier.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in April 2022
+@author: Simon Delarue <sdelarue@enst.fr>
+"""
+from typing import Optional, Union
+from collections import defaultdict
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.classification.metrics import get_accuracy_score
+from sknetwork.gnn.base import BaseGNN
+from sknetwork.gnn.loss import BaseLoss
+from sknetwork.gnn.layer import get_layer
+from sknetwork.gnn.neighbor_sampler import UniformNeighborSampler
+from sknetwork.gnn.optimizer import BaseOptimizer
+from sknetwork.gnn.utils import filter_mask, check_existing_masks, check_output, check_early_stopping, check_loss, \
+    get_layers
+from sknetwork.utils.check import check_format, check_nonnegative, check_square
+
+
+class GNNClassifier(BaseGNN):
+    """Graph Neural Network for node classification.
+
+    Parameters
+    ----------
+    dims : list or int
+        Dimensions of the output of each layer (in forward direction).
+        If an integer, dimension of the output layer (no hidden layer).
+        Optional if ``layers`` is specified.
+    layer_types : list or str
+        Layer types (in forward direction).
+        If a string, use the same type of layer for all layers.
+        Can be ``'Conv'``, graph convolutional layer (default) or ``'Sage'`` (GraphSage).
+    activations : list or str
+        Activation functions (in forward direction).
+        If a string, use the same activation function for all layers.
+        Can be either ``'Identity'``, ``'Relu'``, ``'Sigmoid'`` or ``'Softmax'`` (default = ``'Relu'``).
+    use_bias : list or bool
+        Whether to use a bias term at each layer.
+        If ``True``, use a bias term at all layers.
+    normalizations : list or str
+        Normalization of the adjacency matrix for message passing.
+        If a string, use the same normalization for all layers.
+        Can be either `'left'`` (left normalization by the degrees), ``'right'`` (right normalization by the degrees),
+        ``'both'`` (symmetric normalization by the square root of degrees, default) or ``None`` (no normalization).
+    self_embeddings : list or str
+        Whether to add a self embeddings to each node of the graph for message passing.
+        If ``True``, add self-embeddings at all layers.
+    sample_sizes : list or int
+        Size of neighborhood sampled for each node. Used only for ``'Sage'`` layer type.
+    loss : str (default = ``'CrossEntropy'``) or BaseLoss
+        Loss function name or custom loss.
+    layers : list or None
+        Custom layers. If used, previous parameters are ignored.
+    optimizer : str or optimizer
+        * ``'Adam'``, stochastic gradient-based optimizer (default).
+        * ``'GD'``, gradient descent.
+    learning_rate : float
+        Learning rate.
+    early_stopping : bool (default = ``True``)
+        Whether to use early stopping to end training.
+        If ``True``, training terminates when validation score is not improving for `patience` number of epochs.
+    patience : int (default = 10)
+        Number of iterations with no improvement to wait before stopping fitting.
+    verbose : bool
+        Verbose mode.
+
+    Attributes
+    ----------
+    conv2, ..., conv1: :class:'GCNConv'
+        Graph convolutional layers.
+    output_ : array
+        Output of the GNN.
+    labels_: np.ndarray
+        Predicted node labels.
+    history_: dict
+        Training history per epoch: {``'embedding'``, ``'loss'``, ``'train_accuracy'``, ``'val_accuracy'``}.
+
+    Example
+    -------
+    >>> from sknetwork.gnn.gnn_classifier import GNNClassifier
+    >>> from sknetwork.data import karate_club
+    >>> from numpy.random import randint
+    >>> graph = karate_club(metadata=True)
+    >>> adjacency = graph.adjacency
+    >>> labels = graph.labels
+    >>> features = adjacency.copy()
+    >>> gnn = GNNClassifier(dims=1, early_stopping=False)
+    >>> labels_pred = gnn.fit_predict(adjacency, features, labels, random_state=42)
+    >>> np.round(np.mean(labels_pred == labels), 2)
+    0.91
+    """
+
+    def __init__(self, dims: Optional[Union[int, list]] = None, layer_types: Union[str, list] = 'Conv',
+                 activations: Union[str, list] = 'ReLu', use_bias: Union[bool, list] = True,
+                 normalizations: Union[str, list] = 'both', self_embeddings: Union[bool, list] = True,
+                 sample_sizes: Union[int, list] = 25, loss: Union[BaseLoss, str] = 'CrossEntropy',
+                 layers: Optional[list] = None, optimizer: Union[BaseOptimizer, str] = 'Adam',
+                 learning_rate: float = 0.01, early_stopping: bool = True, patience: int = 10, verbose: bool = False):
+        super(GNNClassifier, self).__init__(loss, optimizer, learning_rate, verbose)
+        if layers is not None:
+            layers = [get_layer(layer) for layer in layers]
+        else:
+            layers = get_layers(dims, layer_types, activations, use_bias, normalizations, self_embeddings, sample_sizes,
+                                loss)
+        self.loss = check_loss(layers[-1])
+        self.layers = layers
+        self.early_stopping = early_stopping
+        self.patience = patience
+        self.history_ = defaultdict(list)
+
+    def forward(self, adjacency: Union[list, sparse.csr_matrix], features: Union[sparse.csr_matrix, np.ndarray]) \
+            -> np.ndarray:
+        """Perform a forward pass on the graph and return the output.
+
+        Parameters
+        ----------
+        adjacency : Union[list, sparse.csr_matrix]
+            Adjacency matrix or list of sampled adjacency matrices.
+        features : sparse.csr_matrix, np.ndarray
+            Features, array of shape (n_nodes, n_features).
+
+        Returns
+        -------
+        output : np.ndarray
+            Output of the GNN.
+        """
+        h = features.copy()
+        for i, layer in enumerate(self.layers):
+            if isinstance(adjacency, list):
+                h = layer(adjacency[i], h)
+            else:
+                h = layer(adjacency, h)
+        return h
+
+    @staticmethod
+    def _compute_predictions(output: np.ndarray) -> np.ndarray:
+        """Compute predictions from the output of the GNN.
+
+        Parameters
+        ----------
+        output : np.ndarray
+            Output of the GNN.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Predicted labels.
+        """
+        if output.shape[1] == 1:
+            labels = (output.ravel() > 0.5).astype(int)
+        else:
+            labels = output.argmax(axis=1)
+        return labels
+
+    def fit(self, adjacency: Union[sparse.csr_matrix, np.ndarray], features: Union[sparse.csr_matrix, np.ndarray],
+            labels: np.ndarray, n_epochs: int = 100, train_mask: Optional[np.ndarray] = None,
+            val_mask: Optional[np.ndarray] = None,
+            test_mask: Optional[np.ndarray] = None, train_size: Optional[float] = 0.8,
+            val_size: Optional[float] = 0.1, test_size: Optional[float] = 0.1, resample: bool = False,
+            reinit: bool = False, random_state: Optional[int] = None, history: bool = False) -> 'GNNClassifier':
+        """ Fit model to data and store trained parameters.
+
+        Parameters
+        ----------
+        adjacency : sparse.csr_matrix
+            Adjacency matrix of the graph.
+        features : sparse.csr_matrix, np.ndarray
+            Input feature of shape :math:`(n, d)` with :math:`n` the number of nodes in the graph and :math:`d`
+            the size of feature space.
+        labels : np.ndarray
+            Label vectors of length :math:`n`, with :math:`n` the number of nodes in `adjacency`. A value of `labels`
+            equals `-1` means no label. The associated nodes are not considered in training steps.
+        n_epochs : int (default = 100)
+            Number of epochs (iterations over the whole graph).
+        train_mask, val_mask, test_mask : np.ndarray
+            Boolean array indicating whether nodes are in training/validation/test set.
+        train_size, test_size : float
+            Proportion of the nodes in the training/test set (between 0 and 1).
+            Only used if the corresponding masks are ``None``.
+        val_size : float
+            Proportion of the training set used for validation (between 0 and 1).
+            Only used if the corresponding mask is ``None``.
+        resample : bool (default = ``False``)
+            If ``True``, resample the train/test/validation sets before fitting.
+            Otherwise, the train/test/validation sets remain the same after the first fit.
+        reinit: bool  (default = ``False``)
+            If ``True``, reinit the trainable parameters of the GNN (weights and biases).
+        random_state : int
+            Pass an int for reproducible results across multiple runs.
+        history : bool (default = ``False``)
+            If ``True``, save training history.
+        """
+        if reinit:
+            for layer in self.layers:
+                layer.weights_initialized = False
+
+        if resample or self.output_ is None:
+            exists_mask, self.train_mask, self.val_mask, self.test_mask = \
+                check_existing_masks(labels, train_mask, val_mask, test_mask, train_size, val_size, test_size)
+            if not exists_mask:
+                self._generate_masks(train_size, val_size, test_size, random_state)
+
+        check_format(adjacency)
+        check_format(features)
+
+        check_output(self.layers[-1].out_channels, labels)
+
+        early_stopping = check_early_stopping(self.early_stopping, self.val_mask, self.patience)
+
+        # List of sampled adjacencies (one per layer)
+        adjacencies = self._sample_nodes(adjacency)
+
+        best_val_acc = 0
+        trigger_times = 0
+
+        for epoch in range(n_epochs):
+
+            # Forward
+            output = self.forward(adjacencies, features)
+
+            # Compute predictions
+            labels_pred = self._compute_predictions(output)
+
+            # Loss
+            loss_value = self.loss.loss(output[self.train_mask], labels[self.train_mask])
+
+            # Accuracy
+            train_acc = get_accuracy_score(labels[self.train_mask], labels_pred[self.train_mask])
+            if self.val_mask is not None and any(self.val_mask):
+                val_acc = get_accuracy_score(labels[self.val_mask], labels_pred[self.val_mask])
+            else:
+                val_acc = None
+
+            # Backpropagation
+            self.backward(features, labels, self.train_mask)
+
+            # Update weights using optimizer
+            self.optimizer.step(self)
+
+            # Save results
+            if history:
+                self.history_['embedding'].append(self.layers[-1].embedding)
+                self.history_['loss'].append(loss_value)
+                self.history_['train_accuracy'].append(train_acc)
+                if val_acc is not None:
+                    self.history_['val_accuracy'].append(val_acc)
+
+            if n_epochs > 10 and epoch % int(n_epochs / 10) == 0:
+                if val_acc is not None:
+                    self.log.print(
+                        f'In epoch {epoch:>3}, loss: {loss_value:.3f}, train accuracy: {train_acc:.3f}, '
+                        f'val accuracy: {val_acc:.3f}')
+                else:
+                    self.log.print(
+                        f'In epoch {epoch:>3}, loss: {loss_value:.3f}, train accuracy: {train_acc:.3f}')
+            elif n_epochs <= 10:
+                if val_acc is not None:
+                    self.log.print(
+                        f'In epoch {epoch:>3}, loss: {loss_value:.3f}, train accuracy: {train_acc:.3f}, '
+                        f'val accuracy: {val_acc:.3f}')
+                else:
+                    self.log.print(
+                        f'In epoch {epoch:>3}, loss: {loss_value:.3f}, train accuracy: {train_acc:.3f}')
+
+            # Early stopping
+            if early_stopping:
+                if val_acc > best_val_acc:
+                    trigger_times = 0
+                    best_val_acc = val_acc
+                else:
+                    trigger_times += 1
+                    if trigger_times >= self.patience:
+                        self.log.print('Early stopping.')
+                        break
+
+        output = self.forward(adjacencies, features)
+        labels_pred = self._compute_predictions(output)
+
+        self.embedding_ = self.layers[-1].embedding
+        self.output_ = self.layers[-1].output
+        self.labels_ = labels_pred
+
+        return self
+
+    def _generate_masks(self, train_size: Optional[float] = None, val_size: Optional[float] = None,
+                        test_size: Optional[float] = None, random_state: int = None):
+        """ Create training, validation and test masks.
+
+        Parameters
+        ----------
+        train_size : float
+            Proportion of nodes in the training set (between 0 and 1).
+        val_size : float
+            Proportion of nodes in the validation set (between 0 and 1).
+        test_size : float
+            Proportion of nodes in the test set (between 0 and 1).
+        random_state : int
+            Pass an int for reproducible results across multiple runs.
+        """
+        is_negative_labels = self.test_mask
+
+        if random_state is not None:
+            np.random.seed(random_state)
+
+        if train_size is None:
+            train_size = 1 - test_size
+
+        self.train_mask = filter_mask(~is_negative_labels, train_size)
+        self.val_mask = filter_mask(np.logical_and(~self.train_mask, ~is_negative_labels), val_size)
+        self.test_mask = np.logical_and(~self.train_mask, ~self.val_mask)
+
+    def _sample_nodes(self, adjacency: Union[sparse.csr_matrix, np.ndarray]) -> list:
+        """Perform node sampling on adjacency matrix for GraphSAGE layers. For other layers, the
+        adjacency matrix remains unchanged.
+
+        Parameters
+        ----------
+        adjacency : sparse.csr_matrix
+            Adjacency matrix of the graph.
+
+        Returns
+        -------
+        List of (sampled) adjacency matrices.
+        """
+        adjacencies = []
+
+        for layer in self.layers:
+            if layer.layer_type == 'sage':
+                sampler = UniformNeighborSampler(sample_size=layer.sample_size)
+                adjacencies.append(sampler(adjacency))
+            else:
+                adjacencies.append(adjacency)
+
+        return adjacencies
+
+    def predict(self, adjacency_vectors: Union[sparse.csr_matrix, np.ndarray] = None,
+                feature_vectors: Union[sparse.csr_matrix, np.ndarray] = None) -> np.ndarray:
+        """Predict labels for new nodes. If called without parameters, labels are returned for all nodes.
+
+        Parameters
+        ----------
+        adjacency_vectors : np.ndarray
+            Square adjacency matrix. Array of shape (n, n).
+        feature_vectors : np.ndarray
+            Features row vectors. Array of shape (n, n_feat). The number of features n_feat must match with the one
+            used during training.
+
+        Returns
+        -------
+        labels : np.ndarray
+            Label of each node of the graph.
+        """
+        self._check_fitted()
+
+        if adjacency_vectors is None and feature_vectors is None:
+            return self.labels_
+        elif adjacency_vectors is None:
+            adjacency_vectors = sparse.identity(feature_vectors.shape[0], format='csr')
+
+        check_square(adjacency_vectors)
+        check_nonnegative(adjacency_vectors)
+        feature_vectors = check_format(feature_vectors)
+
+        n_row, n_col = adjacency_vectors.shape
+        feat_row, feat_col = feature_vectors.shape
+
+        if n_col != feat_row:
+            raise ValueError(f'Dimension mismatch: dim0={n_col} != dim1={feat_row}.')
+        elif feat_col != self.layers[0].weight.shape[0]:
+            raise ValueError(f'Dimension mismatch: current number of features is {feat_col} whereas GNN has been '
+                             f'trained with '
+                             f'{self.layers[0].weight.shape[0]} features.')
+
+        h = self.forward(adjacency_vectors, feature_vectors)
+        labels = self._compute_predictions(h)
+
+        return labels