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

risk/{_network/_graph/_api.py → network/graph/api.py}

@@ -1,6 +1,6 @@
 """
-risk/_network/_graph/_api
-~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -9,14 +9,14 @@ from typing import Any, Dict, Union
 import networkx as nx
 import pandas as pd
 
-from ..._annotation import define_top_annotation
-from ..._log import log_header, logger, params
-from ..._neighborhoods import (
+from ...annotation import define_top_annotation
+from ...log import log_header, logger, params
+from ...cluster import (
     define_domains,
-    process_neighborhoods,
+    process_significant_clusters,
     trim_domains,
 )
-from ._graph import Graph
+from .graph import Graph
 from ._stats import calculate_significance_matrices
 
 
@@ -24,14 +24,14 @@ class GraphAPI:
     """
     Handles the loading of network graphs and associated data.
 
-    The GraphAPI class provides methods to load and process network graphs, annotations, and neighborhoods.
+    The GraphAPI class provides methods to load and process network graphs, annotations, and cluster results.
     """
 
     def load_graph(
         self,
         network: nx.Graph,
         annotation: Dict[str, Any],
-        neighborhoods: Dict[str, Any],
+        stats_results: Dict[str, Any],
         tail: str = "right",
         pval_cutoff: float = 0.01,
         fdr_cutoff: float = 0.9999,
@@ -50,7 +50,7 @@ class GraphAPI:
         Args:
             network (nx.Graph): The network graph.
             annotation (Dict[str, Any]): The annotation associated with the network.
-            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            stats_results (Dict[str, Any]): Cluster significance data.
             tail (str, optional): Type of significance tail ("right", "left", "both"). Defaults to "right".
             pval_cutoff (float, optional): p-value cutoff for significance. Defaults to 0.01.
             fdr_cutoff (float, optional): FDR cutoff for significance. Defaults to 0.9999.
@@ -62,14 +62,14 @@ class GraphAPI:
                 Defaults to "yule".
             linkage_threshold (float, str, optional): Threshold for clustering. Choose "auto" to optimize.
                 Defaults to 0.2.
-            min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
-            max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
+            min_cluster_size (int, optional): Minimum size for significant clusters. Defaults to 5.
+            max_cluster_size (int, optional): Maximum size for significant clusters. Defaults to 1000.
 
         Returns:
             Graph: A fully initialized and processed Graph object.
         """
         # Log the parameters and display headers
