risk-network 0.0.16b0__py3-none-any.whl → 0.0.16b2__py3-none-any.whl

risk/cluster/api.py

@@ -0,0 +1,273 @@
+"""
+risk/cluster/api
+~~~~~~~~~~~~~~~~
+"""
+
+import copy
+import random
+
+import networkx as nx
+import numpy as np
+from scipy.sparse import csr_matrix
+
+from ..log import log_header, logger, params
+from .cluster import cluster_method
+from ._community import (
+    calculate_greedy_modularity_clusters,
+    calculate_label_propagation_clusters,
+    calculate_leiden_clusters,
+    calculate_louvain_clusters,
+    calculate_markov_clustering_clusters,
+    calculate_spinglass_clusters,
+    calculate_walktrap_clusters,
+)
+
+
+class ClusterAPI:
+    """
+    Handles the loading of statistical results and annotation significance for clusters.
+
+    The ClusterAPI class provides methods for explicit clustering algorithms.
+    """
+
+    @cluster_method
+    def cluster_greedy(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+    ) -> csr_matrix:
+        """
+        Compute greedy modularity clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="greedy",
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+        network = copy.copy(network)
+        return calculate_greedy_modularity_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+
+    @cluster_method
+    def cluster_labelprop(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+    ) -> csr_matrix:
+        """
+        Compute label propagation clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="labelprop",
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+        network = copy.copy(network)
+        return calculate_label_propagation_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+
+    @cluster_method
+    def cluster_leiden(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+        resolution: float = 1.0,
+        random_seed: int = 888,
+    ) -> csr_matrix:
+        """
+        Compute Leiden clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+            resolution (float, optional): Resolution parameter for Leiden algorithm. Defaults to 1.0.
+            random_seed (int, optional): Random seed for reproducibility. Defaults to 888.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="leiden",
+            fraction_shortest_edges=fraction_shortest_edges,
+            resolution=resolution,
+            random_seed=random_seed,
+        )
+        # Additional logging for specific parameters
+        logger.debug(f"Resolution: {resolution}")
+        logger.debug(f"Random seed: {random_seed}")
+        # Set random seed for reproducibility
+        random.seed(random_seed)
+        np.random.seed(random_seed)
+        network = copy.copy(network)
+        return calculate_leiden_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+            resolution=resolution,
+            random_seed=random_seed,
+        )
+
+    @cluster_method
+    def cluster_louvain(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+        resolution: float = 0.1,
+        random_seed: int = 888,
+    ) -> csr_matrix:
+        """
+        Compute Louvain clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+            resolution (float, optional): Resolution parameter for Louvain algorithm. Defaults to 1.0.
+            random_seed (int, optional): Random seed for reproducibility. Defaults to 888.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="louvain",
+            fraction_shortest_edges=fraction_shortest_edges,
+            resolution=resolution,
+            random_seed=random_seed,
+        )
+        # Additional logging for specific parameters
+        logger.debug(f"Resolution: {resolution}")
+        logger.debug(f"Random seed: {random_seed}")
+        # Set random seed for reproducibility
+        random.seed(random_seed)
+        np.random.seed(random_seed)
+        network = copy.copy(network)
+        return calculate_louvain_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+            resolution=resolution,
+            random_seed=random_seed,
+        )
+
+    @cluster_method
+    def cluster_markov(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+    ) -> csr_matrix:
+        """
+        Compute Markov clustering clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="markov",
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+        network = copy.copy(network)
+        return calculate_markov_clustering_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+
+    @cluster_method
+    def cluster_spinglass(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+    ) -> csr_matrix:
+        """
+        Compute spinglass clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="spinglass",
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+        network = copy.copy(network)
+        return calculate_spinglass_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+
+    @cluster_method
+    def cluster_walktrap(
+        self,
+        network: nx.Graph,
+        fraction_shortest_edges: float = 0.5,
+    ) -> csr_matrix:
+        """
+        Compute walktrap clusters for the given network.
+
+        Args:
+            network (nx.Graph): The network graph to cluster.
+            fraction_shortest_edges (float, optional): Rank-based fraction (0, 1] of the shortest edges
+                retained when building the clustering subgraph. Defaults to 0.5.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        self._log_clustering_params(
+            clustering="walktrap",
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+        network = copy.copy(network)
+        return calculate_walktrap_clusters(
+            network,
+            fraction_shortest_edges=fraction_shortest_edges,
+        )
+
+    def _log_clustering_params(
+        self,
+        clustering: str,
+        fraction_shortest_edges: float,
+        **kwargs,
+    ) -> None:
+        """
+        Log clustering parameters for debugging and reproducibility.
+
+        Args:
+            clustering (str): The display name of the clustering method.
+            fraction_shortest_edges (float): Rank-based fraction (0, 1] of the shortest edges used for clustering.
+            **kwargs: Additional clustering parameters to log.
+        """
+        log_header("Computing clusters")
+        # Log and display cluster settings
+        logger.debug(f"Clustering: '{clustering}'")
+        logger.debug(f"Edge length threshold: {fraction_shortest_edges}")
+        # Log clustering parameters
+        params.log_clusters(
+            clustering=clustering,
+            fraction_shortest_edges=fraction_shortest_edges,
+            **kwargs,
+        )

risk/{_neighborhoods/_neighborhoods.py → cluster/cluster.py}

@@ -1,6 +1,6 @@
 """
