risk-network 0.0.12b0__py3-none-any.whl → 0.0.12b2__py3-none-any.whl

risk/network/graph/api.py

@@ -0,0 +1,200 @@
+"""
+risk/network/graph/api
+~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+import copy
+from typing import Any, Dict, Union
+
+import networkx as nx
+import pandas as pd
+
+from risk.annotations import define_top_annotations
+from risk.log import log_header, logger, params
+from risk.neighborhoods import (
+    define_domains,
+    process_neighborhoods,
+    trim_domains,
+)
+from risk.network.graph.graph import Graph
+from risk.network.graph.stats import calculate_significance_matrices
+
+
+class GraphAPI:
+    """Handles the loading of network graphs and associated data.
+
+    The GraphAPI class provides methods to load and process network graphs, annotations, and neighborhoods.
+    """
+
+    def __init__() -> None:
+        pass
+
+    def load_graph(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        tail: str = "right",
+        pval_cutoff: float = 0.01,
+        fdr_cutoff: float = 0.9999,
+        impute_depth: int = 0,
+        prune_threshold: float = 0.0,
+        linkage_criterion: str = "distance",
+        linkage_method: str = "average",
+        linkage_metric: str = "yule",
+        linkage_threshold: Union[float, str] = 0.2,
+        min_cluster_size: int = 5,
+        max_cluster_size: int = 1000,
+    ) -> Graph:
+        """Load and process the network graph, defining top annotations and domains.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            tail (str, optional): Type of significance tail ("right", "left", "both"). Defaults to "right".
+            pval_cutoff (float, optional): p-value cutoff for significance. Defaults to 0.01.
+            fdr_cutoff (float, optional): FDR cutoff for significance. Defaults to 0.9999.
+            impute_depth (int, optional): Depth for imputing neighbors. Defaults to 0.
+            prune_threshold (float, optional): Distance threshold for pruning neighbors. Defaults to 0.0.
+            linkage_criterion (str, optional): Clustering criterion for defining domains. Defaults to "distance".
+            linkage_method (str, optional): Clustering method to use. Choose "auto" to optimize. Defaults to "average".
+            linkage_metric (str, optional): Metric to use for calculating distances. Choose "auto" to optimize.
+                Defaults to "yule".
+            linkage_threshold (float, str, optional): Threshold for clustering. Choose "auto" to optimize.
+                Defaults to 0.2.
+            min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
+            max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
+
+        Returns:
+            Graph: A fully initialized and processed Graph object.
+        """
+        # Log the parameters and display headers
+        log_header("Finding significant neighborhoods")
+        params.log_graph(
+            tail=tail,
+            pval_cutoff=pval_cutoff,
+            fdr_cutoff=fdr_cutoff,
+            impute_depth=impute_depth,
+            prune_threshold=prune_threshold,
+            linkage_criterion=linkage_criterion,
+            linkage_method=linkage_method,
+            linkage_metric=linkage_metric,
+            linkage_threshold=linkage_threshold,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )
+
+        # Make a copy of the network to avoid modifying the original
+        network = copy.deepcopy(network)
+
+        logger.debug(f"p-value cutoff: {pval_cutoff}")
+        logger.debug(f"FDR BH cutoff: {fdr_cutoff}")
+        logger.debug(
+            f"Significance tail: '{tail}' ({'enrichment' if tail == 'right' else 'depletion' if tail == 'left' else 'both'})"
+        )
+        # Calculate significant neighborhoods based on the provided parameters
+        significant_neighborhoods = calculate_significance_matrices(
+            neighborhoods["depletion_pvals"],
+            neighborhoods["enrichment_pvals"],
+            tail=tail,
+            pval_cutoff=pval_cutoff,
+            fdr_cutoff=fdr_cutoff,
+        )
+
+        log_header("Processing neighborhoods")
+        # Process neighborhoods by imputing and pruning based on the given settings
+        processed_neighborhoods = process_neighborhoods(
+            network=network,
+            neighborhoods=significant_neighborhoods,
+            impute_depth=impute_depth,
+            prune_threshold=prune_threshold,
+        )
+
+        log_header("Finding top annotations")
+        logger.debug(f"Min cluster size: {min_cluster_size}")
+        logger.debug(f"Max cluster size: {max_cluster_size}")
+        # Define top annotations based on processed neighborhoods
+        top_annotations = self._define_top_annotations(
+            network=network,
+            annotations=annotations,
+            neighborhoods=processed_neighborhoods,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )
+
+        log_header("Optimizing distance threshold for domains")
+        # Extract the significant significance matrix from the neighborhoods data
+        significant_neighborhoods_significance = processed_neighborhoods[
+            "significant_significance_matrix"
+        ]
+        # Define domains in the network using the specified clustering settings
+        domains = define_domains(
+            top_annotations=top_annotations,
+            significant_neighborhoods_significance=significant_neighborhoods_significance,
+            linkage_criterion=linkage_criterion,
+            linkage_method=linkage_method,
+            linkage_metric=linkage_metric,
+            linkage_threshold=linkage_threshold,
+        )
+        # Trim domains and top annotations based on cluster size constraints
+        domains, trimmed_domains = trim_domains(
+            domains=domains,
+            top_annotations=top_annotations,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )
+
+        # Prepare node mapping and significance sums for the final Graph object
+        ordered_nodes = annotations["ordered_nodes"]
+        node_label_to_id = dict(zip(ordered_nodes, range(len(ordered_nodes))))
+        node_significance_sums = processed_neighborhoods["node_significance_sums"]
+
+        # Return the fully initialized Graph object
+        return Graph(
+            network=network,
+            annotations=annotations,
+            neighborhoods=neighborhoods,
+            domains=domains,
+            trimmed_domains=trimmed_domains,
+            node_label_to_node_id_map=node_label_to_id,
+            node_significance_sums=node_significance_sums,
+        )
+
+    def _define_top_annotations(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        min_cluster_size: int = 5,
+        max_cluster_size: int = 1000,
+    ) -> pd.DataFrame:
+        """Define top annotations for the network.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): Annotations data for the network.
+            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            min_cluster_size (int, optional): Minimum size for clusters. Defaults to 5.
+            max_cluster_size (int, optional): Maximum size for clusters. Defaults to 1000.
+
+        Returns:
+            Dict[str, Any]: Top annotations identified within the network.
+        """
+        # Extract necessary data from annotations and neighborhoods
+        ordered_annotations = annotations["ordered_annotations"]
+        neighborhood_significance_sums = neighborhoods["neighborhood_significance_counts"]
+        significant_significance_matrix = neighborhoods["significant_significance_matrix"]
+        significant_binary_significance_matrix = neighborhoods[
+            "significant_binary_significance_matrix"
+        ]
+        # Call external function to define top annotations
+        return define_top_annotations(
+            network=network,
+            ordered_annotation_labels=ordered_annotations,
+            neighborhood_significance_sums=neighborhood_significance_sums,
+            significant_significance_matrix=significant_significance_matrix,
+            significant_binary_significance_matrix=significant_binary_significance_matrix,
+            min_cluster_size=min_cluster_size,
+            max_cluster_size=max_cluster_size,
+        )

risk/network/graph/graph.py

@@ -0,0 +1,274 @@
+"""
+risk/network/graph/graph
+~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from collections import defaultdict
+from typing import Any, Dict, List
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from risk.network.graph.summary import Summary
+
+
+class Graph:
+    """A class to represent a network graph and process its nodes and edges.
+
+    The Graph class provides functionality to handle and manipulate a network graph,
+    including managing domains, annotations, and node significance data. It also includes methods
+    for transforming and mapping graph coordinates, as well as generating colors based on node
+    significance.
+    """
+
+    def __init__(
+        self,
+        network: nx.Graph,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        domains: pd.DataFrame,
+        trimmed_domains: pd.DataFrame,
+        node_label_to_node_id_map: Dict[str, Any],
+        node_significance_sums: np.ndarray,
+    ):
+        """Initialize the Graph object.
+
+        Args:
+            network (nx.Graph): The network graph.
+            annotations (Dict[str, Any]): The annotations associated with the network.
+            neighborhoods (Dict[str, Any]): Neighborhood significance data.
+            domains (pd.DataFrame): DataFrame containing domain data for the network nodes.
+            trimmed_domains (pd.DataFrame): DataFrame containing trimmed domain data for the network nodes.
+            node_label_to_node_id_map (Dict[str, Any]): A dictionary mapping node labels to their corresponding IDs.
+            node_significance_sums (np.ndarray): Array containing the significant sums for the nodes.
+        """
+        # Initialize self.network downstream of the other attributes
+        # All public attributes can be accessed after initialization
+        self.domain_id_to_node_ids_map = self._create_domain_id_to_node_ids_map(domains)
+        self.domain_id_to_domain_terms_map = self._create_domain_id_to_domain_terms_map(
+            trimmed_domains
+        )
+        self.domain_id_to_domain_info_map = self._create_domain_id_to_domain_info_map(
+            trimmed_domains
+        )
+        self.node_id_to_domain_ids_and_significance_map = (
+            self._create_node_id_to_domain_ids_and_significances(domains)
+        )
+        self.node_id_to_node_label_map = {v: k for k, v in node_label_to_node_id_map.items()}
+        self.node_label_to_significance_map = dict(
+            zip(node_label_to_node_id_map.keys(), node_significance_sums)
+        )
+        self.node_significance_sums = node_significance_sums
+        self.node_label_to_node_id_map = node_label_to_node_id_map
+
+        # NOTE: Below this point, instance attributes (i.e., self) will be used!
+        self.domain_id_to_node_labels_map = self._create_domain_id_to_node_labels_map()
+        # Unfold the network's 3D coordinates to 2D and extract node coordinates
+        self.network = self._unfold_sphere_to_plane(network)
+        self.node_coordinates = self._extract_node_coordinates(self.network)
+
+        # NOTE: Only after the above attributes are initialized, we can create the summary
+        self.summary = Summary(annotations, neighborhoods, self)
+
+    def pop(self, domain_id: int) -> List[str]:
+        """Remove a domain ID from the graph and return the corresponding node labels.
+
+        Args:
+            key (int): The domain ID key to be removed from each mapping.
+
+        Returns:
+            List[str]: A list of node labels associated with the domain ID.
+        """
+        # Get the node labels associated with the domain ID
+        node_labels = self.domain_id_to_node_labels_map.get(domain_id, [])
+
+        # Define the domain mappings to be updated
+        domain_mappings = [
+            self.domain_id_to_node_ids_map,
+            self.domain_id_to_domain_terms_map,
+            self.domain_id_to_domain_info_map,
+            self.domain_id_to_node_labels_map,
+        ]
+        # Remove the specified domain_id key from each mapping if it exists
+        for mapping in domain_mappings:
+            if domain_id in mapping:
+                mapping.pop(domain_id)
+
+        # Remove the domain_id from the node_id_to_domain_ids_and_significance_map
+        for _, domain_info in self.node_id_to_domain_ids_and_significance_map.items():
+            if domain_id in domain_info["domains"]:
+                domain_info["domains"].remove(domain_id)
+                domain_info["significances"].pop(domain_id)
+
+        return node_labels
+
+    def _create_domain_id_to_node_ids_map(self, domains: pd.DataFrame) -> Dict[int, Any]:
+        """Create a mapping from domains to the list of node IDs belonging to each domain.
+
+        Args:
+            domains (pd.DataFrame): DataFrame containing domain information, including the 'primary domain' for each node.
+
+        Returns:
+            Dict[int, Any]: A dictionary where keys are domain IDs and values are lists of node IDs belonging to each domain.
+        """
+        cleaned_domains_matrix = domains.reset_index()[["index", "primary_domain"]]
+        node_to_domains_map = cleaned_domains_matrix.set_index("index")["primary_domain"].to_dict()
+        domain_id_to_node_ids_map = defaultdict(list)
+        for k, v in node_to_domains_map.items():
+            domain_id_to_node_ids_map[v].append(k)
+
+        return domain_id_to_node_ids_map
+
+    def _create_domain_id_to_domain_terms_map(
+        self, trimmed_domains: pd.DataFrame
+    ) -> Dict[int, Any]:
+        """Create a mapping from domain IDs to their corresponding terms.
+
+        Args:
+            trimmed_domains (pd.DataFrame): DataFrame containing domain IDs and their corresponding labels.
+
+        Returns:
+            Dict[int, Any]: A dictionary mapping domain IDs to their corresponding terms.
+        """
+        return dict(
+            zip(
+                trimmed_domains.index,
+                trimmed_domains["normalized_description"],
+            )
+        )
+
+    def _create_domain_id_to_domain_info_map(
+        self,
+        trimmed_domains: pd.DataFrame,
+    ) -> Dict[int, Dict[str, Any]]:
+        """Create a mapping from domain IDs to their corresponding full description and significance score,
+        with scores sorted in descending order.
+
+        Args:
+            trimmed_domains (pd.DataFrame): DataFrame containing domain IDs, full descriptions, and significance scores.
+
+        Returns:
+            Dict[int, Dict[str, Any]]: A dictionary mapping domain IDs (int) to a dictionary with 'full_descriptions' and
+                'significance_scores', both sorted by significance score in descending order.
+        """
+        # Initialize an empty dictionary to store full descriptions and significance scores of domains
+        domain_info_map = {}
+        # Domain IDs are the index of the DataFrame (it's common for some IDs to be missing)
+        for domain_id in trimmed_domains.index:
+            # Sort full_descriptions and significance_scores by significance_scores in descending order
+            descriptions_and_scores = sorted(
+                zip(
+                    trimmed_domains.at[domain_id, "full_descriptions"],
+                    trimmed_domains.at[domain_id, "significance_scores"],
+                ),
+                key=lambda x: x[1],  # Sort by significance score
+                reverse=True,  # Descending order
+            )
+            # Unzip the sorted tuples back into separate lists
+            sorted_descriptions, sorted_scores = zip(*descriptions_and_scores)
+            # Assign to the domain info map
+            domain_info_map[int(domain_id)] = {
+                "full_descriptions": list(sorted_descriptions),
+                "significance_scores": list(sorted_scores),
+            }
+
+        return domain_info_map
+
+    def _create_node_id_to_domain_ids_and_significances(
+        self, domains: pd.DataFrame
+    ) -> Dict[int, Dict]:
+        """Creates a dictionary mapping each node ID to its corresponding domain IDs and significance values.
+
+        Args:
+            domains (pd.DataFrame): A DataFrame containing domain information for each node. Assumes the last
+                two columns are 'all domains' and 'primary domain', which are excluded from processing.
+
+        Returns:
+            Dict[int, Dict]: A dictionary where the key is the node ID (index of the DataFrame), and the value is another dictionary
+                with 'domain' (a list of domain IDs with non-zero significance) and 'significance'
+                (a dict of domain IDs and their corresponding significance values).
+        """
+        # Initialize an empty dictionary to store the result
+        node_id_to_domain_ids_and_significances = {}
+        # Get the list of domain columns (excluding 'all domains' and 'primary domain')
+        domain_columns = domains.columns[
+            :-2
+        ]  # The last two columns are 'all domains' and 'primary domain'
+        # Iterate over each row in the dataframe
+        for idx, row in domains.iterrows():
+            # Get the domains (column names) where the significance score is greater than 0
+            all_domains = domain_columns[row[domain_columns] > 0].tolist()
+            # Get the significance values for those domains
+            significance_values = row[all_domains].to_dict()
+            # Store the result in the dictionary with index as the key
+            node_id_to_domain_ids_and_significances[idx] = {
+                "domains": all_domains,  # The column names where significance > 0
+                "significances": significance_values,  # The actual significance values for those columns
+            }
+
+        return node_id_to_domain_ids_and_significances
+
+    def _create_domain_id_to_node_labels_map(self) -> Dict[int, List[str]]:
+        """Create a map from domain IDs to node labels.
+
+        Returns:
+            Dict[int, List[str]]: A dictionary mapping domain IDs to the corresponding node labels.
+        """
+        domain_id_to_label_map = {}
+        for domain_id, node_ids in self.domain_id_to_node_ids_map.items():
+            domain_id_to_label_map[domain_id] = [
+                self.node_id_to_node_label_map[node_id] for node_id in node_ids
+            ]
+
+        return domain_id_to_label_map
+
+    def _unfold_sphere_to_plane(self, G: nx.Graph) -> nx.Graph:
+        """Convert 3D coordinates to 2D by unfolding a sphere to a plane.
+
+        Args:
+            G (nx.Graph): A network graph with 3D coordinates. Each node should have 'x', 'y', and 'z' attributes.
+
+        Returns:
+            nx.Graph: The network graph with updated 2D coordinates (only 'x' and 'y').
+        """
+        for node in G.nodes():
+            if "z" in G.nodes[node]:
+                # Extract 3D coordinates
+                x, y, z = G.nodes[node]["x"], G.nodes[node]["y"], G.nodes[node]["z"]
+                # Calculate spherical coordinates theta and phi from Cartesian coordinates
+                r = np.sqrt(x**2 + y**2 + z**2)
+                theta = np.arctan2(y, x)
+                phi = np.arccos(z / r)
+
+                # Convert spherical coordinates to 2D plane coordinates
+                unfolded_x = (theta + np.pi) / (2 * np.pi)  # Shift and normalize theta to [0, 1]
+                unfolded_x = unfolded_x + 0.5 if unfolded_x < 0.5 else unfolded_x - 0.5
+                unfolded_y = (np.pi - phi) / np.pi  # Reflect phi and normalize to [0, 1]
+                # Update network node attributes
+                G.nodes[node]["x"] = unfolded_x
+                G.nodes[node]["y"] = -unfolded_y
+                # Remove the 'z' coordinate as it's no longer needed
+                del G.nodes[node]["z"]
+
+        return G
+
+    def _extract_node_coordinates(self, G: nx.Graph) -> np.ndarray:
+        """Extract 2D coordinates of nodes from the graph.
+
+        Args:
+            G (nx.Graph): The network graph with node coordinates.
+
+        Returns:
+            np.ndarray: Array of node coordinates with shape (num_nodes, 2).
+        """
+        # Extract x and y coordinates from graph nodes
+        x_coords = dict(G.nodes.data("x"))
+        y_coords = dict(G.nodes.data("y"))
+        coordinates_dicts = [x_coords, y_coords]
+        # Combine x and y coordinates into a single array
+        node_positions = {
+            node: np.array([coords[node] for coords in coordinates_dicts]) for node in x_coords
+        }
+        node_coordinates = np.vstack(list(node_positions.values()))
+        return node_coordinates

