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

risk/network/graph/summary.py

@@ -0,0 +1,254 @@
+"""
+risk/network/graph/summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from statsmodels.stats.multitest import fdrcorrection
+
+from risk.log.console import logger, log_header
+
+
+class AnalysisSummary:
+    """Handles the processing, storage, and export of network analysis results.
+
+    The Results class provides methods to process significance and depletion data, compute
+    FDR-corrected q-values, and structure information on domains and annotations into a
+    DataFrame. It also offers functionality to export the processed data in CSV, JSON,
+    and text formats for analysis and reporting.
+    """
+
+    def __init__(
+        self,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        graph,  # Avoid type hinting NetworkGraph to prevent circular imports
+    ):
+        """Initialize the Results object with analysis components.
+
+        Args:
+            annotations (Dict[str, Any]): Annotation data, including ordered annotations and matrix of associations.
+            neighborhoods (Dict[str, Any]): Neighborhood data containing p-values for significance and depletion analysis.
+            graph (NetworkGraph): Graph object representing domain-to-node and node-to-label mappings.
+        """
+        self.annotations = annotations
+        self.neighborhoods = neighborhoods
+        self.graph = graph
+
+    def to_csv(self, filepath: str) -> None:
+        """Export significance results to a CSV file.
+
+        Args:
+            filepath (str): The path where the CSV file will be saved.
+        """
+        # Load results and export directly to CSV
+        results = self.load()
+        results.to_csv(filepath, index=False)
+        logger.info(f"Analysis summary exported to CSV file: {filepath}")
+
+    def to_json(self, filepath: str) -> None:
+        """Export significance results to a JSON file.
+
+        Args:
+            filepath (str): The path where the JSON file will be saved.
+        """
+        # Load results and export directly to JSON
+        results = self.load()
+        results.to_json(filepath, orient="records", indent=4)
+        logger.info(f"Analysis summary exported to JSON file: {filepath}")
+
+    def to_txt(self, filepath: str) -> None:
+        """Export significance results to a text file.
+
+        Args:
+            filepath (str): The path where the text file will be saved.
+        """
+        # Load results and export directly to text file
+        results = self.load()
+        with open(filepath, "w", encoding="utf-8") as txt_file:
+            txt_file.write(results.to_string(index=False))
+
+        logger.info(f"Analysis summary exported to text file: {filepath}")
+
+    def load(self) -> pd.DataFrame:
+        """Load and process domain and annotation data into a DataFrame with significance metrics.
+
+        Returns:
+            pd.DataFrame: Processed DataFrame containing significance scores, p-values, q-values,
+                and annotation member information.
+        """
+        log_header("Loading analysis summary")
+        # Calculate significance and depletion q-values from p-value matrices in `annotations`
+        enrichment_pvals = self.neighborhoods["enrichment_pvals"]
+        depletion_pvals = self.neighborhoods["depletion_pvals"]
+        enrichment_qvals = self._calculate_qvalues(enrichment_pvals)
+        depletion_qvals = self._calculate_qvalues(depletion_pvals)
+
+        # Initialize DataFrame with domain and annotation details
+        results = pd.DataFrame(
+            [
+                {"Domain ID": domain_id, "Annotation": desc, "Summed Significance Score": score}
+                for domain_id, info in self.graph.domain_id_to_domain_info_map.items()
+                for desc, score in zip(info["full_descriptions"], info["significance_scores"])
+            ]
+        )
+        # Sort by Domain ID and Summed Significance Score
+        results = results.sort_values(
+            by=["Domain ID", "Summed Significance Score"], ascending=[True, False]
+        ).reset_index(drop=True)
+
+        # Add minimum p-values and q-values to DataFrame
+        results[
+            [
+                "Enrichment P-value",
+                "Enrichment Q-value",
+                "Depletion P-value",
+                "Depletion Q-value",
+            ]
+        ] = results.apply(
+            lambda row: self._get_significance_values(
+                row["Domain ID"],
+                row["Annotation"],
+                enrichment_pvals,
+                depletion_pvals,
+                enrichment_qvals,
+                depletion_qvals,
+            ),
+            axis=1,
+            result_type="expand",
+        )
+        # Add annotation members and their counts
+        results["Annotation Members in Network"] = results["Annotation"].apply(
+            lambda desc: self._get_annotation_members(desc)
+        )
+        results["Annotation Members in Network Count"] = results[
+            "Annotation Members in Network"
+        ].apply(lambda x: len(x.split(";")) if x else 0)
+
+        # Reorder columns and drop rows with NaN values
+        results = (
+            results[
+                [
+                    "Domain ID",
+                    "Annotation",
+                    "Annotation Members in Network",
+                    "Annotation Members in Network Count",
+                    "Summed Significance Score",
+                    "Enrichment P-value",
+                    "Enrichment Q-value",
+                    "Depletion P-value",
+                    "Depletion Q-value",
+                ]
+            ]
+            .dropna()
+            .reset_index(drop=True)
+        )
+
+        # Convert annotations list to a DataFrame for comparison then merge with results
+        ordered_annotations = pd.DataFrame({"Annotation": self.annotations["ordered_annotations"]})
+        # Merge to ensure all annotations are present, filling missing rows with defaults
+        results = pd.merge(ordered_annotations, results, on="Annotation", how="left").fillna(
+            {
+                "Domain ID": -1,
+                "Annotation Members in Network": "",
+                "Annotation Members in Network Count": 0,
+                "Summed Significance Score": 0.0,
+                "Enrichment P-value": 1.0,
+                "Enrichment Q-value": 1.0,
+                "Depletion P-value": 1.0,
+                "Depletion Q-value": 1.0,
+            }
+        )
+        # Convert "Domain ID" and "Annotation Members in Network Count" to integers
+        results["Domain ID"] = results["Domain ID"].astype(int)
+        results["Annotation Members in Network Count"] = results[
+            "Annotation Members in Network Count"
+        ].astype(int)
+
+        return results
+
+    @staticmethod
+    def _calculate_qvalues(pvals: np.ndarray) -> np.ndarray:
+        """Calculate q-values (FDR) for each row of a p-value matrix.
+
+        Args:
+            pvals (np.ndarray): 2D array of p-values.
+
+        Returns:
+            np.ndarray: 2D array of q-values, with FDR correction applied row-wise.
+        """
+        return np.apply_along_axis(lambda row: fdrcorrection(row)[1], 1, pvals)
+
+    def _get_significance_values(
+        self,
+        domain_id: int,
+        description: str,
+        enrichment_pvals: np.ndarray,
+        depletion_pvals: np.ndarray,
+        enrichment_qvals: np.ndarray,
+        depletion_qvals: np.ndarray,
+    ) -> Tuple[Union[float, None], Union[float, None], Union[float, None], Union[float, None]]:
+        """Retrieve the most significant p-values and q-values (FDR) for a given annotation.
+
+        Args:
+            domain_id (int): The domain ID associated with the annotation.
+            description (str): The annotation description.
+            enrichment_pvals (np.ndarray): Matrix of significance p-values.
+            depletion_pvals (np.ndarray): Matrix of depletion p-values.
+            enrichment_qvals (np.ndarray): Matrix of significance q-values.
+            depletion_qvals (np.ndarray): Matrix of depletion q-values.
+
+        Returns:
+            Tuple[Union[float, None], Union[float, None], Union[float, None], Union[float, None]]:
+                Minimum significance p-value, significance q-value, depletion p-value, depletion q-value.
+        """
+        try:
+            annotation_idx = self.annotations["ordered_annotations"].index(description)
+        except ValueError:
+            return None, None, None, None  # Description not found
+
+        node_indices = self.graph.domain_id_to_node_ids_map.get(domain_id, [])
+        if not node_indices:
+            return None, None, None, None  # No associated nodes
+
+        sig_p = enrichment_pvals[node_indices, annotation_idx]
+        dep_p = depletion_pvals[node_indices, annotation_idx]
+        sig_q = enrichment_qvals[node_indices, annotation_idx]
+        dep_q = depletion_qvals[node_indices, annotation_idx]
+
+        return (
+            np.min(sig_p) if sig_p.size > 0 else None,
+            np.min(sig_q) if sig_q.size > 0 else None,
+            np.min(dep_p) if dep_p.size > 0 else None,
+            np.min(dep_q) if dep_q.size > 0 else None,
+        )
+
+    def _get_annotation_members(self, description: str) -> str:
+        """Retrieve node labels associated with a given annotation description.
+
+        Args:
+            description (str): The annotation description.
+
+        Returns:
+            str: ';'-separated string of node labels that are associated with the annotation.
+        """
+        try:
+            annotation_idx = self.annotations["ordered_annotations"].index(description)
+        except ValueError:
+            return ""  # Description not found
+
+        # Get the column (safely) from the sparse matrix
+        column = self.annotations["matrix"][:, annotation_idx]
+        # Convert the column to a dense array if needed
+        column = column.toarray().ravel()  # Convert to a 1D dense array
+        # Get nodes present for the annotation and sort by node label - use np.where on the dense array
+        nodes_present = np.where(column == 1)[0]
+        node_labels = sorted(
+            self.graph.node_id_to_node_label_map[node_id]
+            for node_id in nodes_present
+            if node_id in self.graph.node_id_to_node_label_map
+        )
+        return ";".join(node_labels)

risk/network/io.py

@@ -1,8 +1,6 @@
 """
 risk/network/io
 ~~~~~~~~~~~~~~~
