risk-network 0.0.8b27__py3-none-any.whl → 0.0.9b2__py3-none-any.whl

risk/network/graph/summary.py

@@ -0,0 +1,239 @@
+"""
+risk/network/graph/summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+import warnings
+from functools import lru_cache
+from typing import Any, Dict, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from statsmodels.stats.multitest import fdrcorrection
+
+from risk.log.console import logger, log_header
+
+
+# Suppress all warnings - this is to resolve warnings from multiprocessing
+warnings.filterwarnings("ignore")
+
+
+class Summary:
+    """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
+    DataFrame. It also offers functionality to export the processed data in CSV, JSON,
+    and text formats for analysis and reporting.
+    """
+
+    def __init__(
+        self,
+        annotations: Dict[str, Any],
+        neighborhoods: Dict[str, Any],
+        graph,  # Avoid type hinting NetworkGraph to avoid circular import
+    ):
+        """Initialize the Results object with analysis components.
+
+        Args:
+            annotations (Dict[str, Any]): Annotation data, including ordered annotations and matrix of associations.
+            neighborhoods (Dict[str, Any]): Neighborhood data containing p-values for significance and depletion analysis.
+            graph (NetworkGraph): Graph object representing domain-to-node and node-to-label mappings.
+        """
+        self.annotations = annotations
+        self.neighborhoods = neighborhoods
+        self.graph = graph
+
+    def to_csv(self, filepath: str) -> None:
+        """Export significance results to a CSV file.
+
+        Args:
+            filepath (str): The path where the CSV file will be saved.
+        """
+        # Load results and export directly to CSV
+        results = self.load()
+        results.to_csv(filepath, index=False)
+        logger.info(f"Results summary exported to CSV file: {filepath}")
+
+    def to_json(self, filepath: str) -> None:
+        """Export significance results to a JSON file.
+
+        Args:
+            filepath (str): The path where the JSON file will be saved.
+        """
+        # Load results and export directly to JSON
+        results = self.load()
+        results.to_json(filepath, orient="records", indent=4)
+        logger.info(f"Results summary exported to JSON file: {filepath}")
+
+    def to_txt(self, filepath: str) -> None:
+        """Export significance results to a text file.
+
+        Args:
+            filepath (str): The path where the text file will be saved.
+        """
+        # Load results and export directly to text file
+        results = self.load()
+        with open(filepath, "w") as txt_file:
+            txt_file.write(results.to_string(index=False))
+
+        logger.info(f"Results summary exported to text file: {filepath}")
+
+    @lru_cache(maxsize=None)
+    def load(self) -> pd.DataFrame:
+        """Load and process domain and annotation data into a DataFrame with significance metrics.
+
+        Args:
+            graph (Any): Graph object containing domain-to-node and node-to-label mappings.
+            annotations (Dict[str, Any]): Annotation details, including ordered annotations and matrix.
+
+        Returns:
+            pd.DataFrame: Processed DataFrame containing significance scores, p-values, q-values,
+                and annotation member information.
+        """
+        log_header("Loading parameters")
+        # Calculate significance and depletion q-values from p-value matrices in `annotations`
+        enrichment_pvals = self.neighborhoods["enrichment_pvals"]
+        depletion_pvals = self.neighborhoods["depletion_pvals"]
+        enrichment_qvals = self._calculate_qvalues(enrichment_pvals)
+        depletion_qvals = self._calculate_qvalues(depletion_pvals)
+
+        # Initialize DataFrame with domain and annotation details
+        results = pd.DataFrame(
+            [
+                {"Domain ID": domain_id, "Annotation": desc, "Summed Significance Score": score}
+                for domain_id, info in self.graph.domain_id_to_domain_info_map.items()
+                for desc, score in zip(info["full_descriptions"], info["significance_scores"])
+            ]
+        )
+        # Sort by Domain ID and Summed Significance Score
+        results = results.sort_values(
+            by=["Domain ID", "Summed Significance Score"], ascending=[True, False]
+        ).reset_index(drop=True)
+
+        # Add minimum p-values and q-values to DataFrame
+        results[
+            [
+                "Enrichment P-value",
+                "Enrichment Q-value",
+                "Depletion P-value",
+                "Depletion Q-value",
+            ]
+        ] = results.apply(
+            lambda row: self._get_significance_values(
+                row["Domain ID"],
+                row["Annotation"],
+                enrichment_pvals,
+                depletion_pvals,
+                enrichment_qvals,
+                depletion_qvals,
+            ),
+            axis=1,
+            result_type="expand",
+        )
+        # Add annotation members and their counts
+        results["Annotation Members"] = results["Annotation"].apply(
+            lambda desc: self._get_annotation_members(desc)
+        )
+        results["Annotation Member Count"] = results["Annotation Members"].apply(
+            lambda x: len(x.split(";")) if x else 0
+        )
+
+        # Reorder columns and drop rows with NaN values
+        results = (
+            results[
+                [
+                    "Domain ID",
+                    "Annotation",
+                    "Annotation Members",
+                    "Annotation Member Count",
+                    "Summed Significance Score",
+                    "Enrichment P-value",
+                    "Enrichment Q-value",
+                    "Depletion P-value",
+                    "Depletion Q-value",
+                ]
+            ]
+            .dropna()
+            .reset_index(drop=True)
+        )
+
+        return results
+
+    @staticmethod
+    def _calculate_qvalues(pvals: np.ndarray) -> np.ndarray:
+        """Calculate q-values (FDR) for each row of a p-value matrix.
+
+        Args:
+            pvals (np.ndarray): 2D array of p-values.
+
+        Returns:
+            np.ndarray: 2D array of q-values, with FDR correction applied row-wise.
+        """
+        return np.apply_along_axis(lambda row: fdrcorrection(row)[1], 1, pvals)
+
+    def _get_significance_values(
+        self,
+        domain_id: int,
+        description: str,
+        enrichment_pvals: np.ndarray,
+        depletion_pvals: np.ndarray,
+        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.
+
+        Args:
+            domain_id (int): The domain ID associated with the annotation.
+            description (str): The annotation description.
+            enrichment_pvals (np.ndarray): Matrix of significance p-values.
+            depletion_pvals (np.ndarray): Matrix of depletion p-values.
+            enrichment_qvals (np.ndarray): Matrix of significance q-values.
+            depletion_qvals (np.ndarray): Matrix of depletion q-values.
+
+        Returns:
+            Tuple[Union[float, None], Union[float, None], Union[float, None], Union[float, None]]:
+                Minimum significance p-value, significance q-value, depletion p-value, depletion q-value.
+        """
+        try:
+            annotation_idx = self.annotations["ordered_annotations"].index(description)
+        except ValueError:
+            return None, None, None, None  # Description not found
+
+        node_indices = self.graph.domain_id_to_node_ids_map.get(domain_id, [])
+        if not node_indices:
+            return None, None, None, None  # No associated nodes
+
+        sig_p = enrichment_pvals[node_indices, annotation_idx]
+        dep_p = depletion_pvals[node_indices, annotation_idx]
+        sig_q = enrichment_qvals[node_indices, annotation_idx]
+        dep_q = depletion_qvals[node_indices, annotation_idx]
+
+        return (
+            np.min(sig_p) if sig_p.size > 0 else None,
+            np.min(sig_q) if sig_q.size > 0 else None,
+            np.min(dep_p) if dep_p.size > 0 else None,
+            np.min(dep_q) if dep_q.size > 0 else None,
+        )
+
+    def _get_annotation_members(self, description: str) -> str:
+        """Retrieve node labels associated with a given annotation description.
+
+        Args:
+            description (str): The annotation description.
+
+        Returns:
+            str: ';'-separated string of node labels that are associated with the annotation.
+        """
+        try:
+            annotation_idx = self.annotations["ordered_annotations"].index(description)
+        except ValueError:
+            return ""  # Description not found
+
+        nodes_present = np.where(self.annotations["matrix"][:, annotation_idx] == 1)[0]
+        node_labels = sorted(
+            self.graph.node_id_to_node_label_map[node_id]
+            for node_id in nodes_present
+            if node_id in self.graph.node_id_to_node_label_map
+        )
+        return ";".join(node_labels)

