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

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)
 

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

@@ -1,6 +1,6 @@
 """
-risk/_neighborhoods/_domains
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/cluster/label
+~~~~~~~~~~~~~~~~~~
 """
 
 from itertools import product
@@ -13,9 +13,9 @@ from scipy.cluster.hierarchy import fcluster, linkage
 from sklearn.metrics import silhouette_score
 from tqdm import tqdm
 
-from risk._annotation import get_weighted_description
+from risk.annotation import get_weighted_description
 
-from .._log import logger
+from ..log import logger
 
 # Define constants for clustering
 # fmt: off
@@ -30,7 +30,7 @@ LINKAGE_METRICS = {
 
 def define_domains(
     top_annotation: pd.DataFrame,
-    significant_neighborhoods_significance: np.ndarray,
+    significant_clusters_significance: np.ndarray,
     linkage_criterion: str,
     linkage_method: str,
     linkage_metric: str,
@@ -42,7 +42,7 @@ def define_domains(
 
     Args:
         top_annotation (pd.DataFrame): DataFrame of top annotations data for the network nodes.
-        significant_neighborhoods_significance (np.ndarray): The binary significance matrix below alpha.
+        significant_clusters_significance (np.ndarray): The binary significance matrix below alpha.
         linkage_criterion (str): The clustering criterion for defining groups. Choose "off" to disable clustering.
         linkage_method (str): The linkage method for clustering. Choose "auto" to optimize.
         linkage_metric (str): The linkage metric for clustering. Choose "auto" to optimize.
@@ -66,11 +66,11 @@ def define_domains(
         top_annotation["domain"] = range(1, n_rows + 1)
     else:
         # Transpose the matrix to cluster annotations
-        m = significant_neighborhoods_significance[:, top_annotation["significant_annotation"]].T
+        m = significant_clusters_significance[:, top_annotation["significant_annotation"]].T
         # Safeguard the matrix by replacing NaN, Inf, and -Inf values
         m = _safeguard_matrix(m)
         try:
-            # Optimize silhouette score across different linkage methods and distance metrics
+            # Optimize silhouette score across different linkage methods and metrics
             (
                 best_linkage,
                 best_metric,
@@ -99,7 +99,7 @@ def define_domains(
 
     # Create DataFrames to store domain information
     node_to_significance = pd.DataFrame(
-        data=significant_neighborhoods_significance,
+        data=significant_clusters_significance,
         columns=[top_annotation.index.values, top_annotation["domain"]],
     )
     node_to_domain = node_to_significance.T.groupby(level="domain").sum().T
@@ -152,9 +152,9 @@ def trim_domains(
     top_annotation["domain"] = top_annotation["domain"].replace(to_remove, invalid_domain_id)
     domains.loc[domains["primary_domain"].isin(to_remove), ["primary_domain"]] = invalid_domain_id
 
-    # Normalize "num significant neighborhoods" by percentile for each domain and scale to 0-10
+    # Normalize "num significant clusters" by percentile for each domain and scale to 0-10
     top_annotation["normalized_value"] = top_annotation.groupby("domain")[
-        "significant_neighborhood_significance_sums"
+        "significant_cluster_significance_sums"
     ].transform(lambda x: (x.rank(pct=True) * 10).apply(np.ceil).astype(int))
     # Modify the lambda function to pass both full_terms and significant_significance_score
     top_annotation["combined_terms"] = top_annotation.apply(
@@ -245,6 +245,12 @@ def _safeguard_matrix(matrix: np.ndarray) -> np.ndarray:
     Returns:
         np.ndarray: Safeguarded data matrix.
     """
+    # Safety guard: handle empty or invalid matrices
+    if matrix.size == 0 or not np.isfinite(matrix).any():
+        logger.warning(
+            "Input matrix is empty or contains no finite values. Returning a zero matrix of same shape."
+        )
+        return np.zeros(matrix.shape, dtype=float)
     # Replace NaN with column mean
     nan_replacement = np.nanmean(matrix, axis=0)
     matrix = np.where(np.isnan(matrix), nan_replacement, matrix)
@@ -267,7 +273,7 @@ def _optimize_silhouette_across_linkage_and_metrics(
     linkage_threshold: Union[str, float],
 ) -> Tuple[str, str, float]:
     """
-    Optimize silhouette score across different linkage methods and distance metrics.
+    Optimize silhouette score across different linkage methods and metrics.
 
     Args:
         m (np.ndarray): Data matrix.

risk/{_log → log}/__init__.py

@@ -3,8 +3,8 @@ risk/_log
 ~~~~~~~~~
 """
 
-from ._console import log_header, logger, set_global_verbosity
-from ._parameters import Params
+from .console import log_header, logger, set_global_verbosity
+from .parameters import Params
 
 # Initialize the global parameters logger
 params = Params()

risk/{_log/_console.py → log/console.py}

@@ -1,6 +1,6 @@
 """
-risk/_log/_console
-~~~~~~~~~~~~~~~~~~
+risk/log/console
+~~~~~~~~~~~~~~~~
 """
 
 import logging

risk/{_log/_parameters.py → log/parameters.py}

@@ -1,6 +1,6 @@
 """
-risk/_log/_parameters
-~~~~~~~~~~~~~~~~~~~~~
+risk/log/parameters
+~~~~~~~~~~~~~~~~~~~
 """
 
 import csv
@@ -11,7 +11,7 @@ from typing import Any, Dict
 
 import numpy as np
 
-from ._console import log_header, logger
+from .console import log_header, logger
 
 # Suppress all warnings - this is to resolve warnings from multiprocessing
 warnings.filterwarnings("ignore")
@@ -22,7 +22,7 @@ class Params:
     Handles the storage and logging of various parameters for network analysis.
 
     The Params class provides methods to log parameters related to different components of the analysis,
-    such as the network, annotation, neighborhoods, graph, and plotter settings. It also stores
+    such as the network, annotation, clusters, graph, and plotter settings. It also stores
     the current datetime when the parameters were initialized.
     """
 
@@ -35,7 +35,8 @@ class Params:
         """Initialize the parameter dictionaries for different components."""
         self.network = {}
         self.annotation = {}
-        self.neighborhoods = {}
+        self.clusters = {}
+        self.stats = {}
         self.graph = {}
         self.plotter = {}
 
@@ -57,14 +58,23 @@ class Params:
         """
         self.annotation = {**self.annotation, **kwargs}
 
-    def log_neighborhoods(self, **kwargs) -> None:
+    def log_clusters(self, **kwargs) -> None:
         """
-        Log neighborhood-related parameters.
+        Log cluster-related parameters.
 
         Args:
-            **kwargs: Neighborhood parameters to log.
+            **kwargs: Cluster parameters to log.
         """
-        self.neighborhoods = {**self.neighborhoods, **kwargs}
+        self.clusters = {**self.clusters, **kwargs}
+
+    def log_stats(self, **kwargs) -> None:
+        """
+        Log statistical test-related parameters.
+
+        Args:
+            **kwargs: Statistical test parameters to log.
+        """
+        self.stats = {**self.stats, **kwargs}
 
     def log_graph(self, **kwargs) -> None:
         """
@@ -152,7 +162,7 @@ class Params:
                 "annotation": self.annotation,
                 "datetime": self.datetime,
                 "graph": self.graph,
-                "neighborhoods": self.neighborhoods,
+                "clusters": self.clusters,
                 "network": self.network,
                 "plotter": self.plotter,
             }

risk/network/__init__.py

@@ -0,0 +1,8 @@
+"""
+risk/_network
+~~~~~~~~~~~~~
+"""
+
+from .graph import GraphAPI
+from .io import NetworkAPI
+from .plotter import PlotterAPI

risk/network/graph/__init__.py

@@ -0,0 +1,7 @@
+"""
+risk/network/graph
+~~~~~~~~~~~~~~~~~~
+"""
+
+from .api import GraphAPI
+from .graph import Graph

risk/{_network/_graph → network/graph}/_stats.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_graph/_stats
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/_stats
+~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, Union

risk/{_network/_graph → network/graph}/_summary.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_graph/_summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/_summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, Tuple, Union
@@ -9,35 +9,35 @@ import numpy as np
 import pandas as pd
 from statsmodels.stats.multitest import fdrcorrection
 
-from ..._log import log_header, logger
+from ...log import log_header, logger
 
 
 class Summary:
     """
     Handles the processing, storage, and export of network analysis results.
 
-    The Results class provides methods to process significance and depletion data, compute
-    FDR-corrected q-values, and structure information on domains and annotations into a
-    DataFrame. It also offers functionality to export the processed data in CSV, JSON,
-    and text formats for analysis and reporting.
+    The Summary class provides methods to process significance and depletion data,
+    compute FDR-corrected q-values, and structure information on domains and
+    annotations into a DataFrame. It also offers functionality to export the
+    processed data in CSV, JSON, and text formats for analysis and reporting.
     """
 
     def __init__(
         self,
         annotation: Dict[str, Any],
-        neighborhoods: Dict[str, Any],
+        stats_results: Dict[str, Any],
         graph,  # Avoid type hinting Graph to prevent circular imports
     ):
         """
-        Initialize the Results object with analysis components.
+        Initialize the Summary object with analysis components.
 
         Args:
             annotation (Dict[str, Any]): Annotation data, including ordered annotations and matrix of associations.
-            neighborhoods (Dict[str, Any]): Neighborhood data containing p-values for significance and depletion analysis.
+            stats_results (Dict[str, Any]): Cluster data containing p-values for significance and depletion analysis.
             graph (Graph): Graph object representing domain-to-node and node-to-label mappings.
         """
         self.annotation = annotation
-        self.neighborhoods = neighborhoods
+        self.stats_results = stats_results
         self.graph = graph
 
     def to_csv(self, filepath: str) -> None:
@@ -88,8 +88,8 @@ class Summary:
         """
         log_header("Loading analysis summary")
         # Calculate significance and depletion q-values from p-value matrices in annotation
-        enrichment_pvals = self.neighborhoods["enrichment_pvals"]
-        depletion_pvals = self.neighborhoods["depletion_pvals"]
+        enrichment_pvals = self.stats_results["enrichment_pvals"]
+        depletion_pvals = self.stats_results["depletion_pvals"]
         enrichment_qvals = self._calculate_qvalues(enrichment_pvals)
         depletion_qvals = self._calculate_qvalues(depletion_pvals)