risk-network 0.0.9b23__py3-none-any.whl → 0.0.9b25__py3-none-any.whl

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/summary.py

@@ -240,8 +240,12 @@ class AnalysisSummary:
         except ValueError:
             return ""  # Description not found
 
-        # Get nodes present for the annotation and sort by node label
-        nodes_present = np.where(self.annotations["matrix"][:, annotation_idx] == 1)[0]
+        # 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

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

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.colors 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:

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

@@ -12,8 +12,8 @@ from scipy.ndimage import label
 from scipy.stats import gaussian_kde
 
 from risk.log import params, logger
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.colors import get_annotated_domain_colors, to_rgba
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.utils.colors import get_annotated_domain_colors, to_rgba
 
 
 class Contour:

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

@@ -11,9 +11,9 @@ import numpy as np
 import pandas as pd
 
 from risk.log import params
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.colors import get_annotated_domain_colors, 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 get_annotated_domain_colors, to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
 
 TERM_DELIMITER = "::::"  # String used to separate multiple domain terms when constructing composite domain labels
 

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

@@ -5,16 +5,24 @@ risk/network/plot/network
 
 from typing import Any, Dict, List, Tuple, Union
 
+import matplotlib.pyplot as plt
 import networkx as nx
 import numpy as np
 
 from risk.log import params
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.colors import get_domain_colors, to_rgba
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.canvas import Canvas
+from risk.network.plotter.contour import Contour
+from risk.network.plotter.labels import Labels
+from risk.network.plotter.utils.colors import get_domain_colors, to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
 
 
 class Network:
-    """Class for plotting nodes and edges in a network graph."""
+    """A class for plotting network graphs with customizable options.
+
+    The Network class provides methods to plot network graphs with flexible node and edge properties.
+    """
 
     def __init__(self, graph: NetworkGraph, ax: Any = None) -> None:
         """Initialize the NetworkPlotter class.
@@ -289,3 +297,128 @@ class Network:
                 node_sizes[node] = significant_size
 
         return node_sizes
+
+
+class NetworkPlotter(Canvas, Network, Contour, Labels):
+    """A class for visualizing network graphs with customizable options.
+
+    The NetworkPlotter class uses a NetworkGraph object and provides methods to plot the network with
+    flexible node and edge properties. It also supports plotting labels, contours, drawing the network's
+    perimeter, and adjusting background colors.
+    """
+
+    def __init__(
+        self,
+        graph: NetworkGraph,
+        figsize: Tuple = (10, 10),
+        background_color: Union[str, List, Tuple, np.ndarray] = "white",
+        background_alpha: Union[float, None] = 1.0,
+        pad: float = 0.3,
+    ) -> None:
+        """Initialize the NetworkPlotter with a NetworkGraph object and plotting parameters.
+
+        Args:
+            graph (NetworkGraph): The network data and attributes to be visualized.
+            figsize (Tuple, optional): Size of the figure in inches (width, height). Defaults to (10, 10).
+            background_color (str, List, Tuple, np.ndarray, 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.
+        """
+        self.graph = graph
+        # Initialize the plot with the specified parameters
+        self.ax = self._initialize_plot(
+            graph=graph,
+            figsize=figsize,
+            background_color=background_color,
+            background_alpha=background_alpha,
+            pad=pad,
+        )
+        super().__init__(graph=graph, ax=self.ax)
+
+    def _initialize_plot(
+        self,
+        graph: NetworkGraph,
+        figsize: Tuple,
+        background_color: Union[str, List, Tuple, np.ndarray],
+        background_alpha: Union[float, None],
+        pad: float,
+    ) -> plt.Axes:
+        """Set up the plot with figure size and background color.
+
+        Args:
+            graph (NetworkGraph): The network data and attributes to be visualized.
+            figsize (Tuple): Size of the figure in inches (width, height).
+            background_color (str, List, Tuple, or np.ndarray): Background color of the plot. Can be a single color or an array of colors.
+            background_alpha (float, None, optional): Transparency level of the background color. If provided, it overrides any existing
+                alpha values found in `background_color`.
+            pad (float, optional): Padding value to adjust the axis limits.
+
+        Returns:
+            plt.Axes: The axis object for the plot.
+        """
+        # Log the plotter settings
+        params.log_plotter(
+            figsize=figsize,
+            background_color=background_color,
+            background_alpha=background_alpha,
+            pad=pad,
+        )
+
+        # Extract node coordinates from the network graph
+        node_coordinates = graph.node_coordinates
+        # Calculate the center and radius of the bounding box around the network
+        center, radius = calculate_bounding_box(node_coordinates)
+
+        # Create a new figure and axis for plotting
+        fig, ax = plt.subplots(figsize=figsize)
+        fig.tight_layout()  # Adjust subplot parameters to give specified padding
+        # Set axis limits based on the calculated bounding box and radius
+        ax.set_xlim([center[0] - radius - pad, center[0] + radius + pad])
+        ax.set_ylim([center[1] - radius - pad, center[1] + radius + pad])
+        ax.set_aspect("equal")  # Ensure the aspect ratio is equal
+
+        # Set the background color of the plot
+        # Convert color to RGBA using the to_rgba helper function
+        fig.patch.set_facecolor(
+            to_rgba(color=background_color, alpha=background_alpha, num_repeats=1)
+        )  # num_repeats=1 for single color
+        ax.invert_yaxis()  # Invert the y-axis to match typical image coordinates
+        # Remove axis spines for a cleaner look
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+
+        # Hide axis ticks and labels
+        ax.set_xticks([])
+        ax.set_yticks([])
+        ax.patch.set_visible(False)  # Hide the axis background
+
+        return ax
+
+    @staticmethod
+    def savefig(*args, pad_inches: float = 0.5, dpi: int = 100, **kwargs) -> None:
+        """Save the current plot to a file with additional export options.
+
+        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.
+            **kwargs: Keyword arguments passed to `plt.savefig`, such as filename and format.
+        """
+        # Ensure user-provided kwargs take precedence
+        kwargs.setdefault("dpi", dpi)
+        kwargs.setdefault("pad_inches", pad_inches)
+        # Ensure the plot is saved with tight bounding box if not specified
+        kwargs.setdefault("bbox_inches", "tight")
+        # Call plt.savefig with combined arguments
+        plt.savefig(*args, **kwargs)
+
+    @staticmethod
+    def show(*args, **kwargs) -> None:
+        """Display the current plot.
+
+        Args:
+            *args: Positional arguments passed to `plt.show`.
+            **kwargs: Keyword arguments passed to `plt.show`.
+        """
+        plt.show(*args, **kwargs)

risk/network/{plot → plotter}/utils/colors.py

@@ -9,7 +9,7 @@ import matplotlib
 import matplotlib.colors as mcolors
 import numpy as np
 
-from risk.network.graph import NetworkGraph
+from risk.network.graph.network import NetworkGraph
 
 
 def get_annotated_domain_colors(
@@ -68,7 +68,7 @@ def get_annotated_domain_colors(
 
         annotated_colors.append(color)
 
-    return np.array(annotated_colors)
+    return annotated_colors
 
 
 def get_domain_colors(
@@ -311,19 +311,28 @@ def _transform_colors(
     if min_scale == max_scale:
         min_scale = max_scale - 10e-6  # Avoid division by zero
 
+    # Replace invalid values in colors early
+    colors = np.nan_to_num(colors, nan=0.0)  # Replace NaN with black
     # Replace black colors (#000000) with very dark grey (#1A1A1A)
     black_color = np.array([0.0, 0.0, 0.0])  # Pure black RGB
     dark_grey = np.array([0.1, 0.1, 0.1])  # Very dark grey RGB (#1A1A1A)
-    # Check where colors are black (very close to [0, 0, 0]) and replace with dark grey
     is_black = np.all(colors[:, :3] == black_color, axis=1)
     colors[is_black, :3] = dark_grey
 
-    # Normalize the significance sums to the range [0, 1]
-    normalized_sums = significance_sums / np.max(significance_sums)
-    # Apply power scaling to dim lower values and emphasize higher values
+    # Handle invalid or zero significance sums
+    max_significance = np.max(significance_sums)
+    if max_significance == 0:
+        max_significance = 1  # Avoid division by zero
+    normalized_sums = significance_sums / max_significance
+    # Replace NaN values in normalized sums
+    normalized_sums = np.nan_to_num(normalized_sums, nan=0.0)
+
+    # Apply power scaling to emphasize higher significance values
     scaled_sums = normalized_sums**scale_factor
     # Linearly scale the normalized sums to the range [min_scale, max_scale]
     scaled_sums = min_scale + (max_scale - min_scale) * scaled_sums
+    # Replace NaN or invalid scaled sums
+    scaled_sums = np.nan_to_num(scaled_sums, nan=min_scale)
     # Adjust RGB values based on scaled sums
     for i in range(3):  # Only adjust RGB values
         colors[:, i] = scaled_sums * colors[:, i]