cccpm 0.3.2__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cccpm
-Version: 0.3.2
+Version: 0.4.0
 Summary: Confound-Corrected Connectome-based Predictive Modeling Python Package
 License: MIT
 License-File: LICENSE

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cccpm"
-version = "0.3.2"
+version = "0.4.0"
 description = "Confound-Corrected Connectome-based Predictive Modeling Python Package"
 authors = [
     "Nils Winter <nils.r.winter@uni-muenster.de>",

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/constants.py

@@ -14,6 +14,18 @@ class Networks(IntEnum):
     both = 2
 
 
+class EdgeSignificance(str, Enum):
+    """Method for testing edge-stability significance under permutation.
+
+    ``nbs``  — Network-Based Statistic: connected-component test controlling
+               FWER via a permutation max-component null (subnetwork-level).
+    ``tfce`` — Threshold-Free Cluster Enhancement: per-edge FWER control with
+               no arbitrary primary threshold.
+    """
+    nbs = "nbs"
+    tfce = "tfce"
+
+
 class Models(IntEnum):
     """Model types in CPM analysis."""
     connectome = 0

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/cpm_analysis.py

@@ -45,6 +45,9 @@ class CPMAnalysis:
                  impute_missing_values: bool = True,
                  calculate_residuals: bool = False,
                  n_permutations: int = 0,
+                 edge_significance_method: str = "nbs",
+                 nbs_threshold: float = 0.5,
+                 nbs_component_stat: str = "extent",
                  atlas_labels: str = None,
                  device: str = 'cpu',
                  random_state: int = 42):
@@ -85,6 +88,19 @@ class CPMAnalysis:
         n_permutations: int, default=0
             Number of label permutations for significance testing. ``0`` disables
             permutation testing; use 1000+ for publishable p-values.
+        edge_significance_method: str, default='nbs'
+            How edge-stability significance is established from the permutations.
+            ``'nbs'`` uses the Network-Based Statistic (connected-component test,
+            subnetwork-level FWER control); ``'tfce'`` uses network Threshold-Free
+            Cluster Enhancement (per-edge FWER control, no primary threshold).
+        nbs_threshold: float, default=0.5
+            Stability threshold (``>=``) for NBS component forming. Because
+            stability is discrete over the outer folds, ``0.5`` keeps edges
+            selected in a majority of folds. Ignored when method is ``'tfce'``.
+        nbs_component_stat: str, default='extent'
+            NBS component statistic: ``'extent'`` (number of edges, classic NBS)
+            or ``'intensity'`` (summed supra-threshold stability). Ignored when
+            method is ``'tfce'``.
         atlas_labels: str, default=None
             Path to a CSV file with atlas region labels (columns ``x``, ``y``,
             ``z``, ``region``) used for the brain plots in the report.
@@ -119,6 +135,9 @@ class CPMAnalysis:
         self.impute_missing_values = impute_missing_values
         self.calculate_residuals = calculate_residuals
         self.n_permutations = n_permutations
+        self.edge_significance_method = edge_significance_method
+        self.nbs_threshold = nbs_threshold
+        self.nbs_component_stat = nbs_component_stat
 
         if device.lower() == 'gpu' or device.lower() == 'cuda':
             if torch.cuda.is_available():
@@ -245,7 +264,11 @@ class CPMAnalysis:
             self.logger.info(f"Running {self.n_permutations} permutations.")
             y_perms = self._create_permuted_y(y)
             self._single_run(X=X, y=y_perms, covariates=covariates, perm_run=True)
-            PermutationManager.calculate_permutation_results(self.results_directory, self.logger)
+            PermutationManager.calculate_permutation_results(
+                self.results_directory, self.logger,
+                method=self.edge_significance_method,
+                nbs_threshold=self.nbs_threshold,
+                nbs_component_stat=self.nbs_component_stat)
 
         self.logger.info("=" * 50)
         self.logger.info("Estimation completed.")
@@ -385,12 +408,33 @@ class CPMAnalysis:
         if self.select_stable_edges:
             return select_stable_edges(stability_edges, self.stability_threshold)
 
-        edges = torch.zeros(X_train.shape[1], len(Networks) - 1, len(best_params))
+        edges = torch.zeros(X_train.shape[1], len(Networks) - 1, len(best_params),
+                            device=self.device)
+
+        # The edge statistics (r, p) depend only on the data and the fixed
+        # correlation statistic — not on the per-run selector params — so compute
+        # them for every run in a single batched pass (over all target columns)
+        # instead of recomputing them once per run. This is the expensive step;
+        # only the cheap thresholding below can vary per run (e.g. when inner CV
+        # selects different params for different runs).
+        #
+        # INVARIANT: this single shared pass is correct only because the edge
+        # statistic itself is fixed across runs (it is a scalar on
+        # UnivariateEdgeSelection, never part of the tunable param grid — only
+        # the p-threshold / correction are). If the statistic (e.g. pearson vs
+        # spearman) ever becomes a per-run hyperparameter, r/p can no longer be
+        # shared and must be computed once per distinct statistic in play.
+        r_edges, p_edges = self.edge_selection.edge_statistic.fit_transform(
+            X=X_train, y=y_train, covariates=cov_train, device=self.device)
+
         for run_id, params in enumerate(best_params):
             self.edge_selection.set_params(**params)