-        log_header("Finding significant neighborhoods")
+        log_header("Finding significant clusters")
         params.log_graph(
             tail=tail,
             pval_cutoff=pval_cutoff,
@@ -92,20 +92,20 @@ class GraphAPI:
         logger.debug(
             f"Significance tail: '{tail}' ({'enrichment' if tail == 'right' else 'depletion' if tail == 'left' else 'both'})"
         )
-        # Calculate significant neighborhoods based on the provided parameters
-        significant_neighborhoods = calculate_significance_matrices(
-            neighborhoods["depletion_pvals"],
-            neighborhoods["enrichment_pvals"],
+        # Calculate significant clusters based on the provided parameters
+        significant_clusters = calculate_significance_matrices(
+            stats_results["depletion_pvals"],
+            stats_results["enrichment_pvals"],
             tail=tail,
             pval_cutoff=pval_cutoff,
             fdr_cutoff=fdr_cutoff,
         )
 
-        log_header("Processing neighborhoods")
-        # Process neighborhoods by imputing and pruning based on the given settings
-        processed_neighborhoods = process_neighborhoods(
+        log_header("Processing significant clusters")
+        # Process significant clusters by imputing and pruning based on the given settings
+        processed_clusters = process_significant_clusters(
             network=network,
-            neighborhoods=significant_neighborhoods,
+            significant_clusters=significant_clusters,
             impute_depth=impute_depth,
             prune_threshold=prune_threshold,
         )
@@ -113,24 +113,22 @@ class GraphAPI:
         log_header("Finding top annotations")
         logger.debug(f"Min cluster size: {min_cluster_size}")
         logger.debug(f"Max cluster size: {max_cluster_size}")
-        # Define top annotations based on processed neighborhoods
+        # Define top annotations based on processed significant clusters
         top_annotation = self._define_top_annotation(
             network=network,
             annotation=annotation,
-            neighborhoods=processed_neighborhoods,
+            processed_clusters=processed_clusters,
             min_cluster_size=min_cluster_size,
             max_cluster_size=max_cluster_size,
         )
 
-        log_header("Optimizing distance threshold for domains")
-        # Extract the significant significance matrix from the neighborhoods data
-        significant_neighborhoods_significance = processed_neighborhoods[
-            "significant_significance_matrix"
-        ]
+        log_header("Grouping clusters into domains")
+        # Extract the significant significance matrix from the processed_clusters data
+        significant_clusters_significance = processed_clusters["significant_significance_matrix"]
         # Define domains in the network using the specified clustering settings
         domains = define_domains(
             top_annotation=top_annotation,
-            significant_neighborhoods_significance=significant_neighborhoods_significance,
+            significant_clusters_significance=significant_clusters_significance,
             linkage_criterion=linkage_criterion,
             linkage_method=linkage_method,
             linkage_metric=linkage_metric,
@@ -147,13 +145,13 @@ class GraphAPI:
         # Prepare node mapping and significance sums for the final Graph object
         ordered_nodes = annotation["ordered_nodes"]
         node_label_to_id = dict(zip(ordered_nodes, range(len(ordered_nodes))))
-        node_significance_sums = processed_neighborhoods["node_significance_sums"]
+        node_significance_sums = processed_clusters["node_significance_sums"]
 
         # Return the fully initialized Graph object
         return Graph(
             network=network,
             annotation=annotation,
-            neighborhoods=neighborhoods,
+            stats_results=stats_results,
             domains=domains,
             trimmed_domains=trimmed_domains,
             node_label_to_node_id_map=node_label_to_id,
@@ -164,7 +162,7 @@ class GraphAPI:
         self,
         network: nx.Graph,
         annotation: Dict[str, Any],
-        neighborhoods: Dict[str, Any],
+        processed_clusters: Dict[str, Any],
         min_cluster_size: int = 5,
         max_cluster_size: int = 1000,
     ) -> pd.DataFrame:
@@ -174,25 +172,25 @@ class GraphAPI:
         Args:
             network (nx.Graph): The network graph.
             annotation (Dict[str, Any]): Annotation data for the network.
-            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            processed_clusters (Dict[str, Any]): Processed cluster significance data.
             min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
             max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
 
         Returns:
-            Dict[str, Any]: Top annotations identified within the network.
+            pd.DataFrame: Top annotations identified within the network.
         """
-        # Extract necessary data from annotation and neighborhoods
+        # Extract necessary data from annotation and processed_clusters
         ordered_annotation = annotation["ordered_annotation"]
-        neighborhood_significance_sums = neighborhoods["neighborhood_significance_counts"]
-        significant_significance_matrix = neighborhoods["significant_significance_matrix"]
-        significant_binary_significance_matrix = neighborhoods[
+        cluster_significance_sums = processed_clusters["cluster_significance_counts"]
+        significant_significance_matrix = processed_clusters["significant_significance_matrix"]
+        significant_binary_significance_matrix = processed_clusters[
             "significant_binary_significance_matrix"
         ]
         # Call external function to define top annotations
         return define_top_annotation(
             network=network,
             ordered_annotation_labels=ordered_annotation,
-            neighborhood_significance_sums=neighborhood_significance_sums,
+            cluster_significance_sums=cluster_significance_sums,
             significant_significance_matrix=significant_significance_matrix,
             significant_binary_significance_matrix=significant_binary_significance_matrix,
             min_cluster_size=min_cluster_size,

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

@@ -1,6 +1,6 @@
 """
-risk/_network/_graph/_graph
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/graph
+~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from collections import defaultdict
@@ -27,7 +27,7 @@ class Graph:
         self,
         network: nx.Graph,
         annotation: Dict[str, Any],
-        neighborhoods: Dict[str, Any],
+        stats_results: Dict[str, Any],
         domains: pd.DataFrame,
         trimmed_domains: pd.DataFrame,
         node_label_to_node_id_map: Dict[str, Any],
@@ -40,7 +40,7 @@ class Graph:
         Args:
             network (nx.Graph): The network graph.
             annotation (Dict[str, Any]): The annotation associated with the network.
-            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            stats_results (Dict[str, Any]): Cluster significance data.
             domains (pd.DataFrame): DataFrame containing domain data for the network nodes.
             trimmed_domains (pd.DataFrame): DataFrame containing trimmed domain data for the network nodes.
             node_label_to_node_id_map (Dict[str, Any]): A dictionary mapping node labels to their corresponding IDs.
@@ -72,7 +72,7 @@ class Graph:
         self.node_coordinates = self._extract_node_coordinates(self.network)
 
         # NOTE: Only after the above attributes are initialized, we can create the summary
-        self.summary = Summary(annotation, neighborhoods, self)
+        self.summary = Summary(annotation, stats_results, self)
 
     def pop(self, domain_id: int) -> List[str]:
         """

risk/{_network/_io.py → network/io.py}

@@ -1,6 +1,6 @@
 """
-risk/_network/_io
-~~~~~~~~~~~~~~~~~
+risk/network/io
+~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -15,7 +15,7 @@ import networkx as nx
 import numpy as np
 import pandas as pd
 
-from .._log import log_header, logger, params
+from ..log import log_header, logger, params
 
 
 class NetworkAPI:
@@ -370,7 +370,7 @@ class NetworkIO:
         self._log_loading_network(filetype, filepath=filepath)
 
         # Load the Cytoscape JSON file
-        with open(filepath, "r") as f:
+        with open(filepath, "r", encoding="utf-8") as f:
             cyjs_data = json.load(f)
 
         # Create a graph
@@ -603,6 +603,11 @@ class NetworkIO:
         distances = compute_distance_vectorized(edge_data, compute_sphere)
         # Assign Euclidean or spherical distances to edges
         for (u, v), distance in zip(G.edges, distances):
+            if not np.isfinite(distance) or distance <= 0:
+                logger.warning(
+                    f"Edge ({u},{v}) has invalid or non-positive length ({distance}); replaced with minimal fallback 1e-12."
+                )
+                distance = 1e-12
             G.edges[u, v]["length"] = distance
 
     def _map_to_sphere(self, G: nx.Graph) -> None:

risk/network/plotter/__init__.py

@@ -0,0 +1,6 @@
+"""
+risk/network/plotter
+~~~~~~~~~~~~~~~~~~~~
+"""
+
+from .api import PlotterAPI

risk/{_network/_plotter → network/plotter}/_canvas.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_canvas
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_canvas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import List, Tuple, Union
@@ -8,10 +8,10 @@ from typing import List, Tuple, Union
 import matplotlib.pyplot as plt
 import numpy as np
 
-from ..._log import params
-from .._graph import Graph
-from ._utils._colors import to_rgba
-from ._utils._layout import calculate_bounding_box
+from ...log import params
+from ..graph import Graph
+from ._utils.colors import to_rgba
+from ._utils.layout import calculate_bounding_box
 
 
 class Canvas:

risk/{_network/_plotter → network/plotter}/_contour.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_contour
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_contour
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, List, Tuple, Union
@@ -11,8 +11,8 @@ from scipy import linalg
 from scipy.ndimage import label
 from scipy.stats import gaussian_kde
 
-from ..._log import logger, params
-from .._graph import Graph
+from ...log import logger, params
+from ..graph import Graph
 from ._utils import get_annotated_domain_colors, to_rgba
 
 

risk/{_network/_plotter → network/plotter}/_labels.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_labels
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_labels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -10,8 +10,8 @@ import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 
-from ..._log import params
-from .._graph import Graph
+from ...log import params
+from ..graph import Graph
 from ._utils import calculate_bounding_box, get_annotated_domain_colors, to_rgba
 
 TERM_DELIMITER = "::::"  # String used to separate multiple domain terms when constructing composite domain labels
@@ -275,12 +275,12 @@ class Labels:
             fontsize (int, optional): Font size for the label. Defaults to 10.
             fontcolor (str, List, Tuple, or np.ndarray, optional): Color of the label text. Defaults to "black".
             fontalpha (float, None, optional): Transparency level for the font color. If provided, it overrides any existing alpha values found
-                in fontalpha. Defaults to 1.0.
+                in fontcolor. Defaults to 1.0.
             arrow_linewidth (float, optional): Line width of the arrow pointing to the centroid. Defaults to 1.
             arrow_style (str, optional): Style of the arrows pointing to the centroid. Defaults to "->".
             arrow_color (str, List, Tuple, or np.ndarray, optional): Color of the arrow. Defaults to "black".
             arrow_alpha (float, None, optional): Transparency level for the arrow color. If provided, it overrides any existing alpha values
-                found in arrow_alpha. Defaults to 1.0.
+                found in arrow_color. Defaults to 1.0.
             arrow_base_shrink (float, optional): Distance between the text and the base of the arrow. Defaults to 0.0.
             arrow_tip_shrink (float, optional): Distance between the arrow tip and the centroid. Defaults to 0.0.
 

risk/{_network/_plotter → network/plotter}/_network.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_network
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_network
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, List, Tuple, Union
@@ -8,8 +8,8 @@ from typing import Any, Dict, List, Tuple, Union
 import networkx as nx
 import numpy as np
 
-from ..._log import params
-from .._graph import Graph
+from ...log import params
+from ..graph import Graph
 from ._utils import get_domain_colors, to_rgba
 
 
@@ -273,14 +273,14 @@ class Network:
         return adjusted_network_colors
 
     def get_annotated_node_sizes(
-        self, significant_size: int = 50, nonsignificant_size: int = 25
+        self, significant_size: Union[int, float] = 50, nonsignificant_size: Union[int, float] = 25
     ) -> np.ndarray:
         """
         Adjust the sizes of nodes in the network graph based on whether they are significant or not.
 
         Args:
-            significant_size (int): Size for significant nodes. Defaults to 50.
-            nonsignificant_size (int): Size for non-significant nodes. Defaults to 25.
+            significant_size (int or float): Size for significant nodes. Can be an integer or float value. Defaults to 50.
+            nonsignificant_size (int or float): Size for non-significant nodes. Can be an integer or float value. Defaults to 25.
 
         Returns:
             np.ndarray: Array of node sizes, with significant nodes larger than non-significant ones.

risk/{_network/_plotter → network/plotter}/_plotter.py

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_plotter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_plotter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import List, Tuple, Union
@@ -8,8 +8,8 @@ from typing import List, Tuple, Union
 import matplotlib.pyplot as plt
 import numpy as np
 
-from ..._log import params
-from .._graph._graph import Graph
+from ...log import params
+from ..graph.graph import Graph
 from ._canvas import Canvas
 from ._contour import Contour
 from ._labels import Labels
@@ -123,7 +123,7 @@ class Plotter(Canvas, Network, Contour, Labels):
         Args:
             *args: Positional arguments passed to `plt.savefig`.
             pad_inches (float, optional): Padding around the figure when saving. Defaults to 0.5.
-            dpi (int, optional): Dots per inch (DPI) for the exported image. Defaults to 300.
+            dpi (int, optional): Dots per inch (DPI) for the exported image. Defaults to 100.
             **kwargs: Keyword arguments passed to `plt.savefig`, such as filename and format.
         """
         # Ensure user-provided kwargs take precedence

risk/network/plotter/_utils/__init__.py

@@ -0,0 +1,7 @@
+"""
+risk/network/plotter/_utils
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from .colors import get_annotated_domain_colors, get_domain_colors, to_rgba
+from .layout import calculate_bounding_box, calculate_centroids

risk/{_network/_plotter/_utils/_colors.py → network/plotter/_utils/colors.py}

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_utils/_colors
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_utils/colors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, List, Tuple, Union
@@ -9,7 +9,7 @@ import matplotlib
 import matplotlib.colors as mcolors
 import numpy as np
 
-from ..._graph import Graph
+from ...graph import Graph
 
 
 def get_annotated_domain_colors(

risk/{_network/_plotter/_utils/_layout.py → network/plotter/_utils/layout.py}

@@ -1,6 +1,6 @@
 """
-risk/_network/_plotter/_utils/_layout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/_utils/layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, List, Tuple

risk/{_network/_plotter/_api.py → network/plotter/api.py}

@@ -1,14 +1,14 @@
 """
-risk/_network/_plotter/_api
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/network/plotter/api
+~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import List, Tuple, Union
 
 import numpy as np
 
-from ..._log import log_header
-from .._graph import Graph
+from ...log import log_header
+from ..graph import Graph
 from ._plotter import Plotter
 
 
@@ -32,7 +32,7 @@ class PlotterAPI:
 
         Args:
             graph (Graph): The graph to plot.
-            figsize (List, Tuple, or np.ndarray, optional): Size of the plot. Defaults to (10, 10)., optional): Size of the figure. Defaults to (10, 10).
+            figsize (List, Tuple, or np.ndarray, optional): Figure size in inches (width, height). Defaults to (10, 10).
             background_color (str, optional): Background color of the plot. Defaults to "white".
             background_alpha (float, None, optional): Transparency level of the background color. If provided, it overrides
                 any existing alpha values found in background_color. Defaults to 1.0.

risk/{_risk.py → risk.py}

@@ -1,20 +1,21 @@
 """
-risk/_risk
-~~~~~~~~~~
+risk/risk
+~~~~~~~~~
 """
 
-from ._annotation import AnnotationHandler
-from ._log import params, set_global_verbosity
-from ._neighborhoods import NeighborhoodsAPI
-from ._network import GraphAPI, NetworkAPI, PlotterAPI
+from .annotation import AnnotationHandler
+from .cluster import ClusterAPI
+from .log import params, set_global_verbosity
+from .network import GraphAPI, NetworkAPI, PlotterAPI
+from .stats import StatsAPI
 
 
-class RISK(NetworkAPI, AnnotationHandler, NeighborhoodsAPI, GraphAPI, PlotterAPI):
+class RISK(NetworkAPI, AnnotationHandler, ClusterAPI, StatsAPI, GraphAPI, PlotterAPI):
     """
     RISK: A class for network analysis and visualization.
 
     The RISK class integrates functionalities for loading networks, processing annotations,
-    performing network-based statistical analysis to quantify neighborhood relationships,
+    performing network-based statistical analysis to quantify cluster relationships,
     and visualizing networks and their properties.
     """
 

risk/stats/__init__.py

@@ -0,0 +1,6 @@
+"""
+risk/stats
+~~~~~~~~~~
+"""
+
+from .api import StatsAPI

risk/stats/_stats/__init__.py

@@ -0,0 +1,11 @@
+"""
+risk/cluster/_stats
+~~~~~~~~~~~~~~~~~~~
+"""
+
+from .permutation import compute_permutation_test
+from .tests import (
+    compute_binom_test,
+    compute_chi2_test,
+    compute_hypergeom_test,
+)

risk/stats/_stats/permutation/__init__.py

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

risk/stats/_stats/permutation/_test_functions.py

@@ -0,0 +1,72 @@
+"""
+risk/stats/_stats/permutation/_test_functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+import numpy as np
+from scipy.sparse import csr_matrix
+
+# NOTE: Cython optimizations provided minimal performance benefits.
+# The final version with Cython is archived in the `cython_permutation` branch.
+
+# DISPATCH_TEST_FUNCTIONS can be found at the end of the file.
+
+
+def compute_cluster_score_by_sum(
+    clusters_matrix: csr_matrix, annotation_matrix: csr_matrix
+) -> np.ndarray:
+    """
+    Compute the sum of attribute values for each cluster using sparse matrices.
+
+    Args:
+        clusters_matrix (csr_matrix): Sparse binary matrix representing clusters.
+        annotation_matrix (csr_matrix): Sparse matrix representing annotation values.
+
+    Returns:
+        np.ndarray: Dense array of summed attribute values for each cluster.
+    """
+    # Calculate the cluster score as the dot product of clusters and annotation
+    cluster_score = clusters_matrix @ annotation_matrix  # Sparse matrix multiplication
+    # Convert the result to a dense array for downstream calculations
+    cluster_score_dense = cluster_score.toarray()
+    return cluster_score_dense
+
+
+def compute_cluster_score_by_stdev(
+    clusters_matrix: csr_matrix, annotation_matrix: csr_matrix
+) -> np.ndarray:
+    """
+    Compute the standard deviation of cluster scores for sparse matrices.
+
+    Args:
+        clusters_matrix (csr_matrix): Sparse binary matrix representing clusters.
+        annotation_matrix (csr_matrix): Sparse matrix representing annotation values.
+
+    Returns:
+        np.ndarray: Standard deviation of the cluster scores.
+    """
+    # Calculate the cluster score as the dot product of clusters and annotation
+    cluster_score = clusters_matrix @ annotation_matrix  # Sparse matrix multiplication
+    # Calculate the number of elements in each cluster (sum of rows)
+    N = clusters_matrix.sum(axis=1).A.flatten()  # Convert to 1D array
+    # Avoid division by zero by replacing zeros in N with np.nan temporarily
+    N[N == 0] = np.nan
+    # Compute the mean of the cluster scores
+    M = cluster_score.multiply(1 / N[:, None]).toarray()  # Sparse element-wise division
+    # Compute the mean of squares (EXX) directly using squared annotation matrix
+    annotation_squared = annotation_matrix.multiply(annotation_matrix)  # Element-wise squaring
+    EXX = (clusters_matrix @ annotation_squared).multiply(1 / N[:, None]).toarray()
+    # Calculate variance as EXX - M^2
+    variance = EXX - np.power(M, 2)
+    # Compute the standard deviation as the square root of the variance
+    cluster_stdev = np.sqrt(variance)
+    # Replace np.nan back with zeros in case N was 0 (no elements in the cluster)
+    cluster_stdev[np.isnan(cluster_stdev)] = 0
+    return cluster_stdev
+
+
+# Dictionary to dispatch statistical test functions based on the score metric
+DISPATCH_TEST_FUNCTIONS = {
+    "sum": compute_cluster_score_by_sum,
+    "stdev": compute_cluster_score_by_stdev,
+}