bsplot 0.0.2__py3-none-any.whl

bsplot/graph/network.py

@@ -0,0 +1,974 @@
+import numpy as np
+import networkx as nx
+import matplotlib.pyplot as plt
+import nibabel
+import bsplot
+from bsplot.colors import Colormap as _resolve_cmap
+from bsplot.data.surface import get_surface_geometry
+from bsplot import data
+
+
+def _normalize_scale_values(raw_values, mode="linear"):
+    """Normalize values to [0, 1] for mesh radius scaling.
+
+    Uses percentile clipping for linear/log/exp modes to reduce outlier
+    dominance. "quantile" mode maps values to rank percentiles directly,
+    which is useful for dense graphs where geometric contrast is subtle.
+    """
+    values = np.asarray(raw_values, dtype=float)
+    if values.size == 0:
+        return values
+
+    if values.size == 1:
+        return np.array([0.5], dtype=float)
+
+    if mode == "quantile":
+        order = np.argsort(values, kind="mergesort")
+        ranks = np.empty(values.size, dtype=float)
+        ranks[order] = np.linspace(0.0, 1.0, values.size)
+        return ranks
+
+    lo = np.percentile(values, 5)
+    hi = np.percentile(values, 95)
+    if hi <= lo:
+        lo = np.min(values)
+        hi = np.max(values)
+
+    if hi <= lo:
+        norm = np.full(values.size, 0.5, dtype=float)
+    else:
+        clipped = np.clip(values, lo, hi)
+        norm = (clipped - lo) / (hi - lo)
+
+    if mode == "log":
+        # log scaling: spreads out lower values
+        norm = np.log1p(norm * 9.0) / np.log(10.0)
+    elif mode == "exp":
+        # exp scaling: emphasizes higher values
+        norm = (np.exp(norm * 2.0) - 1.0) / (np.exp(2.0) - 1.0)
+
+    return norm
+
+
+def _compute_scale_multiplier(raw_values, factor, mode="linear"):
+    """Compute multiplicative radius factors from raw values.
+
+    Returns values in [1, factor] after normalization and mode transform.
+    """
+    factor = float(factor)
+    normalized = _normalize_scale_values(raw_values, mode=mode)
+    if normalized.size == 0:
+        return normalized
+    return 1.0 + normalized * (factor - 1.0)
+
+
+def get_centers_from_surface_parc(vertices, labels, exclude_zero=True, on_surface=True):
+    """
+    Compute parcel centroids from surface vertices and parcellation labels.
+
+    Parameters
+    ----------
+    vertices : ndarray, shape (n_vertices, 3)
+        Surface vertex coordinates
+    labels : ndarray, shape (n_vertices,)
+        Parcellation labels for each vertex
+    exclude_zero : bool
+        Whether to exclude label 0 (typically "unknown")
+    on_surface : bool
+        If True, project centroids to the nearest vertex on the surface
+        to ensure centers lie exactly on the cortical surface.
+        If False, return the mean coordinate (may be inside the brain).
+
+    Returns
+    -------
+    centers : dict
+        Dictionary mapping label (int) -> centroid coordinates (ndarray, shape (3,))
+    """
+    unique_labels = np.unique(labels)
+    if exclude_zero:
+        unique_labels = unique_labels[unique_labels != 0]
+
+    centers = {}
+    for label in unique_labels:
+        mask = labels == label
+        parcel_vertices = vertices[mask]
+        centroid = parcel_vertices.mean(axis=0)
+
+        if on_surface:
+            # Project centroid to nearest vertex within the parcel
+            distances = np.linalg.norm(parcel_vertices - centroid, axis=1)
+            nearest_idx = np.argmin(distances)
+            centers[int(label)] = parcel_vertices[nearest_idx]
+        else:
+            centers[int(label)] = centroid
+
+    return centers
+
+
+def create_network(
+    centers,
+    connectivity_matrix,
+    labels=None,
+    threshold_percentile=95,
+    directed=False,
+    edge_data_key="weight",
+    node_types=None,
+):
+    """
+    Create a NetworkX graph from parcel centers and connectivity matrix.
+
+    Parameters
+    ----------
+    centers : dict
+        Dictionary mapping label -> (x, y, z) coordinates
+    connectivity_matrix : ndarray or dict[str, ndarray]
+        Connectivity matrix. Can be asymmetric for directed graphs.
+        For multilayer graphs, pass a dict mapping layer_name -> matrix.
+    labels : list, optional
+        Ordered list of labels corresponding to matrix rows/cols.
+        If None, uses sorted keys from centers.
+    threshold_percentile : float
+        Only include edges above this percentile (0-100). Set to 0 for all edges.
+    directed : bool
+        If True, create a MultiDiGraph; otherwise create a Graph.
+    edge_data_key : str
+        Semantic edge attribute key used to store matrix values (e.g., "gain").
+        When different from "weight", a compatibility "weight" attribute is
+        also stored with the same value.
+    node_types : dict, optional
+        Optional mapping label -> node type for heterogeneous graphs.
+
+    Returns
+    -------
+    G : networkx.Graph or networkx.MultiGraph or networkx.MultiDiGraph
+        Network with node positions and semantic edge attributes.
+    """
+    if labels is None:
+        labels = sorted(centers.keys())
+
+    is_multilayer = isinstance(connectivity_matrix, dict)
+
+    # Create graph
+    if directed:
+        G = nx.MultiDiGraph()
+    else:
+        G = nx.MultiGraph() if is_multilayer else nx.Graph()
+
+    def _infer_node_type(label):
+        if isinstance(label, str) and ":" in label:
+            prefix = label.split(":", 1)[0].strip().lower()
+            return prefix if prefix else None
+        return None
+
+    # Add nodes with positions
+    for label in labels:
+        if label in centers:
+            pos = centers[label]
+            node_attrs = {"pos": pos, "x": pos[0], "y": pos[1], "z": pos[2]}
+            if node_types is not None and label in node_types:
+                node_attrs["node_type"] = node_types[label]
+            else:
+                inferred_type = _infer_node_type(label)
+                if inferred_type is not None:
+                    node_attrs["node_type"] = inferred_type
+            G.add_node(label, **node_attrs)
+
+    if is_multilayer:
+        layer_matrices = connectivity_matrix
+    else:
+        layer_matrices = {"default": connectivity_matrix}
+
+    n = len(labels)
+    for layer_name, layer_matrix in layer_matrices.items():
+        matrix = np.asarray(layer_matrix)
+        if matrix.shape != (n, n):
+            raise ValueError(
+                f"Layer '{layer_name}' has shape {matrix.shape}, expected {(n, n)}"
+            )
+
+        # Compute threshold per layer
+        if threshold_percentile > 0:
+            nonzero = matrix[matrix > 0]
+            if len(nonzero) > 0:
+                threshold = np.percentile(nonzero, threshold_percentile)
+            else:
+                threshold = 0
+        else:
+            threshold = 0
+
+        # Add edges
+        for i in range(n):
+            for j in range(n):
+                if i == j:
+                    continue
+                if not directed and i > j:
+                    continue
+
+                edge_value = matrix[i, j]
+                # For undirected graphs, also check the transpose entry
+                if not directed:
+                    edge_value = max(edge_value, matrix[j, i])
+                if edge_value > threshold:
+                    attrs = {edge_data_key: float(edge_value)}
+                    if edge_data_key != "weight":
+                        attrs["weight"] = float(edge_value)
+                    if is_multilayer:
+                        attrs["layer"] = str(layer_name)
+                    G.add_edge(labels[i], labels[j], **attrs)
+
+    return G
+
+
+def create_sphere_mesh(center, radius, resolution=12):
+    """
+    Create a UV sphere mesh at a given center.
+
+    Parameters
+    ----------
+    center : array-like, shape (3,)
+        Center coordinates (x, y, z)
+    radius : float
+        Sphere radius
+    resolution : int
+        Number of subdivisions (higher = smoother)
+
+    Returns
+    -------
+    vertices : ndarray, shape (n_verts, 3)
+    faces : ndarray, shape (n_faces, 3)
+    """
+    u = np.linspace(0, 2 * np.pi, resolution + 1)
+    v = np.linspace(0, np.pi, resolution // 2 + 1)
+
+    verts = []
+    for vi in v:
+        for ui in u[:-1]:
+            x = center[0] + radius * np.sin(vi) * np.cos(ui)
+            y = center[1] + radius * np.sin(vi) * np.sin(ui)
+            z = center[2] + radius * np.cos(vi)
+            verts.append([x, y, z])
+
+    vertices = np.array(verts, dtype=np.float32)
+
+    faces = []
+    n_u = resolution
+    n_v = resolution // 2 + 1
+
+    for j in range(n_v - 1):
+        for i in range(n_u):
+            v0 = j * n_u + i
+            v1 = j * n_u + (i + 1) % n_u
+            v2 = (j + 1) * n_u + (i + 1) % n_u
+            v3 = (j + 1) * n_u + i
+            faces.append([v0, v1, v2])
+            faces.append([v0, v2, v3])
+
+    return vertices, np.array(faces, dtype=np.int32)
+
+
+def create_node_mesh(G, radius=2.0, resolution=12, nodes=None, data_key=None, scale=None):
+    """
+    Create a combined mesh of spheres for network nodes.
+
+    Parameters
+    ----------
+    G : networkx.Graph
+        Network with node positions (pos attribute)
+    radius : float
+        Base sphere radius for each node
+    resolution : int
+        Sphere mesh resolution
+    nodes : list, optional
+        Subset of nodes to include. If None, uses all nodes.
+    data_key : str, optional
+        Node attribute key to extract values for coloring.
+        If provided, returns an overlay array for colormap-based rendering.
+    scale : dict, optional
+        Dictionary mapping node attribute key to scaling factor, with optional "mode".
+        Example: {"strength": 2} scales radius from 1x to 2x based on normalized strength.
+        The factor controls the range: radius * (1 + normalized_value * (factor - 1))
+        Add "mode": "log", "exp", or "quantile" to change scaling behavior.
+        - "linear" (default): uses normalized value directly
+        - "log": applies log(1 + normalized * 9) / log(10) for smoother spread
+        - "exp": applies (exp(normalized * 2) - 1) / (exp(2) - 1) for emphasis on high values
+        - "quantile": spreads values uniformly by rank (best for dense graphs)
+
+    Returns
+    -------
+    mesh : GiftiImage
+        Combined sphere mesh
+    overlay : ndarray, optional
+        Per-vertex values for colormap (only if data_key is provided)
+    """
+    if nodes is None:
+        nodes = list(G.nodes())
+
+    # Filter nodes with positions
+    valid_nodes = [n for n in nodes if "pos" in G.nodes[n]]
+
+    if not valid_nodes:
+        raise ValueError("No nodes with positions found")
+
+    # Pre-compute normalized scale values if scaling is requested
+    node_scale_values = {}
+    if scale is not None:
+        scale_mode = scale.get("mode", "linear")
+        for key, factor in scale.items():
+            if key == "mode":
+                continue
+
+            key_nodes = [n for n in valid_nodes if key in G.nodes[n]]
+            if not key_nodes:
+                continue
+
+            raw_values = [G.nodes[n][key] for n in key_nodes]
+            multipliers = _compute_scale_multiplier(raw_values, factor, scale_mode)
+            for node, mult in zip(key_nodes, multipliers):
+                if node not in node_scale_values:
+                    node_scale_values[node] = 1.0
+                node_scale_values[node] *= mult
+
+    all_vertices = []
+    all_faces = []
+    all_values = [] if data_key else None
+    vertex_offset = 0
+
+    for node in valid_nodes:
+        center = G.nodes[node]["pos"]
+
+        # Get scaled radius
+        node_radius = radius
+        if node in node_scale_values:
+            node_radius = radius * node_scale_values[node]
+
+        verts, faces = create_sphere_mesh(center, node_radius, resolution)
+        all_vertices.append(verts)
+        all_faces.append(faces + vertex_offset)
+        vertex_offset += len(verts)
+
+        # Extract node data value for coloring
+        if data_key is not None:
+            node_data = G.nodes[node]
+            if data_key in node_data:
+                value = node_data[data_key]
+            else:
+                value = 0.0
+            # Assign same value to all vertices of this sphere
+            all_values.extend([value] * len(verts))
+
+    if not all_vertices:
+        raise ValueError("No nodes with positions found")
+
+    combined_verts = np.vstack(all_vertices).astype(np.float32)
+    combined_faces = np.vstack(all_faces).astype(np.int32)
+
+    mesh = _create_gifti_mesh(combined_verts, combined_faces)
+
+    if data_key is not None:
+        return mesh, np.array(all_values, dtype=np.float32)
+    return mesh
+
+
+def create_tube_mesh(start, end, radius=0.3, resolution=8):
+    """
+    Create a tube (cylinder) mesh between two points.
+
+    Parameters
+    ----------
+    start, end : array-like, shape (3,)
+        Start and end coordinates
+    radius : float
+        Tube radius
+    resolution : int
+        Number of segments around the tube
+
+    Returns
+    -------
+    vertices : ndarray, shape (n_verts, 3)
+    faces : ndarray, shape (n_faces, 3)
+    """
+    start = np.array(start)
+    end = np.array(end)
+
+    # Direction vector
+    direction = end - start
+    length = np.linalg.norm(direction)
+    if length < 1e-6:
+        return np.array([]).reshape(0, 3), np.array([]).reshape(0, 3)
+
+    direction = direction / length
+
+    # Find perpendicular vectors
+    if abs(direction[0]) < 0.9:
+        perp1 = np.cross(direction, [1, 0, 0])
+    else:
+        perp1 = np.cross(direction, [0, 1, 0])
+    perp1 = perp1 / np.linalg.norm(perp1)
+    perp2 = np.cross(direction, perp1)
+
+    # Generate vertices
+    angles = np.linspace(0, 2 * np.pi, resolution, endpoint=False)
+
+    verts = []
+    for angle in angles:
+        offset = radius * (np.cos(angle) * perp1 + np.sin(angle) * perp2)
+        verts.append(start + offset)
+        verts.append(end + offset)
+
+    vertices = np.array(verts, dtype=np.float32)
+
+    # Generate faces
+    faces = []
+    for i in range(resolution):
+        i0 = 2 * i
+        i1 = 2 * i + 1
+        i2 = 2 * ((i + 1) % resolution)
+        i3 = 2 * ((i + 1) % resolution) + 1
+
+        faces.append([i0, i2, i1])
+        faces.append([i1, i2, i3])
+
+    return vertices, np.array(faces, dtype=np.int32)
+
+
+def create_edge_mesh(G, radius=0.3, resolution=8, edges=None, data_key=None, scale=None):
+    """
+    Create a combined mesh of tubes for network edges.
+
+    Parameters
+    ----------
+    G : networkx.Graph
+        Network with node positions (pos attribute)
+    radius : float
+        Base tube radius for each edge
+    resolution : int
+        Tube mesh resolution
+    edges : list, optional
+        Subset of edges to include. If None, uses all edges.
+    data_key : str, optional
+        Edge attribute key to extract values for coloring (e.g., "weight").
+        If provided, returns an overlay array for colormap-based rendering.
+    scale : dict, optional
+        Dictionary mapping edge attribute key to scaling factor, with optional "mode".
+        Example: {"weight": 3} scales radius from 1x to 3x based on normalized weight.
+        The factor controls the range: radius * (1 + normalized_value * (factor - 1))
+        Add "mode": "log", "exp", or "quantile" to change scaling behavior.
+        - "linear" (default): uses normalized value directly
+        - "log": applies log(1 + normalized * 9) / log(10) for smoother spread
+        - "exp": applies (exp(normalized * 2) - 1) / (exp(2) - 1) for emphasis on high values
+        - "quantile": spreads values uniformly by rank (best for dense graphs)
+
+    Returns
+    -------
+    mesh : GiftiImage
+        Combined tube mesh
+    overlay : ndarray, optional
+        Per-vertex values for colormap (only if data_key is provided)
+    """
+    if edges is None:
+        edges = list(G.edges(keys=True)) if G.is_multigraph() else list(G.edges())
+
+    def _edge_nodes(edge):
+        return edge[0], edge[1]
+
+    def _edge_lookup_key(edge):
+        if G.is_multigraph() and len(edge) >= 3:
+            return edge[0], edge[1], edge[2]
+        return edge[0], edge[1]
+
+    def _edge_attrs(edge):
+        u, v = _edge_nodes(edge)
+        if G.is_multigraph():
+            if len(edge) >= 3:
+                data = G.get_edge_data(u, v, key=edge[2])
+                return data if isinstance(data, dict) else {}
+
+            data_by_key = G.get_edge_data(u, v)
+            if isinstance(data_by_key, dict):
+                first = next(iter(data_by_key.values()), {})
+                return first if isinstance(first, dict) else {}
+            return {}
+
+        data = G.get_edge_data(u, v)
+        return data if isinstance(data, dict) else {}
+
+    # Filter valid edges (both nodes have positions)
+    valid_edges = []
+    for edge in edges:
+        if len(edge) < 2:
+            continue
+        u, v = _edge_nodes(edge)
+        if u in G.nodes and v in G.nodes and "pos" in G.nodes[u] and "pos" in G.nodes[v]:
+            valid_edges.append(edge)
+
+    if not valid_edges:
+        raise ValueError("No edges with valid node positions found")
+
+    # Pre-compute normalized scale values if scaling is requested
+    edge_scale_values = {}
+    if scale is not None:
+        scale_mode = scale.get("mode", "linear")
+        for key, factor in scale.items():
+            if key == "mode":
+                continue
+
+            key_edges = []
+            raw_values = []
+            for edge in valid_edges:
+                edge_data = _edge_attrs(edge)
+                if edge_data is not None and key in edge_data:
+                    key_edges.append(edge)
+                    raw_values.append(edge_data[key])
+
+            if not raw_values:
+                continue
+
+            multipliers = _compute_scale_multiplier(raw_values, factor, scale_mode)
+            for edge, mult in zip(key_edges, multipliers):
+                edge_key = _edge_lookup_key(edge)
+                if edge_key not in edge_scale_values:
+                    edge_scale_values[edge_key] = 1.0
+                edge_scale_values[edge_key] *= mult
+
+    all_vertices = []
+    all_faces = []
+    all_values = [] if data_key else None
+    vertex_offset = 0
+
+    for edge in valid_edges:
+        u, v = _edge_nodes(edge)
+        start = G.nodes[u]["pos"]
+        end = G.nodes[v]["pos"]
+
+        # Get scaled radius
+        edge_radius = radius
+        edge_key = _edge_lookup_key(edge)
+        if edge_key in edge_scale_values:
+            edge_radius = radius * edge_scale_values[edge_key]
+
+        verts, faces = create_tube_mesh(start, end, edge_radius, resolution)
+        if len(verts) == 0:
+            continue
+
+        all_vertices.append(verts)
+        all_faces.append(faces + vertex_offset)
+        vertex_offset += len(verts)
+
+        # Extract edge data value for coloring
+        if data_key is not None:
+            edge_data = _edge_attrs(edge)
+            if edge_data is not None and data_key in edge_data:
+                value = edge_data[data_key]
+            else:
+                value = 0.0
+            # Assign same value to all vertices of this tube
+            all_values.extend([value] * len(verts))
+
+    if not all_vertices:
+        raise ValueError("No edges with valid node positions found")
+
+    combined_verts = np.vstack(all_vertices).astype(np.float32)
+    combined_faces = np.vstack(all_faces).astype(np.int32)
+
+    mesh = _create_gifti_mesh(combined_verts, combined_faces)
+
+    if data_key is not None:
+        return mesh, np.array(all_values, dtype=np.float32)
+    return mesh
+
+
+def _create_gifti_mesh(vertices, faces):
+    """Create a GiftiImage from vertices and faces."""
+    coords = nibabel.gifti.GiftiDataArray(
+        data=vertices.astype(np.float32),
+        intent=nibabel.nifti1.intent_codes["NIFTI_INTENT_POINTSET"],
+        datatype=nibabel.nifti1.data_type_codes["NIFTI_TYPE_FLOAT32"],
+    )
+    triangles = nibabel.gifti.GiftiDataArray(
+        data=faces.astype(np.int32),
+        intent=nibabel.nifti1.intent_codes["NIFTI_INTENT_TRIANGLE"],
+        datatype=nibabel.nifti1.data_type_codes["NIFTI_TYPE_INT32"],
+    )
+    return nibabel.gifti.GiftiImage(darrays=[coords, triangles])
+
+
+def _apply_log_to_overlay(overlay, vmin=None, vmax=None):
+    """Transform overlay values to log10 space for log-scale colormapping.
+
+    Returns transformed overlay, vmin, vmax for passing to plot_surf.
+    Zeros and negatives are clipped to a small epsilon.
+    """
+    pos = overlay[overlay > 0]
+    if len(pos) > 0:
+        eps = pos.min() * 0.1
+    else:
+        eps = 1e-10
+    log_overlay = np.log10(np.clip(overlay, eps, None))
+    if vmin is not None:
+        log_vmin = np.log10(max(vmin, eps))
+    else:
+        log_vmin = np.log10(eps) if len(pos) == 0 else np.log10(pos.min())
+    if vmax is not None:
+        log_vmax = np.log10(max(vmax, eps))
+    else:
+        log_vmax = log_overlay.max()
+    return log_overlay, log_vmin, log_vmax
+
+
+def plot_network_on_surface(
+    G,
+    ax=None,
+    template="fsLR",
+    density="32k",
+    hemi=("lh", "rh"),
+    view="top",
+    surface_alpha=0.3,
+    node_radius=2.0,
+    node_color="crimson",
+    node_cmap=None,
+    node_data_key=None,
+    node_scale=None,
+    node_vmin=None,
+    node_vmax=None,
+    node_resolution=12,
+    edge_radius=0.3,
+    edge_color="steelblue",
+    edge_cmap=None,
+    edge_data_key="weight",
+    edge_scale=None,
+    edge_vmin=None,
+    edge_vmax=None,
+    edge_resolution=8,
+    show_edges=True,
+    show_nodes=True,
+    nodes=None,
+    edges=None,
+    extra_surfaces=None,
+    extra_colors=None,
+    extra_alphas=None,
+    **kwargs,
+):
+    """
+    Plot a network graph on brain surface with depth-correct rendering.
+
+    Parameters
+    ----------
+    G : networkx.Graph
+        Network with node positions (pos attribute)
+    ax : matplotlib.axes.Axes, optional
+        Axes to plot on. If None, creates new figure.
+    template : str
+        Surface template ("fsLR", "fsaverage")
+    density : str
+        Surface density ("32k", "10k", etc.)
+    hemi : str or tuple/list
+        Hemisphere(s) to plot. Can be "lh", "rh", or ("lh", "rh") for both.
+        Default is ("lh", "rh") to show both hemispheres merged.
+    view : str
+        View angle ("lateral", "medial", "top", "front", etc.)
+    surface_alpha : float
+        Transparency of brain surface
+    node_radius : float
+        Radius of node spheres
+    node_color : str or "auto"
+        Uniform color for nodes. If "auto" and node_data_key is set,
+        uses colormap based on node data. If "auto" and node has "color"
+        attribute, uses that color.
+    node_cmap : str, optional
+        Colormap for nodes based on node_data_key attribute.
+        If provided, nodes are colored by their data values.
+    node_data_key : str, optional
+        Node attribute to use for colormap (e.g., "degree", "strength")
+    node_scale : dict, optional
+        Dictionary mapping node attribute key to max scaling factor for radius.
+        Values are normalized to [0,1] first, then scaled.
+        Example: {"strength": 3} scales radius from 1x (min) to 3x (max).
+        Add "mode": "log", "exp", or "quantile" to change scaling curve.
+        - "linear" (default): linear interpolation between 1x and factor
+        - "log": compresses high values, spreads low values
+        - "exp": emphasizes high values, compresses low values
+        - "quantile": uniform spread by rank, robust for dense graphs
+    node_vmin, node_vmax : float, optional
+        Color scale limits for node colormap
+    node_resolution : int
+        Resolution of node sphere meshes
+    edge_radius : float
+        Radius of edge tubes
+    edge_color : str or "auto"
+        Uniform color for edges. If "auto" and edge_data_key is set,
+        uses colormap based on edge data. Falls back to "steelblue"
+        when "auto" but no data key is provided.
+    edge_cmap : str, optional
+        Colormap for edges based on edge_data_key attribute.
+        If provided, edges are colored by their data values.
+    edge_data_key : str
+        Edge attribute to use for colormap (default: "weight")
+    edge_scale : dict, optional
+        Dictionary mapping edge attribute key to max scaling factor for radius.
+        Values are normalized to [0,1] first, then scaled.
+        Example: {"weight": 5} scales radius from 1x (min) to 5x (max).
+        Add "mode": "log", "exp", or "quantile" to change scaling curve.
+        - "linear" (default): linear interpolation between 1x and factor
+        - "log": compresses high values, spreads low values
+        - "exp": emphasizes high values, compresses low values
+        - "quantile": uniform spread by rank, robust for dense graphs
+    edge_vmin, edge_vmax : float, optional
+        Color scale limits for edge colormap
+    edge_resolution : int
+        Resolution of edge tube meshes
+    show_edges : bool
+        Whether to show edges
+    show_nodes : bool
+        Whether to show nodes
+    nodes : list, optional
+        Subset of nodes to show
+    edges : list, optional
+        Subset of edges to show
+    extra_surfaces : list, optional
+        Additional surface meshes (GiftiImage) to render alongside the brain
+        and network. These are depth-sorted together with all other elements.
+        Example: head/skull surface from MNE BEM.
+    extra_colors : list, optional
+        Colors for extra_surfaces (one per surface).
+    extra_alphas : list, optional
+        Alpha values for extra_surfaces (one per surface).
+    **kwargs
+        Additional arguments passed to plot_surf
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+    mappables : dict
+        Dictionary containing ScalarMappable objects for colorbars.
+        Keys are 'nodes' and/or 'edges' (only present if colormap was used).
+        Use with fig.colorbar(mappables['nodes'], ax=ax, label='Node strength')
+    """
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(12, 10))
+        return_fig = True
+    else:
+        fig = ax.figure
+        return_fig = False
+
+    # Build list of additional surfaces (start with user-provided extras)
+    additional_surfaces = list(extra_surfaces) if extra_surfaces else []
+    additional_colors = list(extra_colors) if extra_colors else []
+    additional_alphas = list(extra_alphas) if extra_alphas else []
+    n_extras = len(additional_surfaces)
+    # Pad colors/alphas lists to match extras count
+    while len(additional_colors) < n_extras:
+        additional_colors.append('wheat')
+    while len(additional_alphas) < n_extras:
+        additional_alphas.append(0.1)
+    additional_overlays = [None] * n_extras
+    additional_cmaps = [None] * n_extras
+    additional_vmins = [None] * n_extras
+    additional_vmaxs = [None] * n_extras
+
+    # Handle "auto" node_color
+    use_node_cmap = False
+    if node_color == "auto":
+        if node_data_key is not None:
+            # Use colormap based on node data
+            use_node_cmap = True
+            if node_cmap is None:
+                node_cmap = "viridis"  # default colormap
+        # Note: per-node colors from "color" attribute would require
+        # separate meshes per node, which we don't support yet
+    elif node_cmap is not None:
+        use_node_cmap = True
+
+    # Detect log mode from scale dicts
+    node_scale_mode = (node_scale or {}).get("mode", "linear")
+    edge_scale_mode = (edge_scale or {}).get("mode", "linear")
+
+    # Create node mesh
+    if show_nodes:
+        if nodes is None:
+            nodes = [n for n in G.nodes() if G.degree(n) > 0]  # nodes with edges
+        if nodes:
+            if use_node_cmap and node_data_key is not None:
+                # Use colormap based on node data
+                node_mesh, node_overlay = create_node_mesh(
+                    G,
+                    radius=node_radius,
+                    resolution=node_resolution,
+                    nodes=nodes,
+                    data_key=node_data_key,
+                    scale=node_scale,
+                )
+                # Apply log transform to overlay if scale mode is "log"
+                _node_ovl_vmin, _node_ovl_vmax = node_vmin, node_vmax
+                if node_scale_mode == "log":
+                    node_overlay, _node_ovl_vmin, _node_ovl_vmax = (
+                        _apply_log_to_overlay(node_overlay, node_vmin, node_vmax)
+                    )
+                additional_surfaces.append(node_mesh)
+                additional_colors.append(None)
+                additional_overlays.append(node_overlay)
+                additional_cmaps.append(node_cmap)
+                additional_vmins.append(_node_ovl_vmin)
+                additional_vmaxs.append(_node_ovl_vmax)
+                additional_alphas.append(1.0)
+            elif node_color == "auto":
+                # Group nodes by their 'color' attribute for per-node colors
+                color_groups = {}
+                for n in nodes:
+                    c = G.nodes[n].get('color', 'crimson')
+                    color_groups.setdefault(c, []).append(n)
+                for c, group_nodes in color_groups.items():
+                    mesh = create_node_mesh(
+                        G, radius=node_radius, resolution=node_resolution,
+                        nodes=group_nodes, scale=node_scale
+                    )
+                    additional_surfaces.append(mesh)
+                    additional_colors.append(c)
+                    additional_overlays.append(None)
+                    additional_cmaps.append(None)
+                    additional_vmins.append(None)
+                    additional_vmaxs.append(None)
+                    additional_alphas.append(1.0)
+            else:
+                # Use uniform color
+                node_mesh = create_node_mesh(
+                    G, radius=node_radius, resolution=node_resolution, nodes=nodes, scale=node_scale
+                )
+                additional_surfaces.append(node_mesh)
+                additional_colors.append(node_color)
+                additional_overlays.append(None)
+                additional_cmaps.append(None)
+                additional_vmins.append(None)
+                additional_vmaxs.append(None)
+                additional_alphas.append(1.0)
+
+    # Handle "auto" edge_color (mirrors node_color logic)
+    use_edge_cmap = False
+    if edge_color == "auto":
+        if edge_data_key is not None:
+            use_edge_cmap = True
+            if edge_cmap is None:
+                edge_cmap = "viridis"
+    elif edge_cmap is not None:
+        use_edge_cmap = True
+
+    # Create edge mesh
+    if show_edges:
+        if edges is None:
+            edges = list(G.edges(keys=True)) if G.is_multigraph() else list(G.edges())
+        if edges:
+            if use_edge_cmap and edge_data_key is not None:
+                # Use colormap based on edge data
+                edge_mesh, edge_overlay = create_edge_mesh(
+                    G,
+                    radius=edge_radius,
+                    resolution=edge_resolution,
+                    edges=edges,
+                    data_key=edge_data_key,
+                    scale=edge_scale,
+                )
+                # Apply log transform to overlay if scale mode is "log"
+                _edge_ovl_vmin, _edge_ovl_vmax = edge_vmin, edge_vmax
+                if edge_scale_mode == "log":
+                    edge_overlay, _edge_ovl_vmin, _edge_ovl_vmax = (
+                        _apply_log_to_overlay(edge_overlay, edge_vmin, edge_vmax)
+                    )
+                additional_surfaces.append(edge_mesh)
+                additional_colors.append(None)
+                additional_overlays.append(edge_overlay)
+                additional_cmaps.append(edge_cmap)
+                additional_vmins.append(_edge_ovl_vmin)
+                additional_vmaxs.append(_edge_ovl_vmax)
+            else:
+                # Use uniform color
+                edge_mesh = create_edge_mesh(
+                    G, radius=edge_radius, resolution=edge_resolution, edges=edges, scale=edge_scale
+                )
+                additional_surfaces.append(edge_mesh)
+                additional_colors.append(
+                    edge_color if edge_color != "auto" else "steelblue"
+                )
+                additional_overlays.append(None)
+                additional_cmaps.append(None)
+                additional_vmins.append(None)
+                additional_vmaxs.append(None)
+            additional_alphas.append(1.0)
+
+    # Track overlay data for creating ScalarMappables
+    node_overlay_data = None
+    edge_overlay_data = None
+
+    if use_node_cmap and node_data_key is not None and show_nodes and nodes:
+        node_overlay_data = node_overlay
+
+    if use_edge_cmap and edge_data_key is not None and show_edges and edges:
+        edge_overlay_data = edge_overlay
+
+    # Plot with merged hemispheres (single call for proper depth sorting)
+    bsplot.surface.plot_surf(
+        template,
+        hemi=hemi,
+        view=view,
+        ax=ax,
+        surface_density=density,
+        alpha=surface_alpha,
+        additional_surfaces=additional_surfaces if additional_surfaces else None,
+        additional_colors=additional_colors if additional_colors else None,
+        additional_alphas=additional_alphas if additional_alphas else None,
+        additional_overlays=additional_overlays if additional_overlays else None,
+        additional_cmaps=additional_cmaps if additional_cmaps else None,
+        additional_vmins=additional_vmins if additional_vmins else None,
+        additional_vmaxs=additional_vmaxs if additional_vmaxs else None,
+        **kwargs,
+    )
+
+    ax.set_aspect("equal")
+
+    # Create ScalarMappables for colorbars
+    mappables = {}
+
+    if node_overlay_data is not None:
+        import matplotlib.cm as cm
+        import matplotlib.colors as mcolors
+
+        # Use raw (untransformed) overlay data for ScalarMappable range
+        raw_node_overlay = node_overlay_data
+        if node_scale_mode == "log":
+            # Recover raw values: overlay_data here is already log-transformed;
+            # rebuild raw for the ScalarMappable from the mesh call
+            raw_node_overlay = 10.0 ** node_overlay_data
+        vmin = node_vmin if node_vmin is not None else np.min(raw_node_overlay)
+        vmax = node_vmax if node_vmax is not None else np.max(raw_node_overlay)
+        if node_scale_mode == "log":
+            eps = max(vmin, raw_node_overlay[raw_node_overlay > 0].min() * 0.1) if np.any(raw_node_overlay > 0) else 1e-10
+            norm = mcolors.LogNorm(vmin=max(vmin, eps), vmax=vmax)
+        else:
+            norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+        node_sm = cm.ScalarMappable(cmap=_resolve_cmap(node_cmap), norm=norm)
+        node_sm.set_array(raw_node_overlay)
+        mappables['nodes'] = node_sm
+
+    if edge_overlay_data is not None:
+        import matplotlib.cm as cm
+        import matplotlib.colors as mcolors
+
+        # Use raw (untransformed) overlay data for ScalarMappable range
+        raw_edge_overlay = edge_overlay_data
+        if edge_scale_mode == "log":
+            raw_edge_overlay = 10.0 ** edge_overlay_data
+        vmin = edge_vmin if edge_vmin is not None else np.min(raw_edge_overlay)
+        vmax = edge_vmax if edge_vmax is not None else np.max(raw_edge_overlay)
+        if edge_scale_mode == "log":
+            eps = max(vmin, raw_edge_overlay[raw_edge_overlay > 0].min() * 0.1) if np.any(raw_edge_overlay > 0) else 1e-10
+            norm = mcolors.LogNorm(vmin=max(vmin, eps), vmax=vmax)
+        else:
+            norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+        edge_sm = cm.ScalarMappable(cmap=_resolve_cmap(edge_cmap), norm=norm)
+        edge_sm.set_array(raw_edge_overlay)
+        mappables['edges'] = edge_sm
+
+    if return_fig:
+        ax.axis("off")
+        return fig, ax, mappables
+
+    return fig, ax, mappables