-            current_edges = self.edge_selection.fit_transform(
-                X=X_train, y=y_train[:, run_id].reshape(-1, 1), covariates=cov_train
-            ).return_selected_edges()
+            # Feed this run's precomputed r/p column into the (unchanged)
+            # selection path, keeping any per-run multiple-comparison correction
+            # applied within a single run's family of edges, exactly as before.
+            self.edge_selection.r_edges = r_edges[:, [run_id]]
+            self.edge_selection.p_edges = p_edges[:, [run_id]]
+            current_edges = self.edge_selection.return_selected_edges()
             edges[:, :, run_id] = current_edges.squeeze()
 
         return edges

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/edge_selection.py

@@ -1,72 +1,10 @@
-import pandas as pd
 import numpy as np
-from scipy.stats import ttest_1samp, t, rankdata
 from typing import Union
 
 import torch
 
 from sklearn.base import BaseEstimator
 from sklearn.model_selection import ParameterGrid
-import statsmodels.stats.multitest as multitest
-from warnings import filterwarnings
-
-device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
-
-
-
-def one_sample_t_test(matrix, population_mean):
-    # Calculate the mean and standard deviation along the rows
-    sample_means = np.mean(matrix, axis=0)
-    sample_stds = np.std(matrix, axis=0, ddof=1)
-    n = matrix.shape[1]  # Number of samples in each row
-
-    # Calculate the t-statistics
-    filterwarnings('ignore', category=RuntimeWarning)
-    t_stats = (sample_means - population_mean) / (sample_stds / np.sqrt(n))
-
-    # Calculate the p-values using the t-distribution survival function
-    p_values = 2 * t.sf(np.abs(t_stats), df=n - 1)
-
-    return t_stats, p_values
-
-
-def compute_t_and_p_values(correlations, df):
-    # Calculate t-statistics
-    t_stats = correlations * np.sqrt(df / (1 - correlations ** 2))
-    # Calculate p-values
-    p_values = 2 * t.sf(np.abs(t_stats), df=df)
-    return t_stats, p_values
-
-
-def compute_correlation_and_pvalues(x, Y, rank=False):
-    n = len(x)
-
-    if rank:
-        x = rankdata(x)
-        Y = rankdata(Y, axis=0)
-
-    # Mean-centering
-    x_centered = x - np.mean(x)
-    Y_centered = Y - np.mean(Y, axis=0)
-
-    # Correlation calculation
-    corr_numerator = np.dot(Y_centered.T, x_centered)
-    corr_denominator = (np.sqrt(np.sum(Y_centered ** 2, axis=0)) * np.sqrt(np.sum(x_centered ** 2)))
-
-    correlations = corr_numerator / corr_denominator
-
-    # Calculate t-statistics and p-values
-    _, p_values = compute_t_and_p_values(correlations, n - 2)
-
-    return correlations, p_values
-
-
-def pearson_correlation_with_pvalues(x, Y):
-    return compute_correlation_and_pvalues(x, Y, rank=False)
-
-
-def spearman_correlation_with_pvalues(x, Y):
-    return compute_correlation_and_pvalues(x, Y, rank=True)
 
 
 def torch_rankdata(data, dim=-1):
@@ -370,11 +308,6 @@ class EdgeStatistic(BaseEstimator):
                       device):
         r_edges, p_edges = (torch.zeros((X.shape[1], y.shape[1]), device=device),
                             torch.ones((X.shape[1], y.shape[1]), device=device))
-        #if self.t_test_filter:
-        #    _, p_values = one_sample_t_test(X, 0)
-        #    valid_edges = p_values < 0.05
-        #else:
-        #    valid_edges = np.bool(np.ones(X.shape[1]))
 
         # 1. Convert to GPU Tensors immediately
         X = torch.as_tensor(X, device=device, dtype=torch.float32)

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/reporting/data_loader.py

@@ -162,6 +162,17 @@ class ReportDataLoader:
 
         return edge_stability, edge_stability_significance
 
+    def load_edge_significance_meta(self) -> Optional[dict]:
+        """Load the edge-significance diagnostics (method, null distributions,
+        components) written by the permutation step, or ``None`` if absent."""
+        import json
+
+        path = os.path.join(self.results_directory, "stability_edges_significance_meta.json")
+        if os.path.exists(path):
+            with open(path) as f:
+                return json.load(f)
+        return None
+
     def load_data_insights(self) -> Tuple[Optional[pd.DataFrame], str, str]:
         """
         Load data insight files (summary stats and scatter matrix).

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/reporting/html_report.py

@@ -68,6 +68,7 @@ class HTMLReporter:
         """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()
+        edge_significance_meta = self.data_loader.load_edge_significance_meta()
 
         # ── Build template context ──────────────────────────────────────────
         ctx: dict = {
@@ -120,6 +121,8 @@ class HTMLReporter:
             edge_stability=edge_stability,
             edge_stability_significance=edge_stability_sig,
             atlas_labels=self.atlas_labels,
+            significance_meta=edge_significance_meta,
+            plots_dir=self.plots_dir,
         ))
 
         # ── Render ─────────────────────────────────────────────────────────

cccpm-0.4.0/src/cccpm/reporting/plots/stats_figures.py

