scikit-network 0.28.3__cp39-cp39-macosx_12_0_arm64.whl

sknetwork/gnn/utils.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# coding: utf-8
+"""
+Created on Thu Apr 21 2022
+@author: Simon Delarue <sdelarue@enst.fr>
+"""
+import inspect
+from typing import Union, Optional, Tuple
+import warnings
+
+import numpy as np
+
+from sknetwork.gnn.base_activation import BaseActivation, BaseLoss
+from sknetwork.gnn.base_layer import BaseLayer
+from sknetwork.gnn.layer import get_layer
+from sknetwork.gnn.loss import BinaryCrossEntropy, CrossEntropy
+from sknetwork.utils.check import check_is_proba, check_boolean, check_labels
+
+
+def filter_mask(mask: np.ndarray, proportion: Optional[float]):
+    """Filter a boolean mask so that the proportion of ones does not exceed some target.
+
+    Parameters
+    ----------
+    mask : np.ndarray
+        Boolean mask
+    proportion : float
+        Target proportion of ones.
+    Returns
+    -------
+    mask_filter : np.ndarray
+        New boolean mask
+    """
+    n_ones = sum(mask)
+    if n_ones:
+        if proportion:
+            ratio = proportion * len(mask) / n_ones
+            mask[mask] = np.random.random(n_ones) <= ratio
+        else:
+            mask = np.zeros_like(mask, dtype=bool)
+    return mask
+
+
+def check_existing_masks(labels: np.ndarray, train_mask: Optional[np.ndarray] = None,
+                         val_mask: Optional[np.ndarray] = None, test_mask: Optional[np.ndarray] = None,
+                         train_size: Optional[float] = None, val_size: Optional[float] = None,
+                         test_size: Optional[float] = None) -> Tuple:
+    """Check mask parameters and return mask boolean arrays.
+
+    Parameters
+    ----------
+    labels: np.ndarray
+        Label vectors of length :math:`n`, with :math:`n` the number of nodes in `adjacency`. Labels set to `-1`
+        will not be considered for training steps.
+    train_mask, val_mask, test_mask: np.ndarray
+        Boolean arrays indicating whether nodes are in training/validation/test set.
+    train_size, val_size, test_size: float
+        Proportion of the nodes in the training/validation/test set (between 0 and 1).
+        Only used if when corresponding masks are ``None``.
+
+    Returns
+    -------
+    Tuple containing:
+        * ``True`` if training mask is provided
+        * training, validation and test masks w.r.t values in `labels`.
+    """
+    _, _ = check_labels(labels)
+
+    is_negative_labels = labels < 0
+
+    if train_mask is not None:
+        check_boolean(train_mask)
+        train_mask_filtered = np.logical_and(train_mask, ~is_negative_labels)
+        check_mask_similarity(train_mask, train_mask_filtered)
+        train_mask = train_mask_filtered
+        if test_mask is not None:
+            check_boolean(test_mask)
+            if val_mask is not None:
+                check_boolean(val_mask)
+                val_mask_filtered = np.logical_and(val_mask, ~is_negative_labels)
+                check_mask_similarity(val_mask, val_mask_filtered)
+                val_mask = val_mask_filtered
+                if (train_mask & val_mask & test_mask).any():
+                    raise ValueError('Masks are overlapping. Please change masks.')
+            else:
+                val_mask = np.logical_and(~train_mask, ~test_mask)
+                val_mask = np.logical_and(val_mask, ~is_negative_labels)
+        else:
+            if val_mask is None:
+                val_mask = filter_mask(~train_mask, val_size)
+            val_mask = np.logical_and(val_mask, ~is_negative_labels)
+            test_mask = np.logical_and(~train_mask, ~val_mask)
+        return True, train_mask, val_mask, test_mask
+    else:
+        if train_size is None and test_size is None:
+            raise ValueError('Either mask parameters or size parameters should be different from None.')
+        for size in [train_size, test_size, val_size]:
+            if size is not None:
+                check_is_proba(size)
+        return False, ~is_negative_labels, None, is_negative_labels
+
+
+def check_mask_similarity(mask_1: np.ndarray, mask_2: np.ndarray):
+    """Print warning if two mask arrays are different."""
+    if any(mask_1 != mask_2):
+        warnings.warn('Nodes with label "-1" are considered in the train set or the validation set.')
+
+
+def check_early_stopping(early_stopping: bool, val_mask: np.ndarray, patience: int):
+    """Check early stopping parameters."""
+    if val_mask is None or patience is None or not any(val_mask):
+        return False
+    else:
+        return early_stopping
+
+
+def check_normalizations(normalizations: Union[str, list]):
+    """Check if normalization is known."""
+    available_norms = ['left', 'right', 'both']
+    if isinstance(normalizations, list):
+        for normalization in normalizations:
+            if normalization.lower() not in available_norms:
+                raise ValueError("Normalization must be 'left', 'right' or 'both'.")
+    elif normalizations.lower() not in available_norms:
+        raise ValueError("Normalization must be 'left', 'right' or 'both'.")
+
+
+def check_output(n_channels: int, labels: np.ndarray):
+    """Check the output of the GNN.
+
+    Parameters
+    ----------
+    n_channels : int
+        Number of output channels
+    labels : np.ndarray
+        Vector of labels
+    """
+    n_labels = len(set(labels[labels >= 0]))
+    if n_labels > 2 and n_labels > n_channels:
+        raise ValueError("The dimension of the output is too small for the number of labels. "
+                         "Please check the `dims` parameter of your GNN or the `labels` parameter.")
+
+
+def check_param(param, length):
+    """Check the length of a parameter if a list.
+    """
+    if not isinstance(param, list):
+        param = length * [param]
+    elif len(param) != length:
+        raise ValueError('The number of parameters must be equal to the number of layers.')
+    return param
+
+
+def check_loss(layer: BaseLayer):
+    """Check the length of a parameter if a list.
+    """
+    if not issubclass(type(layer.activation), BaseLoss):
+        raise ValueError('No loss specified for the last layer.')
+    if isinstance(layer.activation, CrossEntropy) and layer.out_channels == 1:
+        layer.activation = BinaryCrossEntropy()
+    return layer.activation
+
+
+def get_layers(dims: Union[int, list], layer_types: Union[str, BaseLayer, list],
+               activations: Union[str, BaseActivation, list], use_bias: Union[bool, list],
+               normalizations: Union[str, list], self_embeddings: Union[bool, list], sample_sizes: Union[int, list],
+               loss: Union[str, BaseLoss]) -> list:
+    """Get the list of layers.
+
+    Parameters
+    ----------
+    dims :
+        Dimensions of layers (in forward direction).
+    layer_types :
+        Layer types.
+    activations :
+        Activation functions.
+    use_bias :
+        ``True`` if a bias vector is added.
+    normalizations :
+        Normalizations of adjacency matrix.
+    self_embeddings :
+        ``True`` if self embeddings are added. Allowed input are booleans and lists.
+    sample_sizes
+        Size of neighborhood sampled for each node.
+    loss :
+        Loss function.
+
+    Returns
+    -------
+    list
+        List of layers.
+    """
+    check_normalizations(normalizations)
+
+    if not isinstance(dims, list):
+        dims = [dims]
+    n_layers = len(dims)
+
+    layer_types = check_param(layer_types, n_layers)
+    activations = check_param(activations, n_layers)
+    use_bias = check_param(use_bias, n_layers)
+    normalizations = check_param(normalizations, n_layers)
+    self_embeddings = check_param(self_embeddings, n_layers)
+    sample_sizes = check_param(sample_sizes, n_layers)
+
+    layers = []
+    names_params = ['layer', 'out_channels', 'activation', 'use_bias', 'normalization', 'self_embeddings',
+                    'sample_size']
+    for i in range(n_layers):
+        params = [layer_types[i], dims[i], activations[i], use_bias[i], normalizations[i], self_embeddings[i],
+                  sample_sizes[i]]
+        if i == n_layers - 1:
+            params.append(loss)
+            names_params.append('loss')
+        dict_params = dict(zip(names_params, params))
+        layers.append(get_layer(**dict_params))
+
+    return layers