-
-This file contains the code for the RISK class and command-line access.
 """
 
 import copy
@@ -165,12 +163,12 @@ class NetworkIO:
         filepath: str,
         source_label: str = "source",
         target_label: str = "target",
+        view_name: str = "",
         compute_sphere: bool = True,
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
         include_edge_weight: bool = True,
         weight_label: str = "weight",
-        view_name: str = "",
     ) -> nx.Graph:
         """Load a network from a Cytoscape file.
 
@@ -178,7 +176,7 @@ class NetworkIO:
             filepath (str): Path to the Cytoscape file.
             source_label (str, optional): Source node label. Defaults to "source".
             target_label (str, optional): Target node label. Defaults to "target".
-            view_name (str, optional): Specific view name to load. Defaults to None.
+            view_name (str, optional): Specific view name to load. Defaults to "".
             compute_sphere (bool, optional): Whether to map nodes to a sphere. Defaults to True.
             surface_depth (float, optional): Surface depth for the sphere. Defaults to 0.0.
             min_edges_per_node (int, optional): Minimum number of edges per node. Defaults to 0.
@@ -215,7 +213,7 @@ class NetworkIO:
             filepath (str): Path to the Cytoscape file.
             source_label (str, optional): Source node label. Defaults to "source".
             target_label (str, optional): Target node label. Defaults to "target".