@@ -0,0 +1,88 @@
+"""
+Statistics figures for the CCCPM HTML report.
+
+Currently: the permutation null-distribution plot for edge-stability
+significance (NBS max-component or TFCE max-TFCE null), with the critical
+value and the observed statistic marked. Self-contained (input = numpy /
+plain values, output = SVG path) to match the other report-figure modules.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from cccpm.reporting.plots.figure_style import (
+    COLOR_MAP,
+    PANEL,
+    apply_nature_style,
+    figure_path,
+    save_figure,
+)
+
+
+def null_distribution_plot(
+    max_null: Sequence[float],
+    results_folder: str,
+    name: str,
+    *,
+    network: str = "positive",
+    observed: float | None = None,
+    critical_value: float | None = None,
+    statistic_label: str = "Max statistic",
+) -> str:
+    """
+    Plot the permutation max-statistic null distribution for one network.
+
+    Parameters
+    ----------
+    max_null : sequence of float
+        The per-permutation maximum statistic (max component size for NBS, max
+        TFCE score for TFCE) — i.e. the FWER null distribution.
+    results_folder : str
+        Directory to write the figure into.
+    name : str
+        Extension-less figure name.
+    network : {'positive', 'negative'}
+        Selects the accent colour.
+    observed : float, optional
+        The observed statistic to mark (largest true component / max TFCE).
+    critical_value : float, optional
+        The (1 - alpha) quantile of the null; drawn as the significance cutoff.
+    statistic_label : str
+        X-axis label describing the statistic.
+
+    Returns
+    -------
+    str
+        Path to the saved SVG.
+    """
+    apply_nature_style()
+    color = COLOR_MAP.get(network, COLOR_MAP["both"])
+    null = np.asarray(list(max_null), dtype=float)
+
+    fig, ax = plt.subplots(figsize=PANEL)
+    if null.size:
+        n_bins = int(min(40, max(10, np.unique(null).size)))
+        ax.hist(null, bins=n_bins, color=color, alpha=0.55,
+                edgecolor="white", linewidth=0.3)
+
+    if critical_value is not None:
+        ax.axvline(critical_value, color="#555555", linestyle="--", linewidth=0.9,
+                   label=f"critical value ({critical_value:.3g})")
+    if observed is not None:
+        ax.axvline(observed, color=color, linestyle="-", linewidth=1.3,
+                   label=f"observed ({observed:.3g})")
+
+    ax.set_xlabel(statistic_label)
+    ax.set_ylabel("Permutations")
+    if critical_value is not None or observed is not None:
+        ax.legend(frameon=False, loc="upper right")
+
+    path_no_ext = figure_path(results_folder, name)
+    out = save_figure(fig, path_no_ext)
+    plt.close(fig)
+    return out

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/reporting/section_builders.py

@@ -496,18 +496,61 @@ def build_brain_plots_context(
 # 6. Stable Edges section
 # ---------------------------------------------------------------------------
 
+def _method_summary(meta: Optional[dict]) -> dict:
+    """Human-readable summary of the edge-significance method + per-network
+    headline diagnostics, for the Stable Edges section header."""
+    if not meta:
+        return {}
+    method = str(meta.get("method", "")).lower()
+    alpha = meta.get("alpha", 0.05)
+    n_perms = meta.get("n_permutations", 0)
+    if method == "nbs":
+        label = (f"Network-Based Statistic (component statistic: "
+                 f"{meta.get('component_stat', 'extent')}, stability threshold "
+                 f"≥ {meta.get('threshold', 0.5):g})")
+    elif method == "tfce":
+        label = (f"Network TFCE (E={meta.get('E', 0.5):g}, H={meta.get('H', 2.0):g}, "
+                 f"dh={meta.get('dh', 0.1):g})")
+    else:
+        label = method.upper()
+
+    lines = {}
+    for network in ("positive", "negative"):
+        nm = (meta.get("networks") or {}).get(network)
+        if not nm:
+            continue
+        if method == "nbs":
+            lines[network] = (
+                f"largest component: {nm.get('largest_component_edges', 0)} edges; "
+                f"{nm.get('n_significant_components', 0)} significant subnetwork(s)")
+        elif method == "tfce":
+            lines[network] = f"{nm.get('n_significant_edges', 0)} significant edge(s)"
+    return {
+        "edge_method": method,
+        "edge_method_label": label,
+        "edge_method_alpha": alpha,
+        "edge_method_n_permutations": n_perms,
+        "edge_method_lines": lines,
+        "edge_is_subnetwork": method == "nbs",
+    }
+
+
 def build_stable_edges_context(
     edge_stability: Optional[np.ndarray],
     edge_stability_significance: Optional[np.ndarray],
     atlas_labels: Optional[pd.DataFrame],
-    max_rows: int = 50,
+    significance_meta: Optional[dict] = None,
+    plots_dir: Optional[str] = None,
+    alpha: float = 0.05,
 ) -> dict:
     """
     Build context for the Stable Edges section.
 
