risk-network 0.0.8b18__py3-none-any.whl → 0.0.9b26__py3-none-any.whl

risk/network/{plot → plotter}/canvas.py

@@ -9,9 +9,9 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 from risk.log import params
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.color import to_rgba
-from risk.network.plot.utils.layout import calculate_bounding_box
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.utils.colors import to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
 
 
 class Canvas:
@@ -34,8 +34,9 @@ class Canvas:
         title_fontsize: int = 20,
         subtitle_fontsize: int = 14,
         font: str = "Arial",
-        title_color: Union[str, list, tuple, np.ndarray] = "black",
-        subtitle_color: Union[str, list, tuple, np.ndarray] = "gray",
+        title_color: Union[str, List, Tuple, np.ndarray] = "black",
+        subtitle_color: Union[str, List, Tuple, np.ndarray] = "gray",
+        title_x: float = 0.5,
         title_y: float = 0.975,
         title_space_offset: float = 0.075,
         subtitle_offset: float = 0.025,
@@ -48,10 +49,11 @@ class Canvas:
             title_fontsize (int, optional): Font size for the title. Defaults to 20.
             subtitle_fontsize (int, optional): Font size for the subtitle. Defaults to 14.
             font (str, optional): Font family used for both title and subtitle. Defaults to "Arial".
-            title_color (str, list, tuple, or np.ndarray, optional): Color of the title text. Can be a string or an array of colors.
+            title_color (str, List, Tuple, or np.ndarray, optional): Color of the title text. Can be a string or an array of colors.
                 Defaults to "black".
-            subtitle_color (str, list, tuple, or np.ndarray, optional): Color of the subtitle text. Can be a string or an array of colors.
+            subtitle_color (str, List, Tuple, or np.ndarray, optional): Color of the subtitle text. Can be a string or an array of colors.
                 Defaults to "gray".
+            title_x (float, optional): X-axis position of the title. Defaults to 0.5.
             title_y (float, optional): Y-axis position of the title. Defaults to 0.975.
             title_space_offset (float, optional): Fraction of figure height to leave for the space above the plot. Defaults to 0.075.
             subtitle_offset (float, optional): Offset factor to position the subtitle below the title. Defaults to 0.025.
@@ -85,7 +87,7 @@ class Canvas:
                 fontsize=title_fontsize,
                 color=title_color,
                 fontname=font,
-                x=0.5,  # Center the title horizontally
+                x=title_x,
                 ha="center",
                 va="top",
                 y=title_y,
