risk-network 0.0.13b4__py3-none-any.whl → 0.0.14__py3-none-any.whl

risk/{neighborhoods/community.py → _neighborhoods/_community.py}

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/community
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_community
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import community as community_louvain
@@ -12,13 +12,14 @@ from leidenalg import RBConfigurationVertexPartition, find_partition
 from networkx.algorithms.community import greedy_modularity_communities
 from scipy.sparse import csr_matrix
 
-from risk.log import logger
+from .._log import logger
 
 
 def calculate_greedy_modularity_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
 ) -> csr_matrix:
-    """Calculate neighborhoods using the Greedy Modularity method with CSR matrix output.
+    """
+    Calculate neighborhoods using the Greedy Modularity method with CSR matrix output.
 
     Args:
         network (nx.Graph): The network graph.
@@ -62,7 +63,8 @@ def calculate_greedy_modularity_neighborhoods(
 def calculate_label_propagation_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
 ) -> csr_matrix:
-    """Apply Label Propagation to the network to detect communities.
+    """
+    Apply Label Propagation to the network to detect communities.
 
     Args:
         network (nx.Graph): The network graph.
@@ -112,7 +114,8 @@ def calculate_leiden_neighborhoods(
     fraction_shortest_edges: float = 1.0,
     random_seed: int = 888,
 ) -> csr_matrix:
-    """Calculate neighborhoods using the Leiden method with CSR matrix output.
+    """
+    Calculate neighborhoods using the Leiden method with CSR matrix output.
 
     Args:
         network (nx.Graph): The network graph.
@@ -168,7 +171,8 @@ def calculate_louvain_neighborhoods(
     fraction_shortest_edges: float = 1.0,
     random_seed: int = 888,
 ) -> csr_matrix:
-    """Calculate neighborhoods using the Louvain method.
+    """
+    Calculate neighborhoods using the Louvain method.
 
     Args:
         network (nx.Graph): The network graph.
@@ -221,7 +225,8 @@ def calculate_louvain_neighborhoods(
 def calculate_markov_clustering_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
 ) -> csr_matrix:
-    """Apply Markov Clustering (MCL) to the network and return a binary neighborhood matrix (CSR).
+    """
+    Apply Markov Clustering (MCL) to the network and return a binary neighborhood matrix (CSR).
 
     Args:
         network (nx.Graph): The network graph.
@@ -291,7 +296,8 @@ def calculate_markov_clustering_neighborhoods(
 def calculate_spinglass_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
 ) -> csr_matrix:
-    """Apply Spinglass Community Detection to the network, handling disconnected components.
+    """
+    Apply Spinglass Community Detection to the network, handling disconnected components.
 
     Args:
         network (nx.Graph): The network graph.