-            view_name (str, optional): Specific view name to load. Defaults to None.
+            view_name (str, optional): Specific view name to load. Defaults to "".
 
         Returns:
             nx.Graph: Loaded and processed network.
@@ -298,12 +296,8 @@ class NetworkIO:
             # Add node attributes
             for node in G.nodes():
                 G.nodes[node]["label"] = node
-                G.nodes[node]["x"] = node_x_positions[
-                    node
-                ]  # Assuming you have a dict `node_x_positions` for x coordinates
-                G.nodes[node]["y"] = node_y_positions[
-                    node
-                ]  # Assuming you have a dict `node_y_positions` for y coordinates
+                G.nodes[node]["x"] = node_x_positions[node]
+                G.nodes[node]["y"] = node_y_positions[node]
 
             # Initialize the graph
             return self._initialize_graph(G)
@@ -379,15 +373,17 @@ class NetworkIO:
         node_y_positions = {}
         for node in cyjs_data["elements"]["nodes"]:
             node_data = node["data"]
-            node_id = node_data["id_original"]
+            # Use the original node ID if available, otherwise use the default ID
+            node_id = node_data.get("id_original", node_data.get("id"))
             node_x_positions[node_id] = node["position"]["x"]
             node_y_positions[node_id] = node["position"]["y"]
 
         # Process edges and add them to the graph
         for edge in cyjs_data["elements"]["edges"]:
             edge_data = edge["data"]
-            source = edge_data[f"{source_label}_original"]
-            target = edge_data[f"{target_label}_original"]
+            # Use the original source and target labels if available, otherwise fall back to default labels
+            source = edge_data.get(f"{source_label}_original", edge_data.get(source_label))
+            target = edge_data.get(f"{target_label}_original", edge_data.get(target_label))
             # Add the edge to the graph, optionally including weights
             if self.weight_label is not None and self.weight_label in edge_data:
                 weight = float(edge_data[self.weight_label])
@@ -425,7 +421,7 @@ class NetworkIO:
         self._remove_invalid_graph_properties(G)
         # IMPORTANT: This is where the graph node labels are converted to integers
         # Make sure to perform this step after all other processing
