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

risk/network/geometry.py

@@ -3,6 +3,8 @@ risk/network/geometry
 ~~~~~~~~~~~~~~~~~~~~~
 """
 
+import copy
+
 import networkx as nx
 import numpy as np
 
@@ -25,54 +27,50 @@ def assign_edge_lengths(
         nx.Graph: The graph with applied edge lengths.
     """
 
-    def compute_distance(
-        u_coords: np.ndarray, v_coords: np.ndarray, is_sphere: bool = False
-    ) -> float:
-        """Compute the distance between two coordinate vectors.
-
-        Args:
-            u_coords (np.ndarray): Coordinates of the first point.
-            v_coords (np.ndarray): Coordinates of the second point.
-            is_sphere (bool, optional): If True, compute spherical distance. Defaults to False.
-
-        Returns:
-            float: The computed distance between the two points.
-        """
+    def compute_distance_vectorized(coords, is_sphere):
+        """Compute distances between pairs of coordinates."""
+        u_coords, v_coords = coords[:, 0, :], coords[:, 1, :]
         if is_sphere:
-            # Normalize vectors and compute spherical distance using the dot product
-            u_coords /= np.linalg.norm(u_coords)
-            v_coords /= np.linalg.norm(v_coords)
-            return np.arccos(np.clip(np.dot(u_coords, v_coords), -1.0, 1.0))
-        else:
-            # Compute Euclidean distance
-            return np.linalg.norm(u_coords - v_coords)
+            u_norm = np.linalg.norm(u_coords, axis=1, keepdims=True)
+            v_norm = np.linalg.norm(v_coords, axis=1, keepdims=True)
+            u_coords /= u_norm
+            v_coords /= v_norm
+            dot_products = np.einsum("ij,ij->i", u_coords, v_coords)
+            return np.arccos(np.clip(dot_products, -1.0, 1.0))
+
+        return np.linalg.norm(u_coords - v_coords, axis=1)
 
-    # Normalize graph coordinates
+    # Normalize graph coordinates and weights
     _normalize_graph_coordinates(G)
-    # Normalize weights
     _normalize_weights(G)
-    # Use G_depth for edge length calculation
+    # Map nodes to sphere and adjust depth if required
     if compute_sphere:
-        # Map to sphere and adjust depth
         _map_to_sphere(G)
-        G_depth = _create_depth(G.copy(), surface_depth=surface_depth)
+        G_depth = _create_depth(copy.deepcopy(G), surface_depth=surface_depth)
     else:
-        # Calculate edge lengths directly on the plane
-        G_depth = G.copy()
+        G_depth = copy.deepcopy(G)
 
-    for u, v, _ in G_depth.edges(data=True):
+    # Precompute edge coordinate arrays for vectorized computation
+    edge_data = []
+    for u, v in G_depth.edges:
         u_coords = np.array([G_depth.nodes[u]["x"], G_depth.nodes[u]["y"]])
         v_coords = np.array([G_depth.nodes[v]["x"], G_depth.nodes[v]["y"]])
         if compute_sphere:
             u_coords = np.append(u_coords, G_depth.nodes[u].get("z", 0))
             v_coords = np.append(v_coords, G_depth.nodes[v].get("z", 0))
-
-        distance = compute_distance(u_coords, v_coords, is_sphere=compute_sphere)
+        edge_data.append([u_coords, v_coords, (u, v)])
+
+    # Convert to numpy for faster processing
+    edge_coords = np.array([(e[0], e[1]) for e in edge_data])
+    edge_indices = [e[2] for e in edge_data]
+    # Compute distances in bulk
+    distances = compute_distance_vectorized(edge_coords, compute_sphere)
+    # Assign distances back to the graph
+    for (u, v), distance in zip(edge_indices, distances):
         if include_edge_weight:
-            # Square root of the normalized weight is used to minimize the effect of large weights
-            G.edges[u, v]["length"] = distance / np.sqrt(G.edges[u, v]["normalized_weight"] + 1e-6)
+            weight = G.edges[u, v].get("normalized_weight", 0) + 1e-6
+            G.edges[u, v]["length"] = distance / np.sqrt(weight)
         else:
-            # Use calculated distance directly
             G.edges[u, v]["length"] = distance
 
     return G
@@ -84,23 +82,23 @@ def _map_to_sphere(G: nx.Graph) -> None:
     Args:
         G (nx.Graph): The input graph with nodes having 'x' and 'y' coordinates.
     """
-    # Extract x, y coordinates from the graph nodes
-    xy_coords = np.array([[G.nodes[node]["x"], G.nodes[node]["y"]] for node in G.nodes()])
-    # Normalize the coordinates between [0, 1]
-    min_vals = np.min(xy_coords, axis=0)
-    max_vals = np.max(xy_coords, axis=0)
+    # Extract x, y coordinates as a NumPy array
+    nodes = list(G.nodes)
+    xy_coords = np.array([[G.nodes[node]["x"], G.nodes[node]["y"]] for node in nodes])
+    # Normalize coordinates between [0, 1]
+    min_vals = xy_coords.min(axis=0)
+    max_vals = xy_coords.max(axis=0)
     normalized_xy = (xy_coords - min_vals) / (max_vals - min_vals)
-    # Map normalized coordinates to theta and phi on a sphere
+    # Convert normalized coordinates to spherical coordinates
     theta = normalized_xy[:, 0] * np.pi * 2
     phi = normalized_xy[:, 1] * np.pi
-    # Convert spherical coordinates to Cartesian coordinates for 3D sphere
-    for i, node in enumerate(G.nodes()):
-        x = np.sin(phi[i]) * np.cos(theta[i])
-        y = np.sin(phi[i]) * np.sin(theta[i])
-        z = np.cos(phi[i])
-        G.nodes[node]["x"] = x
-        G.nodes[node]["y"] = y
-        G.nodes[node]["z"] = z
+    # Compute 3D Cartesian coordinates
+    x = np.sin(phi) * np.cos(theta)
+    y = np.sin(phi) * np.sin(theta)
+    z = np.cos(phi)
+    # Assign coordinates back to graph nodes in bulk
+    xyz_coords = {node: {"x": x[i], "y": y[i], "z": z[i]} for i, node in enumerate(nodes)}
+    nx.set_node_attributes(G, xyz_coords)
 
 
 def _normalize_graph_coordinates(G: nx.Graph) -> None:
@@ -148,18 +146,31 @@ def _create_depth(G: nx.Graph, surface_depth: float = 0.0) -> nx.Graph:
         nx.Graph: The graph with adjusted 'z' attribute for each node.
     """
     if surface_depth >= 1.0:
-        surface_depth = surface_depth - 1e-6  # Cap the surface depth to prevent value of 1.0
-
-    # Compute subclusters as connected components (subclusters can be any other method)
-    subclusters = {node: set(nx.node_connected_component(G, node)) for node in G.nodes}
-    # Create a strength metric for subclusters (here using size)
-    subcluster_strengths = {node: len(neighbors) for node, neighbors in subclusters.items()}
-    # Normalize the subcluster strengths and apply depths
-    max_strength = max(subcluster_strengths.values())
-    for node, strength in subcluster_strengths.items():
+        surface_depth -= 1e-6  # Cap the surface depth to prevent a value of 1.0
+
+    # Compute subclusters as connected components
+    connected_components = list(nx.connected_components(G))
+    subcluster_strengths = {}
+    max_strength = 0
+    # Precompute strengths and track the maximum strength
+    for component in connected_components:
+        size = len(component)
+        max_strength = max(max_strength, size)
+        for node in component:
+            subcluster_strengths[node] = size
+
+    # Avoid repeated lookups and computations by pre-fetching node data
+    nodes = list(G.nodes(data=True))
+    node_updates = {}
+    for node, attrs in nodes:
+        strength = subcluster_strengths[node]
         normalized_surface_depth = (strength / max_strength) * surface_depth
-        x, y, z = G.nodes[node]["x"], G.nodes[node]["y"], G.nodes[node]["z"]
+        x, y, z = attrs["x"], attrs["y"], attrs["z"]
         norm = np.sqrt(x**2 + y**2 + z**2)
