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

risk/network/plotter/api.py

@@ -0,0 +1,54 @@
+"""
+risk/network/plotter/api
+~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import List, Tuple, Union
+
+import numpy as np
+
+from risk.log import log_header
+from risk.network.graph.graph import Graph
+from risk.network.plotter.plotter import Plotter
+
+
+class PlotterAPI:
+    """Handles the loading of network plotter objects.
+
+    The PlotterAPI class provides methods to load and configure Plotter objects for plotting network graphs.
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    def load_plotter(
+        self,
+        graph: Graph,
+        figsize: Union[List, Tuple, np.ndarray] = (10, 10),
+        background_color: str = "white",
+        background_alpha: Union[float, None] = 1.0,
+        pad: float = 0.3,
+    ) -> Plotter:
+        """Get a Plotter object for plotting.
+
+        Args:
+            graph (Graph): The graph to plot.
+            figsize (List, Tuple, or np.ndarray, optional): Size of the plot. Defaults to (10, 10)., optional): Size of the figure. Defaults to (10, 10).
+            background_color (str, optional): Background color of the plot. Defaults to "white".
+            background_alpha (float, None, optional): Transparency level of the background color. If provided, it overrides
+                any existing alpha values found in background_color. Defaults to 1.0.
+            pad (float, optional): Padding value to adjust the axis limits. Defaults to 0.3.
+
+        Returns:
+            Plotter: A Plotter object configured with the given parameters.
+        """
+        log_header("Loading plotter")
+
+        # Initialize and return a Plotter object
+        return Plotter(
+            graph,
+            figsize=figsize,
+            background_color=background_color,
+            background_alpha=background_alpha,
+            pad=pad,
+        )

risk/network/plotter/canvas.py

