scikit-network 0.31.0__cp39-cp39-win_amd64.whl → 0.33.0__cp39-cp39-win_amd64.whl

sknetwork/hierarchy/louvain_hierarchy.py

@@ -22,34 +22,34 @@ class LouvainIteration(BaseHierarchy):
 
     Parameters
     ----------
-    depth :
+    depth : int
         Depth of the tree.
         A negative value is interpreted as no limit (return a tree of maximum depth).
-    resolution :
+    resolution : float
         Resolution parameter.
-    tol_optimization :
+    tol_optimization : float
         Minimum increase in the objective function to enter a new optimization pass.
-    tol_aggregation :
+    tol_aggregation : float
         Minimum increase in the objective function to enter a new aggregation pass.
-    n_aggregations :
+    n_aggregations : int
         Maximum number of aggregations.
         A negative value is interpreted as no limit.
-    shuffle_nodes :
-        Enables node shuffling before optimization.
-    random_state :
+    shuffle_nodes : bool
+        If ``True``,  shuffle nodes before optimization.
+    random_state : int
         Random number generator or random seed. If ``None``, numpy.random is used.
-    verbose :
+    verbose : bool
         Verbose mode.
 
     Attributes
     ----------
-    dendrogram_ :
+    dendrogram_ : np.ndarray
         Dendrogram of the graph.
-    dendrogram_row_ :
+    dendrogram_row_ : np.ndarray
         Dendrogram for the rows, for bipartite graphs.
-    dendrogram_col_ :
+    dendrogram_col_ : np.ndarray
         Dendrogram for the columns, for bipartite graphs.
-    dendrogram_full_ :
+    dendrogram_full_ : np.ndarray
         Dendrogram for both rows and columns, indexed in this order, for bipartite graphs.
 
     Example
@@ -59,10 +59,10 @@ class LouvainIteration(BaseHierarchy):
     >>> 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.]])
+    array([[3., 2., 1., 2.],
+           [4., 1., 1., 2.],
+           [6., 0., 1., 3.],
+           [5., 7., 2., 5.]])
 
     Notes
     -----
@@ -71,6 +71,7 @@ class LouvainIteration(BaseHierarchy):
     See Also
     --------
     scipy.cluster.hierarchy.dendrogram
+    sknetwork.clustering.Louvain
     """
 
     def __init__(self, depth: int = 3, resolution: float = 1, tol_optimization: float = 1e-3,
@@ -91,11 +92,11 @@ class LouvainIteration(BaseHierarchy):
 
         Parameters
         ----------
-        adjacency :
+        adjacency : sparse.csr_matrix, np.ndarray
             Adjacency matrix of the graph.
-        depth :
+        depth : int
             Depth of the recursion.
-        nodes :
+        nodes : np.ndarray
             The indices of the current nodes in the original graph.
 
         Returns
@@ -127,25 +128,27 @@ class LouvainIteration(BaseHierarchy):
                 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':
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) \
+            -> 'LouvainIteration':
         """Fit algorithm to data.
 
         Parameters
         ----------
-        input_matrix :
+        input_matrix : sparse.csr_matrix, np.ndarray
             Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix.
 
         Returns
         -------
         self: :class:`LouvainIteration`
         """
         self._init_vars()
-        input_matrix = check_format(input_matrix)
-        adjacency, self.bipartite = get_adjacency(input_matrix)
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_bipartite=force_bipartite)
         tree = self._recursive_louvain(adjacency, self.depth)
         dendrogram, _ = get_dendrogram(tree)
         dendrogram = np.array(dendrogram)
-        dendrogram[:, 2] -= min(dendrogram[:, 2])
+        dendrogram[:, 2] += 1 - min(dendrogram[:, 2])
         self.dendrogram_ = reorder_dendrogram(dendrogram)
         if self.bipartite:
             self._split_vars(input_matrix.shape)
@@ -155,30 +158,32 @@ class LouvainIteration(BaseHierarchy):
 class LouvainHierarchy(BaseHierarchy):
     """Hierarchical clustering by Louvain (bottom-up).
 