@@ -355,7 +361,8 @@ def calculate_spinglass_neighborhoods(
 def calculate_walktrap_neighborhoods(
     network: nx.Graph, fraction_shortest_edges: float = 1.0
 ) -> csr_matrix:
-    """Apply Walktrap Community Detection to the network with CSR matrix output.
+    """
+    Apply Walktrap Community Detection to the network with CSR matrix output.
 
     Args:
         network (nx.Graph): The network graph.
@@ -399,7 +406,8 @@ def calculate_walktrap_neighborhoods(
 
 
 def _create_percentile_limited_subgraph(G: nx.Graph, fraction_shortest_edges: float) -> nx.Graph:
-    """Create a subgraph containing the shortest edges based on the specified rank fraction
+    """
+    Create a subgraph containing the shortest edges based on the specified rank fraction
     of all edge lengths in the input graph.
 
     Args:

risk/{neighborhoods/domains.py → _neighborhoods/_domains.py}

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/domains
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_domains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from itertools import product
@@ -13,8 +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.log import logger
+from risk._annotation import get_weighted_description
+
+from .._log import logger
 
 # Define constants for clustering
 # fmt: off
@@ -35,7 +36,8 @@ def define_domains(
     linkage_metric: str,
     linkage_threshold: Union[float, str],
 ) -> pd.DataFrame:
-    """Define domains and assign nodes to these domains based on their significance scores and clustering,
+    """
+    Define domains and assign nodes to these domains based on their significance scores and clustering,
     handling errors by assigning unique domains when clustering fails.
 
     Args:
@@ -52,37 +54,48 @@ def define_domains(
     Raises:
         ValueError: If the clustering criterion is set to "off" or if an error occurs during clustering.
     """
-    try:
-        if linkage_criterion == "off":
-            raise ValueError("Clustering is turned off.")
+    # Validate args first; let user mistakes raise immediately
+    clustering_off = _validate_clustering_args(
+        linkage_criterion, linkage_method, linkage_metric, linkage_threshold
+    )
 
+    # If clustering is turned off, assign unique domains and skip
+    if clustering_off:
+        n_rows = len(top_annotation)
+        logger.warning("Clustering is turned off. Skipping clustering.")
+        top_annotation["domain"] = range(1, n_rows + 1)
+    else:
         # Transpose the matrix to cluster annotations
         m = significant_neighborhoods_significance[:, top_annotation["significant_annotation"]].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, linkage_threshold
-        )
-        # Perform hierarchical clustering
-        Z = linkage(m, method=best_linkage, metric=best_metric)
-        logger.warning(
-            f"Linkage criterion: '{linkage_criterion}'\nLinkage method: '{best_linkage}'\nLinkage metric: '{best_metric}'\nLinkage threshold: {round(best_threshold, 3)}"
-        )
-        # Calculate the optimal threshold for clustering
-        max_d_optimal = np.max(Z[:, 2]) * best_threshold
-        # Assign domains to the annotation matrix
-        domains = fcluster(Z, max_d_optimal, criterion=linkage_criterion)
-        top_annotation["domain"] = 0
-        top_annotation.loc[top_annotation["significant_annotation"], "domain"] = domains
-    except (ValueError, LinAlgError):
-        # If a ValueError is encountered, handle it by assigning unique domains
-        n_rows = len(top_annotation)
-        if linkage_criterion == "off":
-            logger.warning("Clustering is turned off. Skipping clustering.")
-        else:
-            logger.error("Error encountered. Skipping clustering.")
-        top_annotation["domain"] = range(1, n_rows + 1)  # Assign unique domains
+        try:
+            # 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, linkage_threshold
+            )
+            # Perform hierarchical clustering
+            Z = linkage(m, method=best_linkage, metric=best_metric)
+            logger.warning(
+                f"Linkage criterion: '{linkage_criterion}'\nLinkage method: '{best_linkage}'\nLinkage metric: '{best_metric}'\nLinkage threshold: {round(best_threshold, 3)}"
+            )
+            # Calculate the optimal threshold for clustering
+            max_d_optimal = np.max(Z[:, 2]) * best_threshold
+            # Assign domains to the annotation matrix
+            domains = fcluster(Z, max_d_optimal, criterion=linkage_criterion)
+            top_annotation["domain"] = 0
+            top_annotation.loc[top_annotation["significant_annotation"], "domain"] = domains
+        except (LinAlgError, ValueError):
+            # Numerical errors or degenerate input are handled gracefully (not user error)
+            n_rows = len(top_annotation)
+            logger.error(
+                "Clustering failed due to numerical or data degeneracy. Assigning unique domains."
+            )
+            top_annotation["domain"] = range(1, n_rows + 1)
 
     # Create DataFrames to store domain information
     node_to_significance = pd.DataFrame(
@@ -112,7 +125,8 @@ def trim_domains(
     min_cluster_size: int = 5,
     max_cluster_size: int = 1000,
 ) -> Tuple[pd.DataFrame, pd.DataFrame]:
-    """Trim domains that do not meet size criteria and find outliers.
+    """
+    Trim domains that do not meet size criteria and find outliers.
 
     Args:
         domains (pd.DataFrame): DataFrame of domain data for the network nodes.
@@ -181,8 +195,49 @@ def trim_domains(
     return valid_domains, valid_trimmed_domains_matrix
 
 
+def _validate_clustering_args(
+    linkage_criterion: str,
+    linkage_method: str,
+    linkage_metric: str,
+    linkage_threshold: Union[float, str],
+) -> bool:
+    """
+    Validate user-provided clustering arguments.
+
+    Returns:
+        bool: True if clustering is turned off (criterion == 'off'); False otherwise.
+
+    Raises:
+        ValueError: If any argument is invalid (user error).
+    """
+    # Allow opting out of clustering without raising
+    if linkage_criterion == "off":
+        return True
+    # Validate linkage method (allow "auto")
+    if linkage_method != "auto" and linkage_method not in LINKAGE_METHODS:
+        raise ValueError(
+            f"Invalid linkage_method '{linkage_method}'. Allowed values are 'auto' or one of: {sorted(LINKAGE_METHODS)}"
+        )
+    # Validate linkage metric (allow "auto")
+    if linkage_metric != "auto" and linkage_metric not in LINKAGE_METRICS:
+        raise ValueError(
+            f"Invalid linkage_metric '{linkage_metric}'. Allowed values are 'auto' or one of: {sorted(LINKAGE_METRICS)}"
+        )
+    # Validate linkage threshold (allow "auto"; otherwise must be float in (0, 1])
+    if linkage_threshold != "auto":
+        try:
+            lt = float(linkage_threshold)
+        except (TypeError, ValueError):
+            raise ValueError("linkage_threshold must be 'auto' or a float in the interval (0, 1].")
+        if not (0.0 < lt <= 1.0):
+            raise ValueError(f"linkage_threshold must be within (0, 1]. Received: {lt}")
+
+    return False
+
+
 def _safeguard_matrix(matrix: np.ndarray) -> np.ndarray:
-    """Safeguard the matrix by replacing NaN, Inf, and -Inf values.
+    """
+    Safeguard the matrix by replacing NaN, Inf, and -Inf values.
 
     Args:
         matrix (np.ndarray): Data matrix.
@@ -211,7 +266,8 @@ def _optimize_silhouette_across_linkage_and_metrics(
     linkage_metric: str,
     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 distance metrics.
 
     Args:
         m (np.ndarray): Data matrix.
@@ -287,7 +343,8 @@ def _find_best_silhouette_score(
     lower_bound: float = 0.001,
     upper_bound: float = 1.0,
 ) -> Tuple[float, float]:
-    """Find the best silhouette score using binary search.
+    """
+    Find the best silhouette score using binary search.
 
     Args:
         Z (np.ndarray): Linkage matrix.

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

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/neighborhoods
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_neighborhoods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import random
@@ -13,8 +13,8 @@ from scipy.sparse import csr_matrix
 from sklearn.exceptions import DataConversionWarning
 from sklearn.metrics.pairwise import cosine_similarity
 
-from risk.log import logger
-from risk.neighborhoods.community import (
+from .._log import logger
+from ._community import (
     calculate_greedy_modularity_neighborhoods,
     calculate_label_propagation_neighborhoods,
     calculate_leiden_neighborhoods,
@@ -36,7 +36,8 @@ def get_network_neighborhoods(
     leiden_resolution: float = 1.0,
     random_seed: int = 888,
 ) -> csr_matrix:
-    """Calculate the combined neighborhoods for each node using sparse matrices.
+    """
+    Calculate the combined neighborhoods for each node using sparse matrices.
 
     Args:
         network (nx.Graph): The network graph.
@@ -125,7 +126,8 @@ def get_network_neighborhoods(
 
 
 def _set_max_row_value_to_one_sparse(matrix: csr_matrix) -> csr_matrix:
-    """Set the maximum value in each row of a sparse matrix to 1.
+    """
+    Set the maximum value in each row of a sparse matrix to 1.
 
     Args:
         matrix (csr_matrix): The input sparse matrix.
@@ -142,34 +144,14 @@ def _set_max_row_value_to_one_sparse(matrix: csr_matrix) -> csr_matrix:
     return matrix
 
 
-def _set_max_row_value_to_one(matrix: np.ndarray) -> np.ndarray:
-    """For each row in the input matrix, set the maximum value(s) to 1 and all other values to 0. This is particularly
-    useful for neighborhood matrices that have undergone multiple neighborhood detection algorithms, where the
-    maximum value in each row represents the most significant relationship per node in the combined neighborhoods.
-
-    Args:
-        matrix (np.ndarray): A 2D numpy array representing the neighborhood matrix.
-
-    Returns:
-        np.ndarray: The modified matrix where only the maximum value(s) in each row is set to 1, and others are set to 0.
-    """
-    # Find the maximum value in each row (column-wise max operation)
-    max_values = np.max(matrix, axis=1, keepdims=True)
-    # Create a boolean mask where elements are True if they are the max value in their row
-    max_mask = matrix == max_values
-    # Set all elements to 0, and then set the maximum value positions to 1
-    matrix[:] = 0  # Set everything to 0
-    matrix[max_mask] = 1  # Set only the max values to 1
-    return matrix
-
-
 def process_neighborhoods(
     network: nx.Graph,
     neighborhoods: 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 neighborhoods based on the imputation and pruning settings.
 
     Args:
         network (nx.Graph): The network data structure used for imputing and pruning neighbors.
@@ -226,7 +208,8 @@ def _impute_neighbors(
     significant_binary_significance_matrix: np.ndarray,
     max_depth: int = 3,
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
-    """Impute rows with sums of zero in the significance matrix based on the closest non-zero neighbors in the network graph.
+    """
+    Impute rows with sums of zero in the significance matrix based on the closest non-zero neighbors in the network graph.
 
     Args:
         network (nx.Graph): The network graph with nodes having IDs matching the matrix indices.
@@ -262,7 +245,8 @@ def _impute_neighbors_with_similarity(
     significant_binary_significance_matrix: np.ndarray,
     max_depth: int = 3,
 ) -> Tuple[np.ndarray, np.ndarray]:
-    """Impute non-significant nodes based on the closest significant neighbors' profiles and their similarity.
+    """
+    Impute non-significant nodes based on the closest significant neighbors' profiles and their similarity.
 
     Args:
         network (nx.Graph): The network graph with nodes having IDs matching the matrix indices.
@@ -306,7 +290,8 @@ def _process_node_imputation(
     significant_binary_significance_matrix: np.ndarray,
     depth: int,
 ) -> Tuple[np.ndarray, np.ndarray]:
-    """Process the imputation for a single node based on its significant neighbors.
+    """
+    Process the imputation for a single node based on its significant neighbors.
 
     Args:
         row_index (int): The index of the significant node being processed.
@@ -391,7 +376,8 @@ def _prune_neighbors(
     significant_binary_significance_matrix: np.ndarray,
     distance_threshold: float = 0.9,
 ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
-    """Remove outliers based on their rank for edge lengths.
+    """
+    Remove outliers based on their rank for edge lengths.
 
     Args:
         network (nx.Graph): The network graph with nodes having IDs matching the matrix indices.
@@ -408,34 +394,33 @@ def _prune_neighbors(
     # Identify indices with non-zero rows in the binary significance matrix
     non_zero_indices = np.where(significant_binary_significance_matrix.sum(axis=1) != 0)[0]
     median_distances = []
+    distance_lookup = {}
     for node in non_zero_indices:
-        neighbors = [
-            n
-            for n in network.neighbors(node)
-            if significant_binary_significance_matrix[n].sum() != 0
-        ]
-        if neighbors:
-            median_distance = np.median(
-                [_get_euclidean_distance(node, n, network) for n in neighbors]
-            )
-            median_distances.append(median_distance)
+        dist = _median_distance_to_significant_neighbors(
+            node, network, significant_binary_significance_matrix
+        )
+        if dist is not None:
+            median_distances.append(dist)
+            distance_lookup[node] = dist
+
+    if not median_distances:
+        logger.warning("No significant neighbors found for pruning.")
+        significant_significance_matrix = np.where(
+            significant_binary_significance_matrix == 1, significance_matrix, 0
+        )
+        return (
+            significance_matrix,
+            significant_binary_significance_matrix,
+            significant_significance_matrix,
+        )
 
     # Calculate the distance threshold value based on rank
     distance_threshold_value = _calculate_threshold(median_distances, 1 - distance_threshold)
     # Prune nodes that are outliers based on the distance threshold
-    for row_index in non_zero_indices:
-        neighbors = [
-            n
-            for n in network.neighbors(row_index)
-            if significant_binary_significance_matrix[n].sum() != 0
-        ]
-        if neighbors:
-            median_distance = np.median(
-                [_get_euclidean_distance(row_index, n, network) for n in neighbors]
-            )
-            if median_distance >= distance_threshold_value:
-                significance_matrix[row_index] = 0
-                significant_binary_significance_matrix[row_index] = 0
+    for node, dist in distance_lookup.items():
+        if dist >= distance_threshold_value:
+            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(
@@ -449,8 +434,32 @@ def _prune_neighbors(
     )
 
 
+def _median_distance_to_significant_neighbors(
+    node, network, significance_mask
+) -> Union[float, None]:
+    """
+    Calculate the median distance from a node to its significant neighbors.
+
+    Args:
+        node (Any): The node for which the median distance is being calculated.
+        network (nx.Graph): The network graph containing the nodes.
+        significance_mask (np.ndarray): Binary matrix indicating significant nodes.
+
+    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]
+    if not neighbors:
+        return None
+    # Calculate distances to significant neighbors
+    distances = [_get_euclidean_distance(node, n, network) for n in neighbors]
+
+    return np.median(distances)
+
+
 def _get_euclidean_distance(node1: Any, node2: Any, network: nx.Graph) -> float:
-    """Calculate the Euclidean distance between two nodes in the network.
+    """
+    Calculate the Euclidean distance between two nodes in the network.
 
     Args:
         node1 (Any): The first node.
@@ -466,7 +475,8 @@ def _get_euclidean_distance(node1: Any, node2: Any, network: nx.Graph) -> float:
 
 
 def _get_node_position(network: nx.Graph, node: Any) -> np.ndarray:
-    """Retrieve the position of a node in the network as a numpy array.
+    """
+    Retrieve the position of a node in the network as a numpy array.
 
     Args:
         network (nx.Graph): The network graph containing node positions.
@@ -485,7 +495,8 @@ def _get_node_position(network: nx.Graph, node: Any) -> np.ndarray:
 
 
 def _calculate_threshold(median_distances: List, distance_threshold: float) -> float:
-    """Calculate the distance threshold based on the given median distances and a percentile threshold.
+    """
+    Calculate the distance threshold based on the given median distances and a percentile threshold.
 
     Args:
         median_distances (List): An array of median distances.

risk/_neighborhoods/_stats/__init__.py

@@ -0,0 +1,13 @@
+"""
+risk/_neighborhoods/_stats
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from ._permutation import compute_permutation_test
+from ._tests import (
+    compute_binom_test,
+    compute_chi2_test,
+    compute_hypergeom_test,
+    compute_poisson_test,
+    compute_zscore_test,
+)

risk/_neighborhoods/_stats/_permutation/__init__.py

@@ -0,0 +1,6 @@
+"""
+risk/_neighborhoods/_stats/_permutation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from ._permutation import compute_permutation_test

risk/{neighborhoods/stats/permutation/permutation.py → _neighborhoods/_stats/_permutation/_permutation.py}

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/stats/permutation/permutation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_stats/_permutation/_permutation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from multiprocessing import Manager, get_context
@@ -12,7 +12,7 @@ from scipy.sparse import csr_matrix
 from threadpoolctl import threadpool_limits
 from tqdm import tqdm
 
-from risk.neighborhoods.stats.permutation.test_functions import DISPATCH_TEST_FUNCTIONS
+from ._test_functions import DISPATCH_TEST_FUNCTIONS
 
 
 def compute_permutation_test(
@@ -24,7 +24,8 @@ def compute_permutation_test(
     random_seed: int = 888,
     max_workers: int = 1,
 ) -> Dict[str, Any]:
-    """Compute permutation test for enrichment and depletion in neighborhoods.
+    """
+    Compute permutation test for enrichment and depletion in neighborhoods.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -75,7 +76,8 @@ def _run_permutation_test(
     random_seed: int = 888,
     max_workers: int = 4,
 ) -> tuple:
-    """Run the permutation test to calculate depletion and enrichment counts.
+    """
+    Run the permutation test to calculate depletion and enrichment counts.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -181,7 +183,8 @@ def _permutation_process_batch(
     progress_counter: ValueProxy,
     max_workers: int,
 ) -> tuple:
-    """Process a batch of permutations in a worker process.
+    """
+    Process a batch of permutations in a worker process.
 
     Args:
         permutations (Union[List, Tuple, np.ndarray]): Permutation batch to process.

risk/{neighborhoods/stats/permutation/test_functions.py → _neighborhoods/_stats/_permutation/_test_functions.py}

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/stats/permutation/test_functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_stats/_permutation/_test_functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import numpy as np
@@ -15,7 +15,8 @@ from scipy.sparse import csr_matrix
 def compute_neighborhood_score_by_sum(
     neighborhoods_matrix: csr_matrix, annotation_matrix: csr_matrix
 ) -> np.ndarray:
-    """Compute the sum of attribute values for each neighborhood using sparse matrices.
+    """
+    Compute the sum of attribute values for each neighborhood using sparse matrices.
 
     Args:
         neighborhoods_matrix (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -34,7 +35,8 @@ def compute_neighborhood_score_by_sum(
 def compute_neighborhood_score_by_stdev(
     neighborhoods_matrix: csr_matrix, annotation_matrix: csr_matrix
 ) -> np.ndarray:
-    """Compute the standard deviation of neighborhood scores for sparse matrices.
+    """
+    Compute the standard deviation of neighborhood scores for sparse matrices.
 
     Args:
         neighborhoods_matrix (csr_matrix): Sparse binary matrix representing neighborhoods.

risk/{neighborhoods/stats/tests.py → _neighborhoods/_stats/_tests.py}

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/stats/tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_neighborhoods/_stats/_tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict
@@ -15,7 +15,8 @@ def compute_binom_test(
     annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """Compute Binomial test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """
+    Compute Binomial test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -60,7 +61,8 @@ def compute_chi2_test(
     annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """Compute chi-squared test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """
+    Compute chi-squared test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -122,7 +124,8 @@ def compute_hypergeom_test(
     annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """Compute hypergeometric test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """
+    Compute hypergeometric test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -178,7 +181,8 @@ def compute_poisson_test(
     annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """Compute Poisson test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """
+    Compute Poisson test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
@@ -220,7 +224,8 @@ def compute_zscore_test(
     annotation: csr_matrix,
     null_distribution: str = "network",
 ) -> Dict[str, Any]:
-    """Compute z-score test for enrichment and depletion in neighborhoods with selectable null distribution.
+    """
+    Compute z-score test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
         neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.

risk/_network/__init__.py

@@ -0,0 +1,8 @@
+"""
+risk/_network
+~~~~~~~~~~~~~
+"""
+
+from ._graph import GraphAPI
+from ._io import NetworkAPI
+from ._plotter import PlotterAPI