risk-network 0.0.9b24__tar.gz → 0.0.9b26__tar.gz

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: risk-network
-Version: 0.0.9b24
+Version: 0.0.9b26
 Summary: A Python package for biological network analysis
 Author: Ira Horecka
 Author-email: Ira Horecka <ira89@icloud.com>

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/__init__.py

@@ -7,4 +7,4 @@ RISK: Regional Inference of Significant Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.9-beta.24"
+__version__ = "0.0.9-beta.26"

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/annotations/annotations.py

@@ -16,6 +16,7 @@ from nltk.tokenize import word_tokenize
 from nltk.corpus import stopwords
 
 from risk.log import logger
+from scipy.sparse import csr_matrix
 
 
 def _setup_nltk():
@@ -47,17 +48,15 @@ def load_annotations(
         annotations_input (Dict[str, Any]): A dictionary with annotations.
         min_nodes_per_term (int, optional): The minimum number of network nodes required for each annotation
             term to be included. Defaults to 2.
+        use_sparse (bool, optional): Whether to return the annotations matrix as a sparse matrix. Defaults to True.
 
     Returns:
-        Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the binary annotations matrix.
+        Dict[str, Any]: A dictionary containing ordered nodes, ordered annotations, and the sparse binary annotations
+            matrix.
 
     Raises:
         ValueError: If no annotations are found for the nodes in the network.
         ValueError: If no annotations have at least min_nodes_per_term nodes in the network.
-
-    Comment:
-        This function should be optimized to handle large networks and annotations efficiently. An attempt
-        to use sparse matrices did not yield significant performance improvements, so it was not implemented.
     """
     # Flatten the dictionary to a list of tuples for easier DataFrame creation
     flattened_annotations = [
@@ -78,7 +77,6 @@ def load_annotations(
         raise ValueError("No terms found in the annotation file for the nodes in the network.")
 
     # Filter out annotations with fewer than min_nodes_per_term occurrences
-    # This assists in reducing noise and focusing on more relevant annotations for statistical analysis
     num_terms_before_filtering = annotations_pivot.shape[1]
     annotations_pivot = annotations_pivot.loc[
         :, (annotations_pivot.sum(axis=0) >= min_nodes_per_term)
@@ -96,13 +94,15 @@ def load_annotations(
     # Extract ordered nodes and annotations
     ordered_nodes = tuple(annotations_pivot.index)
     ordered_annotations = tuple(annotations_pivot.columns)
-    # Convert the annotations_pivot matrix to a numpy array and ensure it's binary
-    annotations_pivot_numpy = (annotations_pivot.fillna(0).to_numpy() > 0).astype(int)
+    # Convert the annotations_pivot matrix to a numpy array or sparse matrix
+    annotations_pivot_binary = (annotations_pivot.fillna(0).to_numpy() > 0).astype(int)
+    # Convert the binary annotations matrix to a sparse matrix
+    annotations_pivot_binary = csr_matrix(annotations_pivot_binary)
 
     return {
         "ordered_nodes": ordered_nodes,
         "ordered_annotations": ordered_annotations,
-        "matrix": annotations_pivot_numpy,
+        "matrix": annotations_pivot_binary,
     }
 
 

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/neighborhoods/__init__.py

@@ -4,5 +4,5 @@ risk/neighborhoods
 """
 
 from risk.neighborhoods.domains import define_domains, trim_domains
-from risk.neighborhoods.io import NeighborhoodsIO
+from risk.neighborhoods.api import NeighborhoodsAPI
 from risk.neighborhoods.neighborhoods import process_neighborhoods

risk_network-0.0.9b24/risk/neighborhoods/io.py → risk_network-0.0.9b26/risk/neighborhoods/api.py

@@ -1,6 +1,6 @@
 """
-risk/neighborhoods/io
-~~~~~~~~~~~~~~~~~~~~~
+risk/neighborhoods/api
+~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -8,6 +8,7 @@ from typing import Any, Dict, List, Tuple, Union
 
 import networkx as nx
 import numpy as np
+from scipy.sparse import csr_matrix
 
 from risk.log import logger, log_header, params
 from risk.neighborhoods.neighborhoods import get_network_neighborhoods
@@ -21,10 +22,10 @@ from risk.stats import (
 )
 
 
-class NeighborhoodsIO:
+class NeighborhoodsAPI:
     """Handles the loading of statistical results and annotation significance for neighborhoods.
 
-    The NeighborhoodsIO class provides methods to load neighborhood results from statistical tests.
+    The NeighborhoodsAPI class provides methods to load neighborhood results from statistical tests.
     """
 
     def __init__() -> None:
@@ -86,7 +87,7 @@ class NeighborhoodsIO:
         null_distribution: str = "network",
         random_seed: int = 888,
     ) -> Dict[str, Any]:
-        """Load significant neighborhoods for the network using the Chi-squared test.
+        """Load significant neighborhoods for the network using the chi-squared test.
 
         Args:
             network (nx.Graph): The network graph.
@@ -396,12 +397,11 @@ class NeighborhoodsIO:
         leiden_resolution: float = 1.0,
         fraction_shortest_edges: Union[float, List, Tuple, np.ndarray] = 0.5,
         random_seed: int = 888,
-    ) -> np.ndarray:
+    ) -> csr_matrix:
         """Load significant neighborhoods for the network.
 
         Args:
             network (nx.Graph): The network graph.
-            annotations (pd.DataFrame): The matrix of annotations associated with the network.
             distance_metric (str, List, Tuple, or np.ndarray, optional): The distance metric(s) to use. Can be a string for one
                 metric or a list/tuple/ndarray of metrics ('greedy_modularity', 'louvain', 'leiden', 'label_propagation',
                 'markov_clustering', 'walktrap', 'spinglass'). Defaults to 'louvain'.
@@ -413,7 +413,7 @@ class NeighborhoodsIO:
             random_seed (int, optional): Seed for random number generation. Defaults to 888.
 
         Returns:
-            np.ndarray: Neighborhood matrix calculated based on the selected distance metric.
+            csr_matrix: Sparse neighborhood matrix calculated based on the selected distance metric.
         """
         # Display the chosen distance metric
         if distance_metric == "louvain":
@@ -422,12 +422,13 @@ class NeighborhoodsIO:
             for_print_distance_metric = f"leiden (resolution={leiden_resolution})"
         else:
             for_print_distance_metric = distance_metric
+
         # Log and display neighborhood settings
         logger.debug(f"Distance metric: '{for_print_distance_metric}'")
         logger.debug(f"Edge length threshold: {fraction_shortest_edges}")
         logger.debug(f"Random seed: {random_seed}")
 
-        # Compute neighborhoods based on the network and distance metric
+        # Compute neighborhoods
         neighborhoods = get_network_neighborhoods(
             network,
             distance_metric,
@@ -437,5 +438,9 @@ class NeighborhoodsIO:
             random_seed=random_seed,
         )
 
-        # Return the computed neighborhoods
+        # Ensure the neighborhood matrix is in sparse format
+        if not isinstance(neighborhoods, csr_matrix):
+            neighborhoods = csr_matrix(neighborhoods)
+
+        # Return the sparse neighborhood matrix
         return neighborhoods

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/neighborhoods/domains.py

@@ -39,6 +39,9 @@ def define_domains(
         pd.DataFrame: DataFrame with the primary domain for each node.
     """
     try:
+        if linkage_criterion == "off":
+            raise ValueError("Clustering is turned off.")
+
         # Transpose the matrix to cluster annotations
         m = significant_neighborhoods_significance[:, top_annotations["significant_annotations"]].T
         # Safeguard the matrix by replacing NaN, Inf, and -Inf values
@@ -62,9 +65,14 @@ def define_domains(
     except ValueError:
         # If a ValueError is encountered, handle it by assigning unique domains
         n_rows = len(top_annotations)
-        logger.error(
-            f"Error encountered. Skipping clustering and assigning {n_rows} unique domains."
-        )
+        if linkage_criterion == "off":
+            logger.warning(
+                f"Clustering is turned off. Skipping clustering and assigning {n_rows} unique domains."
+            )
+        else:
+            logger.error(
+                f"Error encountered. Skipping clustering and assigning {n_rows} unique domains."
+            )
         top_annotations["domain"] = range(1, n_rows + 1)  # Assign unique domains
 
     # Create DataFrames to store domain information

risk_network-0.0.9b26/risk/network/__init__.py

@@ -0,0 +1,6 @@
+"""
+risk/network
+~~~~~~~~~~~~
+"""
+
+from risk.network.io import NetworkIO

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/network/graph/__init__.py

@@ -3,4 +3,4 @@ risk/network/graph
 ~~~~~~~~~~~~~~~~~~
 """
 
-from risk.network.graph.io import GraphIO
+from risk.network.graph.api import GraphAPI

risk_network-0.0.9b24/risk/network/graph/io.py → risk_network-0.0.9b26/risk/network/graph/api.py

@@ -1,6 +1,6 @@
 """
-risk/network/graph/io
-~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
 """
 
 import copy
@@ -20,10 +20,10 @@ from risk.network.graph.network import NetworkGraph
 from risk.stats import calculate_significance_matrices
 
 
-class GraphIO:
+class GraphAPI:
     """Handles the loading of network graphs and associated data.
 
-    The GraphIO class provides methods to load and process network graphs, annotations, and neighborhoods.
+    The GraphAPI class provides methods to load and process network graphs, annotations, and neighborhoods.
     """
 
     def __init__() -> None:

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/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-0.0.9b26/risk/network/plotter/__init__.py

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

risk_network-0.0.9b24/risk/network/plot/io.py → risk_network-0.0.9b26/risk/network/plotter/api.py

@@ -1,6 +1,6 @@
 """
-risk/network/graph/io
-~~~~~~~~~~~~~~~~~~~~~
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from typing import List, Tuple, Union
@@ -9,13 +9,13 @@ import numpy as np
 
 from risk.log import log_header
 from risk.network.graph.network import NetworkGraph
-from risk.network.plot.network import NetworkPlotter
+from risk.network.plotter.network import NetworkPlotter
 
 
-class PlotterIO:
+class PlotterAPI:
     """Handles the loading of network plotter objects.
 
-    The PlotterIO class provides methods to load and configure NetworkPlotter objects for plotting network graphs.
+    The PlotterAPI class provides methods to load and configure NetworkPlotter objects for plotting network graphs.
     """
 
     def __init__() -> None:

{risk_network-0.0.9b24/risk/network/plot → risk_network-0.0.9b26/risk/network/plotter}/canvas.py

@@ -10,8 +10,8 @@ import numpy as np
 
 from risk.log import params
 from risk.network.graph.network import NetworkGraph
-from risk.network.plot.utils.colors import to_rgba
-from risk.network.plot.utils.layout import calculate_bounding_box
+from risk.network.plotter.utils.colors import to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
 
 
 class Canvas:

{risk_network-0.0.9b24/risk/network/plot → risk_network-0.0.9b26/risk/network/plotter}/contour.py

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

{risk_network-0.0.9b24/risk/network/plot → risk_network-0.0.9b26/risk/network/plotter}/labels.py

@@ -12,8 +12,8 @@ import pandas as pd
 
 from risk.log import params
 from risk.network.graph.network 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.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-0.0.9b24/risk/network/plot → risk_network-0.0.9b26/risk/network/plotter}/network.py

@@ -11,11 +11,11 @@ import numpy as np
 
 from risk.log import params
 from risk.network.graph.network import NetworkGraph
-from risk.network.plot.canvas import Canvas
-from risk.network.plot.contour import Contour
-from risk.network.plot.labels import Labels
-from risk.network.plot.utils.colors import get_domain_colors, to_rgba
-from risk.network.plot.utils.layout import calculate_bounding_box
+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:

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/risk.py

@@ -3,13 +3,16 @@ risk/risk
 ~~~~~~~~~
 """
 
+from risk.network import NetworkIO
 from risk.annotations import AnnotationsIO
+from risk.neighborhoods import NeighborhoodsAPI
+from risk.network.graph import GraphAPI
+from risk.network.plotter import PlotterAPI
+
 from risk.log import params, set_global_verbosity
-from risk.neighborhoods import NeighborhoodsIO
-from risk.network import GraphIO, NetworkIO, PlotterIO
 
 
-class RISK(NetworkIO, AnnotationsIO, NeighborhoodsIO, GraphIO, PlotterIO):
+class RISK(NetworkIO, AnnotationsIO, NeighborhoodsAPI, GraphAPI, PlotterAPI):
     """RISK: A class for network analysis and visualization.
 
     The RISK class integrates functionalities for loading networks, processing annotations,

risk_network-0.0.9b26/risk/stats/binom.py

@@ -0,0 +1,51 @@
+"""
+risk/stats/binomial
+~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict
+
+from scipy.sparse import csr_matrix
+from scipy.stats import binom
+
+
+def compute_binom_test(
+    neighborhoods: csr_matrix,
+    annotations: csr_matrix,
+    null_distribution: str = "network",
+) -> Dict[str, Any]:
+    """Compute Binomial test for enrichment and depletion in neighborhoods with selectable null distribution.
+
+    Args:
+        neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
+        annotations (csr_matrix): Sparse binary matrix representing annotations.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+
+    Returns:
+        Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+    """
+    # Get the total number of nodes in the network
+    total_nodes = neighborhoods.shape[1]
+
+    # Compute sums (remain sparse here)
+    neighborhood_sizes = neighborhoods.sum(axis=1)  # Row sums
+    annotation_totals = annotations.sum(axis=0)  # Column sums
+    # Compute probabilities (convert to dense)
+    if null_distribution == "network":
+        p_values = (annotation_totals / total_nodes).A.flatten()  # Dense 1D array
+    elif null_distribution == "annotations":
+        p_values = (annotation_totals / annotations.sum()).A.flatten()  # Dense 1D array
+    else:
+        raise ValueError(
+            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+        )
+
+    # Observed counts (sparse matrix multiplication)
+    annotated_counts = neighborhoods @ annotations  # Sparse result
+    annotated_counts_dense = annotated_counts.toarray()  # Convert for dense operations
+
+    # Compute enrichment and depletion p-values
+    enrichment_pvals = 1 - binom.cdf(annotated_counts_dense - 1, neighborhood_sizes.A, p_values)
+    depletion_pvals = binom.cdf(annotated_counts_dense, neighborhood_sizes.A, p_values)
+
+    return {"enrichment_pvals": enrichment_pvals, "depletion_pvals": depletion_pvals}

{risk_network-0.0.9b24 → risk_network-0.0.9b26}/risk/stats/chi2.py

@@ -4,51 +4,63 @@ risk/stats/chi2
 """
 
 from typing import Any, Dict
+
 import numpy as np
+from scipy.sparse import csr_matrix
 from scipy.stats import chi2
 
 
 def compute_chi2_test(
-    neighborhoods: np.ndarray, annotations: np.ndarray, null_distribution: str = "network"
+    neighborhoods: csr_matrix,
+    annotations: csr_matrix,
+    null_distribution: str = "network",
 ) -> Dict[str, Any]:
     """Compute chi-squared test for enrichment and depletion in neighborhoods with selectable null distribution.
 
     Args:
-        neighborhoods (np.ndarray): Binary matrix representing neighborhoods.
-        annotations (np.ndarray): Binary matrix representing annotations.
+        neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
+        annotations (csr_matrix): Sparse binary matrix representing annotations.
         null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
 
     Returns:
         Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
     """
-    # Get the total number of nodes in the network
+    # Total number of nodes in the network
     total_node_count = neighborhoods.shape[0]
 
     if null_distribution == "network":
         # Case 1: Use all nodes as the background
         background_population = total_node_count
-        neighborhood_sums = np.sum(
-            neighborhoods, axis=0, keepdims=True
-        ).T  # Column sums of neighborhoods
-        annotation_sums = np.sum(annotations, axis=0, keepdims=True)  # Column sums of annotations
+        neighborhood_sums = neighborhoods.sum(axis=0)  # Column sums of neighborhoods
+        annotation_sums = annotations.sum(axis=0)  # Column sums of annotations
     elif null_distribution == "annotations":
         # Case 2: Only consider nodes with at least one annotation
-        annotated_nodes = np.sum(annotations, axis=1) > 0
-        background_population = np.sum(annotated_nodes)
-        neighborhood_sums = np.sum(neighborhoods[annotated_nodes], axis=0, keepdims=True).T
-        annotation_sums = np.sum(annotations[annotated_nodes], axis=0, keepdims=True)
+        annotated_nodes = (
+            np.ravel(annotations.sum(axis=1)) > 0
+        )  # Row-wise sum to filter nodes with annotations
+        background_population = annotated_nodes.sum()  # Total number of annotated nodes
+        neighborhood_sums = neighborhoods[annotated_nodes].sum(
+            axis=0
+        )  # Neighborhood sums for annotated nodes
+        annotation_sums = annotations[annotated_nodes].sum(
+            axis=0
+        )  # Annotation sums for annotated nodes
     else:
         raise ValueError(
             "Invalid null_distribution value. Choose either 'network' or 'annotations'."
         )
 
+    # Convert to dense arrays for downstream computations
+    neighborhood_sums = np.asarray(neighborhood_sums).reshape(-1, 1)  # Ensure column vector shape
+    annotation_sums = np.asarray(annotation_sums).reshape(1, -1)  # Ensure row vector shape
+
     # Observed values: number of annotated nodes in each neighborhood
     observed = neighborhoods.T @ annotations  # Shape: (neighborhoods, annotations)
     # Expected values under the null
     expected = (neighborhood_sums @ annotation_sums) / background_population
     # Chi-squared statistic: sum((observed - expected)^2 / expected)
     with np.errstate(divide="ignore", invalid="ignore"):  # Handle divide-by-zero
-        chi2_stat = np.where(expected > 0, (observed - expected) ** 2 / expected, 0)
+        chi2_stat = np.where(expected > 0, np.power(observed - expected, 2) / expected, 0)
 
     # Compute p-values for enrichment (upper tail) and depletion (lower tail)
     enrichment_pvals = chi2.sf(chi2_stat, df=1)  # Survival function for upper tail

risk_network-0.0.9b26/risk/stats/hypergeom.py

@@ -0,0 +1,64 @@
+"""
+risk/stats/hypergeom
+~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict
+
+import numpy as np
+from scipy.sparse import csr_matrix
+from scipy.stats import hypergeom
+
+
+def compute_hypergeom_test(
+    neighborhoods: csr_matrix,
+    annotations: csr_matrix,
+    null_distribution: str = "network",
+) -> Dict[str, Any]:
+    """
+    Compute hypergeometric test for enrichment and depletion in neighborhoods with selectable null distribution.
+
+    Args:
+        neighborhoods (csr_matrix): Sparse binary matrix representing neighborhoods.
+        annotations (csr_matrix): Sparse binary matrix representing annotations.
+        null_distribution (str, optional): Type of null distribution ('network' or 'annotations'). Defaults to "network".
+
+    Returns:
+        Dict[str, Any]: Dictionary containing depletion and enrichment p-values.
+    """
+    # Get the total number of nodes in the network
+    total_nodes = neighborhoods.shape[1]
+
+    # Compute sums
+    neighborhood_sums = neighborhoods.sum(axis=0).A.flatten()  # Convert to dense array
+    annotation_sums = annotations.sum(axis=0).A.flatten()  # Convert to dense array
+
+    if null_distribution == "network":
+        background_population = total_nodes
+    elif null_distribution == "annotations":
+        annotated_nodes = annotations.sum(axis=1).A.flatten() > 0  # Boolean mask
+        background_population = annotated_nodes.sum()
+        neighborhood_sums = neighborhoods[annotated_nodes].sum(axis=0).A.flatten()
+        annotation_sums = annotations[annotated_nodes].sum(axis=0).A.flatten()
+    else:
+        raise ValueError(
+            "Invalid null_distribution value. Choose either 'network' or 'annotations'."
+        )
+
+    # Observed counts
+    annotated_in_neighborhood = neighborhoods.T @ annotations  # Sparse result
+    annotated_in_neighborhood = annotated_in_neighborhood.toarray()  # Convert to dense
+    # Align shapes for broadcasting
+    neighborhood_sums = neighborhood_sums.reshape(-1, 1)
+    annotation_sums = annotation_sums.reshape(1, -1)
+    background_population = np.array(background_population).reshape(1, 1)
+
+    # Compute hypergeometric p-values
+    depletion_pvals = hypergeom.cdf(
+        annotated_in_neighborhood, background_population, annotation_sums, neighborhood_sums
+    )
+    enrichment_pvals = hypergeom.sf(
+        annotated_in_neighborhood - 1, background_population, annotation_sums, neighborhood_sums
+    )
+
+    return {"depletion_pvals": depletion_pvals, "enrichment_pvals": enrichment_pvals}