risk/network/io.py

@@ -165,12 +165,12 @@ class NetworkIO:
         filepath: str,
         source_label: str = "source",
         target_label: str = "target",
+        view_name: str = "",
         compute_sphere: bool = True,
         surface_depth: float = 0.0,
         min_edges_per_node: int = 0,
         include_edge_weight: bool = True,
         weight_label: str = "weight",
-        view_name: str = "",
     ) -> nx.Graph:
         """Load a network from a Cytoscape file.
 
@@ -178,7 +178,7 @@ class NetworkIO:
             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 None.
+            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.
@@ -215,7 +215,7 @@ class NetworkIO:
             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 None.
+            view_name (str, optional): Specific view name to load. Defaults to "".
 
         Returns:
             nx.Graph: Loaded and processed network.

risk/network/plot/contour.py

@@ -294,7 +294,7 @@ class Contour:
                 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 color scaling based on enrichment scores.
+            scale_factor (float, optional): Exponent for adjusting color scaling based on significance 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. Defaults to 888.
 

risk/network/plot/labels.py

@@ -659,7 +659,7 @@ class Labels:
                 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 color scaling based on enrichment scores.
+            scale_factor (float, optional): Exponent for adjusting color scaling based on significance 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. Defaults to 888.
 

risk/network/plot/network.py

@@ -203,11 +203,11 @@ class Network:
         max_scale: float = 1.0,
         scale_factor: float = 1.0,
         alpha: Union[float, None] = 1.0,
-        nonenriched_color: Union[str, List, Tuple, np.ndarray] = "white",
-        nonenriched_alpha: Union[float, None] = 1.0,
+        nonsignificant_color: Union[str, List, Tuple, np.ndarray] = "white",
+        nonsignificant_alpha: Union[float, None] = 1.0,
         random_seed: int = 888,
     ) -> np.ndarray:
-        """Adjust the colors of nodes in the network graph based on enrichment.
+        """Adjust the colors of nodes in the network graph based on significance.
 
         Args:
             cmap (str, optional): Colormap to use for coloring the nodes. Defaults to "gist_rainbow".
@@ -218,16 +218,16 @@ class Network:
             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): Factor for adjusting the color scaling intensity. Defaults to 1.0.
-            alpha (float, None, optional): Alpha value for enriched nodes. If provided, it overrides any existing alpha values found in `color`.
+            alpha (float, None, optional): Alpha value for significant nodes. If provided, it overrides any existing alpha values found in `color`.
                 Defaults to 1.0.
-            nonenriched_color (str, List, Tuple, or np.ndarray, optional): Color for non-enriched nodes. Can be a single color or an array of colors.
+            nonsignificant_color (str, List, Tuple, or np.ndarray, optional): Color for non-significant nodes. Can be a single color or an array of colors.
                 Defaults to "white".
-            nonenriched_alpha (float, None, optional): Alpha value for non-enriched nodes. If provided, it overrides any existing alpha values found
-                in `nonenriched_color`. Defaults to 1.0.
+            nonsignificant_alpha (float, None, optional): Alpha value for non-significant nodes. If provided, it overrides any existing alpha values found
+                in `nonsignificant_color`. Defaults to 1.0.
             random_seed (int, optional): Seed for random number generation. Defaults to 888.
 
         Returns:
-            np.ndarray: Array of RGBA colors adjusted for enrichment status.
+            np.ndarray: Array of RGBA colors adjusted for significance status.
         """
         # Get the initial domain colors for each node, which are returned as RGBA
         network_colors = get_domain_colors(
@@ -241,11 +241,11 @@ class Network:
             scale_factor=scale_factor,
             random_seed=random_seed,
         )