@@ -112,6 +114,8 @@ class Canvas:
     def plot_circle_perimeter(
         self,
         scale: float = 1.0,
+        center_offset_x: float = 0.0,
+        center_offset_y: float = 0.0,
         linestyle: str = "dashed",
         linewidth: float = 1.5,
         color: Union[str, List, Tuple, np.ndarray] = "black",
@@ -122,9 +126,13 @@ class Canvas:
 
         Args:
             scale (float, optional): Scaling factor for the perimeter diameter. Defaults to 1.0.
+            center_offset_x (float, optional): Horizontal offset as a fraction of the diameter.
+                Negative values shift the center left, positive values shift it right. Defaults to 0.0.
+            center_offset_y (float, optional): Vertical offset as a fraction of the diameter.
+                Negative values shift the center down, positive values shift it up. Defaults to 0.0.
             linestyle (str, optional): Line style for the network perimeter circle (e.g., dashed, solid). Defaults to "dashed".
             linewidth (float, optional): Width of the circle's outline. Defaults to 1.5.
-            color (str, list, tuple, or np.ndarray, optional): Color of the network perimeter circle. Defaults to "black".
+            color (str, List, Tuple, or np.ndarray, optional): Color of the network perimeter circle. Defaults to "black".
             outline_alpha (float, None, optional): Transparency level of the circle outline. If provided, it overrides any existing alpha
                 values found in color. Defaults to 1.0.
             fill_alpha (float, None, optional): Transparency level of the circle fill. If provided, it overrides any existing alpha values
@@ -134,6 +142,8 @@ class Canvas:
         params.log_plotter(
             perimeter_type="circle",
             perimeter_scale=scale,
+            perimeter_center_offset_x=center_offset_x,
+            perimeter_center_offset_y=center_offset_y,
             perimeter_linestyle=linestyle,
             perimeter_linewidth=linewidth,
             perimeter_color=(
@@ -143,33 +153,37 @@ class Canvas:
             perimeter_fill_alpha=fill_alpha,
         )
 
-        # Convert color to RGBA using the to_rgba helper function - use outline_alpha for the perimeter
-        color = to_rgba(
-            color=color, alpha=outline_alpha, num_repeats=1
-        )  # num_repeats=1 for a single color
-        # Set the fill_alpha to 0 if not provided
-        fill_alpha = fill_alpha if fill_alpha is not None else 0.0
         # Extract node coordinates from the network graph
         node_coordinates = self.graph.node_coordinates
         # Calculate the center and radius of the bounding box around the network
         center, radius = calculate_bounding_box(node_coordinates)
+        # Adjust the center based on user-defined offsets
+        adjusted_center = _calculate_adjusted_center(
+            center, radius, center_offset_x, center_offset_y
+        )
         # Scale the radius by the scale factor
         scaled_radius = radius * scale
 
+        # Convert color to RGBA using the to_rgba helper function - use outline_alpha for the perimeter
+        outline_color_rgba = to_rgba(
+            color=color, alpha=outline_alpha, num_repeats=1
+        )  # num_repeats=1 for a single color
+        fill_color_rgba = to_rgba(
+            color=color, alpha=fill_alpha, num_repeats=1
+        )  # num_repeats=1 for a single color
+
         # Draw a circle to represent the network perimeter
         circle = plt.Circle(
-            center,
+            adjusted_center,
             scaled_radius,
             linestyle=linestyle,
             linewidth=linewidth,
-            color=color,
-            fill=fill_alpha > 0,  # Fill the circle if fill_alpha is greater than 0
+            color=outline_color_rgba,
         )
         # Set the transparency of the fill if applicable
-        if fill_alpha > 0:
-            circle.set_facecolor(
-                to_rgba(color=color, alpha=fill_alpha, num_repeats=1)
-            )  # num_repeats=1 for a single color
+        circle.set_facecolor(
+            to_rgba(color=fill_color_rgba, num_repeats=1)
+        )  # num_repeats=1 for a single color
 
         self.ax.add_artist(circle)
 
@@ -193,7 +207,7 @@ class Canvas:
             levels (int, optional): Number of contour levels. Defaults to 3.
             bandwidth (float, optional): Bandwidth for the KDE. Controls smoothness. Defaults to 0.8.
             grid_size (int, optional): Grid resolution for the KDE. Higher values yield finer contours. Defaults to 250.
-            color (str, list, tuple, or np.ndarray, optional): Color of the network perimeter contour. Defaults to "black".
+            color (str, List, Tuple, or np.ndarray, optional): Color of the network perimeter contour. Defaults to "black".
             linestyle (str, optional): Line style for the network perimeter contour (e.g., dashed, solid). Defaults to "solid".
             linewidth (float, optional): Width of the contour's outline. Defaults to 1.5.
             outline_alpha (float, None, optional): Transparency level of the contour outline. If provided, it overrides any existing
@@ -216,12 +230,13 @@ class Canvas:
         )
 
         # Convert color to RGBA using outline_alpha for the line (outline)
-        outline_color = to_rgba(color=color, num_repeats=1)  # num_repeats=1 for a single color
+        outline_color_rgba = to_rgba(color=color, num_repeats=1)  # num_repeats=1 for a single color
         # Extract node coordinates from the network graph
         node_coordinates = self.graph.node_coordinates
         # Scale the node coordinates if needed
         scaled_coordinates = node_coordinates * scale
         # Use the existing _draw_kde_contour method
+        # NOTE: This is a technical debt that should be refactored in the future - only works when inherited by NetworkPlotter
         self._draw_kde_contour(
             ax=self.ax,
             pos=scaled_coordinates,
@@ -229,9 +244,48 @@ class Canvas:
             levels=levels,
             bandwidth=bandwidth,
             grid_size=grid_size,
-            color=outline_color,
+            color=outline_color_rgba,
             linestyle=linestyle,
             linewidth=linewidth,
-            alpha=outline_alpha,
             fill_alpha=fill_alpha,
         )
+
+
+def _calculate_adjusted_center(
+    center: Tuple[float, float],
+    radius: float,
+    center_offset_x: float = 0.0,
+    center_offset_y: float = 0.0,
+) -> Tuple[float, float]:
+    """Calculate the adjusted center for the network perimeter circle based on user-defined offsets.
+
+    Args:
+        center (Tuple[float, float]): Original center coordinates of the network graph.
+        radius (float): Radius of the bounding box around the network.
+        center_offset_x (float, optional): Horizontal offset as a fraction of the diameter.
+            Negative values shift the center left, positive values shift it right. Allowed
+            values are in the range [-1, 1]. Defaults to 0.0.
+        center_offset_y (float, optional): Vertical offset as a fraction of the diameter.
+            Negative values shift the center down, positive values shift it up. Allowed
+            values are in the range [-1, 1]. Defaults to 0.0.
+
+    Returns:
+        Tuple[float, float]: Adjusted center coordinates after applying the offsets.
+
+    Raises:
+        ValueError: If the center offsets are outside the valid range [-1, 1].
+    """
+    # Flip the y-axis to match the plot orientation
+    flipped_center_offset_y = -center_offset_y
+    # Validate the center offsets
+    if not -1 <= center_offset_x <= 1:
+        raise ValueError("Horizontal center offset must be in the range [-1, 1].")
+    if not -1 <= center_offset_y <= 1:
+        raise ValueError("Vertical center offset must be in the range [-1, 1].")
+
+    # Calculate adjusted center by applying offset fractions of the diameter
+    adjusted_center_x = center[0] + (center_offset_x * radius * 2)
+    adjusted_center_y = center[1] + (flipped_center_offset_y * radius * 2)
+
+    # Return the adjusted center coordinates
+    return adjusted_center_x, adjusted_center_y

risk/network/{plot → plotter}/contour.py

@@ -3,7 +3,7 @@ risk/network/plot/contour
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
-from typing import List, Tuple, Union
+from typing import Any, Dict, List, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -12,8 +12,8 @@ from scipy.ndimage import label
 from scipy.stats import gaussian_kde
 
 from risk.log import params, logger
-from risk.network.graph import NetworkGraph
-from risk.network.plot.utils.color import get_annotated_domain_colors, to_rgba
+from risk.network.graph.network import NetworkGraph
+from risk.network.plotter.utils.colors import get_annotated_domain_colors, to_rgba
 
 
 class Contour:
@@ -46,7 +46,7 @@ class Contour:
             levels (int, optional): Number of contour levels to plot. Defaults to 5.
             bandwidth (float, optional): Bandwidth for KDE. Controls the smoothness of the contour. Defaults to 0.8.
             grid_size (int, optional): Resolution of the grid for KDE. Higher values create finer contours. Defaults to 250.
-            color (str, list, tuple, or np.ndarray, optional): Color of the contours. Can be a single color or an array of colors.
+            color (str, List, Tuple, or np.ndarray, optional): Color of the contours. Can be a single color or an array of colors.
                 Defaults to "white".
             linestyle (str, optional): Line style for the contours. Defaults to "solid".
             linewidth (float, optional): Line width for the contours. Defaults to 1.5.
@@ -63,31 +63,34 @@ class Contour:
             contour_color=(
                 "custom" if isinstance(color, np.ndarray) else color
             ),  # np.ndarray usually indicates custom colors
+            contour_linestyle=linestyle,
+            contour_linewidth=linewidth,
             contour_alpha=alpha,
             contour_fill_alpha=fill_alpha,
         )
 
         # Ensure color is converted to RGBA with repetition matching the number of domains