-    Tables are capped at *max_rows* edges per network (already sorted by
-    significance) — without a stable-edge threshold a run can produce hundreds
-    of edges, which would make the report metres long. A note reports the total.
+    Displays *all* significant edges (p < *alpha*) per network — no cap — and
+    provides a downloadable CSV of every selected edge with its stability and
+    significance. When permutation diagnostics are available (see
+    :meth:`ReportDataLoader.load_edge_significance_meta`) the method is named
+    and a null-distribution figure is rendered per network.
     """
     if edge_stability is None or edge_stability_significance is None:
         return {
@@ -520,8 +563,14 @@ def build_stable_edges_context(
         "has_edge_data": True,
         "edge_table_positive": "", "edge_table_negative": "",
         "edge_count_positive": 0, "edge_count_negative": 0,
-        "edge_max_rows": max_rows,
+        "edge_total_positive": 0, "edge_total_negative": 0,
+        "edge_alpha": alpha,
+        "null_plot_positive": "", "null_plot_negative": "",
+        "edge_csv_data_uri": "",
     }
+    ctx.update(_method_summary(significance_meta))
+
+    all_rows = []
     try:
         for i, network in enumerate(["positive", "negative"]):
             edges = {
@@ -529,10 +578,48 @@ def build_stable_edges_context(
                 "stability_significance": edge_stability_significance[:, :, i],
             }
             df = create_edge_stability_table(edges, atlas_labels)
-            total = len(df)
-            html = df.head(max_rows).to_html(classes="data-table", border=0)
-            ctx[f"edge_table_{network}"] = html
-            ctx[f"edge_count_{network}"] = total
+            # A real table has the (Region A, Region B) MultiIndex; the empty
+            # placeholder does not.
+            is_real = list(df.index.names) == ["Region A", "Region B"]
+            if not is_real:
+                continue
+
+            flat = df.reset_index()
+            flat.insert(0, "Network", network)
+            all_rows.append(flat)
+
+            ctx[f"edge_total_{network}"] = len(df)
+            sig_df = df[df["Stability Significance"] < alpha]
+            ctx[f"edge_count_{network}"] = len(sig_df)
+            if len(sig_df):
+                ctx[f"edge_table_{network}"] = sig_df.to_html(
+                    classes="data-table", border=0)
+
+            # Null-distribution figure.
+            nm = (significance_meta or {}).get("networks", {}).get(network)
+            if nm and plots_dir and nm.get("max_null"):
+                from cccpm.reporting.plots.stats_figures import null_distribution_plot
+
+                if significance_meta.get("method") == "nbs":
+                    comps = nm.get("components") or []
+                    observed = max((c["statistic"] for c in comps), default=None)
+                else:
+                    observed = nm.get("observed_max")
+                path = null_distribution_plot(
+                    nm["max_null"], plots_dir, f"null_dist_{network}",
+                    network=network, observed=observed,
+                    critical_value=nm.get("critical_value"),
+                    statistic_label=significance_meta.get("statistic_label", "Max statistic"),
+                )
+                ctx[f"null_plot_{network}"] = _svg_to_html(path)
+
+        if all_rows:
+            full = pd.concat(all_rows, ignore_index=True)
+            import base64
+
+            csv_bytes = full.to_csv(index=False).encode("utf-8")
+            ctx["edge_csv_data_uri"] = (
+                "data:text/csv;base64," + base64.b64encode(csv_bytes).decode("ascii"))
     except Exception:
         pass
 

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/reporting/templates/report.html.j2

@@ -272,30 +272,77 @@
       <div class="info">
         <p>
           The individual connections (region A — region B) that most reliably drive the
-          prediction. <em>Stability</em> is how often an edge was selected across folds;
-          <em>significance</em> is the permutation p-value for that stability. These are the
-          edges you would report and interpret anatomically.
+          prediction. <em>Stability</em> is how often an edge was selected across folds.
+          {% if edge_method == "nbs" %}
+          Significance is assessed at the <strong>subnetwork</strong> level with the
+          Network-Based Statistic: connected components of stable edges are tested against
+          a permutation null of the largest component, so every edge in a significant
+          subnetwork shares that subnetwork's p-value. A significant result means
+          "this connected subnetwork is selected more consistently than chance" — not a
+          claim about any single edge in isolation.
+          {% elif edge_method == "tfce" %}
+          Significance is a per-edge family-wise-error-corrected p-value from network
+          Threshold-Free Cluster Enhancement (no arbitrary cluster-forming threshold).
+          {% else %}
+          <em>Significance</em> is the permutation p-value for that stability.
+          {% endif %}
         </p>
       </div>
+
+      {% if edge_method_label %}
+      <div class="info">
+        <p>
+          <strong>Significance method:</strong> {{ edge_method_label }},
+          {{ edge_method_n_permutations }} permutations, α = {{ edge_method_alpha }}.
+          {% if edge_method_lines.positive %}<br><strong>Positive network:</strong> {{ edge_method_lines.positive }}.{% endif %}
+          {% if edge_method_lines.negative %}<br><strong>Negative network:</strong> {{ edge_method_lines.negative }}.{% endif %}
+        </p>
+      </div>
+      {% endif %}
+
+      {% if null_plot_positive or null_plot_negative %}
+      <div class="figure-row">
+        {% if null_plot_positive %}
+        <div style="flex:1 1 320px">{{ null_plot_positive }}
+          <p class="caption">Permutation null of the max statistic (positive network); dashed = critical value, solid = observed.</p>
+        </div>
+        {% endif %}
+        {% if null_plot_negative %}
+        <div style="flex:1 1 320px">{{ null_plot_negative }}
+          <p class="caption">Permutation null of the max statistic (negative network); dashed = critical value, solid = observed.</p>
+        </div>
+        {% endif %}
+      </div>
+      {% endif %}
+
+      {% if edge_csv_data_uri %}
+      <p class="caption">
+        <a class="download-link" download="edge_significance.csv" href="{{ edge_csv_data_uri }}">
+          ⭳ Download all edges (CSV)
+        </a>
+        — every selected edge with its network, stability and significance.
+      </p>
+      {% endif %}
+
       <div class="figure-row">
-        {% if edge_table_positive %}
         <div style="flex:1 1 400px">
           <h3>Positive Network</h3>
-          {% if edge_count_positive > edge_max_rows %}
-          <p class="caption">Showing the top {{ edge_max_rows }} of {{ edge_count_positive }} edges (by significance).</p>
-          {% endif %}
+          <p class="caption">{{ edge_count_positive }} significant of {{ edge_total_positive }} selected edges (α = {{ edge_alpha }}).</p>
+          {% if edge_table_positive %}
           <div class="table-scroll table-tall">{{ edge_table_positive }}</div>
+          {% else %}
+          <p class="caption">No significant edges in this network.</p>
+          {% endif %}
         </div>
-        {% endif %}
-        {% if edge_table_negative %}
         <div style="flex:1 1 400px">
           <h3>Negative Network</h3>
-          {% if edge_count_negative > edge_max_rows %}
-          <p class="caption">Showing the top {{ edge_max_rows }} of {{ edge_count_negative }} edges (by significance).</p>
-          {% endif %}
+          <p class="caption">{{ edge_count_negative }} significant of {{ edge_total_negative }} selected edges (α = {{ edge_alpha }}).</p>
+          {% if edge_table_negative %}
           <div class="table-scroll table-tall">{{ edge_table_negative }}</div>
+          {% else %}
+          <p class="caption">No significant edges in this network.</p>
+          {% endif %}
         </div>
-        {% endif %}
       </div>
       {% endif %}
     </section>

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/reporting/templates/styles.css

@@ -377,6 +377,16 @@ figcaption, .caption {
 .figure-row { display: flex; gap: var(--sp-5); flex-wrap: wrap; margin: var(--sp-4) 0; }
 .figure-row > .figure-wrap { flex: 1 1 300px; }
 
+a.download-link {
+  display: inline-block;
+  padding: var(--sp-1) var(--sp-3);
+  border: 1px solid var(--accent-strong);
+  border-radius: 4px;
+  font-size: var(--fs-xs);
+  font-weight: 600;
+}
+a.download-link:hover { background: var(--accent-strong); color: #fff; }
+
 /* Uniform card grid for figures */
 .figure-grid {
   display: grid;

{cccpm-0.3.2 → cccpm-0.4.0}/src/cccpm/results_manager.py

@@ -1,4 +1,5 @@
 import os
+import json
 import pandas as pd
 
 from typing import Union
@@ -8,9 +9,10 @@ import torch
 
 from glob import glob
 
+import networkx as nx
+
 from cccpm.constants import Networks, Models, Metrics, TaskType, get_metrics_for_task
-from cccpm.utils import vector_to_matrix_tensor_version, matrix_to_vector_tensor_version, matrix_to_vector_numpy, vector_to_matrix_numpy
-from statsmodels.stats.multitest import multipletests
+from cccpm.utils import vector_to_matrix_tensor_version
 
 
 class ResultsManager:
@@ -454,11 +456,24 @@ class PermutationManager:
         return pd.Series(result_dict)
 
     @staticmethod
-    def calculate_permutation_results(results_directory, logger):
+    def calculate_permutation_results(results_directory, logger, method="nbs",
+                                      nbs_threshold=0.5, nbs_component_stat="extent"):
         """
         Calculate and save the permutation test results.
 
