risk-network 0.0.8b14__tar.gz → 0.0.8b16__tar.gz

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: risk-network
-Version: 0.0.8b14
+Version: 0.0.8b16
 Summary: A Python package for biological network analysis
 Author: Ira Horecka
 Author-email: Ira Horecka <ira89@icloud.com>

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/risk/__init__.py

@@ -7,4 +7,4 @@ RISK: RISK Infers Spatial Kinships
 
 from risk.risk import RISK
 
-__version__ = "0.0.8-beta.14"
+__version__ = "0.0.8-beta.16"

risk_network-0.0.8b16/risk/network/graph.py

@@ -0,0 +1,159 @@
+"""
+risk/network/graph
+~~~~~~~~~~~~~~~~~~
+"""
+
+from collections import defaultdict
+from typing import Any, Dict, List
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+
+class NetworkGraph:
+    """A class to represent a network graph and process its nodes and edges.
+
+    The NetworkGraph class provides functionality to handle and manipulate a network graph,
+    including managing domains, annotations, and node enrichment data. It also includes methods
+    for transforming and mapping graph coordinates, as well as generating colors based on node
+    enrichment.
+    """
+
+    def __init__(
+        self,
+        network: nx.Graph,
+        top_annotations: pd.DataFrame,
+        domains: pd.DataFrame,
+        trimmed_domains: pd.DataFrame,
+        node_label_to_node_id_map: Dict[str, Any],
+        node_enrichment_sums: np.ndarray,
+    ):
+        """Initialize the NetworkGraph object.
+
+        Args:
+            network (nx.Graph): The network graph.
+            top_annotations (pd.DataFrame): DataFrame containing annotations data for the network nodes.
+            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): A dictionary mapping node labels to their corresponding IDs.
+            node_enrichment_sums (np.ndarray): Array containing the enrichment sums for the nodes.
+        """
+        self.top_annotations = top_annotations
+        self.domain_id_to_node_ids_map = self._create_domain_id_to_node_ids_map(domains)
+        self.domains = domains
+        self.domain_id_to_domain_terms_map = self._create_domain_id_to_domain_terms_map(
+            trimmed_domains
+        )
+        self.node_enrichment_sums = node_enrichment_sums
+        self.node_id_to_node_label_map = {v: k for k, v in node_label_to_node_id_map.items()}
+        self.node_label_to_enrichment_map = dict(
+            zip(node_label_to_node_id_map.keys(), node_enrichment_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 = _unfold_sphere_to_plane(network)
+        self.node_coordinates = _extract_node_coordinates(self.network)
+
+    def _create_domain_id_to_node_ids_map(self, domains: pd.DataFrame) -> Dict[str, 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: 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[str, 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: A dictionary mapping domain IDs to their corresponding terms.
+        """
+        return dict(
+            zip(
+                trimmed_domains.index,
+                trimmed_domains["label"],
+            )
+        )
+
+    def _create_domain_id_to_node_labels_map(self) -> Dict[int, List[str]]:
+        """Create a map from domain IDs to node labels.
+
+        Returns:
+            dict: 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(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(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-0.0.8b14 → risk_network-0.0.8b16}/risk/network/plot/canvas.py

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

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/risk/network/plot/contour.py

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

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/risk/network/plot/labels.py

@@ -11,7 +11,8 @@ import pandas as pd
 
 from risk.log import params
 from risk.network.graph import NetworkGraph
-from risk.network.plot.utils import calculate_bounding_box, get_annotated_domain_colors, to_rgba
+from risk.network.plot.utils.color import get_annotated_domain_colors, to_rgba
+from risk.network.plot.utils.layout import calculate_bounding_box
 
 TERM_DELIMITER = "::::"  # String used to separate multiple domain terms when constructing composite domain labels
 
@@ -34,7 +35,7 @@ class Labels:
         scale: float = 1.05,
         offset: float = 0.10,
         font: str = "Arial",
-        fontcase: Union[str, None] = None,
+        fontcase: Union[str, Dict[str, str], None] = None,
         fontsize: int = 10,
         fontcolor: Union[str, List, Tuple, np.ndarray] = "black",
         fontalpha: Union[float, None] = 1.0,
@@ -60,8 +61,10 @@ class Labels:
             scale (float, optional): Scale factor for positioning labels around the perimeter. Defaults to 1.05.
             offset (float, optional): Offset distance for labels from the perimeter. Defaults to 0.10.
             font (str, optional): Font name for the labels. Defaults to "Arial".
-            fontcase (str, None, optional): Case transformation for the labels. Can be "capitalize", "lower", "title",
-                "upper", or None. Defaults to None.
+            fontcase (Union[str, Dict[str, str], None]): Defines how to transform the case of words.
+                - If a string (e.g., 'upper', 'lower', 'title'), applies the transformation to all words.
+                - If a dictionary, maps specific cases ('lower', 'upper', 'title') to transformations (e.g., 'lower'='upper').
+                - If None, no transformation is applied.
             fontsize (int, optional): Font size for the labels. Defaults to 10.
             fontcolor (str, list, tuple, or np.ndarray, optional): Color of the label text. Can be a string or RGBA array.
                 Defaults to "black".
@@ -855,23 +858,43 @@ def _swap_and_evaluate(
     return _calculate_total_distance(swapped_positions, domain_centroids)
 
 
-def _apply_str_transformation(words: List[str], transformation: str) -> List[str]:
+def _apply_str_transformation(
+    words: List[str], transformation: Union[str, Dict[str, str]]
+) -> List[str]:
     """Apply a user-specified case transformation to each word in the list without appending duplicates.
 
     Args:
         words (List[str]): A list of words to transform.
-        transformation (str): The case transformation to apply (e.g., 'lower', 'upper', 'title', 'capitalize').
+        transformation (Union[str, Dict[str, str]]): A single transformation (e.g., 'lower', 'upper', 'title', 'capitalize')
+            or a dictionary mapping cases ('lower', 'upper', 'title') to transformations (e.g., 'lower'='upper').
 
     Returns:
         List[str]: A list of transformed words with no duplicates.
     """
     transformed_words = []
     for word in words:
-        if hasattr(word, transformation):
-            transformed_word = getattr(word, transformation)()  # Apply the string method
-
-            # Only append if the transformed word is not already in the list
-            if transformed_word not in transformed_words:
-                transformed_words.append(transformed_word)
+        # Convert the word to a string if it is not already
+        word = str(word)
+        transformed_word = word  # Start with the original word
+        # If transformation is a string, apply it to all words
+        if isinstance(transformation, str):
+            if hasattr(word, transformation):
+                transformed_word = getattr(
+                    word, transformation
+                )()  # Apply the single transformation
+
+        # If transformation is a dictionary, apply case-specific transformations
+        elif isinstance(transformation, dict):
+            for case_type, transform in transformation.items():
+                if case_type == "lower" and word.islower() and transform:
+                    transformed_word = getattr(word, transform)()
+                elif case_type == "upper" and word.isupper() and transform:
+                    transformed_word = getattr(word, transform)()
+                elif case_type == "title" and word.istitle() and transform:
+                    transformed_word = getattr(word, transform)()
+
+        # Only append if the transformed word is not already in the list
+        if transformed_word not in transformed_words:
+            transformed_words.append(transformed_word)
 
     return transformed_words

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/risk/network/plot/network.py

@@ -10,7 +10,7 @@ import numpy as np
 
 from risk.log import params
 from risk.network.graph import NetworkGraph
-from risk.network.plot.utils import to_rgba
+from risk.network.plot.utils.color import get_domain_colors, to_rgba
 
 
 class Network:
@@ -222,7 +222,8 @@ class Network:
             np.ndarray: Array of RGBA colors adjusted for enrichment status.
         """
         # Get the initial domain colors for each node, which are returned as RGBA
-        network_colors = self.graph.get_domain_colors(
+        network_colors = get_domain_colors(
+            graph=self.graph,
             cmap=cmap,
             color=color,
             min_scale=min_scale,

{risk_network-0.0.8b14 → risk_network-0.0.8b16}/risk/network/plot/plotter.py

@@ -14,7 +14,8 @@ 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.network import Network
-from risk.network.plot.utils import calculate_bounding_box, to_rgba
+from risk.network.plot.utils.color import to_rgba
+from risk.network.plot.utils.layout import calculate_bounding_box
 
 
 class NetworkPlotter(Canvas, Network, Contour, Labels):

risk_network-0.0.8b16/risk/network/plot/utils/color.py

@@ -0,0 +1,351 @@
+"""
+risk/network/plot/utils/plot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict, List, Tuple, Union
+
+import matplotlib
+import matplotlib.colors as mcolors
+import numpy as np
+
+from risk.network.graph import NetworkGraph
+from risk.network.plot.utils.layout import calculate_centroids
+
+
+def get_annotated_domain_colors(
+    graph: NetworkGraph,
+    cmap: str = "gist_rainbow",
+    color: Union[str, None] = None,
+    min_scale: float = 0.8,
+    max_scale: float = 1.0,
+    scale_factor: float = 1.0,
+    random_seed: int = 888,
+) -> np.ndarray:
+    """Get colors for the domains based on node annotations, or use a specified color.
+
+    Args:
+        graph (NetworkGraph): The network data and attributes to be visualized.
+        cmap (str, optional): Colormap to use for generating domain colors. Defaults to "gist_rainbow".
+        color (str or None, optional): Color to use for the domains. If None, the colormap will be used. Defaults to None.
+        min_scale (float, optional): Minimum scale for color intensity when generating domain colors.
+            Defaults to 0.8.
+        max_scale (float, optional): Maximum scale for color intensity when generating domain colors.
+            Defaults to 1.0.
+        scale_factor (float, optional): Factor for adjusting the contrast in the colors generated based on
+            enrichment. Higher values increase the contrast. Defaults to 1.0.
+        random_seed (int, optional): Seed for random number generation to ensure reproducibility. Defaults to 888.
+
+    Returns:
+        np.ndarray: Array of RGBA colors for each domain.
+    """
+    # Generate domain colors based on the enrichment data
+    node_colors = get_domain_colors(
+        graph=graph,
+        cmap=cmap,
+        color=color,
+        min_scale=min_scale,
+        max_scale=max_scale,
+        scale_factor=scale_factor,
+        random_seed=random_seed,
+    )
+    annotated_colors = []
+    for _, node_ids in graph.domain_id_to_node_ids_map.items():
+        if len(node_ids) > 1:
+            # For multi-node domains, choose the brightest color based on RGB sum
+            domain_colors = np.array([node_colors[node] for node in node_ids])
+            brightest_color = domain_colors[
+                np.argmax(domain_colors[:, :3].sum(axis=1))  # Sum the RGB values
+            ]
+            annotated_colors.append(brightest_color)
+        else:
+            # Single-node domains default to white (RGBA)
+            default_color = np.array([1.0, 1.0, 1.0, 1.0])
+            annotated_colors.append(default_color)
+
+    return np.array(annotated_colors)
+
+
+def get_domain_colors(
+    graph: NetworkGraph,
+    cmap: str = "gist_rainbow",
+    color: Union[str, None] = None,
+    min_scale: float = 0.8,
+    max_scale: float = 1.0,
+    scale_factor: float = 1.0,
+    random_seed: int = 888,
+) -> np.ndarray:
+    """Generate composite colors for domains based on enrichment or specified colors.
+
+    Args:
+        graph (NetworkGraph): The network data and attributes to be visualized.
+        cmap (str, optional): Name of the colormap to use for generating domain colors. Defaults to "gist_rainbow".
+        color (str or None, optional): A specific color to use for all generated colors. Defaults to None.
+        min_scale (float, optional): Minimum intensity scale for the colors generated by the colormap.
+            Controls the dimmest colors. Defaults to 0.8.
+        max_scale (float, optional): Maximum intensity scale for the colors generated by the colormap.
+            Controls the brightest colors. Defaults to 1.0.
+        scale_factor (float, optional): Exponent for adjusting the color scaling based on enrichment scores.
+            A higher value increases contrast by dimming lower scores more. Defaults to 1.0.
+        random_seed (int, optional): Seed for random number generation to ensure reproducibility of color assignments.
+            Defaults to 888.
+
+    Returns:
+        np.ndarray: Array of RGBA colors generated for each domain, based on enrichment or the specified color.
+    """
+    # Get colors for each domain
+    domain_colors = _get_domain_colors(graph=graph, cmap=cmap, color=color, random_seed=random_seed)
+    # Generate composite colors for nodes
+    node_colors = _get_composite_node_colors(graph=graph, domain_colors=domain_colors)
+    # Transform colors to ensure proper alpha values and intensity
+    transformed_colors = _transform_colors(
+        node_colors,
+        graph.node_enrichment_sums,
+        min_scale=min_scale,
+        max_scale=max_scale,
+        scale_factor=scale_factor,
+    )
+    return transformed_colors
+
+
+def _get_domain_colors(
+    graph: NetworkGraph,
+    cmap: str = "gist_rainbow",
+    color: Union[str, None] = None,
+    random_seed: int = 888,
+) -> Dict[str, Any]:
+    """Get colors for each domain.
+
+    Args:
+        graph (NetworkGraph): The network data and attributes to be visualized.
+        cmap (str, optional): The name of the colormap to use. Defaults to "gist_rainbow".
+        color (str or None, optional): A specific color to use for all generated colors. Defaults to None.
+        random_seed (int, optional): Seed for random number generation. Defaults to 888.
+
+    Returns:
+        dict: A dictionary mapping domain keys to their corresponding RGBA colors.
+    """
+    # Get colors for each domain based on node positions
+    domain_colors = _get_colors(
+        graph.network,
+        graph.domain_id_to_node_ids_map,
+        cmap=cmap,
+        color=color,
+        random_seed=random_seed,
+    )
+    return dict(zip(graph.domain_id_to_node_ids_map.keys(), domain_colors))
+
+
+def _get_composite_node_colors(graph: NetworkGraph, domain_colors: np.ndarray) -> np.ndarray:
+    """Generate composite colors for nodes based on domain colors and counts.
+
+    Args:
+        graph (NetworkGraph): The network data and attributes to be visualized.
+        domain_colors (np.ndarray): Array of colors corresponding to each domain.
+
+    Returns:
+        np.ndarray: Array of composite colors for each node.
+    """
+    # Determine the number of nodes
+    num_nodes = len(graph.node_coordinates)
+    # Initialize composite colors array with shape (number of nodes, 4) for RGBA
+    composite_colors = np.zeros((num_nodes, 4))
+    # Assign colors to nodes based on domain_colors
+    for domain_id, nodes in graph.domain_id_to_node_ids_map.items():
+        color = domain_colors[domain_id]
+        for node in nodes:
+            composite_colors[node] = color
+
+    return composite_colors
+
+
+def _get_colors(
+    network,
+    domain_id_to_node_ids_map,
+    cmap: str = "gist_rainbow",
+    color: Union[str, None] = None,
+    random_seed: int = 888,
+) -> List[Tuple]:
+    """Generate a list of RGBA colors based on domain centroids, ensuring that domains
+    close in space get maximally separated colors, while keeping some randomness.
+
+    Args:
+        network (NetworkX graph): The graph representing the network.
+        domain_id_to_node_ids_map (dict): Mapping from domain IDs to lists of node IDs.
+        cmap (str, optional): The name of the colormap to use. Defaults to "gist_rainbow".
+        color (str or None, optional): A specific color to use for all generated colors.
+        random_seed (int): Seed for random number generation. Defaults to 888.
+
+    Returns:
+        List[Tuple]: List of RGBA colors.
+    """
+    # Set random seed for reproducibility
+    np.random.seed(random_seed)
+    # Determine the number of colors to generate based on the number of domains
+    num_colors_to_generate = len(domain_id_to_node_ids_map)
+    if color:
+        # Generate all colors as the same specified color
+        rgba = to_rgba(color, num_repeats=num_colors_to_generate)
+        return rgba
+
+    # Load colormap
+    colormap = matplotlib.colormaps.get_cmap(cmap)
+    # Step 1: Calculate centroids for each domain
+    centroids = calculate_centroids(network, domain_id_to_node_ids_map)
+    # Step 2: Calculate pairwise distances between centroids
+    centroid_array = np.array(centroids)
+    dist_matrix = np.linalg.norm(centroid_array[:, None] - centroid_array, axis=-1)
+    # Step 3: Assign distant colors to close centroids
+    color_positions = _assign_distant_colors(dist_matrix, num_colors_to_generate)
+    # Step 4: Randomly shift the entire color palette while maintaining relative distances
+    global_shift = np.random.uniform(-0.1, 0.1)  # Small global shift to change the overall palette
+    color_positions = (color_positions + global_shift) % 1  # Wrap around to keep within [0, 1]
+    # Step 5: Ensure that all positions remain between 0 and 1
+    color_positions = np.clip(color_positions, 0, 1)
+
+    # Step 6: Generate RGBA colors based on positions
+    return [colormap(pos) for pos in color_positions]
+
+
+def _assign_distant_colors(dist_matrix, num_colors_to_generate):
+    """Assign colors to centroids that are close in space, ensuring stark color differences.
+
+    Args:
+        dist_matrix (ndarray): Matrix of pairwise centroid distances.
+        num_colors_to_generate (int): Number of colors to generate.
+
+    Returns:
+        np.array: Array of color positions in the range [0, 1].
+    """
+    color_positions = np.zeros(num_colors_to_generate)
+    # Step 1: Sort indices by centroid proximity (based on sum of distances to others)
+    proximity_order = sorted(
+        range(num_colors_to_generate), key=lambda idx: np.sum(dist_matrix[idx])
+    )
+    # Step 2: Assign colors starting with the most distant points in proximity order
+    for i, idx in enumerate(proximity_order):
+        color_positions[idx] = i / num_colors_to_generate
+
+    # Step 3: Adjust colors so that centroids close to one another are maximally distant on the color spectrum
+    half_spectrum = int(num_colors_to_generate / 2)
+    for i in range(half_spectrum):
+        # Split the spectrum so that close centroids are assigned distant colors
+        color_positions[proximity_order[i]] = (i * 2) / num_colors_to_generate
+        color_positions[proximity_order[-(i + 1)]] = ((i * 2) + 1) / num_colors_to_generate
+
+    return color_positions
+
+
+def _transform_colors(
+    colors: np.ndarray,
+    enrichment_sums: np.ndarray,
+    min_scale: float = 0.8,
+    max_scale: float = 1.0,
+    scale_factor: float = 1.0,
+) -> np.ndarray:
+    """Transform colors using power scaling to emphasize high enrichment sums more. Black colors are replaced with
+    very dark grey to avoid issues with color scaling (rgb(0.1, 0.1, 0.1)).
+
+    Args:
+        colors (np.ndarray): An array of RGBA colors.
+        enrichment_sums (np.ndarray): An array of enrichment sums corresponding to the colors.
+        min_scale (float, optional): Minimum scale for color intensity. Defaults to 0.8.
+        max_scale (float, optional): Maximum scale for color intensity. Defaults to 1.0.
+        scale_factor (float, optional): Exponent for scaling, where values > 1 increase contrast by dimming small
+            values more. Defaults to 1.0.
+
+    Returns:
+        np.ndarray: The transformed array of RGBA colors with adjusted intensities.
+    """
+    # Ensure that min_scale is less than max_scale
+    if min_scale == max_scale:
+        min_scale = max_scale - 10e-6  # Avoid division by zero
+
+    # 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 enrichment sums to the range [0, 1]
+    normalized_sums = enrichment_sums / np.max(enrichment_sums)
+    # Apply power scaling to dim lower values and emphasize higher 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
+    # Adjust RGB values based on scaled sums
+    for i in range(3):  # Only adjust RGB values
+        colors[:, i] = scaled_sums * colors[:, i]
+
+    return colors
+
+
+def to_rgba(
+    color: Union[str, List, Tuple, np.ndarray],
+    alpha: Union[float, None] = None,
+    num_repeats: Union[int, None] = None,
+) -> np.ndarray:
+    """Convert color(s) to RGBA format, applying alpha and repeating as needed.
+
+    Args:
+        color (Union[str, list, tuple, np.ndarray]): The color(s) to convert. Can be a string, list, tuple, or np.ndarray.
+        alpha (float, None, optional): Alpha value (transparency) to apply. If provided, it overrides any existing alpha values
+            found in color.
+        num_repeats (int, None, optional): If provided, the color(s) will be repeated this many times. Defaults to None.
+
+    Returns:
+        np.ndarray: Array of RGBA colors repeated `num_repeats` times, if applicable.
+    """
+
+    def convert_to_rgba(c: Union[str, List, Tuple, np.ndarray]) -> np.ndarray:
+        """Convert a single color to RGBA format, handling strings, hex, and RGB/RGBA lists."""
+        # Note: if no alpha is provided, the default alpha value is 1.0 by mcolors.to_rgba
+        if isinstance(c, str):
+            # Convert color names or hex values (e.g., 'red', '#FF5733') to RGBA
+            rgba = np.array(mcolors.to_rgba(c))
+        elif isinstance(c, (list, tuple, np.ndarray)) and len(c) in [3, 4]:
+            # Convert RGB (3) or RGBA (4) values to RGBA format
+            rgba = np.array(mcolors.to_rgba(c))
+        else:
+            raise ValueError(
+                f"Invalid color format: {c}. Must be a valid string or RGB/RGBA sequence."
+            )
+
+        if alpha is not None:  # Override alpha if provided
+            rgba[3] = alpha
+        return rgba
+
+    # If color is a 2D array of RGBA values, convert it to a list of lists
+    if isinstance(color, np.ndarray) and color.ndim == 2 and color.shape[1] == 4:
+        color = [list(c) for c in color]
+
+    # Handle a single color (string or RGB/RGBA list/tuple)
+    if (
+        isinstance(color, str)
+        or isinstance(color, (list, tuple, np.ndarray))
+        and not any(isinstance(c, (str, list, tuple, np.ndarray)) for c in color)
+    ):
+        rgba_color = convert_to_rgba(color)
+        if num_repeats:
+            return np.tile(
+                rgba_color, (num_repeats, 1)
+            )  # Repeat the color if num_repeats is provided
+        return np.array([rgba_color])  # Return a single color wrapped in a numpy array
+
+    # Handle a list/array of colors
+    elif isinstance(color, (list, tuple, np.ndarray)):
+        rgba_colors = np.array(
+            [convert_to_rgba(c) for c in color]
+        )  # Convert each color in the list to RGBA
+        # Handle repetition if num_repeats is provided
+        if num_repeats:
+            repeated_colors = np.array(
+                [rgba_colors[i % len(rgba_colors)] for i in range(num_repeats)]
+            )
+            return repeated_colors
+
+        return rgba_colors
+
+    else:
+        raise ValueError("Color must be a valid RGB/RGBA or array of RGB/RGBA colors.")