risk-network 0.0.11__py3-none-any.whl → 0.0.12b0__py3-none-any.whl

risk/network/graph/api.py

@@ -1,200 +0,0 @@
-"""
-risk/network/graph/api
-~~~~~~~~~~~~~~~~~~~~~~
-"""
-
-import copy
-from typing import Any, Dict, Union
-
-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.graph import Graph
-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",
-        linkage_threshold: Union[float, str] = 0.2,
-        min_cluster_size: int = 5,
-        max_cluster_size: int = 1000,
-    ) -> Graph:
-        """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. Choose "auto" to optimize. Defaults to "average".
-            linkage_metric (str, optional): Metric to use for calculating distances. Choose "auto" to optimize.
-                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.
-
-        Returns:
-            Graph: A fully initialized and processed Graph 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,
-            linkage_threshold=linkage_threshold,
-            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,
-            linkage_threshold=linkage_threshold,
-        )
-        # 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 Graph 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 Graph object
-        return Graph(
-            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/graph.py

@@ -1,269 +0,0 @@
-"""
-risk/network/graph/graph
-~~~~~~~~~~~~~~~~~~~~~~~~
-"""
-
-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 Summary
-
-
-class Graph:
-    """A class to represent a network graph and process its nodes and edges.
-
-    The Graph 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 Graph 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 = Summary(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