-        # Apply the alpha value for enriched nodes
-        network_colors[:, 3] = alpha  # Apply the alpha value to the enriched nodes' A channel
-        # Convert the non-enriched color to RGBA using the to_rgba helper function
-        nonenriched_color_rgba = to_rgba(
-            color=nonenriched_color, alpha=nonenriched_alpha, num_repeats=1
+        # Apply the alpha value for significant nodes
+        network_colors[:, 3] = alpha  # Apply the alpha value to the significant nodes' A channel
+        # Convert the non-significant color to RGBA using the to_rgba helper function
+        nonsignificant_color_rgba = to_rgba(
+            color=nonsignificant_color, alpha=nonsignificant_alpha, num_repeats=1
         )  # num_repeats=1 for a single color
         # Adjust node colors: replace any nodes where all three RGB values are equal and less than 0.1
         # 0.1 is a predefined threshold for the minimum color intensity
@@ -255,34 +255,34 @@ class Network:
                 & np.all(network_colors[:, :3] == network_colors[:, 0:1], axis=1)
             )[:, None],
             np.tile(
-                np.array(nonenriched_color_rgba), (network_colors.shape[0], 1)
-            ),  # Replace with the full RGBA non-enriched color
+                np.array(nonsignificant_color_rgba), (network_colors.shape[0], 1)
+            ),  # Replace with the full RGBA non-significant color
             network_colors,  # Keep the original colors where no match is found
         )
         return adjusted_network_colors
 
     def get_annotated_node_sizes(
-        self, enriched_size: int = 50, nonenriched_size: int = 25
+        self, significant_size: int = 50, nonsignificant_size: int = 25
     ) -> np.ndarray:
-        """Adjust the sizes of nodes in the network graph based on whether they are enriched or not.
+        """Adjust the sizes of nodes in the network graph based on whether they are significant or not.
 
         Args:
-            enriched_size (int): Size for enriched nodes. Defaults to 50.
-            nonenriched_size (int): Size for non-enriched nodes. Defaults to 25.
+            significant_size (int): Size for significant nodes. Defaults to 50.
+            nonsignificant_size (int): Size for non-significant nodes. Defaults to 25.
 
         Returns:
-            np.ndarray: Array of node sizes, with enriched nodes larger than non-enriched ones.
+            np.ndarray: Array of node sizes, with significant nodes larger than non-significant ones.
         """
-        # Merge all enriched nodes from the domain_id_to_node_ids_map dictionary
-        enriched_nodes = set()
+        # Merge all significant nodes from the domain_id_to_node_ids_map dictionary
+        significant_nodes = set()
         for _, node_ids in self.graph.domain_id_to_node_ids_map.items():
-            enriched_nodes.update(node_ids)
+            significant_nodes.update(node_ids)
 
-        # Initialize all node sizes to the non-enriched size
-        node_sizes = np.full(len(self.graph.network.nodes), nonenriched_size)
-        # Set the size for enriched nodes
-        for node in enriched_nodes:
+        # Initialize all node sizes to the non-significant size
+        node_sizes = np.full(len(self.graph.network.nodes), nonsignificant_size)
+        # Set the size for significant nodes
+        for node in significant_nodes:
             if node in self.graph.network.nodes:
-                node_sizes[node] = enriched_size
+                node_sizes[node] = significant_size
 
         return node_sizes

risk/network/plot/utils/color.py

@@ -35,14 +35,14 @@ def get_annotated_domain_colors(
         blend_gamma (float, optional): Gamma correction factor for perceptual color blending. Defaults to 2.2.
         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
+        scale_factor (float, optional): Factor for adjusting the contrast in the colors generated based on significance. 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
+    # Generate domain colors based on the significance data
     node_colors = get_domain_colors(
         graph=graph,
         cmap=cmap,
@@ -82,7 +82,7 @@ def get_domain_colors(
     scale_factor: float = 1.0,
     random_seed: int = 888,
 ) -> np.ndarray:
-    """Generate composite colors for domains based on enrichment or specified colors.
+    """Generate composite colors for domains based on significance or specified colors.
 
     Args:
         graph (NetworkGraph): The network data and attributes to be visualized.
@@ -95,12 +95,12 @@ def get_domain_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. Higher values increase
+        scale_factor (float, optional): Exponent for adjusting the color scaling based on significance scores. Higher values increase
             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.
+        np.ndarray: Array of RGBA colors generated for each domain, based on significance or the specified color.
     """
     # Get colors for each domain
     domain_colors = _get_domain_colors(graph=graph, cmap=cmap, color=color, random_seed=random_seed)