-        G = nx.relabel_nodes(G, {node: idx for idx, node in enumerate(G.nodes)})
+        G = nx.convert_node_labels_to_integers(G)
         return G
 
     def _remove_invalid_graph_properties(self, G: nx.Graph) -> None:
@@ -435,22 +431,24 @@ class NetworkIO:
         Args:
             G (nx.Graph): A NetworkX graph object.
         """
-        # Count number of nodes and edges before cleaning
+        # Count the number of nodes and edges before cleaning
         num_initial_nodes = G.number_of_nodes()
         num_initial_edges = G.number_of_edges()
         # Remove self-loops to ensure correct edge count
-        G.remove_edges_from(list(nx.selfloop_edges(G)))
+        G.remove_edges_from(nx.selfloop_edges(G))
         # Iteratively remove nodes with fewer edges than the threshold
         while True:
-            nodes_to_remove = [node for node in G.nodes if G.degree(node) < self.min_edges_per_node]
+            nodes_to_remove = [
+                node
+                for node, degree in dict(G.degree()).items()
+                if degree < self.min_edges_per_node
+            ]
             if not nodes_to_remove:
-                break  # Exit loop if no more nodes need removal
+                break  # Exit loop if no nodes meet the condition
             G.remove_nodes_from(nodes_to_remove)
 
         # Remove isolated nodes
-        isolated_nodes = list(nx.isolates(G))
-        if isolated_nodes:
-            G.remove_nodes_from(isolated_nodes)
+        G.remove_nodes_from(nx.isolates(G))
 
         # Log the number of nodes and edges before and after cleaning
         num_final_nodes = G.number_of_nodes()
@@ -468,12 +466,9 @@ class NetworkIO:
         """
         missing_weights = 0
         # Assign user-defined edge weights to the "weight" attribute
-        for _, _, data in G.edges(data=True):
-            if self.weight_label not in data:
-                missing_weights += 1
-            data["weight"] = data.get(
-                self.weight_label, 1.0
-            )  # Default to 1.0 if 'weight' not present
+        nx.set_edge_attributes(G, 1.0, "weight")  # Set default weight
+        if self.weight_label in nx.get_edge_attributes(G, self.weight_label):
+            nx.set_edge_attributes(G, nx.get_edge_attributes(G, self.weight_label), "weight")
 
         if self.include_edge_weight and missing_weights:
             logger.debug(f"Total edges missing weights: {missing_weights}")
@@ -483,41 +478,55 @@ class NetworkIO:
 
         Args:
             G (nx.Graph): A NetworkX graph object.