-        G.nodes[node]["z"] -= (z / norm) * normalized_surface_depth  # Adjust Z for a depth
+        adjusted_z = z - (z / norm) * normalized_surface_depth
+        node_updates[node] = {"z": adjusted_z}
+
+    # Batch update node attributes
+    nx.set_node_attributes(G, node_updates)
 
     return G

risk/network/graph/__init__.py

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

risk/network/graph/api.py

@@ -0,0 +1,194 @@
+"""
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+import copy
+from typing import Any, Dict
+
+import networkx as nx
+import pandas as pd
+
+from risk.annotations import define_top_annotations
+from risk.log import logger, log_header, params
+from risk.neighborhoods import (
+    define_domains,
+    process_neighborhoods,
+    trim_domains,
+)
+from risk.network.graph.network import NetworkGraph
+from risk.stats import calculate_significance_matrices
+
+
+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.
+    """
+
+    def __init__() -> None:
+        pass
+
+    def load_graph(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        tail: str = "right",
+        pval_cutoff: float = 0.01,
+        fdr_cutoff: float = 0.9999,
+        impute_depth: int = 0,
+        prune_threshold: float = 0.0,
+        linkage_criterion: str = "distance",
+        linkage_method: str = "average",
+        linkage_metric: str = "yule",
+        min_cluster_size: int = 5,
+        max_cluster_size: int = 1000,
+    ) -> NetworkGraph:
+        """Load and process the network graph, defining top annotations and domains.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            neighborhoods (Dict[str, Any]): Neighborhood 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.
+            impute_depth (int, optional): Depth for imputing neighbors. Defaults to 0.
+            prune_threshold (float, optional): Distance threshold for pruning neighbors. Defaults to 0.0.
+            linkage_criterion (str, optional): Clustering criterion for defining domains. Defaults to "distance".
+            linkage_method (str, optional): Clustering method to use. Defaults to "average".
+            linkage_metric (str, optional): Metric to use for calculating distances. Defaults to "yule".
+            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:
+            NetworkGraph: A fully initialized and processed NetworkGraph object.
+        """
+        # Log the parameters and display headers
+        log_header("Finding significant neighborhoods")
+        params.log_graph(
+            tail=tail,
+            pval_cutoff=pval_cutoff,
+            fdr_cutoff=fdr_cutoff,
+            impute_depth=impute_depth,
+            prune_threshold=prune_threshold,
+            linkage_criterion=linkage_criterion,
+            linkage_method=linkage_method,
+            linkage_metric=linkage_metric,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )
+
+        # Make a copy of the network to avoid modifying the original
+        network = copy.deepcopy(network)
+
+        logger.debug(f"p-value cutoff: {pval_cutoff}")
+        logger.debug(f"FDR BH cutoff: {fdr_cutoff}")
+        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"],
+            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(
+            network=network,
+            neighborhoods=significant_neighborhoods,
+            impute_depth=impute_depth,
+            prune_threshold=prune_threshold,
+        )
+
+        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
+        top_annotations = self._define_top_annotations(
+            network=network,
+            annotations=annotations,
+            neighborhoods=processed_neighborhoods,
+            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"
+        ]
+        # Define domains in the network using the specified clustering settings
+        domains = define_domains(
+            top_annotations=top_annotations,
+            significant_neighborhoods_significance=significant_neighborhoods_significance,
+            linkage_criterion=linkage_criterion,
+            linkage_method=linkage_method,
+            linkage_metric=linkage_metric,
+        )
+        # Trim domains and top annotations based on cluster size constraints
+        domains, trimmed_domains = trim_domains(
+            domains=domains,
+            top_annotations=top_annotations,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )
+
+        # Prepare node mapping and significance sums for the final NetworkGraph object
+        ordered_nodes = annotations["ordered_nodes"]
+        node_label_to_id = dict(zip(ordered_nodes, range(len(ordered_nodes))))
+        node_significance_sums = processed_neighborhoods["node_significance_sums"]
+
+        # Return the fully initialized NetworkGraph object
+        return NetworkGraph(
+            network=network,
+            annotations=annotations,
+            neighborhoods=neighborhoods,
+            domains=domains,
+            trimmed_domains=trimmed_domains,
+            node_label_to_node_id_map=node_label_to_id,
+            node_significance_sums=node_significance_sums,
+        )
+
+    def _define_top_annotations(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        min_cluster_size: int = 5,
+        max_cluster_size: int = 1000,
+    ) -> pd.DataFrame:
+        """Define top annotations for the network.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): Annotations data for the network.
+            neighborhoods (Dict[str, Any]): Neighborhood 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.
+        """
+        # Extract necessary data from annotations and neighborhoods
+        ordered_annotations = annotations["ordered_annotations"]
+        neighborhood_significance_sums = neighborhoods["neighborhood_significance_counts"]
+        significant_significance_matrix = neighborhoods["significant_significance_matrix"]
+        significant_binary_significance_matrix = neighborhoods[
+            "significant_binary_significance_matrix"
+        ]
+        # Call external function to define top annotations
+        return define_top_annotations(
+            network=network,
+            ordered_annotation_labels=ordered_annotations,
+            neighborhood_significance_sums=neighborhood_significance_sums,
+            significant_significance_matrix=significant_significance_matrix,
+            significant_binary_significance_matrix=significant_binary_significance_matrix,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )

risk/network/graph/network.py

@@ -0,0 +1,269 @@
+"""
+risk/network/graph/network
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from collections import defaultdict
+from typing import Any, Dict, List
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from risk.network.graph.summary import AnalysisSummary
+
+
+class NetworkGraph:
+    """A class to represent a network graph and process its nodes and edges.
+
+    The NetworkGraph class provides functionality to handle and manipulate a network graph,
+    including managing domains, annotations, and node significance data. It also includes methods
+    for transforming and mapping graph coordinates, as well as generating colors based on node
+    significance.
+    """
+
+    def __init__(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        domains: pd.DataFrame,
+        trimmed_domains: pd.DataFrame,
+        node_label_to_node_id_map: Dict[str, Any],
+        node_significance_sums: np.ndarray,
+    ):
+        """Initialize the NetworkGraph object.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            neighborhoods (Dict[str, Any]): Neighborhood 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.
+            node_significance_sums (np.ndarray): Array containing the significant sums for the nodes.
+        """
+        # Initialize self.network downstream of the other attributes
+        # All public attributes can be accessed after initialization
+        self.domain_id_to_node_ids_map = self._create_domain_id_to_node_ids_map(domains)
+        self.domain_id_to_domain_terms_map = self._create_domain_id_to_domain_terms_map(
+            trimmed_domains
+        )
+        self.domain_id_to_domain_info_map = self._create_domain_id_to_domain_info_map(
+            trimmed_domains
+        )
+        self.node_id_to_domain_ids_and_significance_map = (
+            self._create_node_id_to_domain_ids_and_significances(domains)
+        )
+        self.node_id_to_node_label_map = {v: k for k, v in node_label_to_node_id_map.items()}
+        self.node_label_to_significance_map = dict(
+            zip(node_label_to_node_id_map.keys(), node_significance_sums)
+        )
+        self.node_significance_sums = node_significance_sums
+        self.node_label_to_node_id_map = node_label_to_node_id_map
+
+        # NOTE: Below this point, instance attributes (i.e., self) will be used!
+        self.domain_id_to_node_labels_map = self._create_domain_id_to_node_labels_map()
+        # Unfold the network's 3D coordinates to 2D and extract node coordinates
+        self.network = _unfold_sphere_to_plane(network)
+        self.node_coordinates = _extract_node_coordinates(self.network)
+
+        # NOTE: Only after the above attributes are initialized, we can create the summary
+        self.summary = AnalysisSummary(annotations, neighborhoods, self)
+
+    def pop(self, domain_id: str) -> None:
+        """Remove domain ID from instance domain ID mappings. This can be useful for cleaning up
+        domain-specific mappings based on a given criterion, as domain attributes are stored and
+        accessed only in dictionaries modified by this method.
+
+        Args:
+            key (str): The domain ID key to be removed from each mapping.
+        """
+        # Define the domain mappings to be updated
+        domain_mappings = [
+            self.domain_id_to_node_ids_map,
+            self.domain_id_to_domain_terms_map,
+            self.domain_id_to_domain_info_map,
+            self.domain_id_to_node_labels_map,
+        ]
+        # Remove the specified domain_id key from each mapping if it exists
+        for mapping in domain_mappings:
+            if domain_id in mapping:
+                mapping.pop(domain_id)
+
+        # Remove the domain_id from the node_id_to_domain_ids_and_significance_map
+        for _, domain_info in self.node_id_to_domain_ids_and_significance_map.items():
+            if domain_id in domain_info["domains"]:
+                domain_info["domains"].remove(domain_id)
+                domain_info["significances"].pop(domain_id)
+
+    @staticmethod
+    def _create_domain_id_to_node_ids_map(domains: pd.DataFrame) -> Dict[int, Any]:
+        """Create a mapping from domains to the list of node IDs belonging to each domain.
+
+        Args:
+            domains (pd.DataFrame): DataFrame containing domain information, including the 'primary domain' for each node.
+
+        Returns:
+            Dict[int, Any]: A dictionary where keys are domain IDs and values are lists of node IDs belonging to each domain.
+        """
+        cleaned_domains_matrix = domains.reset_index()[["index", "primary_domain"]]
+        node_to_domains_map = cleaned_domains_matrix.set_index("index")["primary_domain"].to_dict()
+        domain_id_to_node_ids_map = defaultdict(list)
+        for k, v in node_to_domains_map.items():
+            domain_id_to_node_ids_map[v].append(k)
+
+        return domain_id_to_node_ids_map
+
+    @staticmethod
+    def _create_domain_id_to_domain_terms_map(trimmed_domains: pd.DataFrame) -> Dict[int, Any]:
+        """Create a mapping from domain IDs to their corresponding terms.
+
+        Args:
+            trimmed_domains (pd.DataFrame): DataFrame containing domain IDs and their corresponding labels.
+
+        Returns:
+            Dict[int, Any]: A dictionary mapping domain IDs to their corresponding terms.
+        """
+        return dict(
+            zip(
+                trimmed_domains.index,
+                trimmed_domains["normalized_description"],
+            )
+        )
+
+    @staticmethod
+    def _create_domain_id_to_domain_info_map(
+        trimmed_domains: pd.DataFrame,
+    ) -> Dict[int, Dict[str, Any]]:
+        """Create a mapping from domain IDs to their corresponding full description and significance score,
+        with scores sorted in descending order.
+
+        Args:
+            trimmed_domains (pd.DataFrame): DataFrame containing domain IDs, full descriptions, and significance scores.
+
+        Returns:
+            Dict[int, Dict[str, Any]]: A dictionary mapping domain IDs (int) to a dictionary with 'full_descriptions' and
+                'significance_scores', both sorted by significance score in descending order.
+        """
+        # Initialize an empty dictionary to store full descriptions and significance scores of domains
+        domain_info_map = {}
+        # Domain IDs are the index of the DataFrame (it's common for some IDs to be missing)
+        for domain_id in trimmed_domains.index:
+            # Sort full_descriptions and significance_scores by significance_scores in descending order
+            descriptions_and_scores = sorted(
+                zip(
+                    trimmed_domains.at[domain_id, "full_descriptions"],
+                    trimmed_domains.at[domain_id, "significance_scores"],
+                ),
+                key=lambda x: x[1],  # Sort by significance score
+                reverse=True,  # Descending order
+            )
+            # Unzip the sorted tuples back into separate lists
+            sorted_descriptions, sorted_scores = zip(*descriptions_and_scores)
+            # Assign to the domain info map
+            domain_info_map[int(domain_id)] = {
+                "full_descriptions": list(sorted_descriptions),
+                "significance_scores": list(sorted_scores),
+            }
+
+        return domain_info_map
+
+    @staticmethod
+    def _create_node_id_to_domain_ids_and_significances(domains: pd.DataFrame) -> Dict[int, Dict]:
+        """Creates a dictionary mapping each node ID to its corresponding domain IDs and significance values.
+
+        Args:
+            domains (pd.DataFrame): A DataFrame containing domain information for each node. Assumes the last
+                two columns are 'all domains' and 'primary domain', which are excluded from processing.
+
+        Returns:
+            Dict[int, Dict]: A dictionary where the key is the node ID (index of the DataFrame), and the value is another dictionary
+                with 'domain' (a list of domain IDs with non-zero significance) and 'significance'
+                (a dict of domain IDs and their corresponding significance values).
+        """
+        # Initialize an empty dictionary to store the result
+        node_id_to_domain_ids_and_significances = {}
+        # Get the list of domain columns (excluding 'all domains' and 'primary domain')
+        domain_columns = domains.columns[
+            :-2
+        ]  # The last two columns are 'all domains' and 'primary domain'
+        # Iterate over each row in the dataframe
+        for idx, row in domains.iterrows():
+            # Get the domains (column names) where the significance score is greater than 0
+            all_domains = domain_columns[row[domain_columns] > 0].tolist()
+            # Get the significance values for those domains
+            significance_values = row[all_domains].to_dict()
+            # Store the result in the dictionary with index as the key
+            node_id_to_domain_ids_and_significances[idx] = {
+                "domains": all_domains,  # The column names where significance > 0
+                "significances": significance_values,  # The actual significance values for those columns
+            }
+
+        return node_id_to_domain_ids_and_significances
+
+    def _create_domain_id_to_node_labels_map(self) -> Dict[int, List[str]]:
+        """Create a map from domain IDs to node labels.
+
+        Returns:
+            Dict[int, List[str]]: A dictionary mapping domain IDs to the corresponding node labels.
+        """
+        domain_id_to_label_map = {}
+        for domain_id, node_ids in self.domain_id_to_node_ids_map.items():
+            domain_id_to_label_map[domain_id] = [
+                self.node_id_to_node_label_map[node_id] for node_id in node_ids
+            ]
+
+        return domain_id_to_label_map
+
+
+def _unfold_sphere_to_plane(G: nx.Graph) -> nx.Graph:
+    """Convert 3D coordinates to 2D by unfolding a sphere to a plane.
+
+    Args:
+        G (nx.Graph): A network graph with 3D coordinates. Each node should have 'x', 'y', and 'z' attributes.
+
+    Returns:
+        nx.Graph: The network graph with updated 2D coordinates (only 'x' and 'y').
+    """
+    for node in G.nodes():
+        if "z" in G.nodes[node]:
+            # Extract 3D coordinates
+            x, y, z = G.nodes[node]["x"], G.nodes[node]["y"], G.nodes[node]["z"]
+            # Calculate spherical coordinates theta and phi from Cartesian coordinates
+            r = np.sqrt(x**2 + y**2 + z**2)
+            theta = np.arctan2(y, x)
+            phi = np.arccos(z / r)
+
+            # Convert spherical coordinates to 2D plane coordinates
+            unfolded_x = (theta + np.pi) / (2 * np.pi)  # Shift and normalize theta to [0, 1]
+            unfolded_x = unfolded_x + 0.5 if unfolded_x < 0.5 else unfolded_x - 0.5
+            unfolded_y = (np.pi - phi) / np.pi  # Reflect phi and normalize to [0, 1]
+            # Update network node attributes
+            G.nodes[node]["x"] = unfolded_x
+            G.nodes[node]["y"] = -unfolded_y
+            # Remove the 'z' coordinate as it's no longer needed
+            del G.nodes[node]["z"]
+
+    return G
+
+
+def _extract_node_coordinates(G: nx.Graph) -> np.ndarray:
+    """Extract 2D coordinates of nodes from the graph.
+
+    Args:
+        G (nx.Graph): The network graph with node coordinates.
+
+    Returns:
+        np.ndarray: Array of node coordinates with shape (num_nodes, 2).
+    """
+    # Extract x and y coordinates from graph nodes
+    x_coords = dict(G.nodes.data("x"))
+    y_coords = dict(G.nodes.data("y"))
+    coordinates_dicts = [x_coords, y_coords]
+    # Combine x and y coordinates into a single array
+    node_positions = {
+        node: np.array([coords[node] for coords in coordinates_dicts]) for node in x_coords
+    }
+    node_coordinates = np.vstack(list(node_positions.values()))
+    return node_coordinates