risk-network 0.0.13b4__py3-none-any.whl → 0.0.14b0__py3-none-any.whl

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

@@ -1,6 +1,6 @@
 """
-risk/network/graph/stats
-~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_network/_graph/_stats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, Union
@@ -16,7 +16,8 @@ def calculate_significance_matrices(
     pval_cutoff: float = 0.05,
     fdr_cutoff: float = 0.05,
 ) -> Dict[str, Any]:
-    """Calculate significance matrices based on p-values and specified tail.
+    """
+    Calculate significance matrices based on p-values and specified tail.
 
     Args:
         depletion_pvals (np.ndarray): Matrix of depletion p-values.
@@ -89,7 +90,8 @@ def _select_significance_matrices(
     log_enrichment_matrix: np.ndarray,
     enrichment_alpha_threshold_matrix: np.ndarray,
 ) -> tuple:
-    """Select significance matrices based on the specified tail type.
+    """
+    Select significance matrices based on the specified tail type.
 
     Args:
         tail (str): The tail type for significance selection. Options are 'left', 'right', or 'both'.
@@ -143,7 +145,8 @@ def _compute_threshold_matrix(
     pval_cutoff: float = 0.05,
     fdr_cutoff: float = 0.05,
 ) -> np.ndarray:
-    """Compute a threshold matrix indicating significance based on p-value and FDR cutoffs.
+    """
+    Compute a threshold matrix indicating significance based on p-value and FDR cutoffs.
 
     Args:
         pvals (np.ndarray): Array of p-values for statistical tests.

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

@@ -1,6 +1,6 @@
 """
-risk/network/graph/summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_network/_graph/_summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import Any, Dict, Tuple, Union
@@ -9,11 +9,12 @@ import numpy as np
 import pandas as pd
 from statsmodels.stats.multitest import fdrcorrection
 
-from risk.log.console import log_header, logger
+from ..._log import log_header, logger
 
 
 class Summary:
-    """Handles the processing, storage, and export of network analysis results.
+    """
+    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
@@ -27,7 +28,8 @@ class Summary:
         neighborhoods: Dict[str, Any],
         graph,  # Avoid type hinting Graph to prevent circular imports
     ):
-        """Initialize the Results object with analysis components.
+        """
+        Initialize the Results object with analysis components.
 
         Args:
             annotation (Dict[str, Any]): Annotation data, including ordered annotations and matrix of associations.
@@ -39,7 +41,8 @@ class Summary:
         self.graph = graph
 
     def to_csv(self, filepath: str) -> None:
-        """Export significance results to a CSV file.
+        """
+        Export significance results to a CSV file.
 
         Args:
             filepath (str): The path where the CSV file will be saved.
@@ -50,7 +53,8 @@ class Summary:
         logger.info(f"Analysis summary exported to CSV file: {filepath}")
 
     def to_json(self, filepath: str) -> None:
-        """Export significance results to a JSON file.
+        """
+        Export significance results to a JSON file.
 
         Args:
             filepath (str): The path where the JSON file will be saved.
@@ -61,7 +65,8 @@ class Summary:
         logger.info(f"Analysis summary exported to JSON file: {filepath}")
 
     def to_txt(self, filepath: str) -> None:
-        """Export significance results to a text file.
+        """
+        Export significance results to a text file.
 
         Args:
             filepath (str): The path where the text file will be saved.
@@ -74,7 +79,8 @@ class Summary:
         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.
+        """
+        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,
@@ -171,7 +177,8 @@ class Summary:
         return results
 
     def _calculate_qvalues(self, pvals: np.ndarray) -> np.ndarray:
-        """Calculate q-values (FDR) for each row of a p-value matrix.
+        """
+        Calculate q-values (FDR) for each row of a p-value matrix.
 
         Args:
             pvals (np.ndarray): 2D array of p-values.
@@ -190,7 +197,8 @@ class Summary:
         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.
+        """
+        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.
@@ -226,7 +234,8 @@ class Summary:
         )
 
     def _get_annotation_members(self, description: str) -> str:
-        """Retrieve node labels associated with a given annotation description.
+        """
+        Retrieve node labels associated with a given annotation description.
 
         Args:
             description (str): The annotation description.

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