+
+        Raises:
+            ValueError: If a node is missing 'x', 'y', and a valid 'pos' attribute.
         """
-        # Keep track of nodes missing labels
+        # Retrieve all relevant attributes in bulk
+        pos_attrs = nx.get_node_attributes(G, "pos")
+        name_attrs = nx.get_node_attributes(G, "name")
+        id_attrs = nx.get_node_attributes(G, "id")
+        # Dictionaries to hold missing or fallback attributes
+        x_attrs = {}
+        y_attrs = {}
+        label_attrs = {}
         nodes_with_missing_labels = []
 
-        for node, attrs in G.nodes(data=True):
-            # Attribute fallback for 'x' and 'y' attributes
+        # Iterate through nodes to validate and assign missing attributes
+        for node in G.nodes:
+            attrs = G.nodes[node]
+            # Validate and assign 'x' and 'y' attributes
             if "x" not in attrs or "y" not in attrs:
                 if (
-                    "pos" in attrs
-                    and isinstance(attrs["pos"], (list, tuple, np.ndarray))
-                    and len(attrs["pos"]) >= 2
+                    node in pos_attrs
+                    and isinstance(pos_attrs[node], (list, tuple, np.ndarray))
+                    and len(pos_attrs[node]) >= 2
                 ):
-                    attrs["x"], attrs["y"] = attrs["pos"][
-                        :2
-                    ]  # Use only x and y, ignoring z if present
+                    x_attrs[node], y_attrs[node] = pos_attrs[node][:2]
                 else:
                     raise ValueError(
                         f"Node {node} is missing 'x', 'y', and a valid 'pos' attribute."
                     )
 
-            # Attribute fallback for 'label' attribute
+            # Validate and assign 'label' attribute
             if "label" not in attrs:
-                # Try alternative attribute names for label
-                if "name" in attrs:
-                    attrs["label"] = attrs["name"]
-                elif "id" in attrs:
-                    attrs["label"] = attrs["id"]
+                if node in name_attrs:
+                    label_attrs[node] = name_attrs[node]
+                elif node in id_attrs:
+                    label_attrs[node] = id_attrs[node]
                 else:
-                    # Collect nodes with missing labels
+                    # Assign node ID as label and log the missing label
+                    label_attrs[node] = str(node)
                     nodes_with_missing_labels.append(node)
-                    attrs["label"] = str(node)  # Use node ID as the label
 
-        # Issue a single warning if any labels were missing
+        # Batch update attributes in the graph
+        nx.set_node_attributes(G, x_attrs, "x")
+        nx.set_node_attributes(G, y_attrs, "y")
+        nx.set_node_attributes(G, label_attrs, "label")
+
+        # Log a warning if any labels were missing
         if nodes_with_missing_labels:
-            total_nodes = len(G.nodes)
+            total_nodes = G.number_of_nodes()
             fraction_missing_labels = len(nodes_with_missing_labels) / total_nodes
             logger.warning(
                 f"{len(nodes_with_missing_labels)} out of {total_nodes} nodes "

risk/network/plotter/__init__.py

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

risk/network/plotter/api.py

@@ -0,0 +1,54 @@
+"""
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import List, Tuple, Union
+
+import numpy as np
+
+from risk.log import log_header
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.network import NetworkPlotter
+
+
+class PlotterAPI:
+    """Handles the loading of network plotter objects.
+
+    The PlotterAPI class provides methods to load and configure NetworkPlotter objects for plotting network graphs.
+    """
+
+    def __init__() -> None:
+        pass
+
+    def load_plotter(
+        self,
+        graph: NetworkGraph,
+        figsize: Union[List, Tuple, np.ndarray] = (10, 10),
+        background_color: str = "white",
+        background_alpha: Union[float, None] = 1.0,
+        pad: float = 0.3,
+    ) -> NetworkPlotter:
+        """Get a NetworkPlotter object for plotting.
+
+        Args:
+            graph (NetworkGraph): 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).
+            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.
+            pad (float, optional): Padding value to adjust the axis limits. Defaults to 0.3.
+
+        Returns:
+            NetworkPlotter: A NetworkPlotter object configured with the given parameters.
+        """
+        log_header("Loading plotter")
+
+        # Initialize and return a NetworkPlotter object
+        return NetworkPlotter(
+            graph,
+            figsize=figsize,
+            background_color=background_color,
+            background_alpha=background_alpha,
+            pad=pad,
+        )

risk/network/{plot → plotter}/canvas.py

@@ -9,9 +9,9 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 from risk.log import params
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.color import to_rgba
-from risk.network.plot.utils.layout import calculate_bounding_box
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.utils.colors import to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
 
 
 class Canvas:
@@ -36,6 +36,7 @@ class Canvas:
         font: str = "Arial",
         title_color: Union[str, List, Tuple, np.ndarray] = "black",
         subtitle_color: Union[str, List, Tuple, np.ndarray] = "gray",
+        title_x: float = 0.5,
         title_y: float = 0.975,
         title_space_offset: float = 0.075,
         subtitle_offset: float = 0.025,
@@ -52,6 +53,7 @@ class Canvas:
                 Defaults to "black".
             subtitle_color (str, List, Tuple, or np.ndarray, optional): Color of the subtitle text. Can be a string or an array of colors.
                 Defaults to "gray".
+            title_x (float, optional): X-axis position of the title. Defaults to 0.5.
             title_y (float, optional): Y-axis position of the title. Defaults to 0.975.
             title_space_offset (float, optional): Fraction of figure height to leave for the space above the plot. Defaults to 0.075.
             subtitle_offset (float, optional): Offset factor to position the subtitle below the title. Defaults to 0.025.
@@ -85,7 +87,7 @@ class Canvas:
                 fontsize=title_fontsize,
                 color=title_color,
                 fontname=font,
-                x=0.5,  # Center the title horizontally
+                x=title_x,
                 ha="center",
                 va="top",
                 y=title_y,
@@ -234,6 +236,7 @@ class Canvas:
         # Scale the node coordinates if needed
         scaled_coordinates = node_coordinates * scale
         # Use the existing _draw_kde_contour method
+        # NOTE: This is a technical debt that should be refactored in the future - only works when inherited by NetworkPlotter
         self._draw_kde_contour(
             ax=self.ax,
             pos=scaled_coordinates,