+        Model-level metric p-values are always computed. Edge-stability
+        significance is established at the *subnetwork* level via a
+        Network-Based Statistic (``method='nbs'``) or, threshold-free, via
+        network TFCE (``method='tfce'``); both control the family-wise error
+        rate through a permutation max-statistic and write a per-edge p-value
+        matrix (edges belonging to a significant subnetwork carry that
+        subnetwork's p-value) to ``stability_edges_significance.npy``.
+
         :param results_directory: Directory where the results are saved.
+        :param logger: Logger for progress messages.
+        :param method: Edge-significance method, ``'nbs'`` (default) or ``'tfce'``.
+        :param nbs_threshold: Stability threshold for NBS component forming.
+        :param nbs_component_stat: NBS component statistic, ``'extent'`` or ``'intensity'``.
         """
         true_results = ResultsManager.load_cv_results(results_directory)
 
@@ -471,15 +486,21 @@ class PermutationManager:
         p_values = PermutationManager.calculate_p_values(true_results, perm_results)
         p_values.to_csv(os.path.join(results_directory, 'p_values.csv'))
 
-        use_fdr = True
-        if use_fdr:
-            calculate_p_values_edges = PermutationManager.calculate_p_values_edges_fdr
+        if method == "nbs":
+            stability_significance, sig_meta = PermutationManager.calculate_p_values_edges_nbs(
+                true_edge_stability, perm_edge_stability,
+                threshold=nbs_threshold, component_stat=nbs_component_stat,
+                return_diagnostics=True)
+        elif method == "tfce":
+            stability_significance, sig_meta = PermutationManager.calculate_p_values_edges_tfce(
+                true_edge_stability, perm_edge_stability, return_diagnostics=True)
         else:
-            calculate_p_values_edges = PermutationManager.calculate_p_values_edges_max_value
-
-        stability_significance = calculate_p_values_edges(true_edge_stability, perm_edge_stability)
+            raise ValueError(
+                f"Unknown edge-significance method '{method}'. Use 'nbs' or 'tfce'.")
 
         np.save(os.path.join(results_directory, 'stability_edges_significance.npy'), stability_significance)
+        with open(os.path.join(results_directory, 'stability_edges_significance_meta.json'), 'w') as f:
+            json.dump(sig_meta, f)
 
         logger.debug("Saving significance of edge stability.")
         logger.info("Permutation test results")
@@ -487,91 +508,246 @@ class PermutationManager:
         return
 
     @staticmethod
-    def calculate_p_values_edges_max_value(true_stability, permutation_stability):
-        """
-        Calculate empirical p-values for each edge in a connectivity matrix using the
-        max-value method from permutation testing.
+    def _layer_arrays(true_stability, permutation_stability, layer):
+        """Extract the observed ``[n_nodes, n_nodes]`` matrix and the
+        ``[n_nodes, n_nodes, n_perms]`` null stack for one network *layer*
+        (``0`` = positive, ``1`` = negative) from the stored stability arrays,
+        which have shape ``[n_nodes, n_nodes, 2, runs]``."""
+        true_layer = true_stability[:, :, layer, 0]
+        perm_layer = permutation_stability[:, :, layer, :]
+        return true_layer, perm_layer
 
-        For each permutation, the maximum value across all edges is taken to construct
-        a max-null distribution. Each true edge value is then compared to this distribution
-        to compute a p-value, which controls the family-wise error rate (FWER).
+    @staticmethod
+    def _connected_components(supra):
+        """Yield the edge lists of the connected components (each with at least
+        one edge) of a symmetric boolean adjacency matrix, using its upper
+        triangle only. Isolated nodes are skipped."""
+        graph = nx.from_numpy_array(np.triu(supra, k=1))
+        for nodes in nx.connected_components(graph):
+            if len(nodes) < 2:
+                continue
+            edges = list(graph.subgraph(nodes).edges())
+            if edges:
+                yield edges
+
+    @staticmethod
+    def calculate_p_values_edges_nbs(true_stability, permutation_stability,
+                                     threshold=0.5, component_stat="extent",
+                                     alpha=0.05, return_diagnostics=False):
+        """
+        Network-Based Statistic (Zalesky et al., 2010) for edge-stability
+        significance.
+
+        Edges whose stability meets ``threshold`` form a graph; its connected
+        components are the candidate subnetworks. A permutation null of the
+        **largest component statistic** controls the family-wise error rate, so
+        an observed component is significant if it is larger/stronger than the
+        biggest component seen in (almost) any permutation. Each component's
+        p-value is broadcast onto all of its member edges; every other edge is
+        assigned ``p = 1``.
+
+        Inference is at the *subnetwork* level: a significant result licenses
+        "this connected subnetwork is selected more consistently than chance",
+        not per-edge claims.
+
+        Note on discreteness: stability over ``K`` outer folds takes only the
+        values ``{0, 1/K, ..., 1}``, so ``threshold=0.5`` keeps edges selected
+        in a majority of folds and the effective thresholding is coarse for few
+        folds. A continuous edge statistic (deferred) would sharpen this.
 
         Parameters
         ----------
-        true_stability : ndarray of shape (n_regions, n_regions)
-            Symmetric matrix containing the observed stability scores for each edge.
-
-        permutation_stability : ndarray of shape (n_permutations, n_regions, n_regions)
-            Array containing stability scores from each permutation run. Each entry is
-            a symmetric matrix of the same shape as `true_stability`.
+        true_stability : ndarray of shape (n_nodes, n_nodes, 2, 1)
+            Observed edge stability; dim 2 is the positive/negative network.
+        permutation_stability : ndarray of shape (n_nodes, n_nodes, 2, n_perms)
+            Edge stability from each permutation run.
+        threshold : float, default=0.5
+            Stability threshold (``>=``) for component forming.
+        component_stat : {'extent', 'intensity'}, default='extent'
+            ``'extent'`` = number of edges in the component (classic NBS);
+            ``'intensity'`` = sum of ``(stability - threshold)`` over its edges.
+        alpha : float, default=0.05
+            Significance level recorded in the diagnostics.
+        return_diagnostics : bool, default=False
+            If ``True``, also return a JSON-serialisable diagnostics dict with
+            the per-network max-component null distribution, the observed
+            components (size / statistic / p-value) and the largest component.
 
         Returns
         -------
-        sig_stability : ndarray of shape (n_regions, n_regions)
-            Symmetric matrix of empirical p-values for each edge, calculated by comparing
-            the true stability values to the max null distribution. The p-values reflect
-            the probability of observing a value as extreme or more extreme under the null.
-            Family-wise error is controlled via the max-statistic method.
+        sig_stability : ndarray of shape (n_nodes, n_nodes, 2)
+            Per-edge p-values (member edges carry their component's p-value).
+        diagnostics : dict, optional
+            Returned only when ``return_diagnostics=True``.
         """
-        # n_permutations
-        n_permutations = permutation_stability.shape[0]
-
-        triu_indices = np.triu_indices_from(true_stability, k=1)
-
-        # Extract only the upper triangle for each permutation (ignores symmetric redundancy and diagonal)
-        max_null = np.max(permutation_stability[:, triu_indices[0], triu_indices[1]], axis=1)
-
-        # Compute significance p-values per edge, comparing against max null distribution
-        sig_stability = np.ones_like(true_stability)
+        true_stability = np.asarray(true_stability, dtype=float)
+        permutation_stability = np.asarray(permutation_stability, dtype=float)
+        n_nodes = true_stability.shape[0]
+        n_perms = permutation_stability.shape[-1]
+        sig = np.ones((n_nodes, n_nodes, 2))
+
+        if component_stat not in ("extent", "intensity"):
+            raise ValueError(
+                f"Unknown component_stat '{component_stat}'. Use 'extent' or 'intensity'.")
+
+        def components_with_stats(mat):
+            out = []
+            for edges in PermutationManager._connected_components(mat >= threshold):
+                if component_stat == "extent":
+                    stat = float(len(edges))
+                else:  # intensity
+                    stat = float(sum(mat[i, j] - threshold for i, j in edges))
+                out.append((edges, stat))
+            return out
+
+        meta = {
+            "method": "nbs",
+            "threshold": float(threshold),
+            "component_stat": component_stat,
+            "n_permutations": int(n_perms),
+            "alpha": float(alpha),
+            "statistic_label": ("Component size (edges)" if component_stat == "extent"
+                                else "Component intensity"),
+            "networks": {},
+        }
 
-        # For only upper triangle (to avoid redundant computation)
-        for i, j in zip(*triu_indices):
-            true_val = true_stability[i, j]
-            p = (np.sum(max_null >= true_val) + 1) / (n_permutations + 1)
+        for layer in (Networks.positive, Networks.negative):
+            true_layer, perm_layer = PermutationManager._layer_arrays(
+                true_stability, permutation_stability, layer)
+
+            # Null distribution of the largest component statistic.
+            max_null = np.zeros(n_perms)
+            for p in range(n_perms):
+                comps = components_with_stats(perm_layer[:, :, p])
+                max_null[p] = max((s for _, s in comps), default=0.0)
+
+            # Observed components -> component p-value on every member edge.
+            components = []
+            for edges, stat in components_with_stats(true_layer):
+                p_value = (np.sum(max_null >= stat) + 1) / (n_perms + 1)
+                nodes = set()
+                for i, j in edges:
+                    nodes.update((i, j))
+                    sig[i, j, layer] = p_value
+                    sig[j, i, layer] = p_value
+                components.append({
+                    "n_edges": int(len(edges)),
+                    "n_nodes": int(len(nodes)),
+                    "statistic": float(stat),
+                    "p_value": float(p_value),
+                    "significant": bool(p_value < alpha),
+                })
+
+            components.sort(key=lambda c: c["statistic"], reverse=True)
+            name = "positive" if layer == Networks.positive else "negative"
+            meta["networks"][name] = {
+                "max_null": [float(v) for v in max_null],
+                "critical_value": float(np.quantile(max_null, 1.0 - alpha)) if n_perms else 0.0,
+                "components": components,
+                "largest_component_edges": max((c["n_edges"] for c in components), default=0),
+                "n_significant_components": int(sum(c["significant"] for c in components)),
+            }
+
+        if return_diagnostics:
+            return sig, meta
+        return sig
 
-            sig_stability[i, j] = p
-            sig_stability[j, i] = p  # symmetric
-        return sig_stability
+    @staticmethod
+    def _tfce_map(layer_matrix, heights, E, H, dh):
+        """Threshold-Free Cluster Enhancement score per edge for one network
+        layer: integrate ``extent(component)^E * h^H * dh`` over the threshold
+        sweep *heights* (extent = number of edges in the component the edge
+        belongs to at height ``h``)."""
+        n_nodes = layer_matrix.shape[0]
+        tfce = np.zeros((n_nodes, n_nodes))
+        for h in heights:
+            for edges in PermutationManager._connected_components(layer_matrix >= h):
+                contrib = (len(edges) ** E) * (h ** H) * dh
+                for i, j in edges:
+                    tfce[i, j] += contrib
+                    tfce[j, i] += contrib
+        return tfce
 
     @staticmethod
-    def calculate_p_values_edges_fdr(true_stability, permutation_stability):
+    def calculate_p_values_edges_tfce(true_stability, permutation_stability,
+                                      E=0.5, H=2.0, dh=0.1, alpha=0.05,
+                                      return_diagnostics=False):
         """
-        Calculate FDR-corrected p-values for each edge in a connectivity matrix using
-        permutation-based empirical p-values and the Benjamini–Yekutieli procedure.
+        Threshold-Free Cluster Enhancement (Smith & Nichols, 2009) adapted to
+        networks, for per-edge stability significance without an arbitrary
+        primary threshold.
 
-        For each edge, an empirical p-value is calculated by comparing the true
-        stability score to the distribution of permuted scores at the same edge.
-        The Benjamini–Yekutieli (BY) method is then applied to correct for multiple
-        comparisons, controlling the false discovery rate (FDR).
+        Each edge's TFCE score integrates the support of the components it
+        belongs to across a sweep of stability thresholds. A permutation
+        **max-TFCE** null across edges controls the family-wise error rate, so
+        this yields genuine per-edge FWER-corrected p-values (unlike NBS, which
+        is subnetwork-level).
 
         Parameters
         ----------
-        true_stability : ndarray of shape (n_regions, n_regions)
-            Symmetric matrix containing the observed stability scores for each edge.
-
-        permutation_stability : ndarray of shape (n_permutations, n_regions, n_regions)
-            Array containing stability scores from each permutation run. Each entry is
-            a symmetric matrix of the same shape as `true_stability`.
+        true_stability : ndarray of shape (n_nodes, n_nodes, 2, 1)
+            Observed edge stability; dim 2 is the positive/negative network.
+        permutation_stability : ndarray of shape (n_nodes, n_nodes, 2, n_perms)
+            Edge stability from each permutation run.
+        E, H : float
+            TFCE extent/height exponents (field-standard defaults 0.5 / 2.0).
+        dh : float, default=0.1
+            Step of the stability-threshold sweep over ``(0, 1]``.
+        alpha : float, default=0.05
+            Significance level recorded in the diagnostics.
+        return_diagnostics : bool, default=False
+            If ``True``, also return a JSON-serialisable diagnostics dict with
+            the per-network max-TFCE null distribution and observed maximum.
 
         Returns
         -------
-        sig_stability : ndarray of shape (n_regions, n_regions)
-            Symmetric matrix of FDR-corrected p-values for each edge, calculated by first
-            computing empirical p-values and then applying the Benjamini–Yekutieli correction
-            to control the expected false discovery rate across all edges.
+        sig_stability : ndarray of shape (n_nodes, n_nodes, 2)
+            Per-edge FWER-corrected p-values.
+        diagnostics : dict, optional
+            Returned only when ``return_diagnostics=True``.
         """
-        n_permutations = permutation_stability.shape[-1]
-        permutation_stability_flattenened = matrix_to_vector_numpy(permutation_stability, dim=0)
-        true_stability_flattenened = matrix_to_vector_numpy(true_stability, dim=0)
-
-        # Compute empirical p-values for each edge. Use the standard
-        # (count + 1) / (n_permutations + 1) form so p-values are valid in (0, 1].
-        condition_count = (true_stability_flattenened < permutation_stability_flattenened).sum(axis=-1)
-        p_vals = (condition_count + 1) / (n_permutations + 1)
-
-        # Apply Benjamini-Yekutieli correction
-        p_vals_corrected = np.full_like(p_vals, np.nan)
-        _, p_vals_corrected[:, 0], _, _ = multipletests(p_vals[:, 0], alpha=0.05, method='fdr_by')
-        _, p_vals_corrected[:, 1], _, _ = multipletests(p_vals[:, 1], alpha=0.05, method='fdr_by')
+        true_stability = np.asarray(true_stability, dtype=float)
+        permutation_stability = np.asarray(permutation_stability, dtype=float)
+        n_nodes = true_stability.shape[0]
+        n_perms = permutation_stability.shape[-1]
+        heights = np.arange(dh, 1.0 + dh / 2, dh)
+        triu = np.triu_indices(n_nodes, k=1)
+        sig = np.ones((n_nodes, n_nodes, 2))
+
+        meta = {
+            "method": "tfce",
+            "E": float(E), "H": float(H), "dh": float(dh),
+            "n_permutations": int(n_perms),
+            "alpha": float(alpha),
+            "statistic_label": "Max TFCE score",
+            "networks": {},
+        }
 
-        return vector_to_matrix_numpy(p_vals_corrected, dim=0)
+        for layer in (Networks.positive, Networks.negative):
+            true_layer, perm_layer = PermutationManager._layer_arrays(
+                true_stability, permutation_stability, layer)
+
+            true_tfce = PermutationManager._tfce_map(true_layer, heights, E, H, dh)
+            max_null = np.zeros(n_perms)
+            for p in range(n_perms):
+                perm_tfce = PermutationManager._tfce_map(perm_layer[:, :, p], heights, E, H, dh)
+                max_null[p] = perm_tfce[triu].max(initial=0.0)
+
+            for i, j in zip(*triu):
+                score = true_tfce[i, j]
+                if score > 0:
+                    p_value = (np.sum(max_null >= score) + 1) / (n_perms + 1)
+                    sig[i, j, layer] = p_value
+                    sig[j, i, layer] = p_value
+
+            name = "positive" if layer == Networks.positive else "negative"
+            meta["networks"][name] = {
+                "max_null": [float(v) for v in max_null],
+                "critical_value": float(np.quantile(max_null, 1.0 - alpha)) if n_perms else 0.0,
+                "observed_max": float(true_tfce[triu].max(initial=0.0)),
+                "n_significant_edges": int(np.sum(sig[:, :, layer][triu] < alpha)),
+            }
+
+        if return_diagnostics:
+            return sig, meta
+        return sig