cccpm 0.3.0__tar.gz → 0.3.2__tar.gz

{cccpm-0.3.0 → cccpm-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cccpm
-Version: 0.3.0
+Version: 0.3.2
 Summary: Confound-Corrected Connectome-based Predictive Modeling Python Package
 License: MIT
 License-File: LICENSE
@@ -19,8 +19,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
-Requires-Dist: arakawa
 Requires-Dist: bleach
+Requires-Dist: jinja2
 Requires-Dist: matplotlib
 Requires-Dist: netplotbrain
 Requires-Dist: networkx
@@ -28,6 +28,7 @@ Requires-Dist: nilearn
 Requires-Dist: numpy
 Requires-Dist: pandas
 Requires-Dist: plotly
+Requires-Dist: pycirclize
 Requires-Dist: pygam
 Requires-Dist: scikit-image
 Requires-Dist: scikit-learn (>=1.6)

{cccpm-0.3.0 → cccpm-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cccpm"
-version = "0.3.0"
+version = "0.3.2"
 description = "Confound-Corrected Connectome-based Predictive Modeling Python Package"
 authors = [
     "Nils Winter <nils.r.winter@uni-muenster.de>",
@@ -52,7 +52,8 @@ statsmodels = "*"
 nilearn = "*"
 matplotlib = "*"
 seaborn = "*"
-arakawa = "*"
+jinja2 = "*"
+pycirclize = "*"
 tqdm = "*"
 pygam = "*"
 

cccpm-0.3.2/src/cccpm/reporting/html_report.py

@@ -0,0 +1,156 @@
+"""
+HTML Report Generator for Confound-Corrected CPM Analysis.
+
+Builds a self-contained single-page HTML report using a Jinja2 template.
+The public interface (HTMLReporter / generate_html_report) is unchanged.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+import jinja2
+
+import cccpm
+from cccpm.reporting.data_loader import ReportDataLoader
+from cccpm.reporting.reporting_utils import embed_image_base64
+from cccpm.reporting.section_builders import (
+    build_brain_plots_context,
+    build_data_context,
+    build_hero_context,
+    build_hyperparameters_context,
+    build_network_strengths_context,
+    build_performance_context,
+    build_stable_edges_context,
+)
+
+
+class HTMLReporter:
+    """
+    Generate a self-contained HTML report from CPM analysis results.
+
+    The report is a single scrolling page with a sticky sidebar; it embeds
+    all figures as base64 data URIs so it is fully portable and works offline.
+
+    Args:
+        results_directory: Path to the directory containing CPM results.
+        atlas_labels: Optional path to a CSV file with atlas region labels
+            (enables brain plots and labelled edge tables).
+    """
+
+    def __init__(self, results_directory: str, atlas_labels: str | None = None):
+        self.results_directory = results_directory
+        self.plots_dir = os.path.join(results_directory, "plots")
+        os.makedirs(self.plots_dir, exist_ok=True)
+
+        self.data_loader = ReportDataLoader(results_directory, atlas_labels)
+        self.X_names, self.y_name, self.covariates_names = (
+            self.data_loader.load_variable_names()
+        )
+        self.atlas_labels = self.data_loader.atlas_labels
+        self.task_type = self.data_loader.load_task_type()
+        self._load_data()
+
+    def _load_data(self) -> None:
+        self.df, self.df_mean = self.data_loader.load_cv_results()
+        self.df_predictions = self.data_loader.load_predictions()
+        self.df_p_values = self.data_loader.load_p_values()
+        self.df_permutations = self.data_loader.load_permutations()
+        self.df_network_strengths = self.data_loader.load_network_strengths()
+
+    def generate_html_report(self) -> None:
+        """Render the HTML report and write it to ``results_directory/report.html``."""
+        summary_df, scatter_path, _ = self.data_loader.load_data_insights()
+        edge_stability, edge_stability_sig = self.data_loader.load_edge_stability()
+
+        # ── Build template context ──────────────────────────────────────────
+        ctx: dict = {
+            "y_name": self.y_name,
+            "logo_img": self._logo_html(),
+        }
+
+        ctx.update(build_hero_context(
+            df_mean=self.df_mean,
+            df_p_values=self.df_p_values,
+            df_predictions=self.df_predictions,
+            summary_df=summary_df,
+            edge_stability=edge_stability,
+            results_directory=self.results_directory,
+            plots_dir=self.plots_dir,
+            y_name=self.y_name,
+            task_type=self.task_type,
+            version=cccpm.__version__,
+            run_date=datetime.date.today().isoformat(),
+        ))
+
+        ctx.update(build_data_context(summary_df, scatter_path, self.results_directory))
+
+        ctx.update(build_hyperparameters_context(self.df))
+
+        ctx.update(build_performance_context(
+            df_full=self.df,
+            df_mean=self.df_mean,
+            df_p_values=self.df_p_values,
+            y_name=self.y_name,
+            task_type=self.task_type,
+            plots_dir=self.plots_dir,
+        ))
+
+        ctx.update(build_network_strengths_context(
+            df_network_strengths=self.df_network_strengths,
+            y_name=self.y_name,
+            plots_dir=self.plots_dir,
+        ))
+
+        ctx.update(build_brain_plots_context(
+            results_directory=self.results_directory,
+            plots_dir=self.plots_dir,
+            atlas_labels=self.atlas_labels,
+            edge_stability=edge_stability,
+            edge_significance=edge_stability_sig,
+        ))
+
+        ctx.update(build_stable_edges_context(
+            edge_stability=edge_stability,
+            edge_stability_significance=edge_stability_sig,
+            atlas_labels=self.atlas_labels,
+        ))
+
+        # ── Render ─────────────────────────────────────────────────────────
+        html = self._render(ctx)
+
+        out_path = os.path.join(self.results_directory, "report.html")
+        Path(out_path).write_text(html, encoding="utf-8")
+
+        plt.close("all")
+
+    # ── Private helpers ────────────────────────────────────────────────────
+
+    def _logo_html(self) -> str:
+        logo_path = Path(__file__).parent / "assets" / "CCCPM.png"
+        if logo_path.exists():
+            return embed_image_base64(str(logo_path))
+        return ""
+
+    def _render(self, ctx: dict) -> str:
+        template_dir = Path(__file__).parent / "templates"
+        env = jinja2.Environment(
+            loader=jinja2.FileSystemLoader(str(template_dir)),
+            autoescape=jinja2.select_autoescape(["html"]),
+        )
+        # Disable autoescape for HTML fragment variables (figures, tables)
+        env.autoescape = False
+
+        template = env.get_template("report.html.j2")
+
+        # Inline the stylesheet
+        css_path = template_dir / "styles.css"
+        ctx["styles"] = css_path.read_text(encoding="utf-8")
+
+        return template.render(**ctx)

cccpm-0.3.2/src/cccpm/reporting/plots/brain_figures.py

@@ -0,0 +1,320 @@
+"""
+Neuroscience figures for the CCCPM HTML report.
+
+Each function takes a node-level connectome matrix (and, where needed, an atlas
+DataFrame) and returns the path to a saved SVG figure. The functions are kept
+self-contained — input = numpy matrix / atlas, output = matplotlib Figure — so
+they can later be moved into the shared ``wwu-mmll/brainplots`` toolbox.
+
+Atlas convention (matches brainchord): one row per node, columns include
+``region``, ``network``, ``hemisphere``, ``x``, ``y``, ``z``. Only ``network``
+is required for the network-summary and chord figures.
+"""
+
+from __future__ import annotations
+
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from cccpm.reporting.plots.connectome_utils import (
+    aggregate_matrix_by_group,
+    get_network_color,
+)
+from cccpm.reporting.plots.figure_style import (
+    DIVERGING_CMAP,
+    NEG,
+    POS,
+    SQUARE,
+    apply_nature_style,
+    save_figure,
+)
+
+
+# ── 1. Connectivity matrix ─────────────────────────────────────────────────────
+
+def connectivity_matrix(
+    matrix: np.ndarray,
+    results_folder: str,
+    atlas: pd.DataFrame | None = None,
+    *,
+    name: str = "connectivity_matrix",
+) -> str:
+    """
+    Node×node heatmap of (signed) edge stability.
+
+    Red = positive-network edges, blue = negative-network edges. If *atlas* has
+    a ``network`` column, nodes are ordered by network and dividers are drawn,
+    so within/between-network structure is visible (the classic CPM matrix view).
+    """
+    apply_nature_style()
+    mat = np.asarray(matrix, dtype=float)
+    n = mat.shape[0]
+
+    order = np.arange(n)
+    boundaries: list[int] = []
+    tick_pos: list[float] = []
+    tick_lab: list[str] = []
+    if atlas is not None and "network" in atlas.columns and len(atlas) == n:
+        nets = atlas["network"].to_numpy()
+        order = np.argsort(nets, kind="stable")
+        nets_sorted = nets[order]
+        mat = mat[np.ix_(order, order)]
+        # network block boundaries + centered labels
+        start = 0
+        for i in range(1, n + 1):
+            if i == n or nets_sorted[i] != nets_sorted[start]:
+                boundaries.append(i)
+                tick_pos.append((start + i) / 2)
+                tick_lab.append(str(nets_sorted[start]))
+                start = i
+
+    vmax = np.abs(mat).max() or 1.0
+    fig, ax = plt.subplots(figsize=SQUARE)
+    # rasterize the cell grid so the SVG stays small for large atlases
+    # (200-1000 ROIs) while axes/labels remain crisp vectors.
+    im = ax.imshow(mat, cmap=DIVERGING_CMAP, vmin=-vmax, vmax=vmax,
+                   interpolation="nearest", rasterized=True)
+
+    if boundaries:
+        for b in boundaries[:-1]:
+            ax.axhline(b - 0.5, color="#444", linewidth=0.4)
+            ax.axvline(b - 0.5, color="#444", linewidth=0.4)
+        ax.set_xticks(tick_pos)
+        ax.set_xticklabels(tick_lab, rotation=90, fontsize=5)
+        ax.set_yticks(tick_pos)
+        ax.set_yticklabels(tick_lab, fontsize=5)
+    else:
+        ax.set_xlabel("node")
+        ax.set_ylabel("node")
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+    cbar = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    cbar.ax.tick_params(labelsize=5)
+    cbar.set_label("stability (signed)", fontsize=6)
+    fig.tight_layout(pad=0.3)
+    return save_figure(fig, os.path.join(results_folder, name))
+
+
+# ── 2. Network-summary matrix ──────────────────────────────────────────────────
+
+def network_summary_matrix(
+    matrix: np.ndarray,
+    atlas: pd.DataFrame,
+    results_folder: str,
+    *,
+    groupby: str = "network",
+    name: str = "network_summary_matrix",
+) -> str | None:
+    """
+    Region×region matrix: edges aggregated by canonical network.
+
+    Returns ``None`` if the atlas lacks the *groupby* column (caller shows a
+    graceful "needs network labels" message).
+    """
+    if atlas is None or groupby not in atlas.columns or len(atlas) != matrix.shape[0]:
+        return None
+
+    apply_nature_style()
+    groups = atlas[groupby].astype(str).tolist()
+    region_df = aggregate_matrix_by_group(np.asarray(matrix, dtype=float), groups, signed=True)
+
+    vmax = np.abs(region_df.values).max() or 1.0
+    fig, ax = plt.subplots(figsize=SQUARE)
+    im = ax.imshow(region_df.values, cmap=DIVERGING_CMAP, vmin=-vmax, vmax=vmax,
+                   rasterized=True)
+
+    ax.set_xticks(range(len(region_df.columns)))
+    ax.set_xticklabels(region_df.columns, rotation=90, fontsize=6)
+    ax.set_yticks(range(len(region_df.index)))
+    ax.set_yticklabels(region_df.index, fontsize=6)
+
+    # annotate cells
+    for i in range(region_df.shape[0]):
+        for j in range(region_df.shape[1]):
+            v = region_df.values[i, j]
+            if abs(v) > 1e-9:
+                ax.text(j, i, f"{v:.2f}", ha="center", va="center",
+                        fontsize=5, color="#222")
+
+    cbar = fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+    cbar.ax.tick_params(labelsize=5)
+    cbar.set_label("mean stability (signed)", fontsize=6)
+    fig.tight_layout(pad=0.3)
+    return save_figure(fig, os.path.join(results_folder, name))
+
+
+# ── 3. Chord diagram ───────────────────────────────────────────────────────────
+
+def chord_diagram(
+    matrix: np.ndarray,
+    atlas: pd.DataFrame,
+    results_folder: str,
+    *,
+    groupby: str = "network",
+    name: str = "chord_diagram",
+    link_alpha: float = 0.55,
+) -> str | None:
+    """
+    Network-level chord diagram (pycirclize). Sectors = canonical networks,
+    link colour = sign (red positive, blue negative), arc width = |stability|.
+
+    Returns ``None`` if the atlas lacks the *groupby* column or pycirclize is
+    unavailable.
+    """
+    if atlas is None or groupby not in atlas.columns or len(atlas) != matrix.shape[0]:
+        return None
+    try:
+        from pycirclize import Circos
+    except Exception:
+        return None
+
+    groups = atlas[groupby].astype(str).tolist()
+    region_df = aggregate_matrix_by_group(np.asarray(matrix, dtype=float), groups, signed=True)
+
+    # drop empty sectors
+    active = region_df.abs().sum(axis=1) > 1e-9
+    region_df = region_df.loc[active, active]
+    if region_df.empty or region_df.shape[0] < 2:
+        return None
+
+    abs_df = region_df.abs()
+    sector_colors = {r: get_network_color(r) for r in region_df.index}
+
+    def _link_kws_handler(r1: str, r2: str) -> dict:
+        try:
+            val = region_df.loc[r1, r2]
+        except KeyError:
+            val = 0.0
+        color = POS if val >= 0 else NEG
+        return dict(fc=color, alpha=link_alpha, zorder=1.0)
+
+    circos = Circos.chord_diagram(
+        abs_df,
+        space=min(3.0, 360 / max(len(region_df), 1) * 0.8),
+        cmap=sector_colors,
+        label_kws=dict(size=7, r=110, orientation="vertical"),
+        link_kws=dict(alpha=link_alpha, zorder=1.0),
+        link_kws_handler=_link_kws_handler,
+    )
+    fig = circos.plotfig(figsize=SQUARE, dpi=150)
+    fig.patch.set_facecolor("white")
+    return save_figure(fig, os.path.join(results_folder, name), formats=("svg",))
+
+
+# ── 4. Node-degree / hub plot ──────────────────────────────────────────────────
+
+def node_degree_plot(
+    matrix: np.ndarray,
+    results_folder: str,
+    atlas: pd.DataFrame | None = None,
+    *,
+    top_k: int = 15,
+    name: str = "node_degree",
+) -> str:
+    """
+    Horizontal bar of the most-connected nodes (hubs): number of stable edges
+    per node, split into positive (red) and negative (blue) contributions.
+    """
+    apply_nature_style()
+    mat = np.asarray(matrix, dtype=float)
+    n = mat.shape[0]
+
+    pos_deg = (mat > 1e-9).sum(axis=1)
+    neg_deg = (mat < -1e-9).sum(axis=1)
+    total = pos_deg + neg_deg
+
+    if atlas is not None and "region" in atlas.columns and len(atlas) == n:
+        labels = atlas["region"].astype(str).to_numpy()
+    else:
+        labels = np.array([f"node {i}" for i in range(n)])
+
+    order = np.argsort(total)[::-1][:top_k]
+    order = order[total[order] > 0]
+    if len(order) == 0:
+        order = np.argsort(total)[::-1][:top_k]
+
+    y = np.arange(len(order))[::-1]
+    fig, ax = plt.subplots(figsize=(SQUARE[0], SQUARE[1]))
+    ax.barh(y, pos_deg[order], color=POS, label="positive")
+    ax.barh(y, neg_deg[order], left=pos_deg[order], color=NEG, label="negative")
+    ax.set_yticks(y)
+    ax.set_yticklabels(labels[order], fontsize=5)
+    ax.set_xlabel("number of stable edges")
+    # Legend above the plot so it never covers bars.
+    ax.legend(fontsize=6, frameon=False, ncol=2,
+              loc="lower right", bbox_to_anchor=(1.0, 1.0))
+    sns_despine(ax)
+    fig.tight_layout(pad=0.3)
+    return save_figure(fig, os.path.join(results_folder, name))
+
+
+def sns_despine(ax) -> None:
+    """Local despine to avoid importing seaborn just for this."""
+    for spine in ("top", "right"):
+        ax.spines[spine].set_visible(False)
+
+
+# ── 5. Glass brain (netplotbrain) ──────────────────────────────────────────────
+
+def glass_brain(
+    matrix: np.ndarray,
+    atlas: pd.DataFrame,
+    results_folder: str,
+    *,
+    edge_color: str = POS,
+    name: str = "glass_brain",
+) -> str | None:
+    """
+    Anatomical glass-brain rendering of a set of edges via netplotbrain.
+
+    *matrix* is a node×node matrix whose non-zero off-diagonal entries are the
+    edges to draw. The atlas must provide node coordinates (``x``, ``y``, ``z``).
+    Returns the PNG path, or ``None`` if there is nothing to draw / no coordinates
+    / netplotbrain is unavailable.
+
+    This supersedes the file-based ``cpm_chord_plot.plot_netplotbrain`` (which
+    expected ``sig_stability_*`` .npy files the pipeline no longer writes): the
+    edges are passed in directly so it works from the stability matrices.
+    """
+    if atlas is None or not {"x", "y", "z"}.issubset(atlas.columns):
+        return None
+    mat = np.asarray(matrix, dtype=float)
+    if mat.shape[0] != len(atlas):
+        return None
+
+    rows, cols = np.triu_indices(mat.shape[0], k=1)
+    mask = np.abs(mat[rows, cols]) > 1e-9
+    i_idx, j_idx, weights = rows[mask], cols[mask], mat[rows, cols][mask]
+    if len(i_idx) == 0:
+        return None
+
+    try:
+        import netplotbrain
+    except Exception:
+        return None
+
+    edges_df = pd.DataFrame({"i": i_idx, "j": j_idx, "weights": weights})
+    try:
+        fig, _ = netplotbrain.plot(
+            template="MNI152NLin2009cAsym",
+            template_style="glass",
+            nodes=atlas,
+            edges=edges_df,
+            view=["LSR"],
+            highlight_edges=True,
+            highlight_nodes=None,
+            node_type="circles",
+            edge_color=edge_color,
+            node_color="#332f2c",
+        )
+    except Exception:
+        return None
+
+    out = os.path.join(results_folder, f"{name}.png")
+    fig.savefig(out, dpi=200, bbox_inches="tight", facecolor="white")
+    plt.close(fig)
+    return out

cccpm-0.3.2/src/cccpm/reporting/plots/connectome_utils.py

@@ -0,0 +1,170 @@
+"""
+Connectome / atlas utilities for the brain-figure module.
+
+These helpers are deliberately self-contained (they operate on plain numpy
+matrices and a pandas atlas table) so the whole brain-figure layer can later be
+lifted into the shared ``wwu-mmll/brainplots`` toolbox with minimal change.
+
+The network colour scheme and ``upper_tri_to_matrix`` are adapted from that
+toolbox's ``brainchord`` package (Juri Howe) to keep the two consistent.
+"""
+
+from __future__ import annotations
+
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+
+# ── Network colours (Yeo-7 / Schaefer / HCP inspired) ─────────────────────────
+# Adapted from brainchord.atlas.DEFAULT_NETWORK_COLORS.
+DEFAULT_NETWORK_COLORS: dict[str, str] = {
+    "Vis":          "#781286",
+    "SomMot":       "#4682b4",
+    "DorsAttn":     "#00760e",
+    "SalVentAttn":  "#c43afa",
+    "Limbic":       "#dcf8a4",
+    "Cont":         "#e69422",
+    "Default":      "#cd3e4e",
+    "Subcortical":  "#7b1fa2",
+    "Thalamus":     "#6a1b9a",
+    "Cerebellum":   "#1565c0",
+    "Brainstem":    "#c2185b",
+    "Prefrontal":   "#d32f2f",
+    "Frontal":      "#e53935",
+    "Motor":        "#c62828",
+    "Premotor":     "#b71c1c",
+    "Insula":       "#f9a825",
+    "Parietal":     "#388e3c",
+    "Temporal":     "#43a047",
+    "Occipital":    "#00897b",
+    "Cingulate":    "#0277bd",
+}
+
+_FALLBACK_CYCLE = list(plt.cm.tab20.colors)
+_fallback_map: dict[str, str] = {}
+
+
+def get_network_color(name: str, custom: dict[str, str] | None = None) -> str:
+    """Return a hex colour for a network/region *name* (exact → fuzzy → fallback)."""
+    lookup = {**DEFAULT_NETWORK_COLORS, **(custom or {})}
+    if name in lookup:
+        return lookup[name]
+    lower = str(name).lower()
+    for key, color in lookup.items():
+        if key.lower() in lower or lower in key.lower():
+            return color
+    if name not in _fallback_map:
+        idx = len(_fallback_map) % len(_FALLBACK_CYCLE)
+        _fallback_map[name] = mcolors.to_hex(_FALLBACK_CYCLE[idx])
+    return _fallback_map[name]
+
+
+# ── Matrix helpers ────────────────────────────────────────────────────────────
+
+def upper_tri_to_matrix(n_nodes: int, edge_values: np.ndarray) -> np.ndarray:
+    """Reconstruct a symmetric ``n_nodes × n_nodes`` matrix from an upper-tri vector."""
+    mat = np.zeros((n_nodes, n_nodes))
+    rows, cols = np.triu_indices(n_nodes, k=1)
+    mat[rows, cols] = edge_values
+    mat[cols, rows] = edge_values
+    return mat
+
+
+def signed_stability_matrix(edge_stability: np.ndarray) -> np.ndarray:
+    """
+    Collapse a ``[n_nodes, n_nodes, 2(, runs)]`` stability array into one signed
+    matrix: positive-network stability as ``+value``, negative as ``-value``.
+
+    An edge belongs to at most one network, so the two layers do not overlap.
+    """
+    arr = np.asarray(edge_stability, dtype=float)
+    # squeeze any trailing run dimension(s) down to [n, n, 2]
+    while arr.ndim > 3:
+        arr = arr[..., 0]
+    pos = arr[:, :, 0]
+    neg = arr[:, :, 1]
+    return pos - neg
+
+
+def significant_edge_matrices(
+    edge_stability: np.ndarray,
+    edge_significance: np.ndarray | None = None,
+    *,
+    alpha: float = 0.05,
+    fallback_to_stable: bool = True,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Build binary positive/negative node×node matrices of the edges to highlight
+    on the glass brain.
+
+    An edge is kept if it was selected (stability > 0) and, when significance is
+    available, its stability p-value is below *alpha*. If significance filtering
+    leaves a network empty but stable edges exist, fall back to all stable edges
+    (so the figure still renders — e.g. with few permutations the p-values can
+    sit just above the threshold). Returns ``(positive_matrix, negative_matrix)``.
+    """
+    stab = np.asarray(edge_stability, dtype=float)
+    while stab.ndim > 3:
+        stab = stab[..., 0]  # drop trailing run dim(s) -> [n, n, 2]
+
+    sig = None
+    if edge_significance is not None:
+        sig = np.asarray(edge_significance, dtype=float)
+        while sig.ndim > 3:
+            sig = sig[..., 0]
+
+    out = []
+    for layer in (0, 1):
+        stable = stab[:, :, layer] > 1e-9
+        keep = stable
+        if sig is not None:
+            keep = stable & (sig[:, :, layer] < alpha)
+            if fallback_to_stable and not keep.any() and stable.any():
+                keep = stable
+        out.append(np.where(keep, 1.0, 0.0))
+    return out[0], out[1]
+
+
+def aggregate_matrix_by_group(
+    matrix: np.ndarray,
+    groups: list[str],
+    *,
+    signed: bool = True,
+) -> pd.DataFrame:
+    """
+    Aggregate a node×node *matrix* into a region×region DataFrame by averaging
+    over the off-diagonal node pairs that fall in each (group_i, group_j) block.
+
+    Parameters
+    ----------
+    matrix : np.ndarray, shape (n_nodes, n_nodes)
+        Symmetric node-level matrix (e.g. signed stability).
+    groups : list[str], length n_nodes
+        Group/network label for each node.
+    signed : bool
+        If False, aggregate absolute values.
+    """
+    n_nodes = matrix.shape[0]
+    if len(groups) != n_nodes:
+        raise ValueError(f"groups has {len(groups)} entries but matrix has {n_nodes} nodes.")
+
+    vals = matrix if signed else np.abs(matrix)
+    unique = list(dict.fromkeys(groups))
+    idx = {g: i for i, g in enumerate(unique)}
+    k = len(unique)
+
+    sums = np.zeros((k, k))
+    counts = np.zeros((k, k), dtype=int)
+    rows, cols = np.triu_indices(n_nodes, k=1)
+    for r, c in zip(rows, cols):
+        gi, gj = idx[groups[r]], idx[groups[c]]
+        sums[gi, gj] += vals[r, c]
+        sums[gj, gi] += vals[r, c]
+        counts[gi, gj] += 1
+        counts[gj, gi] += 1
+
+    with np.errstate(invalid="ignore"):
+        mean = np.where(counts > 0, sums / counts, 0.0)
+    return pd.DataFrame(mean, index=unique, columns=unique)