sknetwork/hierarchy/__init__.py

@@ -0,0 +1,7 @@
+"""hierarchy module"""
+from sknetwork.hierarchy.paris import Paris
+from sknetwork.hierarchy.base import BaseHierarchy
+from sknetwork.hierarchy.louvain_hierarchy import LouvainIteration, LouvainHierarchy
+from sknetwork.hierarchy.metrics import dasgupta_cost, dasgupta_score, tree_sampling_divergence
+from sknetwork.hierarchy.postprocess import cut_straight, cut_balanced, aggregate_dendrogram, reorder_dendrogram
+from sknetwork.hierarchy.ward import Ward

sknetwork/hierarchy/base.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on November 2019
+@author: Nathan de Lara <nathan.delara@polytechnique.org>
+"""
+from abc import ABC
+
+import numpy as np
+
+from sknetwork.hierarchy.postprocess import split_dendrogram
+from sknetwork.utils.base import Algorithm
+
+
+class BaseHierarchy(Algorithm, ABC):
+    """Base class for hierarchical clustering algorithms.
+    Attributes
+    ----------
+    dendrogram_ :
+        Dendrogram of the graph.
+    dendrogram_row_ :
+        Dendrogram for the rows, for bipartite graphs.
+    dendrogram_col_ :
+        Dendrogram for the columns, for bipartite graphs.
+    dendrogram_full_ :
+        Dendrogram for both rows and columns, indexed in this order, for bipartite graphs.
+    """
+
+    def __init__(self):
+        self._init_vars()
+
+    def fit_predict(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the dendrogram. Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        dendrogram : np.ndarray
+            Dendrogram.
+        """
+        self.fit(*args, **kwargs)
+        return self.dendrogram_
+
+    def fit_transform(self, *args, **kwargs) -> np.ndarray:
+        """Fit algorithm to data and return the dendrogram. Alias for ``fit_predict``.
+        Same parameters as the ``fit`` method.
+
+        Returns
+        -------
+        dendrogram : np.ndarray
+            Dendrogram.
+        """
+        self.fit(*args, **kwargs)
+        return self.dendrogram_
+
+    def _init_vars(self):
+        """Init variables."""
+        self.dendrogram_ = None
+        self.dendrogram_row_ = None
+        self.dendrogram_col_ = None
+        self.dendrogram_full_ = None
+
+    def _split_vars(self, shape):
+        """Split variables."""
+        dendrogram_row, dendrogram_col = split_dendrogram(self.dendrogram_, shape)
+        self.dendrogram_full_ = self.dendrogram_
+        self.dendrogram_ = dendrogram_row
+        self.dendrogram_row_ = dendrogram_row
+        self.dendrogram_col_ = dendrogram_col
+        return self

