risk-network 0.0.8b18__py3-none-any.whl → 0.0.9b26__py3-none-any.whl

risk/log/{params.py → parameters.py}

@@ -1,50 +1,22 @@
 """
-risk/log/params
-~~~~~~~~~~~~~~~
+risk/log/parameters
+~~~~~~~~~~~~~~~~~~~
 """
 
 import csv
 import json
 import warnings
 from datetime import datetime
-from functools import wraps
 from typing import Any, Dict
 
 import numpy as np
 
-from .config import logger, log_header
+from risk.log.console import logger, log_header
 
 # Suppress all warnings - this is to resolve warnings from multiprocessing
 warnings.filterwarnings("ignore")
 
 
-def _safe_param_export(func):
-    """A decorator to wrap parameter export functions in a try-except block for safe execution.
-
-    Args:
-        func (function): The function to be wrapped.
-
-    Returns:
-        function: The wrapped function with error handling.
-    """
-
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        try:
-            result = func(*args, **kwargs)
-            filepath = (
-                kwargs.get("filepath") or args[1]
-            )  # Assuming filepath is always the second argument
-            logger.info(f"Parameters successfully exported to filepath: {filepath}")
-            return result
-        except Exception as e:
-            filepath = kwargs.get("filepath") or args[1]
-            logger.error(f"An error occurred while exporting parameters to {filepath}: {e}")
-            return None
-
-    return wrapper
-
-
 class Params:
     """Handles the storage and logging of various parameters for network analysis.
 
@@ -106,7 +78,6 @@ class Params:
         """
         self.plotter = {**self.plotter, **kwargs}
 
-    @_safe_param_export
     def to_csv(self, filepath: str) -> None:
         """Export the parameters to a CSV file.
 
@@ -116,7 +87,7 @@ class Params:
         # Load the parameter dictionary
         params = self.load()
         # Open the file in write mode
-        with open(filepath, "w", newline="") as csv_file:
+        with open(filepath, "w", encoding="utf-8", newline="") as csv_file:
             writer = csv.writer(csv_file)
             # Write the header
             writer.writerow(["parent_key", "child_key", "value"])
@@ -128,17 +99,19 @@ class Params:
                 else:
                     writer.writerow([parent_key, "", parent_value])
 
-    @_safe_param_export
+        logger.info(f"Parameters exported to CSV file: {filepath}")
+
     def to_json(self, filepath: str) -> None:
         """Export the parameters to a JSON file.
 
         Args:
             filepath (str): The path where the JSON file will be saved.
         """
-        with open(filepath, "w") as json_file:
+        with open(filepath, "w", encoding="utf-8") as json_file:
             json.dump(self.load(), json_file, indent=4)
 
-    @_safe_param_export
+        logger.info(f"Parameters exported to JSON file: {filepath}")
+
     def to_txt(self, filepath: str) -> None:
         """Export the parameters to a text file.
 
@@ -148,18 +121,20 @@ class Params:
         # Load the parameter dictionary
         params = self.load()
         # Open the file in write mode
-        with open(filepath, "w") as txt_file:
+        with open(filepath, "w", encoding="utf-8") as txt_file:
             for key, value in params.items():
                 # Write the key and its corresponding value
                 txt_file.write(f"{key}: {value}\n")
             # Add a blank line after each entry
             txt_file.write("\n")
 
+        logger.info(f"Parameters exported to text file: {filepath}")
+
     def load(self) -> Dict[str, Any]:
         """Load and process various parameters, converting any np.ndarray values to lists.
 
         Returns:
-            dict: A dictionary containing the processed parameters.
+            Dict[str, Any]: A dictionary containing the processed parameters.
         """
         log_header("Loading parameters")
         return _convert_ndarray_to_list(
@@ -174,24 +149,24 @@ class Params:
         )
 
 
-def _convert_ndarray_to_list(d: Any) -> Any:
+def _convert_ndarray_to_list(d: Dict[str, Any]) -> Dict[str, Any]:
     """Recursively convert all np.ndarray values in the dictionary to lists.
 
     Args:
-        d (dict): The dictionary to process.
+        d (Dict[str, Any]): The dictionary to process.
 
     Returns:
-        dict: The processed dictionary with np.ndarray values converted to lists.
+        Dict[str, Any]: The processed dictionary with np.ndarray values converted to lists.
     """
     if isinstance(d, dict):
         # Recursively process each value in the dictionary
         return {k: _convert_ndarray_to_list(v) for k, v in d.items()}
-    elif isinstance(d, list):
+    if isinstance(d, list):
         # Recursively process each item in the list
         return [_convert_ndarray_to_list(v) for v in d]
-    elif isinstance(d, np.ndarray):
+    if isinstance(d, np.ndarray):
         # Convert numpy arrays to lists
         return d.tolist()
-    else:
-        # Return the value unchanged if it's not a dict, list, or ndarray
-        return d
+
+    # Return the value unchanged if it's not a dict, List, or ndarray
+    return d

risk/neighborhoods/__init__.py

@@ -3,8 +3,6 @@ risk/neighborhoods
 ~~~~~~~~~~~~~~~~~~
 """
 
-from .domains import define_domains, trim_domains_and_top_annotations
-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