@@ -111,7 +111,7 @@ def get_domain_colors(
     # Transform colors to ensure proper alpha values and intensity
     transformed_colors = _transform_colors(
         node_colors,
-        graph.node_enrichment_sums,
+        graph.node_significance_sums,
         min_scale=min_scale,
         max_scale=max_scale,
         scale_factor=scale_factor,
@@ -151,7 +151,7 @@ def _get_domain_colors(
 def _get_composite_node_colors(
     graph, domain_colors: np.ndarray, blend_colors: bool = False, blend_gamma: float = 2.2
 ) -> np.ndarray:
-    """Generate composite colors for nodes based on domain colors and enrichment values, with optional color blending.
+    """Generate composite colors for nodes based on domain colors and significance values, with optional color blending.
 
     Args:
         graph (NetworkGraph): The network data and attributes to be visualized.
@@ -177,26 +177,26 @@ def _get_composite_node_colors(
 
     # If blending is required
     else:
-        for node, node_info in graph.node_id_to_domain_ids_and_enrichments_map.items():
+        for node, node_info in graph.node_id_to_domain_ids_and_significance_map.items():
             domains = node_info["domains"]  # List of domain IDs
-            enrichments = node_info["enrichments"]  # List of enrichment values
-            # Filter domains and enrichments to keep only those with corresponding colors in domain_colors
-            filtered_domains_enrichments = [
-                (domain_id, enrichment)
-                for domain_id, enrichment in zip(domains, enrichments)
+            significances = node_info["significances"]  # List of significance values
+            # Filter domains and significances to keep only those with corresponding colors in domain_colors
+            filtered_domains_significances = [
+                (domain_id, significance)
+                for domain_id, significance in zip(domains, significances)
                 if domain_id in domain_colors
             ]
             # If no valid domains exist, skip this node
-            if not filtered_domains_enrichments:
+            if not filtered_domains_significances:
                 continue
 
-            # Unpack filtered domains and enrichments
-            filtered_domains, filtered_enrichments = zip(*filtered_domains_enrichments)
+            # Unpack filtered domains and significances
+            filtered_domains, filtered_significances = zip(*filtered_domains_significances)
             # Get the colors corresponding to the valid filtered domains
             colors = [domain_colors[domain_id] for domain_id in filtered_domains]
             # Blend the colors using the given gamma (default is 2.2 if None)
             gamma = blend_gamma if blend_gamma is not None else 2.2
-            composite_color = _blend_colors_perceptually(colors, filtered_enrichments, gamma)
+            composite_color = _blend_colors_perceptually(colors, filtered_significances, gamma)
             # Assign the composite color to the node
             composite_colors[node] = composite_color
 
@@ -282,21 +282,21 @@ def _assign_distant_colors(dist_matrix, num_colors_to_generate):
 
 
 def _blend_colors_perceptually(
-    colors: Union[List, Tuple, np.ndarray], enrichments: List[float], gamma: float = 2.2
+    colors: Union[List, Tuple, np.ndarray], significances: List[float], gamma: float = 2.2
 ) -> Tuple[float, float, float, float]:
     """Blends a list of RGBA colors using gamma correction for perceptually uniform color mixing.
 
     Args:
         colors (List, Tuple, np.ndarray): List of RGBA colors. Can be a list, tuple, or NumPy array of RGBA values.
-        enrichments (List[float]): Corresponding list of enrichment values.
+        significances (List[float]): Corresponding list of significance values.
         gamma (float, optional): Gamma correction factor, default is 2.2 (typical for perceptual blending).
 
     Returns:
         Tuple[float, float, float, float]: The blended RGBA color.
     """
-    # Normalize enrichments so they sum up to 1 (proportions)
-    total_enrichment = sum(enrichments)
-    proportions = [enrichment / total_enrichment for enrichment in enrichments]
+    # Normalize significances so they sum up to 1 (proportions)
+    total_significance = sum(significances)
+    proportions = [significance / total_significance for significance in significances]
     # Convert colors to gamma-corrected space (apply gamma correction to RGB channels)
     gamma_corrected_colors = [[channel**gamma for channel in color[:3]] for color in colors]
     # Blend the colors in gamma-corrected space
@@ -310,17 +310,17 @@ def _blend_colors_perceptually(
 
 def _transform_colors(
     colors: np.ndarray,
-    enrichment_sums: np.ndarray,
+    significance_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
+    """Transform colors using power scaling to emphasize high significance 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.
+        significance_sums (np.ndarray): An array of significance 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
@@ -340,8 +340,8 @@ def _transform_colors(
     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)
+    # Normalize the significance sums to the range [0, 1]
+    normalized_sums = significance_sums / np.max(significance_sums)
     # Apply power scaling to dim lower values and emphasize higher values
     scaled_sums = normalized_sums**scale_factor
     # Linearly scale the normalized sums to the range [min_scale, max_scale]