sknetwork/hierarchy/louvain_hierarchy.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created in March 2020
+@author: Quentin Lutz <qlutz@enst.fr>
+@author: Thomas Bonald <tbonald@enst.fr>
+"""
+from typing import Optional, Union
+
+import numpy as np
+from scipy import sparse
+
+from sknetwork.clustering.louvain import Louvain
+from sknetwork.hierarchy.base import BaseHierarchy
+from sknetwork.hierarchy.postprocess import get_dendrogram, reorder_dendrogram
+from sknetwork.utils.check import check_format
+from sknetwork.utils.format import get_adjacency
+
+
+class LouvainIteration(BaseHierarchy):
+    """Hierarchical clustering by successive instances of Louvain (top-down).
+
+    Parameters
+    ----------
+    depth :
+        Depth of the tree.
+        A negative value is interpreted as no limit (return a tree of maximum depth).
+    resolution :
+        Resolution parameter.
+    tol_optimization :
+        Minimum increase in the objective function to enter a new optimization pass.
+    tol_aggregation :
+        Minimum increase in the objective function to enter a new aggregation pass.
+    n_aggregations :
+        Maximum number of aggregations.
+        A negative value is interpreted as no limit.
+    shuffle_nodes :
+        Enables node shuffling before optimization.
+    random_state :
+        Random number generator or random seed. If ``None``, numpy.random is used.
+    verbose :
+        Verbose mode.
+
+    Attributes
+    ----------
+    dendrogram_ :
+        Dendrogram of the graph.
+    dendrogram_row_ :
+        Dendrogram for the rows, for bipartite graphs.
+    dendrogram_col_ :
+        Dendrogram for the columns, for bipartite graphs.
+    dendrogram_full_ :
+        Dendrogram for both rows and columns, indexed in this order, for bipartite graphs.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import LouvainIteration
+    >>> from sknetwork.data import house
+    >>> louvain = LouvainIteration()
+    >>> adjacency = house()
+    >>> louvain.fit_predict(adjacency)
+    array([[3., 2., 0., 2.],
+           [4., 1., 0., 2.],
+           [6., 0., 0., 3.],
+           [5., 7., 1., 5.]])
+
+    Notes
+    -----
+    Each row of the dendrogram = merge nodes, distance, size of cluster.
+
+    See Also
+    --------
+    scipy.cluster.hierarchy.dendrogram
+    """
+
+    def __init__(self, depth: int = 3, resolution: float = 1, tol_optimization: float = 1e-3,
+                 tol_aggregation: float = 1e-3, n_aggregations: int = -1, shuffle_nodes: bool = False,
+                 random_state: Optional[Union[np.random.RandomState, int]] = None, verbose: bool = False):
+        super(LouvainIteration, self).__init__()
+
+        self.dendrogram_ = None
+        self.depth = depth
+        self._clustering_method = Louvain(resolution=resolution, tol_optimization=tol_optimization,
+                                          tol_aggregation=tol_aggregation, n_aggregations=n_aggregations,
+                                          shuffle_nodes=shuffle_nodes, random_state=random_state, verbose=verbose)
+        self.bipartite = None
+
+    def _recursive_louvain(self, adjacency: Union[sparse.csr_matrix, np.ndarray], depth: int,
+                           nodes: Optional[np.ndarray] = None):
+        """Recursive function for fit.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency matrix of the graph.
+        depth :
+            Depth of the recursion.
+        nodes :
+            The indices of the current nodes in the original graph.
+
+        Returns
+        -------
+        tree: recursive list of list of nodes.
+        """
+        n = adjacency.shape[0]
+        if nodes is None:
+            nodes = np.arange(n)
+
+        if adjacency.nnz and depth:
+            labels = self._clustering_method.fit_transform(adjacency)
+        else:
+            labels = np.zeros(n)
+
+        clusters = np.unique(labels)
+
+        tree = []
+        if len(clusters) == 1:
+            if len(nodes) > 1:
+                return [[node] for node in nodes]
+            else:
+                return [nodes[0]]
+        else:
+            for cluster in clusters:
+                mask = (labels == cluster)
+                nodes_cluster = nodes[mask]
+                adjacency_cluster = adjacency[mask, :][:, mask]
+                tree.append(self._recursive_louvain(adjacency_cluster, depth - 1, nodes_cluster))
+            return tree
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray]) -> 'LouvainIteration':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`LouvainIteration`
+        """
+        self._init_vars()
+        input_matrix = check_format(input_matrix)
+        adjacency, self.bipartite = get_adjacency(input_matrix)
+        tree = self._recursive_louvain(adjacency, self.depth)
+        dendrogram, _ = get_dendrogram(tree)
+        dendrogram = np.array(dendrogram)
+        dendrogram[:, 2] -= min(dendrogram[:, 2])
+        self.dendrogram_ = reorder_dendrogram(dendrogram)
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self
+
+
+class LouvainHierarchy(BaseHierarchy):
+    """Hierarchical clustering by Louvain (bottom-up).
+
+    Parameters
+    ----------
+    resolution :
+        Resolution parameter.
+    tol_optimization :
+        Minimum increase in the objective function to enter a new optimization pass.
+    tol_aggregation :
+        Minimum increase in the objective function to enter a new aggregation pass.
+    shuffle_nodes :
+        Enables node shuffling before optimization.
+    random_state :
+        Random number generator or random seed. If ``None``, numpy.random is used.
+    verbose :
+        Verbose mode.
+
+    Attributes
+    ----------
+    dendrogram_ :
+        Dendrogram of the graph.
+    dendrogram_row_ :
+        Dendrogram for the rows, for bipartite graphs.
+    dendrogram_col_ :
+        Dendrogram for the columns, for bipartite graphs.
+    dendrogram_full_ :
+        Dendrogram for both rows and columns, indexed in this order, for bipartite graphs.
+
+    Example
+    -------
+    >>> from sknetwork.hierarchy import LouvainHierarchy
+    >>> from sknetwork.data import house
+    >>> louvain = LouvainHierarchy()
+    >>> adjacency = house()
+    >>> louvain.fit_predict(adjacency)
+    array([[3., 2., 0., 2.],
+           [4., 1., 0., 2.],
+           [6., 0., 0., 3.],
+           [5., 7., 1., 5.]])
+
+    Notes
+    -----
+    Each row of the dendrogram = merge nodes, distance, size of cluster.
+
+    See Also
+    --------
+    scipy.cluster.hierarchy.dendrogram
+    """
+
+    def __init__(self, resolution: float = 1, tol_optimization: float = 1e-3,
+                 tol_aggregation: float = 1e-3, shuffle_nodes: bool = False,
+                 random_state: Optional[Union[np.random.RandomState, int]] = None, verbose: bool = False):
+        super(LouvainHierarchy, self).__init__()
+
+        self.dendrogram_ = None
+        self._clustering_method = Louvain(resolution=resolution, tol_optimization=tol_optimization,
+                                          tol_aggregation=tol_aggregation, n_aggregations=1,
+                                          shuffle_nodes=shuffle_nodes, random_state=random_state, verbose=verbose)
+        self.bipartite = None
+
+    def _get_hierarchy(self, adjacency: Union[sparse.csr_matrix, np.ndarray]):
+        """Get the hierarchy from Louvain.
+
+        Parameters
+        ----------
+        adjacency :
+            Adjacency matrix of the graph.
+
+        Returns
+        -------
+        tree: recursive list of list of nodes
+        """
+        tree = [[node] for node in range(adjacency.shape[0])]
+        labels = self._clustering_method.fit_transform(adjacency)
+        labels_unique = np.unique(labels)
+        while 1:
+            tree = [[tree[node] for node in np.flatnonzero(labels == label)] for label in labels_unique]
+            tree = [cluster[0] if len(cluster) == 1 else cluster for cluster in tree]
+            aggregate = self._clustering_method.aggregate_
+            labels = self._clustering_method.fit_transform(aggregate)
+            if len(labels_unique) == len(np.unique(labels)):
+                break
+            else:
+                labels_unique = np.unique(labels)
+        return tree
+
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray]) -> 'LouvainHierarchy':
+        """Fit algorithm to data.
+
+        Parameters
+        ----------
+        input_matrix :
+            Adjacency matrix or biadjacency matrix of the graph.
+
+        Returns
+        -------
+        self: :class:`LouvainIteration`
+        """
+        self._init_vars()
+        input_matrix = check_format(input_matrix)
+        adjacency, self.bipartite = get_adjacency(input_matrix)
+        tree = self._get_hierarchy(adjacency)
+        dendrogram, _ = get_dendrogram(tree)
+        dendrogram = np.array(dendrogram)
+        dendrogram[:, 2] -= min(dendrogram[:, 2])
+        self.dendrogram_ = reorder_dendrogram(dendrogram)
+        if self.bipartite:
+            self._split_vars(input_matrix.shape)
+        return self