@@ -0,0 +1,291 @@
+"""
+risk/network/plotter/canvas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import List, Tuple, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from risk.log import params
+from risk.network.graph.graph import Graph
+from risk.network.plotter.utils.colors import to_rgba
+from risk.network.plotter.utils.layout import calculate_bounding_box
+
+
+class Canvas:
+    """A class for laying out the canvas in a network graph."""
+
+    def __init__(self, graph: Graph, ax: plt.Axes) -> None:
+        """Initialize the Canvas with a Graph and axis for plotting.
+
+        Args:
+            graph (Graph): The Graph object containing the network data.
+            ax (plt.Axes): The axis to plot the canvas on.
+        """
+        self.graph = graph
+        self.ax = ax
+
+    def plot_title(
+        self,
+        title: Union[str, None] = None,
+        subtitle: Union[str, None] = None,
+        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_x: float = 0.5,
+        title_y: float = 0.975,
+        title_space_offset: float = 0.075,
+        subtitle_offset: float = 0.025,
+    ) -> None:
+        """Plot title and subtitle on the network graph with customizable parameters.
+
+        Args:
+            title (str, optional): Title of the plot. Defaults to None.
+            subtitle (str, optional): Subtitle of the plot. Defaults to None.
+            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.
+                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.
+                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.
+        """
+        # Log the title and subtitle parameters
+        params.log_plotter(
+            title=title,
+            subtitle=subtitle,
+            title_fontsize=title_fontsize,
+            subtitle_fontsize=subtitle_fontsize,
+            title_subtitle_font=font,
+            title_color=title_color,
+            subtitle_color=subtitle_color,
+            subtitle_offset=subtitle_offset,
+            title_y=title_y,
+            title_space_offset=title_space_offset,
+        )
+
+        # Get the current figure and axis dimensions
+        fig = self.ax.figure
+        # Use a tight layout to ensure that title and subtitle do not overlap with the original plot
+        fig.tight_layout(
+            rect=[0, 0, 1, 1 - title_space_offset]
+        )  # Leave space above the plot for title
+
+        # Plot title if provided
+        if title:
+            # Set the title using figure's suptitle to ensure centering
+            self.ax.figure.suptitle(
+                title,
+                fontsize=title_fontsize,
+                color=title_color,
+                fontname=font,
+                x=title_x,
+                ha="center",
+                va="top",
+                y=title_y,
+            )
+
+        # Plot subtitle if provided
+        if subtitle:
+            # Calculate the subtitle's y position based on the midpoint of the title and subtitle_offset
+            # Calculate the approximate height of the title in relative axis units
+            title_height = title_fontsize / fig.bbox.height
+            # Position the subtitle relative to the title's center (title_y - half the title height)
+            subtitle_y_position = title_y - (title_height / 2) - subtitle_offset
+            self.ax.figure.text(
+                0.5,  # Ensure horizontal centering for subtitle
+                subtitle_y_position,  # Position subtitle based on the center of the title
+                subtitle,
+                ha="center",
+                va="top",
+                fontname=font,
+                fontsize=subtitle_fontsize,
+                color=subtitle_color,
+            )
+
+    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",
+        outline_alpha: Union[float, None] = 1.0,
+        fill_alpha: Union[float, None] = 0.0,
+    ) -> None:
+        """Plot a circle around the network graph to represent the network perimeter.
+
+        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".
+            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
+                found in color. Defaults to 0.0.
+        """
+        # Log the circle perimeter plotting parameters
+        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=(
+                "custom" if isinstance(color, (list, tuple, np.ndarray)) else color
+            ),  # np.ndarray usually indicates custom colors
+            perimeter_outline_alpha=outline_alpha,
+            perimeter_fill_alpha=fill_alpha,
+        )
+
+        # 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 = self._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(
+            adjusted_center,
+            scaled_radius,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            color=outline_color_rgba,
+        )
+        # Set the transparency of the fill if applicable
+        circle.set_facecolor(
+            to_rgba(color=fill_color_rgba, num_repeats=1)
+        )  # num_repeats=1 for a single color
+
+        self.ax.add_artist(circle)
+
+    def plot_contour_perimeter(
+        self,
+        scale: float = 1.0,
+        levels: int = 3,
+        bandwidth: float = 0.8,
+        grid_size: int = 250,
+        color: Union[str, List, Tuple, np.ndarray] = "black",
+        linestyle: str = "solid",
+        linewidth: float = 1.5,
+        outline_alpha: Union[float, None] = 1.0,
+        fill_alpha: Union[float, None] = 0.0,
+    ) -> None:
+        """
+        Plot a KDE-based contour around the network graph to represent the network perimeter.
+
+        Args:
+            scale (float, optional): Scaling factor for the perimeter size. Defaults to 1.0.
+            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".
+            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
+                alpha values found in color. Defaults to 1.0.
+            fill_alpha (float, None, optional): Transparency level of the contour fill. If provided, it overrides any existing alpha
+                values found in color. Defaults to 0.0.
+        """
+        # Log the contour perimeter plotting parameters
+        params.log_plotter(
+            perimeter_type="contour",
+            perimeter_scale=scale,
+            perimeter_levels=levels,
+            perimeter_bandwidth=bandwidth,
+            perimeter_grid_size=grid_size,
+            perimeter_linestyle=linestyle,
+            perimeter_linewidth=linewidth,
+            perimeter_color=("custom" if isinstance(color, (list, tuple, np.ndarray)) else color),
+            perimeter_outline_alpha=outline_alpha,
+            perimeter_fill_alpha=fill_alpha,
+        )
+
+        # Convert color to RGBA using outline_alpha for the line (outline)
+        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 Plotter
+        self._draw_kde_contour(
+            ax=self.ax,
+            pos=scaled_coordinates,
+            nodes=list(range(len(node_coordinates))),  # All nodes are included
+            levels=levels,
+            bandwidth=bandwidth,
+            grid_size=grid_size,
+            color=outline_color_rgba,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            fill_alpha=fill_alpha,
+        )
+
+    def _calculate_adjusted_center(
+        self,
+        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/plotter/contour.py

@@ -0,0 +1,329 @@
+"""
+risk/network/plotter/contour
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""
+
+from typing import Any, Dict, List, Tuple, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+from scipy import linalg
+from scipy.ndimage import label
+from scipy.stats import gaussian_kde
+
+from risk.log import logger, params
+from risk.network.graph.graph import Graph
+from risk.network.plotter.utils.colors import get_annotated_domain_colors, to_rgba
+
+
+class Contour:
+    """Class to generate Kernel Density Estimate (KDE) contours for nodes in a network graph."""
+
+    def __init__(self, graph: Graph, ax: plt.Axes) -> None:
+        """Initialize the Contour with a Graph and axis for plotting.
+
+        Args:
+            graph (Graph): The Graph object containing the network data.
+            ax (plt.Axes): The axis to plot the contours on.
+        """
+        self.graph = graph
+        self.ax = ax
+
+    def plot_contours(
+        self,
+        levels: int = 5,
+        bandwidth: float = 0.8,
+        grid_size: int = 250,
+        color: Union[str, List, Tuple, np.ndarray] = "white",
+        linestyle: str = "solid",
+        linewidth: float = 1.5,
+        alpha: Union[float, None] = 1.0,
+        fill_alpha: Union[float, None] = None,
+    ) -> None:
+        """Draw KDE contours for nodes in various domains of a network graph, highlighting areas of high density.
+
+        Args:
+            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.
+                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.
+            alpha (float, None, optional): Transparency level of 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 of the contour fill. If provided, it overrides any existing alpha
+                values found in color. Defaults to None.
+        """
+        # Log the contour plotting parameters
+        params.log_plotter(
+            contour_levels=levels,
+            contour_bandwidth=bandwidth,
+            contour_grid_size=grid_size,
+            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_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_rgba[idx],
+                    levels=levels,
+                    bandwidth=bandwidth,
+                    grid_size=grid_size,
+                    linestyle=linestyle,
+                    linewidth=linewidth,
+                    fill_alpha=current_fill_alpha,
+                )
+
+    def plot_subcontour(
+        self,
+        nodes: Union[List, Tuple, np.ndarray],
+        levels: int = 5,
+        bandwidth: float = 0.8,
+        grid_size: int = 250,
+        color: Union[str, List, Tuple, np.ndarray] = "white",
+        linestyle: str = "solid",
+        linewidth: float = 1.5,
+        alpha: Union[float, None] = 1.0,
+        fill_alpha: Union[float, None] = None,
+    ) -> None:
+        """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.
+            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.
+                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.
+            alpha (float, None, optional): Transparency level of 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 of the contour fill. If provided, it overrides any existing alpha
+            values found in color. Defaults to None.
+
+        Raises:
+            ValueError: If no valid nodes are found in the network graph.
+        """
+        # Check if nodes is a list of lists or a flat list
+        if any(isinstance(item, (list, tuple, np.ndarray)) for item in nodes):
+            # If it's a list of lists, iterate over sublists
+            node_groups = nodes
+            # Convert color to RGBA arrays to match the number of groups
+            color_rgba = to_rgba(color=color, alpha=alpha, num_repeats=len(node_groups))
+        else:
+            # If it's a flat list of nodes, treat it as a single group
+            node_groups = [nodes]
+            # Wrap the RGBA color in an array to index the first element
+            color_rgba = to_rgba(color=color, alpha=alpha, num_repeats=1)
+
+        # Iterate over each group of nodes (either sublists or flat list)
+        for idx, sublist in enumerate(node_groups):
+            # Filter to get node IDs and their coordinates for each sublist
+            node_ids = [
+                self.graph.node_label_to_node_id_map.get(node)
+                for node in sublist
+                if node in self.graph.node_label_to_node_id_map
+            ]
+            if not node_ids or len(node_ids) == 1:
+                raise ValueError(
+                    "No nodes found in the network graph or insufficient nodes to plot."
+                )
+
+            # 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,
+                node_ids,
+                color=color_rgba[idx],
+                levels=levels,
+                bandwidth=bandwidth,
+                grid_size=grid_size,
+                linestyle=linestyle,
+                linewidth=linewidth,
+                fill_alpha=current_fill_alpha,
+            )
+
+    def _draw_kde_contour(
+        self,
+        ax: plt.Axes,
+        pos: np.ndarray,
+        nodes: List,
+        levels: int = 5,
+        bandwidth: float = 0.8,
+        grid_size: int = 250,
+        color: Union[str, np.ndarray] = "white",
+        linestyle: str = "solid",
+        linewidth: float = 1.5,
+        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.
+
+        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.
+            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.
+            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  # Not enough points to form a contour
+
+        # Check if the KDE forms a single connected component
+        connected = False
+        z = None  # Initialize z to None to avoid UnboundLocalError
+        while not connected and bandwidth <= 100.0:
+            try:
+                # Perform KDE on the points with the given bandwidth
+                kde = gaussian_kde(points.T, bw_method=bandwidth)
+                xmin, ymin = points.min(axis=0) - bandwidth
+                xmax, ymax = points.max(axis=0) + bandwidth
+                x, y = np.mgrid[
+                    xmin : xmax : complex(0, grid_size), ymin : ymax : complex(0, grid_size)
+                ]
+                z = kde(np.vstack([x.ravel(), y.ravel()])).reshape(x.shape)
+                # Check if the KDE forms a single connected component
+                connected = self._is_connected(z)
+                if not connected:
+                    bandwidth += 0.05  # Increase bandwidth slightly and retry
+            except linalg.LinAlgError:
+                bandwidth += 0.05  # Increase bandwidth and retry
+            except Exception as e:
+                # Catch any other exceptions and log them
+                logger.error(f"Unexpected error when drawing KDE contour: {e}")
+                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
+
+        # Define contour levels based on the density
+        min_density, max_density = z.min(), z.max()
+        if min_density == max_density:
+            logger.warning(
+                "Contour levels could not be created due to lack of variation in density."
+            )
+            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
+
+        # 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,
+                z,
+                levels=contour_levels,
+                colors=contour_colors,
+                antialiased=True,
+                alpha=fill_alpha,
+            )
+
+        # 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=base_contour_level,
+            colors=base_contour_color,
+            linestyles=linestyle,
+            linewidths=linewidth,
+        )
+
+    def get_annotated_contour_colors(
+        self,
+        cmap: str = "gist_rainbow",
+        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.
+                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 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:
+            np.ndarray: Array of RGBA colors for contour annotations.
+        """
+        return get_annotated_domain_colors(
+            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,
+        )
+
+    def _is_connected(self, z: np.ndarray) -> bool:
+        """Determine if a thresholded grid represents a single, connected component.
+
+        Args:
+            z (np.ndarray): A binary grid where the component connectivity is evaluated.
+
+        Returns:
+            bool: True if the grid represents a single connected component, False otherwise.
+        """
+        _, num_features = label(z)
+        return num_features == 1  # Return True if only one connected component is found