-        color = to_rgba(
+        color_rgba = to_rgba(
             color=color, alpha=alpha, num_repeats=len(self.graph.domain_id_to_node_ids_map)
         )
         # Extract node coordinates from the network graph
         node_coordinates = self.graph.node_coordinates
         # Draw contours for each domain in the network
         for idx, (_, node_ids) in enumerate(self.graph.domain_id_to_node_ids_map.items()):
+            # Use the provided alpha value if it's not None, otherwise use the color's alpha
+            current_fill_alpha = fill_alpha if fill_alpha is not None else color_rgba[idx][3]
             if len(node_ids) > 1:
                 self._draw_kde_contour(
                     self.ax,
                     node_coordinates,
                     node_ids,
-                    color=color[idx],
+                    color=color_rgba[idx],
                     levels=levels,
                     bandwidth=bandwidth,
                     grid_size=grid_size,
                     linestyle=linestyle,
                     linewidth=linewidth,
-                    alpha=alpha,
-                    fill_alpha=fill_alpha,
+                    fill_alpha=current_fill_alpha,
                 )
 
     def plot_subcontour(
@@ -105,11 +108,11 @@ class Contour:
         """Plot a subcontour for a given set of nodes or a list of node sets using Kernel Density Estimation (KDE).
 
         Args:
-            nodes (list, tuple, or np.ndarray): List of node labels or list of lists of node labels to plot the contour for.
+            nodes (List, Tuple, or np.ndarray): List of node labels or list of lists of node labels to plot the contour for.
             levels (int, optional): Number of contour levels to plot. Defaults to 5.
             bandwidth (float, optional): Bandwidth for KDE. Controls the smoothness of the contour. Defaults to 0.8.
             grid_size (int, optional): Resolution of the grid for KDE. Higher values create finer contours. Defaults to 250.
-            color (str, list, tuple, or np.ndarray, optional): Color of the contour. Can be a string (e.g., 'white') or RGBA array.
+            color (str, List, Tuple, or np.ndarray, optional): Color of the contour. Can be a string (e.g., 'white') or RGBA array.
                 Can be a single color or an array of colors. Defaults to "white".
             linestyle (str, optional): Line style for the contour. Defaults to "solid".
             linewidth (float, optional): Line width for the contour. Defaults to 1.5.
@@ -148,6 +151,8 @@ class Contour:
 
             # Draw the KDE contour for the specified nodes
             node_coordinates = self.graph.node_coordinates
+            # Use the provided alpha value if it's not None, otherwise use the color's alpha
+            current_fill_alpha = fill_alpha if fill_alpha is not None else color_rgba[idx][3]
             self._draw_kde_contour(
                 self.ax,
                 node_coordinates,
@@ -158,8 +163,7 @@ class Contour:
                 grid_size=grid_size,
                 linestyle=linestyle,
                 linewidth=linewidth,
-                alpha=alpha,
-                fill_alpha=fill_alpha,
+                fill_alpha=current_fill_alpha,
             )
 
     def _draw_kde_contour(
@@ -173,7 +177,6 @@ class Contour:
         color: Union[str, np.ndarray] = "white",
         linestyle: str = "solid",
         linewidth: float = 1.5,
-        alpha: Union[float, None] = 1.0,
         fill_alpha: Union[float, None] = 0.2,
     ) -> None:
         """Draw a Kernel Density Estimate (KDE) contour plot for a set of nodes on a given axis.
@@ -181,22 +184,20 @@ class Contour:
         Args:
             ax (plt.Axes): The axis to draw the contour on.
             pos (np.ndarray): Array of node positions (x, y).
-            nodes (list): List of node indices to include in the contour.
+            nodes (List): List of node indices to include in the contour.
             levels (int, optional): Number of contour levels. Defaults to 5.
             bandwidth (float, optional): Bandwidth for the KDE. Controls smoothness. Defaults to 0.8.
             grid_size (int, optional): Grid resolution for the KDE. Higher values yield finer contours. Defaults to 250.
             color (str or np.ndarray): Color for the contour. Can be a string or RGBA array. Defaults to "white".
             linestyle (str, optional): Line style for the contour. Defaults to "solid".
             linewidth (float, optional): Line width for the contour. Defaults to 1.5.
-            alpha (float, None, optional): Transparency level for the contour lines. If provided, it overrides any existing alpha
-                values found in color. Defaults to 1.0.
             fill_alpha (float, None, optional): Transparency level for the contour fill. If provided, it overrides any existing
                 alpha values found in color. Defaults to 0.2.
         """
         # Extract the positions of the specified nodes
         points = np.array([pos[n] for n in nodes])
         if len(points) <= 1:
-            return None  # Not enough points to form a contour
+            return  # Not enough points to form a contour
 
         # Check if the KDE forms a single connected component
         connected = False
@@ -220,12 +221,12 @@ class Contour:
             except Exception as e:
                 # Catch any other exceptions and log them
                 logger.error(f"Unexpected error when drawing KDE contour: {e}")
-                return None
+                return
 
         # If z is still None, the KDE computation failed
         if z is None:
             logger.error("Failed to compute KDE. Skipping contour plot for these nodes.")
-            return None
+            return
 
         # Define contour levels based on the density
         min_density, max_density = z.min(), z.max()
@@ -233,18 +234,20 @@ class Contour:
             logger.warning(
                 "Contour levels could not be created due to lack of variation in density."
             )
-            return None
+            return
 
         # Create contour levels based on the density values
         contour_levels = np.linspace(min_density, max_density, levels)[1:]
         if len(contour_levels) < 2 or not np.all(np.diff(contour_levels) > 0):
             logger.error("Contour levels must be strictly increasing. Skipping contour plot.")
-            return None
+            return
 
-        # Set the contour color and linestyle
+        # Set the contour color, fill, and linestyle
         contour_colors = [color for _ in range(levels - 1)]
         # Plot the filled contours using fill_alpha for transparency
         if fill_alpha and fill_alpha > 0:
+            # Fill alpha works differently than alpha for contour lines
+            # Contour fill cannot be specified by RGBA, while contour lines can
             ax.contourf(
                 x,
                 y,
@@ -255,43 +258,46 @@ class Contour:
                 alpha=fill_alpha,
             )
 
-        # Plot the contour lines with the specified alpha for transparency
-        c = ax.contour(
+        # Plot the base contour line with the specified RGBA alpha for transparency
+        base_contour_color = [color]
+        base_contour_level = [contour_levels[0]]
+        ax.contour(
             x,
             y,
             z,
-            levels=contour_levels,
-            colors=contour_colors,
+            levels=base_contour_level,
+            colors=base_contour_color,
             linestyles=linestyle,
             linewidths=linewidth,
-            alpha=alpha,
         )
 
-        # Set linewidth for the contour lines to 0 for levels other than the base level
-        for i in range(1, len(contour_levels)):
-            c.collections[i].set_linewidth(0)
-
     def get_annotated_contour_colors(
         self,
         cmap: str = "gist_rainbow",
-        color: Union[str, list, tuple, np.ndarray, None] = None,
+        color: Union[str, List, Tuple, np.ndarray, None] = None,
+        blend_colors: bool = False,
+        blend_gamma: float = 2.2,
         min_scale: float = 0.8,
         max_scale: float = 1.0,
         scale_factor: float = 1.0,
+        ids_to_colors: Union[Dict[int, Any], None] = None,
         random_seed: int = 888,
     ) -> np.ndarray:
         """Get colors for the contours based on node annotations or a specified colormap.
 
         Args:
             cmap (str, optional): Name of the colormap to use for generating contour colors. Defaults to "gist_rainbow".
-            color (str, list, tuple, np.ndarray, or None, optional): Color to use for the contours. Can be a single color or an array of colors.
+            color (str, List, Tuple, np.ndarray, or None, optional): Color to use for the contours. Can be a single color or an array of colors.
                 If None, the colormap will be used. Defaults to None.
+            blend_colors (bool, optional): Whether to blend colors for nodes with multiple domains. Defaults to False.
+            blend_gamma (float, optional): Gamma correction factor for perceptual color blending. Defaults to 2.2.
             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 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.
+            ids_to_colors (Dict[int, Any], None, optional): Mapping of domain IDs to specific colors. Defaults to None.
             random_seed (int, optional): Seed for random number generation to ensure reproducibility. Defaults to 888.
 
         Returns:
@@ -301,9 +307,12 @@ class Contour:
             graph=self.graph,
             cmap=cmap,
             color=color,
+            blend_colors=blend_colors,
+            blend_gamma=blend_gamma,
             min_scale=min_scale,
             max_scale=max_scale,
             scale_factor=scale_factor,
+            ids_to_colors=ids_to_colors,
             random_seed=random_seed,
         )