risk/network/graph/stats.py

@@ -0,0 +1,166 @@
+"""
+risk/network/graph/stats
+~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict, Union
+
+import numpy as np
+from statsmodels.stats.multitest import fdrcorrection
+
+
+def calculate_significance_matrices(
+    depletion_pvals: np.ndarray,
+    enrichment_pvals: np.ndarray,
+    tail: str = "right",
+    pval_cutoff: float = 0.05,
+    fdr_cutoff: float = 0.05,
+) -> Dict[str, Any]:
+    """Calculate significance matrices based on p-values and specified tail.
+
+    Args:
+        depletion_pvals (np.ndarray): Matrix of depletion p-values.
+        enrichment_pvals (np.ndarray): Matrix of enrichment p-values.
+        tail (str, optional): The tail type for significance selection ('left', 'right', 'both'). Defaults to 'right'.
+        pval_cutoff (float, optional): Cutoff for p-value significance. Defaults to 0.05.
+        fdr_cutoff (float, optional): Cutoff for FDR significance if applied. Defaults to 0.05.
+
+    Returns:
+        Dict[str, Any]: Dictionary containing the enrichment matrix, binary significance matrix,
+            and the matrix of significant enrichment values.
+    """
+    if fdr_cutoff < 1.0:
+        # Apply FDR correction to depletion p-values
+        depletion_qvals = np.apply_along_axis(fdrcorrection, 1, depletion_pvals)[:, 1, :]
+        depletion_alpha_threshold_matrix = _compute_threshold_matrix(
+            depletion_pvals, depletion_qvals, pval_cutoff=pval_cutoff, fdr_cutoff=fdr_cutoff
+        )
+        # Compute the depletion matrix using both q-values and p-values
+        depletion_matrix = (depletion_qvals**2) * (depletion_pvals**0.5)
+
+        # Apply FDR correction to enrichment p-values
+        enrichment_qvals = np.apply_along_axis(fdrcorrection, 1, enrichment_pvals)[:, 1, :]
+        enrichment_alpha_threshold_matrix = _compute_threshold_matrix(
+            enrichment_pvals, enrichment_qvals, pval_cutoff=pval_cutoff, fdr_cutoff=fdr_cutoff
+        )
+        # Compute the enrichment matrix using both q-values and p-values
+        enrichment_matrix = (enrichment_pvals**0.5) * (enrichment_qvals**2)
+    else:
+        # Compute threshold matrices based on p-value cutoffs only
+        depletion_alpha_threshold_matrix = _compute_threshold_matrix(
+            depletion_pvals, pval_cutoff=pval_cutoff
+        )
+        depletion_matrix = depletion_pvals
+
+        enrichment_alpha_threshold_matrix = _compute_threshold_matrix(
+            enrichment_pvals, pval_cutoff=pval_cutoff
+        )
+        enrichment_matrix = enrichment_pvals
+
+    # Apply a negative log10 transformation for visualization purposes
+    log_depletion_matrix = -np.log10(depletion_matrix)
+    log_enrichment_matrix = -np.log10(enrichment_matrix)
+
+    # Select the appropriate significance matrices based on the specified tail
+    significance_matrix, significant_binary_significance_matrix = _select_significance_matrices(
+        tail,
+        log_depletion_matrix,
+        depletion_alpha_threshold_matrix,
+        log_enrichment_matrix,
+        enrichment_alpha_threshold_matrix,
+    )
+
+    # Filter the enrichment matrix using the binary significance matrix
+    significant_significance_matrix = np.where(
+        significant_binary_significance_matrix == 1, significance_matrix, 0
+    )
+
+    return {
+        "significance_matrix": significance_matrix,
+        "significant_significance_matrix": significant_significance_matrix,
+        "significant_binary_significance_matrix": significant_binary_significance_matrix,
+    }
+
+
+def _select_significance_matrices(
+    tail: str,
+    log_depletion_matrix: np.ndarray,
+    depletion_alpha_threshold_matrix: np.ndarray,
+    log_enrichment_matrix: np.ndarray,
+    enrichment_alpha_threshold_matrix: np.ndarray,
+) -> tuple:
+    """Select significance matrices based on the specified tail type.
+
+    Args:
+        tail (str): The tail type for significance selection. Options are 'left', 'right', or 'both'.
+        log_depletion_matrix (np.ndarray): Matrix of log-transformed depletion values.
+        depletion_alpha_threshold_matrix (np.ndarray): Alpha threshold matrix for depletion significance.
+        log_enrichment_matrix (np.ndarray): Matrix of log-transformed enrichment values.
+        enrichment_alpha_threshold_matrix (np.ndarray): Alpha threshold matrix for enrichment significance.
+
+    Returns:
+        tuple: A tuple containing the selected enrichment matrix and binary significance matrix.
+
+    Raises:
+        ValueError: If the provided tail type is not 'left', 'right', or 'both'.
+    """
+    if tail not in {"left", "right", "both"}:
+        raise ValueError("Invalid value for 'tail'. Must be 'left', 'right', or 'both'.")
+
+    if tail == "left":
+        # Select depletion matrix and corresponding alpha threshold for left-tail analysis
+        significance_matrix = -log_depletion_matrix
+        alpha_threshold_matrix = depletion_alpha_threshold_matrix
+    elif tail == "right":
+        # Select enrichment matrix and corresponding alpha threshold for right-tail analysis
+        significance_matrix = log_enrichment_matrix
+        alpha_threshold_matrix = enrichment_alpha_threshold_matrix
+    elif tail == "both":
+        # Select the matrix with the highest absolute values while preserving the sign
+        significance_matrix = np.where(
+            np.abs(log_depletion_matrix) >= np.abs(log_enrichment_matrix),
+            -log_depletion_matrix,
+            log_enrichment_matrix,
+        )
+        # Combine alpha thresholds using a logical OR operation
+        alpha_threshold_matrix = np.logical_or(
+            depletion_alpha_threshold_matrix, enrichment_alpha_threshold_matrix
+        )
+    else:
+        raise ValueError("Invalid value for 'tail'. Must be 'left', 'right', or 'both'.")
+
+    # Create a binary significance matrix where valid indices meet the alpha threshold
+    valid_idxs = ~np.isnan(alpha_threshold_matrix)
+    significant_binary_significance_matrix = np.zeros(alpha_threshold_matrix.shape)
+    significant_binary_significance_matrix[valid_idxs] = alpha_threshold_matrix[valid_idxs]
+
+    return significance_matrix, significant_binary_significance_matrix
+
+
+def _compute_threshold_matrix(
+    pvals: np.ndarray,
+    fdr_pvals: Union[np.ndarray, None] = None,
+    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.
+
+    Args:
+        pvals (np.ndarray): Array of p-values for statistical tests.
+        fdr_pvals (np.ndarray, optional): Array of FDR-corrected p-values corresponding to the p-values. Defaults to None.
+        pval_cutoff (float, optional): Cutoff for p-value significance. Defaults to 0.05.
+        fdr_cutoff (float, optional): Cutoff for FDR significance. Defaults to 0.05.
+
+    Returns:
+        np.ndarray: A threshold matrix where 1 indicates significance based on the provided cutoffs, 0 otherwise.
+    """
+    if fdr_pvals is not None:
+        # Compute the threshold matrix based on both p-value and FDR cutoffs
+        pval_below_cutoff = pvals <= pval_cutoff
+        fdr_below_cutoff = fdr_pvals <= fdr_cutoff
+        threshold_matrix = np.logical_and(pval_below_cutoff, fdr_below_cutoff).astype(int)
+    else:
+        # Compute the threshold matrix based only on p-value cutoff
+        threshold_matrix = (pvals <= pval_cutoff).astype(int)
+
+    return threshold_matrix