risk-network 0.0.9b23__py3-none-any.whl → 0.0.9b25__py3-none-any.whl

risk/__init__.py

@@ -7,4 +7,4 @@ RISK: Regional Inference of Significant Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.9-beta.23"
+__version__ = "0.0.9-beta.25"

risk/annotations/__init__.py

@@ -3,5 +3,5 @@ risk/annotations
 ~~~~~~~~~~~~~~~~
 """
 
-from .annotations import define_top_annotations, get_weighted_description
-from .io import AnnotationsIO
+from risk.annotations.annotations import define_top_annotations, get_weighted_description
+from risk.annotations.io import AnnotationsIO

risk/annotations/annotations.py

@@ -16,6 +16,7 @@ from nltk.tokenize import word_tokenize
 from nltk.corpus import stopwords
 
 from risk.log import logger
+from scipy.sparse import csr_matrix
 
 
 def _setup_nltk():
@@ -47,17 +48,15 @@ def load_annotations(
         annotations_input (Dict[str, Any]): A dictionary with annotations.
         min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
             term to be included. Defaults to 2.
+        use_sparse (bool, optional): Whether to return the annotations matrix as a sparse matrix. Defaults to True.
 
     Returns:
-        Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the binary annotations matrix.
+        Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the sparse binary annotations
+            matrix.
 
     Raises:
         ValueError: If no annotations are found for the nodes in the network.
         ValueError: If no annotations have at least min_nodes_per_term nodes in the network.
-
-    Comment:
-        This function should be optimized to handle large networks and annotations efficiently. An attempt
-        to use sparse matrices did not yield significant performance improvements, so it was not implemented.
     """
     # Flatten the dictionary to a list of tuples for easier DataFrame creation
     flattened_annotations = [
@@ -78,7 +77,6 @@ def load_annotations(
         raise ValueError("No terms found in the annotation file for the nodes in the network.")
 
     # Filter out annotations with fewer than min_nodes_per_term occurrences
-    # This assists in reducing noise and focusing on more relevant annotations for statistical analysis
     num_terms_before_filtering = annotations_pivot.shape[1]
     annotations_pivot = annotations_pivot.loc[
         :, (annotations_pivot.sum(axis=0) >= min_nodes_per_term)
@@ -96,13 +94,15 @@ def load_annotations(
     # Extract ordered nodes and annotations
     ordered_nodes = tuple(annotations_pivot.index)
     ordered_annotations = tuple(annotations_pivot.columns)
-    # Convert the annotations_pivot matrix to a numpy array and ensure it's binary
-    annotations_pivot_numpy = (annotations_pivot.fillna(0).to_numpy() > 0).astype(int)
+    # Convert the annotations_pivot matrix to a numpy array or sparse matrix
+    annotations_pivot_binary = (annotations_pivot.fillna(0).to_numpy() > 0).astype(int)
+    # Convert the binary annotations matrix to a sparse matrix
+    annotations_pivot_binary = csr_matrix(annotations_pivot_binary)
 
     return {
         "ordered_nodes": ordered_nodes,
         "ordered_annotations": ordered_annotations,
-        "matrix": annotations_pivot_numpy,
+        "matrix": annotations_pivot_binary,
     }
 
 

risk/annotations/io.py

@@ -1,8 +1,6 @@
 """
 risk/annotations/io
 ~~~~~~~~~~~~~~~~~~~
-
-This file contains the code for the RISK class and command-line access.
 """
 
 import json

risk/log/__init__.py

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

risk/neighborhoods/__init__.py

@@ -3,8 +3,6 @@ risk/neighborhoods
 ~~~~~~~~~~~~~~~~~~
 """
 
-from .domains import define_domains, trim_domains
-from .neighborhoods import (
-    get_network_neighborhoods,
-    process_neighborhoods,
-)
+from risk.neighborhoods.domains import define_domains, trim_domains
+from risk.neighborhoods.api import NeighborhoodsAPI
+from risk.neighborhoods.neighborhoods import process_neighborhoods

risk/neighborhoods/api.py

@@ -0,0 +1,446 @@
+"""
+risk/neighborhoods/api
+~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+import copy
+from typing import Any, Dict, List, Tuple, Union
+
+import networkx as nx
+import numpy as np
+from scipy.sparse import csr_matrix
+
+from risk.log import logger, log_header, params
+from risk.neighborhoods.neighborhoods import get_network_neighborhoods
+from risk.stats import (
+    compute_binom_test,
+    compute_chi2_test,
+    compute_hypergeom_test,
+    compute_permutation_test,
+    compute_poisson_test,
+    compute_zscore_test,
+)
+
+
+class NeighborhoodsAPI:
+    """Handles the loading of statistical results and annotation significance for neighborhoods.
+
+    The NeighborhoodsAPI class provides methods to load neighborhood results from statistical tests.
+    """
+
+    def __init__() -> None:
+        pass
+
+    def load_neighborhoods_by_binom(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the binomial test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running binomial test")
+        # Compute neighborhood significance using the binomial test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="binom",
+            statistical_test_function=compute_binom_test,
+        )
+
+    def load_neighborhoods_by_chi2(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the chi-squared test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running chi-squared test")
+        # Compute neighborhood significance using the chi-squared test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="chi2",
+            statistical_test_function=compute_chi2_test,
+        )
+
+    def load_neighborhoods_by_hypergeom(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the hypergeometric test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running hypergeometric test")
+        # Compute neighborhood significance using the hypergeometric test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="hypergeom",
+            statistical_test_function=compute_hypergeom_test,
+        )
+
+    def load_neighborhoods_by_permutation(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        score_metric: str = "sum",
+        null_distribution: str = "network",
+        num_permutations: int = 1000,
+        random_seed: int = 888,
+        max_workers: int = 1,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the permutation test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            score_metric (str, optional): Scoring metric for neighborhood significance. Defaults to "sum".
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            num_permutations (int, optional): Number of permutations for significance testing. Defaults to 1000.
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+            max_workers (int, optional): Maximum number of workers for parallel computation. Defaults to 1.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running permutation test")
+        # Log and display permutation test settings, which is unique to this test
+        logger.debug(f"Neighborhood scoring metric: '{score_metric}'")
+        logger.debug(f"Number of permutations: {num_permutations}")
+        logger.debug(f"Maximum workers: {max_workers}")
+        # Compute neighborhood significance using the permutation test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="permutation",
+            statistical_test_function=compute_permutation_test,
+            score_metric=score_metric,
+            num_permutations=num_permutations,
+            max_workers=max_workers,
+        )
+
+    def load_neighborhoods_by_poisson(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the Poisson test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running Poisson test")
+        # Compute neighborhood significance using the Poisson test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="poisson",
+            statistical_test_function=compute_poisson_test,
+        )
+
+    def load_neighborhoods_by_zscore(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+    ) -> Dict[str, Any]:
+        """Load significant neighborhoods for the network using the Z-score test.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            Dict[str, Any]: Computed significance of neighborhoods.
+        """
+        log_header("Running Z-score test")
+        # Compute neighborhood significance using the Z-score test
+        return self._load_neighborhoods_by_statistical_test(
+            network=network,
+            annotations=annotations,
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            statistical_test_key="zscore",
+            statistical_test_function=compute_zscore_test,
+        )
+
+    def _load_neighborhoods_by_statistical_test(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        null_distribution: str = "network",
+        random_seed: int = 888,
+        statistical_test_key: str = "hypergeom",
+        statistical_test_function: Any = compute_hypergeom_test,
+        **kwargs,
+    ):
+        """Load and compute significant neighborhoods for the network using a specified statistical test.
+
+        Args:
+            network (nx.Graph): The input network graph.
+            annotations (Dict[str, Any]): Annotation data associated with the network, including a "matrix" key with annotation values.
+            distance_metric (Union[str, List, Tuple, np.ndarray], optional): The distance metric or clustering method to define neighborhoods.
+                Can be a string specifying one method (e.g., 'louvain', 'leiden') or a collection of methods.
+                Defaults to "louvain".
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (Union[float, List, Tuple, np.ndarray], optional): Fraction of shortest edges to consider for creating subgraphs.
+                Can be a single value or a collection of thresholds for flexibility. Defaults to 0.5.
+            null_distribution (str, optional): The type of null distribution to use ('network' or 'annotations').
+                Defaults to "network".
+            random_seed (int, optional): Seed for random number generation to ensure reproducibility. Defaults to 888.
+            statistical_test_key (str, optional): Key or name of the statistical test to be applied (e.g., "hypergeom", "poisson").
+                Used for logging and debugging. Defaults to "hypergeom".
+            statistical_test_function (Any, optional): The function implementing the statistical test.
+                It should accept neighborhoods, annotations, null distribution, and additional kwargs.
+                Defaults to `compute_hypergeom_test`.
+            **kwargs: Additional parameters to be passed to the statistical test function.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the computed significance values for neighborhoods.
+        """
+        # Log null distribution type
+        logger.debug(f"Null distribution: '{null_distribution}'")
+        # Log neighborhood analysis parameters
+        params.log_neighborhoods(
+            distance_metric=distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            statistical_test_function=statistical_test_key,
+            null_distribution=null_distribution,
+            random_seed=random_seed,
+            **kwargs,
+        )
+
+        # Make a copy of the network to avoid modifying the original
+        network = copy.deepcopy(network)
+        # Load neighborhoods based on the network and distance metric
+        neighborhoods = self._load_neighborhoods(
+            network,
+            distance_metric,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            fraction_shortest_edges=fraction_shortest_edges,
+            random_seed=random_seed,
+        )
+        # Apply statistical test function to compute neighborhood significance
+        neighborhood_significance = statistical_test_function(
+            neighborhoods=neighborhoods,
+            annotations=annotations["matrix"],
+            null_distribution=null_distribution,
+            **kwargs,
+        )
+
+        # Return the computed neighborhood significance
+        return neighborhood_significance
+
+    def _load_neighborhoods(
+        self,
+        network: nx.Graph,
+        distance_metric: Union[str, List, Tuple, np.ndarray] = "louvain",
+        louvain_resolution: float = 0.1,
+        leiden_resolution: float = 1.0,
+        fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
+        random_seed: int = 888,
+    ) -> csr_matrix:
+        """Load significant neighborhoods for the network.
+
+        Args:
+            network (nx.Graph): The network graph.
+            distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
+                metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
+                'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
+            louvain_resolution (float, optional): Resolution parameter for Louvain clustering. Defaults to 0.1.
+            leiden_resolution (float, optional): Resolution parameter for Leiden clustering. Defaults to 1.0.
+            fraction_shortest_edges (float, List, Tuple, or np.ndarray, optional): Shortest edge rank fraction threshold(s) for creating subgraphs.
+                Can be a single float for one threshold or a list/tuple of floats corresponding to multiple thresholds.
+                Defaults to 0.5.
+            random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+        Returns:
+            csr_matrix: Sparse neighborhood matrix calculated based on the selected distance metric.
+        """
+        # Display the chosen distance metric
+        if distance_metric == "louvain":
+            for_print_distance_metric = f"louvain (resolution={louvain_resolution})"
+        elif distance_metric == "leiden":
+            for_print_distance_metric = f"leiden (resolution={leiden_resolution})"
+        else:
+            for_print_distance_metric = distance_metric
+
+        # Log and display neighborhood settings
+        logger.debug(f"Distance metric: '{for_print_distance_metric}'")
+        logger.debug(f"Edge length threshold: {fraction_shortest_edges}")
+        logger.debug(f"Random seed: {random_seed}")
+
+        # Compute neighborhoods
+        neighborhoods = get_network_neighborhoods(
+            network,
+            distance_metric,
+            fraction_shortest_edges,
+            louvain_resolution=louvain_resolution,
+            leiden_resolution=leiden_resolution,
+            random_seed=random_seed,
+        )
+
+        # Ensure the neighborhood matrix is in sparse format
+        if not isinstance(neighborhoods, csr_matrix):
+            neighborhoods = csr_matrix(neighborhoods)
+
+        # Return the sparse neighborhood matrix
+        return neighborhoods

risk/neighborhoods/community.py

@@ -11,6 +11,8 @@ import numpy as np
 from leidenalg import find_partition, RBConfigurationVertexPartition
 from networkx.algorithms.community import greedy_modularity_communities
 
+from risk.log import logger
+
 
 def calculate_greedy_modularity_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
@@ -266,14 +268,14 @@ def calculate_spinglass_neighborhoods(
         igraph_subgraph = ig.Graph.from_networkx(subgraph)
         # Ensure the subgraph is connected before running Spinglass
         if not igraph_subgraph.is_connected():
-            print("Warning: Subgraph is not connected. Skipping...")
+            logger.error("Warning: Subgraph is not connected. Skipping...")
             continue
 
         # Apply Spinglass community detection
         try:
             communities = igraph_subgraph.community_spinglass()
         except Exception as e:
-            print(f"Error running Spinglass on component: {e}")
+            logger.error(f"Error running Spinglass on component: {e}")
             continue
 
         # Step 3: Assign neighborhoods based on community labels

risk/neighborhoods/domains.py

@@ -41,6 +41,9 @@ def define_domains(
     try:
         # Transpose the matrix to cluster annotations
         m = significant_neighborhoods_significance[:, top_annotations["significant_annotations"]].T
+        # Safeguard the matrix by replacing NaN, Inf, and -Inf values
+        m = _safeguard_matrix(m)
+        # Optimize silhouette score across different linkage methods and distance metrics
         best_linkage, best_metric, best_threshold = _optimize_silhouette_across_linkage_and_metrics(
             m, linkage_criterion, linkage_method, linkage_metric
         )
@@ -161,6 +164,29 @@ def trim_domains(
     return valid_domains, valid_trimmed_domains_matrix
 
 
+def _safeguard_matrix(matrix: np.ndarray) -> np.ndarray:
+    """Safeguard the matrix by replacing NaN, Inf, and -Inf values.
+
+    Args:
+        matrix (np.ndarray): Data matrix.
+
+    Returns:
+        np.ndarray: Safeguarded data matrix.
+    """
+    # Replace NaN with column mean
+    nan_replacement = np.nanmean(matrix, axis=0)
+    matrix = np.where(np.isnan(matrix), nan_replacement, matrix)
+    # Replace Inf/-Inf with maximum/minimum finite values
+    finite_max = np.nanmax(matrix[np.isfinite(matrix)])
+    finite_min = np.nanmin(matrix[np.isfinite(matrix)])
+    matrix = np.where(np.isposinf(matrix), finite_max, matrix)
+    matrix = np.where(np.isneginf(matrix), finite_min, matrix)
+    # Ensure rows have non-zero variance (optional step)
+    row_variance = np.var(matrix, axis=1)
+    matrix = matrix[row_variance > 0]
+    return matrix
+
+
 def _optimize_silhouette_across_linkage_and_metrics(
     m: np.ndarray, linkage_criterion: str, linkage_method: str, linkage_metric: str
 ) -> Tuple[str, str, float]:
@@ -194,7 +220,8 @@ def _optimize_silhouette_across_linkage_and_metrics(
         total=total_combinations,
         bar_format="{l_bar}{bar}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}]",
     ):
-        with suppress(Exception):
+        # Some linkage methods and metrics may not work with certain data
+        with suppress(ValueError):
             Z = linkage(m, method=method, metric=metric)
             threshold, score = _find_best_silhouette_score(Z, m, metric, linkage_criterion)
             if score > best_overall_score:

risk/network/__init__.py

@@ -3,6 +3,4 @@ risk/network
 ~~~~~~~~~~~~
 """
 
-from .graph import NetworkGraph
-from .io import NetworkIO
-from .plot import NetworkPlotter
+from risk.network.io import NetworkIO

risk/network/graph/__init__.py

@@ -3,4 +3,4 @@ risk/network/graph
 ~~~~~~~~~~~~~~~~~~
 """
 
-from .network import NetworkGraph
+from risk.network.graph.api import GraphAPI