-risk/_neighborhoods/_neighborhoods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/cluster/cluster
+~~~~~~~~~~~~~~~~~~~~
 """
 
 import random
@@ -13,116 +13,124 @@ from scipy.sparse import csr_matrix
 from sklearn.exceptions import DataConversionWarning
 from sklearn.metrics.pairwise import cosine_similarity
 
-from .._log import logger
+from ..log import logger
 from ._community import (
-    calculate_greedy_modularity_neighborhoods,
-    calculate_label_propagation_neighborhoods,
-    calculate_leiden_neighborhoods,
-    calculate_louvain_neighborhoods,
-    calculate_markov_clustering_neighborhoods,
-    calculate_spinglass_neighborhoods,
-    calculate_walktrap_neighborhoods,
+    calculate_greedy_modularity_clusters,
+    calculate_label_propagation_clusters,
+    calculate_leiden_clusters,
+    calculate_louvain_clusters,
+    calculate_markov_clustering_clusters,
+    calculate_spinglass_clusters,
+    calculate_walktrap_clusters,
 )
 
 # Suppress DataConversionWarning
 warnings.filterwarnings(action="ignore", category=DataConversionWarning)
 
 
-def get_network_neighborhoods(
+def cluster_method(func):
+    """
+    Decorator for clustering functions to ensure deterministic, reproducible results.
+    Sets random seeds, copies the network, and ensures output is normalized.
+
+    Args:
+        func (callable): The clustering function to be decorated.
+
+    Returns:
+        callable: The wrapped clustering function with added functionality.
+    """
+
+    def wrapper(*args, **kwargs):
+        """
+        Wrapper function to set random seeds and normalize output.
+
+        Args:
+            *args: Positional arguments for the clustering function.
+            **kwargs: Keyword arguments for the clustering function.
+
+        Returns:
+            csr_matrix: Sparse matrix representing cluster assignments.
+        """
+        clusters = func(*args, **kwargs)
+        return _set_max_row_value_to_one_sparse(clusters)
+
+    return wrapper
+
+
+def get_network_clusters(
     network: nx.Graph,
-    distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
-    fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 1.0,
+    clustering: str = "louvain",
+    fraction_shortest_edges: float = 0.5,
     louvain_resolution: float = 0.1,
     leiden_resolution: float = 1.0,
     random_seed: int = 888,
 ) -> csr_matrix:
     """
-    Calculate the combined neighborhoods for each node using sparse matrices.
+    Calculate clusters for the network using a single method.
 
     Args:
         network (nx.Graph): The network graph.
-        distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use.
-        fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction thresholds.
-        louvain_resolution (float, optional): Resolution parameter for the Louvain method.
-        leiden_resolution (float, optional): Resolution parameter for the Leiden method.
-        random_seed (int, optional): Random seed for methods requiring random initialization.
+        clustering (str, optional): The clustering method ('greedy', 'labelprop', 'leiden', 'louvain', 'markov', 'spinglass', 'walktrap').
+        fraction_shortest_edges (float, optional): Fraction of shortest edges to consider for creating subgraphs. Defaults to 0.5.
+        louvain_resolution (float, optional): Resolution for Louvain.
+        leiden_resolution (float, optional): Resolution for Leiden.
+        random_seed (int, optional): Random seed.
 
     Returns:
-        csr_matrix: The combined neighborhood matrix.
+        csr_matrix: Sparse cluster matrix.
 
     Raises:
-        ValueError: If the number of distance metrics does not match the number of edge length thresholds.
+        ValueError: If invalid clustering method is provided.
     """
-    # Set random seed for reproducibility
+    # Set random seed for cluster reproducibility
     random.seed(random_seed)
     np.random.seed(random_seed)
 
-    # Ensure distance_metric is a list for multi-algorithm handling
-    if isinstance(distance_metric, (str, np.ndarray)):
-        distance_metric = [distance_metric]
-    # Ensure fraction_shortest_edges is a list for multi-threshold handling
-    if isinstance(fraction_shortest_edges, (float, int)):
-        fraction_shortest_edges = [fraction_shortest_edges] * len(distance_metric)
-    # Validate matching lengths of distance metrics and thresholds
-    if len(distance_metric) != len(fraction_shortest_edges):
+    clusters = None
+    # Determine clustering method and compute clusters
+    if clustering == "greedy":
+        clusters = calculate_greedy_modularity_clusters(
+            network, fraction_shortest_edges=fraction_shortest_edges
+        )
+    elif clustering == "labelprop":
+        clusters = calculate_label_propagation_clusters(
+            network, fraction_shortest_edges=fraction_shortest_edges
+        )
+    elif clustering == "leiden":
+        clusters = calculate_leiden_clusters(
+            network,
+            resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            random_seed=random_seed,
+        )
+    elif clustering == "louvain":
+        clusters = calculate_louvain_clusters(
+            network,
+            resolution=louvain_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            random_seed=random_seed,
+        )
+    elif clustering == "markov":
+        clusters = calculate_markov_clustering_clusters(
+            network, fraction_shortest_edges=fraction_shortest_edges
+        )
+    elif clustering == "spinglass":
+        clusters = calculate_spinglass_clusters(
+            network, fraction_shortest_edges=fraction_shortest_edges
+        )
+    elif clustering == "walktrap":
+        clusters = calculate_walktrap_clusters(
+            network, fraction_shortest_edges=fraction_shortest_edges
+        )
+    else:
         raise ValueError(
-            "The number of distance metrics must match the number of edge length thresholds."
+            "Invalid clustering method. Choose from: 'greedy', 'labelprop', 'leiden', 'louvain', 'markov', 'spinglass', 'walktrap'."
         )
 
-    # Initialize a sparse LIL matrix for incremental updates
-    num_nodes = network.number_of_nodes()
-    # Initialize a sparse matrix with the same shape as the network
-    combined_neighborhoods = csr_matrix((num_nodes, num_nodes), dtype=np.uint8)
-    # Loop through each distance metric and corresponding edge rank fraction
-    for metric, percentile in zip(distance_metric, fraction_shortest_edges):
-        # Compute neighborhoods for the specified metric
-        if metric == "greedy_modularity":
-            neighborhoods = calculate_greedy_modularity_neighborhoods(
-                network, fraction_shortest_edges=percentile
-            )
-        elif metric == "label_propagation":
-            neighborhoods = calculate_label_propagation_neighborhoods(
-                network, fraction_shortest_edges=percentile
-            )
-        elif metric == "leiden":
-            neighborhoods = calculate_leiden_neighborhoods(
-                network,
-                resolution=leiden_resolution,
-                fraction_shortest_edges=percentile,
-                random_seed=random_seed,
-            )
-        elif metric == "louvain":
-            neighborhoods = calculate_louvain_neighborhoods(
-                network,
-                resolution=louvain_resolution,
-                fraction_shortest_edges=percentile,
-                random_seed=random_seed,
-            )
-        elif metric == "markov_clustering":
-            neighborhoods = calculate_markov_clustering_neighborhoods(
-                network, fraction_shortest_edges=percentile
-            )
-        elif metric == "spinglass":
-            neighborhoods = calculate_spinglass_neighborhoods(
-                network, fraction_shortest_edges=percentile
-            )
-        elif metric == "walktrap":
-            neighborhoods = calculate_walktrap_neighborhoods(
-                network, fraction_shortest_edges=percentile
-            )
-        else:
-            raise ValueError(
-                "Invalid distance metric. Choose from: 'greedy_modularity', 'label_propagation',"
-                "'leiden', 'louvain', 'markov_clustering', 'spinglass', 'walktrap'."
-            )
-
-        # Add the sparse neighborhood matrix
-        combined_neighborhoods += neighborhoods
-
-    # Ensure maximum value in each row is set to 1
-    combined_neighborhoods = _set_max_row_value_to_one_sparse(combined_neighborhoods)
+    # Ensure maximum per row set to 1
+    clusters = _set_max_row_value_to_one_sparse(clusters)
 
-    return combined_neighborhoods
+    return clusters
 
 
 def _set_max_row_value_to_one_sparse(matrix: csr_matrix) -> csr_matrix:
@@ -144,27 +152,29 @@ def _set_max_row_value_to_one_sparse(matrix: csr_matrix) -> csr_matrix:
     return matrix
 
 
-def process_neighborhoods(
+def process_significant_clusters(
     network: nx.Graph,
-    neighborhoods: Dict[str, Any],
+    significant_clusters: Dict[str, Any],
     impute_depth: int = 0,
     prune_threshold: float = 0.0,
 ) -> Dict[str, Any]:
     """
-    Process neighborhoods based on the imputation and pruning settings.
+    Process clusters based on the imputation and pruning settings.
 
     Args:
         network (nx.Graph): The network data structure used for imputing and pruning neighbors.