@@ -1,6 +1,6 @@
 """
-risk/network/io
-~~~~~~~~~~~~~~~
+risk/_network/_io
+~~~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -15,14 +15,13 @@ import networkx as nx
 import numpy as np
 import pandas as pd
 
-from risk.log import log_header, logger, params
+from .._log import log_header, logger, params
 
 
-class NetworkIO:
-    """A class for loading, processing, and managing network data.
-
-    The NetworkIO class provides methods to load network data from various formats (e.g., GPickle, NetworkX)
-    and process the network by adjusting node coordinates, calculating edge lengths, and validating graph structure.
+class NetworkAPI:
+    """
+    Public-facing interface for loading and initializing network data.
+    Delegates to the NetworkIO worker class for actual I/O and processing.
     """
 
     def __init__(
@@ -31,22 +30,17 @@ class NetworkIO:
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
     ):
-        """Initialize the NetworkIO class.
+        """
+        Initialize the NetworkAPI.
 
         Args:
-            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.
+            compute_sphere (bool): Whether to map nodes to a sphere. Defaults to True.
+            surface_depth (float): Surface depth for the sphere. Defaults to 0.0.
+            min_edges_per_node (int): Minimum number of edges per node. Defaults to 0.
         """
         self.compute_sphere = compute_sphere
         self.surface_depth = surface_depth
         self.min_edges_per_node = min_edges_per_node
-        # Log the initialization of the NetworkIO class
-        params.log_network(
-            compute_sphere=compute_sphere,
-            surface_depth=surface_depth,
-            min_edges_per_node=min_edges_per_node,
-        )
 
     def load_network_gpickle(
         self,
@@ -55,43 +49,23 @@ class NetworkIO:
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
     ) -> nx.Graph:
-        """Load a network from a GPickle file.
+        """
+        Load a network from a GPickle file via NetworkIO.
 
         Args:
             filepath (str): Path to the GPickle file.
-            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.
-
+            compute_sphere (bool, optional): Override or use API default. Defaults to True.
+            surface_depth (float, optional): Override or use API default. Defaults to 0.0.
+            min_edges_per_node (int, optional): Override or use API default. Defaults to 0.
         Returns:
             nx.Graph: Loaded and processed network.
         """