+    Each level corresponds to an aggregation step of the Louvain algorithm.
+
     Parameters
     ----------
-    resolution :
+    resolution : float
         Resolution parameter.
-    tol_optimization :
+    tol_optimization : float
         Minimum increase in the objective function to enter a new optimization pass.
-    tol_aggregation :
+    tol_aggregation : float
         Minimum increase in the objective function to enter a new aggregation pass.
-    shuffle_nodes :
-        Enables node shuffling before optimization.
-    random_state :
+    shuffle_nodes : bool
+        If ``True``, shuffle nodes before optimization.
+    random_state : int
         Random number generator or random seed. If ``None``, numpy.random is used.
-    verbose :
+    verbose : bool
         Verbose mode.
 
     Attributes
     ----------
-    dendrogram_ :
+    dendrogram_ : np.ndarray
         Dendrogram of the graph.
-    dendrogram_row_ :
+    dendrogram_row_ : np.ndarray
         Dendrogram for the rows, for bipartite graphs.
-    dendrogram_col_ :
+    dendrogram_col_ : np.ndarray
         Dendrogram for the columns, for bipartite graphs.
-    dendrogram_full_ :
+    dendrogram_full_ : np.ndarray
         Dendrogram for both rows and columns, indexed in this order, for bipartite graphs.
 
     Example
@@ -188,10 +193,10 @@ class LouvainHierarchy(BaseHierarchy):
     >>> 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.]])
+    array([[3., 2., 1., 2.],
+           [4., 1., 1., 2.],
+           [6., 0., 1., 3.],
+           [5., 7., 2., 5.]])
 
     Notes
     -----
@@ -200,6 +205,7 @@ class LouvainHierarchy(BaseHierarchy):
     See Also
     --------
     scipy.cluster.hierarchy.dendrogram
+    sknetwork.clustering.Louvain
     """
 
     def __init__(self, resolution: float = 1, tol_optimization: float = 1e-3,
@@ -218,7 +224,7 @@ class LouvainHierarchy(BaseHierarchy):
 
         Parameters
         ----------
-        adjacency :
+        adjacency : sparse.csr_matrix, np.ndarray
             Adjacency matrix of the graph.
 
         Returns
@@ -239,25 +245,27 @@ class LouvainHierarchy(BaseHierarchy):
                 labels_unique = np.unique(labels)
         return tree
 
-    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray]) -> 'LouvainHierarchy':
+    def fit(self, input_matrix: Union[sparse.csr_matrix, np.ndarray], force_bipartite: bool = False) \
+            -> 'LouvainHierarchy':
         """Fit algorithm to data.
 
         Parameters
         ----------
-        input_matrix :
+        input_matrix : sparse.csr_matrix, np.ndarray
             Adjacency matrix or biadjacency matrix of the graph.
+        force_bipartite :
+            If ``True``, force the input matrix to be considered as a biadjacency matrix.
 
         Returns
         -------
-        self: :class:`LouvainIteration`
+        self: :class:`LouvainHierarchy`
         """
         self._init_vars()
-        input_matrix = check_format(input_matrix)
-        adjacency, self.bipartite = get_adjacency(input_matrix)
+        adjacency, self.bipartite = get_adjacency(input_matrix, force_bipartite=force_bipartite)
         tree = self._get_hierarchy(adjacency)
         dendrogram, _ = get_dendrogram(tree)
         dendrogram = np.array(dendrogram)
-        dendrogram[:, 2] -= min(dendrogram[:, 2])
+        dendrogram[:, 2] += 1 - min(dendrogram[:, 2])
         self.dendrogram_ = reorder_dendrogram(dendrogram)
         if self.bipartite:
             self._split_vars(input_matrix.shape)