-        neighborhoods (Dict[str, Any]): Dictionary containing 'significance_matrix', 'significant_binary_significance_matrix', and 'significant_significance_matrix'.
+        significant_clusters (Dict[str, Any]): Dictionary containing 'significance_matrix', 'significant_binary_significance_matrix', and 'significant_significance_matrix'.
         impute_depth (int, optional): Depth for imputing neighbors. Defaults to 0.
         prune_threshold (float, optional): Distance threshold for pruning neighbors. Defaults to 0.0.
 
     Returns:
-        Dict[str, Any]: Processed neighborhoods data, including the updated matrices and significance counts.
+        Dict[str, Any]: Processed clusters data, including the updated matrices and significance counts.
     """
-    significance_matrix = neighborhoods["significance_matrix"]
-    significant_binary_significance_matrix = neighborhoods["significant_binary_significance_matrix"]
-    significant_significance_matrix = neighborhoods["significant_significance_matrix"]
+    significance_matrix = significant_clusters["significance_matrix"]
+    significant_binary_significance_matrix = significant_clusters[
+        "significant_binary_significance_matrix"
+    ]
+    significant_significance_matrix = significant_clusters["significant_significance_matrix"]
     logger.debug(f"Imputation depth: {impute_depth}")
     if impute_depth:
         (
@@ -191,13 +201,13 @@ def process_neighborhoods(
             distance_threshold=prune_threshold,
         )
 
-    neighborhood_significance_counts = np.sum(significant_binary_significance_matrix, axis=0)
+    cluster_significance_counts = np.sum(significant_binary_significance_matrix, axis=0)
     node_significance_sums = np.sum(significance_matrix, axis=1)
     return {
         "significance_matrix": significance_matrix,
         "significant_binary_significance_matrix": significant_binary_significance_matrix,
         "significant_significance_matrix": significant_significance_matrix,
-        "neighborhood_significance_counts": neighborhood_significance_counts,
+        "cluster_significance_counts": cluster_significance_counts,
         "node_significance_sums": node_significance_sums,
     }
 
@@ -395,6 +405,7 @@ def _prune_neighbors(
     non_zero_indices = np.where(significant_binary_significance_matrix.sum(axis=1) != 0)[0]
     median_distances = []
     distance_lookup = {}
+    isolated_nodes = []  # Track nodes with no significant neighbors
     for node in non_zero_indices:
         dist = _median_distance_to_significant_neighbors(
             node, network, significant_binary_significance_matrix
@@ -402,6 +413,8 @@ def _prune_neighbors(
         if dist is not None:
             median_distances.append(dist)
             distance_lookup[node] = dist
+        else:
+            isolated_nodes.append(node)  # Node has no significant neighbors
 
     if not median_distances:
         logger.warning("No significant neighbors found for pruning.")
@@ -422,6 +435,11 @@ def _prune_neighbors(
             significance_matrix[node] = 0
             significant_binary_significance_matrix[node] = 0
 
+    # Prune isolated nodes (no significant neighbors)
+    for node in isolated_nodes:
+        significance_matrix[node] = 0
+        significant_binary_significance_matrix[node] = 0
+
     # Create a matrix where non-significant entries are set to zero
     significant_significance_matrix = np.where(
         significant_binary_significance_matrix == 1, significance_matrix, 0
@@ -436,7 +454,7 @@ def _prune_neighbors(
 
 def _median_distance_to_significant_neighbors(
     node, network, significance_mask
-) -> Union[float, None]:
+) -> Union[float, Any, None]:
     """
     Calculate the median distance from a node to its significant neighbors.
 
@@ -448,11 +466,22 @@ def _median_distance_to_significant_neighbors(
     Returns:
         Union[float, None]: The median distance to significant neighbors, or None if no significant neighbors exist.
     """
-    neighbors = [n for n in network.neighbors(node) if significance_mask[n].sum() != 0]
+    # Get all neighbors at once
+    neighbors = list(network.neighbors(node))
     if not neighbors:
         return None
-    # Calculate distances to significant neighbors
-    distances = [_get_euclidean_distance(node, n, network) for n in neighbors]
+
+    # Vectorized check for significant neighbors
+    neighbors = np.array(neighbors)
+    significant_mask = significance_mask[neighbors].sum(axis=1) != 0
+    significant_neighbors = neighbors[significant_mask]
+    if len(significant_neighbors) == 0:
+        return None
+
+    # Vectorized distance calculation
+    node_pos = _get_node_position(network, node)
+    neighbor_positions = np.array([_get_node_position(network, n) for n in significant_neighbors])
+    distances = np.linalg.norm(neighbor_positions - node_pos, axis=1)
 
     return np.median(distances)