-        networkio = NetworkIO(
+        io = NetworkIO(
             compute_sphere=compute_sphere,
             surface_depth=surface_depth,
             min_edges_per_node=min_edges_per_node,
         )
-        return networkio._load_network_gpickle(filepath=filepath)
-
-    def _load_network_gpickle(self, filepath: str) -> nx.Graph:
-        """Private method to load a network from a GPickle file.
-
-        Args:
-            filepath (str): Path to the GPickle file.
-
-        Returns:
-            nx.Graph: Loaded and processed network.
-        """
-        filetype = "GPickle"
-        # Log the loading of the GPickle file
-        params.log_network(filetype=filetype, filepath=filepath)
-        self._log_loading_network(filetype, filepath=filepath)
-
-        with open(filepath, "rb") as f:
-            G = pickle.load(f)
-
-        # Initialize the graph
-        return self._initialize_graph(G)
+        return io.load_network_gpickle(filepath=filepath)
 
     def load_network_networkx(
         self,
@@ -100,42 +74,23 @@ class NetworkIO:
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
     ) -> nx.Graph:
-        """Load a NetworkX graph.
+        """
+        Load a NetworkX graph via NetworkIO.
 
         Args:
             network (nx.Graph): A NetworkX graph object.
-            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.
-
+            compute_sphere (bool, optional): Override or use API default. Defaults to True.
+            surface_depth (float, optional): Override or use API default. Defaults to 0.0.
+            min_edges_per_node (int, optional): Override or use API default. Defaults to 0.
         Returns:
-            nx.Graph: Loaded and processed network.
+            nx.Graph: Processed network.
         """
-        networkio = NetworkIO(
+        io = NetworkIO(
             compute_sphere=compute_sphere,
             surface_depth=surface_depth,
             min_edges_per_node=min_edges_per_node,
         )
-        return networkio._load_network_networkx(network=network)
-
-    def _load_network_networkx(self, network: nx.Graph) -> nx.Graph:
-        """Private method to load a NetworkX graph.
-
-        Args:
-            network (nx.Graph): A NetworkX graph object.
-
-        Returns:
-            nx.Graph: Processed network.
-        """
-        filetype = "NetworkX"
-        # Log the loading of the NetworkX graph
-        params.log_network(filetype=filetype)
-        self._log_loading_network(filetype)
-
-        # Important: Make a copy of the network to avoid modifying the original
-        network_copy = copy.deepcopy(network)
-        # Initialize the graph
-        return self._initialize_graph(network_copy)
+        return io.load_network_networkx(network=network)
 
     def load_network_cytoscape(
         self,
@@ -147,40 +102,148 @@ class NetworkIO:
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
     ) -> nx.Graph:
-        """Load a network from a Cytoscape file.
+        """
+        Load a network from a Cytoscape file via NetworkIO.
 
         Args:
             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 "".
-            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.
-
+            compute_sphere (bool, optional): Override or use API default. Defaults to True.
+            surface_depth (float, optional): Override or use API default. Defaults to 0.0.
+            min_edges_per_node (int, optional): Override or use API default. Defaults to 0.
         Returns:
             nx.Graph: Loaded and processed network.
         """
-        networkio = NetworkIO(
+        io = NetworkIO(
             compute_sphere=compute_sphere,
             surface_depth=surface_depth,
             min_edges_per_node=min_edges_per_node,
         )
-        return networkio._load_network_cytoscape(
+        return io.load_network_cytoscape(
             filepath=filepath,
             source_label=source_label,
             target_label=target_label,
             view_name=view_name,
         )
 
-    def _load_network_cytoscape(
+    def load_network_cyjs(
+        self,
+        filepath: str,
+        source_label: str = "source",
+        target_label: str = "target",
+        compute_sphere: bool = True,
+        surface_depth: float = 0.0,
+        min_edges_per_node: int = 0,
+    ) -> nx.Graph:
+        """
+        Load a network from a Cytoscape JSON (.cyjs) file via NetworkIO.
+
+        Args:
+            filepath (str): Path to the Cytoscape JSON file.
+            source_label (str, optional): Source node label. Defaults to "source".
+            target_label (str, optional): Target node label. Defaults to "target".
+            compute_sphere (bool, optional): Override or use API default. Defaults to True.
+            surface_depth (float, optional): Override or use API default. Defaults to 0.0.
+            min_edges_per_node (int, optional): Override or use API default. Defaults to 0.
+        Returns:
+            nx.Graph: Loaded and processed network.
+        """
+        io = NetworkIO(
+            compute_sphere=compute_sphere,
+            surface_depth=surface_depth,
+            min_edges_per_node=min_edges_per_node,
+        )
+        return io.load_network_cyjs(
+            filepath=filepath,
+            source_label=source_label,
+            target_label=target_label,
+        )
+
+
+class NetworkIO:
+    """
+    A class for loading, processing, and managing network data.
+
+    The NetworkIO class provides methods to load network data from various formats (e.g., GPickle, NetworkX)
+    and process the network by adjusting node coordinates, calculating edge lengths, and validating graph structure.
+    """
+
+    def __init__(
+        self,
+        compute_sphere: bool = True,
+        surface_depth: float = 0.0,
+        min_edges_per_node: int = 0,
+    ):
+        """
+        Initialize the NetworkIO class.
+
+        Args:
+            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.
+        """
+        self.compute_sphere = compute_sphere
+        self.surface_depth = surface_depth
+        self.min_edges_per_node = min_edges_per_node
+        # Log the initialization of the NetworkIO class
+        params.log_network(
+            compute_sphere=compute_sphere,
+            surface_depth=surface_depth,
+            min_edges_per_node=min_edges_per_node,
+        )
+
+    def load_network_gpickle(self, filepath: str) -> nx.Graph:
+        """
+        Load a network from a GPickle file.
+
+        Args:
+            filepath (str): Path to the GPickle file.
+
+        Returns:
+            nx.Graph: Loaded and processed network.
+        """
+        filetype = "GPickle"
+        # Log the loading of the GPickle file
+        params.log_network(filetype=filetype, filepath=filepath)
+        self._log_loading_network(filetype, filepath=filepath)
+
+        with open(filepath, "rb") as f:
+            G = pickle.load(f)
+
+        # Initialize the graph
+        return self._initialize_graph(G)
+
+    def load_network_networkx(self, network: nx.Graph) -> nx.Graph:
+        """
+        Load a NetworkX graph.
+
+        Args:
+            network (nx.Graph): A NetworkX graph object.
+
+        Returns:
+            nx.Graph: Processed network.
+        """
+        filetype = "NetworkX"
+        # Log the loading of the NetworkX graph
+        params.log_network(filetype=filetype)
+        self._log_loading_network(filetype)
+
+        # Important: Make a copy of the network to avoid modifying the original
+        network_copy = copy.deepcopy(network)
+        # Initialize the graph
+        return self._initialize_graph(network_copy)
+
+    def load_network_cytoscape(
         self,
         filepath: str,
         source_label: str = "source",
         target_label: str = "target",
         view_name: str = "",
     ) -> nx.Graph:
-        """Private method to load a network from a Cytoscape file.
+        """
+        Load a network from a Cytoscape file.
 
         Args:
             filepath (str): Path to the Cytoscape file.
@@ -307,41 +370,9 @@ class NetworkIO:
             if os.path.exists(tmp_dir):
                 shutil.rmtree(tmp_dir)
 
-    def load_network_cyjs(
-        self,
-        filepath: str,
-        source_label: str = "source",
-        target_label: str = "target",
-        compute_sphere: bool = True,
-        surface_depth: float = 0.0,
-        min_edges_per_node: int = 0,
-    ) -> nx.Graph:
-        """Load a network from a Cytoscape JSON (.cyjs) file.
-
-        Args:
-            filepath (str): Path to the Cytoscape JSON file.
-            source_label (str, optional): Source node label. Default is "source".
-            target_label (str, optional): Target node label. Default is "target".
-            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.
-
-        Returns:
-            NetworkX graph: Loaded and processed network.
+    def load_network_cyjs(self, filepath, source_label="source", target_label="target"):
         """
-        networkio = NetworkIO(
-            compute_sphere=compute_sphere,
-            surface_depth=surface_depth,
-            min_edges_per_node=min_edges_per_node,
-        )
-        return networkio._load_network_cyjs(
-            filepath=filepath,
-            source_label=source_label,
-            target_label=target_label,
-        )
-
-    def _load_network_cyjs(self, filepath, source_label="source", target_label="target"):
-        """Private method to load a network from a Cytoscape JSON (.cyjs) file.
+        Load a network from a Cytoscape JSON (.cyjs) file.
 
         Args:
             filepath (str): Path to the Cytoscape JSON file.
@@ -396,7 +427,8 @@ class NetworkIO:
         return self._initialize_graph(G)
 
     def _initialize_graph(self, G: nx.Graph) -> nx.Graph:
-        """Initialize the graph by processing and validating its nodes and edges.
+        """
+        Initialize the graph by processing and validating its nodes and edges.
 
         Args:
             G (nx.Graph): The input NetworkX graph.
@@ -414,7 +446,8 @@ class NetworkIO:
         return G
 
     def _remove_invalid_graph_properties(self, G: nx.Graph) -> None:
-        """Remove invalid properties from the graph, including self-loops, nodes with fewer edges than
+        """
+        Remove invalid properties from the graph, including self-loops, nodes with fewer edges than
         the threshold, and isolated nodes.
 
         Args:
@@ -449,7 +482,8 @@ class NetworkIO:
         logger.debug(f"Final edge count: {num_final_edges}")
 
     def _assign_edge_weights(self, G: nx.Graph) -> None:
-        """Assign default edge weights to the graph.
+        """
+        Assign default edge weights to the graph.
 
         Args:
             G (nx.Graph): A NetworkX graph object.
@@ -459,7 +493,8 @@ class NetworkIO:
         nx.set_edge_attributes(G, default_weight, "weight")
 
     def _validate_nodes(self, G: nx.Graph) -> None:
-        """Validate the graph structure and attributes with attribute fallback for positions and labels.
+        """
+        Validate the graph structure and attributes with attribute fallback for positions and labels.
 
         Args:
             G (nx.Graph): A NetworkX graph object.
@@ -519,7 +554,8 @@ class NetworkIO:
             )
 
     def _assign_edge_lengths(self, G: nx.Graph) -> None:
-        """Prepare the network by adjusting surface depth and calculating edge lengths.
+        """
+        Prepare the network by adjusting surface depth and calculating edge lengths.
 
         Args:
             G (nx.Graph): The input network graph.
@@ -537,7 +573,8 @@ class NetworkIO:
         compute_sphere: bool = True,
         surface_depth: float = 0.0,
     ) -> nx.Graph:
-        """Prepare the graph by normalizing coordinates and optionally mapping nodes to a sphere.
+        """
+        Prepare the graph by normalizing coordinates and optionally mapping nodes to a sphere.
 
         Args:
             G (nx.Graph): The input graph.
@@ -558,7 +595,8 @@ class NetworkIO:
         return G_depth
 
     def _calculate_and_set_edge_lengths(self, G: nx.Graph, compute_sphere: bool) -> None:
-        """Compute and assign edge lengths in the graph.
+        """
+        Compute and assign edge lengths in the graph.
 
         Args:
             G (nx.Graph): The input graph.
@@ -592,7 +630,8 @@ class NetworkIO:
             G.edges[u, v]["length"] = distance
 
     def _map_to_sphere(self, G: nx.Graph) -> None:
-        """Map the x and y coordinates of graph nodes onto a 3D sphere.
+        """
+        Map the x and y coordinates of graph nodes onto a 3D sphere.
 
         Args:
             G (nx.Graph): The input graph with nodes having 'x' and 'y' coordinates.
@@ -616,7 +655,8 @@ class NetworkIO:
         nx.set_node_attributes(G, xyz_coords)
 
     def _normalize_graph_coordinates(self, G: nx.Graph) -> None:
-        """Normalize the x and y coordinates of the nodes in the graph to the [0, 1] range.
+        """
+        Normalize the x and y coordinates of the nodes in the graph to the [0, 1] range.
 
         Args:
             G (nx.Graph): The input graph with nodes having 'x' and 'y' coordinates.
@@ -633,7 +673,8 @@ class NetworkIO:
             G.nodes[node]["x"], G.nodes[node]["y"] = normalized_xy[i]
 
     def _create_depth(self, G: nx.Graph, surface_depth: float = 0.0) -> nx.Graph:
-        """Adjust the 'z' attribute of each node based on the subcluster strengths and normalized surface depth.
+        """
+        Adjust the 'z' attribute of each node based on the subcluster strengths and normalized surface depth.
 
         Args:
             G (nx.Graph): The input graph.
@@ -677,7 +718,8 @@ class NetworkIO:
         filetype: str,
         filepath: str = "",
     ) -> None:
-        """Log the loading of the network with relevant parameters.
+        """
+        Log the loading of the network with relevant parameters.
 
         Args:
             filetype (str): The type of the file being loaded (e.g., 'CSV', 'JSON').

risk/_network/_plotter/__init__.py

@@ -0,0 +1,6 @@
+"""
+risk/_network/_plotter
+~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from ._api import PlotterAPI

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

@@ -1,19 +1,20 @@
 """
-risk/network/plotter/api
-~~~~~~~~~~~~~~~~~~~~~~~~
+risk/_network/_plotter/_api
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import List, Tuple, Union
 
 import numpy as np
 
-from risk.log import log_header
-from risk.network.graph.graph import Graph
-from risk.network.plotter.plotter import Plotter
+from ..._log import log_header
+from .._graph import Graph
+from ._plotter import Plotter
 
 
 class PlotterAPI:
-    """Handles the loading of network plotter objects.
+    """
+    Handles the loading of network plotter objects.
 
     The PlotterAPI class provides methods to load and configure Plotter objects for plotting network graphs.
     """
@@ -29,7 +30,8 @@ class PlotterAPI:
         background_alpha: Union[float, None] = 1.0,
         pad: float = 0.3,
     ) -> Plotter:
-        """Get a Plotter object for plotting.
+        """
+        Get a Plotter object for plotting.
 
         Args:
             graph (Graph): The graph to plot.